Recipients

When to Use

✅ Use Recipients when:

• Customer needs to pay vendors/suppliers
• Customer needs to pay employees/contractors
• Customer needs to send money to any third party
• You need to manage multiple bank accounts for the same payee

❌ Do NOT use Recipients when:

• Adding customer's own bank account for withdrawals (use External Accounts instead)

API Endpoints

Recipient Management:

Recipient Bank Account Management: (with endpoint prefix: /v1/customers/{customer_id})

Request Example: Create Recipient with Bank Account

{
  "business_type": "COMPANY",
  "company_name": "Acme Software Inc",
  "relationship": "VENDOR",
  "address": {
    "address_line1": "123 Tech Street",
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94105",
    "country": "USA"
  },
  "bank_accounts": [
    {
      "network": "US_FEDWIRE",
      "account_holder_name": "Acme Software Inc",
      "currency": "USD",
      "country_code": "USA",
      "account_number": "9876543210",
      "institution_id": "021000089",
      "institution_name": "Citibank N.A."
    }
  ]
}

Request Example: Add Bank Account to Existing Recipient

{
  "network": "US_ACH",
  "account_holder_name": "Acme Software Inc",
  "currency": "USD",
  "country_code": "USA",
  "account_number": "9876543210",
  "institution_id": "021000089",
  "institution_name": "Citibank N.A."
}

Key Validation Rules

1. Account Holder Name Matching: The account_holder_name must match the recipient's name with ≥80% similarity
2. Business Type: INDIVIDUAL or COMPANY
3. Required Name Fields:
   • INDIVIDUAL: first_name, last_name
   • COMPANY: company_name
4. Relationship Types: VENDOR, EMPLOYEE, SUPPLIER, CONTRACTOR, etc.

Data Model

Customer
└── Recipients (third-party entities)
    ├── Recipient 1 (Vendor: Acme Software Inc)
    │   ├── Bank Account A (USD Wire)
    │   └── Bank Account B (ACH)
    │
    ├── Recipient 2 (Employee: John Smith)
    │   └── Bank Account C (ACH)
    │
    └── Recipient 3 (Supplier: Global Parts Ltd)
        └── Bank Account D (SWIFT)