Overview
The OPEN rail is OpenFX’s internal payment network for moving funds between entities on the platform. OPEN payments are instant (the response may return status: completed immediately), fee-free (no transaction fees), and same-currency only (no FX conversion — use the FX engine first if you need to convert).
This rail is unique to OpenFX — it does not use any external banking or blockchain network. Funds move between accounts within the platform’s internal ledger.
OPEN payments settle immediately. Unlike ACH (days), wire (hours), or even crypto (minutes), OPEN payments can complete within the same API request. The response may return with status: completed directly.
Use cases
| Scenario | Description |
|---|
| Intercompany transfers | Move funds between different entities within your organization on OpenFX |
| Marketplace settlements | Settle funds from a platform escrow account to seller accounts |
| Platform disbursements | Distribute funds to multiple entities managed on the platform |
| Internal treasury | Move funds between accounts for treasury management purposes |
Two ways to specify the recipient
OPEN payments support two approaches for identifying the recipient:
Option 1: Via a pre-created payment method
Create an open payment method on the counterparty with an openId (the recipient’s customer ID or account ID), then reference it in the payment:
# First, create the open payment method
curl -X POST https://sandbox.api.openfx.com/v1/counterparties/cpt_01953e1a5f4b7040/payment-methods \
-H "Authorization: Bearer $API_KEY" \
-H "X-Signature: $SIGNATURE" \
-H "X-Timestamp: $TIMESTAMP" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"type": "open",
"openId": "acc_01953e1a5f4b7080",
"label": "Subsidiary USD account"
}'
# Then, create the payment
curl -X POST https://sandbox.api.openfx.com/v1/payments/open \
-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_01953e1a5f4b7040",
"paymentMethodId": "pm_01953e1a5f4b7370",
"amount": {
"currency": "USD", "value": "10000000"
},
"reference": "Q1 intercompany settlement"
}'
Option 2: Via inline destination
For ad-hoc payments where you do not want to pre-create a payment method, specify the destination inline using a customer ID or account ID:
curl -X POST https://sandbox.api.openfx.com/v1/payments/open \
-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",
"destination": {
"type": "account_id",
"value": "acc_01953e1a5f4b7080"
},
"amount": {
"currency": "USD", "value": "2500000"
},
"reference": "Marketplace payout - Order #ORD-8842"
}'
destination object accepts two types:
| Type | Description | Example value |
|---|
customer_id | Recipient identified by their OpenFX customer ID | cus_01953e1a5f4b7000 |
account_id | Recipient identified by their OpenFX account ID | acc_01953e1a5f4b7080 |
open_id | Recipient identified by their OPEN ID (a human-readable address) | @acme.treasury.usd |
OPEN IDs use the format @org.handle.currency (e.g., @acme.treasury.usd). They provide a human-readable alternative to opaque resource IDs for identifying recipients on the OPEN rail.
Use inline destination for one-off or ad-hoc transfers. Use pre-created payment methods when you regularly send to the same recipient — it avoids repeating the destination details and enables payment method validation.
Request fields (via payment method)
| Field | Required | Description |
|---|
sourceAccountId | Yes | The funded account to debit |
paymentMethodId | Yes | The open payment method |
counterpartyId | No | The counterparty |
amount | Yes | Money object with currency and amount |
reference | No | Reference visible to both sender and recipient |
metadata | No | Up to 50 key-value pairs |
Request fields (via inline destination)
| Field | Required | Description |
|---|
sourceAccountId | Yes | The funded account to debit |
destination | Yes | OPENDestination with type and value |
counterpartyId | No | The counterparty (optional) |
amount | Yes | Money object with currency and amount |
reference | No | Reference visible to both sender and recipient |
metadata | No | Up to 50 key-value pairs |
Specify either paymentMethodId or destination, not both. The API will reject requests that include both fields.
Constraints
| Constraint | Details |
|---|
| Same-currency only | Source and destination must hold the same currency. No automatic FX conversion. |
| Both parties on OpenFX | The recipient must be an active entity on the OpenFX platform. |
| Fee-free | No transaction fees for OPEN payments. |
| Instant | Payments complete synchronously — the response may already show status: completed. |
If you need to send a different currency than the source account holds, first convert using the FX engine (POST /fx/conversions), then initiate the OPEN payment in the converted currency.
Payment lifecycle
OPEN payments have the simplest lifecycle of any rail:
created -> completed
-> failed
| Status | Description |
|---|
created | Payment accepted (may be transient — can complete in the same request) |
completed | Funds moved. Instant and final. |
failed | Payment could not be processed (e.g., insufficient funds, inactive recipient) |
OPEN payments are designed for speed. In most cases, the API response will already contain status: completed — the payment settles within the same request-response cycle.
OPEN rail vs. internal transfers
OpenFX has two mechanisms for moving money between accounts:
| Feature | OPEN (POST /payments/open) | Transfers (POST /transfers) |
|---|
| Scope | Between different entities/customers | Between accounts owned by the same customer |
| Use case | Intercompany, marketplace, platform | Treasury management, account rebalancing |
| Counterparty required | Yes (or inline destination) | No (both accounts belong to you) |
| Compliance screening | Yes | Minimal (same-owner transfer) |
API reference
