Counterparty Instruments

Counterparty Instruments

A payment instrument defines how funds are delivered to a counterparty — the bank account details, routing information, or wallet address used for the transfer. Each counterparty can have one or more instruments covering different payment rails.

---

Supported instrument types

Type	Rail	Use for
ACH	ACH	US domestic bank transfers
Wire	WIRE	US domestic high-value transfers
International Wire	INTERNATIONAL_WIRE	International wire transfers
Cross-Border	CROSS_BORDER	Multi-currency FX payments
USDC	Stablecoin	USDC wallet transfers
PYUSD	Stablecoin	PayPal USD wallet transfers

---

Key concepts

• Dynamic required fields — Each instrument type requires a specific set of fields that can vary by currency, country, and routing method. Always call POST .../required-fields before creating an instrument and send only the fields it returns — never guess.
• Enable before paying — If an instrument is disabled, it must be enabled before it can be used in a payment. Call PUT .../enable to activate it.
• Compliance review — Individual instruments can be submitted for compliance review independently of their counterparty.

---

Common workflow

1. POST /counterparty/{userId}/counterparties/{counterpartyId}/required-fields — fetch the exact fields required for the chosen instrument type.
2. POST /counterparty/{userId}/counterparties/{counterpartyId}/instrument — create the instrument with the returned fields.
3. PUT .../instrument/{instrumentId}/enable — activate the instrument.
4. Proceed to initiate a payment using the instrument.