Sign in

v1

latestOpenAPI 3.1.02026-07-226250251.5 KB
Beneficiaries

Create Beneficiary

Create a new beneficiary account for payments and transfers

post/v2/beneficiaries

Request body

OR

Example request

{
  "customer_id": "cust_123456",
  "country": "USA",
  "currency": "USD",
  "counter_party": "FIRST_PARTY",
  "account_holder": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890"
  },
  "account_holder_address": {
    "street_line_1": "456 Main Street",
    "street_line_2": "Apt 5B",
    "city": "Brooklyn",
    "state": "US-NY",
    "postcode": "11201",
    "country": "USA"
  },
  "receiver_meta_data": {
    "transaction_purpose_id": 1,
    "transaction_purpose_remarks": "Monthly salary payment",
    "occupation_id": 5,
    "occupation_remarks": "Software Engineer",
    "relationship_remarks": "Long-term contractor",
    "nationality": "USA",
    "govt_id_number": "JG1121316A",
    "govt_id_issue_date": "2024-12-30",
    "govt_id_expire_date": "2027-12-30"
  },
  "developer_fee": {
    "fixed": 5,
    "percentage": 2.5
  },
  "refund_instruction": {
    "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
  },
  "settlement_config": {
    "auto_settlement": true
  },
  "bank_account": {
    "bank_name": "Chase Bank",
    "number": "1234567890"
  },
  "bank_address": {
    "street_line_1": "123 Bank Street",
    "street_line_2": "Suite 100",
    "city": "New York",
    "state": "US-NY",
    "postcode": "10001",
    "country": "USA"
  }
}

Response

Beneficiary created successfully

Example response

{
  "data": {
    "id": "ben_123456",
    "status": "active"
  }
}