Overview
SWIFT (Society for Worldwide Interbank Financial Telecommunication) is the global standard for international cross-border wire transfers. With connectivity to banks in over 180 countries, SWIFT is the primary rail for sending payments internationally.
SWIFT payments on OpenFX support multi-currency transfers with automatic FX conversion, charge bearer options, and purpose codes required by many international corridors.
SWIFT payments typically settle in 1-5 business days depending on the corridor, intermediary banks involved, and whether the payment requires manual compliance review at any point in the chain.
Key features
- 180+ countries — Send to virtually any country with a SWIFT-connected bank
- Multi-currency — Send in the destination currency with automatic FX conversion, or send in your source currency
- Charge bearer options — Control who pays SWIFT network and intermediary bank fees
- Purpose codes — Required for many corridors, ensures regulatory compliance
- Corridor requirements — Dynamic discovery of required fields per destination
Charge bearer options
The chargeBearer field controls how SWIFT network and intermediary bank charges are allocated:
| Option | Description | When to use |
|---|
OUR | Sender pays all charges | When you want the counterparty to receive the exact amount sent |
SHA | Charges shared between sender and counterparty | Most common option; each party pays their own bank’s fees |
BEN | Counterparty pays all charges | When the counterparty has agreed to absorb all transfer costs |
SHA (shared) is the most commonly used charge bearer option and is the default if not specified. Use OUR when the counterparty must receive a specific amount (e.g., exact invoice payment) and you are willing to absorb all intermediary fees.
Purpose codes
Many international corridors require a purpose field that describes the reason for the payment. This is a regulatory requirement enforced by the receiving country’s central bank or financial authority.
| Purpose | Description |
|---|
goods_and_services | Payment for goods or services rendered |
intercompany_transfer | Transfer between related corporate entities |
investments | Investment-related payment |
payroll | Salary or wage payment |
treasury_management | Corporate treasury operation |
pension | Pension or retirement fund payment |
tax_payment | Tax payment to a government entity |
trade_of_goods | International trade payment |
financial_services | Payment for financial services |
donations_and_charity | Charitable donation |
rent_and_lease | Rent or lease payment |
reimbursement | Expense reimbursement |
salary_and_compensation | Employee compensation |
other | Other purpose (provide details in reference) |
Omitting the purpose field when it is required for the destination corridor will cause the payment to fail or be held for manual review. Use the corridor requirements endpoint to check what fields are required before creating the payment.
Prerequisites
Before creating a SWIFT payment, you need:
- An active customer (KYB approved) with a funded account
- A counterparty with an
international_bank payment method containing:
iban — International Bank Account Number (or local account format for non-IBAN countries)bic — SWIFT/BIC code (8 or 11 characters)bankName — Name of the receiving bank
Creating a SWIFT payment
curl -X POST https://sandbox.api.openfx.com/v1/payments/swift \
-H "Authorization: Bearer $API_KEY" \
-H "X-Signature: $SIGNATURE" \
-H "X-Timestamp: $TIMESTAMP" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"sourceAccountId": "acc_01953e1a5f4b7002",
"counterpartyId": "cpt_01953e1a5f4b7020",
"paymentMethodId": "pm_01953e1a5f4b7320",
"sendAmount": {
"currency": "USD", "value": "1000000"
},
"chargeBearer": "SHA",
"purpose": "goods_and_services",
"executionPreference": "at_market",
"reference": "PO-2026-00451 - Q1 component order"
}'
Request fields
| Field | Required | Description |
|---|
sourceAccountId | Yes | The funded account to debit |
paymentMethodId | Yes | The international_bank payment method on the counterparty |
counterpartyId | No | The counterparty (can be inferred from payment method) |
sendAmount | Yes* | Amount to send from the source account. One of sendAmount or receiveAmount must be provided. |
receiveAmount | No* | Amount the counterparty should receive. If specified, the system calculates the send amount including fees and FX. |
chargeBearer | No | OUR, SHA, or BEN. Defaults to SHA. |
purpose | No** | Payment purpose code. Required for many corridors — check corridor requirements. |
executionPreference | No | use_quote (with pre-locked quoteId) or at_market (current market rate). Defaults to at_market. |
quoteId | No | Pre-locked FX quote ID. Required when executionPreference is use_quote. |
reference | No | Payment reference visible to the counterparty |
metadata | No | Up to 50 key-value pairs for internal tracking |
Using a pre-locked FX quote
For large cross-currency SWIFT payments, you may want to lock the exchange rate before creating the payment. Create an FX quote first, then reference it:
# Step 1: Create an FX quote
curl -X POST https://sandbox.api.openfx.com/v1/fx/quotes \
-H "Authorization: Bearer $API_KEY" \
-H "X-Signature: $SIGNATURE" \
-H "X-Timestamp: $TIMESTAMP" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"sellCurrency": "USD",
"buyCurrency": "EUR",
"sellAmount": "25000.00",
"accountId": "acc_01953e1a5f4b7002"
}'
# Step 2: Use the quote in the SWIFT payment
curl -X POST https://sandbox.api.openfx.com/v1/payments/swift \
-H "Authorization: Bearer $API_KEY" \
-H "X-Signature: $SIGNATURE" \
-H "X-Timestamp: $TIMESTAMP" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"sourceAccountId": "acc_01953e1a5f4b7002",
"counterpartyId": "cpt_01953e1a5f4b7020",
"paymentMethodId": "pm_01953e1a5f4b7320",
"sendAmount": {
"currency": "USD", "value": "2500000"
},
"executionPreference": "use_quote",
"quoteId": "qte_01953e1a5f4b7006",
"chargeBearer": "OUR",
"purpose": "intercompany_transfer",
"reference": "Monthly intercompany settlement"
}'
FX quotes are valid for 60 seconds. If the quote expires before the payment is created, the payment creation will fail. You can set executionPreference: "at_market" as a fallback to execute at the current market rate.
Payment lifecycle
created -> processing -> completed
-> in_review -> processing
-> completed
-> returned
-> failed
| Status | Description |
|---|
created | Payment accepted and pre-validated |
in_review | Under compliance or sanctions review |
processing | Submitted to the SWIFT network |
completed | Funds delivered to the counterparty’s bank |
returned | Payment returned by an intermediary or receiving bank |
failed | Payment could not be processed |
International SWIFT payments are more likely to enter in_review status due to compliance screening, sanctions checks, and corridor-specific regulations. Always handle this status in your integration — subscribe to the payment.in_review webhook event.
API reference
