Recipients

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

Base URL
https://api.due.network/v1

Authentication required: Include your API key in Authorization header and account ID in Due-Account-Id header.

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
`GET`	`/channels`	Available payment channels
`GET`	`/schemas`	All schema field definitions
`GET`	`/financial_institutions/{country}/{schema}`	Banks/providers for selection

1️⃣ Create Recipients

POST /v1/recipients
Authorization: Bearer {api_key}
Due-Account-Id: {account_id}
Content-Type: application/json

Core Fields

Field	Type	Required	Description
`id`	string	✅	Your unique recipient identifier
`country`	string	✅	ISO 3166-1 alpha-2 country code
`name`	string	✅	Legal name or business name
`email`	string	✅	Recipient email
`details`	object	✅	Schema-specific payment details
`isExternal`	boolean		External recipient flag (default: false)
`isActive`	boolean		Active status (default: true)

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 '{
    "id": "emp_john_001",
    "country": "US",
    "name": "John Smith",
    "email": "[email protected]",
    "details": {
      "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"
      }
    }
  }'

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 '{
    "id": "contractor_marie_fr",
    "country": "FR",
    "name": "Marie Dubois",
    "email": "[email protected]",
    "details": {
      "accountType": "individual",
      "firstName": "Marie",
      "lastName": "Dubois",
      "IBAN": "FR1420041010050500013M02606"
    }
  }'

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 '{
    "id": "supplier_sg_001",
    "country": "SG",
    "name": "Singapore Tech Pte Ltd",
    "email": "[email protected]",
    "details": {
      "accountType": "business",
      "companyName": "Singapore Tech Pte Ltd",
      "bankName": "DBS Bank Ltd",
      "swiftCode": "DBSSSGSG",
      "accountNumber": "1234567890",
      "currency": "SGD"
    }
  }'

African Bank (with Institution Selection)

Step 1: Get available banks

curl -H "Authorization: Bearer your_api_key" \
  -H "Due-Account-Id: your_account_id" \
  https://api.due.network/v1/financial_institutions/NG/bank_africa

Step 2: Create recipient

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 '{
    "id": "vendor_ng_001",
    "country": "NG",
    "name": "Adebayo Okafor",
    "email": "[email protected]",
    "details": {
      "financialInstitutionId": "access_bank_ng",
      "accountNumber": "0123456789",
      "accountName": "Adebayo Okafor"
    }
  }'

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 '{
    "id": "trader_eth_001",
    "country": "US",
    "name": "Alex Thompson",
    "email": "[email protected]",
    "details": {
      "address": "0x742d35Cc6665C6c175E8c7CaB7CeEf5634123456"
    }
  }'

2️⃣ 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"

3️⃣ Get Single Recipient

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

4️⃣ Delete Recipient

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

5️⃣ Get Schemas & Channels

Get All Schema Definitions

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

Get Available Channels

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

Get Financial Institutions

# Nigerian banks
curl -H "Authorization: Bearer your_api_key" \
  -H "Due-Account-Id: your_account_id" \
  https://api.due.network/v1/financial_institutions/NG/bank_africa

# Kenyan mobile money providers
curl -H "Authorization: Bearer your_api_key" \
  -H "Due-Account-Id: your_account_id" \
  https://api.due.network/v1/financial_institutions/KE/momo_africa

💻 Python SDK

import requests

class DueRecipientsAPI:
    def __init__(self, api_key: str, account_id: str):
        self.base_url = "https://api.due.network/v1"
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Due-Account-Id": account_id,
            "Content-Type": "application/json"
        }
    
    def create_recipient(self, recipient_data: dict) -> dict:
        response = requests.post(f"{self.base_url}/recipients", 
                               headers=self.headers, json=recipient_data)
        response.raise_for_status()
        return response.json()
    
    def list_recipients(self, with_deleted: bool = False) -> dict:
        params = {"with_deleted": with_deleted} if with_deleted else {}
        response = requests.get(f"{self.base_url}/recipients", 
                              headers=self.headers, params=params)
        return response.json()
    
    def get_recipient(self, recipient_id: str) -> dict:
        response = requests.get(f"{self.base_url}/recipients/{recipient_id}", 
                              headers=self.headers)
        return response.json()
    
    def delete_recipient(self, recipient_id: str) -> dict:
        response = requests.delete(f"{self.base_url}/recipients/{recipient_id}", 
                                 headers=self.headers)
        return response.json()
    
    def get_schemas(self) -> list:
        response = requests.get(f"{self.base_url}/schemas", headers=self.headers)
        return response.json()
    
    def get_channels(self) -> list:
        response = requests.get(f"{self.base_url}/channels", headers=self.headers)
        return response.json()
    
    def get_financial_institutions(self, country: str, schema: str) -> list:
        response = requests.get(f"{self.base_url}/financial_institutions/{country}/{schema}", 
                              headers=self.headers)
        return response.json()

