Payout Callbacks

StraitsX sends a payoutStatusUpdated callback to your registered URL when an outgoing payout status changes (e.g., pending → completed or pending → failed).

This event covers payouts made via:

Bank Transfer (SGD) — domestic payouts via FAST network
Bank Transfer (USD) — international wire payouts
FX Payout — cross-currency payouts (e.g., XUSD → IDR)

When this callback fires

Trigger	Description
Payout initiated	A payout request is submitted and enters `pending` state
Payout completed	Funds have been successfully sent to the recipient
Payout failed	The payout could not be processed (see `failure_reason`)

Status values

Status	Meaning
`pending`	Payout is being processed
`completed`	Funds successfully delivered to recipient
`failed`	Payout could not be completed — check `failure_reason` for details

Payload structure

This event uses two different payload structures depending on the payout type:

Payout type	Structure	How to identify
Bank Transfer (SGD/USD)	Flat JSON	Top-level `type` = `"Withdrawal on behalf"`
FX Payout	JSON:API (nested)	`data.type` = `"fxPayout"`

📘
Important:
Your callback handler should check the payload structure to determine which type of payout it's processing. FX payouts are wrapped in data.attributes, while bank transfer payouts use flat top-level fields.

Field Reference — Bank Transfer Payouts

{
  "id": "contract_c3d4e5f6-a7b8-9012-cdef-123456789012",
  "type": "Withdrawal on behalf",
  "idempotency_id": "payout-usd-unique-key-789",
  "amount": "10000.0",
  "fees": "0.0",
  "status": "completed",
  "account_no": "068760057173",
  "bank_abbrev": "",
  "failure_reason": "",
  "arrival": "14 May 2026 -  9:11 AM",
  "currency": "usd",
  "payout_invoice_id": "payout-usd-unique-key-789",
  "wallet_name": "Digital Goods",
  "bank_account_holder_name": "Acme Corp Pte. Ltd.",
  "swift_bic": "TSIBTWTP",
  "beneficiary_address": "123 Main Street, Singapore, SG, 018982",
  "routing_code": "",
  "intermediary_swift_bic": "",
  "description": null,
  "external_reference": "payout-ext-ref-789",
  "charge_option": "OUR",
  "created_at": "2026-05-14T01:11:03.800Z",
  "updated_at": "2026-05-14T01:11:27.946Z"
}

{
  "id": "contract_b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "type": "Withdrawal on behalf",
  "idempotency_id": "payout-unique-key-456",
  "amount": "500.0",
  "fees": "0.0",
  "status": "completed",
  "account_no": "1234567890",
  "bank_abbrev": "OCBC",
  "failure_reason": "",
  "arrival": "13 May 2026 - 10:51 PM",
  "currency": "sgd",
  "payout_invoice_id": "payout-unique-key-456",
  "wallet_name": "Digital Goods",
  "external_reference": "payout-unique-key-456",
  "created_at": "2026-05-13T14:51:07.967Z",
  "updated_at": "2026-05-13T14:51:09.814Z",
  "express": "FAST"
}

