Sandbox LoginChangelogStatus Page

Invoice refunds

Invoice refunds can optionally be triggered in scenarios where end-users send more or less cryptocurrency than they were initially quoted, or they send their cryptocurrency after the invoice expires.

For each of the payment scenarios below, Txn can configure your account to handle them individually. For example:

Payment scenarioHandling options

  • Overpayment

    The end-user sends more cryptocurrency than required, e.g., 150 USDT instead of 100 USDT.

  1. Txn processes the payment in full and credits the funds to the merchant's balance, OR

  2. Txn processes the initial invoice amount of 100 USDT and creates a refund link for the overpayment of 50 USDT, OR

  3. Txn rejects the entire payment and creates a refund link for the full amount of 150 USDT.

  • Underpayment

    The end-user sends less cryptocurrency than required, e.g., 50 USDT instead of 100 USDT.

  1. Txn processes the payment in full and credits the funds to the merchant's balance, OR

  2. Txn rejects the entire payment and creates a refund link for the full amount of 50 USDT.

  • Late payment The end-user sends their cryptocurrency after the invoice expires, and the initial exchange rate is no longer valid.

  1. Txn processes the payment in full and credits the funds to the merchant's balance, OR

  2. Txn rejects the entire payment and creates a refund link for the full amount.

Upon creating a refund request, Txn will provide a refund link via the invoice API and webhook.

A few things to be aware of:

  • Invoice refunds inherit their parent invoice reference ID with a "REFUND-" suffix.

  • Refunds are payment links to web pages hosted by Txn that you will need to share with your end-users so they can submit their wallet address to claim the funds, e.g., https://sandbox.txn.pro/redirect?payment_link_id=d1a2c04c-adab-4c01-8483-eeef02340a82&request_type=payment_link_hosted_page

  • End-users can only claim funds in the same currency and network as the original payment. They would not be able to claim BTC if they paid in USDT.

  • Refund links are valid for 90 days.

