> ## 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 From an Existing Connection > Add a bank account that your own app has already connected and verified, so the user does not have to connect it again. The bank account is saved as connected instantly: it can both add money and receive payouts. Available only when this is turned on for your account — ask us. It works only for a connection your app made through the same instant bank verification account as ours. We never take your word for the account details: we read them from the connection ourselves. The account number and routing number are stored encrypted and only ever shown masked. ### What you need to send - ``user_id`` — the user this bank account belongs to - ``access_token`` — the access token of the user's bank connection, as your app holds it - ``account_id`` — the one account in that connection to add ### What you get back - **201** — the bank account was added. If the user already had it, added with its routing and account number, it is upgraded in place: same ``payment_method_id``, and it can now add money. - **200** — the user already had this bank account connected instantly; it is returned unchanged. Sending the same request again is safe. Either way we send the ``payment_method.bank.added`` webhook when a bank account is added or upgraded. ### Keep the connection The connection stays shared with your app. If your app removes it, this bank account stops working until the user connects it again (``payment_method.bank.relink_required``). ### Errors - ``bank_connection_not_enabled`` (403) — not turned on for your account. - ``bank_connection_not_accepted`` (422) — the access token is not valid for our account. - ``bank_connection_relink_required`` (422) — the user must sign in to their bank again in your app first. - ``bank_connection_account_not_found`` (422) — ``account_id`` is not in this connection. - ``bank_account_not_eligible`` (422) — only checking and savings accounts can be added. - ``bank_account_limit_reached`` (422) — the user already has the most bank accounts allowed. - ``bank_connection_unavailable`` (502) — the connection could not be checked; try again. ## OpenAPI ````yaml POST /v1/platform/bank/add-account-connected 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: emails - name: email-templates - name: onboarding - name: Redirect URLs - name: pending-applications - name: feature requests - name: integration apps - 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: Card Transfers (Sandbox) - name: Accounting - name: check payments - name: check designs - name: embed-tokens paths: /v1/platform/bank/add-account-connected: post: tags: - bank accounts summary: Add a Bank Account From a Connection You Already Hold description: >- Add a bank account that your own app has already connected and verified, so the user does not have to connect it again. The bank account is saved as connected instantly: it can both add money and receive payouts. Available only when this is turned on for your account — ask us. It works only for a connection your app made through the same instant bank verification account as ours. We never take your word for the account details: we read them from the connection ourselves. The account number and routing number are stored encrypted and only ever shown masked. ### What you need to send - ``user_id`` — the user this bank account belongs to - ``access_token`` — the access token of the user's bank connection, as your app holds it - ``account_id`` — the one account in that connection to add ### What you get back - **201** — the bank account was added. If the user already had it, added with its routing and account number, it is upgraded in place: same ``payment_method_id``, and it can now add money. - **200** — the user already had this bank account connected instantly; it is returned unchanged. Sending the same request again is safe. Either way we send the ``payment_method.bank.added`` webhook when a bank account is added or upgraded. ### Keep the connection The connection stays shared with your app. If your app removes it, this bank account stops working until the user connects it again (``payment_method.bank.relink_required``). ### Errors - ``bank_connection_not_enabled`` (403) — not turned on for your account. - ``bank_connection_not_accepted`` (422) — the access token is not valid for our account. - ``bank_connection_relink_required`` (422) — the user must sign in to their bank again in your app first. - ``bank_connection_account_not_found`` (422) — ``account_id`` is not in this connection. - ``bank_account_not_eligible`` (422) — only checking and savings accounts can be added. - ``bank_account_limit_reached`` (422) — the user already has the most bank accounts allowed. - ``bank_connection_unavailable`` (502) — the connection could not be checked; try again. operationId: add_connected_bank_account_v1_platform_bank_add_account_connected_post requestBody: content: application/json: schema: $ref: '#/components/schemas/PlatformConnectedBankAccountCreate' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CommonResponse_PlatformPaymentMethodRead_' '201': description: The bank account, connected instantly (sensitive numbers masked). content: application/json: example: status_code: 201 data: payment_method_id: e5f6a7b8-c9d0-1234-5678-9abcdef01234 user_id: b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4 method_type: bank_account status: active bank_name: Example Bank account_mask: '7890' routing_last4: '0021' account_type: checking account_holder_name: John Doe rail_code: ach created_at: '2026-10-12T10:30:00Z' query_generated_time: 1791801000000 '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - _AuthenticatedBearer: [] components: schemas: PlatformConnectedBankAccountCreate: properties: user_id: type: string format: uuid title: User Id description: The user the bank account belongs to. examples: - b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4 access_token: type: string maxLength: 200 minLength: 1 title: Access Token description: >- The access token of the user's bank connection, as your app holds it. examples: - access-production-1f3c9a52-7d1e-4b8a-9c0f-2e6d4a8b1c37 account_id: type: string maxLength: 100 minLength: 1 title: Account Id description: The id of the one account in that connection to add. examples: - vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D additionalProperties: false type: object required: - user_id - access_token - account_id title: PlatformConnectedBankAccountCreate description: |- Add a bank account from a connection the platform already holds. Provider-neutral by construction: the platform-facing neutrality rewrite turns any message naming the provider into a generic error. CommonResponse_PlatformPaymentMethodRead_: properties: status_code: type: integer title: Status Code description: HTTP status code for the response. data: $ref: '#/components/schemas/PlatformPaymentMethodRead' 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[PlatformPaymentMethodRead] HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError PlatformPaymentMethodRead: properties: payment_method_id: type: string format: uuid title: Payment Method Id description: Unique payment method identifier. examples: - e5f6a7b8-c9d0-1234-5678-9abcdef01234 user_id: type: string format: uuid title: User Id description: Owner user UUID. examples: - b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4 user_email: anyOf: - type: string - type: 'null' title: User Email description: Owner user's email address. examples: - owner@example.com user_name: anyOf: - type: string - type: 'null' title: User Name description: Owner user's name. examples: - Jane Doe method_type: type: string title: Method Type description: Payment method type (``bank``, ``card``). examples: - bank status: type: string title: Status description: Method status (active, disabled, revoked, expired). examples: - active nickname: anyOf: - type: string - type: 'null' title: Nickname description: Display nickname. last4: anyOf: - type: string - type: 'null' title: Last4 description: Last 4 digits of the card number. examples: - '1111' brand: anyOf: - type: string - type: 'null' title: Brand description: Card brand (Visa, Mastercard, etc.). examples: - Visa exp_month: anyOf: - type: integer - type: 'null' title: Exp Month description: Card expiry month. examples: - 12 exp_year: anyOf: - type: integer - type: 'null' title: Exp Year description: Card expiry year. examples: - 2027 cardholder_first_name: anyOf: - type: string - type: 'null' title: Cardholder First Name description: Cardholder first name. examples: - John cardholder_last_name: anyOf: - type: string - type: 'null' title: Cardholder Last Name description: Cardholder last name. examples: - Doe cardholder_name: anyOf: - type: string - type: 'null' title: Cardholder Name description: Name on card (first + last). examples: - John Doe card_transfer_aft_enabled: type: boolean title: Card Transfer Aft Enabled description: >- True when this card is registered for card-to-account (money-in) transfers on the platform. Always false for non-card methods. default: false examples: - false card_transfer_oct_enabled: type: boolean title: Card Transfer Oct Enabled description: >- True when this card is registered for account-to-card (money-out) transfers on the platform. Always false for non-card methods. default: false examples: - false billing_address: anyOf: - additionalProperties: true type: object - type: 'null' title: Billing Address description: Card billing address (line1, city, state, postal_code, country). examples: - city: New York country: US line1: 123 Main St postal_code: '10001' state: NY bank_name: anyOf: - type: string - type: 'null' title: Bank Name description: Name of the bank. examples: - Chase Bank account_mask: anyOf: - type: string - type: 'null' title: Account Mask description: Masked account number (last 4 digits). examples: - '****7890' routing_last4: anyOf: - type: string - type: 'null' title: Routing Last4 description: Last 4 digits of the routing number. examples: - '0021' routing_number: anyOf: - type: string - type: 'null' title: Routing Number description: Full ACH routing number (9 digits) of the bank account. examples: - '021000021' is_rtp_enabled: anyOf: - type: boolean - type: 'null' title: Is Rtp Enabled description: >- Whether this account's routing number is on the RTP (real-time payments) network's participant list, i.e. whether the bank can receive an instant payment. Null when that cannot be told: the list is not available, or there is no valid US routing number. account_type: anyOf: - type: string - type: 'null' title: Account Type description: Bank account type. examples: - checking account_holder_name: anyOf: - type: string - type: 'null' title: Account Holder Name description: Account holder name. examples: - John Doe bank_address: anyOf: - type: string - type: 'null' title: Bank Address description: Bank street address. examples: - 270 Park Avenue bank_city: anyOf: - type: string - type: 'null' title: Bank City description: Bank city. examples: - New York bank_state: anyOf: - type: string - type: 'null' title: Bank State description: Bank state. examples: - NY bank_zip: anyOf: - type: string - type: 'null' title: Bank Zip description: Bank ZIP or postal code. examples: - '10017' bank_country: anyOf: - type: string - type: 'null' title: Bank Country description: Bank country. examples: - US account_holder_address: anyOf: - type: string - type: 'null' title: Account Holder Address description: Account holder street address. examples: - 123 Main St account_holder_city: anyOf: - type: string - type: 'null' title: Account Holder City description: Account holder city. examples: - New York account_holder_state: anyOf: - type: string - type: 'null' title: Account Holder State description: Account holder state. examples: - NY account_holder_zip: anyOf: - type: string - type: 'null' title: Account Holder Zip description: Account holder ZIP or postal code. examples: - '10001' account_holder_country: anyOf: - type: string - type: 'null' title: Account Holder Country description: Account holder country. examples: - US rail_code: anyOf: - type: string - type: 'null' title: Rail Code description: Primary rail this instrument was registered for, if any. rail_capabilities: additionalProperties: true type: object title: Rail Capabilities description: Stored per-rail capability/toggle overrides. created_at: anyOf: - type: string format: date-time - type: 'null' title: Created At description: Creation timestamp (UTC). examples: - '2026-04-01T10:30:00Z' type: object required: - payment_method_id - user_id - method_type - status title: PlatformPaymentMethodRead description: |- Payment method representation for the platform API. Sensitive data (full PAN, full account number) is never returned — only masked values (``last4``, ``account_mask``). 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 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.