Creating a Payment
Create a payment and share its receiving addresses.
addressesFULFILLEDdestinationAddressreferenceBefore you start
You need a payment-links project. Payments are created in your business's default payment-links project, set in the dashboard; without one, requests are refused with 409.
Create a payment
Send Create payment with an Idempotency-Key header. The key is required: a retry without it would create a second set of addresses the payer never sees.
| Field | Value |
|---|---|
reference | Your own reference, for example an invoice number. |
destinations | One entry per network family you accept: evm, bitcoin, spark, solana, tron, ton. |
Each destination takes:
| Field | Value |
|---|---|
asset | What the payer sends, for example USDT or BTC. |
amount | Exactly what must arrive, for example "10.5". |
destinationAddress | Where the funds go once they arrive. It cannot be changed later. |
One evm entry covers every EVM network.
Share the addresses
The response has one deposit address per family. Show them to the payer.
- The first exact payment on any network completes the payment.
- A short payment does not complete it.
- An overpayment completes it, and the excess is held for you.
- Payments that arrive on other networks after it completes are held for you.
See Approvals and Recovered Funds for held funds.
Expiry and cancelling
A payment expires after 30 minutes. Cancel payment stops one sooner, while it is still awaiting payment.
After a payment expires or is cancelled, its addresses stay watched for 24 hours, so funds sent late are held, not lost.
Statuses
| Status | Meaning |
|---|---|
AWAITING_PAYMENT | Waiting for the payer. |
FULFILLED | Paid. Funds are sent to your address, after approval when one is needed. |
EXPIRED | Not paid within 30 minutes. |
CANCELLED | Cancelled before it was paid. |
Tracking
- List payments and Get payment show each payment with its addresses, attempts and held funds.
payment.*events arrive at the webhook endpoints of the project the payment belongs to. See Notifications.
Errors
| Code | Status | Cause |
|---|---|---|
validation_failed | 400 | The Idempotency-Key header is missing. |
validation_failed | 409 | No default payment-links project is set and the key does not belong to one. |
validation_failed | 409 | The payment cannot be cancelled because it is no longer awaiting payment. |
not_found | 404 | No payment has this id. |