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": "john.doe@example.com",
    "phone": "+1234567890"
  },
  "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",
    "transaction_purpose_remarks": "Monthly salary payment",
    "occupation_id": 5,
    "relationship_remarks": "Long-term contractor",
    "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
  },
  "deposit_instruction": {
    "currency": "USDC",
    "rail": "POLYGON"
  },
  "refund_instruction": {
    "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "currency": "USDC",
    "rail": "POLYGON"
  },
  "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"
  },
  "settlement_config": {
    "auto_settlement": true
  }
}
'
{
  "data": {
    "id": "ben_123456",
    "status": "active"
  }
}

​
Rules

  • Beneficiary creation requires the customer to be in the APPROVED status. Ensure the customer has been approved before attempting to create beneficiaries.
  • Two beneficiaries with the same destination are not allowed. Attempting to create a beneficiary with the same account details as an existing beneficiary will result in a HTTP 409 Conflict response.

​
De-Duplication Logic

The system checks for duplicate beneficiaries using the following fields for bank accounts:
  • bank_account.scheme
  • bank_account.number
  • bank_routing.scheme
  • bank_routing.number
and for e-wallets, it checks against:
  • e_wallet.scheme
  • e_wallet.number
If a beneficiary with matching values for all these fields already exists for the customer, the API will return a 409 Conflict error instead of creating a duplicate. Note: Deactivating a beneficiary will prevent it from conflicting with any future beneficiary you create, even if you use the same values for the 4 fields above.

​
Country-Specific Validation

​
GBR (United Kingdom)

  • Bank account number: Must match the pattern ^[0-9]{4,9}$ (4 to 9 numeric digits). This applies to both LOCAL and SWIFT schemes.

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

ISO alpha-3 country code from catalog

Pattern: ^[A-Z]{3}$
Example:

"USA"

​
currency
string
required

3 letter currency code

Example:

"USD"

​
account_holder
Individual · object
required
​
account_holder_address
object
required
​
receiver_meta_data
object
required
​
developer_fee
object
required
​
deposit_instruction
object
required
​
refund_instruction
object
required
​
bank_account
object
required
​
bank_routing
object[]
required

Array of bank routing information

​
bank_address
object
required
​
settlement_config
object

Response

Beneficiary created successfully

​
data
object