API quickstart
The send21 API has two building blocks. A payment request asks to get paid: the payer opens a link, picks a currency and pays from any wallet. A payment draft prepares a payment to someone else, which the sender signs in their own wallet. Base URL: https://send21.io/api/v1.
1. Create an API key
Sign in and open API keys. Pick only the scopes you need. Keys look like s21_... and are shown once. No key can move funds, because send21 never holds any.
| Scope | Allows |
|---|---|
drafts:read | Read drafts, payment requests, templates, status and rates |
drafts:write | Create, cancel and re-quote drafts and payment requests |
addressbook:read | Read saved addresses |
addressbook:write | Change saved addresses |
webhooks:manage | Register and delete webhook endpoints |
2. Ask to get paid: a payment request
Price it in any of 161 fiat currencies and list the currencies you accept, each with your own receiving address. The response contains payPath; share https://send21.io plus that path as a link or QR code. The rate locks when the payer picks a currency.
curl -X POST https://send21.io/api/v1/payment-requests \
-H "Authorization: Bearer s21_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042" \
-d '{
"fiatCurrency": "EUR",
"fiatAmount": 49.00,
"orderId": "ORDER-1042",
"memo": "Invoice 1042",
"options": [
{ "currency": "Eurc", "network": "Base", "address": "0xYourAddress" },
{ "currency": "Usdc", "network": "Solana", "address": "YourSolanaAddress" },
{ "currency": "Btc", "network": "Mainnet", "address": "you@your-wallet.com", "method": "Lightning" }
]
}'Help the person who pays
declineNote(optional, up to 200 characters): what happens if they do not pay. The pay page shows it under the amount as "If you don't pay:". Plain text only.changeSignalsandchangeNotes(read-only, on create and GET by id): what is unusual compared with your paid payments.new_address,new_assetandunusual_amount(more than 2x your usual amount in that currency). The pay page shows the same lines above the payment, and shows nothing when nothing is unusual.shortfallPolicy(optional):{ "absorbUpToPercent": 2, "absorbedBy": "receiver" }accepts payments that arrive up to 2% short, for example when an exchange takes its fee from the amount. Overpayments always wait for you.- When a pay link expires unpaid, the
payment_request.expiredwebhook says whether the payer opened it and whether they picked a currency. - One pay link per order: send
reuseOpenForOrder: trueand an open link for the sameorderIdis returned instead of a second one. A newIdempotency-Keyalone always creates a new link.GET /payment-requests?orderId=lists the links for an order.
3. Prepare a payment: a draft
A draft pays a receiver. Use paymentMethod: "MultiOutput" for any on-chain payment, or "Lightning". Add singleOutput: true for one QR payment from any wallet, with the send21 fee billed to your account. Without it, the fee is a separate output and the draft suits PSBT and batching wallets. Fetch wallet-ready instructions from GET /drafts/{id}/tx-template.
curl -X POST https://send21.io/api/v1/drafts \
-H "Authorization: Bearer s21_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: payout-77" \
-d '{
"receiverAddress": "0xReceiverAddress",
"network": "Arbitrum",
"currency": "Usdc",
"paymentMethod": "MultiOutput",
"singleOutput": true,
"fiatCurrency": "SEK",
"fiatAmount": 1500
}'4. Track the payment
- Poll
GET /drafts/{id}/statusforAwaitingPayment,Seen,Confirmed,ExpiredorCancelled. Once confirmed,confirmedAtsays when; it is set once and never changes. - Better: register a webhook and react to
draft.confirmed. - A transfer within 10% of the billed amount (over or under) is never confirmed on its own. The draft keeps its status (
AwaitingPayment);amountMismatch.reviewState(also onGET /drafts/{id}/status) sayspending, anddraft.amount_mismatchis sent once. - Decide with
POST /drafts/{id}/accept-received(acceptReason; the draft continues as paid,draft.mismatch_accepted) orPOST /drafts/{id}/reject-received(rejectReason, required;draft.mismatch_rejected). Both store who decided and why. - Still undecided 2 hours before the draft expires: one
draft.mismatch_reminder(and an email). At expiry the draft becomesExpiredwithreviewState: unresolved;draft.expiredcarries the received amount anddraft.mismatch_unresolvedis sent. You can still accept it afterwards. - The money is always already in the receiving wallet. send21 never holds funds, so a declined or unresolved payment is refunded by the receiver, outside send21.
- With
shortfallPolicy, short payments within your percent are accepted automatically (acceptReason: "auto: shortfallPolicy"). Overpayments always wait for a person.
Good to know
- Send an
Idempotency-Keyheader on create calls. A retry with the same key returns the original object. - Batch creation:
POST /drafts/batchtakes up to 25 drafts. - Rate limit: 300 requests per minute per key. A 429 means back off; prefer webhooks over tight polling.
- A 402 on a create call means accrued fees must be settled first; the body names
POST /fees/accrued/settle. - Calls signed in with the website's session cookie instead of a key (for example a script that creates API keys) must send the header
X-CSRF: 1on every POST, PUT and DELETE, or they get 403 "Missing X-CSRF header.". It is an anti-forgery check: other sites cannot set it. Requests with an API key do not need it. - Full reference: /swagger and /openapi.json.
Related
Start building
Create a free account to get an API key, or try the whole flow first on test networks.
This page is also available as Markdown: /docs/quickstart.md. Questions: integration@send21.io.