Send payouts

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

Validate the beneficiary

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

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.

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
API Example
Sample Response

string

required

UUID v4 that keeps payout submissions idempotent (exactly 36 characters with hyphens).

string

required

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

string

required

Beneficiary IBAN that will receive the funds.

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"
  }'

const baseUrl = '{{base_url}}';
const aggregatorId = '{{aggregator_id}}';
const secretKey = '{{secret_key}}';

const payoutResponse = await fetch(
  `${baseUrl}/v1/aggregators/${aggregatorId}/payout`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-SFPY-AGGREGATOR-SECRET-KEY': secretKey,
    },
    body: JSON.stringify({
      request_id: crypto.randomUUID(),
      amount: '200',
      creditor_iban: 'PK25ALFH0216001008658216',
    }),
  },
);

if (!payoutResponse.ok) {
  const error = await payoutResponse.json();
  throw new Error(`Payout failed: ${payoutResponse.status} ${error.message}`);
}

type CreatePayoutPayload = {
  api_version: string;
  data: {
    token: string;
    status: 'P_INITIATED' | 'P_RECEIVED' | 'P_FAILED' | 'P_REJECTED' | 'P_SETTLED';
    amount: string;
    request_id: string;
    trace_reference?: string;
    msg_id?: string;
    created_at: string;
  };
};

const payoutPayload: CreatePayoutPayload = await payoutResponse.json();
console.log('Payout token', payoutPayload.data.token);

{
  "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

Payouts use the payment.* event family. Expect payment.created, payment.pending_authorization, and a terminal event such as payment.settled or payment.failed. Identify payout events by checking whether subject.payment.type is PAYOUT or SETTLEMENT_PAYOUT; there is no separate payout.* event family. Refer to the webhooks delivery guide for the full delivery contract and Webhook events and payloads for an example.

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.

Getting started

Integration guides

Use Cases

Concepts

Reference

Prerequisites

Flow summary

Payouts

Webhook events to expect

Failure handling checklist

See also

​Prerequisites

​Flow summary

​Payouts

​Webhook events to expect

​Failure handling checklist

​See also

Prerequisites

Flow summary

Payouts

Webhook events to expect

Failure handling checklist

See also