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

# Get an open banking payment

> Retrieve an open banking payment and its current status. Use it when the customer returns to your `redirectUrl`, to show the payment's state until the `OPEN_BANKING_PAYMENT` webhook arrives.



## OpenAPI

````yaml /openapi.yaml get /internal-accounts/{id}/open-banking-payments/{openBankingPaymentId}
openapi: 3.1.0
info:
  title: Grid API
  description: >
    API for managing global payments on the open Money Grid. Built by
    Lightspark. See the full documentation at https://docs.lightspark.com/.
  version: '2025-10-13'
  contact:
    name: Lightspark Support
    email: support@lightspark.com
  license:
    name: Proprietary
    url: https://lightspark.com/terms
servers:
  - url: https://api.lightspark.com/grid/2025-10-13
    description: Production server
security:
  - BasicAuth: []
  - AgentAuth: []
tags:
  - name: Platform Configuration
    description: >-
      Platform configuration endpoints for managing global settings. You can
      also configure these settings in the Grid dashboard.
  - name: Customers
    description: >-
      Customer management endpoints for creating and updating customer
      information
  - name: Contact Verification
    description: >-
      Endpoints for verifying a customer's email and phone via one-time codes.
      Required only for customers whose payment provider mandates contact
      verification (e.g. EU customers); other providers return 409.
  - name: Strong Customer Authentication
    description: >-
      Endpoints for authorizing money-movement operations that require Strong
      Customer Authentication. Relevant only for customers in a region where SCA
      is required (e.g. EU); customers outside SCA-regulated regions never see
      an SCA challenge and these endpoints return 409.
  - name: KYC/KYB Verifications
    description: >-
      Endpoints for Know Your Customer (KYC) and Know Your Business (KYB)
      verification, including managing beneficial owners and triggering
      verification for customers.
  - name: Documents
    description: >-
      Endpoints for uploading and managing verification documents for customers
      and beneficial owners. Supports KYC and KYB document requirements.
  - name: Internal Accounts
    description: >-
      Internal account management endpoints for creating and managing internal
      accounts
  - name: Periodic Statements
    description: >
      Build, deliver, and evidence a Regulation E periodic statement for a
      customer's internal account. A statement period is a calendar month in US
      Central time (`America/Chicago`).


      A statement is issued for each customer's own USD internal account and
      covers their whole balance. Money received through a rule-based account
      appears on its owner's statement; rule-based, bulk settlement and
      platform-owned accounts have no statement of their own.


      **1. The statement — `GET
      /internal-accounts/{id}/balance-changes?startDate=&endDate=`**


      One row per change to the balance, in the order the money moved, with the
      opening and closing balances for the window in the same response. Page
      until `hasMore` is false, then assert this identity across every page
      before you render anything:


      ```

      openingBalance + Σ(data[].amount) == closingBalance

      ```


      If it does not hold, do not send the statement; contact support instead.
      `startDate` and `endDate` bound a half-open window `[startDate, endDate)`:
      for a monthly statement, pass the first instant of the month and the first
      instant of the following month, both in US Central time (for August 2026,
      `2026-08-01T00:00:00-05:00` and `2026-09-01T00:00:00-05:00`). Grid records
      a statement as fetched only for a window that is exactly one such month.


      **2. The receipt — `POST /internal-accounts/{id}/confirm-statement`**


      Once a month, after you have pulled and issued a period's statement, send
      a receipt with the `statementMonth` it covers. Grid stores it as the
      delivery record for that account and period. Sending it again is harmless:
      the first receipt's time is kept.


      **Timing**


      A window whose card settlement has not closed is refused with `409
      NOT_YET_AVAILABLE` rather than answered with figures that could still
      change; retry once it has settled.
  - name: External Accounts
    description: >-
      External account management endpoints for creating and managing external
      bank accounts
  - name: Same-Currency Transfers
    description: >-
      Deprecated endpoints for transferring funds between internal and external
      accounts with the same currency. Use the quote endpoints under
      Cross-Currency Transfers instead, which now serve same-currency transfers
      as well.
  - name: Cross-Currency Transfers
    description: >-
      Endpoints for creating and confirming quotes for transfers, both
      same-currency and cross-currency
  - name: Payout Runs
    description: >-
      Endpoints for paying many recipients from one internal account in one
      request, and for reconciling the result
  - name: Settlement Rules
    description: >-
      Endpoints for standing instructions that split a customer's matching
      incoming payments among recipients as soon as the payments complete
  - name: Transactions
    description: Endpoints for retrieving transaction information
  - name: Webhooks
    description: Webhook endpoints and configuration for receiving notifications
  - name: Invitations
    description: Endpoints for creating, claiming and managing UMA invitations
  - name: Sandbox
    description: Endpoints to trigger test cases in sandbox
  - name: API Tokens
    description: Endpoints to programmatically manage API tokens
  - name: Exchange Rates
    description: >-
      Endpoints for retrieving cached foreign exchange rates. Rates are cached
      for approximately 5 minutes and include platform-specific fees.
  - name: Discoveries
    description: >-
      Endpoints for discovering available payment rails, banks, and providers
      for a given country and currency corridor.
  - name: Embedded Wallet Auth
    description: >-
      Endpoints for registering and verifying end-user authentication
      credentials (email OTP, OAuth, passkey) used to sign Embedded Wallet
      actions.
  - name: Agent Management
    description: >-
      Endpoints for creating and managing agents, called by the partner's
      backend using platform credentials. Covers the full agent lifecycle:
      creation, policy configuration, pausing, deletion, the device code
      installation flow, and approving or rejecting actions initiated by agents.
  - name: Agent Operations
    description: >-
      Endpoints called by the agent itself using its own credentials (obtained
      via device code redemption). Scoped to the agent's associated customer —
      all requests automatically operate on behalf of that customer and are
      subject to the agent's policy. When an action requires approval, Grid
      holds it as a pending agent action that the platform approves or rejects
      via `POST /agents/{agentId}/actions/{actionId}/approve` or `.../reject`.
  - name: Claimable Payouts
    description: >-
      Endpoints the platform's claim page calls for a claimable payout an agent
      sent to a person by phone number or email: issue the claim token for the
      recipient's link, look the payout up by it, list how Grid can pay her,
      lock a quote to her account and confirm it.
  - name: Cards
    description: >-
      Card management endpoints. Issue debit cards against an internal account,
      freeze / unfreeze, close, manage a card's funding source, and list card
      transactions.
  - name: Stablecoins
    description: >-
      Stablecoin issuance endpoints. Link provider accounts, register
      provider-created stablecoins, create direct mint/burn issuer operations,
      and track operation status.
  - name: Embedded Care
    description: |
      A support chat between the cardholder and Lightspark's care agent, driven
      from the partner's own app. The platform calls with its ordinary Grid
      credential, but the person typing is the cardholder rather than the
      caller, so reaching that cardholder's account takes a second proof: an
      SMS code they send into the chat, after which the partner carries a
      session token in the `X-Ls-Care-Session` header.

      **The surface is two routes, and verification happens inside the
      conversation.**

      1. **Open the chat.** `POST /care/chats/{chatId}/messages` with an empty
         `message`, addressed to the cardholder as `Customer:<uuid>`. Returns
         the chat's id and the agent's opening line in `reply`, which is what
         a chat window renders before anybody has typed. Sends no SMS, needs
         no `Idempotency-Key` and consumes none, and is safe to call again: a
         widget that reloaded gets the same chat back, this time without a
         `reply`.
      2. **Send the cardholder's first message.** The same route with their
         text and an `Idempotency-Key` header. One turn runs synchronously and
         the agent's answer comes back in `reply`. On a chat that cannot yet
         reach the account this call also texts the cardholder a code, and the
         agent's `reply` asks for it.
      3. **The cardholder sends the code as an ordinary message.** When it is
         correct, the response to that turn carries `sessionToken` and
         `expiresAt`. Send that token as the `X-Ls-Care-Session` header on
         every message from then on. A code that does not match is answered in
         `reply`, and the cardholder can simply send it again.
      4. **Close the chat** with `DELETE /care/chats/{chatId}` when the
         cardholder is done. Every response also carries `chatEnded`, and the
         agent can end the chat itself: when `chatEnded` is true, the closing
         line is in `reply` and the chat takes no further messages, so stop
         sending to it. An opening addressed to that `CareChat:<id>` answers
         `409 CARE_CHAT_ENDED`; address the cardholder as `Customer:<uuid>`
         to open a new chat.

      **Render `redactedCustomerMessage` if present, then `reply` if
      present.** That one rule covers an opening, a resume and a turn.

      **A cardholder whose code never arrived asks the agent for another
      one.** The agent sends a new code to the number on file and says so in
      its `reply`. There is no separate route for it.

      **The verification fields are optional hints.** `verificationRequired`
      and `codeLength` let an app show a dedicated one-time-code input of the
      right length, marked as a one-time code so iOS and Android offer to fill
      it from the SMS. A partner can ignore them, since the agent asks for the
      code in its reply and says where it went, and the app still sends the
      code as an ordinary message.

      Step 1 is optional. A message addressed to a `Customer:` id opens that
      cardholder's chat if they have none, so a partner whose cardholder has
      just typed something spends one call rather than two.

      A cardholder who has not verified yet is never a `401`, because the
      first message from every new cardholder is unverified and a `401` there
      would be indistinguishable from a bad credential. On these endpoints a
      `401` means the platform's Grid credential is wrong, the session token
      presented is malformed, or a replay lacks the session token its original
      request required.

      **Verification expires, and a lost session is recoverable in the
      chat.** A chat reaches the cardholder's account only while its
      verification is newer than the session lifetime, fifteen minutes in the
      default deployment, which is also how long a session token lives. Past
      that window a message gets a fresh code, and the agent asks the
      cardholder to send it back inside the conversation, which hands the
      partner the next session token. A new message sent with no
      `X-Ls-Care-Session` header, or with a token past its expiry, on a chat
      whose verification is still current is treated the same way: the
      verification is cancelled before the turn runs, a new code is sent, and
      the agent asks for it. So a client that lost its token, or held one too
      long, simply keeps sending messages. Only a token that is malformed, or
      that was minted for another platform, chat or cardholder, is refused.

      Two things an integration has to get right:

      - **Render `redactedCustomerMessage`, never your own copy of what was
        typed.** Grid masks card numbers and other sensitive digit strings in
        it. A UI that renders its own copy of the input instead puts a card
        number the cardholder pasted back on their screen unmasked, and into
        your logs.
      - **The session token is returned once and is never re-readable.** No
        endpoint hands it back, it cannot be revoked, and it is short-lived by
        design. Hold it for the life of the cardholder's session. It arrives
        on the message response to the turn in which the cardholder sent their
        code, and on no other. Losing it costs the cardholder a new code, never
        access to the chat.

      Some things are absent by construction, so no integration can come to
      depend on them: nothing returns a transcript or an earlier turn's reply
      (retrying under the original `Idempotency-Key` is how an answer that was
      produced but not delivered is recovered; a replay requires the same
      session token its original request required and never carries a
      `sessionToken`, so a lost token is recovered by sending the cardholder's
      next message as a new message, which verifies them again), nothing sets
      a verification state, and nothing changes the number a code is sent to.

      Errors from these endpoints carry `code` and `reason` only (see the
      `CareError` schema), unlike the `Error4xx` schemas used elsewhere in this
      specification.
