> ## 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 V2 > Create a new beneficiary account for payments and transfers V3 is the current version of this endpoint. Use [Create Beneficiary V3](https://developer.fin.com/api-reference/beneficiaries/create-beneficiary-v3) for new integrations. V2 stays available for existing integrations. ## 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. ## OpenAPI ````yaml POST /v2/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 - name: Crypto Orchestration description: >- Accept crypto deposits from exchange and external wallets and settle them to a destination wallet paths: /v2/beneficiaries: post: tags: - Beneficiaries summary: Create Beneficiary V2 description: Create a new beneficiary account for payments and transfers requestBody: required: true content: application/json: schema: allOf: - type: object required: - customer_id - country - currency - account_holder - account_holder_address - receiver_meta_data - developer_fee - deposit_instruction - refund_instruction properties: customer_id: type: string example: cust_123456 country: type: string example: USA pattern: ^[A-Z]{3}$ currency: type: string example: USD counter_party: type: string enum: - FIRST_PARTY - THIRD_PARTY description: >- Indicates whether the beneficiary is a first-party or third-party account. Optional. 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: '+1234567890' - 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: '+1234567890' account_holder_address: type: object required: - street_line_1 - city - state - postcode - country properties: street_line_1: type: string example: 456 Main Street street_line_2: type: string example: Apt 5B city: type: string example: Brooklyn state: type: string description: >- State or province. Required. Must be an ISO 3166-2 subdivision code (e.g. US-CA, BD-13). example: US-NY postcode: type: string example: '11201' country: type: string example: USA pattern: ^[A-Z]{3}$ receiver_meta_data: type: object required: - transaction_purpose_id - occupation_remarks - relationship - nationality properties: transaction_purpose_id: type: integer example: 1 transaction_purpose_remarks: type: string example: Monthly salary payment 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 relationship_remarks: type: string example: Long-term contractor nationality: type: string example: USA pattern: ^[A-Z]{3}$ 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: 5 percentage: type: number example: 2.5 deposit_instruction: type: object required: - currency - rail properties: currency: type: string enum: - USDC rail: type: string enum: - POLYGON refund_instruction: type: object required: - wallet_address - currency - rail properties: wallet_address: type: string example: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb' currency: type: string enum: - USDC rail: type: string enum: - POLYGON settlement_config: type: object required: - auto_settlement properties: auto_settlement: type: boolean example: true - oneOf: - title: Bank Account type: object required: - bank_account - bank_routing - bank_address properties: bank_account: type: object required: - bank_name - number - scheme - type properties: bank_name: type: string example: Chase Bank number: type: string example: '1234567890' scheme: type: string enum: - LOCAL - SWIFT type: type: string enum: - CHECKING - SAVINGS - CURRENT bank_routing: type: array 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 number: oneOf: - type: string - type: integer example: '021000021' bank_address: type: object required: - street_line_1 - city - state - postcode - country properties: street_line_1: type: string example: 123 Bank Street street_line_2: type: string example: Suite 100 city: type: string example: New York state: type: string description: >- State or province. Required. Must be an ISO 3166-2 subdivision code (e.g. US-CA, BD-13). example: US-NY postcode: type: string example: '10001' country: type: string example: USA pattern: ^[A-Z]{3}$ - title: E Wallet type: object required: - e_wallet properties: e_wallet: type: object required: - scheme - number properties: scheme: type: string example: BKASH number: type: string example: '+8801688502814' responses: '200': description: Beneficiary created successfully content: application/json: schema: type: object properties: data: type: object properties: id: type: string example: ben_123456 status: type: string example: active '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: d9868585-78ba-4723-b0af-8f5b1cc5f9e2 '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 ````