Below is an example of an invoice payload containing a Refund object:

    {
      "attributes": {
        "amount": "48.897896",
        "createdAt": "2024-10-14T07:36:00.693Z",
        "currency": "USDT",
        "expiresAt": "2025-01-14T07:36:00.000Z",
        "hostedPageUrl": "https://sandbox.txn.pro/redirect?payment_link_id=d1a2c04c-adab-4c01-8483-eeef02340a82&request_type=payment_link_hosted_page",
        "paymentType": "Refund",
        "reference": "REFUND-6dc0a463-8387-4fdf-adb8-abf5f5728e69",
        "status": "created"
      },
      "id": "d1a2c04c-adab-4c01-8483-eeef02340a82",
      "relationships": {
        "target": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "paymentLinks"
    }

And here is the complete invoice payload for your reference:

Invoice payload
{
  "data": {
    "attributes": {
      "amountBilled": "100.00",
      "amountCharged": "101.102104",
      "billedCurrency": "USD",
      "chargedCurrency": "USDT",
      "createdAt": "2024-10-14T07:34:09.759Z",
      "exchangeRate": "0.9890991",
      "expiresAt": "2024-10-14T07:54:09.677Z",
      "hostedPageUrl": "https://sandbox.txn.pro/redirect?invoice_id=9adb33cb-6aec-4573-a1fb-1a58f9ea834b&request_type=invoice_hosted_page",
      "network": "ttrx:usdt",
      "networkName": "Tron (TRC20)",
      "paymentStatus": "on_time",
      "reference": "6dc0a463-8387-4fdf-adb8-abf5f5728e69",
      "status": "completed",
      "statusContext": "overpaid",
      "successRedirectUrl": null,
      "unsuccessRedirectUrl": null
    },
    "id": "9adb33cb-6aec-4573-a1fb-1a58f9ea834b",
    "relationships": {
      "address": {
        "data": {
          "id": "1b803161-d129-4cc1-b37f-6bf380c2bcd8",
          "type": "addresses"
        }
      },
      "coinDeposits": {
        "data": [
          {
            "id": "2c1b2599-9acc-4360-a21f-4ab0c26d40ff",
            "type": "coinTransactions"
          }
        ]
      },
      "invoiceTransactions": {
        "data": [
          {
            "id": "a7205eb7-ab56-4e40-beab-ab8a82c9da63",
            "type": "invoiceTransactions"
          }
        ]
      },
      "refundLinks": {
        "data": [
          {
            "id": "d1a2c04c-adab-4c01-8483-eeef02340a82",
            "type": "paymentLinks"
          }
        ]
      }
    },
    "type": "invoices"
  },
  "included": [
    {
      "attributes": {
        "createdAt": "2024-10-11T08:10:27.573Z",
        "label": "Tron (TRC20)",
        "value": "TX3sfqPXKDjqKguyjgUSzzF965Guq2fvSV"
      },
      "id": "1b803161-d129-4cc1-b37f-6bf380c2bcd8",
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "network": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "addresses"
    },
    {
      "attributes": {
        "amount": "48.897896",
        "createdAt": "2024-10-14T07:36:00.693Z",
        "currency": "USDT",
        "expiresAt": "2025-01-14T07:36:00.000Z",
        "hostedPageUrl": "https://sandbox.txn.pro/redirect?payment_link_id=d1a2c04c-adab-4c01-8483-eeef02340a82&request_type=payment_link_hosted_page",
        "paymentType": "Refund",
        "reference": "REFUND-6dc0a463-8387-4fdf-adb8-abf5f5728e69",
        "status": "created"
      },
      "id": "d1a2c04c-adab-4c01-8483-eeef02340a82",
      "relationships": {
        "target": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "paymentLinks"
    },
    {
      "attributes": {
        "transactionFee": "1.0",
        "transactionFeeCurrency": "USD"
      },
      "id": "a7205eb7-ab56-4e40-beab-ab8a82c9da63",
      "relationships": {
        "exchangeQuote": {
          "data": {
            "id": "8784e0f8-4df9-4da6-8e11-9e1b5252b9a4",
            "type": "exchangeQuotes"
          }
        },
        "invoice": {
          "meta": {
            "included": false
          }
        },
        "txn": {
          "data": {
            "id": "a7205eb7-ab56-4e40-beab-ab8a82c9da63",
            "type": "transactions"
          }
        }
      },
      "type": "invoiceTransactions"
    },
    {
      "attributes": {
        "accountId": "e289de2b-37bd-4eff-b832-f754c31a2d95",
        "amount": "150.000000",
        "createdAt": "2024-10-14T07:35:40.335Z",
        "currencyCode": "USDT",
        "state": "processed",
        "txHash": "799de0c74f059f12896faeb53c7cafd789bb32e4fa5416ad8e05475aa2d19119"
      },
      "id": "2c1b2599-9acc-4360-a21f-4ab0c26d40ff",
      "relationships": {
        "address": {
          "meta": {
            "included": false
          }
        },
        "network": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "coinTransactions"
    },
    {
      "attributes": {
        "amount": "99.00",
        "createdAt": "2024-10-14T07:36:00.801Z",
        "reference": "6dc0a463-8387-4fdf-adb8-abf5f5728e69",
        "simplifiedState": "completed",
        "transactionType": "InvoiceTransaction"
      },
      "id": "a7205eb7-ab56-4e40-beab-ab8a82c9da63",
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "transactions"
    },
    {
      "attributes": {
        "accountChargedId": "e289de2b-37bd-4eff-b832-f754c31a2d95",
        "accountReceivedId": "80b8dd61-35bc-49cc-9e04-f2c0f741a096",
        "amountCharged": "101.102104",
        "amountChargedCurrency": "USDT",
        "amountReceived": "100.0",
        "amountReceivedCurrency": "USD",
        "exchangeFee": "0.00",
        "exchangeFeeCurrency": "USD",
        "expiresAt": "2024-10-14T07:36:30.725Z",
        "rate": "0.9890991",
        "rateCurrency": "USD"
      },
      "id": "8784e0f8-4df9-4da6-8e11-9e1b5252b9a4",
      "relationships": {
        "exchangeOrder": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "exchangeQuotes"
    }
  ],
  "meta": {}
}

Refund Links

As mentioned, each refund request is essentially a payment link to a web page hosted by Txn, for example, https://sandbox.txn.pro/redirect?payment_link_id=d1a2c04c-adab-4c01-8483-eeef02340a82&request_type=payment_link_hosted_page.

After a refund link is returned by Txn in the invoice API and webhook, the merchant will need to share the link with the end-user. Below are steps and UI examples that the end-user will follow.

Below are the steps and UI examples that the end-user will follow.

PreviousListing invoicesNextChannels concept

Last updated