Counterparties

A counterparty is a saved recipient on a bank account: the beneficiary of fiat payments and local payouts.

Every counterparty needs iban, recipient, country, address_line1, city, postal_code and kind. Some destination countries need more:

Country	Also required
China (`CN`)	`supported_rails` (`CIPS` or `SWIFT`), `institution_name`, `swift`, `state`
United Arab Emirates (`AE`)	`supported_rails` (`UAEFTS00` or `SWIFT`), `swift`, `state`
Colombia (`CO`)	`institution_name`, `national_identification_number`, `phone_number`, `account_type`, `state`
United States (`US`)	`routing_number`, `state` (two-letter code), `supported_rails`, `institution_name`
Mexico (`MX`)	`state`

A 422 response lists every field that's missing or invalid, one error per field.

List counterparties

GET/accounts/{account_id}/bank_accounts/{bank_account_id}/counterparties

Returns the counterparties saved on a bank account, newest first.

Authorization

BearerAuth

AuthorizationBearer <token>

Token from POST /sign_in, sent as Authorization: Bearer <token>.

In: header

Path Parameters

account_id*string

ID of the account.

Formatuuid

bank_account_id*string

ID of the bank account.

Formatuuid

`application/json`

curl -X GET "https://example.com/accounts/8f3a2c1e-5b7d-4e9a-9c21-7d4b6e0f1a23/bank_accounts/6d1c9e2a-3f4b-4c8d-a7e6-5b2f0e9d1c47/counterparties"

{  "data": [    {      "id": "1a6e3b9d-8c2f-4d7a-b5e1-3f9c0a7d2b64",      "iban": "DE89370400440532013000",      "description": "Supplier – office equipment",      "recipient": "Müller Bürobedarf GmbH",      "alias": "Müller",      "external_id": "SUP-0042",      "currency": "EUR",      "kind": "Business",      "address_line1": "Friedrichstraße 123",      "city": "Berlin",      "postal_code": "10117",      "country": "DE",      "state": "BE",      "favourite": true,      "status": null,      "amount": 0,      "relationship_to_customer": "supplier",      "supported_rails": [        "SWIFT"      ],      "preferred_rail": "SWIFT",      "institution_name": "Deutsche Bank",      "routing_number": null,      "swift": "DEUTDEFF",      "national_identification_number": null,      "date_of_birth": null,      "nationality": null,      "phone_number": null,      "email": "accounts@mueller.example",      "account_type": null    }  ]}

Create a counterparty

POST/accounts/{account_id}/bank_accounts/{bank_account_id}/counterparties

Saves a payment recipient on a bank account. Besides the base fields, some destination countries need extra fields (see the table above). A 422 lists every missing or invalid field, one error each.

Authorization

BearerAuth

AuthorizationBearer <token>

Token from POST /sign_in, sent as Authorization: Bearer <token>.

In: header

Path Parameters

account_id*string

ID of the account.

Formatuuid

bank_account_id*string

ID of the bank account.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

A payment recipient. iban, recipient, country, address_line1, city, postal_code and kind are always required; see the table above for the extra fields each destination country needs.

iban*string

IBAN of the recipient, or the local account number in countries without IBANs.

amount?number

Default amount to save with the counterparty.

Formatfloat

Default0

description?string

Your note about the counterparty.

recipient*string

Name of the recipient (person or company).

alias?string

Short name for the counterparty. Only used when favourite is true.

favourite?boolean

Whether to mark the counterparty as a favourite.

city*string

City of the recipient's address.

address_line1*string

Street address of the recipient.

country*string

Two-letter country code as defined in ISO 3166-1 alpha-2 standard (e.g., ES for Spain, US for United States).

Match^[A-Z]{2}$

Lengthlength <= 2

postal_code*string

Postal code of the recipient's address.

currency?string

Currency the recipient is paid in.

Default"EUR"

kind*string

Whether the recipient is a person or a business.

Value in

"Person"
"Business"

supported_rails?array<>

Rails the recipient can be paid on: FEDWIRE, SWIFT, ACH, CIPS or UAEFTS00. Required for USD recipients and for China and the UAE.

preferred_rail?string

Rail to use when the recipient supports several.

institution_name?string

