Fin
Fin Beneficiaries API

Manage beneficiary accounts for payments and transfers
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.1.0
info:
  title: Fin.com Authentication Beneficiaries API
  version: 1.0.0
  description: A simple API specificationFo
servers:
- url: https://sandbox.api.fin.com
  description: Sandbox server
- url: https://api.fin.com
  description: Production server
tags:
- name: Beneficiaries
  description: Manage beneficiary accounts for payments and transfers
paths:
  /v1/beneficiaries/countries:
    get:
      summary: List Available Countries
      description: Retrieve a list of countries supported for beneficiary creation with available payment methods and phone validation rules
      tags:
      - Beneficiaries
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Countries list retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 4
                        code:
                          type: string
                          example: AUS
                        name:
                          type: string
                          example: Australia
                        currency_code:
                          type: string
                          example: AUD
                        phone:
                          type: object
                          properties:
                            code:
                              type: string
                              example: '+61'
                            max_length:
                              type: integer
                              example: 9
                            min_length:
                              type: integer
                              example: 9
                        available_methods:
                          type: array
                          items:
                            type: string
                            enum:
                            - BANK
                            - E_WALLET
                          example:
                          - BANK
                        flag:
                          type: string
                          format: uri
                          example: https://flagcdn.com/au.svg
        '401':
          $ref: '#/components/responses/AuthenticationError'
  /v1/beneficiaries/methods:
    get:
      summary: List Bank Identifiers
      description: Retrieve a list of available banks or e-wallet providers for a specific country and method type
      tags:
      - Beneficiaries
      security:
      - bearerAuth: []
      parameters:
      - name: country_code
        in: query
        required: true
        schema:
          type: string
        example: BGD
      - name: method
        in: query
        required: true
        schema:
          type: string
          enum:
          - BANK
          - E_WALLET
      responses:
        '200':
          description: Bank/method identifiers retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1461
                        name:
                          type: string
                          example: AB BANK LTD.
                        method:
                          type: string
                          enum:
                          - BANK
                          - E_WALLET
                          example: BANK
                        has_branch:
                          type: boolean
                          example: true
        '401':
          $ref: '#/components/responses/AuthenticationError'
  /v1/beneficiaries/methods/{method_id}/branches:
    get:
      summary: List Bank Branch Identifiers
      description: Retrieve a list of available branches for a specific bank or payment method
      tags:
      - Beneficiaries
      security:
      - bearerAuth: []
      parameters:
      - name: method_id
        in: path
        required: true
        schema:
          type: string
        example: '1472'
      responses:
        '200':
          description: Branch identifiers retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 21513
                        name:
                          type: string
                          example: SITAKUNDA
                        branch_code:
                          type: string
                          example: 020157391
        '401':
          $ref: '#/components/responses/AuthenticationError'
  /v3/beneficiaries:
    post:
      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.
      x-mint:
        content: "<Note>\n  The beneficiary will be ready for transactions only when its `status` is `APPROVED` and `active` is true.\n</Note>\n\n## De-Duplication Logic\n\n| Destination Type        | Fields Checked                                                                                          |\n| ----------------------- | ------------------------------------------------------------------------------------------------------- |\n| Bank Account            | `bank_account.scheme`, `bank_account.number`, `bank_routing.scheme`, `bank_routing.number`             |\n| E-Wallet                | `e_wallet.scheme`, `e_wallet.number`                                                                    |\n| External Crypto Wallet  | `destination_wallet.address`, `destination_wallet.rail`                                                 |\n"
      tags:
      - Beneficiaries
      security:
      - bearerAuth: []
      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'
  /v2/beneficiaries:
    post:
      summary: Create Beneficiary
      description: Create a new beneficiary account for payments and transfers
      x-mint:
        content: "<Warning>\n  This endpoint was deprecated on May 20, 2026. Use [Create Beneficiary V3](https://developer.fin.com/api-reference/beneficiaries/create-beneficiary-v3) instead.\n</Warning>\n\n## Rules\n\n- Beneficiary creation requires the customer to be in the `APPROVED` status.\n- Two beneficiaries with the same destination are not allowed.\n\n## De-Duplication Logic\n\nFor _bank accounts_, the system checks: `bank_account.scheme`, `bank_account.number`, `bank_routing.scheme`, `bank_routing.number`.\nFor _e-wallets_: `e_wallet.scheme`, `e_wallet.number`.\n\n## Country-Specific Validation\n\n### GBR (United Kingdom)\n- **Bank account number**: Must match `^[0-9]{4,9}$` for both `LOCAL` and `SWIFT` schemes.\n"
      tags:
      - Beneficiaries
      security:
      - bearerAuth: []
      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
         

# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fin/refs/heads/main/openapi/fin-beneficiaries-api-openapi.yml
Fin Beneficiaries API

Documentation

Specifications

Other Resources

OpenAPI Specification
