Skip to content

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:

FieldDescription
Assetasset · string · requiredThe 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 · requiredThe network the transfer is made on, one GET /v1/payout-networks lists. An address approved on one network authorises nothing on another.
Amountamount · string · requiredWhat 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 · requiredThe destination address, 32 to 80 printable characters: one of your workspace's approved destinations.
Memomemo · stringThe text comment the transfer carries, where the destination needs one. Part of the destination's identity.
Client referenceclient_reference · stringYour own reference, up to 64 letters, digits and ._:-, unique in your workspace for ever (409 duplicate_reference).
Metadatametadata · objectUp to 10 keys of your own, each a string of at most 200 characters, returned on the payout. Never personal data.
Quote IDquote_id · string · requiredThe quote. The payout is charged exactly its charge.total_micros, or refused.
Max total chargemax_total_charge · stringThe 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.

Code for From a quote
# 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:

FieldDescription
Assetasset · string · requiredThe 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 · requiredThe network the transfer is made on, one GET /v1/payout-networks lists. An address approved on one network authorises nothing on another.
Amountamount · string · requiredWhat 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 · requiredThe destination address, 32 to 80 printable characters: one of your workspace's approved destinations.
Memomemo · stringThe text comment the transfer carries, where the destination needs one. Part of the destination's identity.
Client referenceclient_reference · stringYour own reference, up to 64 letters, digits and ._:-, unique in your workspace for ever (409 duplicate_reference).
Metadatametadata · objectUp to 10 keys of your own, each a string of at most 200 characters, returned on the payout. Never personal data.
Max total chargemax_total_charge · string · requiredThe 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.

FieldDescription
IDid · string · requiredThe payout: pyt_ and 26 characters.
Objectobject · string · requiredpayout.
Statusstatus · string · requiredWhere it is: one of the statuses below.
Delivereddelivered · boolean · requiredTrue only when status is completed.
Assetasset · string · requiredThe 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 · requiredThe network the transfer is made on, one GET /v1/payout-networks lists. An address approved on one network authorises nothing on another.
Amountamount · string · requiredWhat the recipient receives.
Amount unitsamount_units · string · requiredThe same amount in the asset's smallest unit.
Decimalsdecimals · integer · requiredThe asset's decimal places.
Addressaddress · string · requiredThe normalised address.
Memomemo · string or null · requiredThe memo, or null.
Destination IDdestination_id · string · requiredThe approved destination it pays.
Client referenceclient_reference · string or null · requiredYour reference, or null.
Metadatametadata · object or null · requiredYour metadata, or null.
Quote IDquote_id · string · requiredThe quote it was priced by.
Chargecharge · object · requiredWhat your USD balance is charged.
Currencycharge.currency · string · requiredUSD.
Payout value microscharge.payout_value_micros · string · requiredWhat the recipient amount is worth at the quote's rate.
Platform fee microscharge.platform_fee_micros · string · requiredNasfam's fee for sending it.
Network fee microscharge.network_fee_micros · string · requiredThe network's fee, Nasfam's own estimate for the network. A request never supplies one.
Conversion fee microscharge.conversion_fee_micros · string · requiredThe spread on the rate.
Total microscharge.total_micros · string · requiredWhat your USD balance is charged in all: the sum of the four.
Screeningscreening · object · requiredThe destination's screening for this payout.
Statusscreening.status · string · requiredOne of the screening statuses below. Only approved_under_policy may be paid.
Approvalapproval · object or null · requiredWhere a second person's approval stands, when your policy asks for one.
Approval request IDapproval.approval_request_id · string · requiredThe approval request.
Stateapproval.state · string · requiredpending, approved, rejected, expired, cancelled or voided.
Chainchain · object · requiredThe transaction on its network.
Tx hashchain.tx_hash · string or null · requiredThe transaction hash, once there is one.
Explorer URLchain.explorer_url · string or null · requiredThe transaction on a block explorer.
Finalitychain.finality · string · requirednone, submitted, included or final.
Failure reasonfailure_reason · string or null · requiredWhy it failed or was cancelled, or null.
Versionversion · integer · requiredIncreases by one on every change of status.
Created atcreated_at · string · requiredWhen the payout was made.
Updated atupdated_at · string · requiredWhen it last changed.
Completed atcompleted_at · string or null · requiredWhen 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

CodeWhen, and what to do
Insufficient fundsinsufficient_funds · 402Your available USD balance does not cover the total charge. Nothing is held. Fund your account, then quote again.
Quote expiredquote_expired · 409The quote passed its expires_at. Nothing is held. Ask for a new quote.
Quote already usedquote_already_used · 409A payout was already made from this quote. Ask for a new quote.
Quote mismatchquote_mismatch · 409The body does not name what the quote priced. Send the quote's own asset, network, amount, address and memo.
Price changedprice_changed · 409The total charge would be above max_total_charge. Nothing is made or held. Quote again, or raise the ceiling.
Duplicate referenceduplicate_reference · 409Your client_reference was used before in this workspace. Use a new reference.
Idempotency in progressidempotency_in_progress · 409A request with this key is still running. Wait, then send again with the same key.
Idempotency key reusedidempotency_key_reused · 422The key was used with another body. A new payout needs a new key.
Destination not approveddestination_not_approved · 422The 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_maximum · 422Above what one payout may be priced at. Send less, in more than one payout.
Payout limit reachedpayout_limit_reached · 422A workspace or platform payout limit. detail names the window, never a figure. Wait for the window, or ask an Owner.
Payout blockedpayout_blocked · 422Your 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_error · 500Something failed on our side. On createPayout the outcome is unknown. Retry with the same Idempotency-Key: it never pays twice.
Payouts unavailablepayouts_unavailable · 503Crypto 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.