Send a payout
Send a payout to an approved destination. It holds money from your balance: one key, one payout.
Sandbox: test money only. No request moves real money.
Sandbox. The payout operations are in the API's contract and built for the sandbox, where a payout is simulated and never a real transfer. Until Nasfam switches payouts on in an environment, every request there answers 503 payouts_unavailable and nothing is written or held. Live: not yet available.
Availability: Sandbox. Built for the sandbox, on synthetic money. Not live.
POST /payouts sends a payout. In one step the server checks your workspace's policy and limits, and holds the total charge from your available USD balance. It needs payouts:write and an Idempotency-Key.
From a quote
Name what the quote priced, and cite it. The payout is charged exactly the quote's charge.total_micros; with max_total_charge as well, a quote above it is refused with price_changed:
| Field | Description |
|---|---|
| Assetasset · string · required | The asset the recipient receives, one GET /v1/payout-networks lists. Its issuer's own token on the named network, never a bridged one. |
| Networknetwork · string · required | The network the transfer is made on, one GET /v1/payout-networks lists. An address approved on one network authorises nothing on another. |
| Amountamount · string · required | What the recipient receives, as a decimal string in the asset's units ("100.5"), never a number. More decimal places than the pair's decimals is 400 invalid_request: nothing is rounded. Zero is refused. |
| Addressaddress · string · required | The destination address, 32 to 80 printable characters: one of your workspace's approved destinations. |
| Memomemo · string | The text comment the transfer carries, where the destination needs one. Part of the destination's identity. |
| Client referenceclient_ | Your own reference, up to 64 letters, digits and ._:-, unique in your workspace for ever (409 duplicate_reference). |
| Metadatametadata · object | Up to 10 keys of your own, each a string of at most 200 characters, returned on the payout. Never personal data. |
| Quote IDquote_ | The quote. The payout is charged exactly its charge.total_micros, or refused. |
| Max total chargemax_ | The most it may charge your USD balance, in micro-dollars. Above it: 409 price_changed, and nothing is made or held. |
metadata is yours, returned on the payout. Never put a name, a phone number, an email or an account number in it.
# One key per purchase: make it once, keep it with the purchase, and send the same key on every retry.: "${IDEMPOTENCY_ KEY:?Set IDEMPOTENCY_ KEY once for this purchase ( a new UUID) and keep it for every retry}"curl -X POST "https:// sandbox-api. nasfampay. com/ v1/ payouts" \ -H "Authorization: Bearer $NASFAM_ SANDBOX_ KEY" \ -H "Content-Type: application/ json" \ -H "Idempotency-Key: $IDEMPOTENCY_ KEY" \ -d '{ "asset": "ASSET", "network": "network_ id", "address": "your-approved-destination-address", "amount": "10.00", "client_ reference": "inv-1042", "metadata": {"batch": "november"}, "quote_ id": "pyq_ 01JD0Q0TE0FY0VRQV0TE000000" }'Priced now
Without a quote, send max_total_charge. The payout is priced when it is made, and refused with price_changed if the total charge would be above your ceiling. Nothing is held then:
| Field | Description |
|---|---|
| Assetasset · string · required | The asset the recipient receives, one GET /v1/payout-networks lists. Its issuer's own token on the named network, never a bridged one. |
| Networknetwork · string · required | The network the transfer is made on, one GET /v1/payout-networks lists. An address approved on one network authorises nothing on another. |
| Amountamount · string · required | What the recipient receives, as a decimal string in the asset's units ("100.5"), never a number. More decimal places than the pair's decimals is 400 invalid_request: nothing is rounded. Zero is refused. |
| Addressaddress · string · required | The destination address, 32 to 80 printable characters: one of your workspace's approved destinations. |
| Memomemo · string | The text comment the transfer carries, where the destination needs one. Part of the destination's identity. |
| Client referenceclient_ | Your own reference, up to 64 letters, digits and ._:-, unique in your workspace for ever (409 duplicate_reference). |
| Metadatametadata · object | Up to 10 keys of your own, each a string of at most 200 characters, returned on the payout. Never personal data. |
| Max total chargemax_ | The most it may charge, in micro-dollars. Above it, nothing is held. |
What it returns
202 Accepted with the payout, queued or pending_approval: accepted and its charge held, nothing sent yet. delivered is false.
| Field | Description |
|---|---|
| IDid · string · required | The payout: pyt_ and 26 characters. |
| Objectobject · string · required | payout. |
| Statusstatus · string · required | Where it is: one of the statuses below. |
| Delivereddelivered · boolean · required | True only when status is completed. |
| Assetasset · string · required | The asset the recipient receives, one GET /v1/payout-networks lists. Its issuer's own token on the named network, never a bridged one. |
| Networknetwork · string · required | The network the transfer is made on, one GET /v1/payout-networks lists. An address approved on one network authorises nothing on another. |
| Amountamount · string · required | What the recipient receives. |
| Amount unitsamount_ | The same amount in the asset's smallest unit. |
| Decimalsdecimals · integer · required | The asset's decimal places. |
| Addressaddress · string · required | The normalised address. |
| Memomemo · string or null · required | The memo, or null. |
| Destination IDdestination_ | The approved destination it pays. |
| Client referenceclient_ | Your reference, or null. |
| Metadatametadata · object or null · required | Your metadata, or null. |
| Quote IDquote_ | The quote it was priced by. |
| Chargecharge · object · required | What your USD balance is charged. |
| Currencycharge. | USD. |
| Payout value microscharge. | What the recipient amount is worth at the quote's rate. |
| Platform fee microscharge. | Nasfam's fee for sending it. |
| Network fee microscharge. | The network's fee, Nasfam's own estimate for the network. A request never supplies one. |
| Conversion fee microscharge. | The spread on the rate. |
| Total microscharge. | What your USD balance is charged in all: the sum of the four. |
| Screeningscreening · object · required | The destination's screening for this payout. |
| Statusscreening. | One of the screening statuses below. Only approved_under_policy may be paid. |
| Approvalapproval · object or null · required | Where a second person's approval stands, when your policy asks for one. |
| Approval request IDapproval. | The approval request. |
| Stateapproval. | pending, approved, rejected, expired, cancelled or voided. |
| Chainchain · object · required | The transaction on its network. |
| Tx hashchain. | The transaction hash, once there is one. |
| Explorer URLchain. | The transaction on a block explorer. |
| Finalitychain. | none, submitted, included or final. |
| Failure reasonfailure_ | Why it failed or was cancelled, or null. |
| Versionversion · integer · required | Increases by one on every change of status. |
| Created atcreated_ | When the payout was made. |
| Updated atupdated_ | When it last changed. |
| Completed atcompleted_ | When it completed, or null. |
If you get no answer
A timeout, a dropped connection or a 5xx means unknown, never failed. The payout may exist and its charge be held. Send the same request with the same key: it never pays twice, and answers the payout exactly as it was first made (200, Idempotent-Replayed: true). Read its state now with GET /payouts/{id}, or find it with GET /payouts by your client_reference.
Refusals
| Code | When, and what to do |
|---|---|
| Insufficient fundsinsufficient_ | Your available USD balance does not cover the total charge. Nothing is held. Fund your account, then quote again. |
| Quote expiredquote_ | The quote passed its expires_at. Nothing is held. Ask for a new quote. |
| Quote already usedquote_ | A payout was already made from this quote. Ask for a new quote. |
| Quote mismatchquote_ | The body does not name what the quote priced. Send the quote's own asset, network, amount, address and memo. |
| Price changedprice_ | The total charge would be above max_total_charge. Nothing is made or held. Quote again, or raise the ceiling. |
| Duplicate referenceduplicate_ | Your client_reference was used before in this workspace. Use a new reference. |
| Idempotency in progressidempotency_ | A request with this key is still running. Wait, then send again with the same key. |
| Idempotency key reusedidempotency_ | The key was used with another body. A new payout needs a new key. |
| Destination not approveddestination_ | The address is not one of your workspace's approved, usable destinations for this asset and network. Approve it as a destination first. |
| Amount above maximumamount_ | Above what one payout may be priced at. Send less, in more than one payout. |
| Payout limit reachedpayout_ | A workspace or platform payout limit. detail names the window, never a figure. Wait for the window, or ask an Owner. |
| Payout blockedpayout_ | Your workspace's policy blocks this payout, or the key no longer stands for a member who may pay. Read your transaction policy, or use a current key. |
| Internal errorinternal_ | Something failed on our side. On createPayout the outcome is unknown. Retry with the same Idempotency-Key: it never pays twice. |
| Payouts unavailablepayouts_ | Crypto payouts are not switched on in this environment. Nothing is written. Do not retry until payouts open here. |
Common mistakes
- Sending again with a new key after a timeout. A new key is a new payout. Reuse the key you stored.
- Reading the state from a replay. A replay answers the payout as it was first made. Read it with a read.
- Treating an accepted payout as paid. It is accepted and its charge held. Wait for
completed. - Retrying a failed payout on your own. A new attempt is a new payout: a new quote and a new key.
Related guides
- Track a payout: what happens after it is accepted.
- Retrying a payout safely: one key, one payout.
- Payout errors: every refusal.