Name of the recipient's bank. Required for China and the United States, and for Colombian payouts, where it must be one of: COINK SA, BANCO DE BOGOTA, BANCO POPULAR, BANCOLOMBIA, CITIBANK, BANCO GNB SUDAMERIS, BANCO BBVA, ITAÚ CORPBANCA COLOMBIA S.A, BANCO COLPATRIA (Scotiabank), BANCO DE OCCIDENTE, BANCOLDEX, BANCO CAJA SOCIAL, BANCO AGRARIO, BANCO DAVIVIENDA, AV VILLAS, BANCO PICHINCHA, BANCO COOMEVA, BANCO FALABELLA, BANCO SANTANDER DE NEGOCIOS COL., BANCO COOPERATIVO COOPCENTRAL, CONFIAR S.A., COLTEFINANCIERA S.A., NEQUI, BANCO W S.A., DAVIPLATA, LULO BANK, BANCO ITAÚ, BANCAMIA S.A., BANCO SERFINANZA, BANCO UNION, BANCIEN, BANCO JP MORGAN, IRIS, MOVII SA, DING TECNIPAGOS SA, POWWI, UALA, BANCO BTG PACTUAL COLOMBIA S.A., PIBANK, RAPPIPAY, BANCO MUNDO MUJER, GLOBAL66, NU, JFK Cooperativa Financiera, BOLD CF, Banco Contactar S.A.

routing_number?string

ABA routing number. Required for US recipients.

swift?string

SWIFT/BIC code of the recipient's bank. Required for China and the UAE.

state?string

State or province. Required for the US (two-letter code), Colombia, Mexico, China and the UAE.

phone_number?string

Phone number with country code. MANDATORY for CO counterparties. Not required for MX.

national_identification_number?string

National ID number (Cédula or NIT). Required for Colombia.

account_type?string

Type of bank account. Required for Colombia.

Value in

"savings"
"checking"

relationship_to_customer?string

How the recipient relates to your customer.

date_of_birth?string

Date of birth of a recipient person (YYYY-MM-DD).

nationality?string

Nationality of a recipient person (ISO 3166-1 alpha-2).

email?string

Email address of the recipient.

Response Body

`application/json`

curl -X POST "https://example.com/accounts/8f3a2c1e-5b7d-4e9a-9c21-7d4b6e0f1a23/bank_accounts/6d1c9e2a-3f4b-4c8d-a7e6-5b2f0e9d1c47/counterparties" \  -H "Content-Type: application/json" \  -d '{    "kind": "Business",    "recipient": "Müller Bürobedarf GmbH",    "iban": "DE89370400440532013000",    "address_line1": "Friedrichstraße 123",    "city": "Berlin",    "postal_code": "10117",    "country": "DE",    "currency": "EUR",    "favourite": true,    "alias": "Müller"  }'

{  "data": {    "id": "1a6e3b9d-8c2f-4d7a-b5e1-3f9c0a7d2b64",    "iban": "DE89370400440532013000",    "description": "Supplier – office equipment",    "recipient": "Müller Bürobedarf GmbH",    "alias": "Müller",    "external_id": "SUP-0042",    "currency": "EUR",    "kind": "Business",    "address_line1": "Friedrichstraße 123",    "city": "Berlin",    "postal_code": "10117",    "country": "DE",    "state": "BE",    "favourite": true,    "status": null,    "amount": 0,    "relationship_to_customer": "supplier",    "supported_rails": [      "SWIFT"    ],    "preferred_rail": "SWIFT",    "institution_name": "Deutsche Bank",    "routing_number": null,    "swift": "DEUTDEFF",    "national_identification_number": null,    "date_of_birth": null,    "nationality": null,    "phone_number": null,    "email": "accounts@mueller.example",    "account_type": null  }}

Update a counterparty

PATCH/accounts/{account_id}/bank_accounts/{bank_account_id}/counterparties/{id}

Changes a saved counterparty. Send only the fields you want to change.

Authorization

BearerAuth

AuthorizationBearer <token>

Token from POST /sign_in, sent as Authorization: Bearer <token>.

In: header

Path Parameters

account_id*string

ID of the account.

Formatuuid

bank_account_id*string

ID of the bank account.

Formatuuid

id*string

ID of the counterparty.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Send only the fields you want to change.

iban?string

IBAN of the counterparty

amount?number

