Counterparties

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. A newly created crypto counterparty starts in pending. Creating it saves the wallet details; it does not itself start screening. A crypto counterparty must be active to be used for payouts, which requires verification. Contact your Augustus account manager if the wallet needs review. You can add as many crypto counterparties as you need, one per wallet address and blockchain.

​

Lifecycle

The status field describes the counterparty’s lifecycle. Blocking is separate. A pending counterparty can become active or rejected. An explicit review reset can return it to pending. Starting a new review of an active counterparty does not itself change its status; a later decision can reject it. Verification attempts and their progress are separate from status.

​

Initial state

These rules apply only when a new record is created. Returning an existing counterparty preserves its status, blocking and details, and does not emit another initial-state event. You cannot choose status in a create or update request.

​

Blocking and payment eligibility

blocked is independent of status: an active counterparty can be blocked. Blocking prevents payments to and from the counterparty; unblocking removes that restriction without activating a pending or rejected counterparty. An account configured to require verified counterparties requires active for payouts. Other fiat accounts do not apply that status requirement. Every payout still has to satisfy the account policy, currency and rail requirements, required recipient details, and payment risk checks. active alone does not mean the destination is reachable over every rail or guarantee that a payment will succeed.

​

Lifecycle webhooks

New records emit their initial-state event. Subscribe to both pending and active events if you need to observe new counterparties; either event can also describe a later lifecycle change. Event payloads are snapshots, and delivery order is not guaranteed. Retrieve the counterparty when you need its current status and blocked values. See Webhooks.

​

Fields

​

Financial address types

Each address includes its type and the fields below. Bank addresses also include account_holder_name. account_type is checking or savings; some destination countries require it. 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. Check its lifecycle and blocking, 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, phone, email, legal_id) 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, phone, email, legal_id, entity_type, and is_self_owned. Omitted fields stay unchanged; send null to clear the name, physical address, date of birth, phone, email or legal ID. financial_address is immutable: create a new counterparty for changed bank details or a different wallet. The update endpoint does not accept metadata, status, or blocked. Updating details does not activate or unblock a counterparty.

​

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.