​
What Are Counterparties?

A counterparty is an external party that can send or receive payments through your OpenFX accounts. Every outbound payment requires a counterparty and a payment method that defines how funds are delivered. OpenFX uses the term “counterparty” rather than “beneficiary” because counterparties work for both credit (sending funds) and debit (receiving funds via collections) scenarios. A single counterparty can participate in payments flowing in either direction.
All counterparty IDs use the cpt_ prefix followed by a UUIDv7 identifier (e.g., cpt_01953e1a5f4b7004). This prefix makes counterparty references instantly recognizable in logs and debugging.

​
Key Design Principle: No Inline Rail Details

Counterparties are identity shells. They hold a name, entity type, and optional contact details. Rail-specific delivery information (bank account numbers, IBANs, crypto wallet addresses) is managed separately through payment methods — a dedicated sub-resource under each counterparty. 
Counterparty (cpt_)
  |-- name, entityType, email, address
  +-- Payment Methods (pm_)
        |-- pm_...  US Bank (ACH/Fedwire)
        |-- pm_...  International Bank (SWIFT)
        +-- pm_...  Crypto Wallet (USDC on Ethereum)
This separation means:
  • One counterparty, multiple delivery methods. A single counterparty can have a US bank account, an international bank account, and a crypto wallet. You choose which payment method to use when creating a payment.
  • Clean lifecycle management. You can add individual payment methods without touching the counterparty record.
  • Consistent with industry patterns. This design aligns with Column, Increase, and other modern financial APIs.

​
Counterparty Types

Every counterparty has an entityType that classifies it as either an individual or a business:
TypeDescriptionExample
individualA natural personA freelancer receiving payroll
businessA legal entity or organizationA vendor receiving invoice payments
The entityType is set at creation and cannot be changed.

​
Counterparty Lifecycle

Counterparties have a simple two-state lifecycle:
StatusDescription
activeAvailable for payments. Default status at creation.
archivedSoft-deleted. Cannot receive new payments. Existing in-flight payments are not affected.

​
Creating a Counterparty

To create a counterparty, provide the customerId (the customer who owns this counterparty), the entityType, and a name. The email and address fields are optional. 
curl -X POST https://sandbox.api.openfx.com/v1/counterparties \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Signature: $SIGNATURE" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_01953e1a5f4b7000",
    "entityType": "business",
    "name": "Globex Corporation",
    "email": "payments@globex.com",
    "address": {
      "line1": "123 Industrial Way",
      "city": "Springfield",
      "state": "IL",
      "postalCode": "62701",
      "country": "US"
    }
  }'
The response returns the full counterparty resource: 
{
  "id": "cpt_01953e1a5f4b7004",
  "customerId": "cus_01953e1a5f4b7000",
  "entityType": "business",
  "name": "Globex Corporation",
  "email": "payments@globex.com",
  "address": {
    "line1": "123 Industrial Way",
    "city": "Springfield",
    "state": "IL",
    "postalCode": "62701",
    "country": "US"
  },
  "status": "active",
  "metadata": {},
  "createdAt": "2026-02-23T12:00:00Z",
  "updatedAt": "2026-02-23T12:00:00Z"
}

​
Listing Counterparties

List counterparties with optional filtering by status and cursor-based pagination. 
curl -X GET "https://sandbox.api.openfx.com/v1/counterparties?limit=20&status=active" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Signature: $SIGNATURE" \
  -H "X-Timestamp: $TIMESTAMP"

​
Using Counterparties in Payments

When creating a payment, you reference both the counterpartyId and the specific paymentMethodId that determines how the funds are delivered: 
{
  "customerId": "cus_01953e1a5f4b7000",
  "sourceAccountId": "acc_01953e1a5f4b7002",
  "counterpartyId": "cpt_01953e1a5f4b7004",
  "paymentMethodId": "pm_01953e1a5f4b7300",
  "rail": "ach",
  "sendAmount": {
    "currency": "USD", "amount": "5000.00"
  }
}
The counterpartyId identifies who receives the payment. The paymentMethodId identifies how they receive it (which bank account, crypto wallet, etc.).

​
Metadata

Counterparties support a metadata object for storing your own key-value pairs. This is useful for linking counterparties to records in your system (e.g., ERP vendor IDs, CRM contact IDs). Constraints: maximum 50 keys, key names must match ^[a-zA-Z0-9_]{1,40}$, values are strings up to 500 characters (or null).

​
Next Steps

Payment Methods

Add bank accounts, crypto wallets, and other delivery methods to counterparties.

​
API Reference