> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywire.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a payment link

> Charge an amount in USD, choose the coins you accept, and send the payer to checkout.

A payment link is a price plus the coins you accept. Create one per purchase (an order in your shop, an invoice), store its `id` against that purchase, and send the payer to the hosted checkout.

## Request

```bash theme={null}
curl -X POST https://api.staging.paywire.xyz/payments/links \
  -H "Authorization: Bearer $PAYWIRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49.90,
    "currency": "USD",
    "callbackUrl": "https://shop.example.com/webhooks/paywire",
    "returnUrl": "https://shop.example.com/orders/1042",
    "orderTtlMinutes": 20,
    "allowedAssets": [
      { "network": "ethereum_sepolia", "token": "0x1c7d4b196cb0c7b01d743fbc6116a902379c7238" },
      { "network": "tron_nile", "token": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf" },
      { "network": "solana_devnet", "token": "native" },
      { "network": "bitcoin_signet", "token": "native" }
    ]
  }'
```

| Field | Required | Description |
| - | - | - |
| `amount` | yes | The price, greater than zero, within the platform's minimum and maximum. |
| `currency` | no | Fiat currency of `amount`. Default `USD`. |
| `allowedAssets` | yes | At least one asset the payer may pay with: `network` + `token` (`native` or a contract). See [Networks and assets](https://docs.paywire.xyz/concepts/networks-and-assets.md). |
| `callbackUrl` | yes | Absolute `https` URL that receives [webhooks](https://docs.paywire.xyz/guides/webhooks.md) for this link's orders. |
| `returnUrl` | no | Absolute `https` URL the checkout offers the payer when they're done. |
| `orderTtlMinutes` | no | How long a quote holds, 5 to 1440 minutes. Default from the payment policy (30). |
| `policyOverride` | no | This link's own `tolerancePercent`, `overpayDustThreshold` and `overpayReviewThreshold`, instead of the company policy. |

## Response

`201 Created` with the link. Its `id` is what you keep.

```json theme={null}
{
  "id": "0193a0c4-5f2e-7c1d-9b8a-3e4f5a6b7c8d",
  "merchantId": "0193a0b1-2c3d-7e4f-8a9b-0c1d2e3f4a5b",
  "amount": 49.90,
  "currency": "USD",
  "allowedAssets": [
    { "network": "ethereum_sepolia", "token": "0x1c7d4b196cb0c7b01d743fbc6116a902379c7238", "decimals": 6 },
    { "network": "tron_nile", "token": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf", "decimals": 6 },
    { "network": "solana_devnet", "token": "native", "decimals": 9 },
    { "network": "bitcoin_signet", "token": "native", "decimals": 8 }
  ],
  "callbackUrl": "https://shop.example.com/webhooks/paywire",
  "orderTtlMinutes": 20,
  "policyOverride": null,
  "returnUrl": "https://shop.example.com/orders/1042",
  "isActive": true,
  "createdAt": "2026-10-24T09:12:31.204Z"
}
```

## Send the payer to checkout

```
https://pay.staging.paywire.xyz/pay/{id}
```

Redirect to it, link to it, or put it in an email or QR code. The page shows your gateway's name, the price and the coins; the payer picks one and gets an address, an exact amount and a countdown. They can give a refund address there too. Want the address in your own UI instead? See [Build your own checkout](https://docs.paywire.xyz/guides/custom-checkout.md).

## Match payments to your orders

Each webhook carries `paymentLinkId` and `orderId`. Store the link `id` with your purchase when you create it, then look the purchase up by `paymentLinkId` when a webhook arrives. One link can produce several orders (a payer who lets a quote expire and starts again gets a new one), so key your fulfilment on the first `order.settled` or `order.overpaid` per link.

## Common errors

| Status | `title` | Fix |
| - | - | - |
| `400` | `PaymentLink.NoAllowedAssets` | List at least one asset |
| `400` | `PaymentLink.AssetNotSupported` | Check the `network` id and `token`; the asset may be switched off |
| `400` | `PaymentLink.CallbackMustBeHttps` | Use an absolute `https` callback URL |
| `400` | `PaymentLink.OrderTtlOutOfRange` | Keep `orderTtlMinutes` between 5 and 1440 |
| `400` | `Policy.AmountBelowMinimum` / `Policy.AmountAboveMaximum` | The amount is outside the platform's limits |
| `409` | `Merchant.Disabled` | Your gateway is disabled; contact Paywire |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.