Field	Scope	Type	Description
`id`	Common fields	String	Unique contract ID.
`type`	Common fields	String	Always `Withdrawal on behalf`.
`idempotency_id`	Common fields	String	Your idempotency key from the payout request.
`amount`	Common fields	String	Payout amount.
`fees`	Common fields	String	Fees charged.
`status`	Common fields	String	Payout status.
`account_no`	Common fields	String	Recipient bank account number.
`bank_abbrev`	Common fields	String	Recipient bank short code. May be empty for USD/international payouts.
`failure_reason`	Common fields	String	Reason for failure. Empty string if not failed.
`arrival`	Common fields	String	Human-readable arrival time. Populated when completed.
`currency`	Common fields	String	Currency code (lowercase).
`payout_invoice_id`	Common fields	String	Your payout invoice/reference ID.
`wallet_name`	Common fields	String	Wallet name associated with the payout.
`external_reference`	Common fields	String	Your external reference.
`created_at`	Common fields	String	ISO 8601 timestamp when the payout was created.
`updated_at`	Common fields	String	ISO 8601 timestamp when the status last changed.
`express`	SGD only	String	`FAST` (sent via Singapore's FAST network).
`bank_account_holder_name`	USD only	String	Recipient account holder name.
`swift_bic`	USD only	String	Recipient SWIFT/BIC code.
`beneficiary_address`	USD only	String	Recipient address.
`routing_code`	USD only	String	Bank routing code (empty string if not applicable).
`intermediary_swift_bic`	USD only	String	Intermediary bank SWIFT code (empty string if not applicable).
`description`	USD only	String	Payment description/remarks.
`charge_option`	USD only	String	Fee charge option: `SHA` (shared) or `OUR` (sender pays all fees). *This affects the net amount received by the beneficiary.

Field Reference — FX Payouts

FX payouts use a different payload structure (JSON:API format). They fire the same payoutStatusUpdated event but are wrapped in a data envelope.

{
  "data": {
    "id": "d4d1da72-111e-4d52-bdbf-2e74a2d803d5",
    "type": "fxPayout",
    "attributes": {
      "status": "completed",
      "quoteId": "fx_quote_c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
      "recipientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "rate": 15832.5,
      "from": {
        "currency": "XUSD",
        "amount": "1000.00"
      },
      "to": {
        "currency": "IDR",
        "amount": "15832500.00"
      },
      "fee": {
        "currency": "XUSD",
        "amount": "1.50"
      },
      "initiator": null,
      "references": {
        "externalReference": null,
        "internalReference": "INV-2026-001"
      },
      "createdAt": "2025-03-25T20:04:05+08:00",
      "updatedAt": "2025-03-25T20:10:00+08:00"
    }
  }
}

{
  "data": {
    "id": "d4d1da72-111e-4d52-bdbf-2e74a2d803d5",
    "type": "fxPayout",
    "attributes": {
      "status": "failed",
      "quoteId": "fx_quote_c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
      "recipientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "rate": 15832.5,
      "from": {
        "currency": "XUSD",
        "amount": "1000.00"
      },
      "to": {
        "currency": "IDR",
        "amount": "15832500.00"
      },
      "fee": {
        "currency": "XUSD",
        "amount": "1.50"
      },
      "initiator": {
        "mode": "onBehalfOf",
        "customerProfileId": "b2c3d4e5-f6a7-8901-bcde-f23456789012"
      },
      "references": {
        "externalReference": null,
        "internalReference": "INV-2026-002"
      },
      "createdAt": "2025-03-25T20:04:05+08:00",
      "updatedAt": "2025-03-25T22:15:30+08:00"
    }
  }
}

Field	Type	Description
`data.id`	String	Unique payout contract ID.
`data.type`	String	Always `fxPayout`.
`data.attributes.status`	String	FX Payout status.
`data.attributes.quoteId`	String	The FX quote ID used for this payout.
`data.attributes.recipientId`	String	The payout recipient ID.
`data.attributes.rate`	String	FX rate applied to the conversion.
`data.attributes.from`	Object	Source currency and amount debited.
`data.attributes.from.currency`	String	Source currency code (e.g., `XUSD`).
`data.attributes.from.amount`	String	Amount debited from source.
`data.attributes.to`	Object	Target currency and amount delivered.
`data.attributes.to.currency`	String	Target currency code (e.g., `IDR`).
`data.attributes.to.amount`	String	Amount delivered to recipient.
`data.attributes.fee`	Object	Fee charged for the payout.
`data.attributes.fee.currency`	String	Fee currency.
`data.attributes.fee.amount`	String	Fee amount.
`data.attributes.initiator`	Object	`null` for direct payouts. Populated for `onBehalfOf` payouts.
`data.attributes.initiator.mode`	String	`onBehalfOf` when initiated for a customer profile.
`data.attributes.initiator.customerProfileId`	String	The customer profile ID the payout was made on behalf of.
`data.attributes.references`	Object	Your reference IDs.
`data.attributes.references.externalReference`	String	Your external reference (if provided in the payout request).
`data.attributes.references.internalReference`	String	Your internal reference (if provided in the payout request).
`data.attributes.createdAt`	String	ISO 8601 timestamp when the payout was created.
`data.attributes.updatedAt`	String	ISO 8601 timestamp when the status last changed.