Skip to main content
Payouts are asynchronous like pay-ins. Use this lifecycle to design back-office processes, customer notifications, and retries.

​
Prerequisites

  • {{aggregator_id}} and {{secret_key}}
  • Validated beneficiary account details (IBAN or alias)
  • Webhook endpoint for status updates

​
Flow overview

1

Validate beneficiary

Run GET /title-fetch or GET /account-info before submitting the payout.
2

Initiate payout

Call POST /v1/aggregators/{{aggregator_id}}/payout with an idempotent request_id, the beneficiary details, and the amount.
3

Await webhook

Safepay pushes status updates to your webhook endpoint. Polling is optional but recommended as a safety net.
4

Reconcile and notify

Update internal ledgers, emit beneficiary notifications, and archive the payload for audit.

​
Webhook events to expect

Use the webhooks delivery guide for the full event catalog and signature verification. Settlement-related events are emitted as batch processing progresses.

​
Status reference

StatusDescriptionRecommended action
P_INITIATEDSafepay accepted the payout request and queued it for processing.Display “processing” in dashboards.
P_RECEIVEDBeneficiary bank is validating the transfer.No action; continue waiting.
P_SETTLEDFunds reached the beneficiary.Mark payouts complete and notify recipients.
P_FAILEDThe payout could not be delivered (invalid account, compliance block, insufficient balance).Investigate failure reason, fix data, and retry with same request_id if appropriate.

​
Operational best practices

  • Webhook reliability: Implement exponential backoff retries if your webhook endpoint experiences downtime.
  • Dual controls: Require two-person review for high-value payouts before calling the API.
  • Ledger reconciliation: Store the trace_reference and request_id to match Safepay webhooks with internal ledger entries.
  • Incident response: Alert operators automatically when a payout remains in P_RECEIVED beyond your SLA or enters P_FAILED.

​
See also