> ## Documentation Index
> Fetch the complete documentation index at: https://developer.finogates.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add a Bank Account to a Payee

> Save the bank account where this payee should receive money. One endpoint covers two cases — send the fields for whichever applies:

* **US domestic (ACH)** — `bank_account_number` plus `routing_number` (9-digit, ABA-valid). Optionally add `account_type` (`checking` or `savings`).
* **International** — `bank_account_number` plus `bank_country` (the ISO 3166-1 alpha-2 destination country, e.g. `AE`, `IN`, `MX`). The receiving bank's routing identifier, `bank_branch`, varies by country (IFSC for India, CLABE for Mexico, SWIFT/BIC elsewhere) and is carried in one field instead of a column per country — it is optional: some corridors (e.g. UAE) need only the account number. The numeric `payout_branch_id` is also optional — if you omit it, it is resolved when a payout is sent (from the corridor's country and currency). Add `bank_name`, `bank_document`, `purpose_of_payment`, and `recipient_type` where the corridor requires them.

Individual fields are optional, but the body must satisfy one of the two cases above or the request is rejected.

Account and routing numbers are encrypted at rest — only the last four digits are ever returned (`account_last4`, `routing_last4`).



## OpenAPI

````yaml POST /v1/platform/payees/bank-accounts/{payee_id}
openapi: 3.1.0
info:
  title: Finogate Platform API v1
  version: 0.1.0
servers:
  - url: https://api-sandbox.finogates.com
    description: Sandbox
  - url: https://api.finogates.com
    description: Production
security: []
tags:
  - name: auth
  - name: users
  - name: payees
  - name: verification
  - name: bank accounts
  - name: card processing
  - name: digital-assets
  - name: international
  - name: fees
  - name: onboarding
  - name: pending-applications
  - name: wallets
  - name: payments
  - name: document mailing
  - name: merchant onboarding
  - name: catalog
  - name: webhooks
  - name: screening
  - name: Platform - File Scanning
  - name: phone-numbers
  - name: sms
  - name: calls
  - name: listings
  - name: Card Transfers
  - name: embed-tokens
