Sending a payout

A payout moves money from your account to a saved beneficiary. Its amount plus fee is set aside the moment you create it.

sequenceDiagram
  autonumber
  participant S as Your server
  participant API as Partner API
  participant B as Beneficiary's bank
  S->>API: POST /beneficiaries (once)
  API-->>S: 201 — id: ben_…
  S->>API: GET /balances
  API-->>S: collateral / available
  S->>API: POST /payouts
  alt enough funds
    API-->>S: 201 — created, amount + fee set aside
    API->>B: Send
    B-->>API: Paid → succeeded
  else not enough
    API-->>S: 409 insufficient_collateral
  end

1. Save the beneficiary

POST /v1/beneficiaries HTTP/1.1
Authorization: Bearer <your API key>
Idempotency-Key: supplier-88-bank
Content-Type: application/json

{
  "type": "bank_account",
  "account_ref": "157203004488",
  "currency": "MYR",
  "details": { "bank_code": "MBBEMYKL", "account_holder": "Acme Payments Sdn Bhd" }
}

• Save the returned id (ben_…). Reuse it for every payout.
• Must be active to receive payouts.

2. Check funds

• GET /balances, per currency.
• Funded from collateral. Some accounts use available instead.
• Needed: amount + fee_amount. Fee is added on top.

3. Create

POST /v1/payouts HTTP/1.1
Authorization: Bearer <your API key>
Idempotency-Key: payout-4821
Content-Type: application/json

{
  "beneficiary_id": "ben_01H8ABCDEFGHJKMNPQRSTVWXYZ",
  "amount": "100.00",
  "currency": "MYR",
  "payment_method": "online_banking",
  "merchant_reference": "payout-4821"
}

• 201 → created, funds set aside.
• Then processing → result. See Payment lifecycle.

Where the money goes

flowchart LR
  bal["Your balance"]
  res["Set aside:<br/>amount + fee"]
  out["Beneficiary"]
  bal -- "POST /payouts" --> res
  res -- "succeeded" --> out
  res -- "failed / expired / cancelled:<br/>all back" --> bal
  res -- "partial:<br/>unsent part back" --> bal

Cancel

POST /v1/payouts/pay_01H8ABCDEFGHJKMNPQRSTVWXYZ/cancel HTTP/1.1
Idempotency-Key: payout-4821-cancel

• Only while created → cancelled, funds back.
• Already sending → 409 payout_not_cancellable.

Errors

• Refused → nothing set aside.