'/%3e%3cdefs%3e%3cpattern%20id='pattern0_2104_4598'%20patternContentUnits='objectBoundingBox'%20width='1'%20height='1'%3e%3cuse%20xlink:href='%23image0_2104_4598'%20transform='matrix(0.00376176%200%200%200.0172414%20-0.00219436%200)'/%3e%3c/pattern%3e%3cimage%20id='image0_2104_4598'%20width='267'%20height='58'%20preserveAspectRatio='none'%20xlink:href='data:image/png;base64,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'/%3e%3c/defs%3e%3c/svg%3e)
SWIFT Payouts
Cross-border payouts use the SWIFT destination type when the destination country/currency has no local corridor (ACH, SEPA, domestic GBP, mobile money, etc.). This is the fallback wire rail for USD, EUR, HKD, and similar currencies into most countries.
SWIFT flows use the standard three-step sequence — beneficiary details go on Initialize, not on the quote.
SWIFT is not a separate endpoint — the quote, initialize, and finalize responses all use the same data.payout envelope you see for bank, mobile_money, ACH, and SEPA corridors. The only architectural difference is destination_type: "swift" (plus the SWIFT-specific fields like swift_code, remittance_purpose, and the discriminated sender variant) on the Initialize beneficiary. Refer to Create Payouts Quote, Initialize Payout, and Finalize Payout above for full per-field explanations — the SWIFT steps below focus on what's SWIFT-specific.
Step 1 — Create Quote
Describes currency, amount, and destination country. No beneficiary info on the quote. The quote is the same shape used for every payout corridor — see Create Payouts Quote above for the full field reference.
The quote body has no beneficiary_info and no destination_type. Both belong on Initialize.
Step 2 — Initialize (the SWIFT payload)
The SWIFT beneficiary lives inside the top-level beneficiary object on POST /api/payouts/:quoteId/initialize. All API fields are lowercase snake_case; the adapter normalises them to the downstream provider's format.
Top-Level Fields
SWIFT payload — see the three tables below. Validated against the corridor's field schema for (country, destination_type=swift).
Client-set idempotency / tracking reference. Overrides or supplements the quote's reference.
Short reason code for the payment (free text at this level).
Per-payout webhook URL override.
Optional link to a persisted customer record.
Arbitrary client metadata string.
beneficiary — Core SWIFT Fields
Set to 'swift' (lowercase). Selects the SWIFT wire rail.
ISO 3166-1 alpha-2 of the destination account. Must match the country on the quote.
Full name of the recipient (e.g. 'John Doe').
Recipient's account number, or IBAN if the destination country uses IBAN.
Recipient bank's SWIFT code.
Display name of the destination bank.
Street address of the destination bank branch.
City of the destination bank branch.
Postal / ZIP code of the destination bank branch.
ISO 3166-1 alpha-2 of the destination bank's country.
Lowercase snake_case value from the remittance purposes enum (see reference below).
Recipient's physical address (nested object — see table below).
Sender identity, discriminated by `type` ('business' or 'individual'). See table below.
beneficiary.beneficiary — Recipient Address
ISO 3166-1 alpha-2 of the recipient.
City.
Postal / ZIP code.
Street address.
Rwanda (RW) and Singapore (SG) additionally require type on the nested beneficiary — one of "business" or "individual". No other SWIFT-supporting country requires this.
beneficiary.sender — Payer Identity
'business' or 'individual' (case-insensitive, normalised server-side).
Legal name of the sender (same name-validation rules as recipient account_name).
Sender's ISO 3166-1 alpha-2 country code.
Sender's city.
Sender's street address.
Sender's postal code.
Business registration / tax ID, 2–30 chars. REQUIRED when type='business'; ignored for individuals.
YYYY-MM-DD. REQUIRED when type='individual'.
ISO 3166-1 alpha-2. REQUIRED when type='individual'.
Country-Specific Extras
A handful of countries add required fields beyond the core SWIFT schema. The corridor config at GET /api/payouts/supported-countries/:country is the source of truth.
Australia: 6-digit BSB code, pattern ^\d{6}$. The corridor placeholder shows '062-000' but dashes are NOT accepted — strip them ('062000').
India: 11-char IFSC code, pattern ^[A-Z]{4}0[A-Z0-9]{6}$. Note the key is `IFSCode` (camelCase) — unlike every other field in the payload. Sending `ifs_code` or `ifsc_code` silently fails validation.
Hong Kong uses a stricter SWIFT regex: ^[A-Za-z]{4}HK[A-Za-z0-9]{2}([A-Za-z0-9]{3})?$ — chars 5–6 are pinned to literal 'HK'. Case-insensitive on HK only.
Rwanda and Singapore require `type` ('business' or 'individual') on the nested beneficiary object.
Step 3 — Finalize
No body. Commit the debit and release the payment to the SWIFT rail.
Any body you send on Finalize is ignored. The server only reads the :quoteId from the path.
Discovering SWIFT-Enabled Countries
Before building a SWIFT payload, fetch the corridor config for the destination country and look for destination_types containing "swift". The returned schema for that destination type is the source of truth for that country's required fields.
Validation Failures
http | code | cause |
|---|---|---|
400 | INVALID_BODY | Request body isn't valid JSON or doesn't match the handler shape. |
400 | INVALID_BENEFICIARY_DATA | `country` missing from beneficiary; or a required SWIFT field is missing / fails regex / exceeds length limits. The error message lists each failing field. |
410 | QUOTE_EXPIRED | Quote TTL elapsed before Initialize or Finalize was called. Run the quote + initialize flow again. |
422 | UNSUPPORTED_CORRIDOR | (country, destination_type) pair has no schema — e.g. requesting `swift` for a country that doesn't support it. |
422 | AMOUNT_OUTSIDE_LIMITS | Quote amount is below or above the corridor's min/max limits. |
422 | INSUFFICIENT_BALANCE | Company balance can't cover the payout when source is `offchain`. |
Common Pitfalls
Beneficiary on the quote. It doesn't go there. Quote has no beneficiary_info, no destination_type. Both live on Initialize.
Casing on enums. API is lowercase snake_case for destination_type, remittance_purpose, sender.type. The adapter uppercases them before dispatch — send lowercase.
Casing on SWIFT/BIC. Must be uppercase (DEUTDEFF, not deutdeff). Length is exactly 8 or 11.
Three address blocks. bank_* = destination bank; nested beneficiary.* = recipient's physical address; sender.* = payer's address. All three are independent.
Finalize body. There is none — sending a body is ignored.
country appears twice. Once at the top of beneficiary (corridor lookup key), once nested inside beneficiary.beneficiary.country (recipient's country — often the same value).
Sender variant mismatch. type: "individual" with registration_number → registration_number is silently ignored. type: "business" without registration_number → validation fails.
Name format. account_name / sender.account_name must have ≥2 space-separated parts, each ≥2 chars. No Mr/Mrs/Dr. No single-letter-plus-dot. J. Doe rejects; John Doe passes.
IFSCode is the one camelCase field. Every other SWIFT field is snake_case; India's IFSC is literally IFSCode. Sending ifs_code / ifsc_code silently fails as "missing required field".
AU BSB has no dashes. Placeholder shows 062-000; regex ^\d{6}$ rejects the dash. Submit as 062000.