Skip to main content
POST
/
v2
/
beneficiaries
Create Beneficiary
curl --request POST \
  --url https://sandbox.api.fin.com/v2/beneficiaries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "cust_123456",
  "country": "USA",
  "currency": "USD",
  "account_holder": {
    "type": "INDIVIDUAL",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone": "+1234567890"
  },
  "bank_account": {
    "bank_name": "Chase Bank",
    "number": "1234567890",
    "scheme": "LOCAL",
    "type": "CHECKING"
  },
  "bank_routing": [
    {
      "scheme": "ACH",
      "number": "021000021"
    }
  ],
  "bank_address": {
    "street_line_1": "123 Bank Street",
    "city": "New York",
    "state": "US-NY",
    "postcode": "10001",
    "country": "USA",
    "street_line_2": "Suite 100"
  },
  "account_holder_address": {
    "street_line_1": "456 Main Street",
    "city": "Brooklyn",
    "state": "US-NY",
    "postcode": "11201",
    "country": "USA",
    "street_line_2": "Apt 5B"
  },
  "receiver_meta_data": {
    "transaction_purpose_id": 1,
    "occupation_remarks": "Software Engineer",
    "relationship": "EMPLOYEE",
    "nationality": "USA",
    "govt_id_issuance_date": "2020-01-15",
    "govt_id_number": "123456789",
    "govt_id_expiry_date": "2030-01-15",
    "transaction_purpose_remarks": "Monthly salary payment",
    "occupation_id": 5,
    "relationship_remarks": "Long-term contractor"
  },
  "developer_fee": {
    "fixed": 5,
    "percentage": "2.5"
  },
  "deposit_instruction": {
    "currency": "USDC",
    "rail": "POLYGON"
  },
  "refund_instruction": {
    "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "currency": "USDC",
    "rail": "POLYGON"
  },
  "settlement_config": {
    "auto_settlement": true
  }
}
'
{
  "data": {
    "id": "ben_123456",
    "status": "active"
  }
}
Beneficiary creation requires the customer to be in the APPROVED status. Ensure the customer has been approved before attempting to create beneficiaries.

Authorizations

Authorization
string
header
required

Bearer token authentication. Obtain token from /v1/oauth/token endpoint

Body

application/json
customer_id
string
required

Unique identifier for the customer

Example:

"cust_123456"

country
string
required

3 letter country code from catalog

Example:

"USA"

currency
string
required

3 letter currency code

Example:

"USD"

account_holder
object
required
bank_account
object
required
bank_routing
object[]
required

Array of bank routing information

bank_address
object
required
account_holder_address
object
required
receiver_meta_data
object
required
developer_fee
object
required
deposit_instruction
object
required
refund_instruction
object
required
settlement_config
object

Response

Beneficiary created successfully

data
object