paths:
  /internal-accounts/{id}/open-banking-payments/{openBankingPaymentId}:
    parameters:
      - name: id
        in: path
        description: The ID of the EUR internal account the payment funds.
        required: true
        schema:
          type: string
        example: InternalAccount:019542f5-b3e7-1d02-0000-000000000005
      - name: openBankingPaymentId
        in: path
        description: The ID of the open banking payment.
        required: true
        schema:
          type: string
        example: OpenBankingPayment:019542f5-b3e7-1d02-0000-000000000020
    get:
      tags:
        - Internal Accounts
      summary: Get an open banking payment
      description: >-
        Retrieve an open banking payment and its current status. Use it when the
        customer returns to your `redirectUrl`, to show the payment's state
        until the `OPEN_BANKING_PAYMENT` webhook arrives.
      operationId: getOpenBankingPayment
      responses:
        '200':
          description: The open banking payment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenBankingPayment'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Internal account or open banking payment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
      security:
        - BasicAuth: []
components:
  schemas:
    OpenBankingPayment:
      type: object
      required:
        - id
        - internalAccountId
        - customerId
        - status
        - amount
        - authorizationUrl
        - redirectUrl
        - reference
        - expiresAt
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          description: System-generated unique identifier for the open banking payment.
          example: OpenBankingPayment:019542f5-b3e7-1d02-0000-000000000020
        internalAccountId:
          type: string
          description: The EUR internal account the payment funds.
          example: InternalAccount:019542f5-b3e7-1d02-0000-000000000005
        customerId:
          type: string
          description: >-
            The customer who owns the internal account and pays from their own
            bank.
          example: Customer:019542f5-b3e7-1d02-0000-000000000001
        status:
          $ref: '#/components/schemas/OpenBankingPaymentStatus'
        amount:
          $ref: '#/components/schemas/CurrencyAmount'
          description: The amount requested from the customer's bank, in `EUR`.
        authorizationUrl:
          type: string
          format: uri
          description: >-
            Send the customer here to choose their bank and approve the payment.
            Open it in the customer's browser or a web view rather than an
            iframe, since many banks hand off to their own app to approve. In
            sandbox it opens a Grid page that simulates the bank.
          example: https://pay.example-provider.com/consent/7f3a9c1e
        redirectUrl:
          type: string
          format: uri
          description: The page the customer returns to, as sent on create.
          example: https://app.example.com/top-up/return
        reference:
          type: string
          description: >-
            The payment reference the customer's bank sends with the funds, set
            by Grid. It appears on the customer's bank statement.
          example: GRIDOB7F3A9C1E
        incomingTransactionId:
          type: string
          description: >-
            The incoming transaction that credited the internal account. Set
            once the credit arrives, which can be shortly after the payment
            becomes `COMPLETED`.
          example: Transaction:019542f5-b3e7-1d02-0000-000000000021
        failureReason:
          type: string
          description: >-
            Why the payment did not complete, when Grid knows. Set only when
            `status` is `FAILED`.
          example: The customer cancelled the payment at their bank.
        expiresAt:
          type: string
          format: date-time
          description: >-
            The deadline for the customer to approve the payment, after which
            `authorizationUrl` stops working. A payment the customer has not
            approved by then becomes `EXPIRED`. One approved in time stays
            `PENDING` until the bank sends the funds or refuses them.
          example: '2026-11-19T15:02:00Z'
        createdAt:
          type: string
          format: date-time
          description: When the payment was created.
          example: '2026-11-19T14:47:00Z'
        updatedAt:
          type: string
          format: date-time
          description: When the payment last changed.
          example: '2026-11-19T14:47:00Z'
    Error401:
      type: object
      required:
        - reason
        - code
      properties:
        code:
          type: string
          description: >
            | Error Code | Description |

            |------------|-------------|

            | UNAUTHORIZED | Issue with API credentials |

            | INVALID_SIGNATURE | Signature header is invalid |

            | WALLET_SIGNATURE_MISSING | The `Grid-Wallet-Signature` header is
            required for this Embedded Wallet action but was not supplied |

            | WALLET_SIGNATURE_MALFORMED | The `Grid-Wallet-Signature` header
            could not be parsed (bad encoding, structure, or fields) |

            | WALLET_SIGNATURE_BODY_MISMATCH | The `Grid-Wallet-Signature` was
            computed over a different request body than the one received |

            | WALLET_SIGNATURE_INVALID | The `Grid-Wallet-Signature` failed
            cryptographic verification against the registered credential |

            | REQUEST_ID_MISSING | The `Request-Id` header is required on the
            signed retry but was not supplied (paired with
            `Grid-Wallet-Signature`) |
          enum:
            - UNAUTHORIZED
            - INVALID_SIGNATURE
            - WALLET_SIGNATURE_MISSING
            - WALLET_SIGNATURE_MALFORMED
            - WALLET_SIGNATURE_BODY_MISMATCH
            - WALLET_SIGNATURE_INVALID
            - REQUEST_ID_MISSING
        reason:
          type: string
          description: Error message
        details:
          type: object
          description: Additional error details
          additionalProperties: true
    Error404:
      type: object
      required:
        - reason
        - code
      properties:
        code:
          type: string
          description: >
            | Error Code | Description |

            |------------|-------------|

            | TRANSACTION_NOT_FOUND | Transaction not found |

            | INVITATION_NOT_FOUND | Invitation not found |

            | USER_NOT_FOUND | Customer not found |

            | QUOTE_NOT_FOUND | Quote not found |

            | LOOKUP_REQUEST_NOT_FOUND | Lookup request not found |

            | TOKEN_NOT_FOUND | Token not found |

            | BULK_UPLOAD_JOB_NOT_FOUND | Bulk upload job not found |

            | REFERENCE_NOT_FOUND | Reference not found |

            | UMA_NOT_FOUND | The UMA address is well-formed but no receiver
            exists at the counterparty VASP |

            | STABLECOIN_PROVIDER_ACCOUNT_NOT_FOUND | Stablecoin provider
            account link not found |

            | ACCOUNT_NOT_FOUND | Account not found |

            | AUTH_METHOD_NOT_FOUND | Authentication credential not found |

            | CUSTOMER_NOT_FOUND | Customer not found |

            | DOCUMENT_HOLDER_NOT_FOUND | Document holder not found |

            | NOT_FOUND | The requested resource was not found |

            | PAYMENT_URL_NOT_FOUND | Payment URL not found |

            | PLATFORM_NOT_FOUND | Platform not found |

            | REQUEST_NOT_FOUND | Pending request not found |

            | SESSION_NOT_FOUND | Session not found |

            | STABLECOIN_EXTERNAL_ACCOUNT_NOT_FOUND | Stablecoin external
            account not found |

            | STABLECOIN_NOT_FOUND | Stablecoin not found |

            | STABLECOIN_OPERATION_NOT_FOUND | Stablecoin operation not found |

            | VERIFICATION_NOT_FOUND | Verification not found |

            | PAYMENT_DOCUMENT_NOT_FOUND | Payment document not found. On `POST
            /quotes`, `details.documentIds` lists each ID in `documentIds` that
            matches no document of the sender |

            | SPENDING_RULE_NOT_FOUND | The agent has no spending rule in force
            |

            | SPENDING_RULE_DRAFT_NOT_FOUND | Spending rule draft not found for
            this agent |

            | SPENDING_RULE_MERCHANT_ANSWER_NOT_FOUND | The owner's answer about
            a merchant was not found for this agent |
          enum:
            - TRANSACTION_NOT_FOUND
            - INVITATION_NOT_FOUND
            - USER_NOT_FOUND
            - QUOTE_NOT_FOUND
            - LOOKUP_REQUEST_NOT_FOUND
            - TOKEN_NOT_FOUND
            - BULK_UPLOAD_JOB_NOT_FOUND
            - REFERENCE_NOT_FOUND
            - UMA_NOT_FOUND
            - STABLECOIN_PROVIDER_ACCOUNT_NOT_FOUND
            - ACCOUNT_NOT_FOUND
            - AUTH_METHOD_NOT_FOUND
            - CUSTOMER_NOT_FOUND
            - DOCUMENT_HOLDER_NOT_FOUND
            - NOT_FOUND
            - PAYMENT_URL_NOT_FOUND
            - PLATFORM_NOT_FOUND
            - REQUEST_NOT_FOUND
            - SESSION_NOT_FOUND
            - STABLECOIN_EXTERNAL_ACCOUNT_NOT_FOUND
            - STABLECOIN_NOT_FOUND
            - STABLECOIN_OPERATION_NOT_FOUND
            - VERIFICATION_NOT_FOUND
            - PAYMENT_DOCUMENT_NOT_FOUND
            - SPENDING_RULE_NOT_FOUND
            - SPENDING_RULE_DRAFT_NOT_FOUND
            - SPENDING_RULE_MERCHANT_ANSWER_NOT_FOUND
        reason:
          type: string
          description: Error message
        details:
          type: object
          description: Additional error details
          additionalProperties: true
    Error500:
      type: object
      required:
        - reason
        - code
      properties:
        code:
          type: string
          description: |
            | Error Code | Description |
            |------------|-------------|
            | GRID_SWITCH_ERROR | Grid switch error |
            | INTERNAL_ERROR | Internal server or UMA error |
          enum:
            - GRID_SWITCH_ERROR
            - INTERNAL_ERROR
        reason:
          type: string
          description: Error message
        details:
          type: object
          description: Additional error details
          additionalProperties: true
    OpenBankingPaymentStatus:
      type: string
      enum:
        - PENDING
        - COMPLETED
        - FAILED
        - EXPIRED
      description: >
        | Status | Description |

        |--------|-------------|

        | `PENDING` | Waiting for the customer to approve the payment at their
        bank, or for the bank to send it |

        | `COMPLETED` | The bank sent the payment. The funds credit the internal
        account as an incoming transaction, reported by its own
        `INCOMING_PAYMENT` webhook |

        | `FAILED` | The customer cancelled, or their bank refused the payment.
        No funds move |

        | `EXPIRED` | The customer did not approve the payment before
        `expiresAt`. No funds move |
    CurrencyAmount:
      type: object
      required:
        - amount
        - currency
      properties:
        amount:
          type: integer
          format: int64
          description: >-
            Amount in the smallest unit of the currency (e.g., cents for
            USD/EUR, satoshis for BTC)
          example: 12550
        currency:
          $ref: '#/components/schemas/Currency'
    Currency:
      type: object
      properties:
        code:
          type: string
          description: >-
            Three-letter currency code (ISO 4217) for fiat currencies. Some
            cryptocurrencies may use their own ticker symbols (e.g. "BTC" for
            Bitcoin, "USDC" for USDC, etc.)
          example: USD
        name:
          type: string
          description: Full name of the currency
          example: United States Dollar
        symbol:
          type: string
          description: Symbol of the currency
          example: $
        decimals:
          type: integer
          description: Number of decimal places for the currency
          minimum: 0
          example: 2
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: >-
        API token authentication using format `<api token id>:<api client
        secret>`
    AgentAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer token authentication for agent-scoped endpoints. The token is the
        `accessToken` returned when redeeming a device code via `POST
        /agents/device-codes/redeem`. Agent credentials are user-scoped: all
        requests are automatically bound to the agent's associated customer and
        subject to the agent's policy.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.