Skip to content

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

StatusWhat it means
Pending approvalpending_approvalYour workspace's policy asks a second person to approve it. The total charge is held, and nothing has left.
QueuedqueuedAccepted and waiting to be signed. The total charge is held, and nothing has left.
ProcessingprocessingBeing signed. Nothing has left yet, and the charge stays held.
SubmittedsubmittedSigned and recorded. From here only its network decides, so the charge stays held.
BroadcastbroadcastA node of its network accepted it. It is not delivery, and the charge stays held.
CompletedcompletedFinal 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.
FailedfailedProven never executed, or returned. The charge is returned once, and failure_reason says why.
CancelledcancelledEnded before anything was signed: rejected, expired, cancelled or refused. The charge is returned once, and failure_reason says why.
HeldheldUnder compliance review. The charge stays held, and it moves on only when the review ends.
Reconciliation requiredreconciliation_requiredIts 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.

Code for Statuses
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:

FinalityWhat it means
NonenoneNot on its network yet.
SubmittedsubmittedSent to its network, not seen in a block yet.
IncludedincludedIn a block, not final yet.
FinalfinalFinal 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:

ReasonWhat happened
Approval rejectedapproval_rejectedThe second person rejected it.
Approval expiredapproval_expiredNobody decided before the approval expired.
CancelledcancelledIt was cancelled before anything was signed.
Policy blockedpolicy_blockedYour workspace's transaction policy blocked it.
Destination unusabledestination_unusableThe destination could no longer be paid.
Screening restrictedscreening_restrictedThe destination's screening restricts it, so nothing was sent.
Signer refusedsigner_refusedThe signer refused to sign it. Nothing left.
Never signednever_signedProof that it was never signed, so it never executed.
Proven deadproven_deadProof that its transaction can never execute on its network.
Proven failedproven_failedProof that its transaction failed or was returned on its network.
Resolved failedresolved_failedNasfam's reviewed decision on a payout whose outcome was not proven: it failed.
Engine offengine_offIt ended before signing while payouts were stopped in this environment.

Approvals

Where your policy asks for a second person, approval says where that stands:

ApprovalWhat it means
PendingpendingWaiting for a decision.
ApprovedapprovedApproved. The payout goes on.
RejectedrejectedRejected. The payout is cancelled and its charge returned.
ExpiredexpiredNobody decided in time. The payout is cancelled and its charge returned.
CancelledcancelledThe request for approval was withdrawn.
VoidedvoidedSomething 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:

FieldDescription
Limitlimit · integerHow many to return, 1 to 100 (20 when not sent).
Cursorcursor · stringWhere the last page ended (next_cursor).
Statusstatus · stringOnly payouts in this status.
Client referenceclient_reference · stringOnly the payout with this reference of yours.
Created fromcreated[gte] · stringMade at or after this time.
Created beforecreated[lt] · stringMade before this time.
Code for Finding payouts
curl "https://sandbox-api.nasfampay.com/v1/payouts?status=reconciliation_required&limit=20" \  -H "Authorization: Bearer $NASFAM_SANDBOX_KEY"