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


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.txn.io/invoices/creating-invoice.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

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