Skip to main content
A counterparty is the bank account or wallet belonging to any recipient of money (customers, suppliers, employees, or your external bank accounts). Create one financial address per counterparty and reuse its counterparty_id for payouts. An individual or business with several destinations is represented by several counterparties.

​
Fiat

Save the recipient’s bank details and set entity_type to individual or business. Choose the financial address type for the currency and payment rail below.

​
Stablecoins (USDC)

A crypto counterparty is an external wallet that you own. Crypto flows are closed loop: every crypto counterparty must be a wallet of your own. Adding one starts the screening and verification of the wallet address; once verified, you receive deposits from it and send stablecoin payouts to it. You can add as many crypto counterparties as you need, one per wallet address and blockchain.
A deposit from a wallet that is not verified yet, including one you have not added as a counterparty, stays pending until the counterparty is verified and is then credited. A deposit from a wallet that failed verification is held for review and returned or redirected.

​
Fields

​
Financial address types

Each address includes its type and the fields below. Bank addresses also include account_holder_name. SWIFT has additional name, address and country requirements; see Counterparty details. The financial address does not itself select a USD rail: specify ach, fedwire, or swift on the payout as appropriate.

​
Create and use

Create a counterparty with POST /v1/counterparties, then pass the returned id as counterparty_id when creating a payout, alongside account_id, amount, and currency. Creation is idempotent on the financial address: repeated creation of the same destination does not create another counterparty. If the financial address already exists, the existing counterparty is returned unchanged and any other values in the request (name, physical_address, date_of_birth) are ignored; change them with update. Each merchant holds one counterparty per financial address. Reuse the saved ID for later payouts. For incoming deposits, counterparty_id identifies the sender where the rail provides the sender’s account details. It can be null; inbound ACH deposits have no counterparty because the rail does not share the originator’s account number. A booked transaction carries counterparty_id when a counterparty was resolved, otherwise null. Its nullable counterparty object contains financial and physical address details; source links to the originating deposit, payout or return when available.

​
Update

Update a counterparty with POST /v1/counterparties/{id}. You can change name, physical_address, date_of_birth, entity_type, and is_self_owned. Omitted fields stay unchanged; send null to clear the name, physical address or date of birth. financial_address is immutable: create a new counterparty for changed bank details or a different wallet. The update endpoint does not accept metadata.

​
Idempotency

Both POST endpoints require an Idempotency-Key. Reuse the same key and identical body when retrying a request to receive the cached response. Reusing the key with a different body returns 409. This retry protection is separate from deduplication by financial address. See Idempotency.

​
List, retrieve and scopes

  • List counterparties: GET /v1/counterparties, with cursor pagination in both directions. limit accepts 1–100 and defaults to 10; pass next_cursor as cursor for older records or previous_cursor for newer ones. See Pagination.
  • Retrieve a counterparty: GET /v1/counterparties/{id}.
  • counterparties:read covers list and retrieve. counterparties:write covers create and update. See Scopes.