Skip to main content
POST
/
v2
/
beneficiaries
Copy of 
curl --request POST \
  --url https://{base_url}/v2/beneficiaries \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "ad41fac1-e406-445b-aea4-69381c39ca5d",
  "country": "AUS",
  "currency": "AUD",
  "account_holder": {
    "type": "INDIVIDUAL",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+61498765432"
  },
  "bank_account": {
    "bank_name": "Commonwealth Bank of Australia",
    "number": "123456789",
    "scheme": "LOCAL",
    "type": "SAVINGS"
  },
  "bank_address": {
    "street_line_1": "Ground Floor Tower 1, 201 Sussex Street",
    "city": "Sydney",
    "state": "AU-SA",
    "postcode": "2000",
    "country": "AUS"
  },
  "account_holder_address": {
    "street_line_1": "221B Baker Street",
    "city": "Sydney",
    "state": "AU-SA",
    "postcode": "2000",
    "country": "AUS"
  },
  "receiver_meta_data": {
    "transaction_purpose_id": 1,
    "transaction_purpose_remarks": "Personal transfer",
    "occupation_id": 504,
    "occupation_remarks": "Software quality assurance analyst and tester",
    "relationship": "SELF",
    "relationship_remarks": "Same account holder",
    "nationality": "AUS"
  },
  "bank_routing": [
    {
      "scheme": "BSB",
      "number": 123456
    },
    {
      "scheme": "BANK_IDENTIFIER",
      "number": 120
    }
  ],
  "developer_fee": {
    "fixed": 1.25,
    "percentage": 0.45
  },
  "deposit_instruction": {
    "currency": "USDC",
    "rail": "POLYGON"
  },
  "refund_instruction": {
    "wallet_address": "0x1b577931C1cC2765024bFbafad97bCe14FF2e87F",
    "currency": "USDC",
    "rail": "POLYGON"
  },
  "settlement_config": {
    "auto_settlement": false
  }
}
'
{
  "data": {
    "beneficiary_id": "ed2b1082-1d71-4a0a-ba3b-7fb87763d498"
  }
}

Documentation Index

Fetch the complete documentation index at: https://developer.fin.com/llms.txt

Use this file to discover all available pages before exploring further.

This endpoint will be deprecated on May 20, 2026. Use Create Beneficiary V3 instead.

​
Rules

  • Beneficiary creation requires the customer to be in the APPROVED status.
  • Two beneficiaries with the same destination are not allowed.

​
De-Duplication Logic

For bank accounts, the system checks: bank_account.scheme, bank_account.number, bank_routing.scheme, bank_routing.number. For e-wallets: e_wallet.scheme, e_wallet.number.

​
Country-Specific Validation

​
GBR (United Kingdom)

  • Bank account number: Must match ^[0-9]{4,9}$ for both LOCAL and SWIFT schemes.

Headers

​
Authorization
string
default:Bearer {{client_access_token}}
required

Body

application/json
​
customer_id
string
required

id of the customer this beneficiary will belong to

​
country
string
required

ISO 3166-1 alpha-3 codes, can be retrieved from the 'Catalogue'

​
currency
string
required

ISO 4217 currency code, can be retrieved from the 'Catalogue'

​
account_holder
object
required

information regarding the account holder

​
bank_account
object
required

Details about the bank account

​
bank_routing
object[]
required

Bank routing requirements vary by country and by the selected account type (LOCAL or SWIFT). Refer to the JSON validation file for the exact routing schemes and fields needed.

​
bank_address
object
required

Exact bank address

​
account_holder_address
object
required
​
receiver_meta_data
object
required

Details about the receiver

​
developer_fee
object
required
​
deposit_instruction
object
required
​
refund_instruction
object
required
​
settlement_config
object
required

Dictates how a beneficiary's liquidation address behaves

Response

​
data
object