Create Recipients

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

Use the v2 endpoint to create a recipient with personal info and payment details in a single call.

Create Recipient

Endpoint

POST /api/v2/recipients

Request Structure

{
  "first_name": "string",
  "last_name": "string",
  "company_name": "string",
  "is_business": false,
  "nick_name": "string",
  "type": "Card",
  "currencies": ["EUR", "USD"],
  "card": { ... },
  "sepa": { ... },
  "ach": { ... },
  "crypto": { ... }
}

Common Fields

Field	Type	Required	Description
`first_name`	string	Yes*	First name (personal recipients)
`last_name`	string	Yes*	Last name (personal recipients)
`company_name`	string	Yes*	Company name (business recipients)
`is_business`	boolean	Yes	`false` for personal, `true` for business
`nick_name`	string	No	Optional display name (max 127 characters)
`type`	string	Yes	Payment type: `Card`, `Sepa`, `Ach`, `Crypto`, etc.
`currencies`	string[]	Yes	Currencies the recipient can accept

*Provide either first_name + last_name for personal recipients, or company_name for business recipients. For Crypto type with a nickname, personal info can be omitted.

Payment Type: Card

For push to card transfers. Requires prior card tokenization via PCI environment.

{
  "first_name": "Alex",
  "last_name": "Grey",
  "is_business": false,
  "type": "Card",
  "currencies": ["EUR", "USD", "GBP"],
  "card": {
    "card_id": "tok_a1b2c3d4e5f6789012345678",
    "card_pan_last": "4242"
  }
}

Field	Type	Required	Description
`card.card_id`	string	Yes	Card token from PCI tokenization
`card.card_pan_last`	string	Yes	Last 4 digits of card number

Payment Type: Sepa

For EUR bank transfers within SEPA zone.

{
  "first_name": "Alex",
  "last_name": "Grey",
  "is_business": false,
  "type": "Sepa",
  "currencies": ["EUR"],
  "sepa": {
    "iban": "DE89370400440532013000",
    "bic": "COBADEFFXXX"
  }
}

Field	Type	Required	Description
`sepa.iban`	string	Yes	IBAN (International Bank Account Number)
`sepa.bic`	string	Yes	BIC/SWIFT code

Payment Type: Ach

For USD bank transfers within the US.

{
  "first_name": "Alex",
  "last_name": "Grey",
  "is_business": false,
  "type": "Ach",
  "currencies": ["USD"],
  "ach": {
    "routing_number": "021000021",
    "account_number": "123456789",
    "bank_name": "JPMorgan Chase",
    "legal_address": {
      "country": "US",
      "city": "New York",
      "zip_code": "10001",
      "line1": "123 Main Street",
      "state": "NY"
    }
  }
}

Field	Type	Required	Description
`ach.routing_number`	string	Yes	ABA routing number (9 digits)
`ach.account_number`	string	Yes	Bank account number
`ach.bank_name`	string	No	Bank name
`ach.legal_address`	object	Yes	Recipient's legal address

Legal Address

Field	Type	Required	Description
`country`	string	Yes	Country code (e.g., "US")
`city`	string	Yes	City name
`zip_code`	string	Yes	Postal code
`line1`	string	Yes	Street address
`line2`	string	No	Additional address info
`state`	string	No	State/province code

Payment Type: Crypto

For blockchain transfers.

{
  "nick_name": "My ETH Wallet",
  "is_business": false,
  "type": "Crypto",
  "currencies": ["USDC", "USDT"],
  "crypto": {
    "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "network": "Base"
  }
}

Field	Type	Required	Description
`crypto.address`	string	Yes	Blockchain wallet address
`crypto.network`	string	Yes	Network name (e.g., "Base", "Ethereum")

Note: For Crypto recipients, nick_name can replace personal info (first_name/last_name).

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", "GBP"],
      "card": {
        "card_id": "tok_a1b2c3d4e5f6789012345678",
        "card_pan_last": "4242"
      }
    }
  ]
}

The payment_details[].id is used as the identifier when initiating transfers (e.g., external_card_id for push to card).

Add Payment Details to Existing Recipient

Add additional payment methods to an existing recipient.

Endpoint

POST /api/v1/recipients/{recipient_id}/payment_details

Request

{
  "type": "Sepa",
  "currencies": ["EUR"],
  "sepa": {
    "iban": "DE89370400440532013000",
    "bic": "COBADEFFXXX"
  }
}

Response

{
  "id": "d45019eb-e091-5b0d-0c4a-5ebce7255f0f"
}

Error Handling

Validation Errors

Error Reason	Field	Description
`ErrorMissingField`	`first_name`	First name required for personal recipients
`ErrorMissingField`	`last_name`	Last name required for personal recipients
`ErrorMissingField`	`company_name`	Company name required for business recipients
`ErrorMissingField`	`type`	Payment type is required
`ErrorMissingField`	`currencies`	At least one currency required
`ErrorMissingField`	`card`	Card details required when type is Card
`ErrorMissingField`	`card.card_id`	Card token is required
`ErrorMissingField`	`card.card_pan_last`	Last 4 digits required
`ErrorInvalidField`	`card.card_pan_last`	Must be exactly 4 digits
`ErrorMissingField`	`sepa.iban`	IBAN is required
`ErrorMissingField`	`sepa.bic`	BIC is required
`ErrorInvalidField`	`sepa.iban`	Invalid IBAN format
`ErrorInvalidField`	`sepa.bic`	Invalid BIC format
`ErrorMissingField`	`ach.routing_number`	Routing number is required
`ErrorMissingField`	`ach.account_number`	Account number is required
`ErrorMissingField`	`ach.legal_address`	Legal address is required for ACH

Error Response Format

{
  "error_reason": "ErrorMissingField",
  "error_description": "first name is required",
  "error_category": {
    "category": "CategoryValidationFailure",
    "http_status_code": 400
  },
  "error_details": [
    {
      "key": "field",
      "details": "first_name"
    },
    {
      "key": "issue",
      "details": "missing"
    }
  ]
}