Amount associated with the counterparty

Formatfloat

description?string

Description of the counterparty

recipient?string

Name of the recipient

alias?string

Alias for the counterparty (only used if favourite is true)

favourite?boolean

Whether to mark the counterparty as favourite

city?string

City of the counterparty

address_line1?string

First line of the address

country?string

Two-letter country code as defined in ISO 3166-1 alpha-2 standard (e.g., ES for Spain, US for United States).

Match^[A-Z]{2}$

Lengthlength <= 2

postal_code?string

Postal code of the counterparty

currency?string

Currency of the counterparty

kind?string

Type of counterparty

supported_rails?array<>

Rails the recipient can be paid on: FEDWIRE, SWIFT, ACH, CIPS or UAEFTS00.

preferred_rail?string

Preferred payment rail.

institution_name?string

Name of the financial institution.

routing_number?string

Routing number (for US accounts)

swift?string

SWIFT/BIC code.

state?string

State or province.

phone_number?string

Phone number with country code.

national_identification_number?string

National identification number (Cédula/NIT).

account_type?string

Bank account type.

Value in

"savings"
"checking"

relationship_to_customer?string

Relationship of the counterparty to the customer

date_of_birth?string

Date of birth (YYYY-MM-DD)

nationality?string

Two-letter nationality code

email?string

Email address of the counterparty

Response Body

`application/json`

curl -X PATCH "https://example.com/accounts/8f3a2c1e-5b7d-4e9a-9c21-7d4b6e0f1a23/bank_accounts/6d1c9e2a-3f4b-4c8d-a7e6-5b2f0e9d1c47/counterparties/1a6e3b9d-8c2f-4d7a-b5e1-3f9c0a7d2b64" \  -H "Content-Type: application/json" \  -d '{    "favourite": true,    "alias": "Müller"  }'

{  "data": {    "id": "1a6e3b9d-8c2f-4d7a-b5e1-3f9c0a7d2b64",    "iban": "DE89370400440532013000",    "description": "Supplier – office equipment",    "recipient": "Müller Bürobedarf GmbH",    "alias": "Müller",    "external_id": "SUP-0042",    "currency": "EUR",    "kind": "Business",    "address_line1": "Friedrichstraße 123",    "city": "Berlin",    "postal_code": "10117",    "country": "DE",    "state": "BE",    "favourite": true,    "status": null,    "amount": 0,    "relationship_to_customer": "supplier",    "supported_rails": [      "SWIFT"    ],    "preferred_rail": "SWIFT",    "institution_name": "Deutsche Bank",    "routing_number": null,    "swift": "DEUTDEFF",    "national_identification_number": null,    "date_of_birth": null,    "nationality": null,    "phone_number": null,    "email": "accounts@mueller.example",    "account_type": null  }}

Delete a counterparty

DELETE/accounts/{account_id}/bank_accounts/{bank_account_id}/counterparties/{id}

Deletes a saved counterparty. Payments already made to it aren't affected.

Authorization

BearerAuth

AuthorizationBearer <token>

Token from POST /sign_in, sent as Authorization: Bearer <token>.

In: header

Path Parameters

account_id*string

ID of the account.

Formatuuid

bank_account_id*string

ID of the bank account.

Formatuuid

id*string

ID of the counterparty.

Formatuuid

Response Body

`application/json`

curl -X DELETE "https://example.com/accounts/8f3a2c1e-5b7d-4e9a-9c21-7d4b6e0f1a23/bank_accounts/6d1c9e2a-3f4b-4c8d-a7e6-5b2f0e9d1c47/counterparties/1a6e3b9d-8c2f-4d7a-b5e1-3f9c0a7d2b64"

{  "status": 200}

List counterpartiesCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

401application/json

404application/json

Create a counterpartyCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

201application/json

401application/json

404application/json

422application/json

Update a counterpartyCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

401application/json

404application/json

422application/json

Delete a counterpartyCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

401application/json

404application/json

List counterparties

Authorization

Path Parameters

Response Body

`application/json`

`application/json`

`application/json`

Create a counterparty

Authorization

Path Parameters

Request Body

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

Update a counterparty

Authorization

Path Parameters

Request Body

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

Delete a counterparty

Authorization

Path Parameters

Response Body

`application/json`

`application/json`

`application/json`