# Environments

Txn maintains two publicly available environments:

<table><thead><tr><th width="158">Environment</th><th>API URL</th><th>Login URL</th></tr></thead><tbody><tr><td>Production</td><td>https://api.txn.io</td><td><a href="https://app.txn.io/login">https://app.txn.io/login</a></td></tr><tr><td>Sandbox</td><td>https://api.sandbox.txn.io</td><td><a href="https://sandbox.txn.io/login">https://sandbox.txn.io/login</a></td></tr></tbody></table>

Sandbox mirrors the Production environment and supports all the features available on the Txn platform in production.


# Creating a Sandbox account

The sandbox is a fully functional replica of the Txn platform for integration testing. It uses separate API credentials and test funds — no real transactions are processed.

To request a sandbox account, contact your Txn sales or integration manager, or write to <support@txn.io>.

Once your account is active, Txn will provision test balances so you can begin testing immediately. If you need additional test funds or cryptocurrency testnet liquidity, contact your integration manager.

The sandbox base URL is `https://api.sandbox.txn.io`. Note that sandbox network codes differ from their production counterparts — testnet networks are prefixed (`tbtc`, `ttrx:usdt`, `hteth`, etc.). See [Supported currencies](/api-basics/supported-currencies) for the full list.

Once your account is ready, [create your API keys](/getting-setup/creating-your-api-keys) to start making requests.


# Making a test payment

The Sandbox settles deposits on public **test networks**, so you can run the full payment flow end to end without moving real funds. This guide shows how to fund a test wallet and pay a Sandbox invoice or channel.

We recommend testing with **TRON** — TRX (`ttrx`) and USDT on TRON (`ttrx:usdt`). Both run on the TRON **Shasta** testnet: confirmations are fast, fees are negligible, and test tokens are easy to obtain. `ttrx:usdt` also mirrors the most common production integration — stablecoin deposits.

{% hint style="info" %}
Sandbox network codes are testnet-prefixed. `ttrx` and `ttrx:usdt` both map to the TRON Shasta testnet. See [Supported currencies](/api-basics/supported-currencies) for the full list.
{% endhint %}

## 1. Install a TronLink wallet

[TronLink](https://www.tronlink.org) is the most widely used TRON wallet and supports the Shasta testnet. It is available as a browser extension and a desktop app — choose whichever suits your workflow.

**Browser extension**

1. Open the [TronLink website](https://www.tronlink.org) and choose your browser, or install directly from the [Chrome Web Store](https://chromewebstore.google.com/detail/tronlink/ibnejdfjmmkpcnlpebklmnkoeoihofec) or [Firefox Add-ons](https://addons.mozilla.org/firefox/addon/tronlink-wallet/).
2. Open the extension and select **Create Wallet** (or **Import Wallet** if you already have a test seed phrase).
3. Set a password and securely store your recovery phrase.

**Desktop app**

1. Download the desktop app for macOS or Windows from the [TronLink website](https://www.tronlink.org).
2. Install it, then create or import a wallet as above.

{% hint style="warning" %}
Use a dedicated wallet for testing. Never import a seed phrase that controls real funds into a test setup.
{% endhint %}

**Switch to the Shasta testnet**

1. Open TronLink and click the network selector at the top of the window.
2. Select **Shasta** (Shasta Testnet). Your balances and transactions now refer to the testnet rather than mainnet.

## 2. Get test tokens

You need a small amount of **test TRX** to cover network fees. For USDT tests you also need **test `ttrx:usdt`**.

* **Public faucets.** Follow TRON's [Getting testnet tokens](https://developers.tron.network/docs/getting-testnet-tokens-on-tron) guide to claim Shasta TRX. Set your wallet to **Shasta**, then paste your address into the faucet.
* **TRON Discord.** Join the official TRON developer Discord (linked from the guide above) and request Shasta tokens in the **faucet** channel.
* **From Txn.** We can also send you test tokens directly — including `ttrx:usdt`. Contact your integration manager or email <support@txn.io> with your Shasta wallet address.

{% hint style="info" %}
TRC-20 transfers (including `ttrx:usdt`) consume network fees paid in TRX, so keep some `ttrx` in the wallet even when testing USDT.

The Sandbox recognises a specific test USDT token (`ttrx:usdt`, contract `TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs`). USDT from an unrelated test faucet may use a different contract and will not be detected — request `ttrx:usdt` from Txn if you are unsure.
{% endhint %}

## 3. Make the payment

1. Create a test [invoice](/invoices/creating-invoice) or [channel](/channels/creating-channel) via the API, using `ttrx:usdt` (or `ttrx`) as the payment network.
2. Copy the receiving **address** from the response. For invoices, also note the exact **`amountCharged`** — send that amount so the invoice completes as a full payment.
3. In TronLink (on Shasta), send the token and amount to the address.
4. Within a minute or two the deposit is detected: the invoice moves through its [status flow](/invoices/invoice-status-flow), or the channel deposit appears in [List channel deposits](/channels/listing-channel-deposits). If you have configured webhooks, you also receive the corresponding events.

## Troubleshooting

* **Payment not detected.** Confirm the wallet is on **Shasta** (not mainnet or Nile), that you sent the correct token to the correct address, and that you are querying the Sandbox base URL (`https://api.sandbox.txn.io`). Testnet confirmations can take a minute or two.
* **Transfer fails or "out of energy".** Ensure the wallet holds some `ttrx` to cover the network fee.
* **USDT sent but not credited.** Check the token contract matches the Sandbox `ttrx:usdt` token above; tokens from unofficial faucets can differ.


# Back office user roles

Merchants can have multiple users in their Txn back office. User invitations and permissions are managed through Txn. Contact your sales or integration manager at Txn to set up users for you.

<table data-full-width="false"><thead><tr><th>User Role</th><th>Manage API keys</th><th>Manage users</th><th>Withdraw funds</th><th>Exchange funds</th><th>View transactions</th></tr></thead><tbody><tr><td>Owner</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td></tr><tr><td>Spender</td><td>—</td><td>—</td><td>✓</td><td>✓</td><td>✓</td></tr><tr><td>Trader</td><td>—</td><td>—</td><td>—</td><td>✓</td><td>✓</td></tr><tr><td>Viewer</td><td>—</td><td>—</td><td>—</td><td>—</td><td>✓</td></tr></tbody></table>


# Approvals feature guide

## Overview

The Approvals feature allows you to create custom approval rules for crypto withdrawals and bank withdrawal requests made through your business account. By setting up approval rules, you can ensure that transactions require review and authorization from designated team members before they're processed.

## Creating Approval Rules

To create an approval rule, navigate to **Approvals → Rules** and follow these steps:

{% hint style="info" %}
Only users with the [Owner role](/getting-setup/back-office-user-roles) can create approval rules. You can create one rule per scope — one for Crypto Payouts and one for Bank Withdrawals.
{% endhint %}

### 1. Choose Your Rule Scope

Select which type of transactions this rule will apply to:

**Crypto Payouts** — This scope covers:

* Creating payouts from crypto accounts
* Creating mass payouts via CSV upload
* Creating payout payment links

**Bank Withdrawals** — This scope covers:

* Bank withdrawal requests only

{% hint style="warning" %}
**Approval rules apply to dashboard-initiated transactions only.** Crypto payouts and bank withdrawals created via the API using an API key are processed without requiring approval, even if a matching rule is active.
{% endhint %}

### 2. Set Required Approvals

Specify the minimum number of approvals needed for each transaction request that falls under this rule.

### 3. Designate Approvers

Select which users are authorized to approve or reject transaction requests under this rule.

### 4. Self-Approval Settings

Decide whether transaction initiators can approve their own requests. By default, this option is disabled, meaning initiators cannot approve their own transactions.

<figure><img src="/files/Zzl7Yplf1uF0Kt3Of8oW" alt=""><figcaption><p>Creating a new approval rule</p></figcaption></figure>

## How Approvals Work

Once an approval rule is active:

**For Transaction Initiators:**

* Any transaction request you create that matches a rule will require the specified number of approvals before processing
* You can view the status of your requests on the **Approvals → Requests** page
* You can cancel your own request at any time (even if you can't approve it)
* If you're allowed to approve your own requests, you can both approve and cancel them
* You'll receive email notifications when your request is approved or rejected

**For Approvers:**

* You'll receive email notifications when a transaction requires your review
* All pending approval requests are visible on the **Approvals → Requests** page
* You can either approve or reject the request
* If even one rejection is received, the transaction request is canceled completely
* The transaction will only proceed once the required number of approvals is reached

## Managing Approval Rules

### Deleting Rules

Only users with the Owner role can initiate rule deletion. When you delete an approval rule, it enters a 24-hour cooling-off period before being permanently removed. This safeguard helps prevent accidental deletions.

**Important:** If you delete a rule while transaction requests are still pending approval, those requests will still need to be resolved (approved, rejected, or canceled) according to the original rule requirements.

<figure><img src="/files/WSAoBhAbjTG2w65V35Qk" alt=""><figcaption><p>The rule is set for deletion</p></figcaption></figure>

For questions about setting up approval rules or managing transaction approvals, contact support at <support@txn.io>.


# Creating your API keys

Once your business account is set up and active, you can create your API keys to authenticate against the Txn API.

To do so, navigate to the **Developers** page on the left-hand menu in your account and click the blue "Add API Key" button. You will be asked to provide the API key label, API key permission (full access or read only) and your OTP code.

| API Key Permission | Description                                              |
| ------------------ | -------------------------------------------------------- |
| Read               | Can only read data, e.g. transaction details.            |
| Full Access        | Can read and write data, e.g. create quotes and payouts. |

Each newly generated API key is shown only once — copy and store it securely, as it cannot be retrieved from your account later.

If you'd like to delete your API key, navigate to the Developers page again to view the list of all API keys associated with your account and click the grey "Delete" button next to the relevant API key.

{% hint style="info" %}
To whitelist your server IP addresses for a given API key, please reach out to us via the integration channel.
{% endhint %}

<figure><img src="/files/3s5SnFpJ2fTdaTGpKkfd" alt="API Keys page"><figcaption><p>Developers → API Keys</p></figcaption></figure>

<figure><img src="/files/ofD8COUnXRbl9ewGg2JA" alt="Create new API key — step 1"><figcaption><p>Step 1: Enter a label and choose the key permission</p></figcaption></figure>

<figure><img src="/files/LebEfqB4qRGKJJnVQvBZ" alt="Create new API key — step 2"><figcaption><p>Step 2: Confirm with your authenticator app code</p></figcaption></figure>

<figure><img src="/files/gpakn3CRKM6wHxWDJ7jE" alt="Create new API key — step 3"><figcaption><p>Step 3: Copy and save the key — it is shown only once</p></figcaption></figure>


# Postman collection

{% file src="/files/kd1FWaMxn0jyc7ejq8VB" %}


# Txn bot Slack application

**How to Install Our Slack App and Set Up a Webhook in Your Workspace**

To allow our system to send payment notifications to your Slack channel, please follow these steps:

**Step 1: Install the Slack App in Your Workspace**

1. Go to our app’s install link:
2. Authorize the app to install in your Slack workspace.

**Step 2: Enable Incoming Webhooks for the App**

1. Visit the Slack App config dashboard: <https://api.slack.com/apps>
2. Click on the app you just installed.
3. On the left sidebar, go to **“Incoming Webhooks”** and click **“Activate Incoming Webhooks”**.
4. Click **“Add New Webhook to Workspace”**.
5. Select the specific channel you want notifications sent to, and click **“Allow”**.
6. Copy the generated **Webhook URL**.

**Step 3: Share the Webhook URL With Us**

Please send the Webhook URL to <support@txn.io> so we can configure our system to post messages to your channel.


# Sending payment notifications to Slack

Route Txn payment events straight into a Slack channel so your support team can act on them in real time — without watching the dashboard or building a backend.

You build a **Slack Workflow** that starts from a webhook and posts a formatted message to a channel. You then share that workflow's URL with Txn. From then on, Txn sends a notification to the channel whenever a relevant payment event occurs.

## When this is useful

The notifications are most valuable for events your support team needs to reach out about proactively. For example:

* **A payment arrives for an already-closed invoice.** When an end user pays again against an invoice that is already settled, Txn allocates the received funds to your account in the payment currency (for example, USDT received is credited to your USDT account) and sends a notification so support can reconcile the extra payment with the customer.
* **A payment is rejected on risk grounds.** When a deposit is placed on hold due to high-risk exposure, then rejected and refunded to the source address, a notification lets support follow up with the end user instead of waiting for them to report a missing payment.

## What you'll need

* A Slack workspace where you can create workflows in **Workflow Builder**.
* A channel for the notifications — for example, a private `customer-support` channel.

## Step 1 — Open Workflow Builder

In Slack, go to **More → Tools** ("Create and find workflows and apps") and create a new workflow. Give it a recognizable name such as `Txn Payment Alerts`.

<p align="center"><img src="/files/3LHCIDgYkqGEkf7YzMox" alt="" data-size="original"></p>

## Step 2 — Start the workflow from a webhook

Under **Start the workflow…**, choose an event, then select **From a webhook** ("Starts from a third-party event"). This makes the workflow run whenever Txn sends a web request to it.

{% hint style="warning" %}
Slack generates the **Web request URL** only after you save the trigger, and anyone with that URL can trigger the workflow. Treat it as a secret — share it only with Txn.
{% endhint %}

<p align="center"><img src="/files/nXxNygaWUxCI0qNhY4ur" alt=""></p>

## Step 3 — Define the data variables

On the webhook trigger, open **Set Up Variables** and add one variable for each field Txn sends in the notification payload. For every variable, set the **Data type** to **Text**.

<p align="center"><img src="/files/zRIuev9YLxezC2q3Ebi8" alt=""></p>

Txn sends a flat JSON payload. Create a variable for each key:

```json
{
  "network_name": "Example text",
  "transaction_type": "Example text",
  "tx_hash": "Example text",
  "description": "Example text",
  "address": "Example text",
  "reference": "Example text",
  "company_name": "Example text",
  "amount": "Example text"
}
```

| Variable key       | Data type | Description                                                    |
| ------------------ | --------- | -------------------------------------------------------------- |
| `network_name`     | Text      | The network the transaction settled on, e.g. `Tron (TRC20)`.   |
| `transaction_type` | Text      | The type of transaction (for example, a deposit).              |
| `tx_hash`          | Text      | The on-chain transaction hash.                                 |
| `description`      | Text      | Human-readable summary of what happened.                       |
| `address`          | Text      | The relevant wallet address (for example, the source address). |
| `reference`        | Text      | Your reference for the related invoice, payout, or channel.    |
| `company_name`     | Text      | Your merchant account name.                                    |
| `amount`           | Text      | The transaction amount, including currency.                    |

## Step 4 — Add a "Send a message to a channel" step

Under **Then, do these things**, add a step, open **Messages**, and choose **Send a message to a channel**.

<p align="center"><img src="/files/fiM8umNQ5pH0Sp2NHW4i" alt=""></p>

Select the destination channel (for example, `customer-support`). Then build the message: type each label, and use **Insert a variable** to drop in the matching webhook variable next to it.

<p align="center"><img src="/files/de0GAzQMptjOo8oPpCro" alt=""></p>

A message template that maps every variable to a labelled line:

```
Description: {description}
Merchant: {company_name}
Transaction Type: {transaction_type}
Merchant Reference: {reference}
Transaction Hash: {tx_hash}
Amount: {amount}
Address: {address}
Network: {network_name}
```

Save the step. Your workflow now starts from the webhook and posts to the channel.

<p align="center"><img src="/files/txti686DFn4l64pCf0w1" alt=""></p>

## Step 5 — Publish

Select **Finish Up**, confirm the workflow's name and permissions, and **Publish**.

<p align="center"><img src="/files/PHxtEJjjSw0JIFOpQtRi" alt=""></p>

After publishing, Slack confirms the workflow is live. You can optionally **Add to Channel** to surface it on the channel's Workflows tab.

<p align="center"><img src="/files/2bITEOggD7B7fJF8qNXM" alt=""></p>

## Step 6 — Share the URL with Txn

Open the webhook trigger again and copy the **Web request URL**. Share it with your **Txn implementation manager** or **Txn customer support**, who will configure Txn to send notifications to it.

Once configured, Txn posts a message to your channel each time a relevant payment event occurs.


# Changelog

## July 11, 2026

Channel deposits now return additional detail on each deposit. The new attributes appear in the [Read channel deposit](/channels/reading-channel-deposit) and [List channel deposits](/channels/listing-channel-deposits) responses, and in the [channel webhook](/channels/channel-webhooks) payload.

**Network fee breakdown**

The on-chain network fee incurred by the deposit is now reported, expressed in three currencies:

* **networkFee** and **networkFeeCurrency** — the network fee and its currency (the network's native asset, e.g. `TRX`).
* **networkFeePayAmount** — the network fee expressed in the deposit's `payCurrency`.
* **networkFeeLocalAmount** — the network fee expressed in the `localCurrency`.
* **payToLocalCurrencyRate** — the `payCurrency` to `localCurrency` exchange rate.

**Source-address screening**

Deposits now carry the result of on-chain analytics screening of the sender:

* **riskScore** — a risk score for the deposit's source address, when a score is available.
* **clusterCategory** and **clusterName** — the category and name of the entity the source address is attributed to (e.g. `Exchange` / `Binance`).

These fields are additive and require no changes to existing integrations. The screening fields are populated once a deposit reaches `completed`.

## May 13, 2026

Added support for USDT and USDC on the Solana network.

| Name       | Code | Network |
| ---------- | ---- | ------- |
| Tether USD | USDT | Solana  |
| USD Coin   | USDC | Solana  |

Refer to the [Supported Currencies](/api-basics/supported-currencies) page for more detail.

## March 25, 2025

Added support for new tokens.

| Name            | Code | Network |
| --------------- | ---- | ------- |
| Polygon Token   | POL  | Polygon |
| Native USD Coin | USDC | Polygon |

Refer to the [Supported Currencies](/api-basics/supported-currencies) page for more detail.

## February 1, 2025

Added support for Chinese Yuan (CNY), Brazilian Real (BRL), Chilean Peso (CLP) and Indian Rupee (INR) currencies.

The following currency pairs are available and supported in invoices, channels and payouts:

* crypto/CNY
* crypto/BRL
* crypto/CLP
* crypto/INR

When creating invoices, channels, and payouts with these currencies, you must also supply the account currency to process payments through (e.g. `EUR`).

## January 15, 2025

Merchants can now supply their preferred account currency when creating invoices, channels and payouts.

* For invoices, it's a new optional `targetCurrency` parameter which specifies the account that an invoice payment amount should be credited to.
* For channels, it's a new optional `localCurrency` parameter which specifies the currency code that a channel deposit amount should be denoted in.
* For payouts, it's a new optional `chargeCurrency` parameter which specifies the account that a payout amount should be debited from.
* For payment links, it's a new optional `accountCurrency` parameter which specifies the account that a payment amount should be credited/debited to/from.

## January 3, 2025

Added support for Canadian Dollar (CAD) and New Zealand Dollar (NZD) currencies.

The following currency pairs and directions are available and supported in exchanges, invoices, channels and payouts:

* crypto/CAD - buy and sell
* crypto/NZD - buy and sell
* EUR/CAD - buy and sell
* EUR/NZD - buy and sell

## December 14, 2024

The [Fiat Settlement API](/fiat-settlements/listing-bank-accounts) endpoints are exposed in the public API, allowing platform clients to fetch data about bank accounts linked to their transaction accounts, as well as to receive webhook notifications related to bank deposits and withdrawals.

## December 5, 2024

Platform users can now request CSV transaction reports containing data on all currency account transactions via the UI and receive the files at their registered email addresses. Navigate to the Reports page from the left-hand menu in your Txn account.

## November 15, 2024

Added support for a new token.

| Name      | Code | Network          |
| --------- | ---- | ---------------- |
| Chainlink | LINK | Ethereum (ERC20) |

Refer to the [Supported Currencies](/api-basics/supported-currencies) page for more detail.

## November 11, 2024

Added support for new cryptocurrencies and tokens.

| Name         | Code | Network          |
| ------------ | ---- | ---------------- |
| Bitcoin Cash | BCH  | Bitcoin Cash     |
| Litecoin     | LTC  | Litecoin         |
| Ether        | ETH  | Ethereum         |
| Tether USD   | USDT | Ethereum (ERC20) |
| USD Coin     | USDC | Ethereum (ERC20) |
| XRP          | XRP  | Ripple           |

Refer to the [Supported Currencies](/api-basics/supported-currencies) page for more detail.

**CNH trading currency pairs delisted**

Txn no longer supports currency pairs and trading routes for buying and selling CNH. We are working on a comprehensive solution to support additional fiat currencies.

**Additional routes for crypto-crypto invoices and payouts**

Invoice Flow: USDT <- BTC, BCH, LTC, ETH, USDT, USDC, TRX, XRP. Users can pay with any of the supported cryptocurrencies or tokens, and merchants are settled in USDT.

Payout Flow: USDT -> BTC, BCH, LTC, ETH, USDT, USDC, TRX, XRP. Users can request payouts in any supported cryptocurrency or token, which will be processed from the merchant’s USDT balance.

**Endpoints for listing and creating account addresses**

Txn clients can now access API endpoints for [listing](/accounts/listing-account-addresses) and [creating](/accounts/creating-account-address) account addresses.

## October 10, 2024

Handling of invoice payment exception scenarios and automated invoice refunds are now available for Txn clients.

Merchants can now use automated by Txn payment refunds in scenarios where their end-users overpay, underpay, or make a payment after the invoice has expired. Txn issues a refund payment link, which can be embedded or emailed to the end-user. On the refund webpage, end-users are asked to provide their wallet address where they would like to receive their refund.

Please refer to the [Invoice Refunds](/invoices/invoice-refunds) page for more information on how it works for both merchants and their end-users.

## October 8, 2024

The Channels related public API endpoints made available to Txn clients:

* [Create channel](/channels/creating-channel)
* [Read channel](/channels/reading-channel)
* [Update channel](/channels/updating-channel)
* [List channels](/channels/listing-channels)
* [List channel deposits by channel ID](/channels/listing-channel-deposits)
* [Read channel deposit](/channels/reading-channel-deposit)

## September 20, 2024

Added support for Offshore Renminbi (CNH) currency.

The following currency pairs and directions are available and supported in exchanges, invoices, channels and payouts:

* USDT/CNH - buy and sell
* BTC/CNH - buy and sell

## September 16, 2024

Webhook messages are now available in both Production and Sandbox environments.

For more information, please refer to the [Webhooks](/api-basics/webhooks) page.

## August 21, 2024

**Invoices**

The following optional parameters are now supported in the [Create Invoice](/invoices/creating-invoice) API call:

* **successRedirectUrl**: Specifies the URL to which your customer will be redirected after a successful invoice completion
* **unsuccessRedirectUrl**: Specifies the URL to redirect your customer if the invoice expires, is canceled, or is rejected

Additionally, invoices now come with hosted web pages provided by Txn. You can either embed these hosted pages within your UI or redirect your customers to them. The API response for each invoice now includes the **hostedPageUrl** attribute, which contains the URL of the hosted page.

**Payouts**

The following optional parameter is now supported in the [Create Payout](/payouts/creating-payout) API call:

* **absorbFees**: If true, both service and network fees are deducted from the transaction amount. If false, both fees are deducted from your account balance.

## July 23, 2024

The [Validate Address](/payouts/validating-addresses) endpoint made available for Txn Public API users. This new feature enhances the security and reliability of your crypto payout transactions by providing address validation capabilities.

Key Features:

* **Address Format Validation:** Ensures that the provided address adheres to the correct format
* **Address Risk Profile Assessment:** Evaluates the risk associated with the address, helping to mitigate fraudulent transactions

**Usage Recommendation:** We strongly recommend that Txn merchants utilize this endpoint to validate destination wallet addresses before initiating crypto payouts via the [Create Payout](/payouts/creating-payout) endpoint. By doing so, you can prevent potential issues arising from invalid address formats or high-risk addresses.

## July 12, 2024

The Invoices and Payouts related public API endpoints made available to Txn clients:

**Invoices**

* [Create invoice](/invoices/creating-invoice)
* [Read invoice](/invoices/reading-invoice)
* [List invoices](/invoices/listing-invoices)

**Payouts**

* [Create payout](/payouts/creating-payout)
* [Read payout](/payouts/reading-payout)
* [List payouts](/payouts/listing-payouts)

## July 2, 2024

The Accounts and Exchange related public API endpoints made available to Txn clients:

**Accounts**

* [List accounts](/accounts/listing-accounts)
* [Read account](/accounts/reading-account)
* [List account transactions](/accounts/listing-account-transactions)
* [Read account transaction](/accounts/reading-account-transaction)

**Exchange**

* [Read exchange rate](/exchange/reading-exchange-rates)
* [Create quote](/exchange/creating-quote)
* [Confirm quote](/exchange/confirming-quote)


# API specification

The Txn API follows the [JSON:API](https://jsonapi.org/) specification. All responses wrap resources in a `data` object with `type`, `id`, and `attributes` fields. Related resources are returned in a top-level `included` array. Errors are returned under an `errors` array with `status`, `title`, and `code` fields.

All requests and responses use the `application/vnd.api+json` content type.


# Date and time format

All timestamps use [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format in UTC, for example:

`1971-06-28T08:36:52.440Z`


# Rate limits

The rate limit is 120 requests per minute per API key, applied uniformly across all endpoints in both Production and Sandbox environments. When the limit is exceeded, the API responds with:

```json
{
    "errors": [
        {
            "status": 429,
            "title": "Too Many Requests",
            "code": "too_many_requests"
        }
    ]
}
```


# Authenticating the API

Authenticated endpoints require an API key passed in the `Authorization` header, prefixed with `Bearer`.

For example, `Authorization: Bearer txn_cmp_F41bbUWxPR2FCPA3KK5t1NadFE9Ghn`.

```bash
curl -X "POST" "https://api.sandbox.txn.io/api/public/v1/invoices" \
     -H 'Content-Type: application/vnd.api+json' \
     -H 'Authorization: Bearer txn_cmp_F41bbUWxPR2FCPA3KK5t1NadFE9Ghn' \
     -d $'{
  "data": {
    "type": "invoices",
    "attributes": {
      "amountBilled": "1000",
      "billedCurrency": "EUR",
      "chargedCurrency": "USDT",
      "network": "TTRX:USDT",
      "reference": "37ac503d-4e1f-458e-8407-033ab8bd1e5c"
    }
  }
}'
```

Without a valid key, the API returns HTTP 401:

```json
{
  "errors": [
    {
      "status": 401,
      "title": "HTTP Token: Access denied.",
      "code": "unauthorized"
    }
  ]
}
```

To create an API key, see [Creating your API keys](/getting-setup/creating-your-api-keys).


# API status

Subscribe to our [status page](https://txnplatform.statuspage.io/) to receive notifications about upcoming maintenance windows and incidents.

You can receive status notifications via Email, Slack, Microsoft Teams, or RSS/Atom feed.


# Supported currencies

This page lists the cryptocurrencies and fiat currencies Txn supports, grouped by environment and currency type. For how each type behaves in API requests, see [Currency types](#currency-types) below.

Network fees are set at the network level and, along with per-currency deposit minimums, may change without notice.

{% hint style="info" %}
Network codes in the Sandbox environment differ from those in Production — testnet networks are typically prefixed (`tbtc`, `ttrx:usdt`, `hteth`, etc.).
{% endhint %}

During the initial setup of your sandbox account, Txn adds test balances to your account. Reach out to your Txn integration manager if you need more test funds, including cryptocurrency testnet liquidity, to run your integration tests.

## Currency types

Txn supports three classes of currency. The class determines where the currency can be used in the API.

* **Cryptocurrencies** — settled on-chain. Used as the on-chain asset transferred to or from a wallet, and held as account balance on Txn.
* **Tradable fiat** — fiat currencies in which you can hold an account balance on Txn. A master account is created for each tradable currency at company onboarding (see [Accounts concept](/accounts/accounts-concept)).
* **Display fiat** — fiat currencies used only to present amounts to end users. Display currencies cannot hold a balance — the underlying settlement always happens in a tradable currency or cryptocurrency.

### Where each currency type can be used

| API field                      | Cryptocurrencies | Tradable fiat | Display fiat |
| ------------------------------ | :--------------: | :-----------: | :----------: |
| Invoice `billedCurrency`       |         ✓        |       ✓       |       ✓      |
| Invoice `chargedCurrency`      |         ✓        |       —       |       —      |
| Invoice `targetCurrency`       |         ✓        |       ✓       |       —      |
| Payout `currency`              |         ✓        |       ✓       |       ✓      |
| Payout `chargeCurrency`        |         ✓        |       ✓       |       —      |
| Payout `payCurrency`           |         ✓        |       —       |       —      |
| Payment link `currency`        |         ✓        |       ✓       |       ✓      |
| Payment link `accountCurrency` |         ✓        |       ✓       |       —      |
| Channel `targetCurrency`       |         ✓        |       ✓       |       —      |
| Channel `localCurrency`        |         ✓        |       ✓       |       ✓      |
| Held as account balance        |         ✓        |       ✓       |       —      |

## Production environment

### Cryptocurrencies

<table data-full-width="true"><thead><tr><th>Currency</th><th width="100">Code</th><th>Network</th><th width="160">Network code</th><th>Min deposit</th><th width="130">Confirmations</th><th>Decimals</th><th>Explorer</th></tr></thead><tbody><tr><td>Bitcoin</td><td>BTC</td><td>Bitcoin</td><td><code>btc</code></td><td>0.000001</td><td>1</td><td>8</td><td><a href="https://blockchair.com/bitcoin">blockchair.com/bitcoin</a></td></tr><tr><td>Bitcoin Cash</td><td>BCH</td><td>Bitcoin Cash</td><td><code>bch</code></td><td>0.03</td><td>1</td><td>8</td><td><a href="https://blockchair.com/bitcoin-cash">blockchair.com/bitcoin-cash</a></td></tr><tr><td>Cardano</td><td>ADA</td><td>Cardano</td><td><code>ada</code></td><td>1</td><td>1</td><td>6</td><td><a href="https://explorer.cardano.org/">explorer.cardano.org</a></td></tr><tr><td>Chainlink</td><td>LINK</td><td>Ethereum</td><td><code>link</code></td><td>0.5</td><td>1</td><td>6</td><td><a href="https://etherscan.io/">etherscan.io</a></td></tr><tr><td>Dogecoin</td><td>DOGE</td><td>Doge</td><td><code>doge</code></td><td>5</td><td>1</td><td>8</td><td><a href="https://blockchair.com/dogecoin">blockchair.com/dogecoin</a></td></tr><tr><td>Ether</td><td>ETH</td><td>Ethereum</td><td><code>eth</code></td><td>0.001</td><td>1</td><td>6</td><td><a href="https://etherscan.io/">etherscan.io</a></td></tr><tr><td>Litecoin</td><td>LTC</td><td>Litecoin</td><td><code>ltc</code></td><td>0.1</td><td>1</td><td>8</td><td><a href="https://blockchair.com/litecoin">blockchair.com/litecoin</a></td></tr><tr><td>Native BNB</td><td>BNB</td><td>Binance Smart Chain</td><td><code>bsc</code></td><td>0.001</td><td>1</td><td>6</td><td><a href="https://bscscan.com/">bscscan.com</a></td></tr><tr><td>Polygon Ecosystem Token</td><td>POL</td><td>Polygon</td><td><code>polygon</code></td><td>5</td><td>1</td><td>6</td><td><a href="https://polygonscan.com/">polygonscan.com</a></td></tr><tr><td>Shiba Inu</td><td>SHIB</td><td>Ethereum</td><td><code>shib</code></td><td>80,000</td><td>1</td><td>6</td><td><a href="https://etherscan.io/">etherscan.io</a></td></tr><tr><td>Solana</td><td>SOL</td><td>Solana</td><td><code>sol</code></td><td>0.01</td><td>1</td><td>6</td><td><a href="https://solscan.io/">solscan.io</a></td></tr><tr><td>Tether USD</td><td>USDT</td><td>Tron</td><td><code>trx:usdt</code></td><td>1</td><td>19</td><td>6</td><td><a href="https://tronscan.org/">tronscan.org</a></td></tr><tr><td>Tether USD</td><td>USDT</td><td>Ethereum</td><td><code>usdt</code></td><td>1</td><td>1</td><td>6</td><td><a href="https://etherscan.io/">etherscan.io</a></td></tr><tr><td>Tether USD</td><td>USDT</td><td>Polygon</td><td><code>polygon:usdt</code></td><td>1</td><td>1</td><td>6</td><td><a href="https://polygonscan.com/">polygonscan.com</a></td></tr><tr><td>Tether USD</td><td>USDT</td><td>Binance Smart Chain</td><td><code>bsc:usdt</code></td><td>1</td><td>1</td><td>6</td><td><a href="https://bscscan.com/">bscscan.com</a></td></tr><tr><td>Tether USD</td><td>USDT</td><td>Solana</td><td><code>sol:usdt</code></td><td>1</td><td>1</td><td>6</td><td><a href="https://solscan.io/">solscan.io</a></td></tr><tr><td>Tronix</td><td>TRX</td><td>Tron</td><td><code>trx</code></td><td>5</td><td>19</td><td>6</td><td><a href="https://tronscan.org/">tronscan.org</a></td></tr><tr><td>USD Coin</td><td>USDC</td><td>Ethereum</td><td><code>usdc</code></td><td>1</td><td>1</td><td>6</td><td><a href="https://etherscan.io/">etherscan.io</a></td></tr><tr><td>USD Coin</td><td>USDC</td><td>Polygon</td><td><code>polygon:usdcv2</code><sup>2</sup></td><td>1</td><td>1</td><td>6</td><td><a href="https://polygonscan.com/">polygonscan.com</a></td></tr><tr><td>USD Coin</td><td>USDC</td><td>Solana</td><td><code>sol:usdc</code></td><td>1</td><td>1</td><td>6</td><td><a href="https://solscan.io/">solscan.io</a></td></tr><tr><td>XRP</td><td>XRP</td><td>Ripple</td><td><code>xrp</code></td><td>1</td><td>1</td><td>6</td><td><a href="https://xrpscan.com/">xrpscan.com</a></td></tr></tbody></table>

<sup>2</sup> The `v2` suffix refers to the bridged USDC contract on Polygon. Use this code when integrating Polygon USDC; the legacy code is no longer accepted.

### Tradable fiat

| Currency           | Code | Decimals |
| ------------------ | ---- | -------- |
| Euro               | EUR  | 2        |
| US Dollar          | USD  | 2        |
| British Pound      | GBP  | 2        |
| Canadian Dollar    | CAD  | 2        |
| New Zealand Dollar | NZD  | 2        |
| Japanese Yen       | JPY  | 0        |

### Display fiat

| Currency           | Code | Decimals |
| ------------------ | ---- | -------- |
| Australian Dollar  | AUD  | 2        |
| Brazilian Real     | BRL  | 2        |
| Chilean Peso       | CLP  | 0        |
| Chinese Yuan       | CNY  | 2        |
| Colombian Peso     | COP  | 2        |
| Hong Kong Dollar   | HKD  | 2        |
| Indian Rupee       | INR  | 2        |
| Indonesian Rupiah  | IDR  | 2        |
| Malaysian Ringgit  | MYR  | 2        |
| Mexican Peso       | MXN  | 2        |
| New Taiwan Dollar  | TWD  | 2        |
| Nigerian Naira     | NGN  | 2        |
| Peruvian Sol       | PEN  | 2        |
| Philippine Peso    | PHP  | 2        |
| South African Rand | ZAR  | 2        |
| South Korean Won   | KRW  | 0        |
| Thai Baht          | THB  | 2        |
| Turkish Lira       | TRY  | 2        |
| Vietnamese Dong    | VND  | 0        |

## Sandbox environment

The Sandbox environment supports a subset of the production cryptocurrencies for testing. The fiat currency catalogue is identical across environments, so the [Tradable fiat](#tradable-fiat) and [Display fiat](#display-fiat) tables above apply to Sandbox as well.

### Cryptocurrencies

<table data-full-width="true"><thead><tr><th>Currency</th><th width="100">Code</th><th>Network</th><th width="160">Network code</th><th>Min deposit</th><th width="130">Confirmations</th><th>Decimals</th><th>Explorer</th></tr></thead><tbody><tr><td>Bitcoin</td><td>BTC</td><td>Bitcoin</td><td><code>tbtc</code></td><td>0.000001</td><td>1</td><td>8</td><td><a href="https://blockchair.com/bitcoin/testnet">blockchair.com/bitcoin/testnet</a></td></tr><tr><td>Ether</td><td>ETH</td><td>Ethereum (Hoodi)</td><td><code>hteth</code></td><td>0.001</td><td>1</td><td>6</td><td><a href="https://hoodi.etherscan.io/">hoodi.etherscan.io</a></td></tr><tr><td>Tether USD</td><td>USDT</td><td>Tron (Shasta)</td><td><code>ttrx:usdt</code></td><td>1</td><td>19</td><td>6</td><td><a href="https://shasta.tronscan.org/">shasta.tronscan.org</a></td></tr><tr><td>Tronix</td><td>TRX</td><td>Tron (Shasta)</td><td><code>ttrx</code></td><td>1</td><td>19</td><td>6</td><td><a href="https://shasta.tronscan.org/">shasta.tronscan.org</a></td></tr><tr><td>XRP</td><td>XRP</td><td>Ripple Testnet</td><td><code>txrp</code></td><td>1</td><td>1</td><td>6</td><td><a href="https://test.xrplexplorer.com/en">test.xrplexplorer.com</a></td></tr></tbody></table>


# Webhooks

Txn supports webhooks for the following transaction types:

* [Invoice](/invoices/invoice-webhooks)
* [API Payout](/payouts/payout-webhooks)
* Manual Payout via UI
* [Channels](/channels/channel-webhooks)
* [Exchange](/exchange/exchange-webhooks)
* Direct crypto deposits received into your account

Webhooks are triggered each time the state of a transaction is updated.

You can configure your webhook URLs on the **Developers → Webhook URLs** tab in your Txn account.

<figure><img src="/files/CeOqbA9YbCLgqTmk8kKI" alt="Webhook URLs page"><figcaption><p>Developers → Webhook URLs</p></figcaption></figure>

<figure><img src="/files/zJt4T9T0Ht3pG4tTmpug" alt="Create Webhook URL"><figcaption><p>Enter a label, your endpoint URL, and choose which event types to subscribe to</p></figcaption></figure>

<figure><img src="/files/X48Oy0PXgJlhs4WdlcjA" alt="Save the webhook secret key"><figcaption><p>Copy and save the secret key — it is shown only once and is used to verify webhook signatures</p></figcaption></figure>

## Associating API keys with webhook URLs

When creating or editing a webhook URL, you can associate one or more API keys with it. All transaction events for resources created by an associated key — invoices, payouts, channels, exchanges, and deposits — are routed to that endpoint.

This lets you route events from different parts of your integration to different endpoints. For example, you could direct invoice events to one service and payout events to another by using separate API keys, each associated with its own webhook URL.

{% hint style="danger" %}
**API key rotation breaks webhook routing for all resources created by the old key.**

Every resource — invoice, payout, channel, and so on — is permanently linked to the API key that created it. Webhook routing follows that link: if the creating key is associated with a webhook URL, events are sent there; if the key is deleted, events stop being sent anywhere.

**Example:** API key A is associated with webhook URL B. A channel is created using key A. Key A is later deleted and key D is created. Even though key D exists and may be associated with URL B, the channel was created by key A — so its events no longer route to URL B or anywhere else.

**When rotating API keys:**

1. Create the new API key first.
2. Associate the new key with the relevant webhook URLs **before** using it to create any resources.
3. Keep in mind that any resources already created by the old key will stop routing events as soon as the old key is deleted — there is no way to reassign them to a new key after the fact.
   {% endhint %}


# Verifying webhooks with the Svix libraries (Recommended)

Each webhook call includes three headers with additional information used for verification:

* **svix-id**: The unique message identifier for the webhook message. This identifier is unique across all messages but will remain the same when the same webhook is being resent (e.g., due to a previous failure).
* **svix-timestamp**: The timestamp in seconds since the epoch.
* **svix-signature**: The Base64-encoded list of signatures, space-delimited.

***

First install the libraries if you haven't already:

{% tabs fullWidth="false" %}
{% tab title="JavaScript" %}

```
npm install svix
// Or
yarn add svix
```

{% endtab %}

{% tab title="Python" %}

```
pip install svix
```

{% endtab %}

{% tab title="Rust" %}

```
http = "1.0.0"
svix = "1.20.0"
```

{% endtab %}

{% tab title="Go" %}

```
go get github.com/svix/svix-webhooks/go
```

{% endtab %}

{% tab title="Java" %}
Gradle: Add this dependency to your project's build file:

```
implementation "com.svix:svix:0.x.y"
```

Maven: Add this dependency to your project's POM:

```
<dependency>
  <groupId>com.svix</groupId>
  <artifactId>svix</artifactId>
  <version>0.x.y</version>
</dependency>
```

{% endtab %}

{% tab title="Kotlin" %}
Gradle: Add this dependency to your project's build file:

```
implementation "com.svix.kotlin:svix-kotlin:0.x.y"
```

Maven: Add this dependency to your project's POM:

```
<dependency>
  <groupId>com.svix.kotlin</groupId>
  <artifactId>svix-kotlin</artifactId>
  <version>0.x.y</version>
</dependency>
```

{% endtab %}

{% tab title="Ruby" %}

```
gem install svix
```

{% endtab %}

{% tab title="C#" %}

```
dotnet add package Svix
```

{% endtab %}

{% tab title="PHP" %}

```
composer require svix/svix
```

{% endtab %}

{% tab title="CLI" %}
On macOS install via [Homebrew](https://brew.sh/):

```
brew install svix/svix/svix-cli
```

On Windows install via [Scoop](https://scoop.sh/):

```
scoop bucket add svix https://github.com/svix/scoop-svix.git
scoop install svix
```

For other platforms, such as linux, checkout the [CLI docs](https://github.com/svix/svix-cli#installation) on Github.
{% endtab %}

{% tab title="cURL" %}

```
# Install cURL. E.g. on arch linux:
pacman -S curl
```

{% endtab %}
{% endtabs %}

Then verify webhooks using the code below. The payload is the raw (string) body of the request, and the headers are the headers passed in the request.

{% hint style="warning" %}
**USE THE RAW REQUEST BODY**

You need to use the raw request body when verifying webhooks, as the cryptographic signature is sensitive to even the slightest changes. You should watch out for frameworks that parse the request as JSON and then stringify it because this too will break the signature verification.
{% endhint %}

## Framework specific examples <a href="#framework-specific-examples" id="framework-specific-examples"></a>

Here are examples of how to adjust the above examples to your framework of choice.

### Python (Django) <a href="#python-django" id="python-django"></a>

```python
from django.http import HttpResponse

from svix.webhooks import Webhook, WebhookVerificationError

secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"

@csrf_exempt
def webhook_handler(request):
    headers = request.headers
    payload = request.body

    try:
        wh = Webhook(secret)
        msg = wh.verify(payload, headers)
    except WebhookVerificationError as e:
        return HttpResponse(status=400)

    # Do something with the message...

    return HttpResponse(status=204)
```

### Python (Flask) <a href="#python-flask" id="python-flask"></a>

```python
from flask import request

from svix.webhooks import Webhook, WebhookVerificationError

secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"

@app.route('/webhook/')
def webhook_handler():
    headers = request.headers
    payload = request.get_data()

    try:
        wh = Webhook(secret)
        msg = wh.verify(payload, headers)
    except WebhookVerificationError as e:
        return ('', 400)

    # Do something with the message...

    return ('', 204)
```

### Python (FastAPI) <a href="#python-fastapi" id="python-fastapi"></a>

```python
from fastapi import Request, Response, status

from svix.webhooks import Webhook, WebhookVerificationError

secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"

@router.post("/webhook/", status_code=status.HTTP_204_NO_CONTENT)
async def webhook_handler(request: Request, response: Response):
    headers = request.headers
    payload = await request.body()

    try:
        wh = Webhook(secret)
        msg = wh.verify(payload, headers)
    except WebhookVerificationError as e:
        response.status_code = status.HTTP_400_BAD_REQUEST
        return

    # Do something with the message...
```

### Node.js (Next.js) <a href="#nodejs-nextjs" id="nodejs-nextjs"></a>

The [svix-example](https://github.com/svix/svix-example) repo contains an [example](https://github.com/svix/svix-example/blob/main/src/pages/api/consumer/webhooks.ts) of how to verify and use webhooks in a Next.js application.

```js
import { Webhook } from "svix";
import { buffer } from "micro";

export const config = {
    api: {
        bodyParser: false,
    },
}

const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

export default async function handler(req, res) {
    const payload = (await buffer(req)).toString();
    const headers = req.headers;

    const wh = new Webhook(secret);
    let msg;
    try {
        msg = wh.verify(payload, headers);
    } catch (err) {
        res.status(400).json({});
    }

    // Do something with the message...

    res.json({});
}
```

### Node.js (Next.js 13 App Router) <a href="#nodejs-nextjs-13-app-router" id="nodejs-nextjs-13-app-router"></a>

```js
import { Webhook } from "svix";

const webhookSecret: string = process.env.WEBHOOK_SECRET || "your-secret";

export async function POST(req: Request) {
  const svix_id = req.headers.get("svix-id") ?? "";
  const svix_timestamp = req.headers.get("svix-timestamp") ?? "";
  const svix_signature = req.headers.get("svix-signature") ?? "";

  const body = await req.text();

  const sivx = new Webhook(webhookSecret);

  let msg;

  try {
    msg = sivx.verify(body, {
      "svix-id": svix_id,
      "svix-timestamp": svix_timestamp,
      "svix-signature": svix_signature,
    });
  } catch (err) {
    return new Response("Bad Request", { status: 400 });
  }

  console.log(msg);

  // Rest

  return new Response("OK", { status: 200 });
}
```

### Node.js (Netlify Functions) <a href="#nodejs-netlify-functions" id="nodejs-netlify-functions"></a>

```js
import { Webhook } from "svix";

const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";


export const handler = async ({body, headers}) => {
    const payload = body;

    const wh = new Webhook(secret);
    let msg;
    try {
        msg = wh.verify(payload, headers);
    } catch (err) {
        res.status(400).json({});
    }

    // Do something with the message...

    res.json({});
}
```

### Node.js (Express) <a href="#nodejs-express" id="nodejs-express"></a>

**Note:** When integrating this example into a larger codebase, you will have to make sure not to apply the `express.json()` middleware to the webhook route, because the payload has to be passed to `wh.verify` without any prior parsing.

```js
import { Webhook } from "svix";
import bodyParser from "body-parser";

const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

app.post('/webhook', bodyParser.raw({ type: 'application/json' }), (req, res) => {
    const payload = req.body;
    const headers = req.headers;

    const wh = new Webhook(secret);
    let msg;
    try {
        msg = wh.verify(payload, headers);
    } catch (err) {
        res.status(400).json({});
    }

    // Do something with the message...

    res.json({});
});
```

### Node.js (NestJS) <a href="#nodejs-nestjs" id="nodejs-nestjs"></a>

Initialize the application with the `rawBody` flag set to true. See the [NestJS docs](https://docs.nestjs.com/faq/raw-body#raw-body) for details.

```js
// main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(
    AppModule,
    { rawBody: true } // add rawBody flag
  );
  await app.listen(3000);
}
bootstrap();

```

```js
// webhook.controller.ts
import { Controller, Post, RawBodyRequest, Req } from '@nestjs/common';
import { Request } from 'express';
import { Webhook } from 'svix';

@Controller('webhook')
class WebhookController {
  @Post()
  webhook(@Req() request: RawBodyRequest<Request>) {
    const secret = 'whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw';
    const wh = new Webhook(secret);

    const payload = request.rawBody.toString('utf8');
    const headers = request.headers;

    let msg;
    try {
      msg = wh.verify(payload, headers);
    } catch (err) {
      // handle error
    }

    // Do something with the message...
  }
}

```

### Node.js (Nuxt) <a href="#nodejs-nuxt" id="nodejs-nuxt"></a>

```js
import { Webhook } from "svix";

const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

export default defineEventHandler(async (event) => {
  const headers = getRequestHeaders(event);
  const payload = await readRawBody(event);

  const wh = new Webhook(secret);

  let msg;

  try {
      msg = wh.verify(payload, headers);
  } catch (err) {
      setResponseStatus(event, 400);
      return "Bad Request";
  }

  // Do something with the message...
  return "OK";
})
```

### Go (Standard lib) <a href="#go-standard-lib" id="go-standard-lib"></a>

```go
package main

import (
	"io"
	"log"
	"net/http"

	svix "github.com/svix/svix-webhooks/go"
)

const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"

func main() {

	wh, err := svix.NewWebhook(secret)
	if err != nil {
		log.Fatal(err)
	}

	http.HandleFunc("/webhook", func(w http.ResponseWriter, r *http.Request) {
		headers := r.Header
		payload, err := io.ReadAll(r.Body)
		if err != nil {
			w.WriteHeader(http.StatusBadRequest)
			return
		}

		err = wh.Verify(payload, headers)
		if err != nil {
			w.WriteHeader(http.StatusBadRequest)
			return
		}

		// Do something with the message...

		w.WriteHeader(http.StatusNoContent)

	})
	http.ListenAndServe(":8080", nil)
}
```

### Go (Gin) <a href="#go-gin" id="go-gin"></a>

```go
package main

import (
	"io"
	"log"
	"net/http"

	"github.com/gin-gonic/gin"
	svix "github.com/svix/svix-webhooks/go"
)

const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"

func main() {

	wh, err := svix.NewWebhook(secret)
	if err != nil {
		log.Fatal(err)
	}

	r := gin.Default()
	r.POST("/webhook", func(c *gin.Context) {
		headers := c.Request.Header
		payload, err := io.ReadAll(c.Request.Body)
		if err != nil {
			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
			return
		}

		err = wh.Verify(payload, headers)
		if err != nil {
			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
			return
		}

		// Do something with the message...

		c.JSON(200, gin.H{})
	})
	r.Run()
}
```

### Rust (axum) <a href="#rust-axum" id="rust-axum"></a>

Add the `webhook_in` route below to an axum router.

```rust
use axum::{body::Bytes, http::StatusCode};
use hyper::HeaderMap;

pub const SECRET: &'static str = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

pub async fn webhook_in(headers: HeaderMap, body: Bytes) -> StatusCode {
    let Ok(wh) = svix::webhooks::Webhook::new(SECRET) else {
        return StatusCode::INTERNAL_SERVER_ERROR;
    };

    if let Err(_) = wh.verify(&body, &headers) {
        return StatusCode::BAD_REQUEST;
    }

    // Do something with the message...

    StatusCode::NO_CONTENT
}
```

### Ruby (Ruby on Rails) <a href="#ruby-ruby-on-rails" id="ruby-ruby-on-rails"></a>

Once you've set up your project add a route to your `config/routes.rb` file at the top of the `Rails.application.routes.draw` block:

```ruby
Rails.application.routes.draw do
  post "/webhook", to: "webhook#index"

  # For details on the DSL available within this file, see https://guides.rubyonrails.org/routing.html
end
```

The route above declares that `POST /webhook` requests are mapped to the index action of `WebhookController`.

To create `WebhookController` and its index action, we'll run the controller generator (with the `--skip-routes` option because we already have an appropriate route):

```
bin/rails generate controller Webhook index --skip-routes
```

Rails will create several files for you:

```ruby
    create  app/controllers/webhook_controller.rb
    invoke  erb
    create    app/views/webhook
    create    app/views/webhook/index.html.erb
    invoke  test_unit
    create    test/controllers/webhook_controller_test.rb
    invoke  helper
    create    app/helpers/webhook_helper.rb
    invoke    test_unit
    invoke  assets
    invoke    scss
    create      app/assets/stylesheets/webhook.scss
```

Now we can add our verification logic to the newly created `app/controllers/webhook_controller.rb` file:

```ruby
require 'svix'

class WebhookController < ApplicationController
  protect_from_forgery with: :null_session # disables CSRF middleware; required for API endpoints

  def index
    begin
      payload = request.body.read
      headers = request.headers
      wh = Svix::Webhook.new("whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw")

      json = wh.verify(payload, headers)

      # Do something with the message...

      head :no_content
    rescue
      head :bad_request
    end
  end
end
```

### PHP (Laravel) <a href="#php-laravel" id="php-laravel"></a>

In your `routes/api.php` file add the following after the last use directive:

```php
use Svix\Webhook;
use Svix\Exception\WebhookVerificationException;

Route::post('webhook', function(Request $request) {
    $payload = $request->getContent();
    $headers = collect($request->headers->all())->transform(function ($item) {
        return $item[0];
    });

    try {
        $wh = new Webhook("whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw");
        $json = $wh->verify($payload, $headers);

        # Do something with the message...

        return response()->noContent();
    } catch (WebhookVerificationException $e) {
        return response(null, 400);
    }
});
```


# Verifying webhooks manually

Each webhook call includes three headers with additional information used for verification:

* **svix-id**: The unique message identifier for the webhook message. This identifier is unique across all messages but will remain the same when the same webhook is being resent (e.g., due to a previous failure).
* **svix-timestamp**: The timestamp in seconds since the epoch.
* **svix-signature**: The Base64-encoded list of signatures, space-delimited.

{% hint style="warning" %}
**USE THE RAW REQUEST BODY**

You need to use the raw request body when verifying webhooks, as the cryptographic signature is sensitive to even the slightest changes. You should watch out for frameworks that parse the request as JSON and then stringify it because this too will break the signature verification.
{% endhint %}

## Constructing the Signed Content

The content to sign is created by concatenating the ID, timestamp, and payload, separated by a period (`.`). In code, it would look something like this:

```javascript
const signedContent = `${svix_id}.${svix_timestamp}.${body}`;
```

Where `body` is the raw body of the request. The signature is highly sensitive to any changes, so even a minor modification in the body will result in a completely different signature. Therefore, you should not alter the body in any way before verifying it.

## Determining the Expected Signature

Txn uses HMAC with SHA-256 to sign its webhooks.

To calculate the expected signature, you should HMAC the `signedContent` (constructed as described above) using the Base64-decoded portion of your signing secret (the part after the `whsec_` prefix) as the key. For example, if your secret is `whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw`, you should use `MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw` as the key.

Here's an example of how to calculate the signature in Ruby on Rails:

```ruby
Base64.encode64(OpenSSL::HMAC.digest(OpenSSL::Digest.new("sha256"), Base64.decode64(secret), "#{msgId}.#{timestamp}.#{payload}")).strip
```

Here’s an example of how to calculate the signature in Node.js:

```javascript
const crypto = require('crypto');

const signedContent = `${svix_id}.${svix_timestamp}.${body}`;
const secret = "whsec_5WbX5kEWLlfzsGNjH64I8lOOqUB6e8FH";

// Base64 decode the secret key
const secretBytes = Buffer.from(secret.split('_')[1], "base64");
const signature = crypto
  .createHmac('sha256', secretBytes)
  .update(signedContent)
  .digest('base64');

console.log(signature);

```

The generated signature should match one of the signatures sent in the `svix-signature` header.

The `svix-signature` header contains a list of space-delimited signatures with their corresponding version identifiers. The list usually contains one signature, but there can be multiple. For example:

```javascript
v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= v1,bm9ldHUjKzFob2VudXRob2VodWUzMjRvdWVvdW9ldQo= v2,MzJsNDk4MzI0K2VvdSMjMTEjQEBAQDEyMzMzMzEyMwo=
```

Before verifying the signature, make sure to remove the version prefix and delimiter (e.g., `v1,`).

{% hint style="warning" %}
Use a constant-time string comparison method to compare signatures to prevent timing attacks.
{% endhint %}

## Verify Timestamp

As mentioned above, Txn includes the timestamp of the attempt in the `svix-timestamp` header. Compare this timestamp against your system's timestamp to ensure it falls within your acceptable tolerance range, helping to prevent timestamp attacks.


# Source IP addresses

If your webhook endpoint is behind a firewall or NAT, allow inbound traffic from the IP addresses listed below.

{% hint style="info" %}
These IP addresses may change due to platform maintenance, upgrades, or vendor outage mitigation.
{% endhint %}

## Sandbox

Webhook messages for the API URL `https://api.sandbox.txn.io` are sent from the following IP addresses:

```
52.215.16.239
54.216.8.72
63.33.109.123
2a05:d028:17:8000::/52
```

## Production

Webhook messages for the API URL `https://api.txn.io` are sent from the following IP addresses:

```
44.228.126.217
50.112.21.217
52.24.126.164
54.148.139.208
2600:1f24:64:8000::/52
```


# Retrying schedule

Your endpoint must respond with an HTTP `2xx` status code to acknowledge receipt. Any other response is treated as a failure and the webhook is retried automatically.

Each webhook is retried on the following schedule, with each attempt starting after the previous one fails:

* Immediately
* After 5 seconds
* After 5 minutes
* After 30 minutes
* After 2 hours
* After 5 hours
* After 10 hours
* After a further 10 hours


# Hosted pages

Txn provides hosted pages for invoices, channels, and payment links. The URL for each hosted page is returned in the `hostedPageUrl` parameter in API responses.

## **Example: Invoice Hosted Page**

{% code overflow="wrap" %}

```
https://sandbox.txn.io/redirect?invoice_id=1e331bac-ca3a-4480-9c66-ae2536f04b81&request_type=invoice_hosted_page&zone=ca
```

{% endcode %}

## **Customizing the Hosted Page Appearance**

You can use the following URL parameters to control the appearance of the hosted page:

1. **`showQrCode`** (`true` / `false`)
   * If `true`, the QR code is displayed by default, so end-users don’t need to click to expand it
   * By default, users must click a button to view the QR code
2. **`hideLangSwitcher`** (`true` / `false`)
   * If `true`, the language switcher is hidden
   * By default, the language switcher is always visible
3. **`lang`** (`en`, `pt`, `fr`, `tr`, `es`, `jp`, `ar`, `cn`, `vn`, `ms`)
   * Specifies the language of the hosted page
   * By default, the platform detects the end-user's browser locale and applies the appropriate translation. If the locale isn't supported, English is used
   * `en` - English
   * `pt` - Portugal
   * `fr` - French
   * `tr` - Turkish
   * `es` - Spanish
   * `jp` - Japanese
   * `ar` - Arabic
   * `cn` - Chinese (Simplified)
   * `vn` - Vietnamese
   * `ms` - Malay (Bahasa Melayu)

### **Example: Customized Hosted Page**

{% code overflow="wrap" %}

```
https://sandbox.txn.io/redirect?invoice_id=1e331bac-ca3a-4480-9c66-ae2536f04b81&request_type=invoice_hosted_page&zone=ca&showQrCode=true&hideLangSwitcher=on&lang=en
```

{% endcode %}


# Accounts concept

A Txn account is a currency account: it holds your balance in a single currency on the Txn platform. Every tradable [currency](/api-basics/supported-currencies) Txn supports is available to your company by default.

Each account exposes its balance, total balance, currency code, ID, and full transaction history. You can read this data from the dashboard or through the API, and Txn keeps it up to date in real time.

### Account hierarchy

Accounts follow a two-level hierarchy — Company → master account (one per currency) → subaccounts:

* **Master accounts** are created automatically for each tradable currency when your company is onboarded. These are your primary accounts, identified by `"master": true` and `"label": "master"`.
* **Subaccounts** are created under a master account to segment funds — for example, by client, project, or business unit. They are identified by `"master": false` and carry the `label` you assign at creation.

For a crypto subaccount (e.g. BTC or USDT), you can generate a dedicated set of receiving addresses linked to that subaccount.

### Bank references

Each EUR account has a unique `bankReference` (e.g. `BDR7130670178476243`). Quote it on incoming bank deposits so funds are credited to the correct account.

### Reconciliation

Reading your accounts, balances, and transaction history through the API lets you reconcile against your own records and generate reports independently of the dashboard.

### Example API response

The example below shows the EUR and USDT master accounts with their subaccounts:

```json
{
  "data": [
    {
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "type": "accounts",
      "attributes": {
        "master": true,
        "currencyCode": "EUR",
        "label": "master",
        "bankReference": "BDR6421088115176062",
        "balance": "38475.76",
        "totalBalance": "38687.80",
        "currencyType": "fiat"
      }
    },
    {
      "id": "dd5016e1-43bb-4be5-b6d6-79e8d0f662b1",
      "type": "accounts",
      "attributes": {
        "master": false,
        "currencyCode": "EUR",
        "label": "EUR_1",
        "bankReference": "BDR4778763138567183",
        "balance": "80.54",
        "totalBalance": "80.54",
        "currencyType": "fiat"
      }
    },
    {
      "id": "ad5e0084-91d3-46c8-9f79-9231a75442e5",
      "type": "accounts",
      "attributes": {
        "master": false,
        "currencyCode": "EUR",
        "label": "EUR_2",
        "bankReference": "BDR8258604421708687",
        "balance": "52.89",
        "totalBalance": "52.89",
        "currencyType": "fiat"
      }
    },
    {
      "id": "0c201594-19fe-461b-bf37-0d14e51c3f3a",
      "type": "accounts",
      "attributes": {
        "master": false,
        "currencyCode": "EUR",
        "label": "EUR_3",
        "bankReference": "BDR7130670178476243",
        "balance": "78.61",
        "totalBalance": "78.61",
        "currencyType": "fiat"
      }
    },
    {
      "id": "e289de2b-37bd-4eff-b832-f754c31a2d95",
      "type": "accounts",
      "attributes": {
        "master": true,
        "currencyCode": "USDT",
        "label": "master",
        "bankReference": "BDR4180381621673581",
        "balance": "344086.455299",
        "totalBalance": "344219.499753",
        "currencyType": "crypto"
      }
    },
    {
      "id": "fbae9123-59bb-49db-bc6b-0f766c189494",
      "type": "accounts",
      "attributes": {
        "master": false,
        "currencyCode": "USDT",
        "label": "USDT_1",
        "bankReference": "BDR4654328482173537",
        "balance": "78.915973",
        "totalBalance": "78.915973",
        "currencyType": "crypto"
      }
    },
    {
      "id": "2df68c92-b9dd-4ff4-b7f2-5aeb381bf6fc",
      "type": "accounts",
      "attributes": {
        "master": false,
        "currencyCode": "USDT",
        "label": "USDT_2",
        "bankReference": "BDR0042354445442825",
        "balance": "31.434196",
        "totalBalance": "31.434196",
        "currencyType": "crypto"
      }
    },
    {
      "id": "c20dec56-10ce-49e0-ad00-916579f0c04a",
      "type": "accounts",
      "attributes": {
        "master": false,
        "currencyCode": "USDT",
        "label": "USDT_3",
        "bankReference": "BDR3865252360837137",
        "balance": "10.301300",
        "totalBalance": "10.301300",
        "currencyType": "crypto"
      }
    },
    {
      "id": "468a0e31-d9e5-4ad8-86aa-6c4806d40a2d",
      "type": "accounts",
      "attributes": {
        "master": false,
        "currencyCode": "USDT",
        "label": "USDT_4",
        "bankReference": "BDR8606155657480464",
        "balance": "12.392985",
        "totalBalance": "12.392985",
        "currencyType": "crypto"
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total": 34
  },
  "jsonapi": {
    "version": "1.0"
  }
}
```


# Listing accounts

<mark style="color:green;">`GET`</mark> `/api/public/v1/accounts`

Returns your master accounts and subaccounts, including current balances. Results are paginated.

### Example request

Use the base URL for your environment. See [Environments](/).

{% code title="curl" %}

```bash
curl -X GET "https://api.sandbox.txn.io/api/public/v1/accounts?page=1&per_page=50" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Authorization: Bearer <api_key>"
```

{% endcode %}

Authentication details: [Authenticating the API](/api-basics/authenticating-the-api).

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**URL Parameters**

| Name       | Type   | Description                            |
| ---------- | ------ | -------------------------------------- |
| `per_page` | number | Number of accounts to return per page. |
| `page`     | number | Page number to return.                 |

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": [
    {
      "id": "adb0f9c4-c7fd-4989-a273-1bd11ad5847b",
      "type": "accounts",
      "attributes": {
        "master": false,
        "currencyCode": "EUR",
        "label": "EUR_4",
        "bankReference": "BDR0154632342411086",
        "balance": "26.16",
        "totalBalance": "26.16",
        "bankWithdrawalAvailable": true,
        "bankDepositAvailable": true,
        "transferAvailable": true,
        "currencyType": "fiat"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        },
        "txnBankCredentials": {
          "data": [
            {
              "type": "txnBankCredential",
              "id": "3808e047-3479-4ba9-88dc-31729b4666d5"
            }
          ]
        }
      }
    },
    {
      "id": "c569b222-6de4-4783-a3c1-8d2b8a1bb980",
      "type": "accounts",
      "attributes": {
        "master": false,
        "currencyCode": "USDC",
        "label": "USDC_1",
        "bankReference": "BDR0804588056382376",
        "balance": "0.00",
        "totalBalance": "0.00",
        "bankWithdrawalAvailable": false,
        "bankDepositAvailable": false,
        "transferAvailable": true,
        "currencyType": "crypto"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        },
        "txnBankCredentials": {
          "data": []
        }
      }
    },
    {
      "id": "1d5a3601-76b7-4426-b5fb-3e434c17803e",
      "type": "accounts",
      "attributes": {
        "master": false,
        "currencyCode": "EUR",
        "label": "EUR_5",
        "bankReference": "BDR0354788360836433",
        "balance": "33.35",
        "totalBalance": "33.35",
        "bankWithdrawalAvailable": true,
        "bankDepositAvailable": true,
        "transferAvailable": true,
        "currencyType": "fiat"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        },
        "txnBankCredentials": {
          "data": [
            {
              "type": "txnBankCredential",
              "id": "3808e047-3479-4ba9-88dc-31729b4666d5"
            }
          ]
        }
      }
    },
    {
      "id": "dc9c1c6e-3fa6-4fce-8c5f-714dfcecf3ee",
      "type": "accounts",
      "attributes": {
        "master": false,
        "currencyCode": "USDT",
        "label": "Sub-account Adam Goodman",
        "bankReference": "BDR7013714686525702",
        "balance": "0.000000",
        "totalBalance": "0.000000",
        "bankWithdrawalAvailable": false,
        "bankDepositAvailable": false,
        "transferAvailable": true,
        "currencyType": "crypto"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        },
        "txnBankCredentials": {
          "data": []
        }
      }
    },
    {
      "id": "d5415da2-b193-4445-aab1-a654ad77cd79",
      "type": "accounts",
      "attributes": {
        "master": false,
        "currencyCode": "EUR",
        "label": "Sub-account Callum Abbott",
        "bankReference": "BDR0812434002530431",
        "balance": "8.44",
        "totalBalance": "8.44",
        "bankWithdrawalAvailable": true,
        "bankDepositAvailable": true,
        "transferAvailable": true,
        "currencyType": "fiat"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        },
        "txnBankCredentials": {
          "data": [
            {
              "type": "txnBankCredential",
              "id": "3808e047-3479-4ba9-88dc-31729b4666d5"
            }
          ]
        }
      }
    }
  ],
  "included": [
    {
      "id": "3808e047-3479-4ba9-88dc-31729b4666d5",
      "type": "txnBankCredential",
      "attributes": {
        "currencyCode": "EUR",
        "beneficiaryName": "Acme Commerce Ltd",
        "iban": "DE89370400440532013000",
        "bic": "COBADEFFXXX",
        "bankName": "Commerzbank",
        "bankAddress": "Kaiserplatz, 60311 Frankfurt am Main, Germany"
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 5,
    "total": 39
  },
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}

**Response Body**

| Name                                                            | Type    | Description                                                                                                                        |
| --------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `data[].id`                                                     | string  | Account ID.                                                                                                                        |
| `data[].type`                                                   | string  | Entity type returned. Always `accounts`.                                                                                           |
| `data[].attributes`                                             | object  | Account attributes.                                                                                                                |
| `data[].attributes.master`                                      | boolean | If `true`, the account is a master account. If `false`, the account is a subaccount.                                               |
| `data[].attributes.currencyCode`                                | string  | Account currency code. See [Supported currencies](/api-basics/supported-currencies).                                               |
| `data[].attributes.currencyType`                                | string  | Currency type. Either `fiat` or `crypto`.                                                                                          |
| `data[].attributes.label`                                       | string  | Account label. Master accounts use `master`. Subaccounts use a user-defined label.                                                 |
| `data[].attributes.bankReference`                               | string  | Unique bank deposit reference (when applicable). Example: `BDR6421088115176062`.                                                   |
| `data[].attributes.balance`                                     | string  | Account balance. Returned as a string for decimal precision.                                                                       |
| `data[].attributes.totalBalance`                                | string  | For master accounts only. Total balance across the master account and its subaccounts.                                             |
| `data[].attributes.bankWithdrawalAvailable`                     | boolean | If `true`, bank withdrawals can be initiated from this account. If `false`, they are restricted.                                   |
| `data[].attributes.bankDepositAvailable`                        | boolean | If `true`, bank deposits can be made to this account. If `false`, they are restricted.                                             |
| `data[].attributes.transferAvailable`                           | boolean | If `true`, transfers between this account and other accounts are allowed. If `false`, they are restricted.                         |
| `data[].relationships.txnBankCredentials.data[].type`           | string  | Entity type of a linked bank credential. Always `txnBankCredential`.                                                               |
| `data[].relationships.txnBankCredentials.data[].id`             | string  | ID of a linked bank credential, expanded under `included`. The array is populated for fiat accounts and empty for crypto accounts. |
| `included[].type(txnBankCredential).attributes`                 | object  | Bank deposit credentials for a fiat account. Use these details to fund the account by bank transfer.                               |
| `included[].type(txnBankCredential).attributes.currencyCode`    | string  | Currency of the bank credential.                                                                                                   |
| `included[].type(txnBankCredential).attributes.beneficiaryName` | string  | Name of the beneficiary on the bank account.                                                                                       |
| `included[].type(txnBankCredential).attributes.iban`            | string  | Beneficiary IBAN.                                                                                                                  |
| `included[].type(txnBankCredential).attributes.bic`             | string  | Beneficiary bank BIC/SWIFT code.                                                                                                   |
| `included[].type(txnBankCredential).attributes.bankName`        | string  | Name of the beneficiary's bank.                                                                                                    |
| `included[].type(txnBankCredential).attributes.bankAddress`     | string  | Address of the beneficiary's bank.                                                                                                 |
| `meta.page`                                                     | number  | Current page number.                                                                                                               |
| `meta.per_page`                                                 | number  | Page size used for the response.                                                                                                   |
| `meta.total`                                                    | number  | Total number of accounts available.                                                                                                |
| `jsonapi.version`                                               | string  | JSON:API version.                                                                                                                  |

### Errors

* `401 Unauthorized` if the API key is missing or invalid. See [Authenticating the API](/api-basics/authenticating-the-api).
* `429 Too Many Requests` if you hit rate limits. See [Rate limits](/api-basics/rate-limits).

### Related endpoints

* [Read account](/accounts/reading-account)
* [Accounts concept](/accounts/accounts-concept)


# Reading account

<mark style="color:green;">`GET`</mark> `/api/public/v1/accounts/:id`

Returns a single account by ID, including its balance and the networks available for receiving deposits.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**Path Parameters**

| Name | Type   | Description |
| ---- | ------ | ----------- |
| id   | string | Account ID. |

**Response**

{% tabs %}
{% tab title="HTTP 200 (crypto account)" %}

```json
{
  "data": {
    "id": "e289de2b-37bd-4eff-b832-f754c31a2d95",
    "type": "accounts",
    "attributes": {
      "master": true,
      "currencyCode": "USDT",
      "label": "master",
      "bankReference": "BDR4180381621673581",
      "balance": "344086.455299",
      "totalBalance": "344219.499753",
      "bankWithdrawalAvailable": false,
      "bankDepositAvailable": false,
      "transferAvailable": true,
      "currencyType": "crypto"
    },
    "relationships": {
      "company": {
        "meta": {
          "included": false
        }
      },
      "networks": {
        "data": [
          {
            "type": "network",
            "id": "2cfea86d-f334-4bd2-99ac-e74281520c95"
          },
          {
            "type": "network",
            "id": "8ededca3-a1cd-4b46-8c3a-14915f706ab2"
          },
          {
            "type": "network",
            "id": "490f02d4-b09a-4486-a469-d10c2ea43638"
          },
          {
            "type": "network",
            "id": "927d49d4-f4b2-48dc-876d-ac375337ec2a"
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": "2cfea86d-f334-4bd2-99ac-e74281520c95",
      "type": "network",
      "attributes": {
        "currencyCode": "USDT",
        "name": "Ethereum (ERC20)",
        "code": "hterc6dp"
      }
    },
    {
      "id": "8ededca3-a1cd-4b46-8c3a-14915f706ab2",
      "type": "network",
      "attributes": {
        "currencyCode": "USDT",
        "name": "Tron (TRC20)",
        "code": "ttrx:usdt"
      }
    },
    {
      "id": "490f02d4-b09a-4486-a469-d10c2ea43638",
      "type": "network",
      "attributes": {
        "currencyCode": "USDT",
        "name": "Polygon (ERC20)",
        "code": "tpolygon:usdt"
      }
    },
    {
      "id": "927d49d4-f4b2-48dc-876d-ac375337ec2a",
      "type": "network",
      "attributes": {
        "currencyCode": "USDT",
        "name": "Binance Smart Chain (BEP20)",
        "code": "tbsc:usdt"
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}

{% tab title="HTTP 200 (fiat account)" %}

```json
{
  "data": {
    "id": "1b67dc40-4fd9-4318-9329-c9afb3ed8a15",
    "type": "accounts",
    "attributes": {
      "master": false,
      "currencyCode": "EUR",
      "label": "EUR_1",
      "bankReference": "BDR0154632342411086",
      "balance": "120.50",
      "totalBalance": "120.50",
      "bankWithdrawalAvailable": true,
      "bankDepositAvailable": true,
      "transferAvailable": true,
      "currencyType": "fiat"
    },
    "relationships": {
      "company": {
        "meta": {
          "included": false
        }
      },
      "networks": {
        "data": []
      },
      "txnBankCredentials": {
        "data": [
          {
            "type": "txnBankCredential",
            "id": "3808e047-3479-4ba9-88dc-31729b4666d5"
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": "3808e047-3479-4ba9-88dc-31729b4666d5",
      "type": "txnBankCredential",
      "attributes": {
        "currencyCode": "EUR",
        "beneficiaryName": "Acme Commerce Ltd",
        "iban": "DE89370400440532013000",
        "bic": "COBADEFFXXX",
        "bankName": "Commerzbank",
        "bankAddress": "Kaiserplatz, 60311 Frankfurt am Main, Germany"
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}

**Response Body**

<table><thead><tr><th>Name</th><th width="102">Type</th><th>Description</th></tr></thead><tbody><tr><td>data.id</td><td>string</td><td>Account ID.</td></tr><tr><td>data.type</td><td>string</td><td>Entity type returned. Always <code>accounts</code>.</td></tr><tr><td>data.attributes</td><td>object</td><td>A set of account attributes.</td></tr><tr><td>data.attributes.master</td><td>boolean</td><td>If <code>true</code>, account is master. If <code>false</code>, account is subaccount.</td></tr><tr><td>data.attributes.bankReference</td><td>string</td><td>Unique bank deposit reference for each account and subaccount. Example: <code>BDR6421088115176062</code>.</td></tr><tr><td>data.attributes.label</td><td>string</td><td>Account label.</td></tr><tr><td>data.attributes.currencyCode</td><td>string</td><td>Account currency code. Refer to the list of <a href="/pages/SA7q0b6VrvXO3W09TQfS">supported currencies</a>.</td></tr><tr><td>data.attributes.balance</td><td>string</td><td>Account balance. Returned as a string for decimal precision.</td></tr><tr><td>data.attributes.totalBalance</td><td>string</td><td>For master accounts only. Total balance across the master account and its subaccounts.</td></tr><tr><td>data.attributes.bankWithdrawalAvailable</td><td>boolean</td><td>If <code>true</code>, bank withdrawals can be initiated from this account. If <code>false</code>, they are restricted.</td></tr><tr><td>data.attributes.bankDepositAvailable</td><td>boolean</td><td>If <code>true</code>, the account can receive bank deposits.</td></tr><tr><td>data.attributes.transferAvailable</td><td>boolean</td><td>If <code>true</code>, the account can send and receive internal transfers.</td></tr><tr><td>data.attributes.currencyType</td><td>string</td><td>Account currency type. Either <code>fiat</code> or <code>crypto</code>.</td></tr><tr><td>data.relationships.txnBankCredentials.data[].type</td><td>string</td><td>Entity type of a linked bank credential. Always <code>txnBankCredential</code>.</td></tr><tr><td>data.relationships.txnBankCredentials.data[].id</td><td>string</td><td>ID of a linked bank credential, expanded under <code>included</code>. Populated for fiat accounts and empty for crypto accounts.</td></tr><tr><td>included[].type(network).id</td><td>string</td><td>Network ID. Use this as <code>network_id</code> when <a href="/pages/GuYa9jkGwNxdQ4yp9iA0">creating an account address</a>. Present for crypto accounts.</td></tr><tr><td>included[].type(network).attributes.currencyCode</td><td>string</td><td>Network currency code. Useful for display to end users.</td></tr><tr><td>included[].type(network).attributes.name</td><td>string</td><td>Human-readable network name, e.g. <code>Tron (TRC20)</code>. Useful for display to end users.</td></tr><tr><td>included[].type(network).attributes.code</td><td>string</td><td>Network code, e.g. <code>ttrx:usdt</code>. See <a href="/pages/SA7q0b6VrvXO3W09TQfS">Supported currencies</a>.</td></tr><tr><td>included[].type(txnBankCredential).attributes</td><td>object</td><td>Bank deposit credentials for a fiat account. Use these details to fund the account by bank transfer.</td></tr><tr><td>included[].type(txnBankCredential).attributes.currencyCode</td><td>string</td><td>Currency of the bank credential.</td></tr><tr><td>included[].type(txnBankCredential).attributes.beneficiaryName</td><td>string</td><td>Name of the beneficiary on the bank account.</td></tr><tr><td>included[].type(txnBankCredential).attributes.iban</td><td>string</td><td>Beneficiary IBAN.</td></tr><tr><td>included[].type(txnBankCredential).attributes.bic</td><td>string</td><td>Beneficiary bank BIC/SWIFT code.</td></tr><tr><td>included[].type(txnBankCredential).attributes.bankName</td><td>string</td><td>Name of the beneficiary's bank.</td></tr><tr><td>included[].type(txnBankCredential).attributes.bankAddress</td><td>string</td><td>Address of the beneficiary's bank.</td></tr></tbody></table>


# Creating subaccount

<mark style="color:green;">`POST`</mark> `/api/public/v1/accounts/:account_id/subaccounts`

Creates a subaccount under the specified master account. The subaccount inherits the master account's currency.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**Path Parameters**

| Name        | Type   | Description        |
| ----------- | ------ | ------------------ |
| account\_id | string | Master account ID. |

**Body**

<table><thead><tr><th>Name</th><th width="116">Type</th><th>Description</th></tr></thead><tbody><tr><td>data</td><td>object</td><td>Request data object.</td></tr><tr><td>data.type</td><td>string</td><td>Resource type. Always <code>accounts</code>.</td></tr><tr><td>data.attributes</td><td>object</td><td>Subaccount attributes.</td></tr><tr><td>data.attributes.label</td><td>string</td><td>Subaccount label. Use a human-readable value so you can recognize it later.</td></tr></tbody></table>

**Request JSON**

```json
{
  "data": {
    "type": "accounts",
    "attributes": {
      "label": "Sub-account Adam Goodman"
    }
  }
}
```

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": {
    "id": "dc9c1c6e-3fa6-4fce-8c5f-714dfcecf3ee",
    "type": "accounts",
    "attributes": {
      "master": false,
      "currencyCode": "USDT",
      "label": "Sub-account Adam Goodman",
      "bankReference": "BDR7013714686525702",
      "balance": "0.000000",
      "totalBalance": "0.000000",
      "bankWithdrawalAvailable": false,
      "currencyType": "crypto"
    },
    "relationships": {
      "company": {
        "meta": {
          "included": false
        }
      },
      "networks": {
        "meta": {
          "included": false
        }
      }
    }
  },
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}

{% tab title="HTTP 404" %}

```json
{
  "errors": [
    {
      "status": 404,
      "title": "Record not found",
      "code": "account_not_found",
      "detail": "Account not found"
    }
  ]
}
```

The master account in the path does not exist.
{% endtab %}
{% endtabs %}

**Response Body**

| Name                                      | Type    | Description                                                     |
| ----------------------------------------- | ------- | --------------------------------------------------------------- |
| `data.id`                                 | string  | Subaccount ID.                                                  |
| `data.type`                               | string  | Entity type returned. Always `accounts`.                        |
| `data.attributes.master`                  | boolean | Always `false` for a subaccount.                                |
| `data.attributes.currencyCode`            | string  | Currency code, inherited from the master account.               |
| `data.attributes.label`                   | string  | Subaccount label, as set in the request.                        |
| `data.attributes.bankReference`           | string  | Unique bank deposit reference assigned to the subaccount.       |
| `data.attributes.balance`                 | string  | Subaccount balance. A new subaccount starts at zero.            |
| `data.attributes.totalBalance`            | string  | Matches `balance` for subaccounts.                              |
| `data.attributes.bankWithdrawalAvailable` | boolean | If `true`, bank withdrawals can be initiated from this account. |
| `data.attributes.currencyType`            | string  | Currency type. Either `fiat` or `crypto`.                       |


# Listing subaccounts for master account

<mark style="color:green;">`GET`</mark> `/api/public/v1/accounts/:account_id/subaccounts`

Returns all subaccounts of a master account, including their current balances. Results are paginated.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**Path Parameters**

| Name        | Type   | Description        |
| ----------- | ------ | ------------------ |
| account\_id | string | Master account ID. |

**URL Parameters**

<table><thead><tr><th width="183">Name</th><th width="92">Type</th><th>Description</th></tr></thead><tbody><tr><td>per_page</td><td>number</td><td>Number of accounts per page to return.</td></tr><tr><td>page</td><td>number</td><td>Page for which you want to return accounts.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": [
    {
      "id": "dc9c1c6e-3fa6-4fce-8c5f-714dfcecf3ee",
      "type": "accounts",
      "attributes": {
        "master": false,
        "currencyCode": "USDT",
        "label": "Sub-account Adam Goodman",
        "bankReference": "BDR7013714686525702",
        "balance": "0.000000",
        "totalBalance": "0.000000",
        "bankWithdrawalAvailable": false,
        "currencyType": "crypto"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "89a401e2-bd3b-4a87-95b0-6ff99c0a3b7c",
      "type": "accounts",
      "attributes": {
        "master": false,
        "currencyCode": "USDT",
        "label": "5",
        "bankReference": "BDR4357564686428100",
        "balance": "0.000000",
        "totalBalance": "0.000000",
        "bankWithdrawalAvailable": false,
        "currencyType": "crypto"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "468a0e31-d9e5-4ad8-86aa-6c4806d40a2d",
      "type": "accounts",
      "attributes": {
        "master": false,
        "currencyCode": "USDT",
        "label": "USDT_4",
        "bankReference": "BDR8606155657480464",
        "balance": "12.392985",
        "totalBalance": "12.392985",
        "bankWithdrawalAvailable": false,
        "currencyType": "crypto"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "c20dec56-10ce-49e0-ad00-916579f0c04a",
      "type": "accounts",
      "attributes": {
        "master": false,
        "currencyCode": "USDT",
        "label": "USDT_3",
        "bankReference": "BDR3865252360837137",
        "balance": "10.301300",
        "totalBalance": "10.301300",
        "bankWithdrawalAvailable": false,
        "currencyType": "crypto"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "2df68c92-b9dd-4ff4-b7f2-5aeb381bf6fc",
      "type": "accounts",
      "attributes": {
        "master": false,
        "currencyCode": "USDT",
        "label": "USDT_2",
        "bankReference": "BDR0042354445442825",
        "balance": "31.434196",
        "totalBalance": "31.434196",
        "bankWithdrawalAvailable": false,
        "currencyType": "crypto"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "fbae9123-59bb-49db-bc6b-0f766c189494",
      "type": "accounts",
      "attributes": {
        "master": false,
        "currencyCode": "USDT",
        "label": "USDT_1",
        "bankReference": "BDR4654328482173537",
        "balance": "78.915973",
        "totalBalance": "78.915973",
        "bankWithdrawalAvailable": false,
        "currencyType": "crypto"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        }
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total": 6
  },
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}

**Response Body**

<table><thead><tr><th>Name</th><th width="102">Type</th><th>Description</th></tr></thead><tbody><tr><td>data[].id</td><td>string</td><td>Account ID.</td></tr><tr><td>data[].type</td><td>string</td><td>Entity type returned. Always <code>accounts</code>.</td></tr><tr><td>data[].attributes</td><td>object</td><td>A set of account attributes.</td></tr><tr><td>data[].attributes.master</td><td>boolean</td><td>If <code>true</code>, account is master. If <code>false</code>, account is subaccount.</td></tr><tr><td>data[].attributes.bankReference</td><td>string</td><td>Unique bank deposit reference for each account and subaccount. Example: <code>BDR6421088115176062</code>.</td></tr><tr><td>data[].attributes.currencyCode</td><td>string</td><td>Account currency code. Refer to the list of <a href="/pages/SA7q0b6VrvXO3W09TQfS">supported currencies</a>.</td></tr><tr><td>data[].attributes.balance</td><td>string</td><td>Account balance.</td></tr><tr><td>data[].attributes.totalBalance</td><td>string</td><td>Total balance across the master account and all subaccounts (applicable to master accounts).</td></tr><tr><td>data[].attributes.bankWithdrawalAvailable</td><td>boolean</td><td>If <code>true</code>, bank withdrawals can be initiated from this account. If <code>false</code>, they are restricted.</td></tr><tr><td>data[].attributes.currencyType</td><td>string</td><td>Account currency type. Can be either <code>fiat</code> or <code>crypto</code>.</td></tr><tr><td>data[].attributes.label</td><td>string</td><td>Account label. Master accounts use <code>master</code>. Subaccounts use a user-defined label.</td></tr><tr><td>data[].attributes.bankDepositAvailable</td><td>boolean</td><td>If <code>true</code>, bank deposits can be made to this account. If <code>false</code>, they are restricted.</td></tr><tr><td>data[].attributes.transferAvailable</td><td>boolean</td><td>If <code>true</code>, transfers between this account and other accounts are allowed. If <code>false</code>, they are restricted.</td></tr></tbody></table>


# Creating account address

<mark style="color:green;">`POST`</mark> `/api/public/v1/accounts/:id/addresses`

Creates a receiving address on the given account for the specified network.

{% hint style="info" %}
This request is asynchronous. The address is registered immediately, but its `value` is generated shortly afterwards — the create response returns `value: null`. Poll [Listing account addresses](/accounts/listing-account-addresses) to retrieve the final address value.
{% endhint %}

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**Path Parameters**

| Name | Type   | Description |
| ---- | ------ | ----------- |
| id   | string | Account ID. |

**Body**

<table><thead><tr><th>Name</th><th width="116">Type</th><th>Description</th></tr></thead><tbody><tr><td>data</td><td>object</td><td>Request data object.</td></tr><tr><td>data.type</td><td>string</td><td>Resource type. Always <code>addresses</code>.</td></tr><tr><td>data.attributes</td><td>object</td><td>Address attributes.</td></tr><tr><td>data.attributes.network_id</td><td>string</td><td>ID of the network to generate the address on. Must belong to the account's currency. Read the account to list its available networks — see <a href="/pages/FavdJFtLKkNm8qh3HLsv">Reading account</a>.</td></tr><tr><td>data.attributes.label</td><td>string</td><td>Address label. Use any value that helps you recognize the address later.</td></tr></tbody></table>

**Request JSON**

```json
{
  "data": {
    "type": "addresses",
    "attributes": {
      "network_id": "string",
      "label": "string"
    }
  }
}
```

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": {
    "id": "0a37e656-fdca-4afb-b78e-992a38279c9d",
    "type": "addresses",
    "attributes": {
      "label": "New Label",
      "value": null,
      "createdAt": "2025-05-29T18:15:35.492Z"
    },
    "relationships": {
      "account": {
        "meta": {
          "included": false
        }
      },
      "network": {
        "meta": {
          "included": false
        }
      }
    }
  },
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "Invalid attribute",
      "code": "address_invalid",
      "detail": "Network does not match account currency",
      "source": {
        "pointer": "/data/attributes/networkId"
      }
    }
  ]
}
```

{% endtab %}

{% tab title="HTTP 404" %}

```json
{
  "errors": [
    {
      "status": 404,
      "title": "Record not found",
      "code": "network_not_found",
      "detail": "Network not found"
    }
  ]
}
```

The `network_id` does not match a known network.
{% endtab %}
{% endtabs %}

**Response Body**

| Name                         | Type   | Description                                                                                                                                               |
| ---------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data.id`                    | string | Address ID.                                                                                                                                               |
| `data.type`                  | string | Entity type returned. Always `addresses`.                                                                                                                 |
| `data.attributes.label`      | string | Address label, as set in the request.                                                                                                                     |
| `data.attributes.value`      | string | The address string. `null` in this response — generated asynchronously. Retrieve it via [Listing account addresses](/accounts/listing-account-addresses). |
| `data.attributes.createdAt`  | string | ISO 8601 timestamp of when the address was created.                                                                                                       |
| `data.relationships.account` | object | The account the address belongs to.                                                                                                                       |
| `data.relationships.network` | object | The network the address was generated on.                                                                                                                 |


# Listing account addresses

<mark style="color:green;">`GET`</mark> `/api/public/v1/accounts/:id/addresses`

Returns the receiving addresses on the given account, including the address `value` once it has been generated. Results are paginated.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**Path Parameters**

| Name | Type   | Description |
| ---- | ------ | ----------- |
| id   | string | Account ID. |

**URL Parameters**

| Name        | Type   | Description                                                                   |
| ----------- | ------ | ----------------------------------------------------------------------------- |
| order       | string | Order in which the list of addresses should be returned. Can be `created_at`. |
| order\_type | string | Order type. Can be either `asc` or `desc`.                                    |
| page        | number | Page for which you want to return addresses.                                  |
| per\_page   | number | Number of addresses per page to return.                                       |

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": [
    {
      "id": "138928d2-769d-478f-9508-90b7e4f8942a",
      "type": "addresses",
      "attributes": {
        "label": "Apr 11",
        "value": "TUbHdtAyfeiWTJPzF12gcBnpLtmLo3qgkS",
        "createdAt": "2025-04-11T07:19:09.729Z"
      },
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "network": {
          "data": {
            "type": "network",
            "id": "8ededca3-a1cd-4b46-8c3a-14915f706ab2"
          }
        }
      }
    }
  ],
  "included": [
    {
      "id": "8ededca3-a1cd-4b46-8c3a-14915f706ab2",
      "type": "network",
      "attributes": {
        "currencyCode": "USDT",
        "name": "Tron (TRC20)",
        "code": "ttrx:usdt"
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 1,
    "total": 22
  },
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}

**Response Body**

| Name                                 | Type   | Description                                                                                                                                 |
| ------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `data[].id`                          | string | Address ID.                                                                                                                                 |
| `data[].type`                        | string | Entity type returned. Always `addresses`.                                                                                                   |
| `data[].attributes.label`            | string | Address label, as set at creation.                                                                                                          |
| `data[].attributes.value`            | string | The address string. `null` while the address is still being generated — see [Creating account address](/accounts/creating-account-address). |
| `data[].attributes.createdAt`        | string | ISO 8601 timestamp of when the address was created.                                                                                         |
| `data[].relationships.network`       | object | The network the address belongs to. The full network entity is returned in `included[]`.                                                    |
| `included[].id`                      | string | Network ID.                                                                                                                                 |
| `included[].type`                    | string | Entity type. Always `network`.                                                                                                              |
| `included[].attributes.currencyCode` | string | Network currency code.                                                                                                                      |
| `included[].attributes.name`         | string | Human-readable network name, e.g. `Tron (TRC20)`.                                                                                           |
| `included[].attributes.code`         | string | Network code, e.g. `ttrx:usdt`. See [Supported currencies](/api-basics/supported-currencies).                                               |
| `meta.page`                          | number | Current page number.                                                                                                                        |
| `meta.per_page`                      | number | Page size used for the response.                                                                                                            |
| `meta.total`                         | number | Total number of addresses on the account.                                                                                                   |


# Listing account transactions

<mark style="color:green;">`GET`</mark> `/api/public/v1/accounts/:account_id/transactions`

Returns the transaction history for a single account. Results are paginated and can be filtered by date and ordered.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**Path Parameters**

| Name        | Type   | Description |
| ----------- | ------ | ----------- |
| account\_id | string | Account ID. |

**URL Parameters**

<table><thead><tr><th width="183">Name</th><th width="92">Type</th><th>Description</th></tr></thead><tbody><tr><td>order</td><td>string</td><td>Order in which the list of transactions should be returned. Can be either <code>created_at</code>, <code>amount</code> or <code>balance</code>.</td></tr><tr><td>order_type</td><td>string</td><td>Order type. Can be either <code>asc</code> or <code>desc</code>.</td></tr><tr><td>per_page</td><td>number</td><td>Number of transactions per page to return.</td></tr><tr><td>page</td><td>number</td><td>Page for which you want to return transactions.</td></tr><tr><td>created_at_from</td><td>string</td><td>Date and time filter. Supports timestamps in ISO 8601 format, e.g. <code>2024-06-18T15:49:02.031Z</code>.</td></tr><tr><td>created_at_to</td><td>string</td><td>Date and time filter. Supports timestamps in ISO 8601 format, e.g. <code>2024-06-18T15:49:02.031Z</code>.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": [
    {
      "id": "28e51afe-a9f9-43f1-9204-cc90a7deb4f2",
      "type": "transactions",
      "attributes": {
        "createdAt": "2024-06-18T15:49:02.031Z",
        "simplifiedState": "completed",
        "transactionType": "CoinTransaction",
        "amount": "0.00010000",
        "balance": "0.20087774"
      },
      "relationships": {
        "account": {
          "data": {
            "type": "accounts",
            "id": "5850abb7-0a60-4041-800c-1d43b4dcf4d6"
          }
        }
      }
    }
  ],
  "included": [
    {
      "id": "5850abb7-0a60-4041-800c-1d43b4dcf4d6",
      "type": "accounts",
      "attributes": {
        "currencyCode": "BTC",
        "balance": "0.20087774",
        "currencyType": "crypto"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        }
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 1,
    "total": 78
  },
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}

**Response Body**

<table><thead><tr><th>Name</th><th width="99">Type</th><th>Description</th></tr></thead><tbody><tr><td>data[].id</td><td>string</td><td>Transaction ID.</td></tr><tr><td>data[].type</td><td>string</td><td>Entity type returned. Always <code>transactions</code>.</td></tr><tr><td>data[].attributes</td><td>object</td><td>A set of transaction attributes.</td></tr><tr><td>data[].attributes.createdAt</td><td>string</td><td>Transaction creation timestamp in UTC+0. Refer to the <a href="/pages/H7xWDJMZukOei8CS8tUW">Date and time format</a> page.</td></tr><tr><td>data[].attributes.simplifiedState</td><td>string</td><td>Transaction status.</td></tr><tr><td>data[].attributes.transactionType</td><td>string</td><td>Transaction type. Can be either <code>ExchangeTransaction</code>, <code>CoinTransaction</code> or <code>ManualTransaction</code>.</td></tr><tr><td>data[].attributes.amount</td><td>string</td><td>Transaction amount.</td></tr><tr><td>data[].attributes.balance</td><td>string</td><td>Account balance immediately after Txn processed this transaction.</td></tr><tr><td>data[].attributes.currency</td><td>string</td><td>Currency code of the transaction. Matches the account currency.</td></tr><tr><td>data[].attributes.reference</td><td>string</td><td>Reference associated with the transaction.</td></tr><tr><td>data[].attributes.accountId</td><td>string</td><td>ID of the account the transaction belongs to. Same value as <code>data[].relationships.account.id</code>.</td></tr><tr><td>data[].relationships.account.type</td><td>string</td><td>Entity type of the related account. Always <code>accounts</code>.</td></tr><tr><td>data[].relationships.account.id</td><td>string</td><td>ID of the account the transaction belongs to.</td></tr><tr><td>meta.page</td><td>number</td><td>Current page number. <code>null</code> when no <code>page</code> parameter is supplied.</td></tr><tr><td>meta.per_page</td><td>number</td><td>Page size used for the response.</td></tr><tr><td>meta.total</td><td>number</td><td>Total number of transactions matching the query.</td></tr></tbody></table>


# Reading account transaction

<mark style="color:green;">`GET`</mark> `/api/public/v1/accounts/:account_id/transactions/:transaction_id/details`

Returns the details of a single account transaction. The `data.type` and the attributes returned depend on the underlying transaction — for example, a `coinDeposits` transaction includes the on-chain hash and risk score, along with its network and address in `included[]`.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**Path Parameters**

| Name            | Type   | Description     |
| --------------- | ------ | --------------- |
| account\_id     | string | Account ID.     |
| transaction\_id | string | Transaction ID. |

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": {
    "id": "28e51afe-a9f9-43f1-9204-cc90a7deb4f2",
    "type": "coinDeposits",
    "attributes": {
      "txHash": "28b056c50e4725205a72fa975fdf6b1fb4ccdd7636995396cb6469fe858e2732",
      "currencyCode": "BTC",
      "createdAt": "2024-06-18T13:37:50.777Z",
      "amount": "0.00010000",
      "riskScore": "10.0"
    },
    "relationships": {
      "network": {
        "data": {
          "type": "network",
          "id": "a1d019ea-26f8-457b-931e-efb06a14ce59"
        }
      },
      "address": {
        "data": {
          "type": "addresses",
          "id": "cf57fd3d-a3de-42b2-bf1b-44fb2280940e"
        }
      }
    }
  },
  "included": [
    {
      "id": "a1d019ea-26f8-457b-931e-efb06a14ce59",
      "type": "network",
      "attributes": {
        "currencyCode": "BTC",
        "name": "BTC Testnet"
      }
    },
    {
      "id": "cf57fd3d-a3de-42b2-bf1b-44fb2280940e",
      "type": "addresses",
      "attributes": {
        "label": "Jun 18 2nd",
        "value": "2N8uzZM46V3u5LQRixzTwJ5wguh53Vthb4a",
        "createdAt": "2024-06-18T12:04:49.325Z"
      },
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "network": {
          "meta": {
            "included": false
          }
        }
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}

**Response Body**

The example above shows a `coinDeposits` transaction. The attributes returned vary by transaction type.

<table><thead><tr><th width="228">Name</th><th width="109">Type</th><th>Description</th></tr></thead><tbody><tr><td>data.id</td><td>string</td><td>Transaction ID.</td></tr><tr><td>data.type</td><td>string</td><td>Transaction type. One of <code>exchangeTransactions</code>, <code>coinDeposits</code>, or <code>manualTransactions</code>.</td></tr><tr><td>data.attributes.txHash</td><td>string</td><td>On-chain transaction hash. Present for <code>coinDeposits</code>.</td></tr><tr><td>data.attributes.currencyCode</td><td>string</td><td>Transaction currency code.</td></tr><tr><td>data.attributes.createdAt</td><td>string</td><td>ISO 8601 timestamp of when the transaction was created.</td></tr><tr><td>data.attributes.amount</td><td>string</td><td>Transaction amount.</td></tr><tr><td>data.attributes.riskScore</td><td>string</td><td>Compliance risk score assigned to the deposit, where higher is riskier. Present for <code>coinDeposits</code>.</td></tr><tr><td>data.relationships.network</td><td>object</td><td>The network the deposit arrived on. Full entity in <code>included[]</code>.</td></tr><tr><td>data.relationships.address</td><td>object</td><td>The receiving address the deposit was sent to. Full entity in <code>included[]</code>.</td></tr><tr><td>included[].type(network)</td><td>object</td><td>Network entity: <code>currencyCode</code> and <code>name</code>.</td></tr><tr><td>included[].type(addresses)</td><td>object</td><td>Address entity: <code>label</code>, <code>value</code>, and <code>createdAt</code>.</td></tr></tbody></table>


# Creating account transfer

<mark style="color:green;">`POST`</mark> `/api/public/v1/transfers`

Creates an instant transfer between two of your accounts in the same currency — between a master account and a subaccount, or between two subaccounts. The transfer produces two account transactions: a debit on the source account and a credit on the destination account.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**Body**

<table><thead><tr><th>Name</th><th width="116">Type</th><th>Description</th></tr></thead><tbody><tr><td>data</td><td>object</td><td>Request data object.</td></tr><tr><td>data.type</td><td>string</td><td>Resource type. Always <code>transfers</code>.</td></tr><tr><td>data.attributes</td><td>object</td><td>Transfer attributes.</td></tr><tr><td>data.attributes.from_account</td><td>string</td><td>ID of the account to debit.</td></tr><tr><td>data.attributes.to_account</td><td>string</td><td>ID of the account to credit. Must hold the same currency as the source account.</td></tr><tr><td>data.attributes.amount</td><td>number</td><td>Amount to transfer.</td></tr><tr><td>data.attributes.currency</td><td>string</td><td>Transfer currency. Must match the currency of both accounts.</td></tr><tr><td>data.attributes.reference</td><td>string</td><td>Your unique reference for this transfer. Included in downloadable CSV transaction reports.</td></tr></tbody></table>

**Request JSON**

```json
{
  "data": {
    "type": "transfers",
    "attributes": {
      "from_account": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "to_account": "dd5016e1-43bb-4be5-b6d6-79e8d0f662b1",
      "amount": 10,
      "currency": "EUR",
      "reference": "c9807056-88da-409e-b628-732adbe76be5"
    }
  }
}
```

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": {
    "id": "5cdf75bf-7f9e-410f-a4a4-841667f57c9f",
    "type": "accountTransfers",
    "attributes": {
      "reference": "c9807056-88da-409e-b628-732adbe76be5"
    },
    "relationships": {
      "accountTransactions": {
        "data": [
          {
            "type": "accountTransactions",
            "id": "e55508e2-81b3-4e0f-b49c-380abc9dec91"
          },
          {
            "type": "accountTransactions",
            "id": "179a4edb-0af4-405d-a006-a8588140bb85"
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": "e55508e2-81b3-4e0f-b49c-380abc9dec91",
      "type": "accountTransactions",
      "attributes": {
        "createdAt": "2026-01-09T10:38:24.351Z",
        "amount": "-10.00"
      },
      "relationships": {
        "account": {
          "data": {
            "type": "accounts",
            "id": "13a85b45-8543-41c7-b963-394d4ea128ae"
          }
        },
        "accountTransfer": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "179a4edb-0af4-405d-a006-a8588140bb85",
      "type": "accountTransactions",
      "attributes": {
        "createdAt": "2026-01-09T10:38:24.395Z",
        "amount": "10.00"
      },
      "relationships": {
        "account": {
          "data": {
            "type": "accounts",
            "id": "dd5016e1-43bb-4be5-b6d6-79e8d0f662b1"
          }
        },
        "accountTransfer": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "type": "accounts",
      "attributes": {
        "master": true,
        "currencyCode": "EUR",
        "label": "master",
        "bankReference": "BDR6421088115176062",
        "balance": "38465.76",
        "totalBalance": "38687.80",
        "currencyType": "fiat"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "dd5016e1-43bb-4be5-b6d6-79e8d0f662b1",
      "type": "accounts",
      "attributes": {
        "master": false,
        "currencyCode": "EUR",
        "label": "EUR_1",
        "bankReference": "BDR4778763138567183",
        "balance": "90.54",
        "totalBalance": "90.54",
        "currencyType": "fiat"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        }
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "Insufficient balance",
      "code": "account_transfer_insufficient_balance",
      "detail": ""
    }
  ]
}
```

{% endtab %}

{% tab title="HTTP 404" %}

```json
{
  "errors": [
    {
      "status": 404,
      "title": "Record not found",
      "code": "account_not_found",
      "detail": "Account not found"
    }
  ]
}
```

Either the source or destination account does not exist.
{% endtab %}
{% endtabs %}

**Response Body**

| Name                                     | Type   | Description                                                                                                |
| ---------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------- |
| `data.id`                                | string | Transfer ID.                                                                                               |
| `data.type`                              | string | Entity type returned. Always `accountTransfers`.                                                           |
| `data.attributes.reference`              | string | The reference you supplied in the request.                                                                 |
| `data.relationships.accountTransactions` | array  | The two transactions created by the transfer — the debit and the credit. Full entities in `included[]`.    |
| `included[].type(accountTransactions)`   | object | A transaction leg: `createdAt` and `amount` (negative on the source account, positive on the destination). |
| `included[].type(accounts)`              | object | The source and destination accounts, with balances updated to reflect the transfer.                        |


# Listing crypto deposits

<mark style="color:green;">`GET`</mark> `/api/public/v1/transactions/coin_deposits`

Returns your crypto deposit transactions. Each entry pairs the account transaction (in `data`) with its on-chain details, network, and receiving address (in `included[]`). Results are paginated, filterable by date, and orderable.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**URL Parameters**

<table><thead><tr><th width="183">Name</th><th width="92">Type</th><th>Description</th></tr></thead><tbody><tr><td>order</td><td>string</td><td>Order in which the list of transactions should be returned. Can be <code>created_at</code>.</td></tr><tr><td>order_type</td><td>string</td><td>Order type. Can be either <code>asc</code> or <code>desc</code>.</td></tr><tr><td>per_page</td><td>number</td><td>Number of transactions per page to return.</td></tr><tr><td>page</td><td>number</td><td>Page for which you want to return transactions.</td></tr><tr><td>created_at_from</td><td>string</td><td>Date and time filter. Supports timestamps in ISO 8601 format, e.g. <code>2024-06-18T15:49:02.031Z</code>.</td></tr><tr><td>created_at_to</td><td>string</td><td>Date and time filter. Supports timestamps in ISO 8601 format, e.g. <code>2024-06-18T15:49:02.031Z</code>.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": [
    {
      "id": "d4c51c64-706f-4ede-8a2c-a5cca27e03bb",
      "type": "transactions",
      "attributes": {
        "createdAt": "2026-04-01T11:12:51.988Z",
        "simplifiedState": "completed",
        "transactionType": "CoinTransaction",
        "amount": "5.000000",
        "currency": "USDT",
        "balance": "10637424.361911",
        "reference": null,
        "accountId": "8140e530-4cd3-47e0-b813-9c473e9a2ea3"
      },
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "transactionDetails": {
          "data": {
            "type": "coinTransactions",
            "id": "d4c51c64-706f-4ede-8a2c-a5cca27e03bb"
          }
        },
        "author": {
          "meta": {
            "included": false
          }
        }
      }
    }
  ],
  "included": [
    {
      "id": "d4c51c64-706f-4ede-8a2c-a5cca27e03bb",
      "type": "coinTransactions",
      "attributes": {
        "txHash": "d47aad66318125d7fb5ce429fef66204f0797c7c71f1a6277ab0a53c66f1fe51",
        "currencyCode": "USDT",
        "createdAt": "2026-04-01T11:12:51.952Z",
        "state": "completed",
        "amount": "5.000000",
        "accountId": "8140e530-4cd3-47e0-b813-9c473e9a2ea3",
        "reference": null,
        "simplifiedState": "completed",
        "sourceAddresses": [
          "TTbGTMwUwA3mncLP7xqCZei1ekaNSgeAJe"
        ]
      },
      "relationships": {
        "network": {
          "data": {
            "type": "network",
            "id": "8ededca3-a1cd-4b46-8c3a-14915f706ab2"
          }
        },
        "address": {
          "data": {
            "type": "addresses",
            "id": "e92d7fb6-4cc0-4814-9a2b-8830ead8e833"
          }
        },
        "author": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "8ededca3-a1cd-4b46-8c3a-14915f706ab2",
      "type": "network",
      "attributes": {
        "currencyCode": "USDT",
        "name": "Tron (TRC20)",
        "code": "ttrx:usdt"
      }
    },
    {
      "id": "e92d7fb6-4cc0-4814-9a2b-8830ead8e833",
      "type": "addresses",
      "attributes": {
        "label": "My Wallet",
        "value": "TGRA6wC7T35dXwdGsSAevNmVJ8srGQKDeE",
        "createdAt": "2026-05-07T10:01:07.566Z"
      },
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "network": {
          "meta": {
            "included": false
          }
        }
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 10,
    "total": 1
  },
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}

**Response Body**

<table><thead><tr><th>Name</th><th width="99">Type</th><th>Description</th></tr></thead><tbody><tr><td>data[].id</td><td>string</td><td>Account transaction ID.</td></tr><tr><td>data[].type</td><td>string</td><td>Entity type returned. Always <code>transactions</code>.</td></tr><tr><td>data[].attributes</td><td>object</td><td>A set of account transaction attributes.</td></tr><tr><td>data[].attributes.createdAt</td><td>string</td><td>Account transaction creation timestamp in UTC+0. Refer to the <a href="/pages/H7xWDJMZukOei8CS8tUW">Date and time format</a> page.</td></tr><tr><td>data[].attributes.simplifiedState</td><td>string</td><td>Account transaction status. Can be one of: <code>pending</code>, <code>processing</code>, <code>completed</code>, <code>on_hold</code>, <code>rejected</code>, <code>cancelled</code>.</td></tr><tr><td>data[].attributes.transactionType</td><td>string</td><td>Account transaction type. Can only be <code>CoinTransaction</code>.</td></tr><tr><td>data[].attributes.amount</td><td>string</td><td>Account transaction amount.</td></tr><tr><td>data[].attributes.currency</td><td>string</td><td>Account transaction currency.</td></tr><tr><td>data[].attributes.balance</td><td>string</td><td>Account balance immediately after Txn processed this transaction.</td></tr><tr><td>data[].attributes.reference</td><td>string</td><td>Account transaction reference.</td></tr><tr><td>data[].attributes.accountId</td><td>string</td><td>ID of the account the transaction belongs to.</td></tr><tr><td>data[].relationships.transactionDetails</td><td>object</td><td>Link to the on-chain deposit details, returned as a <code>coinTransactions</code> entity in <code>included[]</code>.</td></tr><tr><td>included[].id</td><td>string</td><td>Transaction ID.</td></tr><tr><td>included[].type</td><td>string</td><td>Entity type returned. Always <code>coinTransactions</code>.</td></tr><tr><td>included[].attributes</td><td>object</td><td>A set of crypto transaction attributes.</td></tr><tr><td>included[].attributes.txHash</td><td>string</td><td>Crypto transaction hash.</td></tr><tr><td>included[].attributes.currencyCode</td><td>string</td><td>Crypto transaction currency.</td></tr><tr><td>included[].attributes.createdAt</td><td>string</td><td>Crypto transaction creation timestamp in UTC+0. Refer to the <a href="/pages/H7xWDJMZukOei8CS8tUW">Date and time format</a> page.</td></tr><tr><td>included[].attributes.state</td><td>string</td><td>Internal Txn state. Ignore this field — use <code>data[].attributes.simplifiedState</code> in your implementation.</td></tr><tr><td>included[].attributes.amount</td><td>string</td><td>Crypto transaction amount.</td></tr><tr><td>included[].attributes.accountId</td><td>string</td><td>Account ID which the crypto transaction belongs to.</td></tr><tr><td>included[].attributes.reference</td><td>string</td><td>Transaction reference.</td></tr><tr><td>included[].attributes.simplifiedState</td><td>string</td><td>Crypto transaction status. Can be one of: <code>pending</code>, <code>processing</code>, <code>completed</code>, <code>on_hold</code>, <code>rejected</code>, <code>cancelled</code>.</td></tr><tr><td>included[].attributes.sourceAddresses</td><td>array</td><td>Wallet address(es) the funds were sent from. Typically a single address; may contain multiple entries when the deposit arrived via a UTXO-based network (BTC, LTC, BCH, DOGE, etc.) and the sender’s wallet combined several inputs.</td></tr><tr><td>included[].type(network).attributes.name</td><td>string</td><td>Network name. E.g. <code>Tron (TRC20)</code>.</td></tr><tr><td>included[].type(network).attributes.currencyCode</td><td>string</td><td>Currency code for the network.</td></tr><tr><td>included[].type(network).attributes.code</td><td>string</td><td>Network code. E.g. <code>ttrx:usdt</code>. Refer to <a href="/pages/SA7q0b6VrvXO3W09TQfS">Supported currencies</a>.</td></tr><tr><td>included[].type(addresses).attributes.label</td><td>string</td><td>Address label.</td></tr><tr><td>included[].type(addresses).attributes.value</td><td>string</td><td>The wallet address the deposit was received at.</td></tr><tr><td>included[].type(addresses).attributes.createdAt</td><td>string</td><td>Timestamp when the address was created.</td></tr><tr><td>meta.page</td><td>number</td><td>Current page number.</td></tr><tr><td>meta.per_page</td><td>number</td><td>Page size used for the response.</td></tr><tr><td>meta.total</td><td>number</td><td>Total number of crypto deposits matching the query.</td></tr></tbody></table>


# Reading crypto deposit

<mark style="color:green;">`GET`</mark> `/api/public/v1/transactions/coin_deposits/:id`

Returns a single crypto deposit transaction by ID. The account transaction is returned in `data`, with its on-chain details, network, and receiving address in `included[]`.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**Path Parameters**

| Name | Type   | Description     |
| ---- | ------ | --------------- |
| id   | string | Transaction ID. |

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": {
    "id": "41a054ab-e95d-4ebc-91e2-fdf8a7d80ba2",
    "type": "transactions",
    "attributes": {
      "createdAt": "2026-04-03T09:46:50.510Z",
      "simplifiedState": "rejected",
      "transactionType": "CoinTransaction",
      "amount": "7.700000",
      "currency": "USDT",
      "balance": "10637559.798182",
      "reference": null,
      "accountId": "8140e530-4cd3-47e0-b813-9c473e9a2ea3"
    },
    "relationships": {
      "account": {
        "meta": {
          "included": false
        }
      },
      "transactionDetails": {
        "data": {
          "type": "coinTransactions",
          "id": "41a054ab-e95d-4ebc-91e2-fdf8a7d80ba2"
        }
      },
      "author": {
        "meta": {
          "included": false
        }
      }
    }
  },
  "included": [
    {
      "id": "41a054ab-e95d-4ebc-91e2-fdf8a7d80ba2",
      "type": "coinTransactions",
      "attributes": {
        "txHash": "48cd65dd45571ff2d24684b2b2819fd0b32e20069da9e98ab8bf14ef51d4cc3f",
        "currencyCode": "USDT",
        "createdAt": "2026-04-03T09:46:50.451Z",
        "state": "rejected",
        "amount": "7.700000",
        "accountId": "8140e530-4cd3-47e0-b813-9c473e9a2ea3",
        "reference": null,
        "simplifiedState": "rejected",
        "sourceAddresses": [
          "TTbGTMwUwA3mncLP7xqCZei1ekaNSgeAJe"
        ]
      },
      "relationships": {
        "network": {
          "data": {
            "type": "network",
            "id": "8ededca3-a1cd-4b46-8c3a-14915f706ab2"
          }
        },
        "address": {
          "data": {
            "type": "addresses",
            "id": "e92d7fb6-4cc0-4814-9a2b-8830ead8e833"
          }
        },
        "author": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "8ededca3-a1cd-4b46-8c3a-14915f706ab2",
      "type": "network",
      "attributes": {
        "currencyCode": "USDT",
        "name": "Tron (TRC20)",
        "code": "ttrx:usdt"
      }
    },
    {
      "id": "e92d7fb6-4cc0-4814-9a2b-8830ead8e833",
      "type": "addresses",
      "attributes": {
        "label": "My Wallet",
        "value": "TGRA6wC7T35dXwdGsSAevNmVJ8srGQKDeE",
        "createdAt": "2026-05-07T10:01:07.566Z"
      },
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "network": {
          "meta": {
            "included": false
          }
        }
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}

**Response Body**

<table><thead><tr><th>Name</th><th width="99">Type</th><th>Description</th></tr></thead><tbody><tr><td>data.id</td><td>string</td><td>Account transaction ID.</td></tr><tr><td>data.type</td><td>string</td><td>Entity type returned. Always <code>transactions</code>.</td></tr><tr><td>data.attributes</td><td>object</td><td>A set of account transaction attributes.</td></tr><tr><td>data.attributes.createdAt</td><td>string</td><td>Account transaction creation timestamp in UTC+0. Refer to the <a href="/pages/H7xWDJMZukOei8CS8tUW">Date and time format</a> page.</td></tr><tr><td>data.attributes.simplifiedState</td><td>string</td><td>Account transaction status. Can be one of: <code>pending</code>, <code>processing</code>, <code>completed</code>, <code>on_hold</code>, <code>rejected</code>, <code>cancelled</code>.</td></tr><tr><td>data.attributes.transactionType</td><td>string</td><td>Account transaction type. Can only be <code>CoinTransaction</code>.</td></tr><tr><td>data.attributes.amount</td><td>string</td><td>Account transaction amount.</td></tr><tr><td>data.attributes.currency</td><td>string</td><td>Account transaction currency.</td></tr><tr><td>data.attributes.balance</td><td>string</td><td>Account balance immediately after Txn processed this transaction.</td></tr><tr><td>data.attributes.reference</td><td>string</td><td>Account transaction reference.</td></tr><tr><td>data.attributes.accountId</td><td>string</td><td>ID of the account the transaction belongs to.</td></tr><tr><td>data.relationships.transactionDetails</td><td>object</td><td>Link to the on-chain deposit details, returned as a <code>coinTransactions</code> entity in <code>included[]</code>.</td></tr><tr><td>included[].id</td><td>string</td><td>Transaction ID.</td></tr><tr><td>included[].type</td><td>string</td><td>Entity type returned. Always <code>coinTransactions</code>.</td></tr><tr><td>included[].attributes</td><td>object</td><td>A set of crypto transaction attributes.</td></tr><tr><td>included[].attributes.txHash</td><td>string</td><td>Crypto transaction hash.</td></tr><tr><td>included[].attributes.currencyCode</td><td>string</td><td>Crypto transaction currency.</td></tr><tr><td>included[].attributes.createdAt</td><td>string</td><td>Crypto transaction creation timestamp in UTC+0. Refer to the <a href="/pages/H7xWDJMZukOei8CS8tUW">Date and time format</a> page.</td></tr><tr><td>included[].attributes.state</td><td>string</td><td>Internal Txn state. Ignore this field — use <code>data.attributes.simplifiedState</code> in your implementation.</td></tr><tr><td>included[].attributes.amount</td><td>string</td><td>Crypto transaction amount.</td></tr><tr><td>included[].attributes.accountId</td><td>string</td><td>Account ID which the crypto transaction belongs to.</td></tr><tr><td>included[].attributes.reference</td><td>string</td><td>Transaction reference.</td></tr><tr><td>included[].attributes.simplifiedState</td><td>string</td><td>Crypto transaction status. Can be one of: <code>pending</code>, <code>processing</code>, <code>completed</code>, <code>on_hold</code>, <code>rejected</code>, <code>cancelled</code>.</td></tr><tr><td>included[].attributes.sourceAddresses</td><td>array</td><td>Wallet address(es) the funds were sent from. Typically a single address; may contain multiple entries when the deposit arrived via a UTXO-based network (BTC, LTC, BCH, DOGE, etc.) and the sender’s wallet combined several inputs.</td></tr><tr><td>included[].type(network).attributes.name</td><td>string</td><td>Network name. E.g. <code>Tron (TRC20)</code>.</td></tr><tr><td>included[].type(network).attributes.currencyCode</td><td>string</td><td>Currency code for the network.</td></tr><tr><td>included[].type(network).attributes.code</td><td>string</td><td>Network code. E.g. <code>ttrx:usdt</code>. Refer to <a href="/pages/SA7q0b6VrvXO3W09TQfS">Supported currencies</a>.</td></tr><tr><td>included[].type(addresses).attributes.label</td><td>string</td><td>Address label.</td></tr><tr><td>included[].type(addresses).attributes.value</td><td>string</td><td>The wallet address the deposit was received at.</td></tr><tr><td>included[].type(addresses).attributes.createdAt</td><td>string</td><td>Timestamp when the address was created.</td></tr></tbody></table>


# Exchange concept

Exchanges on Txn are requests to convert one currency to another. For instance, you can convert crypto to fiat and vice versa as long as you have a sufficient balance in the currency account from which you are converting funds.

The exchange process consists of two steps: [creating](/exchange/creating-quote) a quote and [confirming](/exchange/confirming-quote) the quote.

When creating a quote, Txn provides you with a guaranteed exchange rate valid for 30 seconds, during which you will need to confirm the quote. If a quote isn't confirmed within 30 seconds, it expires, and no further actions are required from you unless you want to create another quote.

Each successful exchange operation creates a pair of exchange transactions - one transaction for each of your currency accounts involved in the exchange.

In Txn's API terminology, we call these accounts "account charged" and "account received". The exchange transaction in your account charged reduces the account balance, while the exchange transaction in your account received increases the account balance. You can view these exchange transactions in your [account transaction history](/accounts/listing-account-transactions).


# Supported currency pairs

Below is a list of currency pairs and the minimum and maximum amounts per currency pair supported for exchanges.

| Base currency | Quote currency | Direction | Min amount | Max amount    |
| ------------- | -------------- | --------- | ---------- | ------------- |
| BTC           | EUR            | Buy/Sell  | 0.0001 BTC | 2 BTC         |
| BTC           | USD            | Buy/Sell  | 0.0001 BTC | 2 BTC         |
| BTC           | TRY            | Buy/Sell  | 0.0001 BTC | 2 BTC         |
| BTC           | CAD            | Buy/Sell  | 0.0001 BTC | 2 BTC         |
| BTC           | NZD            | Buy/Sell  | 0.0001 BTC | 2 BTC         |
| BTC           | USDT           | Buy/Sell  | 0.0001 BTC | 2 BTC         |
| USDT          | EUR            | Buy/Sell  | 0.01 USDT  | 150,000 USDT  |
| USDT          | USD            | Buy/Sell  | 0.01 USDT  | 150,000 USDT  |
| USDT          | TRY            | Buy/Sell  | 0.01 USDT  | 150,000 USDT  |
| USDT          | CAD            | Buy/Sell  | 0.01 USDT  | 150,000 USDT  |
| USDT          | NZD            | Buy/Sell  | 0.01 USDT  | 150,000 USDT  |
| USDC          | EUR            | Buy/Sell  | 0.01 USDC  | 150,000 USDC  |
| USDC          | USD            | Buy/Sell  | 0.01 USDC  | 150,000 USDC  |
| USDC          | TRY            | Buy/Sell  | 0.01 USDC  | 150,000 USDC  |
| USDC          | CAD            | Buy/Sell  | 0.01 USDC  | 150,000 USDC  |
| USDC          | NZD            | Buy/Sell  | 0.01 USDC  | 150,000 USDC  |
| USDC          | USDT           | Buy/Sell  | 0.01 USDC  | 150,000 USDC  |
| TRX           | EUR            | Buy/Sell  | 1 TRX      | 1,000,000 TRX |
| TRX           | USD            | Buy/Sell  | 1 TRX      | 1,000,000 TRX |
| TRX           | TRY            | Buy/Sell  | 1 TRX      | 1,000,000 TRX |
| TRX           | CAD            | Buy/Sell  | 1 TRX      | 1,000,000 TRX |
| TRX           | NZD            | Buy/Sell  | 1 TRX      | 1,000,000 TRX |
| TRX           | USDT           | Buy/Sell  | 1 TRX      | 1,000,000 TRX |
| ETH           | EUR            | Buy/Sell  | 0.001 ETH  | 40 ETH        |
| ETH           | USD            | Buy/Sell  | 0.001 ETH  | 40 ETH        |
| ETH           | TRY            | Buy/Sell  | 0.001 ETH  | 40 ETH        |
| ETH           | CAD            | Buy/Sell  | 0.001 ETH  | 40 ETH        |
| ETH           | NZD            | Buy/Sell  | 0.001 ETH  | 40 ETH        |
| ETH           | USDT           | Buy/Sell  | 0.001 ETH  | 40 ETH        |
| XRP           | EUR            | Buy/Sell  | 5 XRP      | 200,000 XRP   |
| XRP           | USD            | Buy/Sell  | 5 XRP      | 200,000 XRP   |
| XRP           | TRY            | Buy/Sell  | 5 XRP      | 200,000 XRP   |
| XRP           | CAD            | Buy/Sell  | 5 XRP      | 200,000 XRP   |
| XRP           | NZD            | Buy/Sell  | 5 XRP      | 200,000 XRP   |
| XRP           | USDT           | Buy/Sell  | 5 XRP      | 200,000 XRP   |
| LTC           | EUR            | Buy/Sell  | 0.1 LTC    | 1,500 LTC     |
| LTC           | USD            | Buy/Sell  | 0.1 LTC    | 1,500 LTC     |
| LTC           | TRY            | Buy/Sell  | 0.1 LTC    | 1,500 LTC     |
| LTC           | CAD            | Buy/Sell  | 0.1 LTC    | 1,500 LTC     |
| LTC           | NZD            | Buy/Sell  | 0.1 LTC    | 1,500 LTC     |
| LTC           | USDT           | Buy/Sell  | 0.1 LTC    | 1,500 LTC     |
| BCH           | EUR            | Buy/Sell  | 0.01 BCH   | 300 BCH       |
| BCH           | USD            | Buy/Sell  | 0.01 BCH   | 300 BCH       |
| BCH           | TRY            | Buy/Sell  | 0.01 BCH   | 300 BCH       |
| BCH           | CAD            | Buy/Sell  | 0.01 BCH   | 300 BCH       |
| BCH           | NZD            | Buy/Sell  | 0.01 BCH   | 300 BCH       |
| BCH           | USDT           | Buy/Sell  | 0.01 BCH   | 300 BCH       |
| LINK          | EUR            | Buy/Sell  | 0.1 LINK   | 7,000 LINK    |
| LINK          | USD            | Buy/Sell  | 0.1 LINK   | 7,000 LINK    |
| LINK          | TRY            | Buy/Sell  | 0.1 LINK   | 7,000 LINK    |
| LINK          | CAD            | Buy/Sell  | 0.1 LINK   | 7,000 LINK    |
| LINK          | NZD            | Buy/Sell  | 0.1 LINK   | 7,000 LINK    |
| LINK          | USDT           | Buy/Sell  | 0.1 LINK   | 7,000 LINK    |
| EUR           | TRY            | Buy/Sell  | 0.01 EUR   | 150,000 EUR   |
| EUR           | USD            | Buy/Sell  | 0.01 EUR   | 150,000 EUR   |
| EUR           | CAD            | Buy/Sell  | 0.01 EUR   | 150,000 EUR   |
| EUR           | NZD            | Buy/Sell  | 0.01 EUR   | 150,000 EUR   |

In the event that you exceed the min/max exchange amount thresholds, you can expect the following error messages from our API in response to your [Create Quote](/exchange/creating-quote) request:

{% tabs %}
{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "amount is below minimum",
      "detail": "amount: 1.0, minimum: 10.00",
      "code": "amount_below_minimum"
    }
  ]
}
```

{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "amount is above maximum",
      "detail": "amount: 500000.0, maximum: 150000.00",
      "code": "amount_above_maximum"
    }
  ]
}
```

{% endtab %}
{% endtabs %}


# Reading exchange rates

## Read exchange rate

<mark style="color:green;">`GET`</mark> `/api/public/v1/exchange/rate`

This endpoint returns **indicative mid-market** exchange rate for a specified currency pair.

You cannot specify quantity as it is defaulted to 1.

For a precise price estimation based on the amount, use [Creating quote](/exchange/creating-quote) instead.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_token>`       |

**Query parameters**

<table><thead><tr><th>Name</th><th width="105">Type</th><th>Description</th></tr></thead><tbody><tr><td>sell_currency_code</td><td>string</td><td>Currency code to sell. E.g. EUR. Refer to <a href="/pages/brqdFdtRYeQJbmkSBxHi">Supported currency pairs</a>.</td></tr><tr><td>buy_currency_code</td><td>string</td><td>Currency code to buy. E.g. USDT. Refer to <a href="/pages/brqdFdtRYeQJbmkSBxHi">Supported currency pairs</a>.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": {
    "id": "USDTEUR/10.0USDT",
    "type": "exchangeRates",
    "attributes": {
      "baseCurrencyCode": "USDT",
      "quoteCurrencyCode": "EUR",
      "direction": "mid_market_rate",
      "price": "0.8716",
      "quantity": "10.0"
    }
  },
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "Currency pair not supported",
      "code": "currency_pair_not_supported"
    }
  ]
}
```

{% endtab %}
{% endtabs %}


# Reading exchange rates in bulk

## Read exchange rates in bulk

<mark style="color:green;">`GET`</mark> `/api/public/v1/exchange/rates`

This endpoint returns **indicative** **rates** for a specified currency.

You cannot specify quantity.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_token>`       |

**Query parameters**

<table><thead><tr><th>Name</th><th width="105">Type</th><th>Description</th></tr></thead><tbody><tr><td>currency_code</td><td>string</td><td>Currency code. E.g. USDT. Refer to <a href="/pages/brqdFdtRYeQJbmkSBxHi">Supported currency pairs</a>.</td></tr></tbody></table>

**Response Body**

<table><thead><tr><th>Name</th><th width="97">Type</th><th>Description</th></tr></thead><tbody><tr><td>data[].id</td><td>string</td><td>Rate ID, formed from the base and quote currency codes. Example: <code>USDTBRL</code>.</td></tr><tr><td>data[].type</td><td>string</td><td>Entity type returned. Always <code>indicativeRates</code>.</td></tr><tr><td>data[].attributes</td><td>object</td><td>Set of rate attributes.</td></tr><tr><td>data[].attributes.baseCurrencyCode</td><td>string</td><td>Base currency code. Matches the requested <code>currency_code</code>.</td></tr><tr><td>data[].attributes.quoteCurrencyCode</td><td>string</td><td>Quote currency code.</td></tr><tr><td>data[].attributes.price</td><td>string</td><td>Indicative price of one unit of the base currency expressed in the quote currency.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": [
    {
      "id": "USDTBRL",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "BRL",
        "price": "5.34979458"
      }
    },
    {
      "id": "USDTCLP",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "CLP",
        "price": "943.21695"
      }
    },
    {
      "id": "USDTCNY",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "CNY",
        "price": "7.11936355"
      }
    },
    {
      "id": "USDTINR",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "INR",
        "price": "88.6276987115"
      }
    },
    {
      "id": "USDTKRW",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "KRW",
        "price": "1457.4687331685"
      }
    },
    {
      "id": "USDTNZD",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "NZD",
        "price": "1.7794"
      }
    },
    {
      "id": "USDTTHB",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "THB",
        "price": "32.3302989997"
      }
    },
    {
      "id": "USDTTRY",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "TRY",
        "price": "42.1940769783"
      }
    },
    {
      "id": "USDTPEN",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "PEN",
        "price": "3.377736375"
      }
    },
    {
      "id": "USDTCOP",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "COP",
        "price": "3824.5299627002"
      }
    },
    {
      "id": "USDTMYR",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "MYR",
        "price": "4.1747472"
      }
    },
    {
      "id": "USDTMXN",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "MXN",
        "price": "18.5255956535"
      }
    },
    {
      "id": "USDTHKD",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "HKD",
        "price": "7.7754416675"
      }
    },
    {
      "id": "USDTTWD",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "TWD",
        "price": "30.96800681"
      }
    },
    {
      "id": "USDTVND",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "VND",
        "price": "26304.4340826657"
      }
    },
    {
      "id": "USDTIDR",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "IDR",
        "price": "16684.650192873"
      }
    },
    {
      "id": "USDTAUD",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "AUD",
        "price": "1.5410585437"
      }
    },
    {
      "id": "USDTZAR",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "ZAR",
        "price": "17.31670343"
      }
    },
    {
      "id": "USDTNGN",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "NGN",
        "price": "1437.158723"
      }
    },
    {
      "id": "USDTPHP",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "PHP",
        "price": "59.0782702003"
      }
    },
    {
      "id": "USDTEUR",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "EUR",
        "price": "0.865865"
      }
    },
    {
      "id": "USDTUSD",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "USD",
        "price": "0.9997"
      }
    },
    {
      "id": "USDTBTC",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "BTC",
        "price": "0.000009919947"
      }
    },
    {
      "id": "USDTTRX",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "TRX",
        "price": "3.504663843062"
      }
    },
    {
      "id": "USDTBCH",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "BCH",
        "price": "0.002062154567"
      }
    },
    {
      "id": "USDTLTC",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "LTC",
        "price": "0.011272433796"
      }
    },
    {
      "id": "USDTETH",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "ETH",
        "price": "0.000304233433"
      }
    },
    {
      "id": "USDTUSDC",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "USDC",
        "price": "0.999700179892"
      }
    },
    {
      "id": "USDTXRP",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "XRP",
        "price": "0.455995369317"
      }
    },
    {
      "id": "USDTLINK",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "LINK",
        "price": "0.067556162298"
      }
    },
    {
      "id": "USDTCAD",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "CAD",
        "price": "1.41105"
      }
    },
    {
      "id": "USDTPOL",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "POL",
        "price": "5.874236372564"
      }
    },
    {
      "id": "USDTJPY",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "JPY",
        "price": "153.28"
      }
    },
    {
      "id": "USDTSOL",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "SOL",
        "price": "0.006460783721"
      }
    },
    {
      "id": "USDTADA",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "ADA",
        "price": "1.859566040166"
      }
    },
    {
      "id": "USDTDOGE",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "DOGE",
        "price": "6.063363076122"
      }
    },
    {
      "id": "USDTSHIB",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "SHIB",
        "price": "107816.993585615411"
      }
    },
    {
      "id": "USDTGBP",
      "type": "indicativeRates",
      "attributes": {
        "baseCurrencyCode": "USDT",
        "quoteCurrencyCode": "GBP",
        "price": "0.762715"
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 404,
      "title": "Record not found",
      "code": "currency_not_found",
      "detail": "Currency not found"
    }
  ]
}
```

{% endtab %}
{% endtabs %}


# Listing exchange currency pairs

<mark style="color:green;">`GET`</mark> `/api/public/v1/exchange/currency_pairs`

This endpoint returns a list of currency pairs available for exchange.

**Headers**

| Name          | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/vnd.api+json |
| Authorization | Bearer \<api\_key>       |

**Response Body**

<table><thead><tr><th>Name</th><th width="97">Type</th><th>Description</th></tr></thead><tbody><tr><td>data[].id</td><td>string</td><td>Currency pair ID.</td></tr><tr><td>data[].type</td><td>string</td><td>Entity type returned. Always <code>currencyPairs</code>.</td></tr><tr><td>data[].attributes</td><td>object</td><td>Set of currency pair attributes.</td></tr><tr><td>data[].attributes.direction</td><td>string</td><td>Quote direction. Either <code>buy</code> or <code>sell</code>.</td></tr><tr><td>data[].attributes.enabled</td><td>boolean</td><td>If <code>true</code>, the currency pair is available for exchange.</td></tr><tr><td>data[].attributes.minAmount</td><td>string</td><td>Minimum exchange amount, quoted in <code>minAmountCurrency</code>.</td></tr><tr><td>data[].attributes.minAmountCurrency</td><td>string</td><td>Currency in which <code>minAmount</code> is quoted.</td></tr><tr><td>data[].attributes.maxAmount</td><td>string</td><td>Maximum exchange amount, quoted in <code>maxAmountCurrency</code>.</td></tr><tr><td>data[].attributes.maxAmountCurrency</td><td>string</td><td>Currency in which <code>maxAmount</code> is quoted.</td></tr><tr><td>data[].relationships.baseCurrency.id</td><td>string</td><td>Base currency of the pair. Refer to <a href="/pages/SA7q0b6VrvXO3W09TQfS">supported currencies</a>.</td></tr><tr><td>data[].relationships.quoteCurrency.id</td><td>string</td><td>Quote currency of the pair.</td></tr><tr><td>included[].type(currencies).attributes</td><td>object</td><td>Currency details, including <code>code</code>, <code>symbol</code>, <code>crypto</code>, and <code>subunitToUnit</code>.</td></tr><tr><td>included[].type(network).attributes</td><td>object</td><td>Network details, including <code>code</code>, <code>name</code>, and <code>currencyCode</code>.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": [
    {
      "id": "4018ce40-4af8-42bf-9c72-88c285e9e952",
      "type": "currencyPairs",
      "attributes": {
        "direction": "buy",
        "enabled": true,
        "minAmount": "1.000000",
        "maxAmount": "5000000.000000",
        "minAmountCurrency": "USDT",
        "maxAmountCurrency": "USDT"
      },
      "relationships": {
        "baseCurrency": {
          "data": {
            "type": "currencies",
            "id": "USDT"
          }
        },
        "quoteCurrency": {
          "data": {
            "type": "currencies",
            "id": "EUR"
          }
        }
      }
    },
    {
      "id": "9df10d72-ca21-4d3b-a58f-c538ec9e52e8",
      "type": "currencyPairs",
      "attributes": {
        "direction": "sell",
        "enabled": true,
        "minAmount": "1.000000",
        "maxAmount": "5000000.000000",
        "minAmountCurrency": "USDT",
        "maxAmountCurrency": "USDT"
      },
      "relationships": {
        "baseCurrency": {
          "data": {
            "type": "currencies",
            "id": "USDT"
          }
        },
        "quoteCurrency": {
          "data": {
            "type": "currencies",
            "id": "EUR"
          }
        }
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}

```

{% endtab %}
{% endtabs %}


# Exchange webhooks

Txn currently sends an exchange webhook only when an exchange quote completes — other lifecycle events may be added in future. The payload mirrors the [Read quote](/exchange/reading-quote) endpoint response.

For configuring webhook URLs, retry behaviour, source IPs, and signature verification, see the general [Webhooks](/api-basics/webhooks) section.

{% tabs %}
{% tab title="Exchange Webhook" %}

```json
{
  "data": {
    "attributes": {
      "accountChargedId": "5850abb7-0a60-4041-800c-1d43b4dcf4d6",
      "accountReceivedId": "acd50522-de49-4aaa-a183-dc046ff27fd5",
      "amountCharged": "0.0010418",
      "amountChargedCurrency": "BTC",
      "amountReceived": "100.0",
      "amountReceivedCurrency": "EUR",
      "exchangeFee": "1.00",
      "exchangeFeeCurrency": "EUR",
      "expiresAt": "2025-05-23T09:49:47.431Z",
      "rate": "96947.532",
      "rateCurrency": "EUR",
      "status": "completed"
    },
    "id": "d00edf6e-aa93-4461-ba0b-ebc9055e9e1b",
    "relationships": {
      "exchangeOrder": {
        "data": {
          "id": "44f5d889-1532-4846-ad8d-3796de9cf49d",
          "type": "orders"
        }
      },
      "transactions": {
        "data": [
          {
            "id": "2dba06a9-6289-48c6-9456-1580bcfcefc5",
            "type": "transactions"
          },
          {
            "id": "2e262dba-3b58-4e55-81cc-b2201b4994d0",
            "type": "transactions"
          }
        ]
      }
    },
    "type": "exchangeQuotes"
  },
  "included": [
    {
      "attributes": {
        "baseCode": "BTC",
        "quantity": "0.0010418",
        "quoteCode": "EUR"
      },
      "id": "44f5d889-1532-4846-ad8d-3796de9cf49d",
      "type": "orders"
    },
    {
      "attributes": {
        "accountId": "acd50522-de49-4aaa-a183-dc046ff27fd5",
        "amount": "100.00",
        "balance": null,
        "createdAt": "2025-05-23T09:49:20.508Z",
        "currency": "EUR",
        "reference": null,
        "simplifiedState": "completed",
        "transactionType": "ExchangeTransaction"
      },
      "id": "2dba06a9-6289-48c6-9456-1580bcfcefc5",
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "transactionDetails": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "transactions"
    },
    {
      "attributes": {
        "accountId": "5850abb7-0a60-4041-800c-1d43b4dcf4d6",
        "amount": "-0.00104180",
        "balance": null,
        "createdAt": "2025-05-23T09:49:20.497Z",
        "currency": "BTC",
        "reference": null,
        "simplifiedState": "completed",
        "transactionType": "ExchangeTransaction"
      },
      "id": "2e262dba-3b58-4e55-81cc-b2201b4994d0",
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "transactionDetails": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "transactions"
    }
  ],
  "meta": {}
}
```

{% endtab %}
{% endtabs %}


# Creating quote

## Create quote

<mark style="color:green;">`POST`</mark> `/api/public/v1/exchange/quotes`

This endpoint creates quotes.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_token>`       |

**Body**

<table><thead><tr><th>Name</th><th width="116">Type</th><th>Description</th></tr></thead><tbody><tr><td>data</td><td>object</td><td>Object with exchange request data.</td></tr><tr><td>data.type</td><td>string</td><td>Exchange request type. Always <code>quotes</code>.</td></tr><tr><td>data.attributes</td><td>object</td><td>A set of exchange request attributes.</td></tr><tr><td>data.attributes.accountChargedId</td><td>string</td><td>Account ID from which funds are being converted. See <a href="/pages/JNW72V75tuF0e3CXGcb4">Listing Accounts</a>.</td></tr><tr><td>data.attributes.accountReceivedId</td><td>string</td><td>Account ID to which funds are being converted. See <a href="/pages/JNW72V75tuF0e3CXGcb4">Listing Accounts</a>.</td></tr><tr><td>data.attributes.amount</td><td>number</td><td>Exchange amount.</td></tr><tr><td>data.attributes.amountCurrency</td><td>string</td><td>Exchange amount currency. Can be the currency associated with the <code>accountCharged</code> or <code>accountReceived</code>.</td></tr></tbody></table>

**Request JSON**

```json
{
  "data": {
    "type": "quotes",
    "attributes": {
      "accountChargedId": "string",
      "accountReceivedId": "string",
      "amount": "number",
      "amountCurrency": "string"
    }
  }
}
```

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": {
    "id": "d00edf6e-aa93-4461-ba0b-ebc9055e9e1b",
    "type": "exchangeQuotes",
    "attributes": {
      "expiresAt": "2025-05-23T09:49:47.431Z",
      "amountCharged": "0.0010418",
      "amountReceived": "100.0",
      "rate": "96947.532",
      "exchangeFee": "1.00",
      "exchangeFeeCurrency": "EUR",
      "rateCurrency": "EUR",
      "accountChargedId": "5850abb7-0a60-4041-800c-1d43b4dcf4d6",
      "accountReceivedId": "acd50522-de49-4aaa-a183-dc046ff27fd5",
      "status": "pending",
      "amountChargedCurrency": "BTC",
      "amountReceivedCurrency": "EUR"
    },
    "relationships": {
      "exchangeOrder": {
        "data": {
          "type": "orders",
          "id": "44f5d889-1532-4846-ad8d-3796de9cf49d"
        }
      },
      "transactions": {
        "data": []
      }
    }
  },
  "included": [
    {
      "id": "44f5d889-1532-4846-ad8d-3796de9cf49d",
      "type": "orders",
      "attributes": {
        "baseCode": "BTC",
        "quoteCode": "EUR",
        "quantity": "0.0010418"
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "amount is below minimum",
      "code": "amount_below_minimum"
    }
  ]
}
```

{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "amount is above maximum",
      "code": "amount_above_maximum"
    }
  ]
}
```

{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "account has insufficient balance",
      "code": "account_has_insufficient_balance"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

**Response Body**

<table><thead><tr><th>Name</th><th width="115">Type</th><th>Description</th></tr></thead><tbody><tr><td>data.id</td><td>string</td><td>Quote ID.</td></tr><tr><td>data.type</td><td>string</td><td>Entity type returned. Always <code>exchangeQuotes</code>.</td></tr><tr><td>data.attributes</td><td>object</td><td>A set of quote attributes.</td></tr><tr><td>data.attributes.amountCharged</td><td>string</td><td>Amount to be debited from your <code>accountChargedId</code>.</td></tr><tr><td>data.attributes.amountChargedCurrency</td><td>string</td><td>Account charged currency code.</td></tr><tr><td>data.attributes.amountReceivedCurrency</td><td>string</td><td>Account received currency code.</td></tr><tr><td>data.attributes.amountReceived</td><td>string</td><td>Amount to be credited to your <code>accountReceivedId</code>.</td></tr><tr><td>data.attributes.rate</td><td>string</td><td>Exchange rate.</td></tr><tr><td>data.attributes.status</td><td>string</td><td>One of: <code>pending</code>, <code>completed</code>, <code>expired</code>, or <code>failed</code>. Note: A transaction with status <code>failed</code> can be updated to <code>completed</code> via a support request.</td></tr><tr><td>data.attributes.rateCurrency</td><td>string</td><td>Exchange rate currency code.</td></tr><tr><td>data.attributes.exchangeFee</td><td>string</td><td>Txn fee amount.</td></tr><tr><td>data.attributes.exchangeFeeCurrency</td><td>string</td><td>Fee currency code.</td></tr><tr><td>data.attributes.expiresAt</td><td>string</td><td>Quote expiry timestamp.</td></tr></tbody></table>


# Confirming quote

## Confirm quote

<mark style="color:green;">`PATCH`</mark> `/api/public/v1/exchange/quotes/:id`

This endpoint confirms quotes.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**Path Parameters**

| Name | Type   | Description |
| ---- | ------ | ----------- |
| id   | string | Quote ID.   |

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": {
    "id": "d00edf6e-aa93-4461-ba0b-ebc9055e9e1b",
    "type": "exchangeQuotes",
    "attributes": {
      "expiresAt": "2025-05-23T09:49:47.431Z",
      "amountCharged": "0.0010418",
      "amountReceived": "100.0",
      "rate": "96947.532",
      "exchangeFee": "1.00",
      "exchangeFeeCurrency": "EUR",
      "rateCurrency": "EUR",
      "accountChargedId": "5850abb7-0a60-4041-800c-1d43b4dcf4d6",
      "accountReceivedId": "acd50522-de49-4aaa-a183-dc046ff27fd5",
      "status": "completed",
      "amountChargedCurrency": "BTC",
      "amountReceivedCurrency": "EUR"
    },
    "relationships": {
      "exchangeOrder": {
        "data": {
          "type": "orders",
          "id": "44f5d889-1532-4846-ad8d-3796de9cf49d"
        }
      },
      "transactions": {
        "data": [
          {
            "type": "transactions",
            "id": "2dba06a9-6289-48c6-9456-1580bcfcefc5"
          },
          {
            "type": "transactions",
            "id": "2e262dba-3b58-4e55-81cc-b2201b4994d0"
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": "44f5d889-1532-4846-ad8d-3796de9cf49d",
      "type": "orders",
      "attributes": {
        "baseCode": "BTC",
        "quoteCode": "EUR",
        "quantity": "0.0010418"
      }
    },
    {
      "id": "2dba06a9-6289-48c6-9456-1580bcfcefc5",
      "type": "transactions",
      "attributes": {
        "createdAt": "2025-05-23T09:49:20.508Z",
        "simplifiedState": "completed",
        "transactionType": "ExchangeTransaction",
        "amount": "100.00",
        "currency": "EUR",
        "balance": null,
        "reference": null,
        "accountId": "acd50522-de49-4aaa-a183-dc046ff27fd5"
      },
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "transactionDetails": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "2e262dba-3b58-4e55-81cc-b2201b4994d0",
      "type": "transactions",
      "attributes": {
        "createdAt": "2025-05-23T09:49:20.497Z",
        "simplifiedState": "completed",
        "transactionType": "ExchangeTransaction",
        "amount": "-0.00104180",
        "currency": "BTC",
        "balance": null,
        "reference": null,
        "accountId": "5850abb7-0a60-4041-800c-1d43b4dcf4d6"
      },
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "transactionDetails": {
          "meta": {
            "included": false
          }
        }
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "Quote has expired!",
      "detail": "Quote ID: 299b4cd3-1a09-4ace-8f06-bd3480ce88ac, expired at: 2024-07-01 14:24:36 UTC",
      "code": "exchange_quote_expired"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

**Response Body**

<table><thead><tr><th>Name</th><th width="111">Type</th><th>Description</th></tr></thead><tbody><tr><td>data.id</td><td>string</td><td>Quote ID.</td></tr><tr><td>data.type</td><td>string</td><td>Entity type returned. Always <code>exchangeQuotes</code>.</td></tr><tr><td>data.attributes</td><td>object</td><td>A set of quote attributes.</td></tr><tr><td>data.attributes.amountCharged</td><td>string</td><td>Amount to be debited from your <code>accountChargedId</code>.</td></tr><tr><td>data.attributes.amountChargedCurrency</td><td>string</td><td>Account charged currency code.</td></tr><tr><td>data.attributes.amountReceivedCurrency</td><td>string</td><td>Account received cyrrency code.</td></tr><tr><td>data.attributes.amountReceived</td><td>string</td><td>Amount to be credited to your <code>accountReceivedId</code>.</td></tr><tr><td>data.attributes.rate</td><td>string</td><td>Exchange rate.</td></tr><tr><td>data.attributes.status</td><td>string</td><td>One of: <code>pending</code>, <code>completed</code>, <code>expired</code>, or <code>failed</code>. Note: A transaction with status <code>failed</code> can be updated to <code>completed</code> via a support request.</td></tr><tr><td>data.attributes.rateCurrency</td><td>string</td><td>Exchange rate currency code.</td></tr><tr><td>data.attributes.exchangeFee</td><td>string</td><td>Txn fee amount.</td></tr><tr><td>data.attributes.exchangeFeeCurrency</td><td>string</td><td>Fee currency code.</td></tr><tr><td>data.attributes.expiresAt</td><td>string</td><td>Quote expiry timestamp.</td></tr></tbody></table>


# Listing quotes

## List quotes

<mark style="color:green;">`GET`</mark> `/api/public/v1/exchange/quotes`

This endpoint lists quotes.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_token>`       |

**URL Parameters**

<table><thead><tr><th width="175.1334228515625">Name</th><th width="151.44659423828125">Type</th><th>Description</th></tr></thead><tbody><tr><td>order</td><td>string</td><td>Order in which the list of transactions should be returned. Can be <code>created_at</code>.</td></tr><tr><td>order_type</td><td>string</td><td>Order type. Can be either <code>asc</code> or <code>desc</code>.</td></tr><tr><td>page</td><td>number</td><td>Page for which you want to return transactions.</td></tr><tr><td>per_page</td><td>number</td><td>Number of transactions per page to return.</td></tr><tr><td>created_at_from</td><td>string</td><td>Date and time filter. Supports timestamps in ISO 8601 format, e.g. <code>2024-06-18T15:49:02.031Z</code>.</td></tr><tr><td>created_at_to</td><td>string</td><td>Date and time filter. Supports timestamps in ISO 8601 format, e.g. <code>2024-06-18T15:49:02.031Z</code>.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": [
    {
      "id": "d00edf6e-aa93-4461-ba0b-ebc9055e9e1b",
      "type": "exchangeQuotes",
      "attributes": {
        "expiresAt": "2025-05-23T09:49:47.431Z",
        "amountCharged": "0.0010418",
        "amountReceived": "100.0",
        "rate": "96947.532",
        "exchangeFee": "1.00",
        "exchangeFeeCurrency": "EUR",
        "rateCurrency": "EUR",
        "accountChargedId": "5850abb7-0a60-4041-800c-1d43b4dcf4d6",
        "accountReceivedId": "acd50522-de49-4aaa-a183-dc046ff27fd5",
        "status": "completed",
        "amountChargedCurrency": "BTC",
        "amountReceivedCurrency": "EUR"
      },
      "relationships": {
        "exchangeOrder": {
          "data": {
            "type": "orders",
            "id": "44f5d889-1532-4846-ad8d-3796de9cf49d"
          }
        },
        "transactions": {
          "data": [
            {
              "type": "transactions",
              "id": "2e262dba-3b58-4e55-81cc-b2201b4994d0"
            },
            {
              "type": "transactions",
              "id": "2dba06a9-6289-48c6-9456-1580bcfcefc5"
            }
          ]
        }
      }
    }
  ],
  "included": [
    {
      "id": "44f5d889-1532-4846-ad8d-3796de9cf49d",
      "type": "orders",
      "attributes": {
        "baseCode": "BTC",
        "quoteCode": "EUR",
        "quantity": "0.0010418"
      }
    },
    {
      "id": "2e262dba-3b58-4e55-81cc-b2201b4994d0",
      "type": "transactions",
      "attributes": {
        "createdAt": "2025-05-23T09:49:20.497Z",
        "simplifiedState": "completed",
        "transactionType": "ExchangeTransaction",
        "amount": "-0.00104180",
        "currency": "BTC",
        "balance": null,
        "reference": null,
        "accountId": "5850abb7-0a60-4041-800c-1d43b4dcf4d6"
      },
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "transactionDetails": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "2dba06a9-6289-48c6-9456-1580bcfcefc5",
      "type": "transactions",
      "attributes": {
        "createdAt": "2025-05-23T09:49:20.508Z",
        "simplifiedState": "completed",
        "transactionType": "ExchangeTransaction",
        "amount": "100.00",
        "currency": "EUR",
        "balance": null,
        "reference": null,
        "accountId": "acd50522-de49-4aaa-a183-dc046ff27fd5"
      },
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "transactionDetails": {
          "meta": {
            "included": false
          }
        }
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 1,
    "total": 1561
  },
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}

**Response Body**

<table><thead><tr><th>Name</th><th width="115">Type</th><th>Description</th></tr></thead><tbody><tr><td>data[].id</td><td>string</td><td>Quote ID.</td></tr><tr><td>data[].type</td><td>string</td><td>Entity type returned. Always <code>exchangeQuotes</code>.</td></tr><tr><td>data[].attributes</td><td>object</td><td>A set of quote attributes.</td></tr><tr><td>data[].attributes.amountCharged</td><td>string</td><td>Amount to be debited from your <code>accountChargedId</code>.</td></tr><tr><td>data[].attributes.amountChargedCurrency</td><td>string</td><td>Account charged currency code.</td></tr><tr><td>data[].attributes.amountReceivedCurrency</td><td>string</td><td>Account received currency code.</td></tr><tr><td>data[].attributes.amountReceived</td><td>string</td><td>Amount to be credited to your <code>accountReceivedId</code>.</td></tr><tr><td>data[].attributes.rate</td><td>string</td><td>Exchange rate.</td></tr><tr><td>data[].attributes.status</td><td>string</td><td>One of: <code>pending</code>, <code>completed</code>, <code>expired</code>, or <code>failed</code>. Note: A transaction with status <code>failed</code> can be updated to <code>completed</code> via a support request.</td></tr><tr><td>data[].attributes.rateCurrency</td><td>string</td><td>Exchange rate currency code.</td></tr><tr><td>data[].attributes.exchangeFee</td><td>string</td><td>Txn fee amount.</td></tr><tr><td>data[].attributes.exchangeFeeCurrency</td><td>string</td><td>Fee currency code.</td></tr><tr><td>data[].attributes.expiresAt</td><td>string</td><td>Quote expiry timestamp.</td></tr><tr><td>meta.page</td><td>number</td><td>Current page number.</td></tr><tr><td>meta.per_page</td><td>number</td><td>Page size used for the response.</td></tr><tr><td>meta.total</td><td>number</td><td>Total number of quotes matching the query.</td></tr></tbody></table>


# Reading quote

## Read quote

<mark style="color:green;">`GET`</mark> `/api/public/v1/exchange/quotes/:id`

This endpoint reads a single quote.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_token>`       |

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": {
    "id": "d00edf6e-aa93-4461-ba0b-ebc9055e9e1b",
    "type": "exchangeQuotes",
    "attributes": {
      "expiresAt": "2025-05-23T09:49:47.431Z",
      "amountCharged": "0.0010418",
      "amountReceived": "100.0",
      "rate": "96947.532",
      "exchangeFee": "1.00",
      "exchangeFeeCurrency": "EUR",
      "rateCurrency": "EUR",
      "accountChargedId": "5850abb7-0a60-4041-800c-1d43b4dcf4d6",
      "accountReceivedId": "acd50522-de49-4aaa-a183-dc046ff27fd5",
      "status": "completed",
      "amountChargedCurrency": "BTC",
      "amountReceivedCurrency": "EUR"
    },
    "relationships": {
      "exchangeOrder": {
        "data": {
          "type": "orders",
          "id": "44f5d889-1532-4846-ad8d-3796de9cf49d"
        }
      },
      "transactions": {
        "data": [
          {
            "type": "transactions",
            "id": "2dba06a9-6289-48c6-9456-1580bcfcefc5"
          },
          {
            "type": "transactions",
            "id": "2e262dba-3b58-4e55-81cc-b2201b4994d0"
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": "44f5d889-1532-4846-ad8d-3796de9cf49d",
      "type": "orders",
      "attributes": {
        "baseCode": "BTC",
        "quoteCode": "EUR",
        "quantity": "0.0010418"
      }
    },
    {
      "id": "2dba06a9-6289-48c6-9456-1580bcfcefc5",
      "type": "transactions",
      "attributes": {
        "createdAt": "2025-05-23T09:49:20.508Z",
        "simplifiedState": "completed",
        "transactionType": "ExchangeTransaction",
        "amount": "100.00",
        "currency": "EUR",
        "balance": null,
        "reference": null,
        "accountId": "acd50522-de49-4aaa-a183-dc046ff27fd5"
      },
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "transactionDetails": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "2e262dba-3b58-4e55-81cc-b2201b4994d0",
      "type": "transactions",
      "attributes": {
        "createdAt": "2025-05-23T09:49:20.497Z",
        "simplifiedState": "completed",
        "transactionType": "ExchangeTransaction",
        "amount": "-0.00104180",
        "currency": "BTC",
        "balance": null,
        "reference": null,
        "accountId": "5850abb7-0a60-4041-800c-1d43b4dcf4d6"
      },
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "transactionDetails": {
          "meta": {
            "included": false
          }
        }
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}

**Response Body**

<table><thead><tr><th>Name</th><th width="115">Type</th><th>Description</th></tr></thead><tbody><tr><td>data.id</td><td>string</td><td>Quote ID.</td></tr><tr><td>data.type</td><td>string</td><td>Entity type returned. Always <code>exchangeQuotes</code>.</td></tr><tr><td>data.attributes</td><td>object</td><td>A set of quote attributes.</td></tr><tr><td>data.attributes.amountCharged</td><td>string</td><td>Amount to be debited from your <code>accountChargedId</code>.</td></tr><tr><td>data.attributes.amountChargedCurrency</td><td>string</td><td>Account charged currency code.</td></tr><tr><td>data.attributes.amountReceivedCurrency</td><td>string</td><td>Account received currency code.</td></tr><tr><td>data.attributes.amountReceived</td><td>string</td><td>Amount to be credited to your <code>accountReceivedId</code>.</td></tr><tr><td>data.attributes.rate</td><td>string</td><td>Exchange rate.</td></tr><tr><td>data.attributes.status</td><td>string</td><td>One of: <code>pending</code>, <code>completed</code>, <code>expired</code>, or <code>failed</code>. Note: A transaction with status <code>failed</code> can be updated to <code>completed</code> via a support request.</td></tr><tr><td>data.attributes.rateCurrency</td><td>string</td><td>Exchange rate currency code.</td></tr><tr><td>data.attributes.exchangeFee</td><td>string</td><td>Txn fee amount.</td></tr><tr><td>data.attributes.exchangeFeeCurrency</td><td>string</td><td>Fee currency code.</td></tr><tr><td>data.attributes.expiresAt</td><td>string</td><td>Quote expiry timestamp.</td></tr></tbody></table>


# Invoices concept

Crypto invoices are electronic bills issued by merchants to their customers for goods or services, with payment expected in cryptocurrency rather than traditional fiat currency. These invoices typically include details such as the amount due, the accepted cryptocurrency for payment, the payment address and QR code, and an exchange rate provided by Txn that is locked in for 20 minutes, during which the end user is expected to pay the invoice.

For better context, below is a diagram illustrating the invoice payment flow for each party involved in this process.

<figure><img src="/files/keHzH8x3qThzHrwQkaRS" alt=""><figcaption><p>Invoice payment process flow</p></figcaption></figure>

### Which currencies can invoice be paid in?

The complete list of supported cryptocurrencies and tokens can be found on the [Supported currencies](/api-basics/supported-currencies) page.

### What are the minimum and maximum invoice amounts?

Contact Txn support for the minimum and maximum invoice amounts per currency.

### How long is the invoice and its exchange rate valid?

Both the invoice and its exchange rate are valid for 20 minutes from creation. During that window, end users should send a cryptocurrency transaction to the invoice's address. After the invoice expires, Txn continues to monitor the address for late payments for 7 days — see [What happens after the invoice expires?](#what-happens-after-the-invoice-expires) below.

### What statuses can I expect my invoice to be updated to?

Please refer to the [Invoice status flow](/invoices/invoice-status-flow) page in this documentation.

### How long does it take Txn to process a payment?

Once a cryptocurrency transaction is detected at the invoice's receiving address, Txn updates the invoice status from `pending` to `processing`.

The time it takes for Txn to complete the invoice depends on how quickly the transaction is included in a block on the blockchain. If the network experiences congestion during spikes in activity, it may take a bit longer. Normally, payments are processed within minutes. However, payments on the Bitcoin blockchain may take a bit longer due to the design of the Bitcoin blockchain, which produces a new block approximately every 10 minutes.

As soon as the cryptocurrency transaction is included in a block, Txn updates the invoice status from `processing` to `completed`.

### What happens after the invoice expires?

After the invoice expires, meaning no cryptocurrency transaction has been sent by the end user to the invoice address during the invoice validity period, Txn continues to monitor the invoice address for the next 7 days. If your customer sends their cryptocurrency transaction after the invoice expires, Txn will process it and update the invoice status accordingly.

After 7 days from the invoice creation date and time, Txn stops monitoring the invoice address. If any transaction is sent after 7 days, Txn will receive the transaction, but the payment will not be reflected on the corresponding invoice. This 7-day limitation is set due to the large number of cryptocurrency receive addresses our platform generates and monitors. Additionally, in our experience, it is an extremely rare case when end users send funds after 7 days.

### What happens if the end user sends less or more cryptocurrency than they were quoted?

Normally, end users send the exact amount of cryptocurrency they are asked to send to the invoice address to complete their payment.

However, sometimes, end users send slightly more or less cryptocurrency because they either didn't pay enough attention during the withdrawal process from their wallet provider or their wallet provider wasn't clear enough with the end user on how they charge network fees. These two reasons are primarily what cause underpayments and overpayments.

If your end users end up sending less or more cryptocurrency, Txn will process such transactions as normal, except that a spot exchange rate will be applied when converting crypto to fiat and crediting the payment to your account on Txn. You can expect the final invoice status to be `completed` in this scenario.

Alternatively, if you do not want to accept a payment and wish to return funds back to your end-user instead, please see the [Invoice refunds](/invoices/invoice-refunds) documentation.


# Invoice integration guide

This guide walks through a complete invoice integration — from creating an invoice through handling every payment outcome correctly. It covers the **on-chain** and **Binance Pay** payment methods and applies equally if you're integrating **NFT** payments. For NFT-specific setup, see the [NFT invoice integration guide](/invoices/nft-invoice-integration-guide) alongside this one.

## Before you start

Check these before writing any integration code:

* **Supported currency pairs** — not every `billedCurrency` and `chargedCurrency` combination is valid. Verify yours against the [Listing invoice currency pairs](/invoices/listing-invoice-currency-pairs) endpoint.
* **Amount limits** — each `billedCurrency` has a minimum and maximum. Requests outside the range return HTTP 422. Contact Txn support for the limits per currency.
* **Refund handling** — if you want Txn to automatically issue refunds for underpayments, overpayments, or late payments, this is configured at the account level. Contact Txn to set it up before going live. See [Invoice refunds](/invoices/invoice-refunds) for the available options.
* **Hosted page vs. custom UI** — decide upfront. The hosted page requires almost no frontend work; a custom UI gives you full control but requires you to handle more edge cases (XRP destination tags, Binance Pay deeplinks, countdown timers).

## Step 1: Create the invoice

Send a `POST` to [`/api/public/v1/invoices`](/invoices/creating-invoice) for each payment your end user needs to make. One invoice, one payment attempt.

### Key parameters

**`billedCurrency`** is the currency you display to the end user — typically the currency in which they hold a balance on your platform (e.g. TRY, USD, CNY). It does not have to be a cryptocurrency.

**`chargedCurrency`** and **`payNetwork`** define what the end user actually pays in and on which blockchain network. These must be a supported cryptocurrency/token and network combination — see [Supported currencies](/api-basics/supported-currencies) for valid codes.

**`targetCurrency`** is the currency that lands in your Txn account after the payment is converted. It must be a [tradable fiat currency or cryptocurrency](/api-basics/supported-currencies#currency-types) — [display fiat currencies](/api-basics/supported-currencies#display-fiat) are not accepted here. If omitted, it defaults to `billedCurrency`, which must itself be tradable.

This matters in practice: many common `billedCurrency` values — such as `TRY`, `CNY`, and `BRL` — are display fiat and cannot hold a balance on Txn. If you invoice in one of these currencies, you must supply `targetCurrency` explicitly (for example, `EUR` or `USD`) so Txn knows which account to settle the funds into. Omitting it with a display fiat `billedCurrency` will return an error.

**`reference`** is your internal correlation key. Set it to your order ID, user ID, or any unique value that lets you match the invoice back to a record on your side. It must be unique per invoice. You will see it on every webhook and API response for the invoice's lifetime.

**`successRedirectUrl`** and **`unsuccessRedirectUrl`** apply only to the hosted page flow. They are the URLs Txn redirects the end user to after a successful payment or after the invoice expires or is cancelled.

### What the response gives you

| Field                            | Description                                                             |
| -------------------------------- | ----------------------------------------------------------------------- |
| `data.attributes.address`        | The wallet address the end user must send crypto to                     |
| `data.attributes.amountCharged`  | The exact crypto amount they need to send                               |
| `data.attributes.expiresAt`      | When the exchange rate and invoice expire (20 minutes from creation)    |
| `data.attributes.hostedPageUrl`  | Ready-to-use hosted payment page URL                                    |
| `included[].type(addresses)`     | Full address entity, including the destination tag for XRP              |
| `included[].type(binanceOrders)` | Binance Pay order details, when `paymentMethods` includes `binance_pay` |

{% hint style="warning" %}
The exchange rate is locked for 20 minutes from invoice creation. Create the invoice only when the end user is ready to pay, and present the payment details immediately — do not create the invoice in advance.
{% endhint %}

## Step 2: Present the invoice to the end user

### Option A — Hosted page

Redirect the end user to `hostedPageUrl`. Txn renders the full payment UI: wallet address, QR code, countdown timer, and Binance Pay instructions where applicable. The end user is redirected to your `successRedirectUrl` or `unsuccessRedirectUrl` when the invoice reaches a terminal state.

This is the fastest path to production and requires no frontend work beyond the redirect.

### Option B — Custom UI

Build your own payment screen using the invoice response data. At minimum, display:

* The wallet address and a scannable QR code
* The exact amount to send (`amountCharged` + `chargedCurrency`)
* The payment network by its full name (`networkName`) — for example, "Tron (TRC20)" rather than the network code `ttrx:usdt`. Users select the network in their wallet app when initiating a withdrawal; showing the recognisable display name reduces the risk of them choosing the wrong network and sending funds that cannot be recovered.
* A countdown timer to `expiresAt`

{% hint style="danger" %}
**XRP invoices:** the address is returned in the format `rwCQVZLSMNY6DgMH61317qvH3nHYqm68PF?dt=123456`, where the value after `?dt=` is the **destination tag**. Display the address and the destination tag separately, and ensure both are clearly visible and copyable. If the end user sends XRP without specifying the destination tag, the payment will not be processed.
{% endhint %}

**Binance Pay:** if `paymentMethods` includes `binance_pay`, the `binanceOrders` entity in `included[]` contains:

* `qrcodeLink` — a hosted QR code image to display
* `deeplink` — opens the Binance app directly on mobile
* `universalUrl` — works across both web and mobile browsers

## Step 3: Track invoice status

### Webhooks (recommended)

Configure your webhook endpoint in the Txn dashboard. Txn sends a `POST` request to your endpoint on every `status` change. The payload is the same shape as the [Read invoice](/invoices/reading-invoice) response.

Two implementation requirements:

1. **Verify the signature** on every incoming webhook before processing it. See [Webhooks](/api-basics/webhooks) for signature verification details.
2. **Process webhooks idempotently.** The same status transition can be delivered more than once. Use the invoice `id` and `status` together as a deduplication key.

See [Invoice webhooks](/invoices/invoice-webhooks) for example payloads for each status.

### Polling (alternative)

Poll [Read invoice](/invoices/reading-invoice) by invoice `id`. A reasonable interval is every 5–10 seconds while the end user is on the payment screen. Reduce the frequency after `expiresAt` — the invoice can still complete via late payment for up to 7 days, but changes become infrequent.

### Status reference

| `status`     | Final? | What it means                                                             | What to do                                                                      |
| ------------ | ------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `pending`    | No     | Awaiting a crypto transaction                                             | No action needed                                                                |
| `expired`    | **No** | No payment received within 20 minutes                                     | **Do not cancel your order** — late payment is still possible for 7 days        |
| `processing` | No     | Transaction detected, awaiting confirmations                              | Optionally show "payment detected" to the end user                              |
| `on_hold`    | No     | Compliance review in progress                                             | Do not settle — wait for the next status update                                 |
| `completed`  | Yes    | Payment processed and funds credited to your account                      | Settle based on `statusContext` — see [Step 4](#step-4-handle-payment-outcomes) |
| `cancelled`  | Yes    | No payment received within 7 days, or payment rejected under refund rules | Check `coinDeposits` — if non-empty, a refund link may be present               |
| `rejected`   | Yes    | Payment declined by Txn compliance                                        | Do not settle                                                                   |

## Step 4: Handle payment outcomes

The `statusContext` and `paymentStatus` fields give you the full picture of what happened inside a `completed` or `cancelled` status. Handle each combination explicitly — do not fall through to a default case.

### Full payment, on time

`status: completed` · `statusContext: full` · `paymentStatus: on_time`

Happy path. The end user sent the correct amount within 20 minutes. Proceed to [Step 5](#step-5-credit-the-end-user).

### Full payment, late

`status: completed` · `statusContext: full` · `paymentStatus: late`

The end user paid after the invoice expired but within the 7-day monitoring window. Txn processed the payment at the spot exchange rate applicable at the time of receipt. Proceed to credit the end user.

### Underpayment

`status: completed` · `statusContext: underpaid`

The end user sent less crypto than quoted. Txn applied the spot exchange rate to the amount actually received and settled the result to your account. `invoiceTransactions.amountBilled` reflects the actual credited amount — it will be less than the original invoice amount. Credit the end user accordingly.

If refund rules are configured for underpayments, Txn may instead reject the payment and issue a refund link. The invoice status will be `cancelled` in that case — see [Cancelled with a refund](#cancelled-with-a-refund) below.

### Overpayment

`status: completed` · `statusContext: overpaid`

The end user sent more crypto than quoted. Txn applied the spot exchange rate to the full amount received. `invoiceTransactions.amountBilled` reflects what was actually processed — it will exceed the original invoice amount. Credit the end user accordingly.

Depending on your refund configuration, Txn may instead process only the original invoice amount and issue a refund link for the excess, or reject the entire payment. See [Invoice refunds](/invoices/invoice-refunds) for the configured behaviour options.

### On hold

`status: on_hold`

Txn's compliance team is reviewing the payment, typically because the source wallet is associated with elevated risk. Do not settle the end user. The invoice will resolve to either `completed` (payment cleared) or `rejected` (payment declined). Wait for the next webhook.

### Rejected

`status: rejected` — final

The payment was declined by Txn compliance. Txn returns the funds to the sender. Do not settle the end user.

### Cancelled with a refund

`status: cancelled` · `coinDeposits` relationship non-empty

A payment was received but rejected under your account's refund rules (underpayment, overpayment, or late payment). The `refundLinks` relationship will contain a payment link entry. Extract the `hostedPageUrl` from the corresponding entity in `included[]` and share it with the end user so they can claim their funds. See [Refunds](#refunds).

### No payment received

`status: cancelled` · `statusContext: unpaid` · `coinDeposits` empty

No crypto was ever detected at the invoice address within the 7-day monitoring window. Safe to treat as abandoned — cancel the corresponding order on your side.

## Step 5: Credit the end user

When the invoice reaches `completed`, read `invoiceTransactions.amountBilled` from the `included[]` array. This is the amount in `billedCurrency` that the end user's payment actually resulted in, and it is the value to credit to the end user's balance on your platform.

In a full, on-time payment, `invoiceTransactions.amountBilled` equals the original invoice amount. In underpayment and overpayment scenarios, Txn applies the spot exchange rate to the crypto actually received, so the value will differ.

{% hint style="warning" %}
Do not use `data.attributes.amountBilled` (the original quoted invoice amount) or `data.attributes.targetAmount` (the amount that lands in your Txn account) for crediting the end user. Both will produce incorrect results in underpayment and overpayment scenarios.
{% endhint %}

For fee reporting: `invoiceTransactions.transactionFee` and `invoiceTransactions.targetTransactionFee` give you the fee breakdown in `billedCurrency` and `targetCurrency` respectively.

## Refunds

When Txn's refund handling is enabled for your account and a qualifying payment comes in (underpaid, overpaid, or late), Txn rejects the payment and creates a refund link instead of crediting your account. The invoice status becomes `cancelled` and the `refundLinks` relationship in the API response and webhook payload contains the refund payment link.

To handle a refund in your integration:

1. Detect `status: cancelled` with a non-empty `refundLinks` relationship.
2. Find the corresponding `paymentLinks` entity in `included[]`.
3. Extract its `hostedPageUrl`.
4. Deliver that URL to your end user — by email, in-app notification, or however you communicate with them.

The end user visits the URL, enters their wallet address, and Txn sends the crypto back to them directly. The refund link can only be used once. Funds are returned in the same currency and on the same network as the original payment. Network and service fees are deducted from the refund amount — if the refund amount is smaller than the combined fees, Txn cannot process the refund.

See [Invoice refunds](/invoices/invoice-refunds) for a full breakdown of each scenario and the available configuration options.

## Subsequent payments to a completed invoice address

After an invoice completes, Txn continues to monitor its receiving address. If the end user sends another crypto transaction to the same address — for example, paying twice by mistake — Txn can automatically credit the incoming funds to your crypto account (for example, your USDT account) rather than leaving them unprocessed.

This behaviour is optional and configured at the account level. Contact Txn support to enable it.

When a subsequent payment is credited, it appears as a `coinTransaction` in your account's transaction history. The transaction inherits the `reference` of the original invoice, so your existing reconciliation logic can correlate it back to the originating order using the same reference matching you already apply to invoices. The original invoice is not affected — it remains in its `completed` state.

## Reconciliation

* **Correlate with your records** — the `reference` you set on creation is returned on every invoice response and webhook. Use it to look up the corresponding order or user in your system.
* **Blockchain proof** — `coinTransactions.txHash` (in `included[]`) is the on-chain transaction hash. Store it and share it with the end user if they need confirmation that the payment was sent.
* **Batch reconciliation** — use the [List invoices](/invoices/listing-invoices) endpoint with the `created_at_from` and `created_at_to` parameters to pull all invoices in a given date range.
* **Fee accounting** — `invoiceTransactions.transactionFee` and `invoiceTransactions.targetTransactionFee` are available for each completed invoice.


# Invoice status flow

The status of invoices varies depending on the timing and the amount of cryptocurrency sent by the end user to the invoice's receiving address.

When updating payment status on your side, you will want to look for the `status`, `statusContext`, and `paymentStatus` attribute values when polling the [Read Invoice](/invoices/reading-invoice) endpoint that returns invoice details by its ID.

* The `status` attribute value represents the current status of the invoice, indicating whether Txn is currently waiting for payment, is busy processing payment, or if the invoice has expired
* The `paymentStatus` attribute value provides information on whether the payment was made on time within 20 minutes or if the payment is late, meaning the cryptocurrency was received after the invoice expired
* The `statusContext` attribute value provides information on whether the end-user made their payment in full, underpaid, or overpaid the invoice

You will find possible attribute value combinations in the table below.

<table><thead><tr><th width="142">status</th><th>statusContext</th><th>paymentStatus</th><th width="123">Final state?</th><th>Description</th></tr></thead><tbody><tr><td>pending</td><td>unpaid</td><td>expecting</td><td>no</td><td>Invoice created, awaiting transaction.</td></tr><tr><td>expired</td><td>unpaid</td><td>expecting</td><td>no</td><td>No payment was received within 20 minutes.</td></tr><tr><td>processing</td><td>unpaid</td><td><ul><li>on_time</li><li>late</li></ul></td><td>no</td><td>Payment detected, awaiting confirmations.</td></tr><tr><td>completed</td><td><ul><li>full</li><li>underpaid</li><li>overpaid</li></ul></td><td><ul><li>on_time</li><li>late</li></ul></td><td>yes</td><td>Invoice completed, funds credited to the merchant's account on Txn.</td></tr><tr><td>on_hold</td><td>unpaid</td><td>expecting</td><td>no</td><td>Txn isn’t comfortable with the payment risk level. The payment is subject to further review by Txn compliance.</td></tr><tr><td>cancelled</td><td>unpaid</td><td><ul><li>expecting</li><li>on_time</li><li>late</li></ul></td><td>yes</td><td>Either no payment was received within 7 days, or Txn rejected the payment under your account's refund handling rules — see <a href="/pages/Uxy4jgkgLg1ntEmnv6Wh">Invoice refunds</a>.</td></tr><tr><td>rejected</td><td>unpaid</td><td>expecting</td><td>yes</td><td>Invoice was rejected by Txn Compliance due to payment risk.</td></tr></tbody></table>

For better context, below is the generalized invoice process flow that visualizes the flow of invoice statuses.

<figure><img src="/files/PGL9N3VnjwoHHPpsfGpX" alt=""><figcaption></figcaption></figure>

For more convenience, we've split the above process flow into separate payment flows that you will want to handle on your side.

### Happy Flow

* The end-user sends the **exact amount of crypto** they have been asked to send
* The end-user sends their crypto **within 20 minutes**
* The merchant receives the invoice amount minus processing fees in their account

<figure><img src="/files/0v3JGfQEgrS5VoYHkVhd" alt=""><figcaption></figcaption></figure>

### Underpaid Flow

* The end-user sends **less crypto** than they have been asked to send
* The end-user sends their crypto **within 20 minutes**
* Txn applies the **spot exchange rate** to the received amount of crypto
* The merchant receives the result of the currency conversion

<figure><img src="/files/jtyuW5WduL4hOvu54187" alt=""><figcaption></figcaption></figure>

### Overpaid Flow

* The end-user sends **more crypto** than they have been asked to send
* The end-user sends their crypto **within 20 minutes**
* Txn applies the **spot exchange rate** to the received amount of crypto
* The merchant receives the result of the currency conversion

<figure><img src="/files/1IxiitJfdui58mLqxC5H" alt=""><figcaption></figcaption></figure>

### Late Payment Flow

* The end-user sends either the **exact amount of crypto, less crypto, or more crypto** than they have been asked to send
* The end-user sends their crypto **after the invoice has expired**
* Txn applies the **spot exchange rate** to the received amount of crypto
* The merchant receives the result of the currency conversion

<figure><img src="/files/DSv3JE45dmWHKjtEUemK" alt=""><figcaption></figcaption></figure>

### Risk Payment Flow

* The cryptocurrency **payment comes from a source that is connected to illegal activities**, e.g., dark markets, drug markets, sanctioned entities, etc
* Txn puts the **payment on hold** as it is **subject to further review** by the Txn Compliance team
* The Txn **Compliance team decides** whether the payment must be rejected and sent back to the originator or if it can be released
* If the latter, Txn applies the **spot exchange rate** to the received amount of crypto
* The merchant receives the result of the currency conversion

<figure><img src="/files/rCB9zmH0YV3P8kWBbQF5" alt=""><figcaption></figcaption></figure>


# Invoices in cashier

The visual representation of invoice details is very important from the customer experience perspective. Displaying the right details in the right place and in the right way can significantly increase payment conversion in your cashier. Conversely, representing invoice details in your cashier in a wrong or inconvenient way for the end user can dramatically drop your conversion rate.

We have included some visuals and quick tips below to help you get a better idea of how invoice details in your cashier should look, and to save you from unnecessary struggles and back-and-forths during your customers' payment experience.

### Visual representation

| Invoice details page             | QR code                          |
| -------------------------------- | -------------------------------- |
| ![](/files/ObC73HqjZzCLqJjG4f5P) | ![](/files/LVW7Xt417jlLyHBSB40J) |

All invoice details shown in the image above are returned in the API response when [creating invoices](/invoices/creating-invoice).

Taking a look at the visual example, from top to bottom:

| Visual element          | Description                                                                                                        | Invoice attribute                                                                                                                                                                                                                                                     | Best practice                                                                                                                                                                       |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Amount                  | This is the invoice amount in fiat.                                                                                | <ul><li>data.attributes.amountBilled</li><li>data.attributes.billedCurrency</li></ul>                                                                                                                                                                                 | Keep the invoice amount visible throughout the checkout process in your cashier, so users don't have to backtrack to double-check.                                                  |
| Send exact amount       | This is the exact amount of cryptocurrency required to complete a payment.                                         | <ul><li>data.attributes.amountCharged</li><li>data.attributes.chargedCurrency</li></ul>                                                                                                                                                                               | Make it copyable to avoid customers manually typing it into their wallet. With cryptocurrencies, up to 8 decimal places can be involved, making manual entry tedious for customers. |
| To this address         | This is the invoice receiving address.                                                                             | data.included\[].attributes.value                                                                                                                                                                                                                                     | Make the address copyable. Ideally, your customers should be able to see the full address to verify it after copying and pasting it into their wallet.                              |
| Network                 | This is the blockchain network through which a payment should be made.                                             | data.attributes.networkName                                                                                                                                                                                                                                           | The network name must be visible next to the receiving address. Using the wrong network may result in lost and unrecoverable funds.                                                 |
| Show QR code            | This QR code represents the invoice receive address and can be scanned by end users with their wallet application. | <p>data.included\[].attributes.value<br><br>>>> Look for "type": "addresses" <<<</p>                                                                                                                                                                                  | The QR code is generated on your server-side frontend. It simplifies populating the destination address field in the customer's wallet application.                                 |
| Network type disclaimer | A disclaimer/warning message for end users the ensure they send funds via the right network.                       | <p>No ready-to-go message supplied by the API.<br><br>You can put something like this:<br><br>"Only deposit \<data.attributes.chargedCurrency> from the \<data.attributes.networkName> network. Deposits from other networks are not supported and will be lost."</p> | A disclaimer or warning message for end users to ensure they send funds via the correct network.                                                                                    |
| Exchange rate           | This is the exchange rate provided by Txn.                                                                         | data.attributes.exchangeRate                                                                                                                                                                                                                                          | This is the exchange rate locked in for 20 minutes. It is recommended to include a countdown timer on the page.                                                                     |
| Reference               | This is the invoice reference ID.                                                                                  | data.attributes.reference                                                                                                                                                                                                                                             | Making the reference copyable is beneficial if your customers need to contact your customer support team.                                                                           |
| Invoice expires in      | This is the duration for which the invoice remains valid.                                                          | <ul><li>data.attributes.createdAt</li><li>data.attributes.expiresAt</li></ul>                                                                                                                                                                                         | Inform your customers about the timeframe they have to make their payment while the provided exchange rate is still guaranteed. This helps reduce the number of late payments.      |


# Listing invoice currency pairs

<mark style="color:green;">`GET`</mark> `/api/public/v1/invoices/currency_pairs`

Returns all available invoice currency pairs. Use this endpoint to discover which currencies (`billedCurrency`) can be used to denominate an invoice and which cryptocurrencies (`chargedCurrency`) the customer can pay with, along with the networks available for each.

To construct a [Create Invoice](/invoices/creating-invoice) request from the response:

1. Choose a pair — `billedCurrency` gives you the `billedCurrency` parameter, `chargedCurrency` gives you the `chargedCurrency` parameter.
2. Find the `chargedCurrency` entry in `included` and follow its `networks` references.
3. Find the matching `network` objects in `included` — the `code` is the `network` value to use.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**Response Body**

<table><thead><tr><th>Name</th><th width="96">Type</th><th>Description</th></tr></thead><tbody><tr><td>data[].id</td><td>string</td><td>Currency pair ID.</td></tr><tr><td>data[].type</td><td>string</td><td>Always <code>invoiceCurrencyPairs</code>.</td></tr><tr><td>data[].attributes.direction</td><td>string</td><td>Always <code>sell</code> — the platform sells the <code>chargedCurrency</code> received from the customer and settles the invoice in <code>billedCurrency</code>.</td></tr><tr><td>data[].attributes.enabled</td><td>boolean</td><td>Whether this pair is currently available for invoices.</td></tr><tr><td>data[].relationships.billedCurrency.data.id</td><td>string</td><td>Currency code of the invoice denomination. Use as the <code>billedCurrency</code> parameter in Create Invoice.</td></tr><tr><td>data[].relationships.chargedCurrency.data.id</td><td>string</td><td>Currency code of the cryptocurrency the customer pays with. Use as the <code>chargedCurrency</code> parameter in Create Invoice.</td></tr><tr><td>included[].type(currencies).attributes.code</td><td>string</td><td>Currency code.</td></tr><tr><td>included[].type(currencies).attributes.crypto</td><td>boolean</td><td><code>true</code> for cryptocurrencies, <code>false</code> for fiat.</td></tr><tr><td>included[].type(currencies).attributes.symbol</td><td>string</td><td>Display symbol for the currency.</td></tr><tr><td>included[].type(currencies).attributes.subunitToUnit</td><td>number</td><td>Number of smallest units in one whole unit (e.g. <code>100000000</code> for BTC, <code>100</code> for EUR).</td></tr><tr><td>included[].type(currencies).relationships.networks</td><td>array</td><td>Network references for this currency. Resolve against <code>network</code> objects in <code>included</code> to get the <code>network</code> codes.</td></tr><tr><td>included[].type(network).attributes.code</td><td>string</td><td>Network code. Use as the <code>network</code> parameter in Create Invoice.</td></tr><tr><td>included[].type(network).attributes.name</td><td>string</td><td>Human-readable network name.</td></tr><tr><td>included[].type(network).attributes.currencyCode</td><td>string</td><td>Currency code this network belongs to.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": [
    {
      "id": "b5871e76-9609-4a54-af18-b8979a2e663e",
      "type": "invoiceCurrencyPairs",
      "attributes": {
        "direction": "sell",
        "enabled": true
      },
      "relationships": {
        "billedCurrency": {
          "data": { "type": "currencies", "id": "EUR" }
        },
        "chargedCurrency": {
          "data": { "type": "currencies", "id": "USDT" }
        }
      }
    },
    {
      "id": "d7a631bd-dd67-4d5f-a8ef-d50e1a5bbfca",
      "type": "invoiceCurrencyPairs",
      "attributes": {
        "direction": "sell",
        "enabled": true
      },
      "relationships": {
        "billedCurrency": {
          "data": { "type": "currencies", "id": "EUR" }
        },
        "chargedCurrency": {
          "data": { "type": "currencies", "id": "BTC" }
        }
      }
    }
  ],
  "included": [
    {
      "id": "EUR",
      "type": "currencies",
      "attributes": {
        "code": "EUR",
        "crypto": false,
        "symbol": "€",
        "subunitToUnit": 100
      },
      "relationships": {
        "networks": { "data": [] }
      }
    },
    {
      "id": "USDT",
      "type": "currencies",
      "attributes": {
        "code": "USDT",
        "crypto": true,
        "symbol": "₮",
        "subunitToUnit": 1000000
      },
      "relationships": {
        "networks": {
          "data": [
            { "type": "network", "id": "2cfea86d-f334-4bd2-99ac-e74281520c95" },
            { "type": "network", "id": "8ededca3-a1cd-4b46-8c3a-14915f706ab2" },
            { "type": "network", "id": "490f02d4-b09a-4486-a469-d10c2ea43638" },
            { "type": "network", "id": "927d49d4-f4b2-48dc-876d-ac375337ec2a" },
            { "type": "network", "id": "4a1ec40b-8656-437c-ae79-4dd5435b53a5" }
          ]
        }
      }
    },
    {
      "id": "BTC",
      "type": "currencies",
      "attributes": {
        "code": "BTC",
        "crypto": true,
        "symbol": "฿",
        "subunitToUnit": 100000000
      },
      "relationships": {
        "networks": {
          "data": [
            { "type": "network", "id": "c0369c57-da08-4c60-b5ee-63e1e43d5ae4" }
          ]
        }
      }
    },
    {
      "id": "2cfea86d-f334-4bd2-99ac-e74281520c95",
      "type": "network",
      "attributes": {
        "currencyCode": "USDT",
        "name": "Ethereum (ERC20)",
        "code": "hterc6dp"
      }
    },
    {
      "id": "8ededca3-a1cd-4b46-8c3a-14915f706ab2",
      "type": "network",
      "attributes": {
        "currencyCode": "USDT",
        "name": "Tron (TRC20)",
        "code": "ttrx:usdt"
      }
    },
    {
      "id": "490f02d4-b09a-4486-a469-d10c2ea43638",
      "type": "network",
      "attributes": {
        "currencyCode": "USDT",
        "name": "Polygon (ERC20)",
        "code": "tpolygon:usdt"
      }
    },
    {
      "id": "927d49d4-f4b2-48dc-876d-ac375337ec2a",
      "type": "network",
      "attributes": {
        "currencyCode": "USDT",
        "name": "Binance Smart Chain (BEP20)",
        "code": "tbsc:usdt"
      }
    },
    {
      "id": "4a1ec40b-8656-437c-ae79-4dd5435b53a5",
      "type": "network",
      "attributes": {
        "currencyCode": "USDT",
        "name": "Solana",
        "code": "tsol:usdt"
      }
    },
    {
      "id": "c0369c57-da08-4c60-b5ee-63e1e43d5ae4",
      "type": "network",
      "attributes": {
        "currencyCode": "BTC",
        "name": "Bitcoin",
        "code": "tbtc"
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}


# Invoice webhooks

Txn sends an invoice webhook each time an invoice's `status` changes. The payload is the same shape returned by the [Read invoice](/invoices/reading-invoice) endpoint — the same `data` object, with a JSON:API `included` array carrying the related `addresses`, `binanceOrders`, `coinTransactions`, `invoiceTransactions`, `transactions`, `exchangeQuotes`, and `accounts` resources where applicable.

The tabs below show example payloads for each terminal and intermediate status. For the rules that govern transitions and the meaning of `status`, `statusContext`, and `paymentStatus`, see [Invoice status flow](/invoices/invoice-status-flow).

For configuring webhook URLs, retry behaviour, source IPs, and signature verification, see the general [Webhooks](/api-basics/webhooks) section.

{% tabs %}
{% tab title="Status Pending" %}

```json
{
  "data": {
    "attributes": {
      "amountBilled": "10000.00",
      "amountCharged": "283.417792",
      "billedCurrency": "TRY",
      "chargedCurrency": "USDT",
      "chargedTargetRate": "0.948618",
      "chargedTargetRateCurrency": "EUR",
      "createdAt": "2025-01-28T16:26:56.275Z",
      "exchangeRate": "35.2836",
      "expiresAt": "2025-01-28T16:46:56.063Z",
      "hostedPageUrl": "https://sandbox.txn.io/redirect?invoice_id=fe8ea84a-8490-4133-87e9-3209e6d1f7db&request_type=invoice_hosted_page&zone=eu",
      "network": "ttrx:usdt",
      "networkName": "Tron (TRC20)",
      "paymentMethods": [
        "on_chain",
        "binance_pay"
      ],
      "paymentStatus": "expecting",
      "reference": "bc32c092-8979-4435-b176-ae1b790b1ca6",
      "status": "pending",
      "statusContext": "unpaid",
      "successRedirectUrl": "https://yahoo.com",
      "targetAmount": "266.17",
      "targetCurrency": "EUR",
      "unsuccessRedirectUrl": "https://myspace.com",
      "scAddress": null
    },
    "id": "fe8ea84a-8490-4133-87e9-3209e6d1f7db",
    "relationships": {
      "targetAccount": {
        "data": {
          "type": "accounts",
          "id": "13a85b45-8543-41c7-b963-394d4ea128ae"
        }
      },
      "binanceOrder": {
        "data": {
          "type": "binanceOrders",
          "id": "5e623ab4-f0fc-43df-af01-b3208aa6af0b"
        }
      },
      "address": {
        "data": {
          "id": "e4c1c999-52a5-470b-a8c4-e88d875eb3cf",
          "type": "addresses"
        }
      },
      "coinDeposits": {
        "data": []
      },
      "invoiceTransactions": {
        "data": [
          {
            "id": "89d6e25d-70ff-4d89-b784-0aac1df896a0",
            "type": "invoiceTransactions"
          }
        ]
      },
      "refundLinks": {
        "data": []
      }
    },
    "type": "invoices"
  },
  "included": [
    {
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "type": "accounts",
      "attributes": {
        "master": false,
        "currencyCode": "EUR",
        "label": "EUR account",
        "bankReference": "BDR2891634526738095",
        "balance": "1500.00",
        "totalBalance": "1500.00",
        "bankWithdrawalAvailable": true,
        "bankDepositAvailable": true,
        "transferAvailable": true,
        "currencyType": "fiat"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "5e623ab4-f0fc-43df-af01-b3208aa6af0b",
      "type": "binanceOrders",
      "attributes": {
        "deeplink": "bnc://app.binance.com/payment/secpay?tempToken=41wu19i6qX348MzHSdhyjNcbXC0xe8jA",
        "qrContent": "https://app.binance.com/qr/dplk1d9affed91d34e019653a3d627672478",
        "qrcodeLink": "https://public.bnbstatic.com/static/payment/20250606/18e063aa-9e98-4805-a861-68119e031ea7.jpg",
        "universalUrl": "https://app.binance.com/payment/secpay?linkToken=3104f0eab7ae49a998b10752421b2d99&_dp=Ym5jOi8vYXBwLmJpbmFuY2UuY29tL3BheW1lbnQvc2VjcGF5P3RlbXBUb2tlbj00MXd1MTlpNnFYMzQ4TXpIU2RoeWpOY2JYQzB4ZThqQQ"
      }
    },
    {
      "attributes": {
        "createdAt": "2025-01-28T15:19:00.020Z",
        "label": "Tron (TRC20)",
        "value": "TSEC2CvHZ1MgiA8VhgWoRHpXSxPY6wndyW"
      },
      "id": "e4c1c999-52a5-470b-a8c4-e88d875eb3cf",
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "network": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "addresses"
    },
    {
      "attributes": {
        "amountBilled": "10000.00",
        "billedChargedRate": "35.2836",
        "billedChargedRateCurrency": "TRY",
        "consolidationFee": "0.00",
        "targetTransactionFee": "2.69",
        "targetTransactionFeeCurrency": "EUR",
        "transactionFee": "100.00",
        "transactionFeeCurrency": "TRY",
        "simplifiedState": "pending"
      },
      "id": "89d6e25d-70ff-4d89-b784-0aac1df896a0",
      "relationships": {
        "exchangeQuote": {
          "data": null
        },
        "invoice": {
          "meta": {
            "included": false
          }
        },
        "txn": {
          "data": {
            "id": "89d6e25d-70ff-4d89-b784-0aac1df896a0",
            "type": "transactions"
          }
        }
      },
      "type": "invoiceTransactions"
    },
    {
      "attributes": {
        "amount": "266.17",
        "createdAt": "2025-01-28T16:26:56.299Z",
        "reference": "bc32c092-8979-4435-b176-ae1b790b1ca6",
        "simplifiedState": "pending",
        "transactionType": "InvoiceTransaction"
      },
      "id": "89d6e25d-70ff-4d89-b784-0aac1df896a0",
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "transactionDetails": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "transactions"
    }
  ],
  "meta": {}
}
```

{% endtab %}

{% tab title="Status Processing" %}

```json
{
  "data": {
    "attributes": {
      "amountBilled": "10000.00",
      "amountCharged": "283.417792",
      "billedCurrency": "TRY",
      "chargedCurrency": "USDT",
      "chargedTargetRate": "0.948618",
      "chargedTargetRateCurrency": "EUR",
      "createdAt": "2025-01-28T16:26:56.275Z",
      "exchangeRate": "35.2836",
      "expiresAt": "2025-01-28T16:46:56.063Z",
      "hostedPageUrl": "https://sandbox.txn.io/redirect?invoice_id=fe8ea84a-8490-4133-87e9-3209e6d1f7db&request_type=invoice_hosted_page&zone=eu",
      "network": "ttrx:usdt",
      "networkName": "Tron (TRC20)",
      "paymentMethods": [
        "on_chain",
        "binance_pay"
      ],
      "paymentStatus": "on_time",
      "reference": "bc32c092-8979-4435-b176-ae1b790b1ca6",
      "status": "processing",
      "statusContext": "unpaid",
      "successRedirectUrl": "https://yahoo.com",
      "targetAmount": "266.17",
      "targetCurrency": "EUR",
      "unsuccessRedirectUrl": "https://myspace.com",
      "scAddress": null
    },
    "id": "fe8ea84a-8490-4133-87e9-3209e6d1f7db",
    "relationships": {
      "targetAccount": {
        "data": {
          "type": "accounts",
          "id": "13a85b45-8543-41c7-b963-394d4ea128ae"
        }
      },
      "binanceOrder": {
        "data": {
          "type": "binanceOrders",
          "id": "5e623ab4-f0fc-43df-af01-b3208aa6af0b"
        }
      },
      "address": {
        "data": {
          "id": "e4c1c999-52a5-470b-a8c4-e88d875eb3cf",
          "type": "addresses"
        }
      },
      "coinDeposits": {
        "data": [
          {
            "id": "32520a71-f71a-4878-97c1-41844cd96d9d",
            "type": "coinTransactions"
          }
        ]
      },
      "invoiceTransactions": {
        "data": [
          {
            "id": "89d6e25d-70ff-4d89-b784-0aac1df896a0",
            "type": "invoiceTransactions"
          }
        ]
      },
      "refundLinks": {
        "data": []
      }
    },
    "type": "invoices"
  },
  "included": [
    {
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "type": "accounts",
      "attributes": {
        "master": false,
        "currencyCode": "EUR",
        "label": "EUR account",
        "bankReference": "BDR2891634526738095",
        "balance": "1500.00",
        "totalBalance": "1500.00",
        "bankWithdrawalAvailable": true,
        "bankDepositAvailable": true,
        "transferAvailable": true,
        "currencyType": "fiat"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "5e623ab4-f0fc-43df-af01-b3208aa6af0b",
      "type": "binanceOrders",
      "attributes": {
        "deeplink": "bnc://app.binance.com/payment/secpay?tempToken=41wu19i6qX348MzHSdhyjNcbXC0xe8jA",
        "qrContent": "https://app.binance.com/qr/dplk1d9affed91d34e019653a3d627672478",
        "qrcodeLink": "https://public.bnbstatic.com/static/payment/20250606/18e063aa-9e98-4805-a861-68119e031ea7.jpg",
        "universalUrl": "https://app.binance.com/payment/secpay?linkToken=3104f0eab7ae49a998b10752421b2d99&_dp=Ym5jOi8vYXBwLmJpbmFuY2UuY29tL3BheW1lbnQvc2VjcGF5P3RlbXBUb2tlbj00MXd1MTlpNnFYMzQ4TXpIU2RoeWpOY2JYQzB4ZThqQQ"
      }
    },
    {
      "attributes": {
        "createdAt": "2025-01-28T15:19:00.020Z",
        "label": "Tron (TRC20)",
        "value": "TSEC2CvHZ1MgiA8VhgWoRHpXSxPY6wndyW"
      },
      "id": "e4c1c999-52a5-470b-a8c4-e88d875eb3cf",
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "network": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "addresses"
    },
    {
      "attributes": {
        "amountBilled": "10000.00",
        "billedChargedRate": "35.2836",
        "billedChargedRateCurrency": "TRY",
        "consolidationFee": "0.00",
        "targetTransactionFee": "2.69",
        "targetTransactionFeeCurrency": "EUR",
        "transactionFee": "100.00",
        "transactionFeeCurrency": "TRY",
        "simplifiedState": "on_hold"
      },
      "id": "89d6e25d-70ff-4d89-b784-0aac1df896a0",
      "relationships": {
        "exchangeQuote": {
          "data": null
        },
        "invoice": {
          "meta": {
            "included": false
          }
        },
        "txn": {
          "data": {
            "id": "89d6e25d-70ff-4d89-b784-0aac1df896a0",
            "type": "transactions"
          }
        }
      },
      "type": "invoiceTransactions"
    },
    {
      "attributes": {
        "accountId": "e289de2b-37bd-4eff-b832-f754c31a2d95",
        "amount": "283.417792",
        "createdAt": "2025-01-28T16:28:26.669Z",
        "currencyCode": "USDT",
        "sourceAddresses": [
          "TTbGTMwUwA3mncLP7xqCZei1ekaNSgeAJe"
        ],
        "state": "processed",
        "txHash": "1c378c68c5b78573e069642036747754ed7edbad0cd35d0fa734739243906f18"
      },
      "id": "32520a71-f71a-4878-97c1-41844cd96d9d",
      "relationships": {
        "address": {
          "meta": {
            "included": false
          }
        },
        "network": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "coinTransactions"
    },
    {
      "attributes": {
        "amount": "266.17",
        "createdAt": "2025-01-28T16:29:00.447Z",
        "reference": "bc32c092-8979-4435-b176-ae1b790b1ca6",
        "simplifiedState": "on_hold",
        "transactionType": "InvoiceTransaction"
      },
      "id": "89d6e25d-70ff-4d89-b784-0aac1df896a0",
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "transactionDetails": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "transactions"
    }
  ],
  "meta": {}
}
```

{% endtab %}

{% tab title="Status Completed" %}

```json
{
  "data": {
    "attributes": {
      "amountBilled": "10000.00",
      "amountCharged": "283.417792",
      "billedCurrency": "TRY",
      "chargedCurrency": "USDT",
      "chargedTargetRate": "0.948618",
      "chargedTargetRateCurrency": "EUR",
      "createdAt": "2025-01-28T16:26:56.275Z",
      "exchangeRate": "35.2836",
      "expiresAt": "2025-01-28T16:46:56.063Z",
      "hostedPageUrl": "https://sandbox.txn.io/redirect?invoice_id=fe8ea84a-8490-4133-87e9-3209e6d1f7db&request_type=invoice_hosted_page&zone=eu",
      "network": "ttrx:usdt",
      "networkName": "Tron (TRC20)",
      "paymentMethods": [
        "on_chain",
        "binance_pay"
      ],
      "paymentStatus": "on_time",
      "reference": "bc32c092-8979-4435-b176-ae1b790b1ca6",
      "status": "completed",
      "statusContext": "full",
      "successRedirectUrl": "https://yahoo.com",
      "targetAmount": "266.17",
      "targetCurrency": "EUR",
      "unsuccessRedirectUrl": "https://myspace.com",
      "scAddress": null
    },
    "id": "fe8ea84a-8490-4133-87e9-3209e6d1f7db",
    "relationships": {
      "targetAccount": {
        "data": {
          "type": "accounts",
          "id": "13a85b45-8543-41c7-b963-394d4ea128ae"
        }
      },
      "binanceOrder": {
        "data": {
          "type": "binanceOrders",
          "id": "5e623ab4-f0fc-43df-af01-b3208aa6af0b"
        }
      },
      "address": {
        "data": {
          "id": "e4c1c999-52a5-470b-a8c4-e88d875eb3cf",
          "type": "addresses"
        }
      },
      "coinDeposits": {
        "data": [
          {
            "id": "32520a71-f71a-4878-97c1-41844cd96d9d",
            "type": "coinTransactions"
          }
        ]
      },
      "invoiceTransactions": {
        "data": [
          {
            "id": "89d6e25d-70ff-4d89-b784-0aac1df896a0",
            "type": "invoiceTransactions"
          }
        ]
      },
      "refundLinks": {
        "data": []
      }
    },
    "type": "invoices"
  },
  "included": [
    {
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "type": "accounts",
      "attributes": {
        "master": false,
        "currencyCode": "EUR",
        "label": "EUR account",
        "bankReference": "BDR2891634526738095",
        "balance": "1500.00",
        "totalBalance": "1500.00",
        "bankWithdrawalAvailable": true,
        "bankDepositAvailable": true,
        "transferAvailable": true,
        "currencyType": "fiat"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "5e623ab4-f0fc-43df-af01-b3208aa6af0b",
      "type": "binanceOrders",
      "attributes": {
        "deeplink": "bnc://app.binance.com/payment/secpay?tempToken=41wu19i6qX348MzHSdhyjNcbXC0xe8jA",
        "qrContent": "https://app.binance.com/qr/dplk1d9affed91d34e019653a3d627672478",
        "qrcodeLink": "https://public.bnbstatic.com/static/payment/20250606/18e063aa-9e98-4805-a861-68119e031ea7.jpg",
        "universalUrl": "https://app.binance.com/payment/secpay?linkToken=3104f0eab7ae49a998b10752421b2d99&_dp=Ym5jOi8vYXBwLmJpbmFuY2UuY29tL3BheW1lbnQvc2VjcGF5P3RlbXBUb2tlbj00MXd1MTlpNnFYMzQ4TXpIU2RoeWpOY2JYQzB4ZThqQQ"
      }
    },
    {
      "attributes": {
        "createdAt": "2025-01-28T15:19:00.020Z",
        "label": "Tron (TRC20)",
        "value": "TSEC2CvHZ1MgiA8VhgWoRHpXSxPY6wndyW"
      },
      "id": "e4c1c999-52a5-470b-a8c4-e88d875eb3cf",
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "network": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "addresses"
    },
    {
      "attributes": {
        "amountBilled": "10000.00",
        "billedChargedRate": "35.2836",
        "billedChargedRateCurrency": "TRY",
        "consolidationFee": "0.00",
        "targetTransactionFee": "2.69",
        "targetTransactionFeeCurrency": "EUR",
        "transactionFee": "100.00",
        "transactionFeeCurrency": "TRY",
        "simplifiedState": "completed"
      },
      "id": "89d6e25d-70ff-4d89-b784-0aac1df896a0",
      "relationships": {
        "exchangeQuote": {
          "data": {
            "id": "a8a7da6c-f60c-4546-9036-bb0ca8da9d75",
            "type": "exchangeQuotes"
          }
        },
        "invoice": {
          "meta": {
            "included": false
          }
        },
        "txn": {
          "data": {
            "id": "89d6e25d-70ff-4d89-b784-0aac1df896a0",
            "type": "transactions"
          }
        }
      },
      "type": "invoiceTransactions"
    },
    {
      "attributes": {
        "accountId": "e289de2b-37bd-4eff-b832-f754c31a2d95",
        "amount": "283.417792",
        "createdAt": "2025-01-28T16:28:26.669Z",
        "currencyCode": "USDT",
        "sourceAddresses": [
          "TTbGTMwUwA3mncLP7xqCZei1ekaNSgeAJe"
        ],
        "state": "processed",
        "txHash": "1c378c68c5b78573e069642036747754ed7edbad0cd35d0fa734739243906f18"
      },
      "id": "32520a71-f71a-4878-97c1-41844cd96d9d",
      "relationships": {
        "address": {
          "meta": {
            "included": false
          }
        },
        "network": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "coinTransactions"
    },
    {
      "attributes": {
        "amount": "266.17",
        "createdAt": "2025-01-28T16:38:38.363Z",
        "reference": "bc32c092-8979-4435-b176-ae1b790b1ca6",
        "simplifiedState": "completed",
        "transactionType": "InvoiceTransaction"
      },
      "id": "89d6e25d-70ff-4d89-b784-0aac1df896a0",
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "transactionDetails": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "transactions"
    },
    {
      "attributes": {
        "accountChargedId": "e289de2b-37bd-4eff-b832-f754c31a2d95",
        "accountReceivedId": "13a85b45-8543-41c7-b963-394d4ea128ae",
        "amountCharged": "283.417792",
        "amountChargedCurrency": "USDT",
        "amountReceived": "268.86",
        "amountReceivedCurrency": "EUR",
        "exchangeFee": "0.00",
        "exchangeFeeCurrency": "EUR",
        "expiresAt": "2025-01-28T16:39:08.437Z",
        "rate": "0.948618",
        "rateCurrency": "EUR"
      },
      "id": "a8a7da6c-f60c-4546-9036-bb0ca8da9d75",
      "relationships": {
        "exchangeOrder": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "exchangeQuotes"
    }
  ],
  "meta": {}
}
```

{% endtab %}

{% tab title="Status On Hold" %}

```json
{
  "data": {
    "attributes": {
      "amountBilled": "10000.00",
      "amountCharged": "283.417792",
      "billedCurrency": "TRY",
      "chargedCurrency": "USDT",
      "chargedTargetRate": "0.948618",
      "chargedTargetRateCurrency": "EUR",
      "createdAt": "2025-01-28T16:26:56.275Z",
      "exchangeRate": "35.2836",
      "expiresAt": "2025-01-28T16:46:56.063Z",
      "hostedPageUrl": "https://sandbox.txn.io/redirect?invoice_id=fe8ea84a-8490-4133-87e9-3209e6d1f7db&request_type=invoice_hosted_page&zone=eu",
      "network": "ttrx:usdt",
      "networkName": "Tron (TRC20)",
      "paymentMethods": [
        "on_chain",
        "binance_pay"
      ],
      "paymentStatus": "on_time",
      "reference": "bc32c092-8979-4435-b176-ae1b790b1ca6",
      "status": "on_hold",
      "statusContext": "unpaid",
      "successRedirectUrl": "https://yahoo.com",
      "targetAmount": "266.17",
      "targetCurrency": "EUR",
      "unsuccessRedirectUrl": "https://myspace.com",
      "scAddress": null
    },
    "id": "fe8ea84a-8490-4133-87e9-3209e6d1f7db",
    "relationships": {
      "targetAccount": {
        "data": {
          "type": "accounts",
          "id": "13a85b45-8543-41c7-b963-394d4ea128ae"
        }
      },
      "binanceOrder": {
        "data": {
          "type": "binanceOrders",
          "id": "5e623ab4-f0fc-43df-af01-b3208aa6af0b"
        }
      },
      "address": {
        "data": {
          "id": "e4c1c999-52a5-470b-a8c4-e88d875eb3cf",
          "type": "addresses"
        }
      },
      "coinDeposits": {
        "data": [
          {
            "id": "32520a71-f71a-4878-97c1-41844cd96d9d",
            "type": "coinTransactions"
          }
        ]
      },
      "invoiceTransactions": {
        "data": [
          {
            "id": "89d6e25d-70ff-4d89-b784-0aac1df896a0",
            "type": "invoiceTransactions"
          }
        ]
      },
      "refundLinks": {
        "data": []
      }
    },
    "type": "invoices"
  },
  "included": [
    {
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "type": "accounts",
      "attributes": {
        "master": false,
        "currencyCode": "EUR",
        "label": "EUR account",
        "bankReference": "BDR2891634526738095",
        "balance": "1500.00",
        "totalBalance": "1500.00",
        "bankWithdrawalAvailable": true,
        "bankDepositAvailable": true,
        "transferAvailable": true,
        "currencyType": "fiat"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "5e623ab4-f0fc-43df-af01-b3208aa6af0b",
      "type": "binanceOrders",
      "attributes": {
        "deeplink": "bnc://app.binance.com/payment/secpay?tempToken=41wu19i6qX348MzHSdhyjNcbXC0xe8jA",
        "qrContent": "https://app.binance.com/qr/dplk1d9affed91d34e019653a3d627672478",
        "qrcodeLink": "https://public.bnbstatic.com/static/payment/20250606/18e063aa-9e98-4805-a861-68119e031ea7.jpg",
        "universalUrl": "https://app.binance.com/payment/secpay?linkToken=3104f0eab7ae49a998b10752421b2d99&_dp=Ym5jOi8vYXBwLmJpbmFuY2UuY29tL3BheW1lbnQvc2VjcGF5P3RlbXBUb2tlbj00MXd1MTlpNnFYMzQ4TXpIU2RoeWpOY2JYQzB4ZThqQQ"
      }
    },
    {
      "attributes": {
        "createdAt": "2025-01-28T15:19:00.020Z",
        "label": "Tron (TRC20)",
        "value": "TSEC2CvHZ1MgiA8VhgWoRHpXSxPY6wndyW"
      },
      "id": "e4c1c999-52a5-470b-a8c4-e88d875eb3cf",
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "network": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "addresses"
    },
    {
      "attributes": {
        "amountBilled": "10000.00",
        "billedChargedRate": "35.2836",
        "billedChargedRateCurrency": "TRY",
        "consolidationFee": "0.00",
        "targetTransactionFee": "2.69",
        "targetTransactionFeeCurrency": "EUR",
        "transactionFee": "100.00",
        "transactionFeeCurrency": "TRY",
        "simplifiedState": "on_hold"
      },
      "id": "89d6e25d-70ff-4d89-b784-0aac1df896a0",
      "relationships": {
        "exchangeQuote": {
          "data": null
        },
        "invoice": {
          "meta": {
            "included": false
          }
        },
        "txn": {
          "data": {
            "id": "89d6e25d-70ff-4d89-b784-0aac1df896a0",
            "type": "transactions"
          }
        }
      },
      "type": "invoiceTransactions"
    },
    {
      "attributes": {
        "accountId": "e289de2b-37bd-4eff-b832-f754c31a2d95",
        "amount": "283.417792",
        "createdAt": "2025-01-28T16:28:26.669Z",
        "currencyCode": "USDT",
        "state": "on_hold_confirmed",
        "txHash": "1c378c68c5b78573e069642036747754ed7edbad0cd35d0fa734739243906f18"
      },
      "id": "32520a71-f71a-4878-97c1-41844cd96d9d",
      "relationships": {
        "address": {
          "meta": {
            "included": false
          }
        },
        "network": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "coinTransactions"
    },
    {
      "attributes": {
        "amount": "266.17",
        "createdAt": "2025-01-28T16:29:00.447Z",
        "reference": "bc32c092-8979-4435-b176-ae1b790b1ca6",
        "simplifiedState": "on_hold",
        "transactionType": "InvoiceTransaction"
      },
      "id": "89d6e25d-70ff-4d89-b784-0aac1df896a0",
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "transactionDetails": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "transactions"
    }
  ],
  "meta": {}
}
```

{% endtab %}

{% tab title="Status Expired" %}

```json
{
  "data": {
    "attributes": {
      "amountBilled": "10000.00",
      "amountCharged": "283.489380",
      "billedCurrency": "TRY",
      "chargedCurrency": "USDT",
      "chargedTargetRate": "0.9483804",
      "chargedTargetRateCurrency": "EUR",
      "createdAt": "2025-01-28T17:13:15.057Z",
      "exchangeRate": "35.27469",
      "expiresAt": "2025-01-28T17:33:14.862Z",
      "hostedPageUrl": "https://sandbox.txn.io/redirect?invoice_id=071f4b03-30d9-499e-bef7-743249d3b9ea&request_type=invoice_hosted_page&zone=eu",
      "network": "ttrx:usdt",
      "networkName": "Tron (TRC20)",
      "paymentMethods": [
        "on_chain",
        "binance_pay"
      ],
      "paymentStatus": "expecting",
      "reference": "14c58eb0-b97e-4396-bedf-398a5e6fb8b8",
      "status": "expired",
      "statusContext": "unpaid",
      "successRedirectUrl": "https://yahoo.com",
      "targetAmount": "266.17",
      "targetCurrency": "EUR",
      "unsuccessRedirectUrl": "https://myspace.com",
      "scAddress": null
    },
    "id": "071f4b03-30d9-499e-bef7-743249d3b9ea",
    "relationships": {
      "targetAccount": {
        "data": {
          "type": "accounts",
          "id": "13a85b45-8543-41c7-b963-394d4ea128ae"
        }
      },
      "binanceOrder": {
        "data": {
          "type": "binanceOrders",
          "id": "5e623ab4-f0fc-43df-af01-b3208aa6af0b"
        }
      },
      "address": {
        "data": {
          "id": "8ad44692-b680-4ef9-a160-447ecb4f8962",
          "type": "addresses"
        }
      },
      "coinDeposits": {
        "data": []
      },
      "invoiceTransactions": {
        "data": [
          {
            "id": "432fc78a-660e-4fb1-8691-76dbdb0c496e",
            "type": "invoiceTransactions"
          }
        ]
      },
      "refundLinks": {
        "data": []
      }
    },
    "type": "invoices"
  },
  "included": [
    {
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "type": "accounts",
      "attributes": {
        "master": false,
        "currencyCode": "EUR",
        "label": "EUR account",
        "bankReference": "BDR2891634526738095",
        "balance": "1500.00",
        "totalBalance": "1500.00",
        "bankWithdrawalAvailable": true,
        "bankDepositAvailable": true,
        "transferAvailable": true,
        "currencyType": "fiat"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "5e623ab4-f0fc-43df-af01-b3208aa6af0b",
      "type": "binanceOrders",
      "attributes": {
        "deeplink": "bnc://app.binance.com/payment/secpay?tempToken=41wu19i6qX348MzHSdhyjNcbXC0xe8jA",
        "qrContent": "https://app.binance.com/qr/dplk1d9affed91d34e019653a3d627672478",
        "qrcodeLink": "https://public.bnbstatic.com/static/payment/20250606/18e063aa-9e98-4805-a861-68119e031ea7.jpg",
        "universalUrl": "https://app.binance.com/payment/secpay?linkToken=3104f0eab7ae49a998b10752421b2d99&_dp=Ym5jOi8vYXBwLmJpbmFuY2UuY29tL3BheW1lbnQvc2VjcGF5P3RlbXBUb2tlbj00MXd1MTlpNnFYMzQ4TXpIU2RoeWpOY2JYQzB4ZThqQQ"
      }
    },
    {
      "attributes": {
        "createdAt": "2025-01-28T15:20:41.439Z",
        "label": "Tron (TRC20)",
        "value": "TNrqQjUx6y6SRPs1yQKqc6rmn4XwtW9y5X"
      },
      "id": "8ad44692-b680-4ef9-a160-447ecb4f8962",
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "network": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "addresses"
    },
    {
      "attributes": {
        "amountBilled": "10000.00",
        "billedChargedRate": "35.27469",
        "billedChargedRateCurrency": "TRY",
        "consolidationFee": "0.00",
        "targetTransactionFee": "2.69",
        "targetTransactionFeeCurrency": "EUR",
        "transactionFee": "100.00",
        "transactionFeeCurrency": "TRY",
        "simplifiedState": "pending"
      },
      "id": "432fc78a-660e-4fb1-8691-76dbdb0c496e",
      "relationships": {
        "exchangeQuote": {
          "data": null
        },
        "invoice": {
          "meta": {
            "included": false
          }
        },
        "txn": {
          "data": {
            "id": "432fc78a-660e-4fb1-8691-76dbdb0c496e",
            "type": "transactions"
          }
        }
      },
      "type": "invoiceTransactions"
    },
    {
      "attributes": {
        "amount": "266.17",
        "createdAt": "2025-01-28T17:13:15.084Z",
        "reference": "14c58eb0-b97e-4396-bedf-398a5e6fb8b8",
        "simplifiedState": "pending",
        "transactionType": "InvoiceTransaction"
      },
      "id": "432fc78a-660e-4fb1-8691-76dbdb0c496e",
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "transactionDetails": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "transactions"
    }
  ],
  "meta": {}
}
```

{% endtab %}

{% tab title="Status Cancelled" %}

```json
{
  "data": {
    "attributes": {
      "amountBilled": "10000.00",
      "amountCharged": "283.489380",
      "billedCurrency": "TRY",
      "chargedCurrency": "USDT",
      "chargedTargetRate": "0.9483804",
      "chargedTargetRateCurrency": "EUR",
      "createdAt": "2025-01-28T17:13:15.057Z",
      "exchangeRate": "35.27469",
      "expiresAt": "2025-01-28T17:33:14.862Z",
      "hostedPageUrl": "https://sandbox.txn.io/redirect?invoice_id=071f4b03-30d9-499e-bef7-743249d3b9ea&request_type=invoice_hosted_page&zone=eu",
      "network": "ttrx:usdt",
      "networkName": "Tron (TRC20)",
      "paymentMethods": [
        "on_chain",
        "binance_pay"
      ],
      "paymentStatus": "expecting",
      "reference": "14c58eb0-b97e-4396-bedf-398a5e6fb8b8",
      "status": "cancelled",
      "statusContext": "unpaid",
      "successRedirectUrl": "https://yahoo.com",
      "targetAmount": "266.17",
      "targetCurrency": "EUR",
      "unsuccessRedirectUrl": "https://myspace.com",
      "scAddress": null
    },
    "id": "071f4b03-30d9-499e-bef7-743249d3b9ea",
    "relationships": {
      "targetAccount": {
        "data": {
          "type": "accounts",
          "id": "13a85b45-8543-41c7-b963-394d4ea128ae"
        }
      },
      "binanceOrder": {
        "data": {
          "type": "binanceOrders",
          "id": "5e623ab4-f0fc-43df-af01-b3208aa6af0b"
        }
      },
      "address": {
        "data": {
          "id": "8ad44692-b680-4ef9-a160-447ecb4f8962",
          "type": "addresses"
        }
      },
      "coinDeposits": {
        "data": []
      },
      "invoiceTransactions": {
        "data": [
          {
            "id": "432fc78a-660e-4fb1-8691-76dbdb0c496e",
            "type": "invoiceTransactions"
          }
        ]
      },
      "refundLinks": {
        "data": []
      }
    },
    "type": "invoices"
  },
  "included": [
    {
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "type": "accounts",
      "attributes": {
        "master": false,
        "currencyCode": "EUR",
        "label": "EUR account",
        "bankReference": "BDR2891634526738095",
        "balance": "1500.00",
        "totalBalance": "1500.00",
        "bankWithdrawalAvailable": true,
        "bankDepositAvailable": true,
        "transferAvailable": true,
        "currencyType": "fiat"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "5e623ab4-f0fc-43df-af01-b3208aa6af0b",
      "type": "binanceOrders",
      "attributes": {
        "deeplink": "bnc://app.binance.com/payment/secpay?tempToken=41wu19i6qX348MzHSdhyjNcbXC0xe8jA",
        "qrContent": "https://app.binance.com/qr/dplk1d9affed91d34e019653a3d627672478",
        "qrcodeLink": "https://public.bnbstatic.com/static/payment/20250606/18e063aa-9e98-4805-a861-68119e031ea7.jpg",
        "universalUrl": "https://app.binance.com/payment/secpay?linkToken=3104f0eab7ae49a998b10752421b2d99&_dp=Ym5jOi8vYXBwLmJpbmFuY2UuY29tL3BheW1lbnQvc2VjcGF5P3RlbXBUb2tlbj00MXd1MTlpNnFYMzQ4TXpIU2RoeWpOY2JYQzB4ZThqQQ"
      }
    },
    {
      "attributes": {
        "createdAt": "2025-01-28T15:20:41.439Z",
        "label": "Tron (TRC20)",
        "value": "TNrqQjUx6y6SRPs1yQKqc6rmn4XwtW9y5X"
      },
      "id": "8ad44692-b680-4ef9-a160-447ecb4f8962",
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "network": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "addresses"
    },
    {
      "attributes": {
        "amountBilled": "10000.00",
        "billedChargedRate": "35.27469",
        "billedChargedRateCurrency": "TRY",
        "consolidationFee": "0.00",
        "targetTransactionFee": "2.69",
        "targetTransactionFeeCurrency": "EUR",
        "transactionFee": "100.00",
        "transactionFeeCurrency": "TRY",
        "simplifiedState": "pending"
      },
      "id": "432fc78a-660e-4fb1-8691-76dbdb0c496e",
      "relationships": {
        "exchangeQuote": {
          "data": null
        },
        "invoice": {
          "meta": {
            "included": false
          }
        },
        "txn": {
          "data": {
            "id": "432fc78a-660e-4fb1-8691-76dbdb0c496e",
            "type": "transactions"
          }
        }
      },
      "type": "invoiceTransactions"
    },
    {
      "attributes": {
        "amount": "266.17",
        "createdAt": "2025-01-28T17:13:15.084Z",
        "reference": "14c58eb0-b97e-4396-bedf-398a5e6fb8b8",
        "simplifiedState": "pending",
        "transactionType": "InvoiceTransaction"
      },
      "id": "432fc78a-660e-4fb1-8691-76dbdb0c496e",
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "transactionDetails": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "transactions"
    }
  ],
  "meta": {}
}
```

{% endtab %}
{% endtabs %}


# Creating invoice

<mark style="color:green;">`POST`</mark> `/api/public/v1/invoices`

This endpoint creates an invoice.

**XRP Invoice Addresses Format:**

For XRP invoices, addresses are returned in the following format:

```css
rwCQVZLSMNY6DgMH61317qvH3nHYqm68PF?dt=xyz
```

where `xyz` is a unique destination tag generated for each invoice.

A destination tag acts like a reference number in bank transfers, identifying the intended beneficiary of the transaction.

**Displaying Invoice Deposit Addresses:**

* When showing the deposit address to your customers, separate the address and the destination tag, and ensure both are clearly viewable and copyable

{% hint style="danger" %}
**Warning:** If XRP is sent to the invoice address ***without specifying the destination tag***, the deposit will ***not be processed***.
{% endhint %}

**cURL**

```bash
curl -X "POST" "https://api.sandbox.txn.io/api/public/v1/invoices" \
     -H 'Content-Type: application/vnd.api+json' \
     -H 'Authorization: Bearer <api_key>' \
     -d $'{
  "data": {
    "type": "invoices",
    "attributes": {
      "amountBilled": "10000",
      "billedCurrency": "TRY",
      "chargedCurrency": "USDT",
      "network": "TTRX:USDT",
      "targetCurrency": "EUR",
      "targetAccountId": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "reference": "bc32c092-8979-4435-b176-ae1b790b1ca6",
      "successRedirectUrl": "https://example.com/success",
      "unsuccessRedirectUrl": "https://example.com/fail",
      "paymentMethods": [
        "on_chain"
      ]
    }
  }
}'
```

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**Request Body**

<table data-full-width="false"><thead><tr><th>Name</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>data.type</td><td>string</td><td>Yes</td><td>Can only be <code>invoices</code>.</td></tr><tr><td>data.attributes.amountBilled</td><td>string</td><td>Yes</td><td>Invoice amount to display to end users. Determines the amount due after conversion.</td></tr><tr><td>data.attributes.billedCurrency</td><td>string</td><td>Yes</td><td>Invoice currency to display to end users. Refer to <a href="/pages/SA7q0b6VrvXO3W09TQfS">supported</a> currencies.</td></tr><tr><td>data.attributes.chargedCurrency</td><td>string</td><td>Yes</td><td>Cryptocurrency that the customer must pay in. Refer to <a href="/pages/SA7q0b6VrvXO3W09TQfS">supported</a> currencies.</td></tr><tr><td>data.attributes.network</td><td>string</td><td>Yes</td><td>Payment network. Refer to <a href="/pages/SA7q0b6VrvXO3W09TQfS">supported</a> networks.</td></tr><tr><td>data.attributes.targetCurrency</td><td>string</td><td>No</td><td>Specifies the account currency to which the invoice payment should be credited. Must be a tradable fiat or cryptocurrency listed on the <a href="/pages/SA7q0b6VrvXO3W09TQfS">Supported currencies</a> page — display fiat currencies are not accepted. If omitted, defaults to the value of <code>billedCurrency</code> — in which case <code>billedCurrency</code> must itself be a tradable fiat or cryptocurrency, otherwise the request returns an error.</td></tr><tr><td>data.attributes.targetAccountId</td><td>string</td><td>No</td><td>Specifies the ID of the account to which the invoice payment should be credited. Can be a master or subaccount ID. If not present, the payment will be credited to your master account by default. Requires <code>data.attributes.targetCurrency</code>.</td></tr><tr><td>data.attributes.reference</td><td>string</td><td>No</td><td>The custom reference ID to tie the invoice to end-user who pays. This can be anything you choose. Must be a unique value for each invoice you create.</td></tr><tr><td>data.attributes.successRedirectUrl</td><td>string</td><td>No</td><td>URL you want your customer to be redirected from our hosted page to if the invoice completes.</td></tr><tr><td>data.attributes.unsuccessRedirectUrl</td><td>string</td><td>No</td><td>URL you want your customer to be redirected from our hosted page to if the invoice gets expired, cancelled or rejected.</td></tr><tr><td>data.attributes.paymentMethods</td><td>array</td><td>No</td><td><p>An array listing the supported payment methods for a particular invoice. The array currently accepts exactly one value (multi-method support is reserved for future use).</p><p>Allowed values:</p><ul><li><code>"on_chain"</code> - Generates a deposit wallet address for receiving an <strong>on-chain cryptocurrency transaction</strong>. Users can send crypto directly from their wallet.</li><li><code>"binance_pay"</code> - Generates payment instructions for an <strong>off-chain payment via the Binance app</strong>, allowing users to complete the transaction within Binance.</li><li><code>"nft"</code> - Generates payment instructions for purchasing an NFT. See the <a href="/pages/wLVqKqclJ0G5RR0XGdtQ">NFT invoice integration guide</a>.</li></ul><p>If omitted, defaults to <code>["on_chain"]</code>.</p></td></tr></tbody></table>

**Response Body**

<table><thead><tr><th>Name</th><th width="97">Type</th><th>Description</th></tr></thead><tbody><tr><td>data.id</td><td>string</td><td>Invoice ID.</td></tr><tr><td>data.type</td><td>string</td><td>Entity type returned. Always <code>invoices</code>.</td></tr><tr><td>data.attributes</td><td>object</td><td>Set of invoice attributes.</td></tr><tr><td>data.attributes.amountBilled</td><td>string</td><td>Invoice amount to display to end users. Determines the amount due after conversion.</td></tr><tr><td>data.attributes.amountCharged</td><td>string</td><td>Amount due. Determines the amount of cryptocurrency the end-user is required to pay.</td></tr><tr><td>data.attributes.targetAmount</td><td>string</td><td>Amount you will receive into your target currency account.</td></tr><tr><td>data.attributes.billedCurrency</td><td>string</td><td>Invoice currency to display to end users. Determines the currency due after conversion. Refer to <a href="/pages/SA7q0b6VrvXO3W09TQfS">supported</a> currencies.</td></tr><tr><td>data.attributes.chargedCurrency</td><td>string</td><td>Cryptocurrency that the customer must pay in. Refer to <a href="/pages/SA7q0b6VrvXO3W09TQfS">supported</a> currencies.</td></tr><tr><td>data.attributes.targetCurrency</td><td>string</td><td>Settlement currency. This is the currency you will receive in your account after the payment is processed.</td></tr><tr><td>data.attributes.targetAccountId</td><td>string</td><td>The ID of the account to which the invoice payment is credited.</td></tr><tr><td>data.attributes.chargedTargetRate</td><td>string</td><td>Charged currency to target currency exchange rate.</td></tr><tr><td>data.attributes.chargedTargetRateCurrency</td><td>string</td><td>Currency in which <code>chargedTargetRate</code> is quoted.</td></tr><tr><td>data.attributes.reference</td><td>string</td><td>The custom reference ID to tie the invoice to end-user who pays. This can be anything you choose.</td></tr><tr><td>data.attributes.statusContext</td><td>string</td><td>Indicates whether the end-user paid in <code>full</code>, <code>underpaid</code>, <code>overpaid</code>, or has not paid (<code>unpaid</code>) the invoice. Refer to <a href="/pages/gi0dnWPISndBROaBxzYn">Invoice status flow</a>.</td></tr><tr><td>data.attributes.network</td><td>string</td><td>Network code. Refer to <a href="/pages/SA7q0b6VrvXO3W09TQfS">Supported currencies</a>.</td></tr><tr><td>data.attributes.networkName</td><td>string</td><td>Network name to display.</td></tr><tr><td>data.attributes.paymentMethods</td><td>array</td><td>Invoice payment methods.</td></tr><tr><td>data.attributes.status</td><td>string</td><td>Invoice status. Refer to <a href="/pages/gi0dnWPISndBROaBxzYn">Invoice status flow</a>.</td></tr><tr><td>data.attributes.successRedirectUrl</td><td>string</td><td>URL your customer will be redirected from our hosted page to if the invoice completes.</td></tr><tr><td>data.attributes.unsuccessRedirectUrl</td><td>string</td><td>URL your customer will be redirected from our hosted page to if the invoice gets expired, cancelled or rejected.</td></tr><tr><td>data.attributes.paymentStatus</td><td>string</td><td>Invoice payment status. Refer to <a href="/pages/gi0dnWPISndBROaBxzYn">Invoice status flow</a>.</td></tr><tr><td>data.attributes.exchangeRate</td><td>string</td><td>Invoice exchange rate valid for 20 minutes.</td></tr><tr><td>data.attributes.expiresAt</td><td>string</td><td>Invoice expiry date and time.</td></tr><tr><td>data.attributes.createdAt</td><td>string</td><td>Date and time invoice was created at.</td></tr><tr><td>data.attributes.hostedPageUrl</td><td>string</td><td>Invoice hosted page.</td></tr><tr><td>data.attributes.scAddress</td><td>string</td><td>Smart contract address configured for the NFT payment feature. Returns <code>null</code> if the feature is not enabled on the merchant account.</td></tr><tr><td>included.type(addresses).attributes</td><td>object</td><td>Invoice receiving address. This is the address the end-user must send their cryptocurrency payment to.</td></tr><tr><td>included.type(binanceOrders).attributes</td><td>object</td><td>Payment instructions for an off-chain payment via the Binance application.</td></tr><tr><td>included.type(accounts).attributes</td><td>object</td><td>The target account the invoice payment is credited to. Includes standard account fields: <code>currencyCode</code>, <code>balance</code>, <code>bankWithdrawalAvailable</code>, <code>bankDepositAvailable</code>, <code>transferAvailable</code>, etc.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="HTTP 201" %}

```json
{
  "data": {
    "id": "ab0fbca0-a6b1-41af-95c7-b2ae4595f72d",
    "type": "invoices",
    "attributes": {
      "amountBilled": "1000.00",
      "amountCharged": "140.743359",
      "targetAmount": "119.73",
      "billedCurrency": "CNY",
      "chargedCurrency": "USDT",
      "targetCurrency": "EUR",
      "chargedTargetRate": "0.8593002",
      "chargedTargetRateCurrency": "EUR",
      "reference": "eef67ca4-286b-4c75-ad79-4f313c582c40",
      "statusContext": "unpaid",
      "network": "ttrx:usdt",
      "networkName": "Tron (TRC20)",
      "paymentMethods": [
        "on_chain"
      ],
      "status": "pending",
      "successRedirectUrl": "https://paymentsucceeded.com",
      "unsuccessRedirectUrl": "https://paymentfailed.com",
      "paymentStatus": "expecting",
      "exchangeRate": "7.105131",
      "expiresAt": "2025-06-20T14:46:32.246Z",
      "createdAt": "2025-06-20T12:46:32.342Z",
      "hostedPageUrl": "https://sandbox.txn.io/redirect?invoice_id=ab0fbca0-a6b1-41af-95c7-b2ae4595f72d&request_type=invoice_hosted_page&zone=eu",
      "scAddress": null
    },
    "relationships": {
      "targetAccount": {
        "data": {
          "type": "accounts",
          "id": "13a85b45-8543-41c7-b963-394d4ea128ae"
        }
      },
      "binanceOrder": {
        "data": null
      },
      "address": {
        "data": {
          "type": "addresses",
          "id": "40402ed1-9bca-4ae8-9c33-1eff05280a2d"
        }
      },
      "refundLinks": {
        "meta": {
          "included": false
        }
      },
      "invoiceTransactions": {
        "meta": {
          "included": false
        }
      },
      "coinDeposits": {
        "meta": {
          "included": false
        }
      }
    }
  },
  "included": [
    {
      "id": "40402ed1-9bca-4ae8-9c33-1eff05280a2d",
      "type": "addresses",
      "attributes": {
        "label": "Tron (TRC20)",
        "value": "TCg2JQZSVJLufjzw6nodJiX5zkjtHK45sq",
        "createdAt": "2025-06-19T07:39:11.939Z"
      },
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "network": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "type": "accounts",
      "attributes": {
        "master": true,
        "currencyCode": "EUR",
        "label": "master",
        "bankReference": "BDR6421088115176062",
        "balance": "38178.42",
        "totalBalance": null,
        "bankWithdrawalAvailable": true,
        "bankDepositAvailable": true,
        "transferAvailable": true,
        "currencyType": "fiat"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        },
        "txnBankCredentials": {
          "meta": {
            "included": false
          }
        }
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "title": "amount is below minimum",
      "detail": "amount: 10.0, minimum: 30.00",
      "code": "amount_below_minimum"
    }
  ]
}
```

Amount too low.
{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "title": "amount is above maximum",
      "detail": "amount: 500000.0, maximum: 100000.00",
      "code": "amount_above_maximum"
    }
  ]
}
```

Amount too high.
{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "title": "Invalid attribute",
      "detail": "Reference has already been taken",
      "code": "invoice_invalid",
      "source": {
        "pointer": "/data/attributes/externalId"
      }
    }
  ]
}
```

Duplicate reference.
{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "not allowed use multiple payment methods",
      "code": "payment_methods_conflict",
      "detail": ""
    }
  ]
}
```

{% endtab %}
{% endtabs %}


# Reading invoice

<mark style="color:green;">`GET`</mark> `/api/public/v1/invoices/:id`

This endpoint returns details of a particular invoice by its ID.

**Headers**

| Name         | Value                      |
| ------------ | -------------------------- |
| Content-Type | `application/vnd.api+json` |

**Path Parameters**

| Name | Value      |
| ---- | ---------- |
| id   | Invoice ID |

**Response Body**

<table><thead><tr><th>Name</th><th width="97">Type</th><th>Description</th></tr></thead><tbody><tr><td>data.id</td><td>string</td><td>Invoice ID.</td></tr><tr><td>data.type</td><td>string</td><td>Entity type returned. Always <code>invoices</code>.</td></tr><tr><td>data.attributes</td><td>object</td><td>Set of invoice attributes.</td></tr><tr><td>data.attributes.amountBilled</td><td>string</td><td>Invoice amount to display to end users. Determines the amount due after conversion.</td></tr><tr><td>data.attributes.amountCharged</td><td>string</td><td>Amount due. Determines the amount of cryptocurrency the end-user is required to pay.</td></tr><tr><td>data.attributes.targetAmount</td><td>string</td><td>Amount you will receive into your target currency account.</td></tr><tr><td>data.attributes.billedCurrency</td><td>string</td><td>Invoice currency to display to end users. Determines the currency due after conversion. Refer to <a href="/pages/SA7q0b6VrvXO3W09TQfS">supported</a> currencies.</td></tr><tr><td>data.attributes.chargedCurrency</td><td>string</td><td>Cryptocurrency that the customer must pay in. Refer to <a href="/pages/SA7q0b6VrvXO3W09TQfS">supported</a> currencies.</td></tr><tr><td>data.attributes.targetCurrency</td><td>string</td><td>Settlement currency. This is the currency you will receive in your account after the payment is processed.</td></tr><tr><td>data.attributes.targetAccountId</td><td>string</td><td>The ID of the account to which the invoice payment is credited.</td></tr><tr><td>data.attributes.chargedTargetRate</td><td>string</td><td>Charged currency to target currency exchange rate.</td></tr><tr><td>data.attributes.chargedTargetRateCurrency</td><td>string</td><td>Currency in which <code>chargedTargetRate</code> is quoted.</td></tr><tr><td>data.attributes.reference</td><td>string</td><td>The custom reference ID to tie the invoice to end-user who pays. This can be anything you choose.</td></tr><tr><td>data.attributes.statusContext</td><td>string</td><td>Indicates whether the end-user paid in <code>full</code>, <code>underpaid</code>, <code>overpaid</code>, or has not paid (<code>unpaid</code>) the invoice. Refer to <a href="/pages/gi0dnWPISndBROaBxzYn">Invoice status flow</a>.</td></tr><tr><td>data.attributes.network</td><td>string</td><td>Network code. Refer to <a href="/pages/SA7q0b6VrvXO3W09TQfS">Supported currencies</a>.</td></tr><tr><td>data.attributes.networkName</td><td>string</td><td>Network name to display.</td></tr><tr><td>data.attributes.paymentMethods</td><td>array</td><td>Invoice payment methods.</td></tr><tr><td>data.attributes.status</td><td>string</td><td>Invoice status. Refer to <a href="/pages/gi0dnWPISndBROaBxzYn">Invoice status flow</a>.</td></tr><tr><td>data.attributes.successRedirectUrl</td><td>string</td><td>URL your customer will be redirected from our hosted page to if the invoice completes.</td></tr><tr><td>data.attributes.unsuccessRedirectUrl</td><td>string</td><td>URL your customer will be redirected from our hosted page to if the invoice gets expired, cancelled or rejected.</td></tr><tr><td>data.attributes.paymentStatus</td><td>string</td><td>Invoice payment status. Refer to <a href="/pages/gi0dnWPISndBROaBxzYn">Invoice status flow</a>.</td></tr><tr><td>data.attributes.exchangeRate</td><td>string</td><td>Invoice exchange rate valid for 20 minutes.</td></tr><tr><td>data.attributes.expiresAt</td><td>string</td><td>Invoice expiry date and time.</td></tr><tr><td>data.attributes.createdAt</td><td>string</td><td>Date and time invoice was created at.</td></tr><tr><td>data.attributes.hostedPageUrl</td><td>string</td><td>Invoice hosted page.</td></tr><tr><td>data.attributes.scAddress</td><td>string</td><td>Smart contract address configured for the NFT payment feature. Returns <code>null</code> if the feature is not enabled on the merchant account.</td></tr><tr><td>included.type(addresses).attributes</td><td>object</td><td>Invoice receiving address. This is the address the end-user must send their cryptocurrency payment to.</td></tr><tr><td>included.type(binanceOrders).attributes</td><td>object</td><td>Payment instructions for an off-chain payment via the Binance application.</td></tr><tr><td>included.type(coinTransactions).attributes</td><td>object</td><td>Details of a crypto payment received at the invoice address, including <code>txHash</code>, <code>currencyCode</code>, <code>amount</code>, and other related fields.</td></tr><tr><td>included.type(coinTransactions).attributes.sourceAddresses</td><td>array</td><td>Wallet address(es) the funds were sent from. Typically a single address; may contain multiple entries when the deposit arrived via a UTXO-based network (BTC, LTC, BCH, DOGE, etc.) and the sender's wallet combined several inputs.</td></tr><tr><td>included.type(invoiceTransactions).attributes</td><td>object</td><td>Details of the invoice transaction, including <code>billedChargedRate</code>, <code>transactionFee</code>, <code>targetTransactionFee</code>, and related fields.</td></tr><tr><td>included.type(invoiceTransactions).attributes.amountBilled</td><td>string</td><td>The actual payment amount in <code>billedCurrency</code>, reflecting what the end-user's crypto payment converted to. Use this field to credit the end-user's balance on your platform. In a full payment it equals the original invoice amount; for underpayments and overpayments, Txn applies the spot exchange rate to the crypto actually received, so this value will differ. Pre-fee — see <code>transactionFee</code> and <code>targetTransactionFee</code> for the fee breakdown.</td></tr><tr><td>included.type(apiKeys).attributes</td><td>object</td><td>Details of the API key that created the invoice, including <code>name</code> and <code>createdAt</code>.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": {
    "id": "ab0fbca0-a6b1-41af-95c7-b2ae4595f72d",
    "type": "invoices",
    "attributes": {
      "amountBilled": "1000.00",
      "amountCharged": "140.743359",
      "targetAmount": "119.73",
      "billedCurrency": "CNY",
      "chargedCurrency": "USDT",
      "targetCurrency": "EUR",
      "chargedTargetRate": "0.8593002",
      "chargedTargetRateCurrency": "EUR",
      "reference": "eef67ca4-286b-4c75-ad79-4f313c582c40",
      "statusContext": "underpaid",
      "network": "ttrx:usdt",
      "networkName": "Tron (TRC20)",
      "paymentMethods": [
        "on_chain"
      ],
      "status": "completed",
      "successRedirectUrl": "https://paymentsucceeded.com",
      "unsuccessRedirectUrl": "https://paymentfailed.com",
      "paymentStatus": "on_time",
      "exchangeRate": "7.105131",
      "expiresAt": "2025-06-20T14:46:32.246Z",
      "createdAt": "2025-06-20T12:46:32.342Z",
      "hostedPageUrl": "https://sandbox.txn.io/redirect?invoice_id=ab0fbca0-a6b1-41af-95c7-b2ae4595f72d&request_type=invoice_hosted_page&zone=eu",
      "scAddress": null
    },
    "relationships": {
      "targetAccount": {
        "data": {
          "type": "accounts",
          "id": "13a85b45-8543-41c7-b963-394d4ea128ae"
        }
      },
      "binanceOrder": {
        "data": null
      },
      "address": {
        "data": {
          "type": "addresses",
          "id": "40402ed1-9bca-4ae8-9c33-1eff05280a2d"
        }
      },
      "refundLinks": {
        "data": []
      },
      "invoiceTransactions": {
        "data": [
          {
            "type": "invoiceTransactions",
            "id": "1ab6e545-ec8e-4670-aaba-29c79e9d88f5"
          }
        ]
      },
      "coinDeposits": {
        "data": [
          {
            "type": "coinTransactions",
            "id": "289a039f-6821-48e1-b311-1167563e5855"
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": "40402ed1-9bca-4ae8-9c33-1eff05280a2d",
      "type": "addresses",
      "attributes": {
        "label": "Tron (TRC20)",
        "value": "TCg2JQZSVJLufjzw6nodJiX5zkjtHK45sq",
        "createdAt": "2025-06-19T07:39:11.939Z"
      },
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "network": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "1ab6e545-ec8e-4670-aaba-29c79e9d88f5",
      "type": "invoiceTransactions",
      "attributes": {
        "amountBilled": "703.41",
        "billedChargedRate": "7.105131",
        "billedChargedRateCurrency": "CNY",
        "consolidationFee": "0.00",
        "transactionFee": "7.03",
        "transactionFeeCurrency": "CNY",
        "targetTransactionFee": "0.85",
        "targetTransactionFeeCurrency": "EUR",
        "simplifiedState": "completed"
      },
      "relationships": {
        "txn": {
          "data": {
            "type": "transactions",
            "id": "1ab6e545-ec8e-4670-aaba-29c79e9d88f5"
          }
        },
        "exchangeQuote": {
          "data": {
            "type": "exchangeQuotes",
            "id": "363a412f-dd92-4f03-88b9-1605dece439c"
          }
        },
        "invoice": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "289a039f-6821-48e1-b311-1167563e5855",
      "type": "coinTransactions",
      "attributes": {
        "txHash": "0c772b228a03d15beb83603b2b2ab5905c808940877d28e8d27445a4e239daa7",
        "currencyCode": "USDT",
        "createdAt": "2025-06-20T12:48:51.234Z",
        "state": "processed",
        "amount": "99.000000",
        "accountId": "e289de2b-37bd-4eff-b832-f754c31a2d95",
        "sourceAddresses": [
          "TTbGTMwUwA3mncLP7xqCZei1ekaNSgeAJe"
        ],
        "simplifiedState": "processed"
      },
      "relationships": {
        "network": {
          "meta": {
            "included": false
          }
        },
        "address": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "1ab6e545-ec8e-4670-aaba-29c79e9d88f5",
      "type": "transactions",
      "attributes": {
        "createdAt": "2025-06-20T12:49:01.324Z",
        "simplifiedState": "completed",
        "transactionType": "InvoiceTransaction",
        "amount": "84.29",
        "currency": "EUR",
        "balance": null,
        "reference": "eef67ca4-286b-4c75-ad79-4f313c582c40",
        "accountId": "13a85b45-8543-41c7-b963-394d4ea128ae"
      },
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "transactionDetails": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "363a412f-dd92-4f03-88b9-1605dece439c",
      "type": "exchangeQuotes",
      "attributes": {
        "expiresAt": "2025-06-20T12:49:31.478Z",
        "amountCharged": "99.0",
        "amountReceived": "85.14",
        "rate": "0.8600328",
        "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
          }
        }
      }
    },
    {
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "type": "accounts",
      "attributes": {
        "master": true,
        "currencyCode": "EUR",
        "label": "master",
        "bankReference": "BDR6421088115176062",
        "balance": "38202.60",
        "totalBalance": null,
        "bankWithdrawalAvailable": true,
        "bankDepositAvailable": true,
        "transferAvailable": true,
        "currencyType": "fiat"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        },
        "txnBankCredentials": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "45550837-2dc6-4652-9cbf-bfbe4e16382e",
      "type": "apiKeys",
      "attributes": {
        "name": "Test API key",
        "createdAt": "2024-06-17T19:41:33.398Z"
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}

{% tab title="HTTP 404" %}

```json
{
  "errors": [
    {
      "status": 404,
      "title": "Record not found",
      "code": "invoice_not_found",
      "detail": "Invoice not found"
    }
  ]
}
```

{% endtab %}
{% endtabs %}


# Listing invoices

<mark style="color:green;">`GET`</mark> `/api/public/v1/invoices`

This endpoint returns a list of invoices with pagination.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**URL Parameters**

<table><thead><tr><th width="164.692626953125">Name</th><th width="142.010009765625">Type</th><th>Description</th></tr></thead><tbody><tr><td>order</td><td>string</td><td>Field to order the list of invoices by. Currently the only supported value is <code>created_at</code>.</td></tr><tr><td>order_type</td><td>string</td><td>Order type. Can be either <code>asc</code> or <code>desc</code>.</td></tr><tr><td>page</td><td>number</td><td>Page for which you want to return invoices.</td></tr><tr><td>per_page</td><td>number</td><td>Number of invoices per page to return.</td></tr><tr><td>reference</td><td>string</td><td>Invoice <code>reference</code>.</td></tr><tr><td>created_at_from</td><td>string</td><td>Date and time filter. Supports timestamps in ISO 8601 format, e.g. <code>2024-06-18T15:49:02.031Z</code>.</td></tr><tr><td>created_at_to</td><td>string</td><td>Date and time filter. Supports timestamps in ISO 8601 format, e.g. <code>2024-06-18T15:49:02.031Z</code>.</td></tr></tbody></table>

**Response Body**

<table><thead><tr><th>Name</th><th width="97">Type</th><th>Description</th></tr></thead><tbody><tr><td>data[].id</td><td>string</td><td>Invoice ID.</td></tr><tr><td>data[].type</td><td>string</td><td>Entity type returned. Always <code>invoices</code>.</td></tr><tr><td>data[].attributes</td><td>object</td><td>Set of invoice attributes.</td></tr><tr><td>data[].attributes.amountBilled</td><td>string</td><td>Invoice amount to display to end users. Determines the amount due after conversion.</td></tr><tr><td>data[].attributes.amountCharged</td><td>string</td><td>Amount due. Determines the amount of cryptocurrency the end-user is required to pay.</td></tr><tr><td>data[].attributes.targetAmount</td><td>string</td><td>Amount you will receive into your target currency account.</td></tr><tr><td>data[].attributes.billedCurrency</td><td>string</td><td>Invoice currency to display to end users. Determines the currency due after conversion. Refer to <a href="/pages/SA7q0b6VrvXO3W09TQfS">supported</a> currencies.</td></tr><tr><td>data[].attributes.chargedCurrency</td><td>string</td><td>Cryptocurrency that the customer must pay in. Refer to <a href="/pages/SA7q0b6VrvXO3W09TQfS">supported</a> currencies.</td></tr><tr><td>data[].attributes.targetCurrency</td><td>string</td><td>Settlement currency. This is the currency you will receive in your account after the payment is processed.</td></tr><tr><td>data[].attributes.chargedTargetRate</td><td>string</td><td>Charged currency to target currency exchange rate.</td></tr><tr><td>data[].attributes.chargedTargetRateCurrency</td><td>string</td><td>Currency in which <code>chargedTargetRate</code> is quoted.</td></tr><tr><td>data[].attributes.reference</td><td>string</td><td>The custom reference ID to tie the invoice to end-user who pays. This can be anything you choose.</td></tr><tr><td>data[].attributes.statusContext</td><td>string</td><td>Indicates whether the end-user paid in <code>full</code>, <code>underpaid</code>, <code>overpaid</code>, or has not paid (<code>unpaid</code>) the invoice. Refer to <a href="/pages/gi0dnWPISndBROaBxzYn">Invoice status flow</a>.</td></tr><tr><td>data[].attributes.network</td><td>string</td><td>Network code. Refer to <a href="/pages/SA7q0b6VrvXO3W09TQfS">Supported currencies</a>.</td></tr><tr><td>data[].attributes.networkName</td><td>string</td><td>Network name to display.</td></tr><tr><td>data[].attributes.paymentMethods</td><td>array</td><td>Invoice payment methods.</td></tr><tr><td>data[].attributes.status</td><td>string</td><td>Invoice status. Refer to <a href="/pages/gi0dnWPISndBROaBxzYn">Invoice status flow</a>.</td></tr><tr><td>data[].attributes.successRedirectUrl</td><td>string</td><td>URL your customer will be redirected from our hosted page to if the invoice completes.</td></tr><tr><td>data[].attributes.unsuccessRedirectUrl</td><td>string</td><td>URL your customer will be redirected from our hosted page to if the invoice gets expired, cancelled or rejected.</td></tr><tr><td>data[].attributes.paymentStatus</td><td>string</td><td>Invoice payment status. Refer to <a href="/pages/gi0dnWPISndBROaBxzYn">Invoice status flow</a>.</td></tr><tr><td>data[].attributes.exchangeRate</td><td>string</td><td>Invoice exchange rate valid for 20 minutes.</td></tr><tr><td>data[].attributes.expiresAt</td><td>string</td><td>Invoice expiry date and time.</td></tr><tr><td>data[].attributes.createdAt</td><td>string</td><td>Date and time invoice was created at.</td></tr><tr><td>data[].attributes.hostedPageUrl</td><td>string</td><td>Invoice hosted page.</td></tr><tr><td>data[].attributes.scAddress</td><td>string</td><td>Smart contract address for the NFT payment feature. <code>null</code> when not enabled.</td></tr><tr><td>data[].relationships.targetAccount.type</td><td>string</td><td>Entity type of the settlement account. Always <code>accounts</code>.</td></tr><tr><td>data[].relationships.targetAccount.id</td><td>string</td><td>ID of the account to which the invoice payment is credited.</td></tr><tr><td>included[].type(addresses).attributes</td><td>object</td><td>Invoice receiving address. This is the address the end-user must send their cryptocurrency payment to.</td></tr><tr><td>included[].type(binanceOrders).attributes</td><td>object</td><td>Payment instructions for an off-chain payment via the Binance application.</td></tr><tr><td>included[].type(coinTransactions).attributes</td><td>object</td><td>Details of a crypto payment received at the invoice address, including <code>txHash</code>, <code>currencyCode</code>, <code>amount</code>, and other related fields.</td></tr><tr><td>included[].type(invoiceTransactions).attributes</td><td>object</td><td>Details of the invoice transaction, including <code>billedChargedRate</code>, <code>transactionFee</code>, <code>targetTransactionFee</code>, and related fields.</td></tr><tr><td>included[].type(invoiceTransactions).attributes.amountBilled</td><td>string</td><td>The actual payment amount in <code>billedCurrency</code>, reflecting what the end-user's crypto payment converted to. Use this field to credit the end-user's balance on your platform. In a full payment it equals the original invoice amount; for underpayments and overpayments, Txn applies the spot exchange rate to the crypto actually received, so this value will differ. Pre-fee — see <code>transactionFee</code> and <code>targetTransactionFee</code> for the fee breakdown.</td></tr><tr><td>included[].type(apiKeys).attributes.name</td><td>string</td><td>Name of the API key that created the invoice.</td></tr><tr><td>included[].type(apiKeys).attributes.createdAt</td><td>string</td><td>Timestamp when the API key was created.</td></tr><tr><td>meta.page</td><td>number</td><td>Current page number.</td></tr><tr><td>meta.per_page</td><td>number</td><td>Page size used for the response.</td></tr><tr><td>meta.total</td><td>number</td><td>Total number of invoices matching the query.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": [
    {
      "id": "806f822f-7e7c-440e-bb2d-cba36e4ad6f2",
      "type": "invoices",
      "attributes": {
        "amountBilled": "33.00",
        "amountCharged": "33.365698",
        "targetAmount": "27.76",
        "billedCurrency": "USD",
        "chargedCurrency": "USDT",
        "targetCurrency": "EUR",
        "chargedTargetRate": "0.85512683728197",
        "chargedTargetRateCurrency": "EUR",
        "reference": "dd171c10-f246-4888-9759-ee39009745bf",
        "statusContext": "unpaid",
        "network": "ttrx:usdt",
        "networkName": "Tron (TRC20)",
        "paymentMethods": [
          "on_chain"
        ],
        "status": "cancelled",
        "successRedirectUrl": null,
        "unsuccessRedirectUrl": null,
        "paymentStatus": "expecting",
        "exchangeRate": "0.9890397",
        "expiresAt": "2026-01-19T10:07:54.355Z",
        "createdAt": "2026-01-19T07:07:54.483Z",
        "hostedPageUrl": "https://sandbox.txn.io/redirect?invoice_id=806f822f-7e7c-440e-bb2d-cba36e4ad6f2&request_type=invoice_hosted_page&zone=eu",
        "scAddress": null
      },
      "relationships": {
        "targetAccount": {
          "data": {
            "type": "accounts",
            "id": "adb0f9c4-c7fd-4989-a273-1bd11ad5847b"
          }
        },
        "binanceOrder": {
          "data": null
        },
        "address": {
          "data": {
            "type": "addresses",
            "id": "525d85d7-a0c5-47ad-a775-eb2a6375b706"
          }
        },
        "refundLinks": {
          "data": []
        },
        "invoiceTransactions": {
          "data": [
            {
              "type": "invoiceTransactions",
              "id": "307f4dc9-5395-4a7b-b78d-7484985f7166"
            }
          ]
        },
        "coinDeposits": {
          "data": []
        }
      }
    },
    {
      "id": "9506769e-295d-4d9e-b371-9995dc91fba0",
      "type": "invoices",
      "attributes": {
        "amountBilled": "1000.00",
        "amountCharged": "23.123807",
        "targetAmount": "22.33",
        "billedCurrency": "TRY",
        "chargedCurrency": "USDT",
        "targetCurrency": "USD",
        "chargedTargetRate": "0.99926",
        "chargedTargetRateCurrency": "USD",
        "reference": "edeaa162-3b95-4aa1-b800-b1efa24fbcb6",
        "statusContext": "unpaid",
        "network": "ttrx:usdt",
        "networkName": "Tron (TRC20)",
        "paymentMethods": [
          "on_chain"
        ],
        "status": "cancelled",
        "successRedirectUrl": null,
        "unsuccessRedirectUrl": null,
        "paymentStatus": "expecting",
        "exchangeRate": "43.24547465",
        "expiresAt": "2026-01-17T15:58:58.652Z",
        "createdAt": "2026-01-17T12:58:59.186Z",
        "hostedPageUrl": "https://sandbox.txn.io/redirect?invoice_id=9506769e-295d-4d9e-b371-9995dc91fba0&request_type=invoice_hosted_page&zone=eu",
        "scAddress": null
      },
      "relationships": {
        "targetAccount": {
          "data": {
            "type": "accounts",
            "id": "80b8dd61-35bc-49cc-9e04-f2c0f741a096"
          }
        },
        "binanceOrder": {
          "data": null
        },
        "address": {
          "data": {
            "type": "addresses",
            "id": "f83db4c7-b86c-4b45-8009-2c9d042eac1d"
          }
        },
        "refundLinks": {
          "data": []
        },
        "invoiceTransactions": {
          "data": [
            {
              "type": "invoiceTransactions",
              "id": "7f044fef-f685-4a11-9fac-da5d962ade97"
            }
          ]
        },
        "coinDeposits": {
          "data": []
        }
      }
    }
  ],
  "included": [
    {
      "id": "adb0f9c4-c7fd-4989-a273-1bd11ad5847b",
      "type": "accounts",
      "attributes": {
        "master": false,
        "currencyCode": "EUR",
        "label": "EUR_4",
        "bankReference": "BDR0154632342411086",
        "balance": "31.63",
        "totalBalance": "31.63",
        "bankWithdrawalAvailable": true,
        "bankDepositAvailable": true,
        "transferAvailable": true,
        "currencyType": "fiat"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "525d85d7-a0c5-47ad-a775-eb2a6375b706",
      "type": "addresses",
      "attributes": {
        "label": "Tron (TRC20)",
        "value": "TDa95SveS24fbYATjn59jYdXNAxgpHdvbZ",
        "createdAt": "2026-01-13T07:13:30.951Z"
      },
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "network": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "307f4dc9-5395-4a7b-b78d-7484985f7166",
      "type": "invoiceTransactions",
      "attributes": {
        "amountBilled": "33.00",
        "billedChargedRate": "0.9890397",
        "billedChargedRateCurrency": "USD",
        "consolidationFee": "0.56",
        "transactionFee": "0.33",
        "transactionFeeCurrency": "USD",
        "targetTransactionFee": "0.29",
        "targetTransactionFeeCurrency": "EUR",
        "simplifiedState": "pending"
      },
      "relationships": {
        "txn": {
          "data": {
            "type": "transactions",
            "id": "307f4dc9-5395-4a7b-b78d-7484985f7166"
          }
        },
        "exchangeQuote": {
          "data": null
        },
        "account": {
          "meta": {
            "included": false
          }
        },
        "invoice": {
          "meta": {
            "included": false
          }
        },
        "author": {
          "data": {
            "type": "apiKeys",
            "id": "9c4b8ebd-ae0b-4812-a97b-92d8359fd1e0"
          }
        }
      }
    },
    {
      "id": "80b8dd61-35bc-49cc-9e04-f2c0f741a096",
      "type": "accounts",
      "attributes": {
        "master": true,
        "currencyCode": "USD",
        "label": "master",
        "bankReference": "BDR3455470827278341",
        "balance": "3614.05",
        "totalBalance": "3839.43",
        "bankWithdrawalAvailable": false,
        "bankDepositAvailable": true,
        "transferAvailable": true,
        "currencyType": "fiat"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "f83db4c7-b86c-4b45-8009-2c9d042eac1d",
      "type": "addresses",
      "attributes": {
        "label": "Tron (TRC20)",
        "value": "TXXnCyP46NcyH5aiM9LDx9him1kbWYJJmQ",
        "createdAt": "2026-01-12T18:04:40.953Z"
      },
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "network": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "7f044fef-f685-4a11-9fac-da5d962ade97",
      "type": "invoiceTransactions",
      "attributes": {
        "amountBilled": "1000.00",
        "billedChargedRate": "43.24547465",
        "billedChargedRateCurrency": "TRY",
        "consolidationFee": "23.73",
        "transactionFee": "10.00",
        "transactionFeeCurrency": "TRY",
        "targetTransactionFee": "0.23",
        "targetTransactionFeeCurrency": "USD",
        "simplifiedState": "pending"
      },
      "relationships": {
        "txn": {
          "data": {
            "type": "transactions",
            "id": "7f044fef-f685-4a11-9fac-da5d962ade97"
          }
        },
        "exchangeQuote": {
          "data": null
        },
        "account": {
          "meta": {
            "included": false
          }
        },
        "invoice": {
          "meta": {
            "included": false
          }
        },
        "author": {
          "data": {
            "type": "apiKeys",
            "id": "b56961f4-46cf-4e60-bb32-b36addb09f66"
          }
        }
      }
    },
    {
      "id": "307f4dc9-5395-4a7b-b78d-7484985f7166",
      "type": "transactions",
      "attributes": {
        "createdAt": "2026-01-19T07:07:54.527Z",
        "simplifiedState": "pending",
        "transactionType": "InvoiceTransaction",
        "amount": "27.76",
        "currency": "EUR",
        "balance": null,
        "reference": "dd171c10-f246-4888-9759-ee39009745bf",
        "accountId": "adb0f9c4-c7fd-4989-a273-1bd11ad5847b"
      },
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "transactionDetails": {
          "meta": {
            "included": false
          }
        },
        "author": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "9c4b8ebd-ae0b-4812-a97b-92d8359fd1e0",
      "type": "apiKeys",
      "attributes": {
        "name": "My API Key",
        "createdAt": "2025-07-04T08:07:13.549Z"
      }
    },
    {
      "id": "7f044fef-f685-4a11-9fac-da5d962ade97",
      "type": "transactions",
      "attributes": {
        "createdAt": "2026-01-17T12:58:59.293Z",
        "simplifiedState": "pending",
        "transactionType": "InvoiceTransaction",
        "amount": "22.33",
        "currency": "USD",
        "balance": null,
        "reference": "edeaa162-3b95-4aa1-b800-b1efa24fbcb6",
        "accountId": "80b8dd61-35bc-49cc-9e04-f2c0f741a096"
      },
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "transactionDetails": {
          "meta": {
            "included": false
          }
        },
        "author": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "9c4b8ebd-ae0b-4812-a97b-92d8359fd1e0",
      "type": "apiKeys",
      "attributes": {
        "name": "My API Key",
        "createdAt": "2025-07-04T08:07:13.549Z"
      }
    },
    {
      "id": "b56961f4-46cf-4e60-bb32-b36addb09f66",
      "type": "apiKeys",
      "attributes": {
        "name": "Test API key",
        "createdAt": "2024-06-17T19:41:33.398Z"
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 2,
    "total": 4637
  },
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}


# 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>                                                                                                                                       |

{% hint style="info" %}

* Network and service fees are deducted from the refund amount.
* If the received crypto payment meets one of the refund flow conditions but is less than the total network and service fees, txn will not generate a refund link.

\
Please keep this in mind when integrating the refund feature on your end.
{% 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=85611c70-0f0f-497e-a5d1-b5f46c1e09f1&request_type=payment_link_hosted_page&zone=eu`
* 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 example of an invoice payload containing a **refundLinks** object:

<details>

<summary>Invoice payload</summary>

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

```json
{
  "data": {
    "attributes": {
      "amountBilled": "50.00",
      "amountCharged": "50.469722",
      "billedCurrency": "USD",
      "chargedCurrency": "USDT",
      "chargedTargetRate": "0.990693",
      "chargedTargetRateCurrency": "USD",
      "createdAt": "2025-10-16T20:39:56.888Z",
      "exchangeRate": "0.990693",
      "expiresAt": "2025-10-16T22:39:56.635Z",
      "hostedPageUrl": "https://sandbox.txn.io/redirect?invoice_id=c63e4f48-b7ea-4cb0-a7f1-9cc0cb222da1&request_type=invoice_hosted_page&zone=eu",
      "network": "ttrx:usdt",
      "networkName": "Tron (TRC20)",
      "paymentMethods": [
        "on_chain"
      ],
      "paymentStatus": "on_time",
      "reference": "111956dd-48da-4cec-815f-95ff600aae41",
      "status": "cancelled",
      "statusContext": "unpaid",
      "successRedirectUrl": null,
      "targetAmount": "49.50",
      "targetCurrency": "USD",
      "unsuccessRedirectUrl": null
    },
    "id": "c63e4f48-b7ea-4cb0-a7f1-9cc0cb222da1",
    "relationships": {
      "address": {
        "data": {
          "id": "79a994cd-6fa4-4109-b658-b0f8a2be5af8",
          "type": "addresses"
        }
      },
      "binanceOrder": {
        "data": null
      },
      "coinDeposits": {
        "data": [
          {
            "id": "327c2e54-055d-406b-a696-7130168ab919",
            "type": "coinTransactions"
          }
        ]
      },
      "invoiceTransactions": {
        "data": [
          {
            "id": "88b6c18a-a754-4ed1-8dc5-7d18a40062f8",
            "type": "invoiceTransactions"
          }
        ]
      },
      "refundLinks": {
        "data": [
          {
            "id": "85611c70-0f0f-497e-a5d1-b5f46c1e09f1",
            "type": "paymentLinks"
          }
        ]
      }
    },
    "type": "invoices"
  },
  "included": [
    {
      "attributes": {
        "createdAt": "2025-10-16T09:52:56.145Z",
        "label": "Tron (TRC20)",
        "value": "TB9CkPT1iy8osQTNjiLS94MfVmiXcXwDDC"
      },
      "id": "79a994cd-6fa4-4109-b658-b0f8a2be5af8",
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "network": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "addresses"
    },
    {
      "attributes": {
        "accountCurrency": "USDT",
        "amount": "20.000000",
        "createdAt": "2025-10-16T20:42:00.541Z",
        "currency": "USDT",
        "expiresAt": "2026-01-16T20:42:00.000Z",
        "hostedPageUrl": "https://sandbox.txn.io/redirect?payment_link_id=85611c70-0f0f-497e-a5d1-b5f46c1e09f1&request_type=payment_link_hosted_page&zone=eu",
        "network": "ttrx:usdt",
        "networkName": "Tron (TRC20)",
        "paymentType": "Refund",
        "reference": "REFUND-111956dd-48da-4cec-815f-95ff600aae41-1760647320",
        "status": "created",
        "successRedirectUrl": null,
        "unsuccessRedirectUrl": null
      },
      "id": "85611c70-0f0f-497e-a5d1-b5f46c1e09f1",
      "relationships": {
        "target": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "paymentLinks"
    },
    {
      "attributes": {
        "amountBilled": "50.00",
        "billedChargedRate": "0.990693",
        "billedChargedRateCurrency": "USD",
        "consolidationFee": "0.00",
        "simplifiedState": "cancelled",
        "targetTransactionFee": "0.50",
        "targetTransactionFeeCurrency": "USD",
        "transactionFee": "0.50",
        "transactionFeeCurrency": "USD"
      },
      "id": "88b6c18a-a754-4ed1-8dc5-7d18a40062f8",
      "relationships": {
        "author": {
          "meta": {
            "included": false
          }
        },
        "exchangeQuote": {
          "data": null
        },
        "invoice": {
          "meta": {
            "included": false
          }
        },
        "txn": {
          "data": {
            "id": "88b6c18a-a754-4ed1-8dc5-7d18a40062f8",
            "type": "transactions"
          }
        }
      },
      "type": "invoiceTransactions"
    },
    {
      "attributes": {
        "accountId": "e289de2b-37bd-4eff-b832-f754c31a2d95",
        "amount": "20.000000",
        "createdAt": "2025-10-16T20:41:45.262Z",
        "currencyCode": "USDT",
        "simplifiedState": "processed",
        "state": "processed",
        "txHash": "361cc0bf0386451768116d6b55d97c9abe7cebe9927f8cd426cf8358940a5086"
      },
      "id": "327c2e54-055d-406b-a696-7130168ab919",
      "relationships": {
        "address": {
          "meta": {
            "included": false
          }
        },
        "author": {
          "meta": {
            "included": false
          }
        },
        "network": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "coinTransactions"
    },
    {
      "attributes": {
        "accountId": "80b8dd61-35bc-49cc-9e04-f2c0f741a096",
        "amount": "49.50",
        "balance": null,
        "createdAt": "2025-10-16T20:39:56.944Z",
        "currency": "USD",
        "reference": "111956dd-48da-4cec-815f-95ff600aae41",
        "simplifiedState": "cancelled",
        "transactionType": "InvoiceTransaction"
      },
      "id": "88b6c18a-a754-4ed1-8dc5-7d18a40062f8",
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "author": {
          "meta": {
            "included": false
          }
        },
        "transactionDetails": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "transactions"
    }
  ],
  "meta": {}
}
```

{% endcode %}

</details>

## 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="/files/cLkS49ZKfiRGTo4fa0OV" 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="/files/KlTMNZ4aVUlV9jlsJtGa" alt=""><figcaption><p>The wallet address is entered in the Address input field. The end-user must click Continue to review the payout details.</p></figcaption></figure>

<figure><img src="/files/R1J6829wFnqYCh7rdOEV" 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="/files/A9P5ddaRR1PXZNv0gWaN" 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="/files/5A15t8FLkKdIXjF9YvYy" alt=""><figcaption><p>Once the crypto transaction is confirmed on the blockchain, the payout status is updated to 'Completed.</p></figcaption></figure>


# NFT invoice payment method integration guide

This guide explains how to integrate the NFT invoice payment method with txn, from initial setup through successful payment confirmation.

The integration flow is:

1. Create an API key
2. Configure an invoice webhook URL
3. Create an NFT Pay invoice
4. Forward your end user to the Txn-hosted payment page
5. Receive invoice status updates by webhook
6. Mark the payment as successful once the invoice reaches completed

{% hint style="danger" %}
**Hosted page is required.** You must redirect your end users to the Txn-hosted payment page (`hostedPageUrl`) returned in the invoice response. Embedding it in an iframe, webview, or any other inline frame is not permitted. Open it in a new browser tab or redirect the user's current tab to the URL.
{% endhint %}

{% hint style="danger" %}
**Advertise this only as an NFT purchase — never as a card payment.** Present this method to your end users as an **NFT purchase**. Do not label, describe, or market it as a card payment anywhere on your website, checkout, or user flow — including any use of "card", "credit/debit card", "pay by card", or the Visa and Mastercard names, logos, or branding.
{% endhint %}

To create the invoice request itself, use the standard Create Invoice API described here:

{% content-ref url="/pages/hWiiq4mjjMJhUsPWBia4" %}
[Creating invoice](/invoices/creating-invoice)
{% endcontent-ref %}

## Before you begin

Make sure you have:

* access to your txn merchant back office
* an API key for the environment you are using
* a public webhook endpoint that can receive POST requests

You should use:

* Sandbox for testing
* Production for live payments

### Sandbox

Sandbox replicates the production environment by routing requests to the sandbox module for test purchases and smart contract interactions. It is connected to testnet blockchains, so no real charges are made and no real funds are used. OTP codes are also not sent to your phone in Sandbox - the code is always 0000.

### Test cards details

Cards are not charged in the Sandbox environment. However, please do not use real card details there.

You may use any card number and expiry date, or generate test card details on [this site](https://www.testmuai.com/free-online-tools/credit-card-number-generator/).

To simulate a successful card purchase you can use CVV `000`.

### Required parameter summary

| **Environment** | **chargedCurrency** | **network**      | **paymentMethods** |
| --------------- | ------------------- | ---------------- | ------------------ |
| Sandbox         | `POL`               | `tpolygon`       | `["nft"]`          |
| Production      | `USDC`              | `polygon:usdcv2` | `["nft"]`          |

***

## 1. Create an API key

In the txn back office, go to **Developers** → **API Keys** and create a new API key for your integration.

This API key will be used to authenticate requests to the txn API.

Include it in every request as a Bearer token:

```html
Authorization: Bearer <api_key>
Content-Type: application/vnd.api+json
```

Use your sandbox key in sandbox and your production key in production.

## 2. Configure your webhook URL

To receive invoice status updates, configure a webhook endpoint in the txn back office.

Go to **Developers** → **Webhook URLs** and click **Add Webhook URL**.

When creating the webhook:

* enter a webhook label
* enter your webhook endpoint URL
* enable **API Invoices**
* optionally associate the webhook with specific API keys if required

Once saved, txn will send invoice webhook events to that endpoint.

### Webhook endpoint requirements

Your webhook endpoint should:

* accept POST requests
* read the **raw request body**
* verify the webhook signature before processing
* return a 2xx response quickly after the event is accepted

Your processing should also be **idempotent**, so duplicate webhook deliveries do not result in duplicate order fulfilment.

## 3. Create an NFT Pay invoice

To create an NFT Pay invoice, use the standard **Create Invoice** endpoint:

```html
POST /api/public/v1/invoices
```

For this payment method, the following attributes must always be set exactly as shown below.

### Required NFT parameters

#### Production

{% code lineNumbers="true" %}

```json
{
  "chargedCurrency": "USDC",
  "network": "polygon:usdcv2",
  "paymentMethods": ["nft"]
}
```

{% endcode %}

#### Sandbox

{% code lineNumbers="true" %}

```json
{
  "chargedCurrency": "POL",
  "network": "tpolygon",
  "paymentMethods": ["nft"]
}
```

{% endcode %}

These values are required for NFT and should not be changed.

## 4. Example requests

#### Production example

{% code lineNumbers="true" %}

```bash
curl -X POST "https://api.txn.io/api/public/v1/invoices" \
  -H "Authorization: Bearer <production_api_key>" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "invoices",
      "attributes": {
        "amountBilled": "100.00",
        "billedCurrency": "USD",
        "chargedCurrency": "USDC",
        "network": "polygon:usdcv2",
        "paymentMethods": ["nft"],
        "reference": "order_12345"
      }
    }
  }'
```

{% endcode %}

#### Sandbox example

{% code lineNumbers="true" %}

```bash
curl -X POST "https://api.sandbox.txn.io/api/public/v1/invoices" \
  -H "Authorization: Bearer <sandbox_api_key>" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "invoices",
      "attributes": {
        "amountBilled": "100.00",
        "billedCurrency": "USD",
        "chargedCurrency": "POL",
        "network": "tpolygon",
        "paymentMethods": ["nft"],
        "reference": "order_12345"
      }
    }
  }'
```

{% endcode %}

## 5. Store the invoice identifiers

When the invoice is created successfully, txn returns an invoice object in the response.

You should store at least:

* the txn invoice ID
* your internal `reference`
* any internal order or customer identifiers linked to the payment

The `reference` field is important because it allows you to map later webhook events back to the correct order in your system.

## **6. Handle invoice webhook events**

After the invoice is created, txn will send webhook events to your configured webhook URL as the invoice status changes.

For this integration, you should treat the payment as successful when the invoice status becomes:

```json
"completed"
```

Once you receive a valid webhook showing status = "completed", you should:

* mark the order as paid
* fulfil the NFT purchase or unlock the related service
* store the payment result in your system

Do not fulfil the order before the invoice reaches completed.

## 7. Example webhook handling logic

The example below shows the expected webhook processing flow.

```javascript
app.post("/webhooks/txn", express.raw({ type: "*/*" }), async (req, res) => {
  const rawBody = req.body.toString("utf8");

  const svixId = req.header("svix-id");
  const svixTimestamp = req.header("svix-timestamp");
  const svixSignature = req.header("svix-signature");

  // Verify the webhook signature using the raw body and headers
  // Parse the payload only after verification succeeds
  const event = JSON.parse(rawBody);

  const invoice = event.data;
  const invoiceId = invoice.id;
  const status = invoice.attributes?.status;
  const reference = invoice.attributes?.reference;

  if (status === "completed") {
    // Mark the internal order as paid
    // Fulfil the NFT purchase
    // Store the invoice as processed
  }

  res.status(200).send("ok");
});
```

## 8. Recommended processing rules

For a reliable integration, we recommend the following:

#### Verify webhook authenticity

Always verify the webhook signature before trusting the payload.

Webhook deliveries may be retried. Your system should be able to safely receive the same event more than once without fulfilling the same order twice.

#### Reconcile by reference

Use your `reference` field, together with the txn invoice ID, to match incoming webhook events to the correct internal order.

#### Fulfil only on completed

Only treat the payment as successful once the invoice status is `completed`.

## 9. End-to-end flow summary

A typical NFT Pay integration flow looks like this:

1. Create an API key in **Developers** → **API Keys**
2. Configure a webhook in **Developers** → **Webhook URLs** with **API Invoices** enabled
3. Create an invoice using the standard Create Invoice API
4. Set the required NFT Pay parameters for the target environment
5. Store the invoice ID and your internal reference
6. Receive webhook notifications for invoice status changes
7. Once the invoice reaches `completed`, mark the payment as successful and fulfil the order

***

## FAQ

### Supported countries

| Country                                      | Supported |
| -------------------------------------------- | --------- |
| Afghanistan                                  | ✗         |
| Aland Islands                                | ✓         |
| Albania                                      | ✓         |
| Algeria                                      | ✓         |
| American Samoa                               | ✓         |
| Andorra                                      | ✓         |
| Angola                                       | ✓         |
| Anguilla                                     | ✓         |
| Antigua and Barbuda                          | ✓         |
| Argentina                                    | ✓         |
| Armenia                                      | ✓         |
| Aruba                                        | ✓         |
| Australia                                    | ✓         |
| Austria                                      | ✓         |
| Azerbaijan                                   | ✓         |
| Bahamas                                      | ✓         |
| Bahrain                                      | ✓         |
| Bangladesh                                   | ✓         |
| Barbados                                     | ✓         |
| Belarus                                      | ✗         |
| Belgium                                      | ✓         |
| Belize                                       | ✓         |
| Benin                                        | ✓         |
| Bermuda                                      | ✓         |
| Bhutan                                       | ✓         |
| Bolivia                                      | ✓         |
| Bonaire, Sint Eustatius and Saba             | ✓         |
| Bosnia and Herzegovina                       | ✓         |
| Botswana                                     | ✓         |
| Bouvet Island                                | ✗         |
| Brazil                                       | ✓         |
| British Indian Ocean Territory               | ✓         |
| British Virgin Islands                       | ✓         |
| Brunei Darussalam                            | ✓         |
| Bulgaria                                     | ✓         |
| Burkina Faso                                 | ✓         |
| Burundi                                      | ✓         |
| Cambodia                                     | ✓         |
| Cameroon                                     | ✓         |
| Canada                                       | ✓         |
| Cape Verde (Cabo Verde)                      | ✓         |
| Cayman Islands                               | ✗         |
| Central African Republic                     | ✓         |
| Chad                                         | ✓         |
| Chile                                        | ✓         |
| China                                        | ✓         |
| Christmas Island                             | ✓         |
| Cocos (Keeling) Islands                      | ✓         |
| Colombia                                     | ✓         |
| Comoros                                      | ✓         |
| Cook Islands                                 | ✓         |
| Costa Rica                                   | ✓         |
| Cote D'Ivoire                                | ✓         |
| Croatia                                      | ✓         |
| Cuba                                         | ✗         |
| Curaçao                                      | ✓         |
| Cyprus                                       | ✓         |
| Czech Republic                               | ✓         |
| Democratic Republic of the Congo             | ✗         |
| Denmark                                      | ✓         |
| Djibouti                                     | ✓         |
| Dominica                                     | ✓         |
| Dominican Republic                           | ✓         |
| Ecuador                                      | ✓         |
| Egypt                                        | ✗         |
| El Salvador                                  | ✓         |
| Equatorial Guinea                            | ✓         |
| Eritrea                                      | ✓         |
| Estonia                                      | ✓         |
| Eswatini (Swaziland)                         | ✓         |
| Ethiopia                                     | ✓         |
| Falkland Islands (Malvinas)                  | ✓         |
| Faroe Islands                                | ✓         |
| Fiji                                         | ✓         |
| Finland                                      | ✓         |
| France                                       | ✓         |
| French Guiana                                | ✓         |
| French Polynesia                             | ✓         |
| French Southern Territories                  | ✗         |
| Gabon                                        | ✓         |
| Gambia                                       | ✓         |
| Georgia                                      | ✓         |
| Germany                                      | ✓         |
| Ghana                                        | ✓         |
| Gibraltar                                    | ✗         |
| Greece                                       | ✓         |
| Greenland                                    | ✓         |
| Grenada                                      | ✓         |
| Guadeloupe                                   | ✓         |
| Guam                                         | ✓         |
| Guatemala                                    | ✓         |
| Guernsey                                     | ✓         |
| Guinea                                       | ✓         |
| Guinea-Bissau                                | ✓         |
| Guyana                                       | ✓         |
| Haiti                                        | ✓         |
| Heard Island and McDonald Islands            | ✗         |
| Honduras                                     | ✓         |
| Hong Kong                                    | ✓         |
| Hungary                                      | ✓         |
| Iceland                                      | ✓         |
| India                                        | ✓         |
| Indonesia                                    | ✓         |
| Iran                                         | ✗         |
| Iraq                                         | ✗         |
| Ireland                                      | ✓         |
| Isle of Man                                  | ✓         |
| Israel                                       | ✓         |
| Italy                                        | ✓         |
| Jamaica                                      | ✓         |
| Japan                                        | ✓         |
| Jersey                                       | ✓         |
| Jordan                                       | ✓         |
| Kazakhstan                                   | ✓         |
| Kenya                                        | ✓         |
| Kiribati                                     | ✓         |
| Kosovo                                       | ✓         |
| Kuwait                                       | ✓         |
| Kyrgyzstan                                   | ✓         |
| Laos                                         | ✓         |
| Latvia                                       | ✓         |
| Lebanon                                      | ✓         |
| Lesotho                                      | ✓         |
| Liberia                                      | ✓         |
| Libya                                        | ✓         |
| Liechtenstein                                | ✓         |
| Lithuania                                    | ✓         |
| Luxembourg                                   | ✓         |
| Macau                                        | ✓         |
| Macedonia                                    | ✓         |
| Madagascar                                   | ✓         |
| Malawi                                       | ✓         |
| Malaysia                                     | ✓         |
| Maldives                                     | ✓         |
| Mali                                         | ✓         |
| Malta                                        | ✓         |
| Marshall Islands                             | ✓         |
| Martinique                                   | ✓         |
| Mauritania                                   | ✓         |
| Mauritius                                    | ✓         |
| Mayotte                                      | ✓         |
| Mexico                                       | ✓         |
| Micronesia                                   | ✓         |
| Moldova                                      | ✓         |
| Monaco                                       | ✓         |
| Mongolia                                     | ✓         |
| Montenegro                                   | ✓         |
| Montserrat                                   | ✓         |
| Morocco                                      | ✓         |
| Mozambique                                   | ✓         |
| Myanmar (Burma)                              | ✓         |
| Namibia                                      | ✓         |
| Nauru                                        | ✓         |
| Nepal                                        | ✗         |
| Netherlands                                  | ✓         |
| New Caledonia                                | ✓         |
| New Zealand                                  | ✓         |
| Nicaragua                                    | ✓         |
| Niger                                        | ✓         |
| Nigeria                                      | ✓         |
| Niue                                         | ✓         |
| Norfolk Island                               | ✓         |
| Northern Mariana Islands                     | ✓         |
| North Korea                                  | ✗         |
| Norway                                       | ✓         |
| Oman                                         | ✓         |
| Pakistan                                     | ✓         |
| Palau                                        | ✓         |
| Palestine                                    | ✓         |
| Panama                                       | ✓         |
| Papua New Guinea                             | ✓         |
| Paraguay                                     | ✓         |
| Peru                                         | ✓         |
| Philippines                                  | ✓         |
| Pitcairn                                     | ✓         |
| Poland                                       | ✓         |
| Portugal                                     | ✓         |
| Puerto Rico                                  | ✓         |
| Qatar                                        | ✓         |
| Republic of the Congo                        | ✓         |
| Réunion                                      | ✓         |
| Romania                                      | ✓         |
| Russia                                       | ✗         |
| Rwanda                                       | ✓         |
| Saint Barthélemy                             | ✓         |
| Saint Helena, Ascension and Tristan da Cunha | ✓         |
| Saint Kitts and Nevis                        | ✓         |
| Saint Lucia                                  | ✓         |
| Saint Martin (French part)                   | ✓         |
| Saint Pierre and Miquelon                    | ✓         |
| Saint Vincent and the Grenadines             | ✓         |
| Samoa                                        | ✓         |
| San Marino                                   | ✓         |
| São Tomé and Príncipe                        | ✓         |
| Saudi Arabia                                 | ✓         |
| Senegal                                      | ✓         |
| Serbia                                       | ✓         |
| Seychelles                                   | ✓         |
| Sierra Leone                                 | ✓         |
| Singapore                                    | ✓         |
| Sint Maarten                                 | ✓         |
| Slovakia                                     | ✓         |
| Slovenia                                     | ✓         |
| Solomon Islands                              | ✓         |
| Somalia                                      | ✓         |
| South Africa                                 | ✓         |
| South Georgia and the South Sandwich Islands | ✗         |
| South Korea                                  | ✓         |
| South Sudan                                  | ✗         |
| Spain                                        | ✓         |
| Sri Lanka                                    | ✓         |
| Sudan                                        | ✗         |
| Suriname                                     | ✓         |
| Svalbard and Jan Mayen                       | ✓         |
| Sweden                                       | ✓         |
| Switzerland                                  | ✓         |
| Syria                                        | ✗         |
| Taiwan                                       | ✓         |
| Tajikistan                                   | ✓         |
| Tanzania                                     | ✓         |
| Thailand                                     | ✓         |
| Timor-Leste                                  | ✓         |
| Togo                                         | ✓         |
| Tokelau                                      | ✓         |
| Tonga                                        | ✓         |
| Trinidad and Tobago                          | ✓         |
| Tunisia                                      | ✗         |
| Turkey                                       | ✗         |
| Turkmenistan                                 | ✓         |
| Turks and Caicos Islands                     | ✓         |
| Tuvalu                                       | ✓         |
| Uganda                                       | ✓         |
| Ukraine                                      | ✓         |
| United Arab Emirates                         | ✓         |
| United Kingdom                               | ✓         |
| United States                                | ✓         |
| United States Virgin Islands                 | ✓         |
| Uruguay                                      | ✓         |
| U.S. Minor Outlying Islands                  | ✗         |
| Uzbekistan                                   | ✓         |
| Vanuatu                                      | ✓         |
| Vatican City (Holy See)                      | ✓         |
| Venezuela                                    | ✗         |
| Vietnam                                      | ✓         |
| Wallis and Futuna                            | ✓         |
| Western Sahara                               | ✓         |
| Yemen                                        | ✓         |
| Zambia                                       | ✓         |
| Zimbabwe                                     | ✓         |

### KYC requirements for end users

There are two KYC levels:

1. Non-document KYC (LKYC) allows customers to make NFT purchases of up to $5,000 US. These are lifetime limits per customer profile. Once a customer reaches the applicable limit, they will need to complete document KYC to continue making purchases. LKYC requires only the customer’s name, date of birth, and billing address. In most cases, it is completed within a few seconds, although it may take longer if manual review is required.
2. Document KYC (FKYC) allows customers to make NFT purchases of up to $20,000 US per week. Customers must provide proof of identity (such as a passport or driver’s license), proof of address dated within the last three months (such as a bank statement or utility bill), and complete a liveness check similar to a video selfie. For US residents, FKYC may also be completed by submitting only a driver’s license together with the liveness check. In most cases, FKYC is completed within a few seconds, although it may take longer if manual review is required.

### Minimum and maximum purchase values

The minimum purchase amount is $1 US. The maximum purchase amount is $20,000 US, subject to the customer’s applicable [KYC limit](#kyc-requirements-for-end-users).


# Payouts concept

## General

Payouts let you send cryptocurrency from your Txn account to an external wallet. Each payout request is processed immediately — Txn broadcasts the transaction to the relevant blockchain network as soon as the request is accepted, rather than batching multiple requests together.

{% hint style="danger" %}
**Treat every successfully submitted payout request as irreversible.** Once the API accepts your request, the transaction is queued for broadcast and cannot be recalled. Validate recipient addresses before submitting, especially in production.
{% endhint %}

You can fund payouts from either a fiat or cryptocurrency account balance. Each payout requires the amount, currency, payment network, and recipient wallet address.

### Reference

Every payout accepts a `reference` field — your internal correlation key. Set it to your order ID, user ID, or any value that lets you match the payout back to a record in your system. The `reference` is returned on every read response and webhook event, making it the primary hook for reconciliation.

## Fees

Two fees apply when sending a payout:

* The **payout fee** is the platform fee Txn charges for the service.
* The **network fee** covers blockchain transaction costs. Txn does not control miner fees; network fee settings are updated periodically to track the average fee required for next-block inclusion. Expect network fees to change without prior notice.

Use the `absorbPayoutFee` and `absorbNetworkFee` boolean parameters in your payout request to control how each fee is handled:

* **Absorbed by the merchant** — deducted from your account balance.
* **Deducted from the payout amount** — reduces the cryptocurrency amount the recipient receives.

### Examples

In the formulas below, variable names map to API response fields as follows: `payoutAmount` → `amount`, `paidAmount` → `payAmount`, `rate` → `exchangeRate`.

#### Case 1

`absorbPayoutFee = true` and `absorbNetworkFee = true`

Both fees are absorbed by the merchant. The recipient receives the full intended amount.

Formula:

```ini
amountCharged = payoutAmount + payoutFee + networkFee * rate
paidAmount = payoutAmount / rate
```

#### Case 2

`absorbPayoutFee = false` and `absorbNetworkFee = false`

Both fees are deducted from the payout amount. The recipient receives less cryptocurrency.

Formula:

```ini
amountCharged = payoutAmount
paidAmount = (payoutAmount - payoutFee) / rate - networkFee
```

#### Case 3

`absorbPayoutFee = true` and `absorbNetworkFee = false`

The merchant absorbs the payout fee. The network fee is deducted from the recipient's amount.

Formula:

```ini
amountCharged = payoutAmount + payoutFee
paidAmount = payoutAmount / rate - networkFee
```

#### Case 4

`absorbPayoutFee = false` and `absorbNetworkFee = true`

The payout fee is deducted from the recipient's amount. The merchant absorbs the network fee.

Formula:

```ini
amountCharged = payoutAmount + networkFee * rate
paidAmount = (payoutAmount - payoutFee) / rate
```

Test your fee configuration in the Sandbox environment before going live. Cross-check `amountCharged`, `payAmount`, `payoutFee`, and `networkFee` in the response against your expected values to ensure your reconciliation flows handle all cases correctly.

The table below summarises all four combinations:

<table data-header-hidden data-full-width="true"><thead><tr><th></th><th></th><th></th><th></th><th></th><th></th></tr></thead><tbody><tr><td><strong>absorbPayoutFee</strong></td><td><strong>absorbNetworkFee</strong></td><td><strong>Who pays payout fee</strong></td><td><strong>Who pays network fee</strong></td><td><strong>amountCharged</strong></td><td><strong>paidAmount</strong></td></tr><tr><td><strong>true</strong></td><td><strong>true</strong></td><td>Merchant (account balance)</td><td>Merchant (account balance)</td><td><code>payoutAmount + payoutFee + networkFee * rate</code></td><td><code>payoutAmount / rate</code></td></tr><tr><td><strong>false</strong></td><td><strong>false</strong></td><td>Recipient (deducted from payout)</td><td>Recipient (deducted from crypto)</td><td><code>payoutAmount</code></td><td><code>(payoutAmount - payoutFee) / rate - networkFee</code></td></tr><tr><td><strong>true</strong></td><td><strong>false</strong></td><td>Merchant (account balance)</td><td>Recipient (deducted from crypto)</td><td><code>payoutAmount + payoutFee</code></td><td><code>payoutAmount / rate - networkFee</code></td></tr><tr><td><strong>false</strong></td><td><strong>true</strong></td><td>Recipient (deducted from payout)</td><td>Merchant (account balance)</td><td><code>payoutAmount + networkFee * rate</code></td><td><code>(payoutAmount - payoutFee) / rate</code></td></tr></tbody></table>

## Display currency and charge currency

By default, `currency` also determines which of your Txn account balances is debited. A 100 EUR payout debits your EUR account.

Setting `chargeCurrency` decouples these: you can denominate the payout in one currency while funding it from a different account. This is common when paying recipients who expect amounts quoted in a local currency — such as CNY — while your Txn account holds EUR or another tradable currency.

When `chargeCurrency` is set, three distinct currencies can appear in the response:

* **`currency`** — the display currency the payout is denominated in (e.g. CNY)
* **`amountChargedCurrency`** — the currency debited from your account (e.g. EUR, always matches `chargeCurrency`)
* **`payCurrency`** — the cryptocurrency sent to the recipient (e.g. USDT)

**Example:** 500 CNY display amount, EUR account debited, USDT sent via Tron — both fees absorbed by the merchant:

| Field           | Value      | Currency     |
| --------------- | ---------- | ------------ |
| `amount`        | 500.00     | CNY          |
| `payAmount`     | 71.297671  | USDT         |
| `amountCharged` | 64.84      | EUR          |
| `payoutFee`     | 0.63       | EUR          |
| `networkFee`    | 1.000000   | USDT         |
| `displayFee`    | 5.00       | CNY          |
| `exchangeRate`  | 7.01285182 | CNY per USDT |
| `payChargeRate` | 0.8881381  | EUR per USDT |

`displayFee` is the payout fee re-expressed in `currency` for display to the recipient. `exchangeRate` converts between `currency` and `payCurrency`; `payChargeRate` converts between `payCurrency` and `amountChargedCurrency`.

## Payout status

Payouts move through the following statuses: **processing** → **completed** (or **cancelled**). When using the optional draft flow, a **draft** status precedes processing.

A payout in **processing** has been accepted and is in flight — the transaction is being prepared and broadcast, or has been broadcast and is awaiting its first blockchain confirmation. **completed** means the transaction has received at least one on-chain confirmation. See [Payout Status Flow](/payouts/payout-status-flow) for the full reference.

## Payout limits

Contact Txn support for the minimum and maximum payout amounts per currency.

## Payment methods

Payouts support two payment methods, set via the `paymentMethod` parameter:

* **`on_chain`** (default) — sends cryptocurrency directly to the recipient's wallet address on-chain.
* **`binance_pay`** — routes the payment off-chain through Binance Pay. Requires the recipient's Binance ID instead of a wallet address. Validate the Binance ID using the [Validate Binance ID](/payouts/validating-recipients-binance-id) endpoint before submitting the payout request.

## Address validation

Txn automatically validates the recipient wallet address format and screens it against sanctions and high-risk wallet lists on every payout request. An invalid or flagged address causes the request to be rejected immediately.

For production integrations, validate addresses before submitting a payout request using the [Validate Address](/payouts/validating-addresses) endpoint:

1. Collect the wallet address from your user.
2. Call [Validate Address](/payouts/validating-addresses) to confirm it is correctly formatted and not flagged.
3. Call [Create Payout](/payouts/creating-payout) with the validated address.

This approach catches problems before they reach the payout itself, giving you a clean error surface and avoiding failed payout attempts.


# Payout status flow

| status     | Final state? | Description                                                                                                                                                                                                                     |
| ---------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| draft      | no           | A payout draft has been created. Only returned when using the [optional draft flow](/payouts/drafting-payout-optional). The draft must be confirmed within 30 seconds, otherwise it expires and is cancelled.                   |
| processing | no           | The payout has been accepted and is in flight. The transaction is being prepared and broadcast, or has been broadcast and is awaiting its first on-chain confirmation.                                                          |
| completed  | yes          | The transaction has received at least one on-chain confirmation.                                                                                                                                                                |
| cancelled  | yes          | The payout did not complete and will not proceed. Possible causes include an address flagged during compliance screening, insufficient account balance, an expired or rejected draft, or an unexpected issue during processing. |

```mermaid
stateDiagram-v2
    [*] --> draft : draft flow only
    [*] --> processing : standard flow
    draft --> processing : confirmed
    draft --> cancelled : expired or cancelled
    processing --> completed
    processing --> cancelled
```

{% hint style="info" %}
Processing is immediate in most cases. Delays can occur when a transaction requires compliance review or when liquidity needs to be rebalanced before the transaction can be broadcast.
{% endhint %}

## Approval status

Dashboard-initiated payouts subject to an approval rule carry an additional `approvalStatus` field reflecting where the payout sits in the approval workflow. API-created payouts always return `null` for this field.

See the [Approvals feature guide](/getting-setup/approvals-feature-guide) for how approval rules work.


# Listing payout currency pairs

<mark style="color:green;">`GET`</mark> `/api/public/v1/payouts/currency_pairs`

Returns all available payout currency pairs. Use this endpoint to discover which account currencies (`displayCurrency`) can fund a payout and which cryptocurrencies (`payCurrency`) can be sent, along with the networks available for each.

To construct a [Create Payout](/payouts/creating-payout) request from the response:

1. Choose a pair — `displayCurrency` gives you the `currency` parameter, `payCurrency` gives you the cryptocurrency that will be sent.
2. Find the `payCurrency` entry in `included` and follow its `networks` references.
3. Find the matching `network` objects in `included` — the `code` is the `payNetwork` value to use.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**Response Body**

<table><thead><tr><th>Name</th><th width="96">Type</th><th>Description</th></tr></thead><tbody><tr><td>data[].id</td><td>string</td><td>Currency pair ID.</td></tr><tr><td>data[].type</td><td>string</td><td>Always <code>payoutCurrencyPairs</code>.</td></tr><tr><td>data[].attributes.direction</td><td>string</td><td>Always <code>buy</code> — the platform buys the <code>payCurrency</code> on your behalf to send to the recipient.</td></tr><tr><td>data[].attributes.enabled</td><td>boolean</td><td>Whether this pair is currently available for payouts.</td></tr><tr><td>data[].relationships.displayCurrency.data.id</td><td>string</td><td>Currency code of the account to debit. Use as the <code>currency</code> parameter in Create Payout.</td></tr><tr><td>data[].relationships.payCurrency.data.id</td><td>string</td><td>Currency code of the cryptocurrency sent to the recipient.</td></tr><tr><td>data[].relationships.chargeCurrency</td><td>object</td><td><mark style="color:red;">Deprecated.</mark> Use <code>displayCurrency</code> instead.</td></tr><tr><td>included[].type(currencies).attributes.code</td><td>string</td><td>Currency code.</td></tr><tr><td>included[].type(currencies).attributes.crypto</td><td>boolean</td><td><code>true</code> for cryptocurrencies, <code>false</code> for fiat.</td></tr><tr><td>included[].type(currencies).attributes.symbol</td><td>string</td><td>Display symbol for the currency.</td></tr><tr><td>included[].type(currencies).attributes.subunitToUnit</td><td>number</td><td>Number of smallest units in one whole unit (e.g. <code>100000000</code> for BTC, <code>100</code> for EUR).</td></tr><tr><td>included[].type(currencies).relationships.networks</td><td>array</td><td>Network references for this currency. Resolve against <code>network</code> objects in <code>included</code> to get the <code>payNetwork</code> codes.</td></tr><tr><td>included[].type(network).attributes.code</td><td>string</td><td>Network code. Use as the <code>payNetwork</code> parameter in Create Payout.</td></tr><tr><td>included[].type(network).attributes.name</td><td>string</td><td>Human-readable network name.</td></tr><tr><td>included[].type(network).attributes.currencyCode</td><td>string</td><td>Currency code this network belongs to.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": [
    {
      "id": "bbe5124a-5f43-4b7e-9d49-eb88d7a4537b",
      "type": "payoutCurrencyPairs",
      "attributes": {
        "direction": "buy",
        "enabled": true
      },
      "relationships": {
        "chargeCurrency": {
          "data": { "type": "currencies", "id": "EUR" },
          "meta": { "deprecated": true }
        },
        "displayCurrency": {
          "data": { "type": "currencies", "id": "EUR" }
        },
        "payCurrency": {
          "data": { "type": "currencies", "id": "USDT" }
        }
      }
    },
    {
      "id": "ad07045e-823c-4ab4-ad75-9d1df1f5a1dc",
      "type": "payoutCurrencyPairs",
      "attributes": {
        "direction": "buy",
        "enabled": true
      },
      "relationships": {
        "chargeCurrency": {
          "data": { "type": "currencies", "id": "EUR" },
          "meta": { "deprecated": true }
        },
        "displayCurrency": {
          "data": { "type": "currencies", "id": "EUR" }
        },
        "payCurrency": {
          "data": { "type": "currencies", "id": "BTC" }
        }
      }
    }
  ],
  "included": [
    {
      "id": "EUR",
      "type": "currencies",
      "attributes": {
        "code": "EUR",
        "crypto": false,
        "symbol": "€",
        "subunitToUnit": 100
      },
      "relationships": {
        "networks": { "data": [] }
      }
    },
    {
      "id": "USDT",
      "type": "currencies",
      "attributes": {
        "code": "USDT",
        "crypto": true,
        "symbol": "₮",
        "subunitToUnit": 1000000
      },
      "relationships": {
        "networks": {
          "data": [
            { "type": "network", "id": "2cfea86d-f334-4bd2-99ac-e74281520c95" },
            { "type": "network", "id": "8ededca3-a1cd-4b46-8c3a-14915f706ab2" },
            { "type": "network", "id": "490f02d4-b09a-4486-a469-d10c2ea43638" },
            { "type": "network", "id": "927d49d4-f4b2-48dc-876d-ac375337ec2a" },
            { "type": "network", "id": "4a1ec40b-8656-437c-ae79-4dd5435b53a5" }
          ]
        }
      }
    },
    {
      "id": "BTC",
      "type": "currencies",
      "attributes": {
        "code": "BTC",
        "crypto": true,
        "symbol": "฿",
        "subunitToUnit": 100000000
      },
      "relationships": {
        "networks": {
          "data": [
            { "type": "network", "id": "c0369c57-da08-4c60-b5ee-63e1e43d5ae4" }
          ]
        }
      }
    },
    {
      "id": "2cfea86d-f334-4bd2-99ac-e74281520c95",
      "type": "network",
      "attributes": {
        "currencyCode": "USDT",
        "name": "Ethereum (ERC20)",
        "code": "hterc6dp"
      }
    },
    {
      "id": "8ededca3-a1cd-4b46-8c3a-14915f706ab2",
      "type": "network",
      "attributes": {
        "currencyCode": "USDT",
        "name": "Tron (TRC20)",
        "code": "ttrx:usdt"
      }
    },
    {
      "id": "490f02d4-b09a-4486-a469-d10c2ea43638",
      "type": "network",
      "attributes": {
        "currencyCode": "USDT",
        "name": "Polygon (ERC20)",
        "code": "tpolygon:usdt"
      }
    },
    {
      "id": "927d49d4-f4b2-48dc-876d-ac375337ec2a",
      "type": "network",
      "attributes": {
        "currencyCode": "USDT",
        "name": "Binance Smart Chain (BEP20)",
        "code": "tbsc:usdt"
      }
    },
    {
      "id": "4a1ec40b-8656-437c-ae79-4dd5435b53a5",
      "type": "network",
      "attributes": {
        "currencyCode": "USDT",
        "name": "Solana",
        "code": "tsol:usdt"
      }
    },
    {
      "id": "c0369c57-da08-4c60-b5ee-63e1e43d5ae4",
      "type": "network",
      "attributes": {
        "currencyCode": "BTC",
        "name": "Bitcoin",
        "code": "tbtc"
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}


# Validating addresses

<mark style="color:green;">`POST`</mark> `/api/public/v1/addresses/validate`

Validates a wallet address before you create a payout. The endpoint checks that the address format is correct for the specified network and screens it against sanctions and high-risk wallet lists. A `200` response means the address passed both checks and is safe to use in a [Create Payout](/payouts/creating-payout) request.

{% hint style="info" %}
This endpoint uses `Content-Type: application/json`, not `application/vnd.api+json`.
{% endhint %}

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <api_key>` |

**Request Body**

<table><thead><tr><th width="126">Name</th><th width="111">Type</th><th width="105">Required</th><th>Description</th></tr></thead><tbody><tr><td>address</td><td>string</td><td>Yes</td><td>Wallet address to validate.</td></tr><tr><td>network</td><td>string</td><td>Yes</td><td>Network code for the address. Use the same value you intend to pass as <code>payNetwork</code> in Create Payout. See <a href="/pages/SA7q0b6VrvXO3W09TQfS">Supported Currencies</a> or <a href="/pages/LZN85Aljdy7QXbLhakR2">Listing Payout Currency Pairs</a>.</td></tr></tbody></table>

**cURL**

```json
curl -X "POST" "https://api.sandbox.txn.io/api/public/v1/addresses/validate" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer <api_key>' \
     -d '{
  "address": "TTbGTMwUwA3mncLP7xqCZei1ekaNSgeAJe",
  "network": "ttrx:usdt"
}'
```

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": {},
  "status": "ok",
  "jsonapi": {
    "version": "1.0"
  }
}
```

Address is valid and not flagged. Safe to use in a Create Payout request.
{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "Invalid address",
      "code": "invalid_address",
      "detail": "",
      "source": {
        "pointer": "/data/attributes/address"
      }
    }
  ]
}
```

Address format is invalid for the specified network. This is also returned when the address belongs to a different network than the one specified (e.g. an Ethereum address submitted with a Tron network code).
{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "We couldn't send funds to this address, please try another address",
      "code": "address_has_high_risk_score",
      "detail": "",
      "source": {
        "pointer": "/data/attributes/address"
      }
    }
  ]
}
```

Address failed risk screening. Do not proceed with a payout to this address.
{% endtab %}

{% tab title="HTTP 404" %}

```json
{
  "errors": [
    {
      "status": 404,
      "title": "Record not found",
      "code": "network_not_found",
      "detail": "Network not found"
    }
  ]
}
```

Network code not recognised. Check the value against [Supported Currencies](/api-basics/supported-currencies) or [Listing Payout Currency Pairs](/payouts/listing-payout-currency-pairs).
{% endtab %}
{% endtabs %}


# Validating recipient's Binance ID

<mark style="color:green;">`POST`</mark> `/api/public/v1/payouts/binance_receiver/validate`

Verifies that a recipient's Binance ID is recognised by Binance before you create a `binance_pay` payout. A `200` response confirms the ID is valid and the recipient can receive Binance Pay payments. Call this endpoint before [Create Payout](/payouts/creating-payout) to catch invalid IDs early.

{% hint style="info" %}
This endpoint uses `Content-Type: application/json`, not `application/vnd.api+json`.
{% endhint %}

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <api_key>` |

**Request Body**

<table><thead><tr><th width="126">Name</th><th width="111">Type</th><th width="105">Required</th><th>Description</th></tr></thead><tbody><tr><td>receiver_id</td><td>string</td><td>Yes</td><td>Recipient's Binance ID. Must be numeric, 7 or more digits.</td></tr></tbody></table>

**cURL**

```json
curl -X "POST" "https://api.sandbox.txn.io/api/public/v1/payouts/binance_receiver/validate" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer <api_key>' \
     -d '{
  "receiver_id": "474748434"
}'
```

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": {},
  "status": "ok",
  "jsonapi": {
    "version": "1.0"
  }
}
```

Binance ID is recognised. Safe to use as `receiverBinanceId` in a Create Payout request.
{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "Invalid receiver",
      "code": "binance_pay_invalid_receiver",
      "detail": "The provided Binance ID is not valid."
    }
  ]
}
```

The Binance ID is not recognised or the format is invalid. Do not proceed with a `binance_pay` payout to this ID.
{% endtab %}
{% endtabs %}


# Payout webhooks

Txn sends a payout webhook each time a payout's `status` changes. The payload mirrors the [Read payout](/payouts/reading-payout) endpoint response.

The tabs below show example payloads for each status. For the rules that govern transitions, see [Payout status flow](/payouts/payout-status-flow).

For configuring webhook URLs, retry behaviour, source IPs, and signature verification, see the general [Webhooks](/api-basics/webhooks) section.

{% tabs %}
{% tab title="Status Processing" %}

```json
{
  "data": {
    "id": "9d12fe2c-c8ac-44c7-b2f0-b9d11aa62f53",
    "type": "payouts",
    "attributes": {
      "absorbFees": null,
      "absorbNetworkFee": true,
      "absorbPayoutFee": true,
      "address": "TTbGTMwUwA3mncLP7xqCZei1ekaNSgeAJe",
      "amount": "500.00",
      "amountCharged": "64.84",
      "amountChargedCurrency": "EUR",
      "approvalStatus": null,
      "binanceStatus": null,
      "createdAt": "2026-05-19T15:40:37.788Z",
      "currency": "CNY",
      "displayFee": "5.00",
      "displayFeeCurrency": "CNY",
      "exchangeRate": "7.01285182",
      "expiresAt": "2026-05-19T15:41:07.788Z",
      "networkFee": "1.000000",
      "networkFeeCurrency": "USDT",
      "payAmount": "71.297671",
      "payChargeRate": "0.8881381",
      "payChargeRateCurrency": "EUR",
      "payCurrency": "USDT",
      "paymentMethod": "on_chain",
      "payNetwork": "ttrx:usdt",
      "payNetworkName": "Tron (TRC20)",
      "payoutFee": "0.63",
      "payoutFeeCurrency": "EUR",
      "receiverBinanceId": null,
      "reference": "docs-cny-eur-example-001",
      "status": "processing",
      "txid": null
    },
    "relationships": {
      "accountCharged": {
        "data": {
          "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
          "type": "accounts"
        }
      },
      "author": {
        "data": {
          "id": "b56961f4-46cf-4e60-bb32-b36addb09f66",
          "type": "apiKeys"
        }
      }
    }
  },
  "included": [
    {
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "type": "accounts",
      "attributes": {
        "balance": "38968.92",
        "bankDepositAvailable": true,
        "bankReference": "BDR6421088115176062",
        "bankWithdrawalAvailable": true,
        "currencyCode": "EUR",
        "currencyType": "fiat",
        "label": "master",
        "master": true,
        "totalBalance": null,
        "transferAvailable": true
      },
      "relationships": {
        "company": { "meta": { "included": false } },
        "networks": { "meta": { "included": false } },
        "txnBankCredentials": { "meta": { "included": false } }
      }
    },
    {
      "id": "b56961f4-46cf-4e60-bb32-b36addb09f66",
      "type": "apiKeys",
      "attributes": {
        "createdAt": "2024-06-17T19:41:33.398Z",
        "name": "Test API key"
      }
    }
  ],
  "meta": {}
}
```

{% endtab %}

{% tab title="Status Completed" %}

```json
{
  "data": {
    "id": "9d12fe2c-c8ac-44c7-b2f0-b9d11aa62f53",
    "type": "payouts",
    "attributes": {
      "absorbFees": null,
      "absorbNetworkFee": true,
      "absorbPayoutFee": true,
      "address": "TTbGTMwUwA3mncLP7xqCZei1ekaNSgeAJe",
      "amount": "500.00",
      "amountCharged": "64.84",
      "amountChargedCurrency": "EUR",
      "approvalStatus": null,
      "binanceStatus": null,
      "createdAt": "2026-05-19T15:40:37.788Z",
      "currency": "CNY",
      "displayFee": "5.00",
      "displayFeeCurrency": "CNY",
      "exchangeRate": "7.01285182",
      "expiresAt": "2026-05-19T15:41:07.788Z",
      "networkFee": "1.000000",
      "networkFeeCurrency": "USDT",
      "payAmount": "71.297671",
      "payChargeRate": "0.8881381",
      "payChargeRateCurrency": "EUR",
      "payCurrency": "USDT",
      "paymentMethod": "on_chain",
      "payNetwork": "ttrx:usdt",
      "payNetworkName": "Tron (TRC20)",
      "payoutFee": "0.63",
      "payoutFeeCurrency": "EUR",
      "receiverBinanceId": null,
      "reference": "docs-cny-eur-example-001",
      "status": "completed",
      "txid": "c94f1a2b3d4e5f6071829384a5b6c7d8e9f0a1b2c3d4e5f607182938a4b5c6d7"
    },
    "relationships": {
      "accountCharged": {
        "data": {
          "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
          "type": "accounts"
        }
      },
      "author": {
        "data": {
          "id": "b56961f4-46cf-4e60-bb32-b36addb09f66",
          "type": "apiKeys"
        }
      }
    }
  },
  "included": [
    {
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "type": "accounts",
      "attributes": {
        "balance": "38904.08",
        "bankDepositAvailable": true,
        "bankReference": "BDR6421088115176062",
        "bankWithdrawalAvailable": true,
        "currencyCode": "EUR",
        "currencyType": "fiat",
        "label": "master",
        "master": true,
        "totalBalance": null,
        "transferAvailable": true
      },
      "relationships": {
        "company": { "meta": { "included": false } },
        "networks": { "meta": { "included": false } },
        "txnBankCredentials": { "meta": { "included": false } }
      }
    },
    {
      "id": "b56961f4-46cf-4e60-bb32-b36addb09f66",
      "type": "apiKeys",
      "attributes": {
        "createdAt": "2024-06-17T19:41:33.398Z",
        "name": "Test API key"
      }
    }
  ],
  "meta": {}
}
```

{% endtab %}

{% tab title="Status Cancelled" %}

```json
{
  "data": {
    "id": "9ecba2f9-cc84-4c37-9d05-84570b72c816",
    "type": "payouts",
    "attributes": {
      "absorbFees": null,
      "absorbNetworkFee": true,
      "absorbPayoutFee": true,
      "address": "TTbGTMwUwA3mncLP7xqCZei1ekaNSgeAJe",
      "amount": "50.00",
      "amountCharged": "51.39",
      "amountChargedCurrency": "EUR",
      "approvalStatus": null,
      "binanceStatus": null,
      "createdAt": "2026-05-15T19:00:00.000Z",
      "currency": "EUR",
      "displayFee": "0.50",
      "displayFeeCurrency": "EUR",
      "exchangeRate": "0.8866755",
      "expiresAt": "2026-05-15T19:00:30.000Z",
      "networkFee": "1.000000",
      "networkFeeCurrency": "USDT",
      "payAmount": "56.390416",
      "payChargeRate": "0.8866755",
      "payChargeRateCurrency": "EUR",
      "payCurrency": "USDT",
      "payNetwork": "ttrx:usdt",
      "payNetworkName": "Tron (TRC20)",
      "paymentMethod": "on_chain",
      "payoutFee": "0.50",
      "payoutFeeCurrency": "EUR",
      "receiverBinanceId": null,
      "reference": "9a3e4720-b2e4-e899-fcbb-b956a1b2c3d4",
      "status": "cancelled",
      "txid": null
    },
    "relationships": {
      "accountCharged": {
        "data": {
          "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
          "type": "accounts"
        }
      },
      "author": {
        "data": {
          "id": "3cd066e3-94f7-4182-a242-bf3b4e8ea2da",
          "type": "apiKeys"
        }
      }
    }
  },
  "included": [
    {
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "type": "accounts",
      "attributes": {
        "balance": "39207.72",
        "bankDepositAvailable": true,
        "bankReference": "BDR6421088115176062",
        "bankWithdrawalAvailable": true,
        "currencyCode": "EUR",
        "currencyType": "fiat",
        "label": "master",
        "master": true,
        "totalBalance": null,
        "transferAvailable": true
      },
      "relationships": {
        "company": { "meta": { "included": false } },
        "networks": { "meta": { "included": false } },
        "txnBankCredentials": { "meta": { "included": false } }
      }
    },
    {
      "id": "3cd066e3-94f7-4182-a242-bf3b4e8ea2da",
      "type": "apiKeys",
      "attributes": {
        "createdAt": "2026-05-07T10:39:48.046Z",
        "name": "My API Key"
      }
    }
  ],
  "meta": {}
}
```

{% endtab %}
{% endtabs %}


# Creating payout

<mark style="color:green;">`POST`</mark> `/api/public/v1/payouts`

Creates a payout and immediately queues it for broadcast on the specified network. The response always returns `status: processing`. The `txid` field is `null` on creation and is populated once the transaction is sent — poll [Read Payout](/payouts/reading-payout) to track progress.

{% hint style="danger" %}
Treat a successful response as irreversible. Once the API accepts the request, the payout is queued and cannot be recalled.
{% endhint %}

### XRP destination tag

XRP payouts require a destination tag appended to the wallet address as `address?dt=tag`. The destination tag identifies the specific recipient within a shared XRP wallet — without it, the funds cannot be attributed to the correct account.

Collect the destination tag from your recipient before creating the payout. If the recipient does not have a destination tag, pass `0`:

```
rwCQVZLSMNY6DgMH61317qvH3nHYqm68PF?dt=0
```

{% hint style="danger" %}
Funds sent without a valid destination tag cannot be attributed to a specific account and may be permanently lost.
{% endhint %}

**cURL**

```bash
## Create payout XRP

curl -X "POST" "https://api.sandbox.txn.io/api/public/v1/payouts" \
     -H 'Content-Type: application/vnd.api+json' \
     -H 'Authorization: Bearer <api_key>' \
     -d $'{
  "data": {
    "type": "payouts",
    "attributes": {
      "reference": "b8ad764b-7951-4cbc-9a15-efa91d47fe4e",
      "amount": "1000",
      "currency": "TRY",
      "chargeCurrency": "EUR",
      "accountChargedId": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "absorbPayoutFee": true,
      "absorbNetworkFee": false,
      "address": "rLsBa2vWV2uuPx2UKbocAZG2WHXoaGyMPf?dt=61",
      "payNetwork": "txrp",
      "paymentMethod": "on_chain",
    }
  }
}'
```

**Headers**

<table><thead><tr><th width="320">Name</th><th>Value</th></tr></thead><tbody><tr><td>Content-Type</td><td><code>application/vnd.api+json</code></td></tr><tr><td>Authorization</td><td><code>Bearer &#x3C;api_key></code></td></tr></tbody></table>

**Request Body**

<table><thead><tr><th>Name</th><th width="100">Type</th><th width="105">Required</th><th>Description</th></tr></thead><tbody><tr><td>data.type</td><td>string</td><td>Yes</td><td>Can only be <code>payouts</code>.</td></tr><tr><td>data.attributes.reference</td><td>string</td><td>No</td><td>Your internal correlation key for this payout — use your order ID, user ID, or any value that lets you match this payout to a record in your system. Must be unique per payout.</td></tr><tr><td>data.attributes.amount</td><td>number</td><td>Yes</td><td>Payout amount in <code>currency</code>. Contact Txn support for minimum and maximum values per currency.</td></tr><tr><td>data.attributes.currency</td><td>string</td><td>Yes</td><td>Currency of the payout amount. When <code>chargeCurrency</code> is omitted, also determines which of your Txn account balances is debited. See <a href="/pages/SA7q0b6VrvXO3W09TQfS">Supported Currencies</a>.</td></tr><tr><td>data.attributes.chargeCurrency</td><td>string</td><td>No</td><td>Specifies from which merchant's currency account the payout amount and fees should be taken. Can be any tradable fiat or cryptocurrency listed on the <a href="/pages/SA7q0b6VrvXO3W09TQfS">Supported currencies</a> page — display fiat currencies are not accepted. If omitted, defaults to the <code>data.attributes.currency</code> account; in that case <code>currency</code> must itself be a tradable fiat or cryptocurrency, otherwise <code>chargeCurrency</code> must be supplied.</td></tr><tr><td>data.attributes.accountChargedId</td><td>string</td><td></td><td>ID of the account to debit the payout from. Can be a master or subaccount ID. Defaults to your master account. Requires <code>chargeCurrency</code>.</td></tr><tr><td>data.attributes.payNetwork</td><td>string</td><td>Yes</td><td>Network code for the cryptocurrency to send. See <a href="/pages/SA7q0b6VrvXO3W09TQfS">Supported Currencies</a>.</td></tr><tr><td>data.attributes.address</td><td>string</td><td>Yes</td><td>Recipient's wallet address. For XRP, include the destination tag as <code>address?dt=tag</code>.</td></tr><tr><td>data.attributes.absorbFees</td><td>boolean</td><td>No</td><td><mark style="color:red;">Deprecated.</mark> Use <code>absorbPayoutFee</code> and <code>absorbNetworkFee</code> instead.</td></tr><tr><td>data.attributes.absorbPayoutFee</td><td>boolean</td><td>No</td><td>If <code>false</code> or omitted, the payout fee is deducted from the amount the recipient receives. If <code>true</code>, the fee is charged to your account balance instead.</td></tr><tr><td>data.attributes.absorbNetworkFee</td><td>boolean</td><td>No</td><td>If <code>false</code> or omitted, the network fee is deducted from the amount the recipient receives. If <code>true</code>, the fee is charged to your account balance instead.</td></tr><tr><td>data.attributes.paymentMethod</td><td>string</td><td>No</td><td><code>on_chain</code> sends cryptocurrency directly to the recipient's wallet. <code>binance_pay</code> routes the payment off-chain through Binance Pay and requires <code>receiverBinanceId</code>. Defaults to <code>on_chain</code>.</td></tr><tr><td>data.attributes.receiverBinanceId</td><td>string</td><td>No</td><td>Recipient's Binance ID (7 or more digits). Required for <code>binance_pay</code> payouts. Validate it first using the <a href="/pages/ZmNuWGIc9tmIwns5ay5k">Validate Binance ID</a> endpoint.</td></tr></tbody></table>

**Response Body**

<table><thead><tr><th>Name</th><th width="96">Type</th><th>Description</th></tr></thead><tbody><tr><td>data.id</td><td>string</td><td>Payout ID.</td></tr><tr><td>data.type</td><td>string</td><td>Always <code>payouts</code>.</td></tr><tr><td>data.attributes.reference</td><td>string</td><td>Your internal correlation key, as set at creation.</td></tr><tr><td>data.attributes.status</td><td>string</td><td>Payout status. Refer to <a href="/pages/ISxxub0HyhX1k8q53l50">Payout Status Flow</a>.</td></tr><tr><td>data.attributes.address</td><td>string</td><td>Recipient's wallet address.</td></tr><tr><td>data.attributes.createdAt</td><td>string</td><td>ISO 8601 timestamp of when the payout was created.</td></tr><tr><td>data.attributes.expiresAt</td><td>string</td><td>ISO 8601 timestamp of when the exchange rate lock expires.</td></tr><tr><td>data.attributes.absorbFees</td><td>boolean</td><td>Deprecated. Use <code>absorbPayoutFee</code> and <code>absorbNetworkFee</code> instead.</td></tr><tr><td>data.attributes.absorbPayoutFee</td><td>boolean</td><td>If <code>false</code>, the payout fee was deducted from the amount the recipient received. If <code>true</code>, the fee was charged to your account balance.</td></tr><tr><td>data.attributes.absorbNetworkFee</td><td>boolean</td><td>If <code>false</code>, the network fee was deducted from the amount the recipient received. If <code>true</code>, the fee was charged to your account balance.</td></tr><tr><td>data.attributes.amount</td><td>number</td><td>Payout amount in <code>currency</code>.</td></tr><tr><td>data.attributes.currency</td><td>string</td><td>Payout amount currency code.</td></tr><tr><td>data.attributes.payCurrency</td><td>string</td><td>Currency code of the cryptocurrency sent to the recipient.</td></tr><tr><td>data.attributes.payAmount</td><td>string</td><td>Amount of cryptocurrency sent to the recipient.</td></tr><tr><td>data.attributes.txid</td><td>string</td><td>On-chain transaction hash. Share with the recipient as proof of payment.</td></tr><tr><td>data.attributes.payNetwork</td><td>string</td><td>Network code of the cryptocurrency sent. See <a href="/pages/SA7q0b6VrvXO3W09TQfS">Supported Currencies</a>.</td></tr><tr><td>data.attributes.payNetworkName</td><td>string</td><td>Human-readable network name, e.g. <code>Tron</code>.</td></tr><tr><td>data.attributes.networkFee</td><td>string</td><td>Network fee amount in <code>networkFeeCurrency</code>.</td></tr><tr><td>data.attributes.networkFeeCurrency</td><td>string</td><td>Currency of the network fee.</td></tr><tr><td>data.attributes.payoutFee</td><td>string</td><td>Txn service fee amount in <code>payoutFeeCurrency</code>.</td></tr><tr><td>data.attributes.payoutFeeCurrency</td><td>string</td><td>Currency of the Txn service fee.</td></tr><tr><td>data.attributes.displayFee</td><td>string</td><td>Payout fee expressed in <code>currency</code>.</td></tr><tr><td>data.attributes.displayFeeCurrency</td><td>string</td><td>Currency of <code>displayFee</code>. Always matches <code>currency</code>.</td></tr><tr><td>data.attributes.amountCharged</td><td>string</td><td>Total amount debited from your account, including all fees, in <code>amountChargedCurrency</code>.</td></tr><tr><td>data.attributes.amountChargedCurrency</td><td>string</td><td>Currency of <code>amountCharged</code>. Matches <code>chargeCurrency</code>.</td></tr><tr><td>data.attributes.payChargeRate</td><td>string</td><td>Exchange rate between <code>payCurrency</code> and <code>amountChargedCurrency</code> applied by Txn.</td></tr><tr><td>data.attributes.payChargeRateCurrency</td><td>string</td><td>Quote currency of <code>payChargeRate</code>.</td></tr><tr><td>data.attributes.exchangeRate</td><td>string</td><td>Exchange rate between <code>payCurrency</code> and <code>currency</code> applied by Txn.</td></tr><tr><td>data.attributes.paymentMethod</td><td>string</td><td>Payment method used: <code>on_chain</code> or <code>binance_pay</code>.</td></tr><tr><td>data.attributes.receiverBinanceId</td><td>string</td><td>Recipient's Binance ID. Present only for <code>binance_pay</code> payouts.</td></tr><tr><td>data.attributes.approvalStatus</td><td>string</td><td>Approval workflow status. Present only for dashboard-initiated payouts subject to an approval rule. Always <code>null</code> for API-created payouts.</td></tr><tr><td>data.attributes.binanceStatus</td><td>string</td><td>Binance Pay processing status. Present only for <code>binance_pay</code> payouts.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="HTTP 201" %}

```json
{
  "data": {
    "id": "20d3a6a7-e3ed-402b-b786-19d50a9b607a",
    "type": "payouts",
    "attributes": {
      "absorbFees": null,
      "absorbNetworkFee": true,
      "absorbPayoutFee": true,
      "address": "TTbGTMwUwA3mncLP7xqCZei1ekaNSgeAJe",
      "amount": "50.00",
      "amountCharged": "51.39",
      "amountChargedCurrency": "EUR",
      "approvalStatus": null,
      "binanceStatus": null,
      "createdAt": "2026-05-15T18:45:39.275Z",
      "currency": "EUR",
      "displayFee": "0.50",
      "displayFeeCurrency": "EUR",
      "exchangeRate": "0.8866755",
      "expiresAt": "2026-05-15T18:46:09.275Z",
      "networkFee": "1.000000",
      "networkFeeCurrency": "USDT",
      "payAmount": "56.390416",
      "payChargeRate": "0.8866755",
      "payChargeRateCurrency": "EUR",
      "payCurrency": "USDT",
      "payNetwork": "ttrx:usdt",
      "payNetworkName": "Tron (TRC20)",
      "paymentMethod": "on_chain",
      "payoutFee": "0.50",
      "payoutFeeCurrency": "EUR",
      "receiverBinanceId": null,
      "reference": "70327e5f-9a3e-4720-b2e4-e899fcbbb956",
      "status": "processing",
      "txid": null
    },
    "relationships": {
      "accountCharged": {
        "data": {
          "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
          "type": "accounts"
        }
      },
      "author": {
        "data": {
          "id": "3cd066e3-94f7-4182-a242-bf3b4e8ea2da",
          "type": "apiKeys"
        }
      }
    }
  },
  "included": [
    {
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "type": "accounts",
      "attributes": {
        "balance": "39207.72",
        "bankDepositAvailable": true,
        "bankReference": "BDR6421088115176062",
        "bankWithdrawalAvailable": true,
        "currencyCode": "EUR",
        "currencyType": "fiat",
        "label": "master",
        "master": true,
        "totalBalance": null,
        "transferAvailable": true
      },
      "relationships": {
        "company": { "meta": { "included": false } },
        "networks": { "meta": { "included": false } },
        "txnBankCredentials": { "meta": { "included": false } }
      }
    },
    {
      "id": "3cd066e3-94f7-4182-a242-bf3b4e8ea2da",
      "type": "apiKeys",
      "attributes": {
        "createdAt": "2026-05-07T10:39:48.046Z",
        "name": "My API Key"
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}

{% tab title="HTTP 201 (with chargeCurrency)" %}
500 CNY display amount, EUR account debited, USDT sent via Tron. `currency`, `amountChargedCurrency`, and `payCurrency` are all different.

```json
{
  "data": {
    "id": "9d12fe2c-c8ac-44c7-b2f0-b9d11aa62f53",
    "type": "payouts",
    "attributes": {
      "absorbFees": null,
      "absorbNetworkFee": true,
      "absorbPayoutFee": true,
      "address": "TTbGTMwUwA3mncLP7xqCZei1ekaNSgeAJe",
      "amount": "500.00",
      "amountCharged": "64.84",
      "amountChargedCurrency": "EUR",
      "approvalStatus": null,
      "binanceStatus": null,
      "createdAt": "2026-05-19T15:40:37.788Z",
      "currency": "CNY",
      "displayFee": "5.00",
      "displayFeeCurrency": "CNY",
      "exchangeRate": "7.01285182",
      "expiresAt": "2026-05-19T15:41:07.788Z",
      "networkFee": "1.000000",
      "networkFeeCurrency": "USDT",
      "payAmount": "71.297671",
      "payChargeRate": "0.8881381",
      "payChargeRateCurrency": "EUR",
      "payCurrency": "USDT",
      "paymentMethod": "on_chain",
      "payNetwork": "ttrx:usdt",
      "payNetworkName": "Tron (TRC20)",
      "payoutFee": "0.63",
      "payoutFeeCurrency": "EUR",
      "receiverBinanceId": null,
      "reference": "docs-cny-eur-example-001",
      "status": "processing",
      "txid": null
    },
    "relationships": {
      "accountCharged": {
        "data": {
          "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
          "type": "accounts"
        }
      },
      "author": {
        "data": {
          "id": "b56961f4-46cf-4e60-bb32-b36addb09f66",
          "type": "apiKeys"
        }
      }
    }
  },
  "included": [
    {
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "type": "accounts",
      "attributes": {
        "balance": "38968.92",
        "bankDepositAvailable": true,
        "bankReference": "BDR6421088115176062",
        "bankWithdrawalAvailable": true,
        "currencyCode": "EUR",
        "currencyType": "fiat",
        "label": "master",
        "master": true,
        "totalBalance": null,
        "transferAvailable": true
      },
      "relationships": {
        "company": { "meta": { "included": false } },
        "networks": { "meta": { "included": false } },
        "txnBankCredentials": { "meta": { "included": false } }
      }
    },
    {
      "id": "b56961f4-46cf-4e60-bb32-b36addb09f66",
      "type": "apiKeys",
      "attributes": {
        "createdAt": "2024-06-17T19:41:33.398Z",
        "name": "Test API key"
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "amount is below minimum",
      "detail": "amount: 10.0, minimum: 50.00",
      "code": "amount_below_minimum"
    }
  ]
}
```

Amount too low.
{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "amount is above maximum",
      "detail": "amount: 500000.0, maximum: 100000.00",
      "code": "amount_above_maximum"
    }
  ]
}
```

Amount too high.
{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "Invalid address",
      "code": "invalid_address"
    }
  ]
}
```

Invalid address format.
{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "Invalid attribute",
      "detail": "Reference has already been taken",
      "code": "payout_invalid",
      "source": {
        "pointer": "/data/attributes/externalId"
      }
    }
  ]
}
```

Duplicate reference.
{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "account has insufficient balance",
      "code": "account_has_insufficient_balance"
    }
  ]
}
```

Your source account has insufficient funds.
{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "We couldn’t send funds to this address, please try another address",
      "code": "address_has_high_risk_score"
    }
  ]
}
```

Destination wallet address risk profile is too high.
{% endtab %}
{% endtabs %}


# Drafting payout (Optional)

<mark style="color:green;">`POST`</mark> `/api/public/v1/payouts/draft`

Creates a payout draft and locks the exchange rate for 30 seconds. No funds move at this stage — the draft transitions to `processing` only after you call [Confirming payout draft](/payouts/confirming-payout-draft-optional). If you do not confirm within 30 seconds, the draft expires and is automatically cancelled.

Use the draft flow when you want to show the user the exact amounts and rates before committing — for example, on a confirmation screen before the user clicks "Send".

{% hint style="danger" %}
Treat a confirmed draft as irreversible. Once you call the confirm endpoint, the payout is queued and cannot be recalled.
{% endhint %}

### XRP destination tag

XRP payouts require a destination tag appended to the wallet address as `address?dt=tag`. The destination tag identifies the specific recipient within a shared XRP wallet — without it, the funds cannot be attributed to the correct account.

Collect the destination tag from your recipient before creating the draft. If the recipient does not have a destination tag, pass `0`:

```
rwCQVZLSMNY6DgMH61317qvH3nHYqm68PF?dt=0
```

{% hint style="danger" %}
Do not use `dt=0` for wallets shared by multiple users such as exchange platforms or custodial wallets. Funds sent without a valid destination tag cannot be attributed to a specific account and may be permanently lost.
{% endhint %}

**cURL**

```bash
## Draft payout XRP

curl -X "POST" "https://api.sandbox.txn.io/api/public/v1/payouts/draft" \
     -H 'Content-Type: application/vnd.api+json' \
     -H 'Authorization: Bearer <api_key>' \
     -d $'{
  "data": {
    "type": "payouts",
    "attributes": {
      "reference": "b8ad764b-7951-4cbc-9a15-efa91d47fe4e",
      "amount": "1000",
      "currency": "TRY",
      "chargeCurrency": "EUR",
      "accountChargedId": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "absorbPayoutFee": true,
      "absorbNetworkFee": false,
      "address": "rLsBa2vWV2uuPx2UKbocAZG2WHXoaGyMPf?dt=61",
      "payNetwork": "txrp",
      "paymentMethod": "on_chain"
    }
  }
}'
```

**Headers**

<table><thead><tr><th width="320">Name</th><th>Value</th></tr></thead><tbody><tr><td>Content-Type</td><td><code>application/vnd.api+json</code></td></tr><tr><td>Authorization</td><td><code>Bearer &#x3C;api_key></code></td></tr></tbody></table>

**Request Body**

<table><thead><tr><th>Name</th><th width="100">Type</th><th width="105">Required</th><th>Description</th></tr></thead><tbody><tr><td>data.type</td><td>string</td><td>Yes</td><td>Can only be <code>payouts</code>.</td></tr><tr><td>data.attributes.reference</td><td>string</td><td>No</td><td>Your internal correlation key for this payout — use your order ID, user ID, or any value that lets you match this payout to a record in your system. Must be unique per payout.</td></tr><tr><td>data.attributes.amount</td><td>number</td><td>Yes</td><td>Payout amount in <code>currency</code>. Contact Txn support for minimum and maximum values per currency.</td></tr><tr><td>data.attributes.currency</td><td>string</td><td>Yes</td><td>Currency of the payout amount. When <code>chargeCurrency</code> is omitted, also determines which of your Txn account balances is debited. See <a href="/pages/SA7q0b6VrvXO3W09TQfS">Supported Currencies</a>.</td></tr><tr><td>data.attributes.chargeCurrency</td><td>string</td><td>No</td><td>Specifies from which merchant's currency account the payout amount and fees should be taken. Can be any tradable fiat or cryptocurrency listed on the <a href="/pages/SA7q0b6VrvXO3W09TQfS">Supported currencies</a> page — display fiat currencies are not accepted. If omitted, defaults to the <code>data.attributes.currency</code> account; in that case <code>currency</code> must itself be a tradable fiat or cryptocurrency, otherwise <code>chargeCurrency</code> must be supplied.</td></tr><tr><td>data.attributes.accountChargedId</td><td>string</td><td>No</td><td>ID of the account to debit the payout from. Can be a master or subaccount ID. Defaults to your master account. Requires <code>chargeCurrency</code>.</td></tr><tr><td>data.attributes.payNetwork</td><td>string</td><td>Yes</td><td>Network code for the cryptocurrency to send. See <a href="/pages/SA7q0b6VrvXO3W09TQfS">Supported Currencies</a>.</td></tr><tr><td>data.attributes.address</td><td>string</td><td>Yes</td><td>Recipient's wallet address. For XRP, include the destination tag as <code>address?dt=tag</code>.</td></tr><tr><td>data.attributes.absorbFees</td><td>boolean</td><td>No</td><td><mark style="color:red;">Deprecated.</mark> Use <code>absorbPayoutFee</code> and <code>absorbNetworkFee</code> instead.</td></tr><tr><td>data.attributes.absorbPayoutFee</td><td>boolean</td><td>No</td><td>If <code>false</code> or omitted, the payout fee is deducted from the amount the recipient receives. If <code>true</code>, the fee is charged to your account balance instead.</td></tr><tr><td>data.attributes.absorbNetworkFee</td><td>boolean</td><td>No</td><td>If <code>false</code> or omitted, the network fee is deducted from the amount the recipient receives. If <code>true</code>, the fee is charged to your account balance instead.</td></tr><tr><td>data.attributes.paymentMethod</td><td>string</td><td>No</td><td><code>on_chain</code> sends cryptocurrency directly to the recipient's wallet. <code>binance_pay</code> routes the payment off-chain through Binance Pay and requires <code>receiverBinanceId</code>. Defaults to <code>on_chain</code>.</td></tr><tr><td>data.attributes.receiverBinanceId</td><td>string</td><td>No</td><td>Recipient's Binance ID (7 or more digits). Required for <code>binance_pay</code> payouts. Validate it first using the <a href="/pages/ZmNuWGIc9tmIwns5ay5k">Validate Binance ID</a> endpoint.</td></tr></tbody></table>

**Response Body**

<table><thead><tr><th>Name</th><th width="96">Type</th><th>Description</th></tr></thead><tbody><tr><td>data.id</td><td>string</td><td>Payout draft ID.</td></tr><tr><td>data.type</td><td>string</td><td>Always <code>payouts</code>.</td></tr><tr><td>data.attributes.reference</td><td>string</td><td>Your internal correlation key, as set at creation.</td></tr><tr><td>data.attributes.status</td><td>string</td><td>Always <code>draft</code>. See <a href="/pages/ISxxub0HyhX1k8q53l50">Payout Status Flow</a>.</td></tr><tr><td>data.attributes.address</td><td>string</td><td>Recipient's wallet address.</td></tr><tr><td>data.attributes.createdAt</td><td>string</td><td>ISO 8601 timestamp of when the draft was created.</td></tr><tr><td>data.attributes.expiresAt</td><td>string</td><td>ISO 8601 timestamp of when the draft expires. The rate lock is valid until this time — confirm within 30 seconds.</td></tr><tr><td>data.attributes.absorbFees</td><td>boolean</td><td>Deprecated. Use <code>absorbPayoutFee</code> and <code>absorbNetworkFee</code> instead.</td></tr><tr><td>data.attributes.absorbPayoutFee</td><td>boolean</td><td>If <code>false</code>, the payout fee was deducted from the amount the recipient received. If <code>true</code>, the fee was charged to your account balance.</td></tr><tr><td>data.attributes.absorbNetworkFee</td><td>boolean</td><td>If <code>false</code>, the network fee was deducted from the amount the recipient received. If <code>true</code>, the fee was charged to your account balance.</td></tr><tr><td>data.attributes.amount</td><td>number</td><td>Payout amount in <code>currency</code>.</td></tr><tr><td>data.attributes.currency</td><td>string</td><td>Payout amount currency code.</td></tr><tr><td>data.attributes.payCurrency</td><td>string</td><td>Currency code of the cryptocurrency sent to the recipient.</td></tr><tr><td>data.attributes.payAmount</td><td>string</td><td>Amount of cryptocurrency sent to the recipient.</td></tr><tr><td>data.attributes.txid</td><td>string</td><td>On-chain transaction hash. Always <code>null</code> for drafts — populated after the draft is confirmed and the transaction is sent.</td></tr><tr><td>data.attributes.payNetwork</td><td>string</td><td>Network code of the cryptocurrency sent. See <a href="/pages/SA7q0b6VrvXO3W09TQfS">Supported Currencies</a>.</td></tr><tr><td>data.attributes.payNetworkName</td><td>string</td><td>Human-readable network name, e.g. <code>Ripple</code>.</td></tr><tr><td>data.attributes.networkFee</td><td>string</td><td>Network fee amount in <code>networkFeeCurrency</code>.</td></tr><tr><td>data.attributes.networkFeeCurrency</td><td>string</td><td>Currency of the network fee.</td></tr><tr><td>data.attributes.payoutFee</td><td>string</td><td>Txn service fee amount in <code>payoutFeeCurrency</code>.</td></tr><tr><td>data.attributes.payoutFeeCurrency</td><td>string</td><td>Currency of the Txn service fee.</td></tr><tr><td>data.attributes.displayFee</td><td>string</td><td>Payout fee expressed in <code>currency</code>.</td></tr><tr><td>data.attributes.displayFeeCurrency</td><td>string</td><td>Currency of <code>displayFee</code>. Always matches <code>currency</code>.</td></tr><tr><td>data.attributes.amountCharged</td><td>string</td><td>Total amount debited from your account, including all fees, in <code>amountChargedCurrency</code>.</td></tr><tr><td>data.attributes.amountChargedCurrency</td><td>string</td><td>Currency of <code>amountCharged</code>. Matches <code>chargeCurrency</code>.</td></tr><tr><td>data.attributes.payChargeRate</td><td>string</td><td>Exchange rate between <code>payCurrency</code> and <code>amountChargedCurrency</code> applied by Txn.</td></tr><tr><td>data.attributes.payChargeRateCurrency</td><td>string</td><td>Quote currency of <code>payChargeRate</code>.</td></tr><tr><td>data.attributes.exchangeRate</td><td>string</td><td>Exchange rate between <code>payCurrency</code> and <code>currency</code> applied by Txn.</td></tr><tr><td>data.attributes.paymentMethod</td><td>string</td><td>Payment method used: <code>on_chain</code> or <code>binance_pay</code>.</td></tr><tr><td>data.attributes.receiverBinanceId</td><td>string</td><td>Recipient's Binance ID. Present only for <code>binance_pay</code> payouts.</td></tr><tr><td>data.attributes.approvalStatus</td><td>string</td><td>Approval workflow status. Always <code>null</code> for API-created payouts.</td></tr><tr><td>data.attributes.binanceStatus</td><td>string</td><td>Binance Pay processing status. Present only for <code>binance_pay</code> payouts.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="HTTP 201" %}

```json
{
  "data": {
    "id": "6ecebf80-b210-413b-b396-df4760d142c5",
    "type": "payouts",
    "attributes": {
      "absorbFees": null,
      "absorbNetworkFee": false,
      "absorbPayoutFee": true,
      "address": "rLsBa2vWV2uuPx2UKbocAZG2WHXoaGyMPf?dt=61",
      "amount": "1000.00",
      "amountCharged": "22.70",
      "amountChargedCurrency": "USD",
      "approvalStatus": null,
      "binanceStatus": null,
      "createdAt": "2026-04-01T06:56:53.830Z",
      "currency": "TRY",
      "displayFee": "10.00",
      "displayFeeCurrency": "TRY",
      "exchangeRate": "62.3244527497791",
      "expiresAt": "2026-04-01T06:57:23.830Z",
      "networkFee": "1.000000",
      "networkFeeCurrency": "XRP",
      "payAmount": "15.045067",
      "payChargeRate": "1.4010781",
      "payChargeRateCurrency": "USD",
      "payCurrency": "XRP",
      "payNetwork": "txrp",
      "payNetworkName": "Ripple",
      "paymentMethod": "on_chain",
      "payoutFee": "0.22",
      "payoutFeeCurrency": "USD",
      "receiverBinanceId": null,
      "reference": "c533ca8f-63eb-4c0a-a784-4cdfc731ca31",
      "status": "draft",
      "txid": null
    },
    "relationships": {
      "accountCharged": {
        "data": {
          "id": "80b8dd61-35bc-49cc-9e04-f2c0f741a096",
          "type": "accounts"
        }
      },
      "author": {
        "data": {
          "id": "b56961f4-46cf-4e60-bb32-b36addb09f66",
          "type": "apiKeys"
        }
      }
    }
  },
  "included": [
    {
      "id": "80b8dd61-35bc-49cc-9e04-f2c0f741a096",
      "type": "accounts",
      "attributes": {
        "balance": "446.68",
        "bankDepositAvailable": true,
        "bankReference": "BDR3455470827278341",
        "bankWithdrawalAvailable": false,
        "currencyCode": "USD",
        "currencyType": "fiat",
        "label": "master",
        "master": true,
        "totalBalance": null,
        "transferAvailable": true
      },
      "relationships": {
        "company": { "meta": { "included": false } },
        "networks": { "meta": { "included": false } },
        "txnBankCredentials": { "meta": { "included": false } }
      }
    },
    {
      "id": "b56961f4-46cf-4e60-bb32-b36addb09f66",
      "type": "apiKeys",
      "attributes": {
        "createdAt": "2024-06-17T19:41:33.398Z",
        "name": "Test API key"
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "amount is below minimum",
      "detail": "amount: 10.0, minimum: 50.00",
      "code": "amount_below_minimum"
    }
  ]
}
```

Amount too low.
{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "amount is above maximum",
      "detail": "amount: 500000.0, maximum: 100000.00",
      "code": "amount_above_maximum"
    }
  ]
}
```

Amount too high.
{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "Invalid address",
      "code": "invalid_address"
    }
  ]
}
```

Invalid address format.
{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "Invalid attribute",
      "detail": "Reference has already been taken",
      "code": "payout_invalid",
      "source": {
        "pointer": "/data/attributes/externalId"
      }
    }
  ]
}
```

Duplicate reference.
{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "account has insufficient balance",
      "code": "account_has_insufficient_balance"
    }
  ]
}
```

Your source account has insufficient funds.
{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "We couldn't send funds to this address, please try another address",
      "code": "address_has_high_risk_score"
    }
  ]
}
```

Destination wallet address risk profile is too high.
{% endtab %}
{% endtabs %}


# Confirming payout draft (Optional)

<mark style="color:green;">`PUT`</mark> `/api/public/v1/payouts/:id`

Confirms a payout draft and queues it for broadcast. The draft transitions from `draft` to `processing` — the same end state as the [direct create endpoint](/payouts/creating-payout). Once confirmed, the payout cannot be recalled.

{% hint style="info" %}
The `txid` field is `null` immediately after confirmation and is populated once the transaction is broadcast. Poll [Read Payout](/payouts/reading-payout) to track progress.
{% endhint %}

**cURL**

{% code overflow="wrap" %}

```bash
curl -X "PUT" "https://api.sandbox.txn.io/api/public/v1/payouts/6ecebf80-b210-413b-b396-df4760d142c5" \
     -H 'Content-Type: application/vnd.api+json' \
     -H 'Authorization: Bearer <api_key>'
```

{% endcode %}

**Headers**

<table><thead><tr><th width="320">Name</th><th>Value</th></tr></thead><tbody><tr><td>Content-Type</td><td><code>application/vnd.api+json</code></td></tr><tr><td>Authorization</td><td><code>Bearer &#x3C;api_key></code></td></tr></tbody></table>

**Response Body**

<table><thead><tr><th>Name</th><th width="96">Type</th><th>Description</th></tr></thead><tbody><tr><td>data.id</td><td>string</td><td>Payout ID.</td></tr><tr><td>data.type</td><td>string</td><td>Always <code>payouts</code>.</td></tr><tr><td>data.attributes.reference</td><td>string</td><td>Your internal correlation key, as set at creation.</td></tr><tr><td>data.attributes.status</td><td>string</td><td>Always <code>processing</code> after confirmation. See <a href="/pages/ISxxub0HyhX1k8q53l50">Payout Status Flow</a>.</td></tr><tr><td>data.attributes.address</td><td>string</td><td>Recipient's wallet address.</td></tr><tr><td>data.attributes.createdAt</td><td>string</td><td>ISO 8601 timestamp of when the draft was created.</td></tr><tr><td>data.attributes.expiresAt</td><td>string</td><td>ISO 8601 timestamp of when the draft rate lock expired.</td></tr><tr><td>data.attributes.absorbFees</td><td>boolean</td><td>Deprecated. Use <code>absorbPayoutFee</code> and <code>absorbNetworkFee</code> instead.</td></tr><tr><td>data.attributes.absorbPayoutFee</td><td>boolean</td><td>If <code>false</code>, the payout fee was deducted from the amount the recipient received. If <code>true</code>, the fee was charged to your account balance.</td></tr><tr><td>data.attributes.absorbNetworkFee</td><td>boolean</td><td>If <code>false</code>, the network fee was deducted from the amount the recipient received. If <code>true</code>, the fee was charged to your account balance.</td></tr><tr><td>data.attributes.amount</td><td>number</td><td>Payout amount in <code>currency</code>.</td></tr><tr><td>data.attributes.currency</td><td>string</td><td>Payout amount currency code.</td></tr><tr><td>data.attributes.payCurrency</td><td>string</td><td>Currency code of the cryptocurrency sent to the recipient.</td></tr><tr><td>data.attributes.payAmount</td><td>string</td><td>Amount of cryptocurrency sent to the recipient.</td></tr><tr><td>data.attributes.txid</td><td>string</td><td>On-chain transaction hash. <code>null</code> immediately after confirmation — populated once the transaction is broadcast.</td></tr><tr><td>data.attributes.payNetwork</td><td>string</td><td>Network code of the cryptocurrency sent. See <a href="/pages/SA7q0b6VrvXO3W09TQfS">Supported Currencies</a>.</td></tr><tr><td>data.attributes.payNetworkName</td><td>string</td><td>Human-readable network name, e.g. <code>Ripple</code>.</td></tr><tr><td>data.attributes.networkFee</td><td>string</td><td>Network fee amount in <code>networkFeeCurrency</code>.</td></tr><tr><td>data.attributes.networkFeeCurrency</td><td>string</td><td>Currency of the network fee.</td></tr><tr><td>data.attributes.payoutFee</td><td>string</td><td>Txn service fee amount in <code>payoutFeeCurrency</code>.</td></tr><tr><td>data.attributes.payoutFeeCurrency</td><td>string</td><td>Currency of the Txn service fee.</td></tr><tr><td>data.attributes.displayFee</td><td>string</td><td>Payout fee expressed in <code>currency</code>.</td></tr><tr><td>data.attributes.displayFeeCurrency</td><td>string</td><td>Currency of <code>displayFee</code>. Always matches <code>currency</code>.</td></tr><tr><td>data.attributes.amountCharged</td><td>string</td><td>Total amount debited from your account, including all fees, in <code>amountChargedCurrency</code>.</td></tr><tr><td>data.attributes.amountChargedCurrency</td><td>string</td><td>Currency of <code>amountCharged</code>. Matches <code>chargeCurrency</code>.</td></tr><tr><td>data.attributes.payChargeRate</td><td>string</td><td>Exchange rate between <code>payCurrency</code> and <code>amountChargedCurrency</code> applied by Txn.</td></tr><tr><td>data.attributes.payChargeRateCurrency</td><td>string</td><td>Quote currency of <code>payChargeRate</code>.</td></tr><tr><td>data.attributes.exchangeRate</td><td>string</td><td>Exchange rate between <code>payCurrency</code> and <code>currency</code> applied by Txn.</td></tr><tr><td>data.attributes.paymentMethod</td><td>string</td><td>Payment method used: <code>on_chain</code> or <code>binance_pay</code>.</td></tr><tr><td>data.attributes.receiverBinanceId</td><td>string</td><td>Recipient's Binance ID. Present only for <code>binance_pay</code> payouts.</td></tr><tr><td>data.attributes.approvalStatus</td><td>string</td><td>Approval workflow status. Always <code>null</code> for API-created payouts.</td></tr><tr><td>data.attributes.binanceStatus</td><td>string</td><td>Binance Pay processing status. Present only for <code>binance_pay</code> payouts.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="HTTP 201" %}

```json
{
  "data": {
    "id": "6ecebf80-b210-413b-b396-df4760d142c5",
    "type": "payouts",
    "attributes": {
      "absorbFees": null,
      "absorbNetworkFee": false,
      "absorbPayoutFee": true,
      "address": "rLsBa2vWV2uuPx2UKbocAZG2WHXoaGyMPf?dt=61",
      "amount": "1000.00",
      "amountCharged": "22.70",
      "amountChargedCurrency": "USD",
      "approvalStatus": null,
      "binanceStatus": null,
      "createdAt": "2026-04-01T06:59:51.932Z",
      "currency": "TRY",
      "displayFee": "10.00",
      "displayFeeCurrency": "TRY",
      "exchangeRate": "62.412880924926",
      "expiresAt": "2026-04-01T07:00:21.932Z",
      "networkFee": "1.000000",
      "networkFeeCurrency": "XRP",
      "payAmount": "15.022334",
      "payChargeRate": "1.403066",
      "payChargeRateCurrency": "USD",
      "payCurrency": "XRP",
      "payNetwork": "txrp",
      "payNetworkName": "Ripple",
      "paymentMethod": "on_chain",
      "payoutFee": "0.22",
      "payoutFeeCurrency": "USD",
      "receiverBinanceId": null,
      "reference": "c5d423bb-3b08-44ba-9816-0ac633ef6081",
      "status": "processing",
      "txid": null
    },
    "relationships": {
      "accountCharged": {
        "data": {
          "id": "80b8dd61-35bc-49cc-9e04-f2c0f741a096",
          "type": "accounts"
        }
      },
      "author": {
        "data": {
          "id": "b56961f4-46cf-4e60-bb32-b36addb09f66",
          "type": "apiKeys"
        }
      }
    }
  },
  "included": [
    {
      "id": "80b8dd61-35bc-49cc-9e04-f2c0f741a096",
      "type": "accounts",
      "attributes": {
        "balance": "423.98",
        "bankDepositAvailable": true,
        "bankReference": "BDR3455470827278341",
        "bankWithdrawalAvailable": false,
        "currencyCode": "USD",
        "currencyType": "fiat",
        "label": "master",
        "master": true,
        "totalBalance": null,
        "transferAvailable": true
      },
      "relationships": {
        "company": { "meta": { "included": false } },
        "networks": { "meta": { "included": false } },
        "txnBankCredentials": { "meta": { "included": false } }
      }
    },
    {
      "id": "b56961f4-46cf-4e60-bb32-b36addb09f66",
      "type": "apiKeys",
      "attributes": {
        "createdAt": "2024-06-17T19:41:33.398Z",
        "name": "Test API key"
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "amount is below minimum",
      "detail": "amount: 10.0, minimum: 50.00",
      "code": "amount_below_minimum"
    }
  ]
}
```

Amount too low.
{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "amount is above maximum",
      "detail": "amount: 500000.0, maximum: 100000.00",
      "code": "amount_above_maximum"
    }
  ]
}
```

Amount too high.
{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "Invalid address",
      "code": "invalid_address"
    }
  ]
}
```

Invalid address format.
{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "Invalid attribute",
      "detail": "Reference has already been taken",
      "code": "payout_invalid",
      "source": {
        "pointer": "/data/attributes/externalId"
      }
    }
  ]
}
```

Duplicate reference.
{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "account has insufficient balance",
      "code": "account_has_insufficient_balance"
    }
  ]
}
```

Your source account has insufficient funds.
{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "We couldn't send funds to this address, please try another address",
      "code": "address_has_high_risk_score"
    }
  ]
}
```

Destination wallet address risk profile is too high.
{% endtab %}
{% endtabs %}


# Reading payout

<mark style="color:green;">`GET`</mark> `/api/public/v1/payouts/:id`

Returns a single payout by ID. Poll this endpoint after creating a payout to track `status` and `txid`.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**Path Parameters**

| Name | Value      |
| ---- | ---------- |
| id   | Payout ID. |

**Response Body**

<table><thead><tr><th>Name</th><th width="96">Type</th><th>Description</th></tr></thead><tbody><tr><td>data.id</td><td>string</td><td>Payout ID.</td></tr><tr><td>data.type</td><td>string</td><td>Always <code>payouts</code>.</td></tr><tr><td>data.attributes.reference</td><td>string</td><td>Your internal correlation key, as set at creation.</td></tr><tr><td>data.attributes.status</td><td>string</td><td>Payout status. Refer to <a href="/pages/ISxxub0HyhX1k8q53l50">Payout Status Flow</a>.</td></tr><tr><td>data.attributes.address</td><td>string</td><td>Recipient's wallet address.</td></tr><tr><td>data.attributes.createdAt</td><td>string</td><td>ISO 8601 timestamp of when the payout was created.</td></tr><tr><td>data.attributes.expiresAt</td><td>string</td><td>ISO 8601 timestamp of when the exchange rate lock expires.</td></tr><tr><td>data.attributes.absorbFees</td><td>boolean</td><td>Deprecated. Use <code>absorbPayoutFee</code> and <code>absorbNetworkFee</code> instead.</td></tr><tr><td>data.attributes.absorbPayoutFee</td><td>boolean</td><td>If <code>false</code>, the payout fee was deducted from the amount the recipient received. If <code>true</code>, the fee was charged to your account balance.</td></tr><tr><td>data.attributes.absorbNetworkFee</td><td>boolean</td><td>If <code>false</code>, the network fee was deducted from the amount the recipient received. If <code>true</code>, the fee was charged to your account balance.</td></tr><tr><td>data.attributes.amount</td><td>number</td><td>Payout amount in <code>currency</code>.</td></tr><tr><td>data.attributes.currency</td><td>string</td><td>Payout amount currency code.</td></tr><tr><td>data.attributes.payCurrency</td><td>string</td><td>Currency code of the cryptocurrency sent to the recipient.</td></tr><tr><td>data.attributes.payAmount</td><td>string</td><td>Amount of cryptocurrency sent to the recipient.</td></tr><tr><td>data.attributes.txid</td><td>string</td><td>On-chain transaction hash. <code>null</code> until the transaction is broadcast. Share with the recipient as proof of payment once populated.</td></tr><tr><td>data.attributes.payNetwork</td><td>string</td><td>Network code of the cryptocurrency sent. See <a href="/pages/SA7q0b6VrvXO3W09TQfS">Supported Currencies</a>.</td></tr><tr><td>data.attributes.payNetworkName</td><td>string</td><td>Human-readable network name, e.g. <code>Tron (TRC20)</code>.</td></tr><tr><td>data.attributes.networkFee</td><td>string</td><td>Network fee amount in <code>networkFeeCurrency</code>.</td></tr><tr><td>data.attributes.networkFeeCurrency</td><td>string</td><td>Currency of the network fee.</td></tr><tr><td>data.attributes.payoutFee</td><td>string</td><td>Txn service fee amount in <code>payoutFeeCurrency</code>.</td></tr><tr><td>data.attributes.payoutFeeCurrency</td><td>string</td><td>Currency of the Txn service fee.</td></tr><tr><td>data.attributes.displayFee</td><td>string</td><td>Payout fee expressed in <code>currency</code>.</td></tr><tr><td>data.attributes.displayFeeCurrency</td><td>string</td><td>Currency of <code>displayFee</code>. Always matches <code>currency</code>.</td></tr><tr><td>data.attributes.amountCharged</td><td>string</td><td>Total amount debited from your account, including all fees, in <code>amountChargedCurrency</code>.</td></tr><tr><td>data.attributes.amountChargedCurrency</td><td>string</td><td>Currency of <code>amountCharged</code>. Matches <code>chargeCurrency</code>.</td></tr><tr><td>data.attributes.payChargeRate</td><td>string</td><td>Exchange rate between <code>payCurrency</code> and <code>amountChargedCurrency</code> applied by Txn.</td></tr><tr><td>data.attributes.payChargeRateCurrency</td><td>string</td><td>Quote currency of <code>payChargeRate</code>.</td></tr><tr><td>data.attributes.exchangeRate</td><td>string</td><td>Exchange rate between <code>payCurrency</code> and <code>currency</code> applied by Txn.</td></tr><tr><td>data.attributes.paymentMethod</td><td>string</td><td>Payment method used: <code>on_chain</code> or <code>binance_pay</code>.</td></tr><tr><td>data.attributes.receiverBinanceId</td><td>string</td><td>Recipient's Binance ID. Present only for <code>binance_pay</code> payouts.</td></tr><tr><td>data.attributes.approvalStatus</td><td>string</td><td>Approval workflow status. <code>null</code> for API-created payouts. See <a href="/pages/ISxxub0HyhX1k8q53l50">Payout Status Flow</a>.</td></tr><tr><td>data.attributes.binanceStatus</td><td>string</td><td>Binance Pay processing status. Present only for <code>binance_pay</code> payouts.</td></tr><tr><td>included[].type(accounts).attributes</td><td>object</td><td>The account the payout was charged from. Includes standard account fields: <code>currencyCode</code>, <code>balance</code>, <code>bankWithdrawalAvailable</code>, <code>bankDepositAvailable</code>, <code>transferAvailable</code>, etc.</td></tr><tr><td>included[].type(apiKeys).attributes.name</td><td>string</td><td>Name of the API key that created the payout.</td></tr><tr><td>included[].type(apiKeys).attributes.createdAt</td><td>string</td><td>Timestamp when the API key was created.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": {
    "id": "9d12fe2c-c8ac-44c7-b2f0-b9d11aa62f53",
    "type": "payouts",
    "attributes": {
      "absorbFees": null,
      "absorbNetworkFee": true,
      "absorbPayoutFee": true,
      "address": "TTbGTMwUwA3mncLP7xqCZei1ekaNSgeAJe",
      "amount": "500.00",
      "amountCharged": "64.84",
      "amountChargedCurrency": "EUR",
      "approvalStatus": null,
      "binanceStatus": null,
      "createdAt": "2026-05-19T15:40:37.788Z",
      "currency": "CNY",
      "displayFee": "5.00",
      "displayFeeCurrency": "CNY",
      "exchangeRate": "7.01285182",
      "expiresAt": "2026-05-19T15:41:07.788Z",
      "networkFee": "1.000000",
      "networkFeeCurrency": "USDT",
      "payAmount": "71.297671",
      "payChargeRate": "0.8881381",
      "payChargeRateCurrency": "EUR",
      "payCurrency": "USDT",
      "paymentMethod": "on_chain",
      "payNetwork": "ttrx:usdt",
      "payNetworkName": "Tron (TRC20)",
      "payoutFee": "0.63",
      "payoutFeeCurrency": "EUR",
      "receiverBinanceId": null,
      "reference": "docs-cny-eur-example-001",
      "status": "completed",
      "txid": "c94f1a2b3d4e5f6071829384a5b6c7d8e9f0a1b2c3d4e5f607182938a4b5c6d7"
    },
    "relationships": {
      "accountCharged": {
        "data": {
          "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
          "type": "accounts"
        }
      },
      "author": {
        "data": {
          "id": "b56961f4-46cf-4e60-bb32-b36addb09f66",
          "type": "apiKeys"
        }
      }
    }
  },
  "included": [
    {
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "type": "accounts",
      "attributes": {
        "balance": "38904.08",
        "bankDepositAvailable": true,
        "bankReference": "BDR6421088115176062",
        "bankWithdrawalAvailable": true,
        "currencyCode": "EUR",
        "currencyType": "fiat",
        "label": "master",
        "master": true,
        "totalBalance": null,
        "transferAvailable": true
      },
      "relationships": {
        "company": { "meta": { "included": false } },
        "networks": { "meta": { "included": false } },
        "txnBankCredentials": { "meta": { "included": false } }
      }
    },
    {
      "id": "b56961f4-46cf-4e60-bb32-b36addb09f66",
      "type": "apiKeys",
      "attributes": {
        "createdAt": "2024-06-17T19:41:33.398Z",
        "name": "Test API key"
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}


# Listing payouts

<mark style="color:green;">`GET`</mark> `/api/public/v1/payouts`

Returns a paginated list of payouts, ordered by creation time by default.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**URL Parameters**

<table><thead><tr><th width="160.5435791015625">Name</th><th width="128">Type</th><th>Description</th></tr></thead><tbody><tr><td>order</td><td>string</td><td>Field to sort by. Supported value: <code>created_at</code>.</td></tr><tr><td>order_type</td><td>string</td><td>Sort direction. <code>asc</code> or <code>desc</code>.</td></tr><tr><td>page</td><td>number</td><td>Page number to return.</td></tr><tr><td>per_page</td><td>number</td><td>Number of results per page.</td></tr><tr><td>reference</td><td>string</td><td>Filter by payout <code>reference</code>.</td></tr><tr><td>created_at_from</td><td>string</td><td>Return payouts created at or after this ISO 8601 timestamp, e.g. <code>2024-06-18T15:49:02.031Z</code>.</td></tr><tr><td>created_at_to</td><td>string</td><td>Return payouts created at or before this ISO 8601 timestamp, e.g. <code>2024-06-18T15:49:02.031Z</code>.</td></tr></tbody></table>

**Response Body**

<table><thead><tr><th>Name</th><th width="96">Type</th><th>Description</th></tr></thead><tbody><tr><td>data[].id</td><td>string</td><td>Payout ID.</td></tr><tr><td>data[].type</td><td>string</td><td>Always <code>payouts</code>.</td></tr><tr><td>data[].attributes.reference</td><td>string</td><td>Your internal correlation key, as set at creation.</td></tr><tr><td>data[].attributes.status</td><td>string</td><td>Payout status. Refer to <a href="/pages/ISxxub0HyhX1k8q53l50">Payout Status Flow</a>.</td></tr><tr><td>data[].attributes.address</td><td>string</td><td>Recipient's wallet address.</td></tr><tr><td>data[].attributes.createdAt</td><td>string</td><td>ISO 8601 timestamp of when the payout was created.</td></tr><tr><td>data[].attributes.expiresAt</td><td>string</td><td>ISO 8601 timestamp of when the exchange rate lock expires.</td></tr><tr><td>data[].attributes.absorbFees</td><td>boolean</td><td>Deprecated. Use <code>absorbPayoutFee</code> and <code>absorbNetworkFee</code> instead.</td></tr><tr><td>data[].attributes.absorbPayoutFee</td><td>boolean</td><td>If <code>false</code>, the payout fee was deducted from the amount the recipient received. If <code>true</code>, the fee was charged to your account balance.</td></tr><tr><td>data[].attributes.absorbNetworkFee</td><td>boolean</td><td>If <code>false</code>, the network fee was deducted from the amount the recipient received. If <code>true</code>, the fee was charged to your account balance.</td></tr><tr><td>data[].attributes.amount</td><td>number</td><td>Payout amount in <code>currency</code>.</td></tr><tr><td>data[].attributes.currency</td><td>string</td><td>Payout amount currency code.</td></tr><tr><td>data[].attributes.payCurrency</td><td>string</td><td>Currency code of the cryptocurrency sent to the recipient.</td></tr><tr><td>data[].attributes.payAmount</td><td>string</td><td>Amount of cryptocurrency sent to the recipient.</td></tr><tr><td>data[].attributes.txid</td><td>string</td><td>On-chain transaction hash. <code>null</code> until the transaction is broadcast.</td></tr><tr><td>data[].attributes.payNetwork</td><td>string</td><td>Network code of the cryptocurrency sent. See <a href="/pages/SA7q0b6VrvXO3W09TQfS">Supported Currencies</a>.</td></tr><tr><td>data[].attributes.payNetworkName</td><td>string</td><td>Human-readable network name, e.g. <code>Tron (TRC20)</code>.</td></tr><tr><td>data[].attributes.networkFee</td><td>string</td><td>Network fee amount in <code>networkFeeCurrency</code>.</td></tr><tr><td>data[].attributes.networkFeeCurrency</td><td>string</td><td>Currency of the network fee.</td></tr><tr><td>data[].attributes.payoutFee</td><td>string</td><td>Txn service fee amount in <code>payoutFeeCurrency</code>.</td></tr><tr><td>data[].attributes.payoutFeeCurrency</td><td>string</td><td>Currency of the Txn service fee.</td></tr><tr><td>data[].attributes.displayFee</td><td>string</td><td>Payout fee expressed in <code>currency</code>.</td></tr><tr><td>data[].attributes.displayFeeCurrency</td><td>string</td><td>Currency of <code>displayFee</code>. Always matches <code>currency</code>.</td></tr><tr><td>data[].attributes.amountCharged</td><td>string</td><td>Total amount debited from your account, including all fees, in <code>amountChargedCurrency</code>.</td></tr><tr><td>data[].attributes.amountChargedCurrency</td><td>string</td><td>Currency of <code>amountCharged</code>. Matches <code>chargeCurrency</code>.</td></tr><tr><td>data[].attributes.payChargeRate</td><td>string</td><td>Exchange rate between <code>payCurrency</code> and <code>amountChargedCurrency</code> applied by Txn.</td></tr><tr><td>data[].attributes.payChargeRateCurrency</td><td>string</td><td>Quote currency of <code>payChargeRate</code>.</td></tr><tr><td>data[].attributes.exchangeRate</td><td>string</td><td>Exchange rate between <code>payCurrency</code> and <code>currency</code> applied by Txn.</td></tr><tr><td>data[].attributes.paymentMethod</td><td>string</td><td>Payment method used: <code>on_chain</code> or <code>binance_pay</code>.</td></tr><tr><td>data[].attributes.receiverBinanceId</td><td>string</td><td>Recipient's Binance ID. Present only for <code>binance_pay</code> payouts.</td></tr><tr><td>data[].attributes.approvalStatus</td><td>string</td><td>Approval workflow status. <code>null</code> for API-created payouts. See <a href="/pages/ISxxub0HyhX1k8q53l50">Payout Status Flow</a>.</td></tr><tr><td>data[].attributes.binanceStatus</td><td>string</td><td>Binance Pay processing status. Present only for <code>binance_pay</code> payouts.</td></tr><tr><td>meta.page</td><td>number</td><td>Current page number.</td></tr><tr><td>meta.per_page</td><td>number</td><td>Number of results per page.</td></tr><tr><td>meta.total</td><td>number</td><td>Total number of payouts matching the query.</td></tr><tr><td>included[].type(accounts).attributes</td><td>object</td><td>The account the payout was charged from. Includes standard account fields: <code>currencyCode</code>, <code>balance</code>, <code>bankWithdrawalAvailable</code>, <code>bankDepositAvailable</code>, <code>transferAvailable</code>, etc.</td></tr><tr><td>included[].type(apiKeys).attributes.name</td><td>string</td><td>Name of the API key that created the payout.</td></tr><tr><td>included[].type(apiKeys).attributes.createdAt</td><td>string</td><td>Timestamp when the API key was created.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": [
    {
      "id": "9d12fe2c-c8ac-44c7-b2f0-b9d11aa62f53",
      "type": "payouts",
      "attributes": {
        "absorbFees": null,
        "absorbNetworkFee": true,
        "absorbPayoutFee": true,
        "address": "TTbGTMwUwA3mncLP7xqCZei1ekaNSgeAJe",
        "amount": "500.00",
        "amountCharged": "64.84",
        "amountChargedCurrency": "EUR",
        "approvalStatus": null,
        "binanceStatus": null,
        "createdAt": "2026-05-19T15:40:37.788Z",
        "currency": "CNY",
        "displayFee": "5.00",
        "displayFeeCurrency": "CNY",
        "exchangeRate": "7.01285182",
        "expiresAt": "2026-05-19T15:41:07.788Z",
        "networkFee": "1.000000",
        "networkFeeCurrency": "USDT",
        "payAmount": "71.297671",
        "payChargeRate": "0.8881381",
        "payChargeRateCurrency": "EUR",
        "payCurrency": "USDT",
        "paymentMethod": "on_chain",
        "payNetwork": "ttrx:usdt",
        "payNetworkName": "Tron (TRC20)",
        "payoutFee": "0.63",
        "payoutFeeCurrency": "EUR",
        "receiverBinanceId": null,
        "reference": "docs-cny-eur-example-001",
        "status": "completed",
        "txid": "c94f1a2b3d4e5f6071829384a5b6c7d8e9f0a1b2c3d4e5f607182938a4b5c6d7"
      },
      "relationships": {
        "accountCharged": {
          "data": {
            "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
            "type": "accounts"
          }
        },
        "author": {
          "data": {
            "id": "b56961f4-46cf-4e60-bb32-b36addb09f66",
            "type": "apiKeys"
          }
        }
      }
    }
  ],
  "included": [
    {
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "type": "accounts",
      "attributes": {
        "balance": "38904.08",
        "bankDepositAvailable": true,
        "bankReference": "BDR6421088115176062",
        "bankWithdrawalAvailable": true,
        "currencyCode": "EUR",
        "currencyType": "fiat",
        "label": "master",
        "master": true,
        "totalBalance": null,
        "transferAvailable": true
      },
      "relationships": {
        "company": { "meta": { "included": false } },
        "networks": { "meta": { "included": false } },
        "txnBankCredentials": { "meta": { "included": false } }
      }
    },
    {
      "id": "b56961f4-46cf-4e60-bb32-b36addb09f66",
      "type": "apiKeys",
      "attributes": {
        "createdAt": "2024-06-17T19:41:33.398Z",
        "name": "Test API key"
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 1,
    "total": 2766
  },
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}


# Mass Payouts

## **What is Mass Payouts?**

The Mass Payouts feature allows you to send multiple cryptocurrency payments in a single batch. Instead of processing each payout individually, you can simply upload a CSV file containing all the payout details, and our platform will handle the rest - validating the data, calculating fees, and executing transactions seamlessly.

## **How It Works**

1. **Download the CSV template** from the Mass Payouts page in the user interface of your account
2. **Fill in the required details**, such as recipient addresses, amounts, and payout currencies
3. **Upload the completed CSV** to the platform
   1. When uploading the file, pay your attention to the "**Absorb fees**" toggle in the user interface
      1. If **FALSE**, both Txn service and network fees are deducted from the transaction amount
      2. If **TRUE**, both fees are deducted from your account balance instead
4. **Our system validates** the data
5. **Review and confirm** the batch before processing
6. **Our system executes** the payouts automatically

## CSV Template

{% file src="/files/fx2PVjgAwUfOtdGTuVFq" %}

## How to Populate the Mass Payout CSV

* **Charge Currency** → The currency of your account from which the payout amount will be deducted
* **Pay Currency** → The payout amount currency either it fiat or crypto
* **Pay Amount** →The payout amount
* **Pay Network** → The combination of blockchain/network to which the payout will be sent and a token, e.g. TRX:USDT means USDT will be sent over the Tron network (TRC20). Refer to the list of supported networks [here](/api-basics/supported-currencies)
* **Address** → The recipient's wallet address
* **Destination Tag** → Required only for XRP transactions
* **Reference** → A unique reference ID to link the payout to a recipient. This can be any identifier you choose, but it must be unique for each payout in the transaction
* **Beneficiary Type** → Select either **legal\_person** (for companies/organizations) or **natural\_person** (for persons)
* **Primary Identifier** →
  * If **legal\_person** → The complete legal entity name
  * If **natural\_person** → The first name
* **Secondary Identifier** →
  * If **legal\_person** → Leave empty
  * If **natural\_person** → The last name
* **Registered Address** →
  * If **legal\_person** → The official registered company address
  * If **natural\_person** → The residence address
* **City** → City name
* **Country** → Country name

## Example: How to Populate the Mass Payout CSV

### **Scenario 1**: Charging in Fiat and Paying in Crypto

<table data-header-hidden data-full-width="true"><thead><tr><th></th><th></th><th></th><th></th><th></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Charge Currency</strong></td><td><strong>Pay Currency</strong></td><td><strong>Pay Amount</strong></td><td><strong>Pay Network</strong></td><td><strong>Address</strong></td><td><strong>Destination Tag</strong></td><td><strong>Reference</strong></td></tr><tr><td>EUR</td><td>USDT</td><td>1000</td><td>TRX:USDT</td><td>TTbGTMwUwA3mncLP7xqCZei1ekaNSgeAJe</td><td>(empty)</td><td>(empty)</td></tr></tbody></table>

* This payout is **charged in EUR** from the sender’s account
* The recipient receives **1000** **USDT on the TRON network (TRX:USDT)**
* The recipient's wallet address is **TTbGTMwUwA3mncLP7xqCZei1ekaNSgeAJe**

### Scenario 2: Charging in Fiat and Paying in Fiat

<table data-header-hidden data-full-width="true"><thead><tr><th></th><th></th><th></th><th></th><th></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Charge Currency</strong></td><td><strong>Pay Currency</strong></td><td><strong>Pay Amount</strong></td><td><strong>Pay Network</strong></td><td><strong>Address</strong></td><td><strong>Destination Tag</strong></td><td><strong>Reference</strong></td></tr><tr><td>EUR</td><td>EUR</td><td>1000</td><td>TRX:USDT</td><td>TTbGTMwUwA3mncLP7xqCZei1ekaNSgeAJe</td><td>(empty)</td><td>(empty)</td></tr></tbody></table>

* This payout is charged in EUR from the sender’s account.
* The recipient receives 1,000 EUR worth of USDT on the TRON network (TRX:USDT).
* The recipient’s wallet address is TTbGTMwUwA3mncLP7xqCZei1ekaNSgeAJe.

### **Scenario 3**: Charging and Paying in the Same Cryptocurrency

<table data-header-hidden data-full-width="true"><thead><tr><th></th><th></th><th></th><th></th><th></th><th></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Charge Currency</strong></td><td><strong>Pay Currency</strong></td><td><strong>Pay Amount</strong></td><td><strong>Pay Network</strong></td><td><strong>Absorb Fees</strong></td><td><strong>Address</strong></td><td><strong>Destination Tag</strong></td><td><strong>Reference</strong></td></tr><tr><td>USDT</td><td>USDT</td><td>1000</td><td>TRX:USDT</td><td>FALSE</td><td>TTbGTMwUwA3mncLP7xqCZei1ekaNSgeAJe</td><td>(empty)</td><td>(empty)</td></tr></tbody></table>

* This payout is **charged directly in USDT**, meaning the amount specified (1000 USDT) is sent without conversion
* The recipient receives **1000 USDT on the TRON network (TRX:USDT)**
* The recipient’s wallet address is **TTbGTMwUwA3mncLP7xqCZei1ekaNSgeAJe**

## List of Supported Currencies

{% content-ref url="/pages/SA7q0b6VrvXO3W09TQfS" %}
[Supported currencies](/api-basics/supported-currencies)
{% endcontent-ref %}


# Payment links concept

A **Payment Link** is a Txn-hosted page that lets your end user select the cryptocurrency and network they want to use before a transaction is created. You create the link via API, send your end user to the `hostedPageUrl`, and Txn handles the rest — creating the child invoice or payout once the user makes their selection.

Payment links work with both invoices and payouts:

* **Invoice payment links** — the end user picks a cryptocurrency to pay with. Txn creates a child invoice and redirects them to the invoice payment page.
* **Payout payment links** — the end user picks a cryptocurrency and submits their wallet address. Txn creates a child payout and sends funds to that address.

## Invoice payment links

<figure><img src="/files/E82QYpykVqh3GwXEBlKZ" alt=""><figcaption></figcaption></figure>

See [Invoices concept](/invoices/invoices-concept) and [Invoice status flow](/invoices/invoice-status-flow) for details on the child invoice lifecycle.

## Payout payment links

<figure><img src="/files/FQFRudDLbz17dqBVPjli" alt=""><figcaption></figcaption></figure>

See [Payouts concept](/payouts/payouts-concept) and [Payout status flow](/payouts/payout-status-flow) for details on the child payout lifecycle.

## Payment link status

Payment link status is independent of its child invoice or payout status.

| Status    | Final? | Description                                                                                                                                                                        |
| --------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| created   | No     | The link has been created. The end user has not yet interacted with the hosted page.                                                                                               |
| pending   | No     | The end user has selected a cryptocurrency and triggered a child invoice or payout. Transitions to `completed` on success, or `expired` if the child transaction is not completed. |
| completed | Yes    | The end user successfully initiated a child invoice or payout through the payment link.                                                                                            |
| expired   | Yes    | The payment link expired before the end user completed the flow, or was manually expired via the [Expire Payment Link](/payment-links/expiring-payment-link) endpoint.             |

{% hint style="info" %}
**Payment link expiry is independent of child invoice and payout expiry.** A payment link and the invoice or payout it triggers each have their own expiry windows, configured separately.

For example: a payment link is set to expire in 20 minutes, and invoices on your account are configured to expire in 60 minutes. An end user opens the hosted page, selects a cryptocurrency at minute 15 (triggering an invoice with a fresh 60-minute window), and completes payment at minute 25. The payment link will show `expired` — it passed its 20-minute window — while the invoice will show `completed`. This is expected behaviour.

**Always use the child invoice or payout status to determine payment outcome**, not the payment link status. Subscribe to [invoice webhooks](/api-basics/webhooks) and [payout webhooks](/payouts/payout-webhooks) to receive real-time status updates on the actual transactions.
{% endhint %}

For child invoice and payout statuses:

* [Invoice status flow](/invoices/invoice-status-flow)
* [Payout status flow](/payouts/payout-status-flow)

## Hosted page examples

### Invoice payment link

The end user selects their preferred cryptocurrency and network:

<figure><img src="/files/C49TX3f5M877aRjDbQUY" alt=""><figcaption></figcaption></figure>

After clicking **Continue**, Txn creates an invoice and redirects the end user to the invoice payment page:

<figure><img src="/files/YaOD9cW1qB6zTtpH8Bcj" alt=""><figcaption></figcaption></figure>

### Payout payment link

The end user selects a cryptocurrency, network, and submits their wallet address:

<figure><img src="/files/AiuEUqyVPpKF6myV5P7m" alt=""><figcaption></figcaption></figure>

After clicking **Continue**, the end user reviews the payout details:

<figure><img src="/files/atvP5eQgB2trqIzOzeql" alt=""><figcaption></figcaption></figure>

After clicking **Confirm**, Txn initiates the cryptocurrency transfer to their wallet:

<figure><img src="/files/8xp1TwaggrguxzhyajaJ" alt=""><figcaption></figcaption></figure>


# Creating payment link

<mark style="color:green;">`POST`</mark> `/api/public/v1/payment_links`

Creates a payment link and returns a hosted page URL to redirect your end user to. The end user selects a cryptocurrency and network on the hosted page; Txn then creates the child invoice or payout automatically.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**Request Body**

<table><thead><tr><th>Name</th><th width="100">Type</th><th width="105">Required</th><th>Description</th></tr></thead><tbody><tr><td>data.type</td><td>string</td><td>Yes</td><td>Can only be <code>payment_links</code>.</td></tr><tr><td>data.attributes.amount</td><td>string</td><td>Yes</td><td>Payment amount to display to the end user.</td></tr><tr><td>data.attributes.currency</td><td>string</td><td>Yes</td><td>Display currency of the payment amount shown to the end user. Accepts any supported currency code — fiat or cryptocurrency. If <code>currency</code> is a display fiat currency (one that cannot be used directly as a settlement or funding account), <code>accountCurrency</code> must also be provided. See <a href="/pages/SA7q0b6VrvXO3W09TQfS">Supported Currencies</a>.</td></tr><tr><td>data.attributes.paymentType</td><td>string</td><td>Yes</td><td><code>Invoice</code> or <code>Payout</code>.</td></tr><tr><td>data.attributes.expires_at</td><td>string</td><td>Yes</td><td>ISO 8601 timestamp of when the payment link should expire, e.g. <code>2026-06-01T23:00:00.000Z</code>.</td></tr><tr><td>data.attributes.accountCurrency</td><td>string</td><td>No</td><td>Merchant account currency for settlement (invoice payment links) or funding (payout payment links). Equivalent to <code>targetCurrency</code> on invoices and <code>chargeCurrency</code> on payouts. Must be a tradable fiat or cryptocurrency — display fiat currencies are not accepted. If omitted, defaults to <code>currency</code>, which must then itself be a tradable fiat or cryptocurrency. See <a href="/pages/SA7q0b6VrvXO3W09TQfS">Supported Currencies</a>.</td></tr><tr><td>data.attributes.paymentMethods</td><td>array</td><td>No</td><td>Payment methods available on the hosted page. <code>on_chain</code> generates a deposit address for a direct on-chain transfer. <code>binance_pay</code> generates Binance Pay instructions. <code>nft</code> generates NFT purchase instructions. Defaults to <code>["on_chain"]</code>.</td></tr><tr><td>data.attributes.payCurrencies[]</td><td>array</td><td>No</td><td>Restrict which cryptocurrencies the end user can choose from on the hosted page. If omitted, all supported options are shown. See <a href="/pages/SA7q0b6VrvXO3W09TQfS">Supported Currencies</a>.</td></tr><tr><td>data.attributes.reference</td><td>string</td><td>No</td><td>Your internal correlation key for this payment link. Must be unique per payment link.</td></tr><tr><td>data.attributes.successRedirectUrl</td><td>string</td><td>No</td><td>Invoice payment links only. URL to redirect the end user to after successful payment.</td></tr><tr><td>data.attributes.unsuccessRedirectUrl</td><td>string</td><td>No</td><td>Invoice payment links only. URL to redirect the end user to if the invoice expires, is cancelled, or rejected.</td></tr></tbody></table>

**cURL**

```bash
curl -X "POST" "https://api.sandbox.txn.io/api/public/v1/payment_links" \
     -H 'Content-Type: application/vnd.api+json' \
     -H 'Authorization: Bearer <api_key>' \
     -d $'{
  "data": {
    "type": "payment_links",
    "attributes": {
      "amount": "100",
      "currency": "EUR",
      "accountCurrency": "EUR",
      "reference": "8c40d8b6-ccdf-4861-a6d6-6c3125ce3f31",
      "expires_at": "2026-06-01T23:00:00.000Z",
      "paymentType": "Invoice",
      "paymentMethods": ["on_chain"],
      "payCurrencies": ["USDT", "BTC"],
      "successRedirectUrl": "https://example.com/success",
      "unsuccessRedirectUrl": "https://example.com/fail"
    }
  }
}'
```

**Response Body**

<table><thead><tr><th>Name</th><th width="97">Type</th><th>Description</th></tr></thead><tbody><tr><td>data.id</td><td>string</td><td>Payment link ID.</td></tr><tr><td>data.type</td><td>string</td><td>Always <code>paymentLinks</code>.</td></tr><tr><td>data.attributes.amount</td><td>string</td><td>Payment amount displayed to the end user.</td></tr><tr><td>data.attributes.currency</td><td>string</td><td>Currency of the payment amount.</td></tr><tr><td>data.attributes.accountCurrency</td><td>string</td><td>Merchant account currency used for settlement or funding.</td></tr><tr><td>data.attributes.network</td><td>string</td><td>Network code selected by the end user on the hosted page. <code>null</code> until a selection is made.</td></tr><tr><td>data.attributes.networkName</td><td>string</td><td>Human-readable network name. <code>null</code> until the end user selects a network.</td></tr><tr><td>data.attributes.reference</td><td>string</td><td>Your internal correlation key, as set at creation.</td></tr><tr><td>data.attributes.hostedPageUrl</td><td>string</td><td>URL of the Txn-hosted page to redirect your end user to.</td></tr><tr><td>data.attributes.status</td><td>string</td><td>Payment link status. See <a href="/pages/2XgPefwnfLqZ7rf7y1ai">Payment Links Concept</a>.</td></tr><tr><td>data.attributes.approvalStatus</td><td>string</td><td>Approval workflow status for payout payment links subject to an approval rule. <code>null</code> otherwise.</td></tr><tr><td>data.attributes.expiresAt</td><td>string</td><td>ISO 8601 timestamp of when the payment link expires.</td></tr><tr><td>data.attributes.createdAt</td><td>string</td><td>ISO 8601 timestamp of when the payment link was created.</td></tr><tr><td>data.attributes.paymentType</td><td>string</td><td><code>Invoice</code> or <code>Payout</code>.</td></tr><tr><td>data.attributes.paymentMethods[]</td><td>array</td><td>Payment methods available on the hosted page.</td></tr><tr><td>data.attributes.successRedirectUrl</td><td>string</td><td>Success redirect URL. <code>null</code> if not set.</td></tr><tr><td>data.attributes.unsuccessRedirectUrl</td><td>string</td><td>Unsuccessful redirect URL. <code>null</code> if not set.</td></tr><tr><td>data.relationships.target.data</td><td>object</td><td>ID and type of the child invoice or payout. <code>null</code> until the end user selects a cryptocurrency on the hosted page.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="HTTP 201" %}

```json
{
  "data": {
    "id": "46df1a5c-a478-427f-a988-a2dacb235d6b",
    "type": "paymentLinks",
    "attributes": {
      "amount": "100.00",
      "currency": "EUR",
      "accountCurrency": "EUR",
      "network": null,
      "networkName": null,
      "reference": "8c40d8b6-ccdf-4861-a6d6-6c3125ce3f31",
      "hostedPageUrl": "https://sandbox.txn.io/redirect?payment_link_id=46df1a5c-a478-427f-a988-a2dacb235d6b&request_type=payment_link_hosted_page&zone=eu",
      "status": "created",
      "approvalStatus": null,
      "expiresAt": "2026-06-01T23:00:00.000Z",
      "createdAt": "2026-05-17T10:07:24.199Z",
      "paymentType": "Invoice",
      "successRedirectUrl": "https://example.com/success",
      "unsuccessRedirectUrl": "https://example.com/fail",
      "paymentMethods": [
        "on_chain"
      ]
    },
    "relationships": {
      "target": {
        "data": null
      }
    }
  },
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "title": "Reference duplicate",
      "detail": "8c40d8b6-ccdf-4861-a6d6-6c3125ce3f31",
      "code": "reference_duplicate"
    }
  ]
}
```

Duplicate reference.
{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "Unsupported pay currency",
      "code": "unsupported_pay_currency",
      "detail": ""
    }
  ]
}
```

Currency code in `payCurrencies` is not supported.
{% endtab %}
{% endtabs %}


# Expiring payment link

<mark style="color:green;">`POST`</mark> `/api/public/v1/payment_links/:id/expiration`

Immediately expires a payment link, transitioning its status to `expired`. Only payment links with status `created` or `pending` can be expired.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**Path Parameters**

| Name | Value            |
| ---- | ---------------- |
| id   | Payment link ID. |

**Response Body**

<table><thead><tr><th>Name</th><th width="97">Type</th><th>Description</th></tr></thead><tbody><tr><td>data.id</td><td>string</td><td>Payment link ID.</td></tr><tr><td>data.type</td><td>string</td><td>Always <code>paymentLinks</code>.</td></tr><tr><td>data.attributes.amount</td><td>string</td><td>Payment amount displayed to the end user.</td></tr><tr><td>data.attributes.currency</td><td>string</td><td>Currency of the payment amount.</td></tr><tr><td>data.attributes.accountCurrency</td><td>string</td><td>Merchant account currency used for settlement or funding.</td></tr><tr><td>data.attributes.network</td><td>string</td><td>Network code selected by the end user. <code>null</code> if not yet selected.</td></tr><tr><td>data.attributes.networkName</td><td>string</td><td>Human-readable network name. <code>null</code> if not yet selected.</td></tr><tr><td>data.attributes.reference</td><td>string</td><td>Your internal correlation key, as set at creation.</td></tr><tr><td>data.attributes.hostedPageUrl</td><td>string</td><td>URL of the Txn-hosted page.</td></tr><tr><td>data.attributes.status</td><td>string</td><td>Always <code>expired</code> after a successful call.</td></tr><tr><td>data.attributes.approvalStatus</td><td>string</td><td>Approval workflow status for payout payment links subject to an approval rule. <code>null</code> otherwise.</td></tr><tr><td>data.attributes.expiresAt</td><td>string</td><td>ISO 8601 timestamp of when the payment link expired.</td></tr><tr><td>data.attributes.createdAt</td><td>string</td><td>ISO 8601 timestamp of when the payment link was created.</td></tr><tr><td>data.attributes.paymentType</td><td>string</td><td><code>Invoice</code> or <code>Payout</code>.</td></tr><tr><td>data.attributes.paymentMethods[]</td><td>array</td><td>Payment methods that were available on the hosted page.</td></tr><tr><td>data.attributes.successRedirectUrl</td><td>string</td><td>Success redirect URL. <code>null</code> if not set.</td></tr><tr><td>data.attributes.unsuccessRedirectUrl</td><td>string</td><td>Unsuccessful redirect URL. <code>null</code> if not set.</td></tr><tr><td>data.relationships.target.data</td><td>object</td><td>ID and type of the child invoice or payout. <code>null</code> if none was triggered before expiry.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": {
    "id": "e33e1727-1eba-4581-bfd5-ded60713a5b8",
    "type": "paymentLinks",
    "attributes": {
      "amount": "50.00",
      "currency": "EUR",
      "accountCurrency": "EUR",
      "network": null,
      "networkName": null,
      "reference": "docs-example-pl-payout-001",
      "hostedPageUrl": "https://sandbox.txn.io/redirect?payment_link_id=e33e1727-1eba-4581-bfd5-ded60713a5b8&request_type=payment_link_hosted_page&zone=eu",
      "status": "expired",
      "approvalStatus": null,
      "expiresAt": "2026-05-17T10:07:53.269Z",
      "createdAt": "2026-05-17T10:07:43.353Z",
      "paymentType": "Payout",
      "successRedirectUrl": null,
      "unsuccessRedirectUrl": null,
      "paymentMethods": [
        "on_chain"
      ]
    },
    "relationships": {
      "target": {
        "data": null
      }
    }
  },
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}


# Reading payment link

<mark style="color:green;">`GET`</mark> `/api/public/v1/payment_links/:id`

Returns a single payment link by ID.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**Path Parameters**

| Name | Value            |
| ---- | ---------------- |
| id   | Payment link ID. |

**Response Body**

<table><thead><tr><th>Name</th><th width="97">Type</th><th>Description</th></tr></thead><tbody><tr><td>data.id</td><td>string</td><td>Payment link ID.</td></tr><tr><td>data.type</td><td>string</td><td>Always <code>paymentLinks</code>.</td></tr><tr><td>data.attributes.amount</td><td>string</td><td>Payment amount displayed to the end user.</td></tr><tr><td>data.attributes.currency</td><td>string</td><td>Currency of the payment amount.</td></tr><tr><td>data.attributes.accountCurrency</td><td>string</td><td>Merchant account currency used for settlement or funding.</td></tr><tr><td>data.attributes.network</td><td>string</td><td>Network code selected by the end user on the hosted page. <code>null</code> until a selection is made.</td></tr><tr><td>data.attributes.networkName</td><td>string</td><td>Human-readable network name. <code>null</code> until the end user selects a network.</td></tr><tr><td>data.attributes.reference</td><td>string</td><td>Your internal correlation key, as set at creation.</td></tr><tr><td>data.attributes.hostedPageUrl</td><td>string</td><td>URL of the Txn-hosted page to redirect your end user to.</td></tr><tr><td>data.attributes.status</td><td>string</td><td>Payment link status. See <a href="/pages/2XgPefwnfLqZ7rf7y1ai">Payment Links Concept</a>.</td></tr><tr><td>data.attributes.approvalStatus</td><td>string</td><td>Approval workflow status for payout payment links subject to an approval rule. <code>null</code> otherwise.</td></tr><tr><td>data.attributes.expiresAt</td><td>string</td><td>ISO 8601 timestamp of when the payment link expires.</td></tr><tr><td>data.attributes.createdAt</td><td>string</td><td>ISO 8601 timestamp of when the payment link was created.</td></tr><tr><td>data.attributes.paymentType</td><td>string</td><td><code>Invoice</code> or <code>Payout</code>.</td></tr><tr><td>data.attributes.paymentMethods[]</td><td>array</td><td>Payment methods available on the hosted page.</td></tr><tr><td>data.attributes.successRedirectUrl</td><td>string</td><td>Success redirect URL. <code>null</code> if not set.</td></tr><tr><td>data.attributes.unsuccessRedirectUrl</td><td>string</td><td>Unsuccessful redirect URL. <code>null</code> if not set.</td></tr><tr><td>data.relationships.target.data</td><td>object</td><td>ID and type of the child invoice or payout. <code>null</code> until the end user selects a cryptocurrency on the hosted page.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": {
    "id": "46df1a5c-a478-427f-a988-a2dacb235d6b",
    "type": "paymentLinks",
    "attributes": {
      "amount": "100.00",
      "currency": "EUR",
      "accountCurrency": "EUR",
      "network": null,
      "networkName": null,
      "reference": "8c40d8b6-ccdf-4861-a6d6-6c3125ce3f31",
      "hostedPageUrl": "https://sandbox.txn.io/redirect?payment_link_id=46df1a5c-a478-427f-a988-a2dacb235d6b&request_type=payment_link_hosted_page&zone=eu",
      "status": "created",
      "approvalStatus": null,
      "expiresAt": "2026-06-01T23:00:00.000Z",
      "createdAt": "2026-05-17T10:07:24.199Z",
      "paymentType": "Invoice",
      "successRedirectUrl": "https://example.com/success",
      "unsuccessRedirectUrl": "https://example.com/fail",
      "paymentMethods": [
        "on_chain"
      ]
    },
    "relationships": {
      "target": {
        "data": null
      }
    }
  },
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}


# Listing payment links

<mark style="color:green;">`GET`</mark> `/api/public/v1/payment_links`

Returns a paginated list of payment links, ordered by creation time by default.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**URL Parameters**

<table><thead><tr><th width="163">Name</th><th width="120">Type</th><th>Description</th></tr></thead><tbody><tr><td>order</td><td>string</td><td>Field to sort by. Supported value: <code>created_at</code>.</td></tr><tr><td>order_type</td><td>string</td><td>Sort direction. <code>asc</code> or <code>desc</code>.</td></tr><tr><td>page</td><td>number</td><td>Page number to return.</td></tr><tr><td>per_page</td><td>number</td><td>Number of results per page.</td></tr><tr><td>reference</td><td>string</td><td>Filter by payment link <code>reference</code>.</td></tr><tr><td>created_at_from</td><td>string</td><td>Return payment links created at or after this ISO 8601 timestamp, e.g. <code>2024-06-18T15:49:02.031Z</code>.</td></tr><tr><td>created_at_to</td><td>string</td><td>Return payment links created at or before this ISO 8601 timestamp, e.g. <code>2024-06-18T15:49:02.031Z</code>.</td></tr></tbody></table>

**Response Body**

<table><thead><tr><th>Name</th><th width="97">Type</th><th>Description</th></tr></thead><tbody><tr><td>data[].id</td><td>string</td><td>Payment link ID.</td></tr><tr><td>data[].type</td><td>string</td><td>Always <code>paymentLinks</code>.</td></tr><tr><td>data[].attributes.amount</td><td>string</td><td>Payment amount displayed to the end user.</td></tr><tr><td>data[].attributes.currency</td><td>string</td><td>Currency of the payment amount.</td></tr><tr><td>data[].attributes.accountCurrency</td><td>string</td><td>Merchant account currency used for settlement or funding.</td></tr><tr><td>data[].attributes.network</td><td>string</td><td>Network code selected by the end user. <code>null</code> until a selection is made.</td></tr><tr><td>data[].attributes.networkName</td><td>string</td><td>Human-readable network name. <code>null</code> until the end user selects a network.</td></tr><tr><td>data[].attributes.reference</td><td>string</td><td>Your internal correlation key, as set at creation.</td></tr><tr><td>data[].attributes.hostedPageUrl</td><td>string</td><td>URL of the Txn-hosted page to redirect your end user to.</td></tr><tr><td>data[].attributes.status</td><td>string</td><td>Payment link status. See <a href="/pages/2XgPefwnfLqZ7rf7y1ai">Payment Links Concept</a>.</td></tr><tr><td>data[].attributes.approvalStatus</td><td>string</td><td>Approval workflow status for payout payment links subject to an approval rule. <code>null</code> otherwise.</td></tr><tr><td>data[].attributes.expiresAt</td><td>string</td><td>ISO 8601 timestamp of when the payment link expires.</td></tr><tr><td>data[].attributes.createdAt</td><td>string</td><td>ISO 8601 timestamp of when the payment link was created.</td></tr><tr><td>data[].attributes.paymentType</td><td>string</td><td><code>Invoice</code> or <code>Payout</code>.</td></tr><tr><td>data[].attributes.paymentMethods[]</td><td>array</td><td>Payment methods available on the hosted page.</td></tr><tr><td>data[].attributes.successRedirectUrl</td><td>string</td><td>Success redirect URL. <code>null</code> if not set.</td></tr><tr><td>data[].attributes.unsuccessRedirectUrl</td><td>string</td><td>Unsuccessful redirect URL. <code>null</code> if not set.</td></tr><tr><td>data[].relationships.target.data</td><td>object</td><td>ID and type of the child invoice or payout. <code>null</code> until the end user selects a cryptocurrency on the hosted page.</td></tr><tr><td>meta.page</td><td>number</td><td>Current page number.</td></tr><tr><td>meta.per_page</td><td>number</td><td>Number of results per page.</td></tr><tr><td>meta.total</td><td>number</td><td>Total number of payment links matching the query.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": [
    {
      "id": "46df1a5c-a478-427f-a988-a2dacb235d6b",
      "type": "paymentLinks",
      "attributes": {
        "amount": "100.00",
        "currency": "EUR",
        "accountCurrency": "EUR",
        "network": null,
        "networkName": null,
        "reference": "8c40d8b6-ccdf-4861-a6d6-6c3125ce3f31",
        "hostedPageUrl": "https://sandbox.txn.io/redirect?payment_link_id=46df1a5c-a478-427f-a988-a2dacb235d6b&request_type=payment_link_hosted_page&zone=eu",
        "status": "created",
        "approvalStatus": null,
        "expiresAt": "2026-06-01T23:00:00.000Z",
        "createdAt": "2026-05-17T10:07:24.199Z",
        "paymentType": "Invoice",
        "successRedirectUrl": "https://example.com/success",
        "unsuccessRedirectUrl": "https://example.com/fail",
        "paymentMethods": [
          "on_chain"
        ]
      },
      "relationships": {
        "target": {
          "data": null
        }
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 1,
    "total": 264
  },
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}


# Channels concept

Unlike [invoices](/invoices/invoices-concept), channels are essentially permanent addresses assigned to each of your end-users. Once created, a channel can be reused by the end-user whenever they want to make a deposit.

{% hint style="warning" %}
Avoid assigning a single channel to multiple end-users, as it will prevent you from identifying which user sent the funds. Unlike fiat transactions, cryptocurrency transactions do not carry references over the blockchain. By giving each customer their own unique channel, you can easily match their deposits with their account on your platform.
{% endhint %}

Merchants can create either crypto-to-crypto or crypto-to-fiat channels. For crypto-to-fiat channels, no exchange rate is fixed for 20 minutes as with other transactions. Instead, the exchange rate is determined at the time the transaction is confirmed on the blockchain. Once confirmed, the cryptocurrency is converted to fiat and credited to the merchant's account on Txn.

A single channel can receive multiple deposits. Txn emits webhook messages for each transaction detected and received at the channel address. These messages contain data such as the channel ID and reference, deposit ID, crypto transaction amount and hash, exchange rate, credited amount, and timestamps.


# Channels deposit flow

## Channels flow of funds

<figure><img src="/files/k8ypkup2dpfT8eLxE8uo" alt=""><figcaption></figcaption></figure>

## Channels diagram

<figure><img src="/files/NNB1OPyv3gVlBVNvgPe7" alt=""><figcaption></figcaption></figure>

## Channel status list

<table><thead><tr><th width="156">status</th><th width="139">Final state?</th><th>Description</th></tr></thead><tbody><tr><td>enabled</td><td>no</td><td>The enabled state means that Txn will process incoming deposit transactions and credit the merchant's balance as usual.</td></tr><tr><td>disabled</td><td>no</td><td>The disabled state means that Txn won't process incoming deposits, convert crypto to fiat, or credit funds to the merchant's balance. This can be useful when merchants want to stop or pause deposits made through a particular channel.</td></tr></tbody></table>

## Channel Deposit status list

<table><thead><tr><th width="156">status</th><th width="139">Final state?</th><th>Description</th></tr></thead><tbody><tr><td>Pending</td><td>no</td><td>Deposit detected. Txn is awaiting transaction confirmation on the blockchain.</td></tr><tr><td>Completed</td><td>yes</td><td>Deposit confirmed on the blockchain. Txn has credited the funds to the merchant.</td></tr><tr><td>On Hold</td><td>no</td><td>Deposit has been evaluated as a risk and is subject to further review by Compliance.</td></tr><tr><td>Rejected</td><td>yes</td><td>Deposit has been rejected by Compliance.</td></tr></tbody></table>

<figure><img src="/files/5RSaHnZyQBkrwDwbxVpB" alt=""><figcaption><p>Channel Deposit status flow</p></figcaption></figure>


# Listing channel currency pairs

<mark style="color:green;">`GET`</mark> `/api/public/v1/channels/currency_pairs`

This endpoint returns a list of available currency pairs and networks.

**Headers**

| Name          | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/vnd.api+json |
| Authorization | Bearer \<api\_key>       |

**Response Body**

<table><thead><tr><th>Name</th><th width="97">Type</th><th>Description</th></tr></thead><tbody><tr><td>data[].id</td><td>string</td><td>Currency pair ID.</td></tr><tr><td>data[].type</td><td>string</td><td>Entity type returned. Always <code>channelCurrencyPairs</code>.</td></tr><tr><td>data[].attributes</td><td>object</td><td>Set of currency pair attributes.</td></tr><tr><td>data[].attributes.enabled</td><td>boolean</td><td>If <code>true</code>, the currency pair is available for channels.</td></tr><tr><td>data[].relationships.payCurrency.id</td><td>string</td><td>Crypto currency the customer pays in. Refer to <a href="/pages/SA7q0b6VrvXO3W09TQfS">supported currencies</a>.</td></tr><tr><td>data[].relationships.targetCurrency.id</td><td>string</td><td>Settlement currency credited to your account.</td></tr><tr><td>data[].relationships.localCurrency.id</td><td>string</td><td>Display currency shown to the end-user.</td></tr><tr><td>included[].type(currencies).attributes</td><td>object</td><td>Currency details, including <code>code</code>, <code>symbol</code>, <code>crypto</code>, and <code>subunitToUnit</code>.</td></tr><tr><td>included[].type(network).attributes</td><td>object</td><td>Network details, including <code>code</code>, <code>name</code>, and <code>currencyCode</code>.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": [
    {
      "id": "82756d59-a72f-499f-9657-edae023ac222",
      "type": "channelCurrencyPairs",
      "attributes": {
        "enabled": false
      },
      "relationships": {
        "targetCurrency": {
          "data": {
            "type": "currencies",
            "id": "USD"
          }
        },
        "payCurrency": {
          "data": {
            "type": "currencies",
            "id": "USDT"
          }
        }
      }
    },
    {
      "id": "0eb35771-0082-4ee0-b874-5d1b6028cefb",
      "type": "channelCurrencyPairs",
      "attributes": {
        "enabled": false
      },
      "relationships": {
        "targetCurrency": {
          "data": {
            "type": "currencies",
            "id": "USD"
          }
        },
        "payCurrency": {
          "data": {
            "type": "currencies",
            "id": "BTC"
          }
        }
      }
    },
    {
      "id": "4edc1cad-abf5-4227-b8e2-b0369c6151af",
      "type": "channelCurrencyPairs",
      "attributes": {
        "enabled": false
      },
      "relationships": {
        "targetCurrency": {
          "data": {
            "type": "currencies",
            "id": "USD"
          }
        },
        "payCurrency": {
          "data": {
            "type": "currencies",
            "id": "TRX"
          }
        }
      }
    },
    {
      "id": "aacdef29-b956-4e3b-ad4f-a4f930aa13d5",
      "type": "channelCurrencyPairs",
      "attributes": {
        "enabled": false
      },
      "relationships": {
        "targetCurrency": {
          "data": {
            "type": "currencies",
            "id": "EUR"
          }
        },
        "payCurrency": {
          "data": {
            "type": "currencies",
            "id": "USDT"
          }
        }
      }
    },
    {
      "id": "1bf7de3d-20c5-4467-a1fe-303fe4aa664a",
      "type": "channelCurrencyPairs",
      "attributes": {
        "enabled": false
      },
      "relationships": {
        "targetCurrency": {
          "data": {
            "type": "currencies",
            "id": "EUR"
          }
        },
        "payCurrency": {
          "data": {
            "type": "currencies",
            "id": "BTC"
          }
        }
      }
    },
    {
      "id": "db64658e-021f-45cb-9fff-3864d77ec87f",
      "type": "channelCurrencyPairs",
      "attributes": {
        "enabled": false
      },
      "relationships": {
        "targetCurrency": {
          "data": {
            "type": "currencies",
            "id": "EUR"
          }
        },
        "payCurrency": {
          "data": {
            "type": "currencies",
            "id": "TRX"
          }
        }
      }
    },
    {
      "id": "d559ad26-3bef-461f-a84e-cf155bee71e2",
      "type": "channelCurrencyPairs",
      "attributes": {
        "enabled": false
      },
      "relationships": {
        "targetCurrency": {
          "data": {
            "type": "currencies",
            "id": "TRY"
          }
        },
        "payCurrency": {
          "data": {
            "type": "currencies",
            "id": "USDT"
          }
        }
      }
    },
    {
      "id": "3459c743-9bff-4acb-82c5-2ad24405f13b",
      "type": "channelCurrencyPairs",
      "attributes": {
        "enabled": false
      },
      "relationships": {
        "targetCurrency": {
          "data": {
            "type": "currencies",
            "id": "TRY"
          }
        },
        "payCurrency": {
          "data": {
            "type": "currencies",
            "id": "BTC"
          }
        }
      }
    },
    {
      "id": "e61e7914-af51-4479-af13-990a14cd0710",
      "type": "channelCurrencyPairs",
      "attributes": {
        "enabled": false
      },
      "relationships": {
        "targetCurrency": {
          "data": {
            "type": "currencies",
            "id": "TRY"
          }
        },
        "payCurrency": {
          "data": {
            "type": "currencies",
            "id": "TRX"
          }
        }
      }
    },
    {
      "id": "863696ac-ca07-44db-8d0c-eb19e11bd623",
      "type": "channelCurrencyPairs",
      "attributes": {
        "enabled": false
      },
      "relationships": {
        "targetCurrency": {
          "data": {
            "type": "currencies",
            "id": "USDT"
          }
        },
        "payCurrency": {
          "data": {
            "type": "currencies",
            "id": "USDT"
          }
        }
      }
    },
    {
      "id": "d1fb7205-0396-4dfb-a476-a7b9207c812d",
      "type": "channelCurrencyPairs",
      "attributes": {
        "enabled": false
      },
      "relationships": {
        "targetCurrency": {
          "data": {
            "type": "currencies",
            "id": "BTC"
          }
        },
        "payCurrency": {
          "data": {
            "type": "currencies",
            "id": "BTC"
          }
        }
      }
    },
    {
      "id": "77a15352-b7e3-404a-ba4f-361a51161b52",
      "type": "channelCurrencyPairs",
      "attributes": {
        "enabled": false
      },
      "relationships": {
        "targetCurrency": {
          "data": {
            "type": "currencies",
            "id": "TRX"
          }
        },
        "payCurrency": {
          "data": {
            "type": "currencies",
            "id": "TRX"
          }
        }
      }
    }
  ],
  "included": [
    {
      "id": "USD",
      "type": "currencies",
      "attributes": {
        "code": "USD",
        "crypto": false,
        "symbol": "$",
        "subunitToUnit": 100
      },
      "relationships": {
        "networks": {
          "data": []
        }
      }
    },
    {
      "id": "USDT",
      "type": "currencies",
      "attributes": {
        "code": "USDT",
        "crypto": true,
        "symbol": "₮",
        "subunitToUnit": 1000000
      },
      "relationships": {
        "networks": {
          "data": [
            {
              "type": "network",
              "id": "8ededca3-a1cd-4b46-8c3a-14915f706ab2"
            }
          ]
        }
      }
    },
    {
      "id": "BTC",
      "type": "currencies",
      "attributes": {
        "code": "BTC",
        "crypto": true,
        "symbol": "฿",
        "subunitToUnit": 100000000
      },
      "relationships": {
        "networks": {
          "data": [
            {
              "type": "network",
              "id": "c0369c57-da08-4c60-b5ee-63e1e43d5ae4"
            }
          ]
        }
      }
    },
    {
      "id": "TRX",
      "type": "currencies",
      "attributes": {
        "code": "TRX",
        "crypto": true,
        "symbol": "TRX",
        "subunitToUnit": 1000000
      },
      "relationships": {
        "networks": {
          "data": [
            {
              "type": "network",
              "id": "dc5f15f5-176e-43b6-ab8d-239614a7961d"
            }
          ]
        }
      }
    },
    {
      "id": "EUR",
      "type": "currencies",
      "attributes": {
        "code": "EUR",
        "crypto": false,
        "symbol": "€",
        "subunitToUnit": 100
      },
      "relationships": {
        "networks": {
          "data": []
        }
      }
    },
    {
      "id": "TRY",
      "type": "currencies",
      "attributes": {
        "code": "TRY",
        "crypto": false,
        "symbol": "₺",
        "subunitToUnit": 100
      },
      "relationships": {
        "networks": {
          "data": []
        }
      }
    },
    {
      "id": "8ededca3-a1cd-4b46-8c3a-14915f706ab2",
      "type": "network",
      "attributes": {
        "currencyCode": "USDT",
        "name": "Tron (TRC20)",
        "code": "ttrx:usdt"
      }
    },
    {
      "id": "c0369c57-da08-4c60-b5ee-63e1e43d5ae4",
      "type": "network",
      "attributes": {
        "currencyCode": "BTC",
        "name": "Bitcoin",
        "code": "tbtc"
      }
    },
    {
      "id": "dc5f15f5-176e-43b6-ab8d-239614a7961d",
      "type": "network",
      "attributes": {
        "currencyCode": "TRX",
        "name": "Tron",
        "code": "ttrx"
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}


# Channel webhooks

Txn sends a channel webhook each time a channel deposit's `status` changes. The payload mirrors the [Read channel deposit](/channels/reading-channel-deposit) endpoint response.

The tabs below show example payloads for each status. For the lifecycle of a channel deposit, see [Channels deposit flow](/channels/channels-deposit-flow).

For configuring webhook URLs, retry behaviour, source IPs, and signature verification, see the general [Webhooks](/api-basics/webhooks) section.

{% tabs %}
{% tab title="Status Pending" %}

```json
{
  "data": {
    "attributes": {
      "address": "TUbpY2zUNFDcpacgNzoJczT4x8ctV2mmLn",
      "amount": "74.94",
      "amountCurrency": "EUR",
      "amountToLocalCurrencyRate": "53.3840874",
      "channelId": "ace25dae-dc26-4fdc-9a7a-6561237f340b",
      "clusterCategory": null,
      "clusterName": null,
      "consolidationFee": "0.00",
      "createdAt": "2026-05-26T09:45:58.636Z",
      "exchangeRate": "0.7971774",
      "fee": "4.78",
      "feeCurrency": "EUR",
      "hash": "9a6fe053bd758967e43ee10e82963110f9ac809c318371b2f4464908d112f19e",
      "localAmount": "4255.78",
      "localCurrency": "TRY",
      "networkCode": "ttrx:usdt",
      "networkFee": "0.000000",
      "networkFeeCurrency": "TRX",
      "networkFeeLocalAmount": "0.00",
      "networkFeePayAmount": "0.000000",
      "networkName": "Tron (TRC20)",
      "payAmount": "100.000000",
      "payCurrency": "USDT",
      "payToLocalCurrencyRate": "42.5578",
      "reference": "docs-try-eur-example-001",
      "riskScore": null,
      "simplifiedState": "pending",
      "sourceAddresses": [
        "TZDYuARwgbzsnEKQ6Z2srh8fZYsmqU4my2"
      ],
      "status": "pending",
      "updatedAt": "2026-05-26T09:45:58.636Z"
    },
    "id": "aefeea52-d59a-41a4-944a-0bbef4e38095",
    "type": "channelTransactions"
  },
  "meta": {}
}
```

{% endtab %}

{% tab title="Status Completed" %}

```json
{
  "data": {
    "attributes": {
      "address": "TUbpY2zUNFDcpacgNzoJczT4x8ctV2mmLn",
      "amount": "74.94",
      "amountCurrency": "EUR",
      "amountToLocalCurrencyRate": "53.3840874",
      "channelId": "ace25dae-dc26-4fdc-9a7a-6561237f340b",
      "clusterCategory": "Exchange",
      "clusterName": "Binance",
      "consolidationFee": "0.00",
      "createdAt": "2026-05-26T09:45:58.636Z",
      "exchangeRate": "0.7971774",
      "fee": "4.78",
      "feeCurrency": "EUR",
      "hash": "9a6fe053bd758967e43ee10e82963110f9ac809c318371b2f4464908d112f19e",
      "localAmount": "4255.78",
      "localCurrency": "TRY",
      "networkCode": "ttrx:usdt",
      "networkFee": "3.149500",
      "networkFeeCurrency": "TRX",
      "networkFeeLocalAmount": "44.43",
      "networkFeePayAmount": "1.043981",
      "networkName": "Tron (TRC20)",
      "payAmount": "100.000000",
      "payCurrency": "USDT",
      "payToLocalCurrencyRate": "42.5578",
      "reference": "docs-try-eur-example-001",
      "riskScore": "10.0",
      "simplifiedState": "completed",
      "sourceAddresses": [
        "TZDYuARwgbzsnEKQ6Z2srh8fZYsmqU4my2"
      ],
      "status": "completed",
      "updatedAt": "2026-05-26T09:46:01.307Z"
    },
    "id": "aefeea52-d59a-41a4-944a-0bbef4e38095",
    "type": "channelTransactions"
  },
  "meta": {}
}
```

{% endtab %}
{% endtabs %}

**Payload Description**

| Name                                      | Type   | Description                                                                                                                                                                                                                          |
| ----------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| data.id                                   | string | Channel deposit ID.                                                                                                                                                                                                                  |
| data.type                                 | string | Always `channelTransactions`.                                                                                                                                                                                                        |
| data.attributes.hash                      | string | Transaction hash.                                                                                                                                                                                                                    |
| data.attributes.amountCurrency            | string | Determines the currency due after processing and conversion. Refer to [supported](https://docs.txn.io/api-basics/supported-currencies) currencies.                                                                                   |
| data.attributes.amount                    | string | Determines the amount due **after** processing and conversion. This is the amount the end-user's deposit resulted in on your account.                                                                                                |
| data.attributes.payCurrency               | string | Crypto currency that customer paid in. Refer to [supported](/api-basics/supported-currencies) currencies.                                                                                                                            |
| data.attributes.payAmount                 | string | Crypto amount that customer paid in.                                                                                                                                                                                                 |
| data.attributes.localAmount               | string | Determines the deposit amount value **before** fees in a display currency like CNY, KRW, BRL, etc. **This is normally the amount you will want to credit to the user's account on your platform.**                                   |
| data.attributes.localCurrency             | string | Display currency code, e.g. CNY, KRW, BRW. This is normally your end-user's currency. Refer to [Supported currencies](/api-basics/supported-currencies)                                                                              |
| data.attributes.amountToLocalCurrencyRate | string | `amountCurrency` vs `localCurency` exchange rate.                                                                                                                                                                                    |
| data.attributes.exchangeRate              | string | `payCurrency` vs `amountCurrency` exchange rate applied to the deposit.                                                                                                                                                              |
| data.attributes.payToLocalCurrencyRate    | string | `payCurrency` vs `localCurrency` exchange rate.                                                                                                                                                                                      |
| data.attributes.fee                       | string | Fee amount taken by Txn for processing this deposit.                                                                                                                                                                                 |
| data.attributes.feeCurrency               | string | Fee currency.                                                                                                                                                                                                                        |
| data.attributes.consolidationFee          | string | Fee for consolidating the deposited funds to your account. Quoted in `feeCurrency`.                                                                                                                                                  |
| data.attributes.networkFee                | string | On-chain network fee for the deposit transaction, in `networkFeeCurrency`.                                                                                                                                                           |
| data.attributes.networkFeeCurrency        | string | Currency of the network fee — the network's native asset, e.g. `TRX`.                                                                                                                                                                |
| data.attributes.networkFeePayAmount       | string | Network fee expressed in `payCurrency`.                                                                                                                                                                                              |
| data.attributes.networkFeeLocalAmount     | string | Network fee expressed in `localCurrency`.                                                                                                                                                                                            |
| data.attributes.address                   | string | Channel address.                                                                                                                                                                                                                     |
| data.attributes.networkCode               | string | Network code.                                                                                                                                                                                                                        |
| data.attributes.networkName               | string | Network name.                                                                                                                                                                                                                        |
| data.attributes.reference                 | string | The custom reference ID inherited from the parent channel.                                                                                                                                                                           |
| data.attributes.channelId                 | string | The ID of the parent channel that this particular deposit is linked to.                                                                                                                                                              |
| data.attributes.status                    | string | Channel deposit status. Refer to the [Channel deposit flow](/channels/channels-deposit-flow) for more info.                                                                                                                          |
| data.attributes.simplifiedState           | string | Simplified channel deposit status.                                                                                                                                                                                                   |
| data.attributes.riskScore                 | string | Risk score for the deposit's source address from on-chain analytics screening, when available. `null` if no score was returned.                                                                                                      |
| data.attributes.clusterCategory           | string | Category of the entity the source address is attributed to by on-chain analytics, e.g. `Exchange`. `null` until screening completes.                                                                                                 |
| data.attributes.clusterName               | string | Name of the entity the source address is attributed to, e.g. `Binance`. `null` until screening completes.                                                                                                                            |
| data.attributes.sourceAddresses           | array  | Wallet address(es) the funds were sent from. Typically a single address; may contain multiple entries when the deposit arrived via a UTXO-based network (BTC, LTC, BCH, DOGE, etc.) and the sender’s wallet combined several inputs. |
| data.attributes.createdAt                 | string | Timestamp when a channel deposit was created.                                                                                                                                                                                        |
| data.attributes.updatedAt                 | string | Timestamp when a channel deposit was last updated.                                                                                                                                                                                   |


# Creating channel

<mark style="color:green;">`POST`</mark> `/api/public/v1/channels`

This endpoint creates channels.

**XRP Channel Addresses Format:**

For XRP channels, addresses are returned in the following format:

```css
rwCQVZLSMNY6DgMH61317qvH3nHYqm68PF?dt=xyz
```

where `xyz` is a unique destination tag generated for each channel.

A destination tag acts like a reference number in bank transfers, identifying the intended beneficiary of the transaction.

**Displaying Channel Deposit Addresses:**

* When showing the deposit address to your customers, separate the address and the destination tag, and ensure both are clearly viewable and copyable

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**Body**

| Name                            | Type   | Required | Description                                                                                                                                                                                                                                                                               |
| ------------------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| data.type                       | string | yes      | Always `channels`.                                                                                                                                                                                                                                                                        |
| data.attributes.targetCurrency  | string | yes      | Specifies the merchant’s currency account on the txn platform to which the deposit will be credited. Must be a tradable fiat or cryptocurrency listed on the [Supported currencies](https://docs.txn.io/api-basics/supported-currencies) page — display fiat currencies are not accepted. |
| data.attributes.targetAccountId | string | no       | Specifies the ID of the account to which the channel payments should be credited. Can be a master or subaccount ID. If not present, payments will be credited to your master account by default.                                                                                          |
| data.attributes.localCurrency   | string | no       | Currency to display to end users, e.g. their local currency in which they hold a balance on the merchant’s platform. This field is optional and can be different from the `targetCurrency` value.                                                                                         |
| data.attributes.payNetwork      | string | yes      | Payment network code. Refer to [supported](https://docs.txn.io/api-basics/supported-currencies) networks.                                                                                                                                                                                 |
| data.attributes.reference       | string | no       | The custom reference ID to tie the channel and its deposits to end-user who pays. This can be anything you choose. Must be a unique value for each channel you create.                                                                                                                    |
| data.attributes.status          | string | yes      | Channel status. Can be either `enabled` or `disabled`. If `enabled`, deposits get processed and credited to the merchant's account as normal. If `disabled`, deposits do not get credited to the merchant's account.                                                                      |

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": {
    "id": "ace25dae-dc26-4fdc-9a7a-6561237f340b",
    "type": "channels",
    "attributes": {
      "address": "TUbpY2zUNFDcpacgNzoJczT4x8ctV2mmLn",
      "createdAt": "2026-05-26T09:44:53.750Z",
      "hostedPageUrl": "https://sandbox.txn.io/redirect?channel_id=ace25dae-dc26-4fdc-9a7a-6561237f340b&request_type=channel_hosted_page&zone=eu",
      "localCurrency": "TRY",
      "network": "ttrx:usdt",
      "networkCode": "ttrx:usdt",
      "networkName": "Tron (TRC20)",
      "payCurrency": "USDT",
      "reference": "docs-try-eur-example-001",
      "status": "enabled",
      "targetCurrency": "EUR",
      "updatedAt": "2026-05-26T09:44:53.750Z"
    },
    "relationships": {
      "targetAccount": {
        "data": {
          "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
          "type": "accounts"
        }
      }
    }
  },
  "included": [
    {
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "type": "accounts",
      "attributes": {
        "balance": "38270.61",
        "bankDepositAvailable": true,
        "bankReference": "BDR6421088115176062",
        "bankWithdrawalAvailable": true,
        "currencyCode": "EUR",
        "currencyType": "fiat",
        "label": "master",
        "master": true,
        "totalBalance": null,
        "transferAvailable": true
      },
      "relationships": {
        "company": { "meta": { "included": false } },
        "networks": { "meta": { "included": false } },
        "txnBankCredentials": { "meta": { "included": false } }
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "title": "Reference must be unique within company",
      "detail": "Reference must be unique within company",
      "code": "reference must be unique within company"
    }
  ]
}
```

Duplicate reference.
{% endtab %}
{% endtabs %}

**Response Body**

| Name                                  | Type   | Description                                                                                                                                                                                                                                                                               |
| ------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| data.id                               | string | Channel ID.                                                                                                                                                                                                                                                                               |
| data.type                             | string | Always `channels`.                                                                                                                                                                                                                                                                        |
| data.attributes.targetCurrency        | string | Specifies the merchant’s currency account on the txn platform to which the deposit will be credited. Must be a tradable fiat or cryptocurrency listed on the [Supported currencies](https://docs.txn.io/api-basics/supported-currencies) page — display fiat currencies are not accepted. |
| data.attributes.localCurrency         | string | Currency to display to end users, e.g. their local currency in which they hold a balance on the merchant’s platform. This field is optional and can be different from the `targetCurrency` value.                                                                                         |
| data.attributes.payCurrency           | string | Crypto currency that customer must pay in. Refer to [supported](/api-basics/supported-currencies) currencies.                                                                                                                                                                             |
| data.attributes.address               | string | Channel address.                                                                                                                                                                                                                                                                          |
| data.attributes.networkCode           | string | Payment network code. Refer to [supported](https://docs.txn.io/api-basics/supported-currencies) networks.                                                                                                                                                                                 |
| data.attributes.network               | string | Alias for `networkCode`. Refer to [supported](https://docs.txn.io/api-basics/supported-currencies) networks.                                                                                                                                                                              |
| data.attributes.networkName           | string | Network name.                                                                                                                                                                                                                                                                             |
| data.attributes.hostedPageUrl         | string | Channel redirect URL hosted by Txn.                                                                                                                                                                                                                                                       |
| data.attributes.reference             | string | The custom reference ID to tie the channel and its deposits to end-user who pays.                                                                                                                                                                                                         |
| data.attributes.status                | string | Channel status. Can be either `enabled` or `disabled`. If `enabled`, deposits get processed and credited to the merchant’s account as normal. If `disabled`, deposits do not get credited to the merchant’s account.                                                                      |
| data.attributes.createdAt             | string | Timestamp when a channel was created.                                                                                                                                                                                                                                                     |
| data.attributes.updatedAt             | string | Timestamp when a channel was last updated.                                                                                                                                                                                                                                                |
| data.relationships.targetAccount      | object | Reference to the account the channel is credited to. The full account entity is returned in `included[]`.                                                                                                                                                                                 |
| included\[].type(accounts).attributes | object | The target account the channel payments are credited to. Includes standard account fields: `currencyCode`, `balance`, `bankWithdrawalAvailable`, `bankDepositAvailable`, `transferAvailable`, etc.                                                                                        |


# Reading channel

<mark style="color:green;">`GET`</mark> `/api/public/v1/channels/:id`

This endpoint returns details of a particular channel by its ID.

**Headers**

| Name         | Value                      |
| ------------ | -------------------------- |
| Content-Type | `application/vnd.api+json` |

**Path Parameters**

| Name | Type   | Description |
| ---- | ------ | ----------- |
| id   | string | Channel ID. |

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": {
    "id": "ace25dae-dc26-4fdc-9a7a-6561237f340b",
    "type": "channels",
    "attributes": {
      "address": "TUbpY2zUNFDcpacgNzoJczT4x8ctV2mmLn",
      "createdAt": "2026-05-26T09:44:53.750Z",
      "hostedPageUrl": "https://sandbox.txn.io/redirect?channel_id=ace25dae-dc26-4fdc-9a7a-6561237f340b&request_type=channel_hosted_page&zone=eu",
      "localCurrency": "TRY",
      "network": "ttrx:usdt",
      "networkCode": "ttrx:usdt",
      "networkName": "Tron (TRC20)",
      "payCurrency": "USDT",
      "reference": "docs-try-eur-example-001",
      "status": "enabled",
      "targetCurrency": "EUR",
      "updatedAt": "2026-05-26T09:44:53.750Z"
    },
    "relationships": {
      "targetAccount": {
        "data": {
          "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
          "type": "accounts"
        }
      }
    }
  },
  "included": [
    {
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "type": "accounts",
      "attributes": {
        "balance": "38345.55",
        "bankDepositAvailable": true,
        "bankReference": "BDR6421088115176062",
        "bankWithdrawalAvailable": true,
        "currencyCode": "EUR",
        "currencyType": "fiat",
        "label": "master",
        "master": true,
        "totalBalance": null,
        "transferAvailable": true
      },
      "relationships": {
        "company": { "meta": { "included": false } },
        "networks": { "meta": { "included": false } },
        "txnBankCredentials": { "meta": { "included": false } }
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}

{% tab title="HTTP 404" %}

```json
{
  "errors": [
    {
      "status": 404,
      "title": "Record not found",
      "code": "channel_not_found"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

**Response Body**

| Name                                  | Type   | Description                                                                                                                                                                                                                                                                               |
| ------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| data.id                               | string | Channel ID.                                                                                                                                                                                                                                                                               |
| data.type                             | string | Always `channels`.                                                                                                                                                                                                                                                                        |
| data.attributes.targetCurrency        | string | Specifies the merchant’s currency account on the txn platform to which the deposit will be credited. Must be a tradable fiat or cryptocurrency listed on the [Supported currencies](https://docs.txn.io/api-basics/supported-currencies) page — display fiat currencies are not accepted. |
| data.attributes.localCurrency         | string | Currency to display to end users, e.g. their local currency in which they hold a balance on the merchant’s platform. This field is optional and can be different from the `targetCurrency` value.                                                                                         |
| data.attributes.payCurrency           | string | Crypto currency that customer must pay in. Refer to [supported](/api-basics/supported-currencies) currencies.                                                                                                                                                                             |
| data.attributes.address               | string | Channel address.                                                                                                                                                                                                                                                                          |
| data.attributes.networkCode           | string | Payment network code. Refer to [supported](https://docs.txn.io/api-basics/supported-currencies) networks.                                                                                                                                                                                 |
| data.attributes.network               | string | Alias for `networkCode`. Refer to [supported](https://docs.txn.io/api-basics/supported-currencies) networks.                                                                                                                                                                              |
| data.attributes.networkName           | string | Network name.                                                                                                                                                                                                                                                                             |
| data.attributes.hostedPageUrl         | string | Channel redirect URL hosted by Txn.                                                                                                                                                                                                                                                       |
| data.attributes.reference             | string | The custom reference ID to tie the channel and its deposits to end-user who pays.                                                                                                                                                                                                         |
| data.attributes.status                | string | Channel status. Can be either `enabled` or `disabled`. If `enabled`, deposits get processed and credited to the merchant's account as normal. If `disabled`, deposits do not get credited to the merchant's account.                                                                      |
| data.attributes.createdAt             | string | Timestamp when a channel was created.                                                                                                                                                                                                                                                     |
| data.attributes.updatedAt             | string | Timestamp when a channel was last updated.                                                                                                                                                                                                                                                |
| data.relationships.targetAccount      | object | Reference to the account the channel is credited to. The full account entity is returned in `included[]`.                                                                                                                                                                                 |
| included\[].type(accounts).attributes | object | The target account the channel payments are credited to. Includes standard account fields: `currencyCode`, `balance`, `bankWithdrawalAvailable`, `bankDepositAvailable`, `transferAvailable`, etc.                                                                                        |


# Updating channel

<mark style="color:green;">`PATCH`</mark> `/api/public/v1/channels/:id/status`

This endpoints updates channel status.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**Path Parameters**

| Name | Type   | Description |
| ---- | ------ | ----------- |
| id   | string | Channel ID. |

**Body**

| Name                   | Type   | Description                            |
| ---------------------- | ------ | -------------------------------------- |
| data.type              | string | Always `channels`.                     |
| data.attributes.status | string | Can be either `enabled` or `disabled`. |

**Response**

{% tabs %}
{% tab title="HTTP 201" %}

```json
{
  "data": {
    "id": "ace25dae-dc26-4fdc-9a7a-6561237f340b",
    "type": "channels",
    "attributes": {
      "address": "TUbpY2zUNFDcpacgNzoJczT4x8ctV2mmLn",
      "createdAt": "2026-05-26T09:44:53.750Z",
      "hostedPageUrl": "https://sandbox.txn.io/redirect?channel_id=ace25dae-dc26-4fdc-9a7a-6561237f340b&request_type=channel_hosted_page&zone=eu",
      "localCurrency": "TRY",
      "network": "ttrx:usdt",
      "networkCode": "ttrx:usdt",
      "networkName": "Tron (TRC20)",
      "payCurrency": "USDT",
      "reference": "docs-try-eur-example-001",
      "status": "disabled",
      "targetCurrency": "EUR",
      "updatedAt": "2026-05-26T09:48:12.043Z"
    },
    "relationships": {
      "targetAccount": {
        "data": {
          "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
          "type": "accounts"
        }
      }
    }
  },
  "included": [
    {
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "type": "accounts",
      "attributes": {
        "balance": "38345.55",
        "bankDepositAvailable": true,
        "bankReference": "BDR6421088115176062",
        "bankWithdrawalAvailable": true,
        "currencyCode": "EUR",
        "currencyType": "fiat",
        "label": "master",
        "master": true,
        "totalBalance": null,
        "transferAvailable": true
      },
      "relationships": {
        "company": { "meta": { "included": false } },
        "networks": { "meta": { "included": false } },
        "txnBankCredentials": { "meta": { "included": false } }
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}

{% tab title="HTTP 404" %}

```json
{
  "errors": [
    {
      "status": 404,
      "title": "Record not found",
      "code": "channel_not_found"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

**Response Body**

| Name                           | Type   | Description                                                                                                                                                                                                                                                                               |
| ------------------------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| data.id                        | string | Channel ID.                                                                                                                                                                                                                                                                               |
| data.type                      | string | Always `channels`.                                                                                                                                                                                                                                                                        |
| data.attributes.targetCurrency | string | Specifies the merchant’s currency account on the txn platform to which the deposit will be credited. Must be a tradable fiat or cryptocurrency listed on the [Supported currencies](https://docs.txn.io/api-basics/supported-currencies) page — display fiat currencies are not accepted. |
| data.attributes.localCurrency  | string | Currency to display to end users, e.g. their local currency in which they hold a balance on the merchant’s platform. This field is optional and can be different from the `targetCurrency` value.                                                                                         |
| data.attributes.payCurrency    | string | Crypto currency that customer must pay in. Refer to [supported](/api-basics/supported-currencies) currencies.                                                                                                                                                                             |
| data.attributes.address        | string | Channel address.                                                                                                                                                                                                                                                                          |
| data.attributes.networkCode    | string | Payment network code. Refer to [supported](https://docs.txn.io/api-basics/supported-currencies) networks.                                                                                                                                                                                 |
| data.attributes.network        | string | Alias for `networkCode`. Refer to [supported](https://docs.txn.io/api-basics/supported-currencies) networks.                                                                                                                                                                              |
| data.attributes.networkName    | string | Network name.                                                                                                                                                                                                                                                                             |
| data.attributes.hostedPageUrl  | string | Channel redirect URL hosted by Txn.                                                                                                                                                                                                                                                       |
| data.attributes.reference      | string | The custom reference ID to tie the channel and its deposits to end-user who pays.                                                                                                                                                                                                         |
| data.attributes.status         | string | Channel status. Can be either `enabled` or `disabled`. If `enabled`, deposits get processed and credited to the merchant's account as normal. If `disabled`, deposits do not get credited to the merchant's account.                                                                      |
| data.attributes.createdAt      | string | Timestamp when a channel was created.                                                                                                                                                                                                                                                     |
| data.attributes.updatedAt      | string | Timestamp when a channel was last updated.                                                                                                                                                                                                                                                |


# Listing channels

<mark style="color:green;">`GET`</mark> `/api/public/v1/channels`

This endpoint returns a list of channels with pagination.<br>

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**URL Parameters**

| Name        | Type   | Description                                                                  |
| ----------- | ------ | ---------------------------------------------------------------------------- |
| order       | string | Order in which the list of channels should be returned. Can be `created_at`. |
| order\_type | string | Order type. Can be either `asc` or `desc`.                                   |
| page        | number | Page for which you want to return channels.                                  |
| per\_page   | number | Number of channels per page to return.                                       |
| reference   | number | Channel `reference`.                                                         |

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": [
    {
      "id": "ace25dae-dc26-4fdc-9a7a-6561237f340b",
      "type": "channels",
      "attributes": {
        "address": "TUbpY2zUNFDcpacgNzoJczT4x8ctV2mmLn",
        "createdAt": "2026-05-26T09:44:53.750Z",
        "hostedPageUrl": "https://sandbox.txn.io/redirect?channel_id=ace25dae-dc26-4fdc-9a7a-6561237f340b&request_type=channel_hosted_page&zone=eu",
        "localCurrency": "TRY",
        "network": "ttrx:usdt",
        "networkCode": "ttrx:usdt",
        "networkName": "Tron (TRC20)",
        "payCurrency": "USDT",
        "reference": "docs-try-eur-example-001",
        "status": "enabled",
        "targetCurrency": "EUR",
        "updatedAt": "2026-05-26T09:44:53.750Z"
      },
      "relationships": {
        "targetAccount": {
          "data": {
            "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
            "type": "accounts"
          }
        }
      }
    }
  ],
  "included": [
    {
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "type": "accounts",
      "attributes": {
        "balance": "38345.55",
        "bankDepositAvailable": true,
        "bankReference": "BDR6421088115176062",
        "bankWithdrawalAvailable": true,
        "currencyCode": "EUR",
        "currencyType": "fiat",
        "label": "master",
        "master": true,
        "totalBalance": null,
        "transferAvailable": true
      },
      "relationships": {
        "company": { "meta": { "included": false } },
        "networks": { "meta": { "included": false } },
        "txnBankCredentials": { "meta": { "included": false } }
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 10,
    "total": 5
  },
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}

**Response Body**

| Name                                  | Type   | Description                                                                                                                                                                                                                                                                               |
| ------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| data\[].id                            | string | Channel ID.                                                                                                                                                                                                                                                                               |
| data\[].type                          | string | Always `channels`.                                                                                                                                                                                                                                                                        |
| data\[].attributes.targetCurrency     | string | Specifies the merchant’s currency account on the txn platform to which the deposit will be credited. Must be a tradable fiat or cryptocurrency listed on the [Supported currencies](https://docs.txn.io/api-basics/supported-currencies) page — display fiat currencies are not accepted. |
| data\[].attributes.localCurrency      | string | Currency to display to end users, e.g. their local currency in which they hold a balance on the merchant’s platform. This field is optional and can be different from the `targetCurrency` value.                                                                                         |
| data\[].attributes.payCurrency        | string | Crypto currency that customer must pay in. Refer to [supported](/api-basics/supported-currencies) currencies.                                                                                                                                                                             |
| data\[].attributes.address            | string | Channel address.                                                                                                                                                                                                                                                                          |
| data\[].attributes.networkCode        | string | Payment network code. Refer to [supported](https://docs.txn.io/api-basics/supported-currencies) networks.                                                                                                                                                                                 |
| data\[].attributes.network            | string | Alias for `networkCode`. Refer to [supported](https://docs.txn.io/api-basics/supported-currencies) networks.                                                                                                                                                                              |
| data\[].attributes.networkName        | string | Network name.                                                                                                                                                                                                                                                                             |
| data\[].attributes.hostedPageUrl      | string | Channel redirect URL hosted by Txn.                                                                                                                                                                                                                                                       |
| data\[].attributes.reference          | string | The custom reference ID to tie the channel and its deposits to end-user who pays.                                                                                                                                                                                                         |
| data\[].attributes.status             | string | Channel status. Can be either `enabled` or `disabled`. If `enabled`, deposits get processed and credited to the merchant's account as normal. If `disabled`, deposits do not get credited to the merchant's account.                                                                      |
| data\[].attributes.createdAt          | string | Timestamp when a channel was created.                                                                                                                                                                                                                                                     |
| data\[].attributes.updatedAt          | string | Timestamp when a channel was last updated.                                                                                                                                                                                                                                                |
| data\[].relationships.targetAccount   | object | Reference to the account the channel is credited to. The full account entity is returned in `included[]`.                                                                                                                                                                                 |
| included\[].type(accounts).attributes | object | The target account the channel payments are credited to. Includes standard account fields: `currencyCode`, `balance`, `bankWithdrawalAvailable`, `bankDepositAvailable`, `transferAvailable`, etc.                                                                                        |
| meta.page                             | number | Current page number.                                                                                                                                                                                                                                                                      |
| meta.per\_page                        | number | Page size used for the response.                                                                                                                                                                                                                                                          |
| meta.total                            | number | Total number of channels matching the query.                                                                                                                                                                                                                                              |


# Listing channel deposits

<mark style="color:green;">`GET`</mark> `/api/public/v1/channels/:id/transactions`

This endpoint returns a paginated list of deposits for a specific channel.<br>

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**Body**

| Name | Type   | Description |
| ---- | ------ | ----------- |
| id   | string | Channel ID  |

**URL Parameters**

<table><thead><tr><th width="160.25311279296875">Name</th><th width="154.96551513671875">Type</th><th>Description</th></tr></thead><tbody><tr><td>order</td><td>string</td><td>Order in which the list of transactions should be returned. Can be <code>created_at</code>.</td></tr><tr><td>order_type</td><td>string</td><td>Order type. Can be either <code>asc</code> or <code>desc</code>.</td></tr><tr><td>page</td><td>number</td><td>Page for which you want to return transactions.</td></tr><tr><td>per_page</td><td>number</td><td>Number of transactions per page to return.</td></tr><tr><td>created_at_from</td><td>string</td><td>Date and time filter. Supports timestamps in ISO 8601 format, e.g. <code>2024-06-18T15:49:02.031Z</code>.</td></tr><tr><td>created_at_to</td><td>string</td><td>Date and time filter. Supports timestamps in ISO 8601 format, e.g. <code>2024-06-18T15:49:02.031Z</code>.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": [
    {
      "id": "aefeea52-d59a-41a4-944a-0bbef4e38095",
      "type": "channelTransactions",
      "attributes": {
        "address": "TUbpY2zUNFDcpacgNzoJczT4x8ctV2mmLn",
        "amount": "74.94",
        "amountCurrency": "EUR",
        "amountToLocalCurrencyRate": "53.3840874",
        "channelId": "ace25dae-dc26-4fdc-9a7a-6561237f340b",
        "clusterCategory": "Exchange",
        "clusterName": "Binance",
        "consolidationFee": "0.00",
        "createdAt": "2026-05-26T09:45:58.636Z",
        "exchangeRate": "0.7971774",
        "fee": "4.78",
        "feeCurrency": "EUR",
        "hash": "9a6fe053bd758967e43ee10e82963110f9ac809c318371b2f4464908d112f19e",
        "localAmount": "4255.78",
        "localCurrency": "TRY",
        "networkCode": "ttrx:usdt",
        "networkFee": "3.149500",
        "networkFeeCurrency": "TRX",
        "networkFeeLocalAmount": "44.43",
        "networkFeePayAmount": "1.043981",
        "networkName": "Tron (TRC20)",
        "payAmount": "100.000000",
        "payCurrency": "USDT",
        "payToLocalCurrencyRate": "42.5578",
        "reference": "docs-try-eur-example-001",
        "riskScore": "10.0",
        "simplifiedState": "completed",
        "sourceAddresses": [
          "TZDYuARwgbzsnEKQ6Z2srh8fZYsmqU4my2"
        ],
        "status": "completed",
        "updatedAt": "2026-05-26T09:46:01.307Z"
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 10,
    "total": 1
  },
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}

{% tab title="HTTP 404" %}

```json
{
  "errors": [
    {
      "status": 404,
      "title": "Record not found",
      "code": "channel_not_found"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

**Response Body**

| Name                                         | Type   | Description                                                                                                                                                                                                                          |
| -------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| data\[].id                                   | string | Channel deposit ID.                                                                                                                                                                                                                  |
| data\[].type                                 | string | Always `channelTransactions`.                                                                                                                                                                                                        |
| data\[].attributes.hash                      | string | Transaction hash.                                                                                                                                                                                                                    |
| data\[].attributes.amountCurrency            | string | Determines the currency due after processing and conversion. Refer to [supported](https://docs.txn.io/api-basics/supported-currencies) currencies.                                                                                   |
| data\[].attributes.amount                    | string | Determines the amount due **after** processing and conversion. This is the amount the end-user's deposit resulted in on your account.                                                                                                |
| data\[].attributes.payCurrency               | string | Crypto currency that customer paid in. Refer to [supported](/api-basics/supported-currencies) currencies.                                                                                                                            |
| data\[].attributes.payAmount                 | string | Crypto amount that customer paid in.                                                                                                                                                                                                 |
| data\[].attributes.localAmount               | string | Determines the deposit amount value **before** fees in a display currency like CNY, KRW, BRL, etc. **This is normally the amount you will want to credit to the user's account on your platform.**                                   |
| data\[].attributes.localCurrency             | string | Display currency code, e.g. CNY, KRW, BRW. This is normally your end-user's currency. Refer to [Supported currencies](/api-basics/supported-currencies)                                                                              |
| data\[].attributes.amountToLocalCurrencyRate | string | `amountCurrency` vs `localCurency` exchange rate.                                                                                                                                                                                    |
| data\[].attributes.exchangeRate              | string | `payCurrency` vs `amountCurrency` exchange rate applied to the deposit.                                                                                                                                                              |
| data\[].attributes.payToLocalCurrencyRate    | string | `payCurrency` vs `localCurrency` exchange rate.                                                                                                                                                                                      |
| data\[].attributes.fee                       | string | Fee amount taken by Txn for processing this deposit.                                                                                                                                                                                 |
| data\[].attributes.feeCurrency               | string | Fee currency.                                                                                                                                                                                                                        |
| data\[].attributes.networkFee                | string | On-chain network fee for the deposit transaction, in `networkFeeCurrency`.                                                                                                                                                           |
| data\[].attributes.networkFeeCurrency        | string | Currency of the network fee — the network's native asset, e.g. `TRX`.                                                                                                                                                                |
| data\[].attributes.networkFeePayAmount       | string | Network fee expressed in `payCurrency`.                                                                                                                                                                                              |
| data\[].attributes.networkFeeLocalAmount     | string | Network fee expressed in `localCurrency`.                                                                                                                                                                                            |
| data\[].attributes.consolidationFee          | string | Network fee for consolidating the deposited funds (e.g. combining UTXO inputs). Quoted in `feeCurrency`. `0.00` when not applicable.                                                                                                 |
| data\[].attributes.address                   | string | Channel address.                                                                                                                                                                                                                     |
| data\[].attributes.networkCode               | string | Network code.                                                                                                                                                                                                                        |
| data\[].attributes.networkName               | string | Network name.                                                                                                                                                                                                                        |
| data\[].attributes.reference                 | string | The custom reference ID inherited from the parent channel.                                                                                                                                                                           |
| data\[].attributes.channelId                 | string | The ID of the parent channel that this particular deposit is linked to.                                                                                                                                                              |
| data\[].attributes.status                    | string | Channel deposit status. Refer to the [Channel deposit flow](/channels/channels-deposit-flow) for more info.                                                                                                                          |
| data\[].attributes.riskScore                 | string | Risk score for the deposit's source address from on-chain analytics screening, when available. `null` if no score was returned.                                                                                                      |
| data\[].attributes.clusterCategory           | string | Category of the entity the source address is attributed to by on-chain analytics, e.g. `Exchange`. `null` until screening completes.                                                                                                 |
| data\[].attributes.clusterName               | string | Name of the entity the source address is attributed to, e.g. `Binance`. `null` until screening completes.                                                                                                                            |
| data\[].attributes.simplifiedState           | string | Simplified channel deposit status.                                                                                                                                                                                                   |
| data\[].attributes.sourceAddresses           | array  | Wallet address(es) the funds were sent from. Typically a single address; may contain multiple entries when the deposit arrived via a UTXO-based network (BTC, LTC, BCH, DOGE, etc.) and the sender’s wallet combined several inputs. |
| data\[].attributes.createdAt                 | string | Timestamp when a channel deposit was created.                                                                                                                                                                                        |
| data\[].attributes.updatedAt                 | string | Timestamp when a channel deposit was last updated.                                                                                                                                                                                   |
| meta.page                                    | number | Current page number.                                                                                                                                                                                                                 |
| meta.per\_page                               | number | Page size used for the response.                                                                                                                                                                                                     |
| meta.total                                   | number | Total number of deposits matching the query.                                                                                                                                                                                         |


# Reading channel deposit

<mark style="color:green;">`GET`</mark> `/api/public/v1/channels/:channel_id/transactions/:deposit_id`

This endpoint returns channel deposit details by its ID.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**Path Parameters**

| Name        | Type   | Description |
| ----------- | ------ | ----------- |
| channel\_id | string | Channel ID. |
| deposit\_id | string | Deposit ID. |

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": {
    "id": "aefeea52-d59a-41a4-944a-0bbef4e38095",
    "type": "channelTransactions",
    "attributes": {
      "address": "TUbpY2zUNFDcpacgNzoJczT4x8ctV2mmLn",
      "amount": "74.94",
      "amountCurrency": "EUR",
      "amountToLocalCurrencyRate": "53.3840874",
      "channelId": "ace25dae-dc26-4fdc-9a7a-6561237f340b",
      "clusterCategory": "Exchange",
      "clusterName": "Binance",
      "consolidationFee": "0.00",
      "createdAt": "2026-05-26T09:45:58.636Z",
      "exchangeRate": "0.7971774",
      "fee": "4.78",
      "feeCurrency": "EUR",
      "hash": "9a6fe053bd758967e43ee10e82963110f9ac809c318371b2f4464908d112f19e",
      "localAmount": "4255.78",
      "localCurrency": "TRY",
      "networkCode": "ttrx:usdt",
      "networkFee": "3.149500",
      "networkFeeCurrency": "TRX",
      "networkFeeLocalAmount": "44.43",
      "networkFeePayAmount": "1.043981",
      "networkName": "Tron (TRC20)",
      "payAmount": "100.000000",
      "payCurrency": "USDT",
      "payToLocalCurrencyRate": "42.5578",
      "reference": "docs-try-eur-example-001",
      "riskScore": "10.0",
      "simplifiedState": "completed",
      "sourceAddresses": [
        "TZDYuARwgbzsnEKQ6Z2srh8fZYsmqU4my2"
      ],
      "status": "completed",
      "updatedAt": "2026-05-26T09:46:01.307Z"
    }
  },
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}

**Response Body**

| Name                                      | Type   | Description                                                                                                                                                                                                                          |
| ----------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| data.id                                   | string | Channel deposit ID.                                                                                                                                                                                                                  |
| data.type                                 | string | Always `channelTransactions`.                                                                                                                                                                                                        |
| data.attributes.hash                      | string | Transaction hash.                                                                                                                                                                                                                    |
| data.attributes.amountCurrency            | string | Determines the currency due after processing and conversion. Refer to [supported](https://docs.txn.io/api-basics/supported-currencies) currencies.                                                                                   |
| data.attributes.amount                    | string | Determines the amount due **after** processing and conversion. This is the amount the end-user's deposit resulted in on your account.                                                                                                |
| data.attributes.payCurrency               | string | Crypto currency that customer paid in. Refer to [supported](/api-basics/supported-currencies) currencies.                                                                                                                            |
| data.attributes.payAmount                 | string | Crypto amount that customer paid in.                                                                                                                                                                                                 |
| data.attributes.localAmount               | string | Determines the deposit amount value **before** fees in a display currency like CNY, KRW, BRL, etc. **This is normally the amount you will want to credit to the user's account on your platform.**                                   |
| data.attributes.localCurrency             | string | Display currency code, e.g. CNY, KRW, BRW. This is normally your end-user's currency. Refer to [Supported currencies](/api-basics/supported-currencies)                                                                              |
| data.attributes.amountToLocalCurrencyRate | string | `amountCurrency` vs `localCurency` exchange rate.                                                                                                                                                                                    |
| data.attributes.exchangeRate              | string | `payCurrency` vs `amountCurrency` exchange rate applied to the deposit.                                                                                                                                                              |
| data.attributes.payToLocalCurrencyRate    | string | `payCurrency` vs `localCurrency` exchange rate.                                                                                                                                                                                      |
| data.attributes.fee                       | string | Fee amount taken by Txn for processing this deposit.                                                                                                                                                                                 |
| data.attributes.feeCurrency               | string | Fee currency.                                                                                                                                                                                                                        |
| data.attributes.consolidationFee          | string | Fee for consolidating the deposited funds to your account. Quoted in `feeCurrency`.                                                                                                                                                  |
| data.attributes.networkFee                | string | On-chain network fee for the deposit transaction, in `networkFeeCurrency`.                                                                                                                                                           |
| data.attributes.networkFeeCurrency        | string | Currency of the network fee — the network's native asset, e.g. `TRX`.                                                                                                                                                                |
| data.attributes.networkFeePayAmount       | string | Network fee expressed in `payCurrency`.                                                                                                                                                                                              |
| data.attributes.networkFeeLocalAmount     | string | Network fee expressed in `localCurrency`.                                                                                                                                                                                            |
| data.attributes.address                   | string | Channel address.                                                                                                                                                                                                                     |
| data.attributes.networkCode               | string | Network code.                                                                                                                                                                                                                        |
| data.attributes.networkName               | string | Network name.                                                                                                                                                                                                                        |
| data.attributes.reference                 | string | The custom reference ID inherited from the parent channel.                                                                                                                                                                           |
| data.attributes.channelId                 | string | The ID of the parent channel that this particular deposit is linked to.                                                                                                                                                              |
| data.attributes.status                    | string | Channel deposit status. Refer to the [Channel deposit flow](/channels/channels-deposit-flow) for more info.                                                                                                                          |
| data.attributes.simplifiedState           | string | Simplified channel deposit status.                                                                                                                                                                                                   |
| data.attributes.riskScore                 | string | Risk score for the deposit's source address from on-chain analytics screening, when available. `null` if no score was returned.                                                                                                      |
| data.attributes.clusterCategory           | string | Category of the entity the source address is attributed to by on-chain analytics, e.g. `Exchange`. `null` until screening completes.                                                                                                 |
| data.attributes.clusterName               | string | Name of the entity the source address is attributed to, e.g. `Binance`. `null` until screening completes.                                                                                                                            |
| data.attributes.sourceAddresses           | array  | Wallet address(es) the funds were sent from. Typically a single address; may contain multiple entries when the deposit arrived via a UTXO-based network (BTC, LTC, BCH, DOGE, etc.) and the sender’s wallet combined several inputs. |
| data.attributes.createdAt                 | string | Timestamp when a channel deposit was created.                                                                                                                                                                                        |
| data.attributes.updatedAt                 | string | Timestamp when a channel deposit was last updated.                                                                                                                                                                                   |


# Important information

{% hint style="danger" %}
All endpoints, response examples, and explained transaction behaviors listed in this section are in the beta phase of development. Further changes, which may break backward compatibility, can be expected. Please consider this information when integrating related endpoints into your system.
{% endhint %}


# Bank withdrawal webhooks

Txn sends a bank withdrawal webhook each time a bank withdrawal transaction's `simplifiedState` changes. The payload mirrors the [Read bank withdrawal](/fiat-settlements/reading-bank-withdrawal) endpoint response.

The tabs below show example payloads for each state.

For configuring webhook URLs, retry behaviour, source IPs, and signature verification, see the general [Webhooks](/api-basics/webhooks) section.

{% tabs %}
{% tab title="Pending" %}

```json
{
  "data": {
    "attributes": {
      "amount": "-1.01",
      "createdAt": "2025-01-28T17:21:13.534Z",
      "reference": null,
      "simplifiedState": "pending",
      "transactionType": "BankWithdrawalTransaction"
    },
    "id": "a67076da-14cc-4f20-a443-8ffe1766fd31",
    "relationships": {
      "account": {
        "meta": {
          "included": false
        }
      },
      "transactionDetails": {
        "data": {
          "id": "a67076da-14cc-4f20-a443-8ffe1766fd31",
          "type": "bank_withdrawal_transactions"
        }
      }
    },
    "type": "transactions"
  },
  "included": [
    {
      "attributes": {
        "absorbFees": true,
        "amount": "1.01",
        "bankBic": "GUPULT22XXX",
        "bankName": "BANK NAME",
        "beneficiaryName": "Acme Ltd",
        "createdAt": "2025-01-28T17:21:13.493Z",
        "currency": "EUR",
        "fee": "0.01",
        "iban": "LT563400023810000822",
        "payAmount": "1.00",
        "paymentStatus": "created",
        "reference": "BDR6421088115176062",
        "state": "pending",
        "updatedAt": "2025-01-28T17:21:13.493Z"
      },
      "id": "a67076da-14cc-4f20-a443-8ffe1766fd31",
      "relationships": {
        "account": {
          "data": {
            "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
            "type": "accounts"
          }
        },
        "bankAccount": {
          "data": {
            "id": "849b4c2d-698b-4bde-9203-5cddcb8ea6e1",
            "type": "bank_accounts"
          }
        }
      },
      "type": "bank_withdrawal_transactions"
    },
    {
      "attributes": {
        "bankBic": "GXPTLT22XXX",
        "bankName": "BANK NAME",
        "beneficiaryName": "Acme Ltd",
        "createdAt": "2024-11-21T14:01:20.154Z",
        "currencyCode": "EUR",
        "iban": "LT563400023810000822",
        "updatedAt": "2024-12-27T13:52:12.012Z"
      },
      "id": "849b4c2d-698b-4bde-9203-5cddcb8ea6e1",
      "type": "bank_accounts"
    },
    {
      "attributes": {
        "balance": "32218.80",
        "currencyCode": "EUR",
        "currencyType": "fiat"
      },
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "accounts"
    }
  ],
  "meta": {}
}
```

{% endtab %}

{% tab title="Completed" %}

```json
{
  "data": {
    "attributes": {
      "amount": "-1.01",
      "createdAt": "2025-01-28T17:22:11.008Z",
      "reference": null,
      "simplifiedState": "completed",
      "transactionType": "BankWithdrawalTransaction"
    },
    "id": "a67076da-14cc-4f20-a443-8ffe1766fd31",
    "relationships": {
      "account": {
        "meta": {
          "included": false
        }
      },
      "transactionDetails": {
        "data": {
          "id": "a67076da-14cc-4f20-a443-8ffe1766fd31",
          "type": "bank_withdrawal_transactions"
        }
      }
    },
    "type": "transactions"
  },
  "included": [
    {
      "attributes": {
        "absorbFees": true,
        "amount": "1.01",
        "bankBic": "GXPTLT22XXX",
        "bankName": "BANK NAME",
        "beneficiaryName": "Acme Ltd",
        "createdAt": "2025-01-28T17:21:13.493Z",
        "currency": "EUR",
        "fee": "0.01",
        "iban": "LT563400023810000822",
        "payAmount": "1.00",
        "paymentStatus": "completed",
        "reference": "BDR6421088115176062",
        "state": "completed",
        "updatedAt": "2025-01-28T17:22:11.002Z"
      },
      "id": "a67076da-14cc-4f20-a443-8ffe1766fd31",
      "relationships": {
        "account": {
          "data": {
            "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
            "type": "accounts"
          }
        },
        "bankAccount": {
          "data": {
            "id": "849b4c2d-698b-4bde-9203-5cddcb8ea6e1",
            "type": "bank_accounts"
          }
        }
      },
      "type": "bank_withdrawal_transactions"
    },
    {
      "attributes": {
        "bankBic": "GUPULT22XXX",
        "bankName": "GURU PAY",
        "beneficiaryName": "Acme Ltd",
        "createdAt": "2024-11-21T14:01:20.154Z",
        "currencyCode": "EUR",
        "iban": "LT563400023810000822",
        "updatedAt": "2024-12-27T13:52:12.012Z"
      },
      "id": "849b4c2d-698b-4bde-9203-5cddcb8ea6e1",
      "type": "bank_accounts"
    },
    {
      "attributes": {
        "balance": "32218.80",
        "currencyCode": "EUR",
        "currencyType": "fiat"
      },
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "accounts"
    }
  ],
  "meta": {}
}
```

{% endtab %}

{% tab title="Cancelled" %}

```json
{
  "data": {
    "attributes": {
      "amount": "-1.01",
      "createdAt": "2025-01-28T17:24:27.302Z",
      "reference": null,
      "simplifiedState": "cancelled",
      "transactionType": "BankWithdrawalTransaction"
    },
    "id": "29e9704e-7ddc-4690-8f08-bb0fd7aad801",
    "relationships": {
      "account": {
        "meta": {
          "included": false
        }
      },
      "transactionDetails": {
        "data": {
          "id": "29e9704e-7ddc-4690-8f08-bb0fd7aad801",
          "type": "bank_withdrawal_transactions"
        }
      }
    },
    "type": "transactions"
  },
  "included": [
    {
      "attributes": {
        "absorbFees": true,
        "amount": "1.01",
        "bankBic": "GXPTLT22XXX",
        "bankName": "BANK NAME",
        "beneficiaryName": "Acme Ltd",
        "createdAt": "2025-01-28T17:24:11.463Z",
        "currency": "EUR",
        "fee": "0.01",
        "iban": "LT563400023810000822",
        "payAmount": "1.00",
        "paymentStatus": "cancelled",
        "reference": "BDR6421088115176062",
        "state": "cancelled",
        "updatedAt": "2025-01-28T17:24:27.293Z"
      },
      "id": "29e9704e-7ddc-4690-8f08-bb0fd7aad801",
      "relationships": {
        "account": {
          "data": {
            "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
            "type": "accounts"
          }
        },
        "bankAccount": {
          "data": {
            "id": "849b4c2d-698b-4bde-9203-5cddcb8ea6e1",
            "type": "bank_accounts"
          }
        }
      },
      "type": "bank_withdrawal_transactions"
    },
    {
      "attributes": {
        "bankBic": "GUPULT22XXX",
        "bankName": "GURU PAY",
        "beneficiaryName": "Acme Ltd",
        "createdAt": "2024-11-21T14:01:20.154Z",
        "currencyCode": "EUR",
        "iban": "LT563400023810000822",
        "updatedAt": "2024-12-27T13:52:12.012Z"
      },
      "id": "849b4c2d-698b-4bde-9203-5cddcb8ea6e1",
      "type": "bank_accounts"
    },
    {
      "attributes": {
        "balance": "32219.80",
        "currencyCode": "EUR",
        "currencyType": "fiat"
      },
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "accounts"
    }
  ],
  "meta": {}
}
```

{% endtab %}
{% endtabs %}


# Bank deposit webhooks

Txn sends a bank deposit webhook each time a bank deposit transaction's `simplifiedState` changes. The payload mirrors the [Read bank deposit](/fiat-settlements/reading-bank-deposit) endpoint response.

The tabs below show example payloads for each state.

For configuring webhook URLs, retry behaviour, source IPs, and signature verification, see the general [Webhooks](/api-basics/webhooks) section.

{% tabs %}
{% tab title="Pending" %}

```json
{
  "data": {
    "attributes": {
      "amount": "1.00",
      "createdAt": "2025-01-28T17:22:13.290Z",
      "reference": "26b7e971-e493-4e4c-86a1-a7a0f18c2444",
      "simplifiedState": "pending",
      "transactionType": "BankDepositTransaction"
    },
    "id": "a01776d7-30fb-4b13-98f1-fd635088f061",
    "relationships": {
      "account": {
        "meta": {
          "included": false
        }
      },
      "transactionDetails": {
        "data": {
          "id": "a01776d7-30fb-4b13-98f1-fd635088f061",
          "type": "bank_deposit_transactions"
        }
      }
    },
    "type": "transactions"
  },
  "included": [
    {
      "attributes": {
        "amount": "1.00",
        "createdAt": "2025-01-28T17:22:13.268Z",
        "currency": "EUR",
        "payerAddress": null,
        "payerBic": null,
        "payerIban": null,
        "payerName": null,
        "state": "confirmed",
        "updatedAt": "2025-01-28T17:22:13.268Z"
      },
      "id": "a01776d7-30fb-4b13-98f1-fd635088f061",
      "relationships": {
        "account": {
          "data": {
            "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
            "type": "accounts"
          }
        }
      },
      "type": "bank_deposit_transactions"
    },
    {
      "attributes": {
        "balance": "32218.80",
        "currencyCode": "EUR",
        "currencyType": "fiat"
      },
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "accounts"
    }
  ],
  "meta": {}
}
```

{% endtab %}

{% tab title="Completed" %}

```json
{
  "data": {
    "attributes": {
      "amount": "1.00",
      "createdAt": "2025-01-28T17:23:14.828Z",
      "reference": "26b7e971-e493-4e4c-86a1-a7a0f18c2444",
      "simplifiedState": "completed",
      "transactionType": "BankDepositTransaction"
    },
    "id": "a01776d7-30fb-4b13-98f1-fd635088f061",
    "relationships": {
      "account": {
        "meta": {
          "included": false
        }
      },
      "transactionDetails": {
        "data": {
          "id": "a01776d7-30fb-4b13-98f1-fd635088f061",
          "type": "bank_deposit_transactions"
        }
      }
    },
    "type": "transactions"
  },
  "included": [
    {
      "attributes": {
        "amount": "1.00",
        "createdAt": "2025-01-28T17:22:13.268Z",
        "currency": "EUR",
        "payerAddress": null,
        "payerBic": null,
        "payerIban": null,
        "payerName": null,
        "state": "completed",
        "updatedAt": "2025-01-28T17:22:13.268Z"
      },
      "id": "a01776d7-30fb-4b13-98f1-fd635088f061",
      "relationships": {
        "account": {
          "data": {
            "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
            "type": "accounts"
          }
        }
      },
      "type": "bank_deposit_transactions"
    },
    {
      "attributes": {
        "balance": "32219.80",
        "currencyCode": "EUR",
        "currencyType": "fiat"
      },
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "accounts"
    }
  ],
  "meta": {}
}
```

{% endtab %}

{% tab title="Cancelled" %}

```json
{
  "data": {
    "attributes": {
      "amount": "1.00",
      "createdAt": "2025-01-28T17:26:22.736Z",
      "reference": "344c23c1-f3d8-4a97-bcdf-d3d66a810103",
      "simplifiedState": "cancelled",
      "transactionType": "BankDepositTransaction"
    },
    "id": "09585b73-dfb9-41c0-a238-2e53d00f9608",
    "relationships": {
      "account": {
        "meta": {
          "included": false
        }
      },
      "transactionDetails": {
        "data": {
          "id": "09585b73-dfb9-41c0-a238-2e53d00f9608",
          "type": "bank_deposit_transactions"
        }
      }
    },
    "type": "transactions"
  },
  "included": [
    {
      "attributes": {
        "amount": "1.00",
        "createdAt": "2025-01-28T17:26:14.194Z",
        "currency": "EUR",
        "payerAddress": null,
        "payerBic": null,
        "payerIban": null,
        "payerName": null,
        "state": "cancelled",
        "updatedAt": "2025-01-28T17:26:14.194Z"
      },
      "id": "09585b73-dfb9-41c0-a238-2e53d00f9608",
      "relationships": {
        "account": {
          "data": {
            "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
            "type": "accounts"
          }
        }
      },
      "type": "bank_deposit_transactions"
    },
    {
      "attributes": {
        "balance": "32218.79",
        "currencyCode": "EUR",
        "currencyType": "fiat"
      },
      "id": "13a85b45-8543-41c7-b963-394d4ea128ae",
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        }
      },
      "type": "accounts"
    }
  ],
  "meta": {}
}
```

{% endtab %}
{% endtabs %}


# Listing bank accounts

<mark style="color:green;">`GET`</mark> `/api/public/v1/bank_accounts`

This endpoint returns a list of bank accounts linked to your Txn account.

{% hint style="info" %}
Please note that Txn clients cannot add beneficiaries themselves just yet. Instead, please reach out to your account manager.
{% endhint %}

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**Response Body**

<table><thead><tr><th>Name</th><th width="97">Type</th><th>Description</th></tr></thead><tbody><tr><td>data[].id</td><td>string</td><td>Bank account ID.</td></tr><tr><td>data[].type</td><td>string</td><td>Entity type returned. Always <code>bankAccounts</code>.</td></tr><tr><td>data[].attributes</td><td>object</td><td>Set of bank account attributes.</td></tr><tr><td>data[].attributes.beneficiaryName</td><td>string</td><td>Name of the beneficiary on the bank account.</td></tr><tr><td>data[].attributes.iban</td><td>string</td><td>Beneficiary IBAN.</td></tr><tr><td>data[].attributes.bankName</td><td>string</td><td>Name of the beneficiary's bank.</td></tr><tr><td>data[].attributes.bankBic</td><td>string</td><td>BIC/SWIFT code of the beneficiary's bank.</td></tr><tr><td>data[].attributes.currencyCode</td><td>string</td><td>Account currency code. Refer to <a href="/pages/SA7q0b6VrvXO3W09TQfS">supported currencies</a>.</td></tr><tr><td>data[].attributes.label</td><td>string</td><td>User-defined label for the bank account.</td></tr><tr><td>data[].attributes.createdAt</td><td>string</td><td>Timestamp when the bank account was created. Refer to the <a href="/pages/H7xWDJMZukOei8CS8tUW">Date and time format</a> page.</td></tr><tr><td>data[].attributes.updatedAt</td><td>string</td><td>Timestamp when the bank account was last updated.</td></tr><tr><td>meta.page</td><td>number</td><td>Current page number.</td></tr><tr><td>meta.per_page</td><td>number</td><td>Page size used for the response.</td></tr><tr><td>meta.total</td><td>number</td><td>Total number of bank accounts available.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": [
    {
      "id": "a754cd82-74a0-4c1c-a832-e83445bce2c5",
      "type": "bank_accounts",
      "attributes": {
        "beneficiaryName": "Acme Limited",
        "currencyCode": "EUR",
        "iban": "LT563400023810000822",
        "createdAt": "2024-12-07T11:42:27.571Z",
        "updatedAt": "2024-12-07T11:42:27.571Z",
        "bankBic": "GXPTLT22XXX",
        "bankName": "BANK NAME"
      }
    },
    {
      "id": "f96d0db2-3e5d-42b4-8e36-7a0ea2a951fe",
      "type": "bank_accounts",
      "attributes": {
        "beneficiaryName": "Acme Limited",
        "currencyCode": "EUR",
        "iban": "LT293400023810000823",
        "createdAt": "2024-10-24T14:13:11.802Z",
        "updatedAt": "2024-12-07T11:21:01.250Z",
        "bankBic": "GXPTLT22XXX",
        "bankName": "BANK NAME"
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 10,
    "total": 2
  },
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}


# Reading bank account

<mark style="color:green;">`GET`</mark> `/api/public/v1/bank_accounts/:id`

This endpoint returns details of a particular bank account by its ID.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**Path Parameters**

| Name | Value            |
| ---- | ---------------- |
| id   | Bank account ID. |

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": {
    "id": "a754cd82-74a0-4c1c-a832-e83445bce2c5",
    "type": "bank_accounts",
    "attributes": {
      "beneficiaryName": "Acme",
      "currencyCode": "EUR",
      "iban": "LT563400023810000822",
      "createdAt": "2024-12-07T11:42:27.571Z",
      "updatedAt": "2024-12-07T11:42:27.571Z",
      "bankBic": "GXPTLT22XXX",
      "bankName": "BANK NAME"
    }
  },
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}


# Previewing bank withdrawal

<mark style="color:green;">`POST`</mark> `/api/public/v1/transactions/bank_withdrawals/build`

This endpoint allows you to preview a bank withdrawal details before submitting an actual [Create Fiat Withdrawal](/fiat-settlements/creating-bank-withdrawal) request.

**Headers**

<table><thead><tr><th width="320">Name</th><th>Value</th></tr></thead><tbody><tr><td>Content-Type</td><td><code>application/vnd.api+json</code></td></tr><tr><td>Authorization</td><td><code>Bearer &#x3C;api_key></code></td></tr></tbody></table>

**Request Body**

```json
{
  "data": {
    "type": "bankWithdrawalTransactions",
    "attributes": {
      "absorb_fees": true,
      "account_id": "acd50522-de49-4aaa-a183-dc046ff27fd5",
      "bank_account_id": "a754cd82-74a0-4c1c-a832-e83445bce2c5",
      "amount": 1,
      "reference": "Fiat payout from Txn to Acme"
    }
  }
}
```

<table><thead><tr><th>Name</th><th width="100">Type</th><th width="105">Required</th><th>Description</th></tr></thead><tbody><tr><td>data.type</td><td>string</td><td>Yes</td><td>Can only be <code>bankWithdrawalTransactions</code>.</td></tr><tr><td>data.attributes.reference</td><td>string</td><td>Yes</td><td>The custom reference ID to tie the request to end-user or their account who gets paid. This can be anything you choose.</td></tr><tr><td>data.attributes.amount</td><td>number</td><td>Yes</td><td>Withdrawal amount.</td></tr><tr><td>data.attributes.account_id</td><td>string</td><td>Yes</td><td>Account ID on the Txn platform, e.g. your Euro account, which Txn will debit funds from.</td></tr><tr><td>data.attributes.bank_account_id</td><td>string</td><td>Yes</td><td>Beneficiary (bank account) ID. Refer to <a href="/pages/8yHTHPLZ0E9fbn4BIpy3">Listing Beneficiaries</a>.</td></tr><tr><td>absorbFees</td><td>boolean</td><td>No</td><td>If false or omitted, the service fee is deducted from the transaction amount. If true, the service fee is deducted from your account balance.</td></tr></tbody></table>

**Response Body**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": {
    "id": "",
    "type": "transactions",
    "attributes": {
      "createdAt": null,
      "simplifiedState": "pending",
      "transactionType": "BankWithdrawalTransaction",
      "amount": "-1.01",
      "reference": null
    },
    "relationships": {
      "account": {
        "meta": {
          "included": false
        }
      },
      "transactionDetails": {
        "data": {
          "type": "bank_withdrawal_transactions",
          "id": ""
        }
      }
    }
  },
  "included": [
    {
      "id": "",
      "type": "bank_withdrawal_transactions",
      "attributes": {
        "absorbFees": true,
        "createdAt": null,
        "updatedAt": null,
        "state": "unconfirmed",
        "iban": "LT563400023810000822",
        "beneficiaryName": "Acme",
        "reference": "Fiat payout from Txn to Acme",
        "paymentStatus": "created",
        "bankBic": "GXPTLT22XXX",
        "bankName": "BANK NAME",
        "currency": "EUR",
        "amount": "1.01",
        "payAmount": "1.00",
        "fee": "0.01"
      },
      "relationships": {
        "bankAccount": {
          "meta": {
            "included": false
          }
        },
        "account": {
          "meta": {
            "included": false
          }
        }
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}


# Creating bank withdrawal

<mark style="color:green;">`POST`</mark> `/api/public/v1/transactions/bank_withdrawals`

This endpoint creates a bank withdrawal.

**Headers**

<table><thead><tr><th width="320">Name</th><th>Value</th></tr></thead><tbody><tr><td>Content-Type</td><td><code>application/vnd.api+json</code></td></tr><tr><td>Authorization</td><td><code>Bearer &#x3C;api_key></code></td></tr></tbody></table>

**Request Body**

```json
{
  "data": {
    "type": "bankWithdrawalTransactions",
    "attributes": {
      "absorb_fees": true,
      "account_id": "acd50522-de49-4aaa-a183-dc046ff27fd5",
      "bank_account_id": "a754cd82-74a0-4c1c-a832-e83445bce2c5",
      "amount": 1,
      "reference": "Fiat payout from Txn to Acme"
    }
  }
}
```

<table><thead><tr><th>Name</th><th width="100">Type</th><th width="105">Required</th><th>Description</th></tr></thead><tbody><tr><td>data.type</td><td>string</td><td>Yes</td><td>Can only be <code>bankWithdrawalTransactions</code>.</td></tr><tr><td>data.attributes.reference</td><td>string</td><td>Yes</td><td>The custom reference ID to tie the request to end-user or their account who gets paid. This can be anything you choose.</td></tr><tr><td>data.attributes.amount</td><td>number</td><td>Yes</td><td>Withdrawal amount.</td></tr><tr><td>data.attributes.account_id</td><td>string</td><td>Yes</td><td>Account ID on the Txn platform, e.g. your Euro account, which Txn will debit funds from.</td></tr><tr><td>data.attributes.bank_account_id</td><td>string</td><td>Yes</td><td>Beneficiary (bank account) ID. Refer to <a href="/pages/8yHTHPLZ0E9fbn4BIpy3">Listing Beneficiaries</a>.</td></tr><tr><td>absorbFees</td><td>boolean</td><td>No</td><td>If false or omitted, the service fee is deducted from the transaction amount. If true, the service fee is deducted from your account balance.</td></tr></tbody></table>

**Response Body**

{% tabs %}
{% tab title="HTTP 201" %}

```json
{
  "data": {
    "id": "8ba506eb-0a5e-4518-9f64-9fcb399691aa",
    "type": "transactions",
    "attributes": {
      "createdAt": "2024-12-11T16:23:37.732Z",
      "simplifiedState": "completed",
      "transactionType": "BankWithdrawalTransaction",
      "amount": "-1.01",
      "reference": null
    },
    "relationships": {
      "account": {
        "meta": {
          "included": false
        }
      },
      "transactionDetails": {
        "data": {
          "type": "bank_withdrawal_transactions",
          "id": "8ba506eb-0a5e-4518-9f64-9fcb399691aa"
        }
      }
    }
  },
  "included": [
    {
      "id": "8ba506eb-0a5e-4518-9f64-9fcb399691aa",
      "type": "bank_withdrawal_transactions",
      "attributes": {
        "absorbFees": true,
        "createdAt": "2024-12-11T16:23:37.690Z",
        "updatedAt": "2024-12-11T16:23:37.690Z",
        "state": "completed",
        "iban": "LT563400023810000822",
        "beneficiaryName": "Acme",
        "reference": "Fiat payout from Txn to Acme",
        "paymentStatus": "created",
        "bankBic": "GXPTLT22XXX",
        "bankName": "BANK NAME",
        "currency": "EUR",
        "amount": "1.01",
        "payAmount": "1.00",
        "fee": "0.01"
      },
      "relationships": {
        "bankAccount": {
          "meta": {
            "included": false
          }
        },
        "account": {
          "meta": {
            "included": false
          }
        }
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}


# Listing bank withdrawals

<mark style="color:green;">`GET`</mark> `/api/public/v1/transactions/bank_withdrawals`

This endpoint returns a list of all bank withdrawal transactions.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**URL Parameters**

<table><thead><tr><th width="166.71502685546875">Name</th><th width="130.13836669921875">Type</th><th>Description</th></tr></thead><tbody><tr><td>order</td><td>string</td><td>Order in which the list of transactions should be returned. Can be <code>created_at</code>.</td></tr><tr><td>order_type</td><td>string</td><td>Order type. Can be either <code>asc</code> or <code>desc</code>.</td></tr><tr><td>page</td><td>number</td><td>Page for which you want to return transactions.</td></tr><tr><td>per_page</td><td>number</td><td>Number of transactions per page to return.</td></tr><tr><td>created_at_from</td><td>string</td><td>Date and time filter. Supports timestamps in ISO 8601 format, e.g. <code>2024-06-18T15:49:02.031Z</code>.</td></tr><tr><td>created_at_to</td><td>string</td><td>Date and time filter. Supports timestamps in ISO 8601 format, e.g. <code>2024-06-18T15:49:02.031Z</code>.</td></tr></tbody></table>

**Response Body**

<table><thead><tr><th>Name</th><th width="97">Type</th><th>Description</th></tr></thead><tbody><tr><td>data[].id</td><td>string</td><td>Transaction ID.</td></tr><tr><td>data[].type</td><td>string</td><td>Entity type returned. Always <code>transactions</code>.</td></tr><tr><td>data[].attributes</td><td>object</td><td>Set of transaction attributes.</td></tr><tr><td>data[].attributes.createdAt</td><td>string</td><td>Timestamp when the withdrawal was created. Refer to the <a href="/pages/H7xWDJMZukOei8CS8tUW">Date and time format</a> page.</td></tr><tr><td>data[].attributes.simplifiedState</td><td>string</td><td>Transaction status.</td></tr><tr><td>data[].attributes.transactionType</td><td>string</td><td>Transaction type. Always <code>BankWithdrawalTransaction</code>.</td></tr><tr><td>data[].attributes.amount</td><td>string</td><td>Amount debited from the account. Negative for withdrawals.</td></tr><tr><td>data[].attributes.currency</td><td>string</td><td>Currency code of the transaction.</td></tr><tr><td>data[].attributes.balance</td><td>string</td><td>Account balance immediately after Txn processed this transaction. <code>null</code> when not applicable.</td></tr><tr><td>data[].attributes.reference</td><td>string</td><td>Bank withdrawal reference.</td></tr><tr><td>data[].attributes.accountId</td><td>string</td><td>ID of the account the withdrawal was debited from.</td></tr><tr><td>data[].relationships.account.id</td><td>string</td><td>ID of the account the withdrawal belongs to.</td></tr><tr><td>included[].type(accounts).attributes</td><td>object</td><td>The account the withdrawal was debited from.</td></tr><tr><td>included[].type(bankAccounts).attributes</td><td>object</td><td>The destination bank account, including <code>beneficiaryName</code>, <code>iban</code>, <code>bankName</code>, and <code>bankBic</code>.</td></tr><tr><td>included[].type(bankWithdrawalTransactions).attributes</td><td>object</td><td>Withdrawal details, including <code>fee</code>, <code>payAmount</code>, <code>absorbFees</code>, <code>paymentStatus</code>, <code>approvalStatus</code>, and <code>state</code>.</td></tr><tr><td>meta.page</td><td>number</td><td>Current page number.</td></tr><tr><td>meta.per_page</td><td>number</td><td>Page size used for the response.</td></tr><tr><td>meta.total</td><td>number</td><td>Total number of withdrawals matching the query.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": [
    {
      "id": "8ba506eb-0a5e-4518-9f64-9fcb399691aa",
      "type": "transactions",
      "attributes": {
        "createdAt": "2024-12-11T16:23:37.732Z",
        "simplifiedState": "completed",
        "transactionType": "BankWithdrawalTransaction",
        "amount": "-1.01",
        "reference": null
      },
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "transactionDetails": {
          "data": {
            "type": "bank_withdrawal_transactions",
            "id": "8ba506eb-0a5e-4518-9f64-9fcb399691aa"
          }
        }
      }
    }
  ],
  "included": [
    {
      "id": "8ba506eb-0a5e-4518-9f64-9fcb399691aa",
      "type": "bank_withdrawal_transactions",
      "attributes": {
        "absorbFees": true,
        "createdAt": "2024-12-11T16:23:37.690Z",
        "updatedAt": "2024-12-11T16:23:37.690Z",
        "state": "completed",
        "iban": "LT563400023810000822",
        "beneficiaryName": "Acme",
        "reference": "Fiat payout from Txn to Acme",
        "paymentStatus": "created",
        "bankBic": "GXPTLT22XXX",
        "bankName": "BANK NAME",
        "currency": "EUR",
        "amount": "1.01",
        "payAmount": "1.00",
        "fee": "0.01"
      },
      "relationships": {
        "bankAccount": {
          "data": {
            "type": "bank_accounts",
            "id": "a754cd82-74a0-4c1c-a832-e83445bce2c5"
          }
        },
        "account": {
          "data": {
            "type": "accounts",
            "id": "acd50522-de49-4aaa-a183-dc046ff27fd5"
          }
        }
      }
    },
    {
      "id": "a754cd82-74a0-4c1c-a832-e83445bce2c5",
      "type": "bank_accounts",
      "attributes": {
        "beneficiaryName": "Acme",
        "currencyCode": "EUR",
        "iban": "LT563400023810000822",
        "createdAt": "2024-12-07T11:42:27.571Z",
        "updatedAt": "2024-12-07T11:42:27.571Z",
        "bankBic": "GUPULT22XXX",
        "bankName": "GURU PAY"
      }
    },
    {
      "id": "acd50522-de49-4aaa-a183-dc046ff27fd5",
      "type": "accounts",
      "attributes": {
        "currencyCode": "EUR",
        "balance": "25609.70",
        "currencyType": "fiat"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        }
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 1,
    "total": 34
  },
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}


# Reading bank withdrawal

<mark style="color:green;">`GET`</mark> `/api/public/v1/transactions/bank_withdrawals/:id`

This endpoint returns details of a particular bank withdrawal by its ID.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**Path Parameters**

| Name | Value               |
| ---- | ------------------- |
| id   | Bank withdrawal ID. |

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": {
    "id": "8ba506eb-0a5e-4518-9f64-9fcb399691aa",
    "type": "transactions",
    "attributes": {
      "createdAt": "2024-12-11T16:23:37.732Z",
      "simplifiedState": "completed",
      "transactionType": "BankWithdrawalTransaction",
      "amount": "-1.01",
      "reference": null
    },
    "relationships": {
      "account": {
        "meta": {
          "included": false
        }
      },
      "transactionDetails": {
        "data": {
          "type": "bank_withdrawal_transactions",
          "id": "8ba506eb-0a5e-4518-9f64-9fcb399691aa"
        }
      }
    }
  },
  "included": [
    {
      "id": "8ba506eb-0a5e-4518-9f64-9fcb399691aa",
      "type": "bank_withdrawal_transactions",
      "attributes": {
        "absorbFees": true,
        "createdAt": "2024-12-11T16:23:37.690Z",
        "updatedAt": "2024-12-11T16:23:37.690Z",
        "state": "completed",
        "iban": "LT563400023810000822",
        "beneficiaryName": "Acme",
        "reference": "Fiat payout from Txn to Acme",
        "paymentStatus": "created",
        "bankBic": "GXPTLT22XXX",
        "bankName": "BANK NAME",
        "currency": "EUR",
        "amount": "1.01",
        "payAmount": "1.00",
        "fee": "0.01"
      },
      "relationships": {
        "bankAccount": {
          "data": {
            "type": "bank_accounts",
            "id": "a754cd82-74a0-4c1c-a832-e83445bce2c5"
          }
        },
        "account": {
          "data": {
            "type": "accounts",
            "id": "acd50522-de49-4aaa-a183-dc046ff27fd5"
          }
        }
      }
    },
    {
      "id": "a754cd82-74a0-4c1c-a832-e83445bce2c5",
      "type": "bank_accounts",
      "attributes": {
        "beneficiaryName": "Acme",
        "currencyCode": "EUR",
        "iban": "LT563400023810000822",
        "createdAt": "2024-12-07T11:42:27.571Z",
        "updatedAt": "2024-12-07T11:42:27.571Z",
        "bankBic": "GXPTLT22XXX",
        "bankName": "BANK NAME"
      }
    },
    {
      "id": "acd50522-de49-4aaa-a183-dc046ff27fd5",
      "type": "accounts",
      "attributes": {
        "currencyCode": "EUR",
        "balance": "25609.70",
        "currencyType": "fiat"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        }
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}


# Listing bank deposits

<mark style="color:green;">`GET`</mark> `/api/public/v1/transactions/bank_deposits`

This endpoint returns a list of all bank deposit transactions.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**URL Parameters**

<table><thead><tr><th width="161.23699951171875">Name</th><th width="142.8192138671875">Type</th><th>Description</th></tr></thead><tbody><tr><td>order</td><td>string</td><td>Order in which the list of transactions should be returned. Can be <code>created_at</code>.</td></tr><tr><td>order_type</td><td>string</td><td>Order type. Can be either <code>asc</code> or <code>desc</code>.</td></tr><tr><td>page</td><td>number</td><td>Page for which you want to return transactions.</td></tr><tr><td>per_page</td><td>number</td><td>Number of transactions per page to return.</td></tr><tr><td>created_at_from</td><td>string</td><td>Date and time filter. Supports timestamps in ISO 8601 format, e.g. <code>2024-06-18T15:49:02.031Z</code>.</td></tr><tr><td>created_at_to</td><td>string</td><td>Date and time filter. Supports timestamps in ISO 8601 format, e.g. <code>2024-06-18T15:49:02.031Z</code>.</td></tr></tbody></table>

**Response Body**

<table><thead><tr><th>Name</th><th width="97">Type</th><th>Description</th></tr></thead><tbody><tr><td>data[].id</td><td>string</td><td>Transaction ID.</td></tr><tr><td>data[].type</td><td>string</td><td>Entity type returned. Always <code>transactions</code>.</td></tr><tr><td>data[].attributes</td><td>object</td><td>Set of transaction attributes.</td></tr><tr><td>data[].attributes.createdAt</td><td>string</td><td>Timestamp when the deposit was created. Refer to the <a href="/pages/H7xWDJMZukOei8CS8tUW">Date and time format</a> page.</td></tr><tr><td>data[].attributes.simplifiedState</td><td>string</td><td>Transaction status.</td></tr><tr><td>data[].attributes.transactionType</td><td>string</td><td>Transaction type. Always <code>BankDepositTransaction</code>.</td></tr><tr><td>data[].attributes.amount</td><td>string</td><td>Amount credited to the account.</td></tr><tr><td>data[].attributes.currency</td><td>string</td><td>Currency code of the transaction.</td></tr><tr><td>data[].attributes.balance</td><td>string</td><td>Account balance immediately after Txn processed this transaction. <code>null</code> when not applicable.</td></tr><tr><td>data[].attributes.reference</td><td>string</td><td>Bank deposit reference.</td></tr><tr><td>data[].attributes.accountId</td><td>string</td><td>ID of the account the deposit was credited to.</td></tr><tr><td>data[].relationships.account.id</td><td>string</td><td>ID of the account the deposit belongs to.</td></tr><tr><td>included[].type(accounts).attributes</td><td>object</td><td>The account the deposit was credited to.</td></tr><tr><td>included[].type(bankDepositTransactions).attributes</td><td>object</td><td>Bank deposit details, including <code>state</code>, payer information (<code>payerName</code>, <code>payerIban</code>, <code>payerBic</code>, <code>payerAddress</code>), <code>amount</code>, and <code>currency</code>.</td></tr><tr><td>meta.page</td><td>number</td><td>Current page number.</td></tr><tr><td>meta.per_page</td><td>number</td><td>Page size used for the response.</td></tr><tr><td>meta.total</td><td>number</td><td>Total number of deposits matching the query.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": [
    {
      "id": "9a53eecf-2cad-4e01-99e2-135d68a47c0b",
      "type": "transactions",
      "attributes": {
        "createdAt": "2024-12-10T12:14:04.295Z",
        "simplifiedState": "completed",
        "transactionType": "BankDepositTransaction",
        "amount": "1.40",
        "reference": "dbc43033-7692-4e6e-bdcb-3e4d7aafd5f4"
      },
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "transactionDetails": {
          "data": {
            "type": "bank_deposit_transactions",
            "id": "9a53eecf-2cad-4e01-99e2-135d68a47c0b"
          }
        }
      }
    }
  ],
  "included": [
    {
      "id": "9a53eecf-2cad-4e01-99e2-135d68a47c0b",
      "type": "bank_deposit_transactions",
      "attributes": {
        "createdAt": "2024-12-10T12:12:49.639Z",
        "updatedAt": "2024-12-10T12:12:49.639Z",
        "state": "completed",
        "currency": "EUR",
        "amount": "1.40"
      },
      "relationships": {
        "account": {
          "data": {
            "type": "accounts",
            "id": "acd50522-de49-4aaa-a183-dc046ff27fd5"
          }
        }
      }
    },
    {
      "id": "acd50522-de49-4aaa-a183-dc046ff27fd5",
      "type": "accounts",
      "attributes": {
        "currencyCode": "EUR",
        "balance": "25609.70",
        "currencyType": "fiat"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        }
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 1,
    "total": 6
  },
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}


# Reading bank deposit

<mark style="color:green;">`GET`</mark> `/api/public/v1/transactions/bank_deposits/:id`

This endpoint returns details of a particular bank deposit by its ID.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**Path Parameters**

| Name | Value            |
| ---- | ---------------- |
| id   | Bank deposit ID. |

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": {
    "id": "9a53eecf-2cad-4e01-99e2-135d68a47c0b",
    "type": "transactions",
    "attributes": {
      "createdAt": "2024-12-10T12:14:04.295Z",
      "simplifiedState": "completed",
      "transactionType": "BankDepositTransaction",
      "amount": "1.40",
      "reference": "dbc43033-7692-4e6e-bdcb-3e4d7aafd5f4"
    },
    "relationships": {
      "account": {
        "meta": {
          "included": false
        }
      },
      "transactionDetails": {
        "data": {
          "type": "bank_deposit_transactions",
          "id": "9a53eecf-2cad-4e01-99e2-135d68a47c0b"
        }
      }
    }
  },
  "included": [
    {
      "id": "9a53eecf-2cad-4e01-99e2-135d68a47c0b",
      "type": "bank_deposit_transactions",
      "attributes": {
        "createdAt": "2024-12-10T12:12:49.639Z",
        "updatedAt": "2024-12-10T12:12:49.639Z",
        "state": "completed",
        "currency": "EUR",
        "amount": "1.40"
      },
      "relationships": {
        "account": {
          "data": {
            "type": "accounts",
            "id": "acd50522-de49-4aaa-a183-dc046ff27fd5"
          }
        }
      }
    },
    {
      "id": "acd50522-de49-4aaa-a183-dc046ff27fd5",
      "type": "accounts",
      "attributes": {
        "currencyCode": "EUR",
        "balance": "25609.70",
        "currencyType": "fiat"
      },
      "relationships": {
        "company": {
          "meta": {
            "included": false
          }
        },
        "networks": {
          "meta": {
            "included": false
          }
        }
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}
{% endtabs %}