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

Payouts are represented as payment resources, so they emit payment.* events rather than a separate payout.* family. For the lifecycle above, expect payment.created, payment.pending_authorization, and a terminal event such as payment.settled or payment.failed. Confirm that subject.payment.type is PAYOUT or SETTLEMENT_PAYOUT before applying payout-specific business logic. Use the webhooks delivery guide for signature verification and delivery handling, and Webhook events and payloads for an example.

​
Status reference

​
Operational best practices

  • Webhook reliability: Persist events idempotently and return a 2xx promptly. Safepay performs the supported delivery retries when your endpoint has a transport error or returns 5xx.
  • 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