POST
/
counterparties
/
{counterpartyId}
/
payment-methods
curl --request POST \
  --url https://sandbox.api.openfx.com/v1/counterparties/{counterpartyId}/payment-methods \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-Signature: <api-key>' \
  --header 'X-Timestamp: <api-key>' \
  --data '
{
  "type": "us_bank",
  "currency": "USD",
  "label": "Globex USD Operating",
  "routingNumber": "021000021",
  "accountNumber": "123456789012",
  "bankAccountType": "checking",
  "accountHolderName": "Globex Corporation"
}
'
{
  "id": "pm_01953e1a5f4b7300",
  "counterpartyId": "cpt_01953e1a5f4b7004",
  "type": "us_bank",
  "status": "active",
  "currency": "USD",
  "label": "Globex USD Operating",
  "accountHolderName": "Globex Corporation",
  "bankName": "Chase",
  "routingNumber": "021000021",
  "accountNumberLast4": "7890",
  "bankAccountType": "checking",
  "validationResult": "verified",
  "validatedAt": "2026-02-23T12:00:00Z",
  "createdAt": "2026-02-23T12:00:00Z"
}

Authorizations

​
Authorization
string
header
required

API key issued at onboarding. Passed as a Bearer token in the Authorization header: Authorization: Bearer <api-key>. Identifies the caller and determines organization scope. Invalid or revoked keys return 401 with error type authentication_error.

​
X-Signature
string
header
required

Ed25519 or RSA-SHA256 asymmetric signature over the request payload (ADR-0015). Provides request integrity and non-repudiation. The signature covers the HTTP method, path, query string, request body, and timestamp. Invalid signatures return 401 with error type authentication_error.

​
X-Timestamp
string
header
required

Unix timestamp (seconds) of when the request was signed. Server rejects requests where the timestamp drifts beyond +/-60 seconds from server time to prevent replay attacks. Must match the timestamp used in the signature computation.

Headers

​
Idempotency-Key
string
required

Idempotency key for this request. UUID v4 recommended. Max 128 characters. 24-hour retention. Same key + same body replays original response with Idempotency-Replayed: true. Same key + different body returns 409 (code: duplicate_idempotency_key). Same key while the original request is still processing returns 409 with a Retry-After header (code: idempotency_key_in_flight).

Maximum string length: 128
Example:

"550e8400-e29b-41d4-a716-446655440000"

Path Parameters

​
counterpartyId
string
required

Unique identifier of the counterparty (cpt_ prefix). Counterparty resource identifier.

Pattern: ^cpt_[A-Za-z0-9]+$
Example:

"cpt_01953e1a5f4b7004"

Body

application/json

US domestic bank account payment method (ACH/Wire/FedNow).

​
type
enum<string>
required

Payment method type discriminator.

Available options:
us_bank
​
currency
string
required

ISO 4217 currency code for fiat (USD, EUR, GBP) or crypto asset ticker (USDC, BTC, ETH). Uppercase, 2-10 characters. Use this type in contexts where both fiat currencies and crypto assets are accepted.

Pattern: ^[A-Z]{2,10}$
Example:

"USD"

​
routingNumber
string
required

ABA routing transit number (9 digits).

Pattern: ^\d{9}$
​
accountNumber
string
required

Bank account number. Write-only; masked in responses.

​
bankAccountType
enum<string>
required

Type of US bank account.

Available options:
checking,
savings
​
label
string

Consumer-defined label.

Maximum string length: 100
​
accountHolderName
string

Name on the bank account.

Maximum string length: 200
​
metadata
object

Consumer-defined key-value store. Available on all primary resources. Max 50 keys. Keys must match ^[a-zA-Z0-9_]{1,40}$. Values are strings (max 500 chars) or null.

Response

Payment method created.

A reusable payment method attached to a counterparty. Discriminated on type for rail-specific fields. Replaces V2's inline rail details. Fields present depend on the type — see each field's description for which types include it.

​
id
string
required

Payment method resource identifier.

Pattern: ^pm_[A-Za-z0-9]+$
Example:

"pm_01953e1a5f4b7300"

​
counterpartyId
string
required

Counterparty resource identifier.

Pattern: ^cpt_[A-Za-z0-9]+$
Example:

"cpt_01953e1a5f4b7004"

​
type
enum<string>
required

Type of payment method. Used as discriminator for type-specific fields.

Available options:
us_bank,
international_bank,
crypto_wallet,
open
​
status
enum<string>
required

Lifecycle status of a payment method.

Available options:
pending,
active,
rejected
​
currency
string
required

Currency of the payment method.

Pattern: ^[A-Z]{2,10}$
Example:

"USD"

​
createdAt
string<date-time>
required

UTC timestamp in RFC 3339 / ISO 8601 format.

Example:

"2026-02-23T12:00:00Z"

​
label
string

Consumer-defined label.

Example:

"Globex USD Operating"

​
accountHolderName
string

Name on the account (us_bank, international_bank, sepa_bank, fps_bank).

Example:

"Globex Corporation"

​
bankName
string

Name of the bank (us_bank, international_bank).

Example:

"Chase"

​
routingNumber
string

ABA routing number (us_bank).

Example:

"021000021"

​
accountNumberLast4
string

Last 4 digits of account number (us_bank, fps_bank).

Pattern: ^[0-9]{4}$
​
bankAccountType
enum<string>

Checking or savings (us_bank).

Available options:
checking,
savings
​
iban
string

IBAN (international_bank, sepa_bank).

Example:

"DE89370400440532013000"

​
bic
string

SWIFT/BIC code (international_bank, sepa_bank).

Example:

"COBADEFFXXX"

​
intermediaryBic
string

Intermediary/correspondent bank SWIFT code (international_bank).

​
bankAddress
object

Address of the receiving bank (international_bank).

​
chain
enum<string>

Blockchain network (crypto_wallet).

Available options:
ethereum,
solana,
base,
ink,
sui
​
walletAddress
string

On-chain wallet address (crypto_wallet).

Example:

"0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B"

​
destinationTag
string

Destination tag or memo for chains that require it, e.g. XRP, XLM (crypto_wallet).

​
openId
string

Recipient's OPEN ID (@org.handle.currency), OpenFX customer ID (cus_), or account ID (acc_) for platform-internal OPEN payments.

​
validationResult
enum<string>

Result of payment method validation (e.g., Confirmation of Payee, Verification of Payee). partial_match and no_match replace the deprecated mismatch value with legally significant granularity required under UK PSR regulations.

Available options:
verified,
partial_match,
no_match,
unverified,
mismatch,
unavailable,
not_required,
error
​
validatedAt
string<date-time> | null

UTC timestamp in RFC 3339 / ISO 8601 format.

Example:

"2026-02-23T12:00:00Z"