Send payouts

Disburse funds to beneficiaries using the Safepay Raast payout endpoint.

Use this recipe to push funds to beneficiaries such as drivers, vendors, or partners. Payouts share the same aggregator credentials you use for pay-ins.

Prerequisites

• {{aggregator_id}} and {{secret_key}}
• Beneficiary IBAN validated with the account validation utilities
• Webhook endpoint ready to receive payout status updates

Flow summary

1. Validate the beneficiary

   Resolve the beneficiary’s details with GET /title-fetch or GET /account-info to avoid payout failures.

2. Call the payout endpoint

   Send POST /v1/aggregators/{{aggregator_id}}/payout with a unique request_id, the payout amount (string, in PKR), and the beneficiary creditor_iban.

3. Track completion

   Listen for webhook notifications or poll GET /v1/aggregators/{{aggregator_id}}/payments to confirm settlement and update ledgers.

Set {{base_url}} to https://dev.api.getsafepay.com/raastwire in Sandbox or https://api.getsafepay.com/raastwire in Production.

Payouts

Request Fields

request_id · string · required

UUID that keeps payout submissions idempotent.

amount · string · required

Amount in PKR represented as a string (for example, "200" = PKR 200).

creditor_iban · string · required

Beneficiary IBAN that will receive the funds.

API Example

cURL

curl --request POST "{{base_url}}/v1/aggregators/{{aggregator_id}}/payout" \
  --header "X-SFPY-AGGREGATOR-SECRET-KEY: {{secret_key}}" \
  --header "Content-Type: application/json" \
  --data '{
    "request_id": "{{request_id}}",
    "amount": "200",
    "creditor_iban": "PK25ALFH0216001008658216"
  }'

Sample Response

{
  "api_version": "v1",
  "data": {
    "token": "pm_2a8c2cfc-e61d-431e-a850-f1808405ca07",
    "status": "P_INITIATED",
    "amount": "200",
    "request_id": "{{request_id}}",
    "trace_reference": "2005867c-752f-430f-8619-a4c998423e3d",
    "msg_id": "QAI8456FZ5NOR5H6ITEVK2U2NCD7POCSKQS",
    "created_at": "2025-10-02T06:03:11Z"
  }
}

Webhook events to expect

Refer to the webhooks delivery guide for the full event catalog. Settlement-related events are emitted as batch processing progresses.

Failure handling checklist

• Inspect webhook payloads for failure reasons (insufficient funds, invalid account, compliance hold).
• Retry transient errors with the same request_id to stay idempotent.
• Raise manual review tasks for permanent failures and notify beneficiaries.

See also

• Payout lifecycle
• Account validation
• Ledger accounts
• Webhooks delivery
• Create payout