Description

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.

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