Overview
Fedwire is the US Federal Reserve’s real-time gross settlement (RTGS) system for domestic wire transfers. Fedwire payments settle on the same business day and are irrevocable once processed — the sending bank cannot recall the funds after settlement. This makes Fedwire ideal for urgent, high-value payments where finality is critical.
Wire transfers on OpenFX are created through the POST /payments/fedwire endpoint with a us_bank payment method.
Wire transfers are irrevocable. Once a Fedwire payment reaches processing status, it cannot be canceled or reversed. Double-check all payment details before submission. For payments where you may need the ability to reverse, consider ACH instead.
When to use wire vs. ACH
| Factor | Fedwire | ACH |
|---|
| Speed | Same-day (minutes to hours) | 1-3 business days (standard), same-day available |
| Cost | Higher ($15-30 typical) | Lower ($0.25-1.00 typical) |
| Reversibility | Irrevocable | Returnable (2-60 days) |
| Maximum amount | No network limit | $1M same-day (NACHA) |
| Availability | Business days, Fed hours | Business days, batch windows |
| Best for | Large urgent payments, real estate, time-sensitive settlements | Recurring payments, payroll, vendor payments |
Use wire transfers when you need same-day settlement with no amount limit and can accept higher per-transaction fees.
Prerequisites
Before creating a Fedwire payment, you need:
- An active customer (KYB approved) with a funded USD account
- A counterparty with a
us_bank payment method containing:
routingNumber — 9-digit ABA routing number (must be Fedwire-eligible)accountNumber — Bank account numberbankAccountType — checking or savings
The same us_bank payment method type is used for both ACH and Fedwire payments. The routing number must be valid for Fedwire transactions. Not all routing numbers are Fedwire-eligible — use POST /rails/fedwire/validate to check before creating the payment.
Creating a Fedwire payment
curl -X POST https://sandbox.api.openfx.com/v1/payments/fedwire \
-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_01953e1a5f4b7004",
"paymentMethodId": "pm_01953e1a5f4b7300",
"amount": {
"currency": "USD", "value": "5000000"
},
"reference": "Commercial real estate closing - 100 Main St"
}'
Request fields
| Field | Required | Description |
|---|
sourceAccountId | Yes | The funded USD account to debit |
paymentMethodId | Yes | The us_bank payment method on the counterparty |
counterpartyId | No | The counterparty (can be inferred from payment method) |
amount | Yes | Money object with currency: "USD" and amount as a string |
reference | No | Free-text reference visible to the receiver |
metadata | No | Up to 50 key-value pairs for your internal tracking |
Payment lifecycle
Fedwire payments follow a streamlined lifecycle with no return window:
created -> processing -> completed
-> failed
| Status | Description |
|---|
created | Payment accepted and queued for Fedwire submission |
processing | Payment submitted to the Fedwire network |
completed | Funds delivered to the receiving bank. Final and irrevocable. |
failed | Payment could not be processed (e.g., invalid routing number, insufficient funds) |
Fedwire payments do not have a returned status. Unlike ACH, Fedwire transactions are final once settled. In rare cases of fraud or error, recovery requires a separate process outside the API.
Cutoff times
Fedwire operates during Federal Reserve business hours (approximately 09:00 - 19:00 ET on business days). Payments submitted outside these hours are queued and processed on the next business day.
Use GET /rails/fedwire to check the current cutoff time:
curl -X GET https://sandbox.api.openfx.com/v1/rails/fedwire \
-H "Authorization: Bearer $API_KEY" \
-H "X-Signature: $SIGNATURE" \
-H "X-Timestamp: $TIMESTAMP"
Provider mapping reference
Under the hood, POST /payments/fedwire maps to the banking provider’s wire origination endpoint. The Platform API normalizes provider-specific field names and status values into the OpenFX schema.
Field mapping:
| OpenFX Field | Provider Field | Notes |
|---|
sourceAccountId | deposit_account_id | The funded account to debit |
paymentMethodId | counterparty_us_bank_account_id | The counterparty’s bank account |
amount (decimal string) | amount.value (string cents) + amount.currency="USD" | Amount conversion from OpenFX to provider format |
reference | memo | Max 140 characters, ISO 20022 character set |
| Provider Status | OpenFX Status |
|---|
PENDING | processing |
SETTLED | completed |
FAILED | failed |
RETURNED | returned |
The reference field maps to the provider’s memo field with a maximum of 140 characters
using the ISO 20022 character set. References exceeding this limit will be truncated. Avoid
special characters outside the ISO 20022 set (basic Latin letters, digits, and common punctuation).
The Idempotency-Key header is mapped to the provider’s idempotency header automatically.
You do not need to handle provider-specific header formats.
API reference
