Track a payout
Read where a payout is, what happened on its network and where its charge is.
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.
Read one payout with GET /payouts/{id}, or your payouts, newest first, with GET /payouts. Both need payouts:read. Another workspace's payout answers not_found.
Statuses
| Status | What it means |
|---|---|
| Pending approvalpending_ | Your workspace's policy asks a second person to approve it. The total charge is held, and nothing has left. |
| Queuedqueued | Accepted and waiting to be signed. The total charge is held, and nothing has left. |
| Processingprocessing | Being signed. Nothing has left yet, and the charge stays held. |
| Submittedsubmitted | Signed and recorded. From here only its network decides, so the charge stays held. |
| Broadcastbroadcast | A node of its network accepted it. It is not delivery, and the charge stays held. |
| Completedcompleted | Final on its network, two independent readings agreeing it reached the address in exactly this amount. The only status with delivered: true. The charge is captured. |
| Failedfailed | Proven never executed, or returned. The charge is returned once, and failure_reason says why. |
| Cancelledcancelled | Ended before anything was signed: rejected, expired, cancelled or refused. The charge is returned once, and failure_reason says why. |
| Heldheld | Under compliance review. The charge stays held, and it moves on only when the review ends. |
| Reconciliation requiredreconciliation_ | Its outcome is not proven by its deadline. The charge stays held while Nasfam reconciles it, and no timer returns it: it moves on only on proof. |
Say the money is back only once the payout reads failed or cancelled. Until then its charge is held, and your available balance does not include it. submitted, broadcast and reconciliation_required are never failures.
curl "https:// sandbox-api. nasfampay. com/ v1/ payouts/ pyt_ 01JD0PAY0VT000000000000000" \ -H "Authorization: Bearer $NASFAM_ SANDBOX_ KEY"On its network
chain holds the tx_hash once there is one, an explorer_url to look it up where there is a network to look on, and how far the network has taken it:
| Finality | What it means |
|---|---|
| Nonenone | Not on its network yet. |
| Submittedsubmitted | Sent to its network, not seen in a block yet. |
| Includedincluded | In a block, not final yet. |
| Finalfinal | Final on its network. |
A hash on its own is not delivery: read status and delivered. A sandbox payout is simulated, so its hash is on no network and it has no explorer_url.
Why it ended
A failed or cancelled payout says why in failure_reason:
| Reason | What happened |
|---|---|
| Approval rejectedapproval_ | The second person rejected it. |
| Approval expiredapproval_ | Nobody decided before the approval expired. |
| Cancelledcancelled | It was cancelled before anything was signed. |
| Policy blockedpolicy_ | Your workspace's transaction policy blocked it. |
| Destination unusabledestination_ | The destination could no longer be paid. |
| Screening restrictedscreening_ | The destination's screening restricts it, so nothing was sent. |
| Signer refusedsigner_ | The signer refused to sign it. Nothing left. |
| Never signednever_ | Proof that it was never signed, so it never executed. |
| Proven deadproven_ | Proof that its transaction can never execute on its network. |
| Proven failedproven_ | Proof that its transaction failed or was returned on its network. |
| Resolved failedresolved_ | Nasfam's reviewed decision on a payout whose outcome was not proven: it failed. |
| Engine offengine_ | It ended before signing while payouts were stopped in this environment. |
Approvals
Where your policy asks for a second person, approval says where that stands:
| Approval | What it means |
|---|---|
| Pendingpending | Waiting for a decision. |
| Approvedapproved | Approved. The payout goes on. |
| Rejectedrejected | Rejected. The payout is cancelled and its charge returned. |
| Expiredexpired | Nobody decided in time. The payout is cancelled and its charge returned. |
| Cancelledcancelled | The request for approval was withdrawn. |
| Voidedvoided | Something it decided on changed, so the decision no longer stands. |
Finding payouts
GET /payouts takes these, and answers a page with has_more and next_cursor:
| Field | Description |
|---|---|
| Limitlimit · integer | How many to return, 1 to 100 (20 when not sent). |
| Cursorcursor · string | Where the last page ended (next_cursor). |
| Statusstatus · string | Only payouts in this status. |
| Client referenceclient_ | Only the payout with this reference of yours. |
| Created fromcreated[gte] · string | Made at or after this time. |
| Created beforecreated[lt] · string | Made before this time. |
curl "https:// sandbox-api. nasfampay. com/ v1/ payouts?status=reconciliation_ required&limit=20" \ -H "Authorization: Bearer $NASFAM_ SANDBOX_ KEY"Related guides
- Following a payout: the events a payout sends, and how to act on them.
- Send a payout: where a payout starts.
- Production readiness: handling a payout still in review.
