Skip to content

Following a payout

Each change of a payout is sent to an endpoint that subscribes to its events. Order them by version and read the payout before acting.

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.

Subscribe a webhook endpoint to the payout events and every change of a payout's state is sent to it, signed, retried and replayable as every event is. An event tells you a payout moved. The payout itself says where it is and where its charge is.

Subscribing

  • Add the payout event types to an endpoint's events, as you do for order events. See Webhooks for endpoints, signing, retries and replays.
  • An endpoint receives only the types it subscribes to. Ignore a type you do not know: new ones may be added.
  • The event log holds order events only. A payout is read, never looked up in the log.

The events

EventWhat it says
Payout createdpayout.createdThe payout was made and its total charge is held: pending_approval or queued.
Payout processingpayout.processingIt is being prepared for signing. Nothing has left, and the charge stays held.
Payout review requiredpayout.review_requiredIt is held for a screening review, in held. Nothing is sent until the review ends.
Payout submittedpayout.submittedThe signed transfer exists and is handed to its network. From here only the network decides, and the charge stays held.
Payout completedpayout.completedTwo independent readings saw the exact transfer final. The recipient was paid, and the charge is captured.
Payout failedpayout.failedIt ended without delivery: failed on proof, or cancelled before anything was signed. Sent with payout.refunded, at the same version.
Payout refundedpayout.refundedThe charge is back in your available balance. Sent with payout.failed, at the same version, and only once the charge is posted back.
Payout reconciliation requiredpayout.reconciliation_requiredIts outcome is not proven yet. The charge stays held while Nasfam checks the network, and no timer returns it.

Each event is written in the same transaction as the change it reports, once per payout, type and version. It carries the payout exactly as a read presented it at that version.

Handling an event

  1. Verify the signature over the raw body before you parse it, as Webhooks shows. The headers and secrets are the same as for order events.
  2. Record the webhook-id and ignore a repeat. A retry or a replay sends the same bytes and changes nothing.
  3. Order events by the payout's version, never by arrival. Keep the highest version you have seen per payout and ignore anything lower.
  4. Fetch the payout with GET /payouts/{id} before you act on an event.
  5. Mark it paid only when it reads delivered: true on a completed payout.
  6. payout.failed and payout.refunded arrive together, at one version: one change, the charge back in your available balance.
  7. A payout in submitted or reconciliation_required still holds its charge. Time passing never returns it.

When an event does not come

An endpoint can be down, and an event can be late. The payout is the record: read it with GET /payouts/{id} until its status is completed, failed or cancelled. A payout that is taking long is still in progress, and its charge still held.