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.

ScopeAllows
drafts:readRead drafts, payment requests, templates, status and rates
drafts:writeCreate, cancel and re-quote drafts and payment requests
addressbook:readRead saved addresses
addressbook:writeChange saved addresses
webhooks:manageRegister 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.
  • changeSignals and changeNotes (read-only, on create and GET by id): what is unusual compared with your paid payments. new_address, new_asset and unusual_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.expired webhook says whether the payer opened it and whether they picked a currency.
  • One pay link per order: send reuseOpenForOrder: true and an open link for the same orderId is returned instead of a second one. A new Idempotency-Key alone 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}/status for AwaitingPayment, Seen, Confirmed, Expired or Cancelled. Once confirmed, confirmedAt says 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 on GET /drafts/{id}/status) says pending, and draft.amount_mismatch is sent once.
  • Decide with POST /drafts/{id}/accept-received (acceptReason; the draft continues as paid, draft.mismatch_accepted) or POST /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 becomes Expired with reviewState: unresolved; draft.expired carries the received amount and draft.mismatch_unresolved is 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-Key header on create calls. A retry with the same key returns the original object.
  • Batch creation: POST /drafts/batch takes 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: 1 on 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.