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.

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

Show child attributes

refund_instruction

object

required

Show child attributes

settlement_config

object

Show child attributes

Response

Beneficiary created successfully

data

object

Show child attributes

Enable USD Features

Create Beneficiary

⌘I

​De-Duplication Logic

Authorizations

Body

Response

De-Duplication Logic