> ## 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.
# Create Beneficiary
> Create a new beneficiary for payments and transfers. Supports bank accounts, e-wallets, and external crypto wallets as destination types.
* 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](https://developer.fin.com/guides/others/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.
* `receiver_meta_data.intermediary_routing_number` is required for SWIFT payouts.
* USD ACH payouts are coming soon.
When `settlement_config.auto_settlement` is `true`, send funds with a maximum of two decimal places. Anything beyond two decimal places is not counted during conversion.
## 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` |
## OpenAPI
````yaml POST /v3/beneficiaries
openapi: 3.1.0
info:
title: Fin.com API
version: 1.0.0
description: >-
A simple API specification for Fin.com, a financial services platform that
provides a range of banking and payment solutions for businesses and
individuals. This API allows developers to integrate Fin.com's services into
their applications, enabling functionalities such as customer management,
transaction processing, and access to financial data.
servers:
- url: https://sandbox.api.fin.com
description: Sandbox server
- url: https://api.fin.com
description: Production server
security: []
tags:
- name: Authentication
description: A modified OAuth 2.0 Client Credential Flow
- name: Customers
description: Customer management and document upload operations
- name: Balances
description: Retrieve wallet balance information
- name: Catalogue
description: |
A set of endpoints to retrieve contextual data to assemble requests
to fin.com's API
- name: Beneficiaries
description: Manage beneficiary accounts for payments and transfers
- name: Transactions
description: Transaction history and management for beneficiaries
- name: Virtual Accounts
description: Create and manage virtual accounts for USD to USDC conversions
- name: Fees & FX Rates
description: Retrieve fees and foreign exchange rates
paths:
/v3/beneficiaries:
post:
tags:
- Beneficiaries
summary: Create Beneficiary
description: >-
Create a new beneficiary for payments and transfers. Supports bank
accounts, e-wallets, and external crypto wallets as destination types.
requestBody:
required: true
content:
application/json:
schema:
allOf:
- type: object
required:
- customer_id
- country
- currency
- counter_party
- account_holder
- account_holder_address
- receiver_meta_data
- developer_fee
properties:
customer_id:
type: string
format: uuid
example: 6fa1ccd4-ffbd-4b20-a113-ccc286b35443
country:
type: string
pattern: ^[A-Z]{3}$
example: BGD
currency:
type: string
example: BDT
counter_party:
type: string
enum:
- FIRST_PARTY
- THIRD_PARTY
example: FIRST_PARTY
account_holder:
oneOf:
- title: Individual
type: object
required:
- type
- first_name
- last_name
- email
- phone
properties:
type:
type: string
enum:
- INDIVIDUAL
first_name:
type: string
example: John
last_name:
type: string
example: Doe
email:
type: string
format: email
example: john.doe@example.com
phone:
type: string
example: '+8801912244626'
- title: Business
type: object
required:
- type
- business_name
- email
- phone
properties:
type:
type: string
enum:
- BUSINESS
business_name:
type: string
example: Acme Corp
email:
type: string
format: email
example: contact@acmecorp.com
phone:
type: string
example: '+8801912244626'
account_holder_address:
type: object
required:
- street_line_1
- city
- state
- postcode
- country
properties:
street_line_1:
type: string
example: 42 Wallaby Way
city:
type: string
example: Dhaka
state:
type: string
description: >-
State or province. Required. Must be an ISO 3166-2
subdivision code (e.g. US-CA, BD-13).
example: BD-13
postcode:
type: string
example: '1212'
country:
type: string
pattern: ^[A-Z]{3}$
example: BGD
receiver_meta_data:
type: object
required:
- transaction_purpose_id
- relationship
- nationality
properties:
nationality:
type: string
pattern: ^[A-Z]{3}$
example: AUS
transaction_purpose_id:
type: integer
example: 1
transaction_purpose_remarks:
type: string
nullable: true
example: null
occupation_id:
type: integer
example: 5
occupation_remarks:
type: string
example: Software Engineer
relationship:
type: string
enum:
- EMPLOYEE
- FREELANCER
- GIG_WORKER
- AFFILIATE
- CUSTOMER
- FAMILY_MEMBER
- FRIEND
- SELF
- OTHER
- SUPPLIER
- VENDOR
- SERVICE_PROVIDER
- MERCHANT
- CONTRACTOR
- SUBSIDIARY
- PARENT_COMPANY
- AFFILIATE_BUSINESS
- BANK_ACCOUNT
- BROKER
- EXCHANGE
- WALLET
example: FAMILY_MEMBER
relationship_remarks:
type: string
example: Family & Friends
govt_id_number:
type: string
example: JG1121316A
govt_id_issue_date:
type: string
format: date
example: '2024-12-30'
govt_id_expire_date:
type: string
format: date
example: '2027-12-30'
intermediary_routing_number:
type: string
description: >-
Required for SWIFT payouts. Routing number of an
intermediary bank, when the payout has to be routed
through one before it reaches the beneficiary bank.
example: '021000021'
developer_fee:
type: object
required:
- fixed
- percentage
properties:
fixed:
type: number
example: 0.02
percentage:
type: number
example: 0.01
- oneOf:
- title: Bank Account
type: object
required:
- bank_account
- bank_address
- bank_routing
- deposit_instruction
- refund_instruction
properties:
bank_account:
type: object
required:
- bank_name
- number
- scheme
- type
properties:
bank_name:
type: string
example: Commonwealth Bank of Australia
number:
type: string
example: '1234572211'
scheme:
type: string
enum:
- LOCAL
- SWIFT
example: LOCAL
type:
type: string
enum:
- CHECKING
- SAVINGS
- CURRENT
example: SAVINGS
bank_address:
type: object
required:
- street_line_1
- city
- state
- postcode
- country
properties:
street_line_1:
type: string
example: Ground Floor Tower 1, 201 Sussex Street
city:
type: string
example: Dhaka
state:
type: string
description: >-
State or province. Required. Must be an ISO
3166-2 subdivision code (e.g. US-CA, BD-13).
example: BD-13
postcode:
type: string
example: '1212'
country:
type: string
pattern: ^[A-Z]{3}$
example: BGD
bank_routing:
type: array
description: >-
For country-specific routing validation rules, see
[Bank Account and Routing Validation
Rules](https://developer.fin.com/bank-account-and-routing-validation-rules).
items:
type: object
required:
- scheme
- number
properties:
scheme:
type: string
enum:
- ACH
- BANK_CODE
- BANK_IDENTIFIER
- BRANCH_CODE
- BRANCH_IDENTIFIER
- BSB
- IBAN
- IFSC
- SWIFT
- TRANSIT_NUMBER
- WIRE
example: SWIFT
number:
oneOf:
- type: string
- type: integer
example: CLNOUS66BRX
deposit_instruction:
type: object
description: >-
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](https://developer.fin.com/guides/others/supported-rails-and-currencies)
for valid combinations.
required:
- currency
- rail
properties:
currency:
type: string
enum:
- USDC
- USDT
example: USDC
rail:
type: string
enum:
- POLYGON
- ETHEREUM
- SOLANA
- BASE
example: POLYGON
refund_instruction:
type: object
description: >-
The `currency` and `rail` must match
`deposit_instruction`.
required:
- wallet_address
- currency
- rail
properties:
wallet_address:
type: string
example: '0x1b577931C1cC2765024bFbafad97bCe14FF2e87F'
currency:
type: string
enum:
- USDC
- USDT
example: USDC
rail:
type: string
enum:
- POLYGON
- ETHEREUM
- SOLANA
- BASE
example: POLYGON
settlement_config:
type: object
properties:
auto_settlement:
type: boolean
example: true
- title: E Wallet
type: object
required:
- e_wallet
- deposit_instruction
- refund_instruction
properties:
e_wallet:
type: object
required:
- scheme
- number
properties:
scheme:
type: string
example: BKASH
number:
type: string
example: '+8801688502814'
deposit_instruction:
type: object
description: >-
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](https://developer.fin.com/guides/others/supported-rails-and-currencies)
for valid combinations.
required:
- currency
- rail
properties:
currency:
type: string
enum:
- USDC
- USDT
example: USDC
rail:
type: string
enum:
- POLYGON
- ETHEREUM
- SOLANA
- BASE
example: POLYGON
refund_instruction:
type: object
description: >-
The `currency` and `rail` must match
`deposit_instruction`.
required:
- wallet_address
- currency
- rail
properties:
wallet_address:
type: string
example: '0x1b577931C1cC2765024bFbafad97bCe14FF2e87F'
currency:
type: string
enum:
- USDC
- USDT
example: USDC
rail:
type: string
enum:
- POLYGON
- ETHEREUM
- SOLANA
- BASE
example: POLYGON
settlement_config:
type: object
properties:
auto_settlement:
type: boolean
example: true
- title: External Crypto Wallet
type: object
required:
- destination_wallet
properties:
destination_wallet:
type: object
required:
- address
- rail
- currency
properties:
address:
type: string
description: On-chain wallet address of the recipient.
example: '0xD2Ba7d0DaBd36498df5906fC7B054Fa9EfA9843E'
rail:
type: string
enum:
- POLYGON
- ETHEREUM
- SOLANA
- BASE
description: Blockchain network for the destination wallet.
example: POLYGON
currency:
type: string
enum:
- ETH
- SOL
- MATIC
- USDC
- USDT
- PYUSD
- USDPT
description: >-
Token to be sent to the destination wallet. Not
every token is available on every rail. USDPT is
available on SOLANA only.
example: USDC
examples:
Bank (Local):
summary: Bank beneficiary, local rail
value:
customer_id: c1f4a8e2-3b57-4d09-9a61-7e2b5c8d4f30
counter_party: THIRD_PARTY
country: USA
currency: USD
account_holder:
type: INDIVIDUAL
first_name: Walter
last_name: Reed
email: walter.reed@example.com
phone: '+12125550143'
account_holder_address:
street_line_1: 1 Wall Street
city: New York
state: US-NY
postcode: '10005'
country: USA
bank_account:
bank_name: Chase
number: '12345678901'
scheme: LOCAL
type: CHECKING
bank_routing:
- scheme: FEDWIRE
number: '021000021'
bank_address:
street_line_1: 270 Park Ave
city: New York
state: US-NY
postcode: '10017'
country: USA
deposit_instruction:
currency: USDC
rail: ETHEREUM
refund_instruction:
wallet_address: '0x3D6b18Ea54c9F27b0A83d1e6C475b920Fa8E13d4'
currency: USDC
rail: ETHEREUM
developer_fee:
fixed: 0
percentage: 0
settlement_config:
auto_settlement: true
receiver_meta_data:
transaction_purpose_id: 1
occupation_id: 53
nationality: USA
relationship: FRIEND
Bank (International):
summary: Bank beneficiary, international rail
value:
customer_id: c1f4a8e2-3b57-4d09-9a61-7e2b5c8d4f30
counter_party: THIRD_PARTY
country: BGD
currency: USD
account_holder:
type: INDIVIDUAL
first_name: Rahim
last_name: Uddin
email: rahim.uddin@example.com
phone: '+8801712345678'
account_holder_address:
street_line_1: 12 Gulshan Avenue
city: Dhaka
state: BD-13
postcode: '1212'
country: BGD
bank_account:
bank_name: Eastern Commercial Bank
number: '20501174963'
scheme: SWIFT
type: CHECKING
bank_routing:
- scheme: SWIFT
number: ABCDBDDHXXX
bank_address:
street_line_1: 9 Motijheel C/A
city: Dhaka
state: BD-13
postcode: '1000'
country: BGD
deposit_instruction:
currency: USDC
rail: ETHEREUM
refund_instruction:
wallet_address: '0x3D6b18Ea54c9F27b0A83d1e6C475b920Fa8E13d4'
currency: USDC
rail: ETHEREUM
developer_fee:
fixed: 0
percentage: 0
receiver_meta_data:
transaction_purpose_id: 1
occupation_id: 53
nationality: BGD
relationship: FRIEND
intermediary_routing_number: '021000021'
Ewallet:
summary: E-wallet beneficiary
value:
customer_id: 31526861-ebe0-4f84-a7b2-2c3ec1cc47f9
counter_party: FIRST_PARTY
country: BGD
currency: BDT
account_holder:
type: INDIVIDUAL
first_name: Fahmi
last_name: Testbenvtwo
email: fahmitestbenv2ewallet@email.com
phone: '+8801688502814'
account_holder_address:
street_line_1: 42 Chamelibag Shantinagar
city: Dhaka
state: BD-13
postcode: '1217'
country: BGD
receiver_meta_data:
nationality: BGD
transaction_purpose_id: 1
transaction_purpose_remarks: Education expenses
occupation_id: 2
occupation_remarks: Software Engineer
relationship: FRIEND
e_wallet:
number: '+8801688502814'
scheme: BKASH
developer_fee:
fixed: 1.55
percentage: 0.48
deposit_instruction:
currency: USDC
rail: POLYGON
refund_instruction:
wallet_address: '0xabcdef1234567890abcdef1234567890abcdef12'
currency: USDC
rail: POLYGON
settlement_config:
auto_settlement: false
External Crypto Wallet:
summary: External crypto wallet beneficiary
value:
customer_id: '{{customer_id}}'
counter_party: THIRD_PARTY
currency: USDC
country: BGD
account_holder:
type: INDIVIDUAL
first_name: Daphne
last_name: Elliot
email: daphneelliot@email.com
phone: '+8801646767354'
account_holder_address:
street_line_1: 42 Chamelibag Shantinagar
city: Dhaka
state: BD-13
postcode: '1217'
country: BGD
destination_wallet:
address: '0xD2Ba7d0DaBd36498df5906fC7B054Fa9EfA9843E'
rail: POLYGON
currency: USDC
developer_fee:
fixed: 0
percentage: 0
receiver_meta_data:
nationality: BGD
transaction_purpose_id: 7
transaction_purpose_remarks: POLYGON USDC test
occupation_id: 8
relationship: FAMILY_MEMBER
relationship_remarks: Family and Friends
responses:
'200':
description: Beneficiary created successfully
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
beneficiary_id:
type: string
format: uuid
example: 0254b433-e47d-412e-844b-b735c4bbba74
examples:
OK:
summary: OK
value:
data:
beneficiary_id: 0254b433-e47d-412e-844b-b735c4bbba74
'400':
description: Bad Request - Invalid input format
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
message:
type: string
example: Validation failed!
'401':
$ref: '#/components/responses/AuthenticationError'
'409':
description: >-
Conflict - A beneficiary with the same account details already
exists
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: >-
A beneficiary with the same account details already
exists.
error:
type: object
properties:
beneficiary_id:
type: string
format: uuid
example: 0254b433-e47d-412e-844b-b735c4bbba74
'422':
$ref: '#/components/responses/ValidationError'
security:
- bearerAuth: []
components:
responses:
AuthenticationError:
description: Authentication failed due to invalid credentials
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Authentication failed
ValidationError:
description: Failed due to a formatting error.
content:
application/json:
schema:
type: object
required:
- message
properties:
message:
type: string
errors:
type: array
items:
type: object
additionalProperties:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
Bearer token authentication. Obtain token from [Issue a
Token](https://developer.fin.com/api-reference/authentication/issue-a-token)
endpoint
````