> ## 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 V3 > 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. ## 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 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 V3 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' 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 required: - currency - rail properties: currency: type: string enum: - USDC example: USDC rail: type: string enum: - POLYGON example: POLYGON refund_instruction: type: object required: - wallet_address - currency - rail properties: wallet_address: type: string example: '0x1b577931C1cC2765024bFbafad97bCe14FF2e87F' currency: type: string enum: - USDC example: USDC rail: type: string enum: - POLYGON 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 required: - currency - rail properties: currency: type: string enum: - USDC example: USDC rail: type: string enum: - POLYGON example: POLYGON refund_instruction: type: object required: - wallet_address - currency - rail properties: wallet_address: type: string example: '0x1b577931C1cC2765024bFbafad97bCe14FF2e87F' currency: type: string enum: - USDC example: USDC rail: type: string enum: - POLYGON 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 description: >- Blockchain network for the destination wallet. Supported values are POLYGON, ETHEREUM, and SOLANA. example: POLYGON currency: type: string enum: - USDC description: >- Token to be sent to the destination wallet. Currently only USDC is supported. example: USDC examples: Bank / Ewallet: summary: Bank or e-wallet beneficiary value: 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 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 ````