> For the complete documentation index, see [llms.txt](https://docs.txn.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.txn.io/invoices/invoice-refunds.md).

# 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 scenario                                                                                                                                                 | Handling options                                                                                                                                                                                                                                                                                                                    |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p><strong>Overpayment:</strong></p><p>The end-user sends more cryptocurrency than required, e.g., 150 USDT instead of 100 USDT.</p>                             | <ol><li>Txn processes the payment in full and credits the funds to the merchant's balance, OR</li><li>Txn processes the initial invoice amount of 100 USDT and creates a refund link for the overpayment of 50 USDT, OR</li><li>Txn rejects the entire payment and creates a refund link for the full amount of 150 USDT.</li></ol> |
| <p><strong>Underpayment:</strong></p><p>The end-user sends less cryptocurrency than required, e.g., 50 USDT instead of 100 USDT.</p>                             | <ol><li>Txn processes the payment in full and credits the funds to the merchant's balance, OR</li><li>Txn rejects the entire payment and creates a refund link for the full amount of 50 USDT.</li></ol>                                                                                                                            |
| <p><strong>Late payment</strong><br><br>The end-user sends their cryptocurrency after the invoice expires, and the initial exchange rate is no longer valid.</p> | <ol><li>Txn processes the payment in full and credits the funds to the merchant's balance, OR</li><li>Txn rejects the entire payment and creates a refund link for the full amount.</li></ol>                                                                                                                                       |

Unless Txn has configured your account otherwise, all three scenarios are processed in full. A late payment of the wrong amount follows the overpayment or underpayment option, and the late payment option applies only when the amount is exact; see [Invoice status flow](https://docs.txn.io/invoices/invoice-status-flow.md).

{% hint style="info" %}

* Refunding only the overpaid difference needs an overpayment tolerance on your account, a percentage of the charged amount. Txn creates the refund link only when the difference exceeds that tolerance and is larger than the network fee for the refund payout. Otherwise the whole payment is credited to your balance.
* A full refund link is always created. Network and service fees are deducted when the end user claims it, so a refund smaller than those fees cannot be claimed.
  {% endhint %}

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

A few things to be aware of:

* 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.io/redirect?payment_link_id=7312928e-f5b1-46b3-94cd-b7356e2c6825&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.
* Processing and network fees are deducted from the refund amount. If the combined total of both processing and network fees exceeds the refund amount, Txn will be unable to broadcast the refund transaction.

Below is an overpaid invoice as returned by [Reading invoice](https://docs.txn.io/invoices/reading-invoice.md). The end user sent 17 USDT against 14.211788 USDT charged, so Txn completed the invoice for the charged amount and created a refund link for the 2.788212 USDT difference. The link is listed in `data.relationships.refundLinks` and returned in `included[]` as a `paymentLinks` entity, with `status` `created` until the end user submits a wallet address.

<details>

<summary>Invoice payload</summary>

{% code overflow="wrap" lineNumbers="true" %}

```json
{
  "data": {
    "id": "c3622abe-83f4-4bb8-ad93-19ddcc68eb7d",
    "type": "invoices",
    "attributes": {
      "amountBilled": "12.00",
      "amountCharged": "14.211788",
      "targetAmount": "10.76",
      "billedCurrency": "EUR",
      "chargedCurrency": "USDT",
      "targetCurrency": "EUR",
      "chargedTargetRate": "0.8443695",
      "chargedTargetRateCurrency": "EUR",
      "statusContext": "overpaid",
      "network": "ttrx:usdt",
      "networkName": "Tron (TRC20)",
      "paymentMethods": [
        "on_chain"
      ],
      "status": "completed",
      "successRedirectUrl": null,
      "unsuccessRedirectUrl": null,
      "paymentStatus": "on_time",
      "exchangeRate": "0.8443695",
      "reference": null,
      "expiresAt": "2026-11-03T10:34:42.463Z",
      "createdAt": "2026-11-03T10:14:42.515Z",
      "hostedPageUrl": "https://sandbox.txn.io/redirect?item_id=c3622abe-83f4-4bb8-ad93-19ddcc68eb7d&request_type=item_hosted_page",
      "scAddress": null
    },
    "relationships": {
      "targetAccount": {
        "data": {
          "type": "accounts",
          "id": "13a85b45-8543-41c7-b963-394d4ea128ae"
        }
      },
      "binanceOrder": {
        "data": null
      },
      "address": {
        "data": {
          "type": "addresses",
          "id": "cbb847b0-4f58-454c-a646-ee678c81b6a6"
        }
      },
      "refundLinks": {
        "data": [
          {
            "type": "paymentLinks",
            "id": "7312928e-f5b1-46b3-94cd-b7356e2c6825"
          }
        ]
      },
      "invoiceTransactions": {
        "data": [
          {
            "type": "invoiceTransactions",
            "id": "07d1416f-f46b-48aa-99e9-299d2b0df4a6"
          }
        ]
      },
      "coinDeposits": {
        "data": [
          {
            "type": "coinDeposits",
            "id": "45e3bccd-6e75-477e-8654-410bdacb4506"
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "type": "accounts",
      "attributes": {
        "master": true,
        "currencyCode": "EUR",
        "label": "master",
        "bankReference": "BDR6421088115176062",
        "balance": "39252.28",
        "totalBalance": null,
        "bankWithdrawalAvailable": true,
        "bankDepositAvailable": true,
        "transferAvailable": true,
        "currencyType": "fiat"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        },
        "txnBankCredentials": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "cbb847b0-4f58-454c-a646-ee678c81b6a6",
      "type": "addresses",
      "attributes": {
        "label": "Tron (TRC20)",
        "value": "TK8M2PAqZ959rjQJYz7hLJdKG793uYuc93",
        "createdAt": "2026-11-03T08:34:40.595Z"
      },
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "network": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "7312928e-f5b1-46b3-94cd-b7356e2c6825",
      "type": "paymentLinks",
      "attributes": {
        "amount": "2.788212",
        "currency": "USDT",
        "accountCurrency": "USDT",
        "network": "ttrx:usdt",
        "networkName": "Tron (TRC20)",
        "reference": "REFUND-c3622abe-83f4-4bb8-ad93-19ddcc68eb7d-1793701020",
        "hostedPageUrl": "https://sandbox.txn.io/redirect?payment_link_id=7312928e-f5b1-46b3-94cd-b7356e2c6825&request_type=payment_link_hosted_page",
        "status": "created",
        "approvalStatus": null,
        "expiresAt": "2026-12-03T10:17:00.000Z",
        "createdAt": "2026-11-03T10:17:00.494Z",
        "paymentType": "Refund",
        "successRedirectUrl": null,
        "unsuccessRedirectUrl": null,
        "paymentMethods": [
          "on_chain"
        ]
      },
      "relationships": {
        "target": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "07d1416f-f46b-48aa-99e9-299d2b0df4a6",
      "type": "invoiceTransactions",
      "attributes": {
        "amountBilled": "12.00",
        "billedChargedRate": "0.844664",
        "billedChargedRateCurrency": "EUR",
        "consolidationFee": "0.00",
        "transactionFee": "1.24",
        "transactionFeeCurrency": "EUR",
        "targetTransactionFee": "1.24",
        "targetTransactionFeeCurrency": "EUR",
        "simplifiedState": "completed"
      },
      "relationships": {
        "txn": {
          "data": {
            "type": "transactions",
            "id": "07d1416f-f46b-48aa-99e9-299d2b0df4a6"
          }
        },
        "exchangeQuote": {
          "data": {
            "type": "exchangeQuotes",
            "id": "dc35fbe8-ca47-498d-b040-4ab2855effb5"
          }
        },
        "account": {
          "meta": {
            "included": false
          }
        },
        "invoice": {
          "meta": {
            "included": false
          }
        },
        "author": {
          "data": null
        }
      }
    },
    {
      "id": "45e3bccd-6e75-477e-8654-410bdacb4506",
      "type": "coinDeposits",
      "attributes": {
        "txHash": "fe749f3a6e5a90e82f182f752c97b8a4876d66170ce5573d397f0e90385dd589",
        "currencyCode": "USDT",
        "createdAt": "2026-11-03T10:16:08.105Z",
        "state": "processed",
        "amount": "17.000000",
        "riskScore": null,
        "reference": null,
        "accountId": "e289de2b-37bd-4eff-b832-f754c31a2d95",
        "simplifiedState": "processed",
        "sourceAddresses": [
          "TVkgb653SJdqxA8jyWcD49PAJonZzCBcMk"
        ],
        "clusterCategory": "Exchange",
        "clusterName": "Test ENV"
      },
      "relationships": {
        "network": {
          "meta": {
            "included": false
          }
        },
        "address": {
          "meta": {
            "included": false
          }
        },
        "author": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "07d1416f-f46b-48aa-99e9-299d2b0df4a6",
      "type": "transactions",
      "attributes": {
        "createdAt": "2026-11-03T10:14:42.531Z",
        "simplifiedState": "completed",
        "transactionType": "InvoiceTransaction",
        "amount": "10.76",
        "currency": "EUR",
        "balance": null,
        "reference": null,
        "accountId": "13a85b45-8543-41c7-b963-394d4ea128ae"
      },
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "transactionDetails": {
          "meta": {
            "included": false
          }
        },
        "author": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "dc35fbe8-ca47-498d-b040-4ab2855effb5",
      "type": "exchangeQuotes",
      "attributes": {
        "expiresAt": "2026-11-03T10:17:30.603Z",
        "amountCharged": "14.211788",
        "amountReceived": "12.0",
        "rate": "0.844664",
        "exchangeFee": "0.00",
        "exchangeFeeCurrency": "EUR",
        "rateCurrency": "EUR",
        "accountChargedId": "e289de2b-37bd-4eff-b832-f754c31a2d95",
        "accountReceivedId": "13a85b45-8543-41c7-b963-394d4ea128ae",
        "status": "completed",
        "amountChargedCurrency": "USDT",
        "amountReceivedCurrency": "EUR"
      },
      "relationships": {
        "exchangeOrder": {
          "meta": {
            "included": false
          }
        },
        "transactions": {
          "meta": {
            "included": false
          }
        },
        "author": {
          "meta": {
            "included": false
          }
        },
        "accountCharged": {
          "meta": {
            "included": false
          }
        },
        "accountReceived": {
          "meta": {
            "included": false
          }
        }
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endcode %}

</details>

Refund links are listed in `data.relationships.refundLinks.data[]` (type `paymentLinks`), and each link is returned as an entity in `included[]`. The other entities in the payload are described in [Read invoice](https://docs.txn.io/invoices/reading-invoice.md); the payment that was refunded is the `coinDeposits` entity, and the settlement record (`invoiceTransactions`) carries the outcome of the invoice.

**Refund link fields**

<table><thead><tr><th>Name</th><th width="97">Type</th><th>Description</th></tr></thead><tbody><tr><td>data.relationships.refundLinks</td><td>array</td><td>Refund links created for this invoice. <code>data[].type</code> is <code>paymentLinks</code>; the entities are returned in <code>included[]</code>. Empty when nothing was refunded.</td></tr><tr><td>included[].type(paymentLinks)</td><td>object</td><td>A refund link, in the shape returned by <a href="https://docs.txn.io/payment-links/reading-payment-link.md">Reading payment link</a>. The values specific to refund links are listed below.</td></tr><tr><td>included[].type(paymentLinks).attributes.paymentType</td><td>string</td><td>Always <code>Refund</code>.</td></tr><tr><td>included[].type(paymentLinks).attributes.amount</td><td>string</td><td>Amount refunded, in <code>currency</code>: the received payment before network and processing fees. The fees are deducted when the end user claims the refund.</td></tr><tr><td>included[].type(paymentLinks).attributes.currency</td><td>string</td><td>Currency of the refunded payment. Equals the invoice <code>chargedCurrency</code>.</td></tr><tr><td>included[].type(paymentLinks).attributes.accountCurrency</td><td>string</td><td>Same as <code>currency</code>. The refund is paid from your account in that currency.</td></tr><tr><td>included[].type(paymentLinks).attributes.network, included[].type(paymentLinks).attributes.networkName</td><td>string</td><td>Network of the original payment. The refund can only be claimed on this network.</td></tr><tr><td>included[].type(paymentLinks).attributes.reference</td><td>string</td><td><code>REFUND-&#x3C;invoice reference>-&#x3C;unix timestamp></code>. The invoice ID is used when the invoice has no reference.</td></tr><tr><td>included[].type(paymentLinks).attributes.hostedPageUrl</td><td>string</td><td>The hosted page to share with the end user.</td></tr><tr><td>included[].type(paymentLinks).attributes.status</td><td>string</td><td><code>created</code> until the end user submits a wallet address, then the regular payment link statuses; see <a href="https://docs.txn.io/payment-links/payment-links-concept.md">Payment links concept</a>.</td></tr><tr><td>included[].type(paymentLinks).attributes.approvalStatus</td><td>string</td><td>Approval workflow status when a payout approval rule applies to the refund, otherwise <code>null</code>.</td></tr><tr><td>included[].type(paymentLinks).attributes.expiresAt</td><td>string</td><td>When the link expires: 30 days after it was created.</td></tr><tr><td>included[].type(paymentLinks).attributes.createdAt</td><td>string</td><td>When the refund link was created.</td></tr><tr><td>included[].type(paymentLinks).attributes.paymentMethods</td><td>array</td><td>Always <code>["on_chain"]</code>.</td></tr><tr><td>included[].type(paymentLinks).attributes.successRedirectUrl, included[].type(paymentLinks).attributes.unsuccessRedirectUrl</td><td>string</td><td>Always <code>null</code> for refund links.</td></tr><tr><td>included[].type(paymentLinks).relationships.target</td><td>object</td><td>The payout created when the end user claims the refund; <code>data</code> is <code>null</code> until then. Not expanded in the invoice payload (<code>meta.included</code> is <code>false</code>); read the payment link to get it.</td></tr></tbody></table>

## Refund Links

As mentioned, each refund request is essentially a payment link to a web page hosted by Txn, for example,

`https://sandbox.txn.io/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 the steps and UI examples that the end-user will follow.

<figure><img src="https://1963856601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgfUDRstNYYBTf2futZ28%2Fuploads%2Fgit-blob-9bf38b5a47d725caf74496ff042ff7258ed37bd9%2FInvoice%20Refund%201.png?alt=media" alt=""><figcaption><p>Once the refund link is opened, the end-user will need to provide their wallet address.</p></figcaption></figure>

<figure><img src="https://1963856601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgfUDRstNYYBTf2futZ28%2Fuploads%2Fgit-blob-12688b575cb5d8aee6810b6e337b81d92149e5f0%2FInvoice%20Refund%202.png?alt=media" alt=""><figcaption><p>The end-user enters their wallet address and clicks Continue to review the payout details.</p></figcaption></figure>

<figure><img src="https://1963856601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgfUDRstNYYBTf2futZ28%2Fuploads%2Fgit-blob-fa958f84c7f05b07c7f645eba24d62452638fec2%2FInvoice%20Refund%203.png?alt=media" alt=""><figcaption><p>After clicking Continue, the end-user is shown the payout details, including fees and the payout amount, for their review. The end-user then clicks Confirm.</p></figcaption></figure>

<figure><img src="https://1963856601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgfUDRstNYYBTf2futZ28%2Fuploads%2Fgit-blob-2392997fd7cb2fbe9d2bdc55b6a70aa912a972af%2FInvoice%20Refund%204.png?alt=media" alt=""><figcaption><p>After clicking Confirm, Txn sends the cryptocurrency transaction to the end-user's wallet address. The refund link can no longer be reused.</p></figcaption></figure>

<figure><img src="https://1963856601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgfUDRstNYYBTf2futZ28%2Fuploads%2Fgit-blob-94ff464fd8c4adfd074c1e4c1f099cbc93991e1a%2FInvoice%20Refund%205.png?alt=media" alt=""><figcaption><p>Once the crypto transaction is confirmed on the blockchain, the page shows that the payout has been completed.</p></figcaption></figure>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.txn.io/invoices/invoice-refunds.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
