> 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/payment-links-concept.md).

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

If your own checkout collects the cryptocurrency choice, you can create the child invoice of an invoice payment link directly with [Creating payment link payment](https://docs.txn.io/payment-links/creating-payment-link-payment.md) instead of sending the end user to the hosted page.

## Invoice payment links

<figure><img src="https://1963856601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgfUDRstNYYBTf2futZ28%2Fuploads%2FRLIwpDpp2ASOCJ1rDHtX%2Finvoice%20payment%20link%20flow.svg?alt=media&amp;token=b6af6b99-2977-4170-bc0c-d787b0cd994b" alt=""><figcaption></figcaption></figure>

See [Invoices concept](https://docs.txn.io/invoices/invoices-concept.md) and [Invoice status flow](https://docs.txn.io/invoices/invoice-status-flow.md) for details on the child invoice lifecycle.

## Payout payment links

<figure><img src="https://1963856601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgfUDRstNYYBTf2futZ28%2Fuploads%2FMyGDWxTgPMgOMYL6j4y1%2Fpayout%20payment%20link%20flow.svg?alt=media&amp;token=e5b277c9-be4f-43a7-ae20-b9a3a69073fa" alt=""><figcaption></figcaption></figure>

See [Payouts concept](https://docs.txn.io/payouts/payouts-concept.md) and [Payout status flow](https://docs.txn.io/payouts/payout-status-flow.md) 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 network, and the child invoice or payout was created. The link stays `pending` until the child completes, including when a child invoice expires unpaid while the link is still valid. |
| completed | Yes    | The child invoice was paid, or the child payout completed.                                                                                                                                                                            |
| expired   | Yes    | The payment link expired before the end user completed the flow, or was manually expired via the [Expire Payment Link](https://docs.txn.io/payment-links/expiring-payment-link.md) 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](https://docs.txn.io/api-basics/webhooks.md) and [payout webhooks](https://docs.txn.io/payouts/payout-webhooks.md) to receive real-time status updates on the actual transactions.
{% endhint %}

For child invoice and payout statuses:

* [Invoice status flow](https://docs.txn.io/invoices/invoice-status-flow.md)
* [Payout status flow](https://docs.txn.io/payouts/payout-status-flow.md)

## Hosted page examples

### Invoice payment link

The end user first selects a cryptocurrency:

<figure><img src="https://1963856601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgfUDRstNYYBTf2futZ28%2Fuploads%2Fgit-blob-a6e69c5cad2d2c5947e87372bfc3f3c7ba88bdd3%2Fpayment-link-invoice-1.png?alt=media" alt="Invoice payment link — select cryptocurrency"><figcaption><p>Step 1: Select the cryptocurrency</p></figcaption></figure>

Then the end user selects the network and clicks **Continue to payment**:

<figure><img src="https://1963856601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgfUDRstNYYBTf2futZ28%2Fuploads%2Fgit-blob-a047f99a72554eab66f49df70b762a0d6d614464%2Fpayment-link-invoice-2.png?alt=media" alt="Invoice payment link — select network"><figcaption><p>Step 2: Select the network</p></figcaption></figure>

Txn creates an invoice and redirects the end user to the invoice payment page, which shows the exact amount to send, the address and network, and the time left before the invoice expires:

<figure><img src="https://1963856601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgfUDRstNYYBTf2futZ28%2Fuploads%2Fgit-blob-256326179a0ba6d791fc6ee9a31b78842fc86a85%2Fpayment-link-invoice-3.png?alt=media" alt="Invoice payment page"><figcaption><p>The invoice payment page</p></figcaption></figure>

### Payout payment link

The end user selects a cryptocurrency and network, and enters their wallet address:

<figure><img src="https://1963856601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgfUDRstNYYBTf2futZ28%2Fuploads%2Fgit-blob-b453decafe91fdbe611d73a82017963acd6819c3%2Fpayment-link-payout-1.png?alt=media" alt="Payout payment link — wallet address"><figcaption><p>Select the cryptocurrency and network, and enter the wallet address</p></figcaption></figure>

After clicking **Continue**, the end user reviews the payout details, including the fees and the amount they will receive:

<figure><img src="https://1963856601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgfUDRstNYYBTf2futZ28%2Fuploads%2Fgit-blob-670b955d93dfcfc95e880e55c7c814c6d6b10669%2Fpayment-link-payout-2.png?alt=media" alt="Payout payment link — review"><figcaption><p>Review the payout details</p></figcaption></figure>

After clicking **Confirm**, Txn initiates the cryptocurrency transfer to their wallet:

<figure><img src="https://1963856601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgfUDRstNYYBTf2futZ28%2Fuploads%2Fgit-blob-2e45be24b4774cdfe406c2507a5fbf898dafd07b%2Fpayment-link-payout-3.png?alt=media" alt="Payout payment link — processing"><figcaption><p>The payout is being processed</p></figcaption></figure>


---

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

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

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

```
GET https://docs.txn.io/payment-links/payment-links-concept.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.
