Payment Callbacks

StraitsX sends a paymentStatusUpdated callback to your registered URL when an incoming payment status changes (e.g., pending → completed or completed → refunded).

This event covers payments received via:

Bank Transfer (SGD/UGD) — deposits into your Virtual Bank Account
PayNow — PayNow QR code payments

When this callback fires

Trigger	Description
Payment received	A sender deposits funds into your VBA or pays via PayNow
Status change	Payment moves from `pending` → `completed`, or `completed` → `refunded`

Status values

Status	Meaning
`pending`	Payment received but not yet settled
`completed`	Payment successfully credited to your account
`refunded`	Payment was refunded back to the sender

Payload structure

{
  "id": "contract_820d55d3621342bbad68a5d795e8a88d",
  "type": "Direct bank transfer",
  "idempotency_id": "0ded43ab-3f06-498d-a776-8fa8fd8ddf35",
  "amount": "29955.0",
  "fees": "0.0",
  "status": "completed",
  "bank_account_no": "885381014328374",
  "merchant_ref": "John Doe",
  "blocked_reasons": [],
  "currency": "xusd",
  "end_to_end_ref": "S0661340E3B601",
  "transaction_remarks": "MYSELF PERSONAL PURPOSE",
  "payment_method": {
    "id": "virtual_account_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "reference_id": "John Doe",
    "account_no": "885381014328374",
    "bank_short_code": "DBS",
    "bank_name": "DBS Bank",
    "bank_address": "12 MARINA BOULEVARD, MBFC TOWER 3, SINGAPORE 018982",
    "bank_country": "Singapore",
    "swift_bic": "DBSSSGSGXXX",
    "recipient_name": "JOHN DOE"
  },
  "sender_information": {
    "account_holder_name": "JOHN DOE",
    "account_number": "SA 832-011076-001",
    "bank_short_code": null,
    "bank_name": null,
    "end_to_end_ref": "S0661340E3B601",
    "swift_bic": "SABBSARIXXX",
    "transaction_remarks": "MYSELF PERSONAL PURPOSE"
  },
  "sender_bank": null,
  "sender_bank_account_no": "SA 832-011076-001",
  "sender_bank_account_holder_name": "JOHN DOE",
  "sender_bank_swift_bic": "SABBSARIXXX",
  "created_at": "2025-04-16T08:15:42.681Z",
  "updated_at": "2025-04-16T08:15:43.330Z",
  "customer_profile_id": "customer_profile_74a5cfe1-587e-4dcf-8885-3e92f5d3c96c"
}

{
  "id": "contract_ce3e2a69c5694665a41fe3f7130e0f35",
  "type": "Direct bank transfer",
  "idempotency_id": "a4e709611640500d5b1c66241850c3b6",
  "amount": "1000.0",
  "fees": "0.0",
  "status": "completed",
  "bank_account_no": "3225445900001",
  "merchant_ref": "merchant-va-ref-001",
  "blocked_reasons": [],
  "currency": "xsgd",
  "end_to_end_ref": "Acme Fintech 0514023018201",
  "transaction_remarks": null,
  "payment_method": {
    "id": "StraitsX-175932-fc1783e5-7854-4388-8111-035385ff9220",
    "reference_id": "merchant-va-ref-001",
    "account_no": "3225445900001",
    "bank_short_code": "FAZZ",
    "recipient_name": "Xfers Pte Ltd"
  },
  "sender_information": {
    "account_holder_name": "ACME FINTECH PTE. LTD.",
    "account_number": "0721100001",
    "bank_short_code": "DBS",
    "bank_name": "DBS Bank Ltd",
    "end_to_end_ref": "Acme Fintech 0514023018201",
    "swift_bic": "DBSSSGSGXXX",
    "transaction_remarks": null
  },
  "sender_bank": "DBS Bank Ltd",
  "sender_bank_account_no": "0721100001",
  "sender_bank_account_holder_name": "ACME FINTECH PTE. LTD.",
  "sender_bank_swift_bic": "DBSSSGSGXXX",
  "created_at": "2025-04-16T02:30:22.492Z",
  "updated_at": "2025-04-16T02:30:22.850Z",
  "customer_profile_id": "customer_profile_af516116-f262-4582-9536-4ddc86fc7442"
}

