Recipients Overview

Before You Start

Read the following guides before proceeding:

Guide	Why
Getting Started	Platform overview and setup
Api Basics	Required headers and request configuration
Authentication	How to obtain access tokens
Onboarding	User and wallet registration

Overview

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.

Payment Detail Types

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`

List Recipients

Retrieve all recipients for the authenticated user.

Endpoint

GET /api/v1/recipients

Query Parameters

Parameter	Type	Required	Description
`page_number`	integer	No	Page number (default: 0)
`page_size`	integer	No	Results per page (default: 25)

Response

{
  "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
}

Get Recipient by ID

Retrieve a specific recipient by ID.

Endpoint

GET /api/v1/recipients/{recipient_id}

Path Parameters

Parameter	Type	Required	Description
`recipient_id`	string (UUID)	Yes	Recipient identifier

Response

{
  "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

By Payment Type

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.

By Currency

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.)

By Name

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)

Response Fields

Recipient

Field	Type	Description
`id`	string (UUID)	Recipient identifier
`personal_info`	object	Recipient's personal or business info
`payment_details`	array	List of payment methods

Personal Info

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

Payment Details

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 Handling

Error Reason	Description
`ErrorNotFound`	Recipient not found or not owned by user
`ErrorInvalidField`	Invalid UUID format for recipient_id