paths:
  /v1/platform/payees/bank-accounts/{payee_id}:
    post:
      tags:
        - payees
      summary: Add a Bank Account to a Payee
      description: >-
        Save the bank account where this payee should receive money. One
        endpoint covers two cases — send the fields for whichever applies:


        * **US domestic (ACH)** — `bank_account_number` plus `routing_number`
        (9-digit, ABA-valid). Optionally add `account_type` (`checking` or
        `savings`).

        * **International** — `bank_account_number` plus `bank_country` (the ISO
        3166-1 alpha-2 destination country, e.g. `AE`, `IN`, `MX`). The
        receiving bank's routing identifier, `bank_branch`, varies by country
        (IFSC for India, CLABE for Mexico, SWIFT/BIC elsewhere) and is carried
        in one field instead of a column per country — it is optional: some
        corridors (e.g. UAE) need only the account number. The numeric
        `payout_branch_id` is also optional — if you omit it, it is resolved
        when a payout is sent (from the corridor's country and currency). Add
        `bank_name`, `bank_document`, `purpose_of_payment`, and `recipient_type`
        where the corridor requires them.


        Individual fields are optional, but the body must satisfy one of the two
        cases above or the request is rejected.


        Account and routing numbers are encrypted at rest — only the last four
        digits are ever returned (`account_last4`, `routing_last4`).
      operationId: add_bank_account_v1_platform_payees_bank_accounts__payee_id__post
      parameters:
        - name: payee_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Payee Id
        - name: user_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
            description: The unique ID of the user who owns this payee.
            examples:
              - b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4
            title: User Id
          description: The unique ID of the user who owns this payee.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayeeBankAccountCreate'
            examples:
              domestic_ach:
                summary: US domestic (ACH)
                value:
                  nickname: Acme — Operating
                  account_holder_name: Acme Supplier LLC
                  bank_name: Example Bank
                  bank_country: US
                  currency: USD
                  bank_account_number: '000123456789'
                  routing_number: '021000021'
                  account_type: checking
              international:
                summary: International (single bank_branch routing code)
                value:
                  nickname: Acme — India payouts
                  account_holder_name: Acme Supplier Pvt Ltd
                  bank_name: State Bank of India
                  bank_country: IN
                  currency: INR
                  bank_account_number: '30987654321'
                  bank_branch: SBIN0001234
                  payout_branch_id: 4821
                  bank_document: ABCDE1234F
                  recipient_type: business
                  purpose_of_payment: Vendor invoice 2026-05
              international_account_only:
                summary: International (account number only — no bank_branch)
                value:
                  nickname: Beneficiary — UAE payouts
                  account_holder_name: Beneficiary Name
                  bank_country: AE
                  currency: AED
                  bank_account_number: '0123456789'
      responses:
        '200':
          description: The saved bank account (sensitive numbers masked).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommonResponse_PayeeBankAccountRead_'
              example:
                status_code: 201
                data:
                  id: f1e2d3c4-b5a6-7890-1234-567890abcdef
                  payee_id: d4e5f6a7-b8c9-0123-4567-890abcdef012
                  nickname: Acme — Operating
                  account_holder_name: Acme Supplier LLC
                  bank_name: Example Bank
                  bank_country: US
                  currency: USD
                  rail_code: ach
                  account_type: checking
                  account_last4: '6789'
                  routing_last4: '0021'
                  status: active
                  created_at: '2025-06-10T18:12:00.000Z'
                  updated_at: '2025-06-10T18:12:00.000Z'
                query_generated_time: 1712847600000
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - _AuthenticatedBearer: []
components:
  schemas:
    PayeeBankAccountCreate:
      properties:
        nickname:
          anyOf:
            - type: string
              maxLength: 120
            - type: 'null'
          title: Nickname
          description: >-
            Optional short label your user gave this bank account (for example,
            "Acme — Chase Checking").
        account_holder_name:
          anyOf:
            - type: string
              maxLength: 120
            - type: 'null'
          title: Account Holder Name
          description: The name on the bank account, exactly as the bank has it.
        bank_name:
          anyOf:
            - type: string
              maxLength: 120
            - type: 'null'
          title: Bank Name
          description: The bank's name. Useful for international accounts.
        bank_country:
          anyOf:
            - type: string
              maxLength: 2
              minLength: 2
            - type: 'null'
          title: Bank Country
          description: ISO 3166-1 alpha-2 country code of the bank (e.g. US, GB, DE).
        currency:
          anyOf:
            - type: string
              maxLength: 3
              minLength: 3
            - type: 'null'
          title: Currency
          description: >-
            ISO 4217 three-letter currency code (e.g. USD, EUR, GBP). Defaults
            to USD when not provided.
        bank_account_number:
          anyOf:
            - type: string
              maxLength: 34
              minLength: 4
            - type: 'null'
          title: Bank Account Number
          description: The bank account number where money will be deposited.
        routing_number:
          anyOf:
            - type: string
              maxLength: 9
            - type: 'null'
          title: Routing Number
          description: 'US-only: the 9-digit ABA routing number of the bank.'
        account_type:
          anyOf:
            - type: string
              maxLength: 30
            - type: 'null'
          title: Account Type
          description: >-
            Account type — "checking"/"savings" for US ACH, or a corridor
            account-type code (AHO/CTE/NON) for international.
        purpose_of_payment:
          anyOf:
            - type: string
              maxLength: 120
            - type: 'null'
          title: Purpose Of Payment
          description: >-
            Optional: a short description of why the money is being sent (some
            corridors require it).
        recipient_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Recipient Type
          description: 'Optional: either "individual" or "business".'
        bank_branch:
          anyOf:
            - type: string
              maxLength: 50
            - type: 'null'
          title: Bank Branch
          description: >-
            The receiving bank's routing identifier for an international payout.
            A single field that carries whatever the destination country uses —
            e.g. IFSC for India, CLABE for Mexico, or the SWIFT/BIC code
            elsewhere.
        bank_document:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Bank Document
          description: >-
            Recipient bank document (e.g. CPF / CNPJ / RFC), where the corridor
            needs it.
        payout_branch_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Payout Branch Id
          description: >-
            Optional numeric payout branch id for an international payout. If
            omitted, it is resolved at payout time from the destination's
            corridor (country + currency), so the account can be registered with
            just the routing code in bank_branch.
      type: object
      title: PayeeBankAccountCreate
      description: |-
        Request body for adding a bank account to a payee.

        Every field is optional, but the combination must describe either:

        * A US domestic account — set ``bank_account_number`` and
          ``routing_number`` (a 9-digit US ABA-valid routing number); or
        * An international account — set ``bank_account_number`` and
          ``bank_country`` (the ISO 3166-1 alpha-2 destination country). The
          corridor's routing identifier — ``bank_branch`` (IFSC / CLABE /
          SWIFT-BIC / …) and the numeric ``payout_branch_id`` — is optional:
          some corridors (e.g. UAE) need only the account number, and where a
          branch is required it is resolved at payout time.

        The endpoint rejects requests that satisfy neither case.
    CommonResponse_PayeeBankAccountRead_:
      properties:
        status_code:
          type: integer
          title: Status Code
          description: HTTP status code for the response.
        data:
          $ref: '#/components/schemas/PayeeBankAccountRead'
          description: Payload or error details.
        query_generated_time:
          type: integer
          title: Query Generated Time
          description: >-
            UTC timestamp (milliseconds since epoch) when response was
            generated.
      type: object
      required:
        - status_code
        - data
        - query_generated_time
      title: CommonResponse[PayeeBankAccountRead]
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PayeeBankAccountRead:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        payee_id:
          type: string
          format: uuid
          title: Payee Id
        nickname:
          anyOf:
            - type: string
            - type: 'null'
          title: Nickname
        account_holder_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Account Holder Name
        bank_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Bank Name
        bank_country:
          anyOf:
            - type: string
            - type: 'null'
          title: Bank Country
        currency:
          anyOf:
            - type: string
            - type: 'null'
          title: Currency
        rail_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Rail Code
        account_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Account Type
        account_last4:
          anyOf:
            - type: string
            - type: 'null'
          title: Account Last4
        routing_last4:
          anyOf:
            - type: string
            - type: 'null'
          title: Routing Last4
        routing_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Routing Number
        swift_bic:
          anyOf:
            - type: string
            - type: 'null'
          title: Swift Bic
        iban_last4:
          anyOf:
            - type: string
            - type: 'null'
          title: Iban Last4
        bank_branch:
          anyOf:
            - type: string
            - type: 'null'
          title: Bank Branch
        bank_document:
          anyOf:
            - type: string
            - type: 'null'
          title: Bank Document
        payout_branch_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Payout Branch Id
        status:
          type: string
          title: Status
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updated At
      type: object
      required:
        - id
        - payee_id
        - status
      title: PayeeBankAccountRead
      description: Bank account returned by the API — last-four digits only.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    _AuthenticatedBearer:
      type: oauth2
      flows:
        password:
          scopes: {}
          tokenUrl: /v1/platform/auth/token

````