# Usage
api = DueRecipientsAPI("your_api_key", "your_account_id")

# Create US bank recipient
us_recipient = api.create_recipient({
    "id": "emp_sarah_001",
    "country": "US",
    "name": "Sarah Johnson", 
    "email": "[email protected]",
    "details": {
        "bankName": "Bank of America",
        "accountName": "Sarah Johnson",
        "accountNumber": "987654321",
        "routingNumber": "021000021",
        "beneficiaryAddress": {
            "street_line_1": "456 Oak St",
            "city": "Los Angeles",
            "state": "CA",
            "postal_code": "90210",
            "country": "USA"
        }
    }
})

# Get available schemas
schemas = api.get_schemas()
bank_schemas = [s for s in schemas if s['category'] == 'bank']
print(f"Available bank schemas: {[s['id'] for s in bank_schemas]}")

# Get Nigerian banks for institution selection
ng_banks = api.get_financial_institutions("NG", "bank_africa")
print(f"Nigerian banks: {[b['name'] for b in ng_banks]}")

📱 JavaScript SDK

class DueRecipientsAPI {
    constructor(apiKey, accountId) {
        this.baseURL = 'https://api.due.network/v1';
        this.headers = {
            'Authorization': `Bearer ${apiKey}`,
            'Due-Account-Id': accountId,
            'Content-Type': 'application/json'
        };
    }

    async createRecipient(recipientData) {
        const response = await fetch(`${this.baseURL}/recipients`, {
            method: 'POST',
            headers: this.headers,
            body: JSON.stringify(recipientData)
        });
        return response.json();
    }

    async listRecipients(withDeleted = false) {
        const params = withDeleted ? '?with_deleted=true' : '';
        const response = await fetch(`${this.baseURL}/recipients${params}`, {
            headers: this.headers
        });
        return response.json();
    }

    async getSchemas() {
        const response = await fetch(`${this.baseURL}/schemas`, {
            headers: this.headers
        });
        return response.json();
    }

    async getChannels() {
        const response = await fetch(`${this.baseURL}/channels`, {
            headers: this.headers
        });
        return response.json();
    }

    async getFinancialInstitutions(country, schema) {
        const response = await fetch(
            `${this.baseURL}/financial_institutions/${country}/${schema}`,
            { headers: this.headers }
        );
        return response.json();
    }
}

// Usage
const api = new DueRecipientsAPI('your_api_key', 'your_account_id');

// Create SWIFT recipient
const swiftRecipient = await api.createRecipient({
    id: 'supplier_hk_001',
    country: 'HK',
    name: 'Hong Kong Supplier Ltd',
    email: '[email protected]',
    details: {
        accountType: 'business',
        companyName: 'Hong Kong Supplier Ltd',
        bankName: 'HSBC Hong Kong',
        swiftCode: 'HSBCHKHHHKH',
        accountNumber: '123456789',
        currency: 'HKD'
    }
});

🔄 Institution Selection Workflow

For schemas requiring financial institution selection (bank_africa, momo_africa, etc.):

Get institutions: Call /financial_institutions/{country}/{schema}
User selects: Present options in your UI
Create recipient: Use selected institution ID in financialInstitutionId field

# Complete workflow example
def create_african_recipient_with_selection(api, country, recipient_data):
    # Step 1: Get available institutions
    institutions = api.get_financial_institutions(country, "bank_africa")
    
    # Step 2: User selection (in real app, show dropdown)
    print("Available banks:")
    for i, inst in enumerate(institutions):
        print(f"{i+1}. {inst['name']}")
    
    selected_id = institutions[0]['id']  # Auto-select first for demo
    
    # Step 3: Create recipient with selected institution
    recipient_data['details']['financialInstitutionId'] = selected_id
    return api.create_recipient(recipient_data)

🚨 Important Notes

Financial Institution Selection: Required for bank_africa, momo_africa, bank_colombia, etc.
Schema Validation: Use /schemas endpoint to get current field requirements
Rate Limits: Standard limits apply (see endpoint table)
Deletion: Recipients with pending payments cannot be deleted
Updates: Recipient details cannot be modified after creation (delete and recreate instead)