# Creating invoice

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

This endpoint creates invoices.

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

```json
curl -X "POST" "https://api.sandbox.txn.pro/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="../api-basics/supported-currencies">supported</a> currencies.</td></tr><tr><td>data.attributes.chargedCurrency</td><td>string</td><td>Yes</td><td>Crypto currency that customer must pay in. Refer to <a href="../api-basics/supported-currencies">supported</a> currencies.</td></tr><tr><td>data.attributes.network</td><td>string</td><td>Yes</td><td>Payment network. Refer to <a href="../api-basics/supported-currencies">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. Can be EUR, USD, USDT, or USDC.</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>This field is an array listing the supported payment methods for a particular invoice.</p><p></p><p>Can be ONE of these possible values:</p><p></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.</li></ul><p>If no value supplied, 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 cryptucurrency 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="../api-basics/supported-currencies">supported</a> currencies.</td></tr><tr><td>data.attributes.chargedCurrency</td><td>string</td><td>Crypto currency that customer must pay in. Refer to <a href="../api-basics/supported-currencies">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>Charged currency to target currency exchange rate.</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>Invoice status context. Refer to <a href="invoice-status-flow">Invoice status flow</a>.</td></tr><tr><td>data.attributes.network</td><td>string</td><td>Network code. Refer to <a href="../api-basics/supported-currencies">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>string</td><td>Invoice payment methods.</td></tr><tr><td>data.attributes.status</td><td>string</td><td>Invoice status. Refer to <a href="invoice-status-flow">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="invoice-status-flow">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>included.type(addresses).attributes</td><td>object</td><td>Invocie receiving address. This is the address the end-user must send their crytpocurrency 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></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.pro/redirect?invoice_id=ab0fbca0-a6b1-41af-95c7-b2ae4595f72d&request_type=invoice_hosted_page&zone=eu"
    },
    "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
          }
        }
      }
    }
  ],
  "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"
    }
  ]
}

// Amoun 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"
      }
    }
  ]
}

// Dplicate reference.
```

{% endtab %}

{% tab title="HTTP 422" %}

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

{% endtab %}
{% endtabs %}