Recipients

Recipients are payment destinations for your global transfers. Create once, use for multiple payments across traditional banking, mobile money networks, and cryptocurrency platforms.

Core Concepts

Term	Definition
Recipient	Payment destination with all required transfer details
Schema	Field template for payment method (bank_us, bank_sepa, etc.)
Channel	Complete payment config (rail + currency + fees + timing + schemas)
Financial Institution	Bank/provider selection required for some schemas

Payment Methods

Traditional Banking - ACH, SWIFT, SEPA, Faster Payments, local rails
Mobile Money - M-Pesa, MTN, Airtel, regional providers
Cryptocurrency - USDC/USDT on major networks (Ethereum, Polygon, etc.)

Get real-time channels: Use GET /channels for current fees, processing times, and availability

Get field requirements: Use GET /schemas for up-to-date field definitions

API Endpoints

Method	Endpoint	Purpose
POST	`/recipients`	Create new recipient
GET	`/recipients`	List recipients (optional: include deleted)
GET	`/recipients/{id}`	Get recipient details
DELETE	`/recipients/{id}`	Delete recipient

Create Recipients

Create a new recipient with the account details required for transfers.

POST /recipients

Request Parameters

Field	Type	Required	Description
`name`	string	✅	Legal name or business name
`details`	object	✅	Schema-specific payment details
`isExternal`	boolean	✅	Whether this is an external recipient (third-party account vs your own account)

The details object must include a schema field and conform to the specified payment schema. See Schemas for complete field definitions and validation rules.

US Bank Transfer

curl -X POST https://api.due.network/v1/recipients \
-H "Authorization: Bearer your_api_key" \
-H "Due-Account-Id: your_account_id" \
-H "Content-Type: application/json" \
-d '{
  "name": "John Smith",
  "details": {
    "schema": "bank_us",
    "bankName": "JPMorgan Chase Bank",
    "accountName": "John Smith", 
    "accountNumber": "123456789",
    "routingNumber": "021000021",
    "beneficiaryAddress": {
      "street_line_1": "123 Main Street",
      "city": "New York",
      "postal_code": "10001",
      "country": "USA",
      "state": "NY"
    }
  },
  "isExternal": true
}'

SEPA Transfer (Europe)

curl -X POST https://api.due.network/v1/recipients \
-H "Authorization: Bearer your_api_key" \
-H "Due-Account-Id: your_account_id" \
-H "Content-Type: application/json" \
-d '{
  "name": "Marie Dubois", 
  "details": {
    "schema": "bank_sepa",
    "accountType": "individual",
    "firstName": "Marie",
    "lastName": "Dubois",
    "IBAN": "FR1420041010050500013M02606"
  },
  "isExternal": true
}'

SWIFT Transfer (International)

curl -X POST https://api.due.network/v1/recipients \
-H "Authorization: Bearer your_api_key" \
-H "Due-Account-Id: your_account_id" \
-H "Content-Type: application/json" \
-d '{
  "name": "Singapore Tech Pte Ltd",
  "details": {
    "schema": "bank_swift",
    "accountType": "business", 
    "companyName": "Singapore Tech Pte Ltd",
    "bankName": "DBS Bank Ltd",
    "swiftCode": "DBSSSGSG",
    "accountNumber": "1234567890",
    "currency": "SGD"
  },
  "isExternal": true
}'

African Bank (with Institution Selection)

curl -X POST https://api.due.network/v1/recipients \
-H "Authorization: Bearer your_api_key" \
-H "Due-Account-Id: your_account_id" \
-H "Content-Type: application/json" \
-d '{
  "name": "Adebayo Okafor",
  "details": {
    "schema": "bank_africa",
    "financialInstitutionId": "access_bank_ng",
    "accountNumber": "0123456789",
    "accountName": "Adebayo Okafor"
  },
  "isExternal": true
}'

Cryptocurrency

curl -X POST https://api.due.network/v1/recipients \
-H "Authorization: Bearer your_api_key" \
-H "Due-Account-Id: your_account_id" \
-H "Content-Type: application/json" \
-d '{
  "name": "Alex Thompson", 
  "details": {
    "schema": "evm",
    "address": "0x742d35Cc6665C6c175E8c7CaB7CeEf5634123456"
  },
  "isExternal": false
}'

Success Response

{
  "id": "recipient_1234567890abcdef",
  "label": "John Smith",
  "details": {
    "schema": "bank_us",
    "bankName": "JPMorgan Chase Bank",
    "accountName": "John Smith",
    "accountNumber": "123456789", 
    "routingNumber": "021000021",
    "beneficiaryAddress": {
      "street_line_1": "123 Main Street",
      "city": "New York",
      "postal_code": "10001",
      "country": "USA",
      "state": "NY"
    }
  },
  "isExternal": true,
  "isActive": true
}

List Recipients

# All active recipients
curl -H "Authorization: Bearer your_api_key" \
-H "Due-Account-Id: your_account_id" \
https://api.due.network/v1/recipients

# Include deleted recipients  
curl -H "Authorization: Bearer your_api_key" \
-H "Due-Account-Id: your_account_id" \
"https://api.due.network/v1/recipients?with_deleted=true"

Get Single Recipient

curl -H "Authorization: Bearer your_api_key" \
-H "Due-Account-Id: your_account_id" \
https://api.due.network/v1/recipients/{recipient_id}

Delete Recipient

curl -X DELETE \
-H "Authorization: Bearer your_api_key" \
-H "Due-Account-Id: your_account_id" \
https://api.due.network/v1/recipients/{recipient_id}

Validation Errors

When recipient creation fails due to invalid data, you'll receive a structured validation error:

Error Response (422 Unprocessable Entity):

{
  "statusCode": 422,
  "message": "Validation error",
  "code": "err_validation", 
  "details": {
    "routingNumber": "required",
    "beneficiaryAddress.street_line_1": "required"
  }
}

The details object maps field paths to the specific validation rule that failed. For complete validation rules and field requirements, see Schema.

Duplicate Prevention

Recipients are automatically deduplicated based on their account details. If you attempt to create a recipient with identical account information to an existing recipient, you'll receive an error:

Error Response (400 Bad Request):

{
  "statusCode": 400,
  "message": "Recipient already exists", 
  "code": "err_recipient_already_exists"
}

Financial Institution Selection

Some payment schemas require selecting a specific bank or provider before creating the recipient. For schemas like bank_africa, momo_africa, and bank_colombia, you must:

Get available institutions for the country and schema
Present options to your user
Include the selected financialInstitutionId in the recipient details

For complete workflows and available institutions, see Financial Institutions.

Important Notes

Schema Requirements: Each payment method has specific required fields. Use /schemas endpoint or see Schemas for current requirements
Deletion: Recipients with pending payments cannot be deleted
Updates: Recipient details cannot be modified after creation (delete and recreate instead)