{
  "id": "contract_a1b2c3d4e5f6789012345678abcdef01",
  "type": "paynowTransaction",
  "idempotency_id": "2026051400001234",
  "amount": "50.0",
  "fees": "0.0",
  "status": "completed",
  "bank_account_no": null,
  "merchant_ref": "2026051400001234",
  "blocked_reasons": [],
  "currency": "xsgd",
  "end_to_end_ref": "paynow1a2b3c4d5e6f789012",
  "transaction_remarks": null,
  "payment_method": {
    "id": "paynow_b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "reference_id": "2026051400001234",
    "base64_encoded_image": "<base64 QR code image>",
    "qr_code_data": "00020101021226650009SG.PAYNOW...",
    "expires_at": "2026-05-14T14:25:32.000Z"
  },
  "sender_information": {
    "account_holder_name": "Jane Smith",
    "account_number": "1234567890",
    "bank_short_code": "UOB",
    "bank_name": "United Overseas Bank Ltd",
    "end_to_end_ref": "paynow1a2b3c4d5e6f789012",
    "swift_bic": "UOVBSGSGXXX",
    "transaction_remarks": null
  },
  "sender_bank": "United Overseas Bank Ltd",
  "sender_bank_account_no": "1234567890",
  "sender_bank_account_holder_name": "Jane Smith",
  "sender_bank_swift_bic": "UOVBSGSGXXX",
  "customer_profile_id": "customer_profile_c3d4e5f6-a7b8-9012-cdef-123456789012",
  "created_at": "2026-05-14T14:19:33.483Z",
  "updated_at": "2026-05-14T14:19:58.509Z"
}

Field reference

📘
Note:

All paymentStatusUpdated callbacks share the same top-level structure. Use the type and currency fields to determine the payment type.

The payment_method object varies depending on the payment type and currency.

`type` value	`currency`	Payment type
`"Direct bank transfer"`	`xsgd` / `sgd`	SGD Bank Transfer
`"Direct bank transfer"`	`xusd` / `usd`	USD Bank Transfer
`"paynowTransaction"`	`xsgd`	PayNow

Top-level fields

Field	Type	Description
`id`	String	Unique contract ID.
`type`	String	`Direct bank transfer` for bank transfers, `paynowTransaction` for PayNow.
`idempotency_id`	String	Your external reference ID (provided during VBA or PayNow creation).
`amount`	String	Payment amount received.
`fees`	String	Fees charged.
`status`	String	Payment status.
`bank_account_no`	String	VBA account number that received the payment. `null` for PayNow.
`merchant_ref`	String	Your merchant reference.
`blocked_reasons`	String	Reasons the payment is held. Empty array if not blocked.
`currency`	String	Currency code (lowercase).
`end_to_end_ref`	String	Bank end-to-end reference.
`transaction_remarks`	String	Sender's transaction remarks.
`payment_method`	Object	Payment method details. Structure varies by payment type (see below).
`sender_information`	Object	Details about who sent the payment.
`customer_profile_id`	String	Customer profile this payment belongs to. Note: Only present for First Party and Third Party integration models. Not included for Regular Transfer payments.
`created_at`	String	ISO 8601 timestamp when the transaction was created.
`updated_at`	String	ISO 8601 timestamp when the status last changed.

`payment_method` object

Field	Scope	Type	Description
`id`	Common fields	String	Payment method ID.
`reference_id`	Common fields	String	Your reference ID.
`account_no`	Common fields	String	VBA account number.
`bank_short_code`	Common fields	String	Bank short code.
`recipient_name`	Common fields	String	Registered recipient name on the VBA.
`bank_name`	USD only	String	Bank full name.
`bank_address`	USD only	String	Bank address.
`bank_country`	USD only	String	Bank country.
`swift_bic`	USD only	String	SWIFT/BIC code.
`base64_encoded_image`	PayNow only	String	Base64-encoded QR code image.
`qr_code_data`	PayNow only	String	Raw QR code data string.
`expires_at`	PayNow only	String	ISO 8601 expiry timestamp for the PayNow QR.

`sender_information` object

Field	Type	Description
`account_holder_name`	String	Sender's name as registered with their bank.
`account_number`	String	Sender's bank account number.
`bank_short_code`	String	Sender's bank short code. May be `null` for international transfers.
`bank_name`	String	Sender's bank full name. May be null for international transfers.
`end_to_end_ref`	String	End-to-end reference from sender's bank.
`swift_bic`	String	Sender's SWIFT/BIC code.
`transaction_remarks`	String	Sender's transaction remarks.

⚠️
Deprecated flat fields
The top-level fields sender_bank, sender_bank_account_no, sender_bank_account_holder_name, and sender_bank_swift_bic duplicate data from sender_information object. Use the sender_information object instead. These flat fields are retained for backward compatibility.

Updated 4 months ago

Did this page help you?