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

# Creating payment link payment

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

Creates the child invoice of an invoice payment link with a cryptocurrency and network you choose, instead of letting the end user choose on the hosted page. Use it when your own checkout collects that choice. The invoice takes the link's amount, currency, reference, payment methods and redirect URLs, and the response returns it together with its deposit address.

After the call the payment link is `pending` and the invoice follows the [invoice status flow](https://docs.txn.io/invoices/invoice-status-flow.md). The invoice expires after your account's payment-link invoice period (20 minutes by default), independently of the link's own `expiresAt`. A link accepts one payment: once its invoice exists, further calls return `422`.

{% hint style="warning" %}
Payout payment links cannot be completed through this endpoint. The payout it creates is a draft that expires after 30 seconds, and the public API has no call to confirm it. Send end users of payout payment links to the link's `hostedPageUrl`.
{% endhint %}

**Headers**

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

**Path Parameters**

| Name | Value                                                              |
| ---- | ------------------------------------------------------------------ |
| id   | Payment link ID. The link must have status `created` or `pending`. |

**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>Always <code>payment_links</code>.</td></tr><tr><td>data.attributes.chargedCurrency</td><td>string</td><td>Yes</td><td>Cryptocurrency the customer pays with. Must be one of the link's <code>payCurrencies</code>.</td></tr><tr><td>data.attributes.network</td><td>string</td><td>Yes</td><td>Network code for <code>chargedCurrency</code>. See <a href="https://docs.txn.io/invoices/listing-invoice-currencies-and-networks.md">Listing invoice currencies and networks</a>.</td></tr></tbody></table>

**cURL**

```bash
curl -X "POST" "https://api.sandbox.txn.io/api/public/v1/payment_links/3b1896d1-326b-4a39-9dd5-36aeb9ef3058/payment" \
     -H 'Content-Type: application/vnd.api+json' \
     -H 'Authorization: Bearer <api_key>' \
     -d $'{
  "data": {
    "type": "payment_links",
    "attributes": {
      "chargedCurrency": "USDT",
      "network": "ttrx:usdt"
    }
  }
}'
```

**Response Body**

<table><thead><tr><th>Name</th><th width="97">Type</th><th>Description</th></tr></thead><tbody><tr><td>data</td><td>object</td><td>The payment link, with the same attributes as <a href="https://docs.txn.io/payment-links/reading-payment-link.md">Reading payment link</a>. <code>status</code> is <code>pending</code>, <code>network</code> and <code>networkName</code> are set, and <code>relationships.target.data</code> points at the invoice.</td></tr><tr><td>data.relationships.target</td><td>object</td><td>The child invoice. <code>data.type</code> is <code>invoices</code>; the entity is returned in <code>included[]</code>.</td></tr><tr><td>included[].type(invoices)</td><td>object</td><td>The child invoice (<code>data.relationships.target</code>), with the same attributes as <a href="https://docs.txn.io/invoices/reading-invoice.md">Reading invoice</a>. Its <code>hostedPageUrl</code> is the invoice payment page.</td></tr><tr><td>included[].type(invoices).relationships</td><td>object</td><td><code>address</code>, <code>invoiceTransactions</code> and <code>coinDeposits</code> are expanded; their entities are returned in <code>included[]</code> and described below (<code>coinDeposits</code> is empty, no payment has been received yet). <code>targetAccount</code>, <code>binanceOrder</code> and <code>refundLinks</code> are not expanded (<code>meta.included</code> is <code>false</code>); <a href="https://docs.txn.io/invoices/reading-invoice.md">read the invoice</a> to get them.</td></tr><tr><td>included[].type(addresses)</td><td>object</td><td>The receiving address of the invoice (<code>included[].type(invoices).relationships.address</code>).</td></tr><tr><td>included[].type(addresses).attributes.value</td><td>string</td><td>The address the end user must send the payment to. For XRP the destination tag is appended as <code>?dt=&#x3C;tag></code>; display both parts, see the <a href="https://docs.txn.io/invoices/invoice-integration-guide.md">invoice integration guide</a>.</td></tr><tr><td>included[].type(addresses).attributes.label</td><td>string</td><td>Address label. For invoice addresses this is the network name, e.g. <code>Tron (TRC20)</code>.</td></tr><tr><td>included[].type(addresses).attributes.createdAt</td><td>string</td><td>When the address was created. Invoice addresses are allocated from a pool, so this can predate the invoice.</td></tr><tr><td>included[].type(addresses).relationships</td><td>object</td><td><code>account</code> and <code>network</code>: not expanded (<code>meta.included</code> is <code>false</code>); use <code>data.attributes.network</code> and <code>data.attributes.networkName</code>.</td></tr><tr><td>included[].type(invoiceTransactions)</td><td>object</td><td>The settlement record of the invoice: the amounts to settle and the fees charged. Created with the invoice and updated when the payment is applied. Its <code>id</code> equals the <code>id</code> of the related <code>transactions</code> entity.</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(invoiceTransactions).attributes.billedChargedRate</td><td>string</td><td>Rate used to convert <code>billedCurrency</code> into <code>chargedCurrency</code>, including your spread. Same value as <code>included[].type(invoices).attributes.exchangeRate</code>.</td></tr><tr><td>included[].type(invoiceTransactions).attributes.billedChargedRateCurrency</td><td>string</td><td>Currency the rate is quoted in. Equals <code>billedCurrency</code>.</td></tr><tr><td>included[].type(invoiceTransactions).attributes.transactionFee</td><td>string</td><td>Txn processing fee in <code>transactionFeeCurrency</code>: <code>amountBilled</code> multiplied by your invoice fee percentage, subject to the minimum fee configured for your account.</td></tr><tr><td>included[].type(invoiceTransactions).attributes.transactionFeeCurrency</td><td>string</td><td>Equals <code>billedCurrency</code>.</td></tr><tr><td>included[].type(invoiceTransactions).attributes.consolidationFee</td><td>string</td><td>Network fee for consolidating the received funds from the invoice address, quoted in <code>billedCurrency</code>. <code>0.00</code> when your account is not charged consolidation fees.</td></tr><tr><td>included[].type(invoiceTransactions).attributes.targetTransactionFee</td><td>string</td><td><code>transactionFee</code> converted into <code>targetCurrency</code>. This is the amount deducted from what is credited to the target account.</td></tr><tr><td>included[].type(invoiceTransactions).attributes.targetTransactionFeeCurrency</td><td>string</td><td>Equals <code>targetCurrency</code>.</td></tr><tr><td>included[].type(invoiceTransactions).attributes.simplifiedState</td><td>string</td><td>Status of the settlement on the target account: <code>pending</code> until a payment is applied (it stays <code>pending</code> for invoices that expire or are cancelled unpaid), <code>on_hold</code> while a received payment is under review, <code>completed</code> once credited, <code>cancelled</code> when a received payment was rejected. Same value as the related <code>transactions</code> entity. See <a href="https://docs.txn.io/transactions/listing-transactions.md#transaction-statuses">Transaction statuses</a>.</td></tr><tr><td>included[].type(invoiceTransactions).relationships.txn</td><td>object</td><td>The account transaction crediting the target account. <code>data.type</code> is <code>transactions</code>; the entity is returned in <code>included[]</code>.</td></tr><tr><td>included[].type(invoiceTransactions).relationships.exchangeQuote</td><td>object</td><td>The conversion of the received crypto into <code>targetCurrency</code>; <code>data.type</code> is <code>exchangeQuotes</code>. <code>data</code> is <code>null</code> here: the quote is created when the invoice completes, and only when <code>chargedCurrency</code> differs from <code>targetCurrency</code>.</td></tr><tr><td>included[].type(invoiceTransactions).relationships</td><td>object</td><td><code>account</code>, <code>invoice</code> and <code>author</code>: not expanded (<code>meta.included</code> is <code>false</code>).</td></tr><tr><td>included[].type(transactions)</td><td>object</td><td>The balance movement on the target account for this invoice, in the shape returned by <a href="https://docs.txn.io/transactions/listing-transactions.md">Listing transactions</a>. Its <code>id</code> equals the <code>invoiceTransactions</code> id.</td></tr><tr><td>included[].type(transactions).attributes.amount</td><td>string</td><td>Amount credited to the target account in <code>currency</code>, net of fees. Equals <code>included[].type(invoices).attributes.targetAmount</code> until a payment is applied and is then set to the settled amount, so it differs from <code>targetAmount</code> on underpayment and overpayment.</td></tr><tr><td>included[].type(transactions).attributes.currency</td><td>string</td><td>Equals <code>included[].type(invoices).attributes.targetCurrency</code>.</td></tr><tr><td>included[].type(transactions).attributes.simplifiedState</td><td>string</td><td>Same value as <code>included[].type(invoiceTransactions).attributes.simplifiedState</code>.</td></tr><tr><td>included[].type(transactions).attributes.transactionType</td><td>string</td><td>Always <code>InvoiceTransaction</code>.</td></tr><tr><td>included[].type(transactions).attributes.balance</td><td>string</td><td>Always <code>null</code> here. The running balance is only computed by the transaction listings.</td></tr><tr><td>included[].type(transactions).attributes.reference</td><td>string</td><td>The invoice <code>reference</code>.</td></tr><tr><td>included[].type(transactions).attributes.accountId</td><td>string</td><td>ID of the target account.</td></tr><tr><td>included[].type(transactions).attributes.createdAt</td><td>string</td><td>When the invoice was created.</td></tr><tr><td>included[].type(transactions).relationships</td><td>object</td><td><code>account</code>, <code>transactionDetails</code> and <code>author</code>: not expanded (<code>meta.included</code> is <code>false</code>).</td></tr></tbody></table>

**Response**

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

```json
{
  "data": {
    "id": "3b1896d1-326b-4a39-9dd5-36aeb9ef3058",
    "type": "paymentLinks",
    "attributes": {
      "amount": "25.00",
      "currency": "EUR",
      "accountCurrency": "EUR",
      "network": "ttrx:usdt",
      "networkName": "Tron (TRC20)",
      "reference": "docs-pl-payment-1793374122",
      "hostedPageUrl": "https://sandbox.txn.io/redirect?payment_link_id=3b1896d1-326b-4a39-9dd5-36aeb9ef3058&request_type=payment_link_hosted_page",
      "status": "pending",
      "approvalStatus": null,
      "expiresAt": "2026-10-31T15:28:42.000Z",
      "createdAt": "2026-10-30T15:28:43.241Z",
      "paymentType": "Invoice",
      "successRedirectUrl": null,
      "unsuccessRedirectUrl": null,
      "paymentMethods": [
        "on_chain"
      ]
    },
    "relationships": {
      "target": {
        "data": {
          "type": "invoices",
          "id": "6e3838c9-40e1-4c4a-bd6c-8befce4ce5fc"
        }
      }
    }
  },
  "included": [
    {
      "id": "6e3838c9-40e1-4c4a-bd6c-8befce4ce5fc",
      "type": "invoices",
      "attributes": {
        "amountBilled": "25.00",
        "amountCharged": "29.511601",
        "targetAmount": "23.50",
        "billedCurrency": "EUR",
        "chargedCurrency": "USDT",
        "targetCurrency": "EUR",
        "chargedTargetRate": "0.8471245",
        "chargedTargetRateCurrency": "EUR",
        "statusContext": "unpaid",
        "network": "ttrx:usdt",
        "networkName": "Tron (TRC20)",
        "paymentMethods": [
          "on_chain"
        ],
        "status": "pending",
        "successRedirectUrl": null,
        "unsuccessRedirectUrl": null,
        "paymentStatus": "expecting",
        "exchangeRate": "0.8471245",
        "reference": "docs-pl-payment-1793374122",
        "expiresAt": "2026-10-30T15:48:44.284Z",
        "createdAt": "2026-10-30T15:28:44.335Z",
        "hostedPageUrl": "https://sandbox.txn.io/redirect?item_id=6e3838c9-40e1-4c4a-bd6c-8befce4ce5fc&request_type=item_hosted_page",
        "scAddress": null
      },
      "relationships": {
        "targetAccount": {
          "meta": {
            "included": false
          }
        },
        "binanceOrder": {
          "meta": {
            "included": false
          }
        },
        "address": {
          "data": {
            "type": "addresses",
            "id": "5b8d9f82-ee15-4510-b8d2-57348bca807b"
          }
        },
        "refundLinks": {
          "meta": {
            "included": false
          }
        },
        "invoiceTransactions": {
          "data": [
            {
              "type": "invoiceTransactions",
              "id": "601e3c47-2060-4c03-bbb1-d286d942938b"
            }
          ]
        },
        "coinDeposits": {
          "data": []
        }
      }
    },
    {
      "id": "5b8d9f82-ee15-4510-b8d2-57348bca807b",
      "type": "addresses",
      "attributes": {
        "label": "Tron (TRC20)",
        "value": "TJb7un5JTwYdVD54DeZwGyvz1JRwDHLjfB",
        "createdAt": "2026-10-29T10:37:05.788Z"
      },
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "network": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "601e3c47-2060-4c03-bbb1-d286d942938b",
      "type": "invoiceTransactions",
      "attributes": {
        "amountBilled": "25.00",
        "billedChargedRate": "0.8471245",
        "billedChargedRateCurrency": "EUR",
        "consolidationFee": "0.00",
        "transactionFee": "1.50",
        "transactionFeeCurrency": "EUR",
        "targetTransactionFee": "1.50",
        "targetTransactionFeeCurrency": "EUR",
        "simplifiedState": "pending"
      },
      "relationships": {
        "txn": {
          "data": {
            "type": "transactions",
            "id": "601e3c47-2060-4c03-bbb1-d286d942938b"
          }
        },
        "exchangeQuote": {
          "data": null
        },
        "account": {
          "meta": {
            "included": false
          }
        },
        "invoice": {
          "meta": {
            "included": false
          }
        },
        "author": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "601e3c47-2060-4c03-bbb1-d286d942938b",
      "type": "transactions",
      "attributes": {
        "createdAt": "2026-10-30T15:28:44.351Z",
        "simplifiedState": "pending",
        "transactionType": "InvoiceTransaction",
        "amount": "23.50",
        "currency": "EUR",
        "balance": null,
        "reference": "docs-pl-payment-1793374122",
        "accountId": "13a85b45-8543-41c7-b963-394d4ea128ae"
      },
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "transactionDetails": {
          "meta": {
            "included": false
          }
        },
        "author": {
          "meta": {
            "included": false
          }
        }
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "Disallowed charged currency",
      "code": "disallowed_charged_currency",
      "detail": "This currency is not accepted by the payment link"
    }
  ]
}
```

{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "Network and currency mismatch",
      "code": "network_currency_mismatch",
      "detail": "Currency BTC does not belong to network ttrx:usdt"
    }
  ]
}
```

{% endtab %}

{% tab title="HTTP 422" %}

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

{% endtab %}

{% tab title="HTTP 404" %}

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

{% endtab %}
{% endtabs %}


---

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

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

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

```
GET https://docs.txn.io/payment-links/creating-payment-link-payment.md?ask=<question>&goal=<user_goal>
```

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

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

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