Description

Purpose and use

Recipients represent trusted payment destinations that can be reused when creating transfers. They hold beneficiary details, destination instruments, validation state, and search metadata so payment operations do not re-key the same beneficiary information each time.

Who uses this. Payment operations, customer support, relationship managers, and customers through client channels use recipients when selecting where money should be sent.

How it works. A recipient can represent a bank account, crypto wallet, or another supported destination. Validation checks such as BIC format, country, instrument type, and customer access determine whether the recipient can be used in a transfer flow.

What users do. Users create or search recipients, review saved bank or crypto details, update stale metadata, and choose a recipient as the destination for a transfer.

Outcomes and side effects. A valid recipient shortens transfer creation, improves beneficiary audit history, and reduces payment errors. Recipient changes can affect future transfers but do not change historical payment records.

Related manuals: Counterparties, Transfers, Accounts & Portfolios, KYT.

Overview

The Recipients API provides functionality for managing payment recipients, including:

• Business and personal recipients
• Bank account details management
• Intermediate bank information
• IBAN and BIC validation
• Recipient search and filtering

Core Concepts

Recipient Types

• business: For business/corporate recipients
• personal: For individual recipients

BIC Validation

All BIC codes must match the standard format:

• 8 or 11 characters total length
• First 4 characters: Bank code (letters)
• Next 2 characters: Country code (letters)
• Next 2 characters: Location code (letters/numbers)
• Last 3 characters: Branch code (optional, letters/numbers)

Endpoints

Create Recipient

POST /v1/customers/{customer_id}/recipients

Create a new payment recipient.

For v2 recipient create payloads, each bank_accounts item may include active and is_validated. Both fields default to true when omitted; explicit false values are preserved.

Request Body:

{
  "iban": "CH9300762011623852957",
  "legal_name": "Acme Corp",
  "country": "CH",
  "city": "Zurich",
  "legal_address": "Bahnhofstrasse 1",
  "bic": "UBSWCHZH80A",
  "bank": "UBS Switzerland AG",
  "type": "business",
  "intermediate_bic": "CRESCHZZ80A",
  "intermediate_bank": "Credit Suisse AG",
  "intermediate_route": "Direct",
  "email": "payments@acme.com",
  "phone": "+41441234567",
  "reference": "SUPPLIER-123"
}

Get All Recipients

GET /v1/recipients

Retrieve all recipients with optional filtering (you may pass customer_id as a query parameter if needed).

Query Parameters:

• limit: Maximum number of records (default: 20)
• offset: Number of records to skip
• type: Filter by recipient type
• country: Filter by country
• search: Search in legal name and reference

Response:

{
  "recipients": [
    {
      "id": "uuid",
      "iban": "string",
      "legal_name": "string",
      "country": "string",
      "city": "string",
      "legal_address": "string",
      "bic": "string",
      "bank": "string",
      "type": "business|personal",
      "intermediate_bic": "string",
      "intermediate_bank": "string",
      "intermediate_route": "string",
      "email": "string",
      "phone": "string",
      "reference": "string",
      "customer_id": "uuid"
    }
  ],
  "total": 0,
  "has_more": false
}

Get Recipient

GET /v1/recipients/{id}

Retrieve a specific recipient by ID.

Update Recipient

PUT /v1/recipients/{id}

Update an existing recipient.

Delete Recipient

DELETE /v1/recipients/{id}

Delete a recipient.

Search Recipient

POST /v1/recipients/search

Search for a recipient using a prioritized criteria order:

1. By IBAN and customer_id (highest priority)
2. By legal name + email and customer_id (when IBAN search returns no results)

Optional flags (default false; invoice OCR enables both server-side):

• allow_legal_name_fallback — when IBAN and legal_name+email miss, match an existing recipient by legal name only. Can merge unrelated payees that share a name; use only when the caller accepts that risk.
• attach_missing_iban — when a recipient is matched, add the search IBAN if it is not already stored on that profile.

If no recipient is found and create_when_404 is set to true, a new recipient will be created using the provided fields. This requires at minimum the IBAN and legal_name fields.

When creating a new recipient through this endpoint, if no type is specified, it defaults to "business".

Request Body:

{
  "customer_id": "uuid",              // Required
  "iban": "CH9300762011623852957",    // 1st priority search
  "legal_name": "Acme Corp",          // 2nd priority - used with email
  "email": "payments@acme.com",       // 2nd priority - used with legal_name
  "create_when_404": true,            // Optional, default: false - If true, creates a recipient when not found
  "allow_legal_name_fallback": false,   // Optional, default: false - legal-name-only match when IBAN + email miss
  "attach_missing_iban": false,       // Optional, default: false - add search IBAN to matched recipient
  
  // The following fields are only used when create_when_404=true
  "street": "Bahnhofstrasse 1",       // Used for creation
  "city": "Zurich",                   // Used for creation 
  "country": "CH",                    // Used for creation
  "bic": "UBSWCHZH80A",               // Optional for creation
  "bank": "UBS Switzerland AG",        // Optional for creation
  // ... other recipient fields can be included for creation
}

Response: Returns the recipient object if found using any of the search criteria or if a new one was created. Returns 404 if no recipient is found and create_when_404 is false.

Error Codes