Create Beneficiary V3

curl --request POST \
  --url https://sandbox.api.fin.com/v3/beneficiaries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "6fa1ccd4-ffbd-4b20-a113-ccc286b35443",
  "country": "BGD",
  "currency": "BDT",
  "counter_party": "FIRST_PARTY",
  "account_holder": {
    "type": "INDIVIDUAL",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+8801912244626"
  },
  "bank_account": {
    "bank_name": "Commonwealth Bank of Australia",
    "number": "1234572211",
    "scheme": "LOCAL",
    "type": "SAVINGS"
  },
  "bank_address": {
    "street_line_1": "Ground Floor Tower 1, 201 Sussex Street",
    "city": "Dhaka",
    "state": "BD-13",
    "postcode": "1212",
    "country": "BGD"
  },
  "account_holder_address": {
    "street_line_1": "42 Wallaby Way",
    "city": "Dhaka",
    "state": "BD-13",
    "postcode": "1212",
    "country": "BGD"
  },
  "receiver_meta_data": {
    "nationality": "AUS",
    "transaction_purpose_id": 1,
    "occupation_id": 5,
    "relationship": "FAMILY_MEMBER",
    "relationship_remarks": "Family & Friends"
  },
  "bank_routing": [
    {
      "scheme": "SWIFT",
      "number": "CLNOUS66BRX"
    },
    {
      "scheme": "BANK_IDENTIFIER",
      "number": 160
    },
    {
      "scheme": "BRANCH_IDENTIFIER",
      "number": 8
    }
  ],
  "developer_fee": {
    "fixed": 0.02,
    "percentage": 0.01
  },
  "deposit_instruction": {
    "currency": "USDC",
    "rail": "POLYGON"
  },
  "refund_instruction": {
    "wallet_address": "0x1b577931C1cC2765024bFbafad97bCe14FF2e87F",
    "currency": "USDC",
    "rail": "POLYGON"
  },
  "settlement_config": {
    "auto_settlement": true
  }
}
'

{
  "data": {
    "beneficiary_id": "0254b433-e47d-412e-844b-b735c4bbba74"
  }
}

{
  "errors": [
    {}
  ],
  "message": "Validation failed!"
}

{
  "message": "Authentication failed"
}

{
  "message": "A beneficiary with the same account details already exists.",
  "error": {
    "beneficiary_id": "0254b433-e47d-412e-844b-b735c4bbba74"
  }
}

{
  "message": "<string>",
  "errors": [
    {}
  ]
}

POST

beneficiaries

curl --request POST \
  --url https://sandbox.api.fin.com/v3/beneficiaries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "6fa1ccd4-ffbd-4b20-a113-ccc286b35443",
  "country": "BGD",
  "currency": "BDT",
  "counter_party": "FIRST_PARTY",
  "account_holder": {
    "type": "INDIVIDUAL",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+8801912244626"
  },
  "bank_account": {
    "bank_name": "Commonwealth Bank of Australia",
    "number": "1234572211",
    "scheme": "LOCAL",
    "type": "SAVINGS"
  },
  "bank_address": {
    "street_line_1": "Ground Floor Tower 1, 201 Sussex Street",
    "city": "Dhaka",
    "state": "BD-13",
    "postcode": "1212",
    "country": "BGD"
  },
  "account_holder_address": {
    "street_line_1": "42 Wallaby Way",
    "city": "Dhaka",
    "state": "BD-13",
    "postcode": "1212",
    "country": "BGD"
  },
  "receiver_meta_data": {
    "nationality": "AUS",
    "transaction_purpose_id": 1,
    "occupation_id": 5,
    "relationship": "FAMILY_MEMBER",
    "relationship_remarks": "Family & Friends"
  },
  "bank_routing": [
    {
      "scheme": "SWIFT",
      "number": "CLNOUS66BRX"
    },
    {
      "scheme": "BANK_IDENTIFIER",
      "number": 160
    },
    {
      "scheme": "BRANCH_IDENTIFIER",
      "number": 8
    }
  ],
  "developer_fee": {
    "fixed": 0.02,
    "percentage": 0.01
  },
  "deposit_instruction": {
    "currency": "USDC",
    "rail": "POLYGON"
  },
  "refund_instruction": {
    "wallet_address": "0x1b577931C1cC2765024bFbafad97bCe14FF2e87F",
    "currency": "USDC",
    "rail": "POLYGON"
  },
  "settlement_config": {
    "auto_settlement": true
  }
}
'

{
  "data": {
    "beneficiary_id": "0254b433-e47d-412e-844b-b735c4bbba74"
  }
}

{
  "errors": [
    {}
  ],
  "message": "Validation failed!"
}

{
  "message": "Authentication failed"
}

{
  "message": "A beneficiary with the same account details already exists.",
  "error": {
    "beneficiary_id": "0254b433-e47d-412e-844b-b735c4bbba74"
  }
}

{
  "message": "<string>",
  "errors": [
    {}
  ]
}

The beneficiary will be ready for transactions only when its status is APPROVED and active is true.
Check all the supported fiat and crypto rails and currencies, along with the valid combinations, in Supported rails and currencies.
The rails and currencies of deposit_instruction and refund_instruction have to be the same.
The available rails and currencies depend on the configuration set up for you. Contact support to know more.

De-Duplication Logic

Destination Type	Fields Checked
Bank Account	`bank_account.scheme`, `bank_account.number`, `bank_routing.scheme`, `bank_routing.number`
E-Wallet	`e_wallet.scheme`, `e_wallet.number`
External Crypto Wallet	`destination_wallet.address`, `destination_wallet.rail`

Authorizations

Authorization

string

header

required

Bearer token authentication. Obtain token from Issue a Token endpoint

Body

application/json

Bank Account
E Wallet
External Crypto Wallet

customer_id

string<uuid>

required

Example:

"6fa1ccd4-ffbd-4b20-a113-ccc286b35443"

country

string

required

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

Example:

"BGD"

currency

string

required

Example:

"BDT"

counter_party

enum<string>

required

Available options:

FIRST_PARTY,

THIRD_PARTY

Example:

"FIRST_PARTY"

account_holder

Individual · object

required

Individual
Business

Show child attributes

account_holder_address

object

required

Show child attributes

receiver_meta_data

object

required

Show child attributes

developer_fee

object

required

Show child attributes

bank_account

object

required

Show child attributes

bank_address

object

required

Show child attributes

bank_routing

object[]

required

For country-specific routing validation rules, see Bank Account and Routing Validation Rules.

Show child attributes

deposit_instruction

object

required

Token and network the customer deposits on to fund this beneficiary. The currency and rail must match refund_instruction. Availability depends on the payout currency, and not every token is issued on every network. See Supported rails and currencies for valid combinations.

Show child attributes

refund_instruction

object

required

The currency and rail must match deposit_instruction.

Show child attributes

settlement_config

object

Show child attributes

Response

Beneficiary created successfully

data

object

Show child attributes

Authentication

Customers

Beneficiaries

Virtual Accounts

Transactions

Balances

Fees & FX Rates

Catalogue

Webhooks

Create Beneficiary V3

De-Duplication Logic

Authorizations

Body

Response

​De-Duplication Logic

Authorizations

Body

Response

De-Duplication Logic