> ## 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.

# Get a Bank Account Relink Link

> Get a ready-made web page link that lets one of your users refresh the
instant connection behind a bank account they already added — the bank has
asked them to sign in again, and until they do, payments from that account
fail with `bank_relink_required`.

You learn a bank needs this from the `payment_method.bank.relink_required`
webhook, from `relink_required: true` on `GET /platform/bank-accounts/{user_id}`,
or from a payment that failed with that reason. Show the page inside your
own website (in an iframe) or open it in its own window; the user signs in
to their bank on it, and the account they already have keeps working — no
new bank account is created.

### What you get back
- ``bank_account_id`` / ``user_id`` — the account this link is for.
- ``relink_bank_url`` — the link to load. It can be used once.
- ``expires_at`` — the time the link stops working (about 10 minutes away).

### How you find out the result
- When the connection is working again, we send your server a
  ``payment_method.bank.relinked`` webhook with the ``payment_method_id`` and
  ``user_id``, and ``relink_required`` goes back to false.
- If the user does not finish, nothing changes and no notification is sent.
  Call this endpoint again for a fresh link — links cannot be renewed.

A bank account that was added manually (routing and account number) has no
instant connection to refresh and is refused with `bank_not_relinkable`.
The link contains no details about which company connects the bank behind
the scenes. Treat it as a plain string with no meaning of its own.



## OpenAPI

````yaml GET /v1/platform/bank/relink/{bank_account_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: Redirect URLs
  - 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: Accounting
  - name: embed-tokens
paths:
  /v1/platform/bank/relink/{bank_account_id}:
    get:
      tags:
        - bank accounts
      summary: Get a Link for the User to Reconnect a Bank Account
      description: >-
        Get a ready-made web page link that lets one of your users refresh the

        instant connection behind a bank account they already added — the bank
        has

        asked them to sign in again, and until they do, payments from that
        account

        fail with `bank_relink_required`.


        You learn a bank needs this from the
        `payment_method.bank.relink_required`

        webhook, from `relink_required: true` on `GET
        /platform/bank-accounts/{user_id}`,

        or from a payment that failed with that reason. Show the page inside
        your

        own website (in an iframe) or open it in its own window; the user signs
        in

        to their bank on it, and the account they already have keeps working —
        no

        new bank account is created.


        ### What you get back

        - ``bank_account_id`` / ``user_id`` — the account this link is for.

        - ``relink_bank_url`` — the link to load. It can be used once.

        - ``expires_at`` — the time the link stops working (about 10 minutes
        away).


        ### How you find out the result

        - When the connection is working again, we send your server a
          ``payment_method.bank.relinked`` webhook with the ``payment_method_id`` and
          ``user_id``, and ``relink_required`` goes back to false.
        - If the user does not finish, nothing changes and no notification is
        sent.
          Call this endpoint again for a fresh link — links cannot be renewed.

        A bank account that was added manually (routing and account number) has
        no

        instant connection to refresh and is refused with `bank_not_relinkable`.

        The link contains no details about which company connects the bank
        behind

        the scenes. Treat it as a plain string with no meaning of its own.
      operationId: get_hosted_relink_bank_url_v1_platform_bank_relink__bank_account_id__get
      parameters:
        - name: bank_account_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: >-
              The unique ID of the linked bank account whose connection needs
              refreshing.
            examples:
              - e5f6a7b8-c9d0-1234-5678-9abcdef01234
            title: Bank Account Id
          description: >-
            The unique ID of the linked bank account whose connection needs
            refreshing.
        - name: parent_origin
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                maxLength: 255
              - type: 'null'
            description: >-
              Optional. The bare origin of the page that will embed the link in
              an iframe (e.g. ``https://app.example.com``). When provided, the
              page sends the outcome back to that exact window via a browser
              message. Omit it when opening the link as a full page or popup.
            examples:
              - https://app.example.com
            title: Parent Origin
          description: >-
            Optional. The bare origin of the page that will embed the link in an
            iframe (e.g. ``https://app.example.com``). When provided, the page
            sends the outcome back to that exact window via a browser message.
            Omit it when opening the link as a full page or popup.
      responses:
        '200':
          description: A short-lived, single-use hosted relink link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommonResponse_HostedRelinkBankUrlRead_'
              example:
                status_code: 200
                data:
                  bank_account_id: e5f6a7b8-c9d0-1234-5678-9abcdef01234
                  user_id: b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4
                  relink_bank_url: >-
                    https://connect.finogates.com/payment-methods/add-bank/session/sess_2f8a1c9b4d
                  expires_at: '2026-09-18T10:40:00Z'
                query_generated_time: 1758191000000
        '422':
          description: bank_not_relinkable
          content:
            application/json:
              examples:
                bank_not_relinkable:
                  summary: bank_not_relinkable (error_code 1118)
                  value:
                    status_code: 422
                    data:
                      detail: >-
                        This bank account was not connected through the instant
                        bank link, so there is no connection to refresh.
                      code: bank_not_relinkable
                      error_code: 1118
                    query_generated_time: 1750000000000
              schema:
                $ref: '#/components/schemas/CodedErrorResponse'
      security:
        - _AuthenticatedBearer: []
components:
  schemas:
    CommonResponse_HostedRelinkBankUrlRead_:
      properties:
        status_code:
          type: integer
          title: Status Code
          description: HTTP status code for the response.
        data:
          $ref: '#/components/schemas/HostedRelinkBankUrlRead'
          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[HostedRelinkBankUrlRead]
    CodedErrorResponse:
      properties:
        status_code:
          type: integer
          title: Status Code
          description: HTTP status code for the response.
        data:
          $ref: '#/components/schemas/CodedErrorBody'
          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: CodedErrorResponse
      description: Standard envelope wrapping a :class:`CodedErrorBody`.
    HostedRelinkBankUrlRead:
      properties:
        bank_account_id:
          type: string
          format: uuid
          title: Bank Account Id
        user_id:
          type: string
          format: uuid
          title: User Id
        relink_bank_url:
          type: string
          title: Relink Bank Url
          description: >-
            Iframe-ready URL of the hosted relink page. Short-lived (roughly 10
            minutes). Treat as a single-use credential.
        expires_at:
          type: string
          format: date-time
          title: Expires At
          description: Absolute UTC expiry.
      type: object
      required:
        - bank_account_id
        - user_id
        - relink_bank_url
        - expires_at
      title: HostedRelinkBankUrlRead
      description: |-
        Response body for ``GET /v1/platform/bank/relink/{bank_account_id}``.

        The same contract as :class:`HostedAddBankUrlRead`: a public-safe,
        single-use hosted page URL, no provider names, no internal identifiers.
    CodedErrorBody:
      properties:
        detail:
          type: string
          title: Detail
          description: Human-readable error message.
        code:
          type: string
          title: Code
          description: Stable string error code — the canonical value to branch on.
        error_code:
          type: integer
          title: Error Code
          description: >-
            Numeric custom error code from the Finogate registry. Unique per
            condition and stable forever.
      type: object
      required:
        - detail
        - code
        - error_code
      title: CodedErrorBody
      description: >-
        The ``data`` payload of a coded-error response.


        Condition-specific extras (e.g. ``remaining_time``) may also appear;
        only

        the always-present fields are typed here.
  securitySchemes:
    _AuthenticatedBearer:
      type: oauth2
      flows:
        password:
          scopes: {}
          tokenUrl: /v1/platform/auth/token

````