Create a payment link

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

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.
`callbackUrl`	yes	Absolute `https` URL that receives webhooks 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.

{
  "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.

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

Get started

Concepts

Integrate

Create a payment link

Request

Response

Send the payer to checkout

Match payments to your orders

Common errors

​Request

​Response

​Send the payer to checkout

​Match payments to your orders

​Common errors

Request

Response

Send the payer to checkout

Match payments to your orders

Common errors