Read the following guides before proceeding:
Recipients are saved destinations for outbound transfers. Each recipient contains:
- Personal Info — Name (personal or business) and optional nickname
- Payment Details — One or more payment methods (Card, Sepa, Ach, Crypto, etc.)
Recipients are user-scoped — each user manages their own recipients.
| Type | Description | Required Fields |
|---|
Card | External payment card | card_id, card_pan_last |
Sepa | EUR bank account | iban, bic |
Ach | USD bank account | routing_number, account_number, legal_address |
Crypto | Blockchain address | address, network |
FasterPayment | GBP bank account | account_number, sort_code |
Swift | International wire | iban, bic, legal_address |
Retrieve all recipients for the authenticated user.
GET /api/v1/recipients
| Parameter | Type | Required | Description |
|---|
page_number | integer | No | Page number (default: 0) |
page_size | integer | No | Results per page (default: 25) |
{
"items": [
{
"id": "77fc49bd-1d7d-41d9-beea-a0aee0dc8c35",
"personal_info": {
"first_name": "Alex",
"last_name": "Grey",
"is_business": false
},
"payment_details": [
{
"id": "c34908da-d980-4a9c-9b39-4dabd6f6144e",
"type": "Card",
"currencies": ["EUR", "USD"],
"card": {
"card_id": "tok_a1b2c3d4e5f6789012345678",
"card_pan_last": "4242"
}
},
{
"id": "d45019eb-e091-5b0d-0c4a-5ebce7255f0f",
"type": "Sepa",
"currencies": ["EUR"],
"sepa": {
"iban": "DE89370400440532013000",
"bic": "COBADEFFXXX"
}
}
]
}
],
"total_count": 1,
"page_number": 0,
"page_size": 25
}
Retrieve a specific recipient by ID.
GET /api/v1/recipients/{recipient_id}
| Parameter | Type | Required | Description |
|---|
recipient_id | string (UUID) | Yes | Recipient identifier |
{
"id": "77fc49bd-1d7d-41d9-beea-a0aee0dc8c35",
"personal_info": {
"first_name": "Alex",
"last_name": "Grey",
"is_business": false
},
"payment_details": [
{
"id": "c34908da-d980-4a9c-9b39-4dabd6f6144e",
"type": "Card",
"currencies": ["EUR", "USD"],
"card": {
"card_id": "tok_a1b2c3d4e5f6789012345678",
"card_pan_last": "4242"
}
}
]
}
Filter recipients that have a specific payment detail type.
GET /api/v1/recipients/filter/type?type=Card
| Parameter | Type | Required | Description |
|---|
type | string | Yes | Payment type: Card, Sepa, Ach, Crypto, etc. |
Filter recipients that accept a specific currency.
GET /api/v1/recipients/filter/currency?currency=EUR
| Parameter | Type | Required | Description |
|---|
currency | string | Yes | Currency code (EUR, USD, GBP, etc.) |
Search recipients by name.
GET /api/v1/recipients/filter/name?name=Alex
| Parameter | Type | Required | Description |
|---|
name | string | Yes | Search term (matches first_name, last_name, company_name, nick_name) |
| Field | Type | Description |
|---|
id | string (UUID) | Recipient identifier |
personal_info | object | Recipient's personal or business info |
payment_details | array | List of payment methods |
| Field | Type | Description |
|---|
first_name | string | First name (personal recipients) |
last_name | string | Last name (personal recipients) |
company_name | string | Company name (business recipients) |
is_business | boolean | true for business, false for personal |
nick_name | string | Optional display name |
| Field | Type | Description |
|---|
id | string (UUID) | Payment details identifier (used as external_card_id for Card type) |
type | string | Payment type |
currencies | string[] | Supported currencies |
card | object | Card details (when type is Card) |
sepa | object | SEPA details (when type is Sepa) |
ach | object | ACH details (when type is Ach) |
crypto | object | Crypto details (when type is Crypto) |
| Error Reason | Description |
|---|
ErrorNotFound | Recipient not found or not owned by user |
ErrorInvalidField | Invalid UUID format for recipient_id |
