> ## Documentation Index > Fetch the complete documentation index at: https://agents-docs.lightspark.com/llms.txt > Use this file to discover all available pages before exploring further. # Approve a pending incoming payment > Approve a pending incoming payment that was previously acknowledged with a 202 response. This endpoint allows platforms to asynchronously approve payments after async processing. ## OpenAPI ````yaml /openapi.yaml post /transactions/{transactionId}/approve 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 transactions 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 a request requires approval, it is held as an agent action in `PENDING_APPROVAL` until the platform approves it via `POST /agents/{agentId}/actions/{actionId}/approve` or rejects it. - 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:`. 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:` answers `409 CARE_CHAT_ENDED`; address the cardholder as `Customer:` 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: /transactions/{transactionId}/approve: post: tags: - Transactions summary: Approve a pending incoming payment description: > Approve a pending incoming payment that was previously acknowledged with a 202 response. This endpoint allows platforms to asynchronously approve payments after async processing. operationId: approvePendingPayment parameters: - name: transactionId in: path description: Unique identifier of the transaction to approve required: true schema: type: string requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/ApprovePaymentRequest' responses: '200': description: Payment approved successfully content: application/json: schema: $ref: '#/components/schemas/IncomingTransaction' '400': description: Bad request - Invalid parameters or payment cannot be approved content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error401' '404': description: Transaction not found content: application/json: schema: $ref: '#/components/schemas/Error404' '409': description: >- Conflict - Payment is not in a pending state or has already been processed or timed out. content: application/json: schema: $ref: '#/components/schemas/Error409' '500': description: Internal service error content: application/json: schema: $ref: '#/components/schemas/Error500' security: - BasicAuth: [] components: schemas: ApprovePaymentRequest: type: object properties: receiverCustomerInfo: type: object additionalProperties: true description: >- Information about the recipient, provided by the platform if requested in the original webhook via `requestedReceiverCustomerInfoFields`. IncomingTransaction: title: Incoming Transaction allOf: - $ref: '#/components/schemas/Transaction' - type: object required: - type properties: type: type: string enum: - INCOMING source: $ref: '#/components/schemas/TransactionSourceOneOf' receivedAmount: $ref: '#/components/schemas/CurrencyAmount' description: >- Amount received in the recipient's currency. This is only absent for rule-based account sweeps if the sweep couldn't be quoted. It's always present otherwise. fees: type: integer format: int64 description: >- The total fees available from the receive quote in the smallest unit of the sending currency (eg. cents). minimum: 0 example: 10 reconciliationInstructions: $ref: '#/components/schemas/ReconciliationInstructions' description: Included for all transactions except those with "CREATED" status failureReason: $ref: '#/components/schemas/IncomingTransactionFailureReason' description: >- If the transaction failed, this field provides the reason for failure. Error400: type: object required: - reason - code properties: code: type: string description: > | Error Code | Description | |------------|-------------| | INVALID_INPUT | Invalid input provided. When Grid knows the cause, `details.refusalReason` names it. When a card cannot be issued because the customer record lacks fields, it is `CARDHOLDER_INFO_MISSING` and `details.missingFields` lists them | | END_USER_TERMS_VERSION_NOT_FOUND | The submitted version is not supported for the agreement it was sent for | | MISSING_MANDATORY_USER_INFO | Required customer information is missing | | INVITATION_ALREADY_CLAIMED | Invitation has already been claimed | | INVITATIONS_NOT_CONFIGURED | Invitations are not configured | | INVALID_UMA_ADDRESS | UMA address format is invalid | | INVITATION_CANCELLED | Invitation has been cancelled | | INVALID_RECEIVER | Receiver is invalid | | PARSE_PAYREQ_RESPONSE_ERROR | Error parsing receiver PayReq response | | CERT_CHAIN_INVALID | Counterparty certificate chain is invalid | | CERT_CHAIN_EXPIRED | Counterparty certificate chain has expired | | INVALID_PUBKEY_FORMAT | Counterparty Public key format is invalid | | MISSING_REQUIRED_UMA_PARAMETERS | Counterparty required UMA parameters are missing | | SENDER_NOT_ACCEPTED | The receiving institution declined this sender. Final; a retry returns the same answer | | AMOUNT_OUT_OF_RANGE | Amount is out of range | | INVALID_CURRENCY | Currency is invalid | | INVALID_TIMESTAMP | Timestamp is invalid | | INVALID_NONCE | Nonce is invalid | | INVALID_REQUEST_FORMAT | Request format is invalid | | INVALID_BANK_ACCOUNT | Bank account is invalid | | SELF_PAYMENT | Self payment not allowed | | PARSE_LNURLP_RESPONSE_ERROR | Error parsing LNURLP response | | INVALID_AMOUNT | Amount is invalid | | WEBHOOK_ENDPOINT_NOT_SET | Webhook endpoint is not set | | WEBHOOK_DELIVERY_ERROR | Webhook delivery error | | LOW_QUALITY | Document quality too low to process | | DATA_MISMATCH | Document details don't match provided information | | EXPIRED | Document has expired | | SUSPECTED_FRAUD | Document suspected of being forged or edited | | UNSUITABLE_DOCUMENT | Document type is not accepted or not supported | | INCOMPLETE | Document is missing pages or sides | | EMAIL_OTP_CREDENTIAL_ALREADY_EXISTS | The account holder already has an EMAIL_OTP credential on the target internal account; the holder may have one. Administrators' credentials, added with `POST /auth/admin-credentials`, are not counted | | SMS_OTP_CREDENTIAL_ALREADY_EXISTS | An SMS_OTP credential is already registered on the target internal account; only one SMS OTP credential is supported per internal account at this time | | PASSKEY_CREDENTIAL_ALREADY_EXISTS | A PASSKEY credential with the same WebAuthn credentialId is already registered on the target internal account | | AUTH_CREDENTIAL_VERIFICATION_REQUIRED | The new email or phone number has no verified replacement credential | | AUTH_CREDENTIAL_VERIFICATION_EXPIRED | The replacement credential's verification has expired | | STABLECOIN_PROVIDER_ACCOUNT_INVALID | The stablecoin provider account link is not usable | | STABLECOIN_PROVIDER_ACCOUNT_REVOKED | The stablecoin provider account link has been revoked | | STABLECOIN_PROVIDER_ACCOUNT_SELECTION_REQUIRED | Multiple active provider account links exist; pass `stablecoinProviderAccountId` to select one | | STORED_CARD_VERIFICATION_FAILED | The card's issuer did not confirm the card: its security code, billing address or name did not match. Nothing was stored | | CARDHOLDER_KYC_NOT_APPROVED | The cardholder's KYC status is not `APPROVED`, so a card cannot be issued | | ACCOUNTHOLDER_AGREEMENT_NOT_ACCEPTED | The customer create request omits an accountholder agreement its accounts require | | CARDHOLDER_AGREEMENT_NOT_ACCEPTED | The customer has not accepted the cardholder agreement the platform requires before a card is issued | | TRANSACTION_SIZE_LIMIT_EXCEEDED | The requested amount exceeds the configured maximum single-transaction amount for this trade corridor or withdrawal currency | | EXTERNAL_ACCOUNT_VERIFICATION_REQUIRED | The destination account's ownership must be verified before this transfer can proceed | | INSUFFICIENT_FUNDS | Insufficient funds for this operation | | QUOTE_EXPIRED | The quote has expired; request a new quote | | QUOTE_RATE_UNAVAILABLE | No exchange rate is available for this corridor right now | | STABLECOIN_AMOUNT_NOT_REPRESENTABLE | The amount cannot be represented at the token's precision | | STABLECOIN_BURN_SOURCE_NOT_SUPPORTED | The burn source account cannot be used for this operation | | STABLECOIN_EXTERNAL_ACCOUNT_LINK_FAILED | Linking the external account for stablecoin operations failed | | STABLECOIN_EXTERNAL_ACCOUNT_LINK_METHOD_REQUIRED | The external account needs a link method before it can be used | | STABLECOIN_EXTERNAL_ACCOUNT_NOT_LINKED | The external account is not linked for stablecoin operations | | STABLECOIN_EXTERNAL_ACCOUNT_NOT_SUPPORTED | This external account type is not supported for stablecoin operations | | STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_FAILED | The provider could not link the external account | | STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_REQUIRED | The external account must be linked with the provider first | | STABLECOIN_GRID_OPERATIONS_NOT_ENABLED | The stablecoin is not enabled for Grid operations | | STABLECOIN_NOT_PROVISIONED | The stablecoin is not provisioned for issuer operations | | STABLECOIN_OPERATION_NOT_SUPPORTED | The stablecoin does not support this operation | | STABLECOIN_PROVIDER_ERROR | The stablecoin provider rejected the operation | | STABLECOIN_PROVIDER_SOURCE_NOT_LINKED | The provider source account is not linked | | STABLECOIN_VERIFICATION_FAILED | The stablecoin could not be verified with the provider | | DOCUMENTS_REQUIRED | The destination requires supporting documents for the quote's `purposeOfPayment` that the request did not supply. `details.missingRequirements` lists the requirement ID of each one | | EXACT_AMOUNT_UNAVAILABLE | The quote cannot deliver exactly the requested receiving amount at the current rate; quote again shortly or lock the sending amount | enum: - INVALID_INPUT - END_USER_TERMS_VERSION_NOT_FOUND - MISSING_MANDATORY_USER_INFO - INVITATION_ALREADY_CLAIMED - INVITATIONS_NOT_CONFIGURED - INVALID_UMA_ADDRESS - INVITATION_CANCELLED - INVALID_RECEIVER - PARSE_PAYREQ_RESPONSE_ERROR - CERT_CHAIN_INVALID - CERT_CHAIN_EXPIRED - INVALID_PUBKEY_FORMAT - MISSING_REQUIRED_UMA_PARAMETERS - SENDER_NOT_ACCEPTED - AMOUNT_OUT_OF_RANGE - INVALID_CURRENCY - INVALID_TIMESTAMP - INVALID_NONCE - INVALID_REQUEST_FORMAT - INVALID_BANK_ACCOUNT - SELF_PAYMENT - PARSE_LNURLP_RESPONSE_ERROR - INVALID_AMOUNT - WEBHOOK_ENDPOINT_NOT_SET - WEBHOOK_DELIVERY_ERROR - LOW_QUALITY - DATA_MISMATCH - EXPIRED - SUSPECTED_FRAUD - UNSUITABLE_DOCUMENT - INCOMPLETE - EMAIL_OTP_CREDENTIAL_ALREADY_EXISTS - SMS_OTP_CREDENTIAL_ALREADY_EXISTS - PASSKEY_CREDENTIAL_ALREADY_EXISTS - AUTH_CREDENTIAL_VERIFICATION_REQUIRED - AUTH_CREDENTIAL_VERIFICATION_EXPIRED - STABLECOIN_PROVIDER_ACCOUNT_INVALID - STABLECOIN_PROVIDER_ACCOUNT_REVOKED - STABLECOIN_PROVIDER_ACCOUNT_SELECTION_REQUIRED - STORED_CARD_VERIFICATION_FAILED - CARDHOLDER_KYC_NOT_APPROVED - ACCOUNTHOLDER_AGREEMENT_NOT_ACCEPTED - CARDHOLDER_AGREEMENT_NOT_ACCEPTED - TRANSACTION_SIZE_LIMIT_EXCEEDED - EXTERNAL_ACCOUNT_VERIFICATION_REQUIRED - INSUFFICIENT_FUNDS - QUOTE_EXPIRED - QUOTE_RATE_UNAVAILABLE - STABLECOIN_AMOUNT_NOT_REPRESENTABLE - STABLECOIN_BURN_SOURCE_NOT_SUPPORTED - STABLECOIN_EXTERNAL_ACCOUNT_LINK_FAILED - STABLECOIN_EXTERNAL_ACCOUNT_LINK_METHOD_REQUIRED - STABLECOIN_EXTERNAL_ACCOUNT_NOT_LINKED - STABLECOIN_EXTERNAL_ACCOUNT_NOT_SUPPORTED - STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_FAILED - STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_REQUIRED - STABLECOIN_GRID_OPERATIONS_NOT_ENABLED - STABLECOIN_NOT_PROVISIONED - STABLECOIN_OPERATION_NOT_SUPPORTED - STABLECOIN_PROVIDER_ERROR - STABLECOIN_PROVIDER_SOURCE_NOT_LINKED - STABLECOIN_VERIFICATION_FAILED - DOCUMENTS_REQUIRED - EXACT_AMOUNT_UNAVAILABLE reason: type: string description: Error message details: type: object description: >- Additional error details. Shape varies by `code`. For field-validation errors on submit endpoints (e.g. `POST /customers`, `PATCH /customers/{id}`), `details.errors[]` enumerates every invalid field so platforms can render form-field-level UX for the entire request in a single round-trip. properties: errors: type: array description: >- One entry per invalid field. Present on field-validation errors from submit endpoints. items: $ref: '#/components/schemas/FieldError' missingRequirements: type: array description: >- The requirement ID of each required document that the quote request did not supply. Present on `DOCUMENTS_REQUIRED`. items: $ref: '#/components/schemas/PaymentDocumentRequirementId' refusalReason: $ref: '#/components/schemas/RefusalReason' missingFields: type: array description: >- Each customer field the request needs but the customer record lacks, named as in `CustomerInfoFieldName` (for example `PHONE_NUMBER`). Present with refusal reason `CARDHOLDER_INFO_MISSING`. Grid may name fields not yet listed there. items: type: string example: PHONE_NUMBER additionalProperties: true 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 | 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 reason: type: string description: Error message details: type: object description: Additional error details additionalProperties: true Error409: type: object required: - reason - code properties: code: type: string description: > | Error Code | Description | |------------|-------------| | TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL | Transaction is not pending platform approval | | TRANSACTION_NOT_CANCELLABLE | Transaction has already settled or is otherwise past the point where it can be cancelled | | UMA_ADDRESS_EXISTS | UMA address already exists | | EMAIL_OTP_EMAIL_ALREADY_EXISTS | Email address is already associated with an EMAIL_OTP credential | | PASSKEY_ALREADY_ENROLLED | The customer already has the most passkeys allowed (two). Delete one before enrolling another | | SCA_SESSION_REQUIRED | The customer's Strong Customer Authentication login session is missing or expired. Re-authenticate the customer, then retry the request. Distinct from a `401`, which means the platform's own API credentials were rejected | | BENEFICIARY_NOT_TRUSTED | The external account must be a trusted beneficiary before it can be used here. Trust it first via `POST /customers/external-accounts/{externalAccountId}/trust` (and its `/confirm`), then retry | | BENEFICIARY_TRUSTED | The external account is currently a trusted beneficiary, so it cannot be deleted. Untrust it first via `POST /customers/external-accounts/{externalAccountId}/untrust` (and its `/confirm`), then delete | | BANK_ACCOUNT_VALIDATION_PENDING | The US bank account on this request is still being validated. Grid verifies a newly added ACH account by sending a micro-entry and waiting out the return window, which takes a few banking days. The account is not rejected; retry once validation completes. A permanently failed account returns `400 INVALID_BANK_ACCOUNT` instead | | INVALID_STATE_TRANSITION | The requested card `status` transition is not one of `ACTIVE ⇄ FROZEN` or `ACTIVE \| FROZEN → CLOSED`, or the card cannot be unfrozen by the platform because Grid froze it for review, it was frozen as `COMPROMISED`, or its customer is not `ACTIVE` | | CARD_ALREADY_CLOSED | `status: CLOSED` was requested for a card that is already `CLOSED` | | CARD_NOT_MUTABLE | The card is `CLOSED`, so it can no longer be mutated | | PIN_CHANGE_REQUIRED | The card's PIN unblock allowance is consumed for seven days. Change the PIN to recover sooner. `details.pinUnblockAvailableAt` gives the next allowed unblock time | | AGENT_CARD_EXISTS | The agent already holds a card that is not `CLOSED`, so it cannot issue another. Close that card first | | PURCHASE_CARD_LIMIT_REACHED | The agent already holds the most open purchase cards allowed, counting purchase cards awaiting approval. Use or close one first | | CARD_LIMIT_REACHED | The platform has reached the maximum number of live cards it may hold, or the cardholder already holds a card and the platform is limited to one per cardholder. Closing a card frees its slot; contact Lightspark to raise the limit | | STABLECOIN_GRID_ENABLEMENT_NOT_REQUESTABLE | Grid enablement can only be requested while the stablecoin is `NOT_ENABLED` (a repeat request while already `PENDING_APPROVAL` succeeds). `ENABLING`, `ENABLED` and `DISABLED` are driven by Lightspark and cannot be requested | | NOT_YET_AVAILABLE | The request is valid, but its result is not available yet because the data it depends on could still change. Retry later. `reason` says what is outstanding. For balance changes, card settlement for a window boundary has not closed | | CONFLICT | Generic resource-state conflict. Returned, for example, when `platformCustomerId` on a customer create call collides with an existing active customer on the same platform. When the cardholder already holds the one card the platform allows, `details.refusalReason` is `CARDHOLDER_HOLDS_CARD` | | DOCUMENT_ALREADY_EXISTS | A document of this type already exists for the holder; replace it with PUT | | DUPLICATE_EXTERNAL_ACCOUNT | The `platformAccountId` is already used, or, without one, the wallet is already registered. When the conflicting account belongs to your platform, `details.externalAccountId` and `details.platformAccountId` identify it; otherwise `details` is omitted | | DUPLICATE_PAY_REQUEST | A pay request with this idempotency key already exists | | OPERATION_IN_PROGRESS | A conflicting Embedded Wallet operation is still in progress | | SMS_OTP_PHONE_NUMBER_ALREADY_EXISTS | The phone number is already associated with an SMS_OTP credential | | STABLECOIN_SYMBOL_ALREADY_EXISTS | A stablecoin with this symbol is already registered | | STABLECOIN_TOKEN_IDENTIFIER_ALREADY_EXISTS | A stablecoin with this token identifier is already registered | | WALLET_NOT_PROVISIONED | The embedded wallet has not been provisioned | | PAYMENT_DOCUMENT_ALREADY_USED | The payment document is already attached to a quote. A document can be used on one quote only, so upload the file again to use it on another quote | | INVOICE_ALREADY_USED | Another quote for the Lightning invoice can still be executed or funded, or was executed. An invoice has one live quote at a time; ask the recipient for a new one, or retry once Grid has closed the earlier quote as expired | enum: - TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL - TRANSACTION_NOT_CANCELLABLE - UMA_ADDRESS_EXISTS - EMAIL_OTP_EMAIL_ALREADY_EXISTS - PASSKEY_ALREADY_ENROLLED - SCA_SESSION_REQUIRED - BENEFICIARY_NOT_TRUSTED - BENEFICIARY_TRUSTED - BANK_ACCOUNT_VALIDATION_PENDING - INVALID_STATE_TRANSITION - CARD_ALREADY_CLOSED - CARD_NOT_MUTABLE - PIN_CHANGE_REQUIRED - AGENT_CARD_EXISTS - PURCHASE_CARD_LIMIT_REACHED - CARD_LIMIT_REACHED - STABLECOIN_GRID_ENABLEMENT_NOT_REQUESTABLE - NOT_YET_AVAILABLE - CONFLICT - DOCUMENT_ALREADY_EXISTS - DUPLICATE_EXTERNAL_ACCOUNT - DUPLICATE_PAY_REQUEST - OPERATION_IN_PROGRESS - SMS_OTP_PHONE_NUMBER_ALREADY_EXISTS - STABLECOIN_SYMBOL_ALREADY_EXISTS - STABLECOIN_TOKEN_IDENTIFIER_ALREADY_EXISTS - WALLET_NOT_PROVISIONED - PAYMENT_DOCUMENT_ALREADY_USED - INVOICE_ALREADY_USED 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 Transaction: type: object required: - id - status - type - direction - destination - customerId - platformCustomerId properties: id: type: string description: Unique identifier for the transaction example: Transaction:019542f5-b3e7-1d02-0000-000000000004 status: $ref: '#/components/schemas/TransactionStatus' pendingReason: $ref: '#/components/schemas/TransactionPendingReason' description: >- Present when compliance review or required customer action is delaying settlement. type: $ref: '#/components/schemas/TransactionType' direction: $ref: '#/components/schemas/TransactionDirection' description: Whether this transaction credits or debits the customer's account. destination: $ref: '#/components/schemas/TransactionDestinationOneOf' ruleBasedAccountId: type: string description: >- The `RULE_BASED` internal account whose deposit this transaction sweeps. Present only on sweep transactions. For these, `source` describes the party that made the deposit when it is known, and is this account otherwise. example: InternalAccount:019542f5-b3e7-1d02-0000-000000000011 customerId: type: string description: System ID of the customer this transaction belongs to example: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: type: string description: Platform-specific ID of the customer this transaction belongs to example: 18d3e5f7b4a9c2 settledAt: type: string format: date-time description: When the payment was or will be settled example: '2025-08-15T14:30:00Z' createdAt: type: string format: date-time description: When the transaction was created example: '2025-08-15T14:25:18Z' updatedAt: type: string format: date-time description: When the transaction was last updated example: '2025-08-15T14:30:00Z' receiptDeliveryConfirmedAt: type: string format: date-time description: >- The time at which the platform confirmed delivery of the receipt to their customer. example: '2025-08-15T14:31:00Z' agentId: type: string description: >- If this transaction was initiated by an agent, the system-generated ID of that agent. Absent for platform-initiated transactions. example: Agent:019542f5-b3e7-1d02-0000-000000000042 description: type: string description: Optional memo or description for the payment example: 'Payment for invoice #1234' sentAmount: $ref: '#/components/schemas/CurrencyAmount' description: Amount sent in the sender's currency exchangeRate: type: number description: >- Number of sending currency units per receiving currency unit. The rate is fee-exclusive: Grid deducts fees from the sending amount before converting at this rate. exclusiveMinimum: 0 example: 1.08 quoteId: type: string description: The ID of the quote that was used to trigger this payment example: Quote:019542f5-b3e7-1d02-0000-000000000006 refund: $ref: '#/components/schemas/Refund' description: The refund if transaction was refunded. counterpartyInformation: $ref: '#/components/schemas/CounterpartyInformation' TransactionSourceOneOf: oneOf: - $ref: '#/components/schemas/AccountTransactionSource' - $ref: '#/components/schemas/UmaAddressTransactionSource' - $ref: '#/components/schemas/RealtimeFundingTransactionSource' discriminator: propertyName: sourceType mapping: ACCOUNT: '#/components/schemas/AccountTransactionSource' UMA_ADDRESS: '#/components/schemas/UmaAddressTransactionSource' REALTIME_FUNDING: '#/components/schemas/RealtimeFundingTransactionSource' 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' ReconciliationInstructions: type: object minProperties: 1 description: >- Instructions for reconciling a payment with this transaction. For the on-chain transaction to or from an external crypto wallet that is the transaction's own source or destination, use the `railDetails` on the relevant source or destination instead. properties: reference: type: string description: >- Unique reference code to include with the payment to match it with the correct incoming transaction, when available. example: UMA-Q12345-REF transactionHash: deprecated: true type: string description: >- Transaction hash of the settlement transfer, when available. This field reports two different transfers, and only one of them has a replacement today: For a crypto transfer to or from a customer's own external wallet, use the `railDetails` on the relevant source or destination instead — it names the network alongside the hash. That is the transfer this field is deprecated for. For the inter-VASP settlement leg of a UMA payment (e.g. USDC on Solana to the receiving partner), this field remains the only place the hash is reported: a UMA address is not a wallet you hold, so its source and destination carry no `railDetails`. The field will not be removed before that leg has a replacement. example: '0x9f2c6b6f4b6c8f2a8d9e0b1c2d3e4f5061728394a5b6c7d8e9f00112233445566' IncomingTransactionFailureReason: type: string enum: - LNURLP_FAILED - PAY_REQUEST_FAILED - PAYMENT_APPROVAL_WEBHOOK_ERROR - PAYMENT_APPROVAL_TIMED_OUT - OFFRAMP_FAILED - MISSING_MANDATORY_PAYEE_DATA - QUOTE_EXPIRED - QUOTE_EXECUTION_FAILED - COMPLIANCE_REJECTED - COLLECTION_FAILED - SWEEP_AMOUNT_OUT_OF_RANGE - SWEEP_QUOTE_FAILED description: >- Reason for failure of an incoming transaction. This is used to provide more context on why a transaction failed. If the transaction is not in a failed state, this field is omitted. COMPLIANCE_REJECTED means compliance blocked the incoming funds. COLLECTION_FAILED means an inbound bank-rail collection deposit (e.g. a SWIFT wire) failed after arrival and did not credit — most commonly a compliance-screening rejection or an unresolved request for information, on either the collection provider's side or Grid's. Failed collections are returned to the sender per the collection provider's process. A payment that settled into a rule-based account but could not be swept to the destination of the account's rule fails with one of the `SWEEP_*` reasons. A rule-based account never holds a balance, so the funds are moved to the account holder's own account in the same currency. SWEEP_AMOUNT_OUT_OF_RANGE means the amount was outside the band the corridor to the destination can carry — the rule's minimumAmount and maximumAmount give the current band — and SWEEP_QUOTE_FAILED that Grid could not price it. A sweep that was priced and then failed on the way to settlement reports QUOTE_EXECUTION_FAILED, the same as any other payment. FieldError: type: object required: - field description: >- One field-level validation failure. Field-validation errors on submit endpoints (e.g. `POST /customers`, `PATCH /customers/{id}`) emit an array of these under `details.errors` so platforms can render form-field-level UX for every failure in a single round-trip. properties: field: type: string description: Dot-notation path to the offending field. example: identifier constraint: $ref: '#/components/schemas/FieldConstraint' message: type: string description: Human-readable explanation of what's wrong with this field. example: Value is not one of the allowed enum members. PaymentDocumentRequirementId: type: string description: >- A stable identifier for one required document within a purpose's requirements. The same ID means the same requirement across quotes. It is separate from `PaymentDocumentType`. The requirement ID names the document to supply, and the document type names what a file is. The two differ where a requirement accepts alternatives. For example, a file declared as either `PURCHASE_ORDER` or `DELIVERY_SLIP` fills the `SUPPORTING_PROOF` requirement. [Supporting Documents](https://docs.lightspark.com/payouts-and-b2b/payment-flow/send-payment#supporting-documents) lists the IDs each purpose requires. Treat the ID as an opaque value, not a member of a fixed list. Grid may add new IDs as requirements change. example: SUPPORTING_PROOF RefusalReason: type: string description: > Why Grid refused the request, as `details.refusalReason`. Several refusals share one `code`, and `reason` is a message that may be reworded, so branch on this value rather than on `reason`. Treat it as an open set, not a fixed list: Grid may add values, and an unknown one is a refusal without a known cause. | Refusal reason | Status | Description | |----------------|--------|-------------| | `AGENT_API_DISABLED` | 403 | The agent API is not enabled for the platform | | `AGENT_CUSTOMER_INACTIVE` | 403 | The agent's customer is not active | | `AGENT_INACTIVE` | 403 | The agent is paused or deleted | | `AGENT_NO_DELEGATED_KEY` | 403 | The agent holds no active delegated key for the source wallet | | `AGENT_PERMISSION_REQUIRED` | 403 | The agent's policy lacks a permission this call needs. `details.permission` names it | | `AGENT_ACCOUNT_NOT_ALLOWED` | 403 | The agent's policy does not allow the source account or funding source | | `AGENT_DEPOSIT_ACCOUNT_NOT_ALLOWED` | 403 | The agent's policy does not allow deposits to this account | | `AGENT_POLICY_DENIED` | 403 | The agent's policy denied executing the quote. `details.policyDenialReason` says which rule | | `AGENT_QUOTE_HELD` | 403 | The quote cannot be sent and is held for manual follow-up | | `AGENT_CARDS_DISABLED` | 403 | Agent cards are not enabled for the platform | | `AGENT_CARDS_CUSTOMER_NOT_VERIFIED` | 403 | Agent cards need a verified individual customer | | `AGENT_CARD_HANDOVER_DISABLED` | 403 | Handing an agent's card over to its customer is not enabled for the platform | | `AGENT_PURCHASE_CARDS_DISABLED` | 403 | Agent purchase cards are not enabled for the platform | | `AGENT_RECURRING_PURCHASE_CARDS_DISABLED` | 403 | Agent recurring purchase cards are not enabled for the platform | | `AGENT_PURCHASE_CARD_POLICY_DENIED` | 403 | The agent's policy denied the purchase card. `details.policyDenialReason` says which rule | | `STORED_CARDS_DISABLED` | 403 | Stored cards are not enabled for the platform | | `CARDS_DISABLED` | 403 | Cards are not enabled for the platform | | `CARDHOLDER_INFO_MISSING` | 400 | The cardholder record lacks fields a card needs. `details.missingFields` lists them; supply them through the customers API | | `CARDHOLDER_BANK_ACCOUNT_NOT_OPEN` | 400 | The cardholder's USD bank account is not open yet, so no card can be issued until it is | | `CARDHOLDER_COUNTRY_NOT_SUPPORTED` | 400 | The cardholder's address is outside the United States, where agent cards are not offered yet | | `CARDHOLDER_HOLDS_CARD` | 409 | The cardholder already holds a card and the platform allows one per cardholder. Close it before issuing another | | `INVOICE_SUB_SAT_AMOUNT` | 400 | The Lightning invoice's amount is not a whole number of satoshis | | `INVOICE_FUNDS_DEPOSIT` | 400 | The Lightning invoice was issued by Lightspark to fund a deposit and cannot be paid with a send | | `INVOICE_FUNDS_OWN_DEPOSIT` | 400 | The Lightning invoice funds a deposit of the sender's own. Quote a transfer between the customer's accounts instead | example: AGENT_POLICY_DENIED TransactionStatus: type: string enum: - CREATED - PENDING - PENDING_AUTHORIZATION - PROCESSING - COMPLETED - REJECTED - FAILED - REFUNDED - EXPIRED description: > Status of a payment transaction. | Status | Description | |--------|-------------| | `CREATED` | Initial lookup has been created | | `PENDING` | Quote has been created | | `PENDING_AUTHORIZATION` | Awaiting Strong Customer Authentication. Only occurs for customers in a region where SCA is required (e.g. EU). The challenge is carried by the quote, not the transaction — fetch `GET /quotes/{quoteId}` using the transaction's `quoteId`, then authorize its `scaChallenge` via `POST /quotes/{quoteId}/authorize`. | | `PROCESSING` | Funding has been received and payment initiated | | `COMPLETED` | The funds are where settlement put them. A return that takes them back moves the transaction to `FAILED`, and the returned side's `railDetails` shows `RETURNED`. A transaction stays `COMPLETED` through a return only when a later step that can't be undone already used the funds | | `REJECTED` | Receiving institution or wallet rejected payment, payment has been refunded | | `FAILED` | The payment did not reach its destination, or the funds were sent back after it did. Not terminal for an incoming payment: a dishonored return restores the credit and moves it to `COMPLETED`. A returned payout stays `FAILED`, since it has already been refunded. Each step shows on the returned side's `railDetails` | | `REFUNDED` | Deprecated. A refund is reported on the transaction's `refund` object, and the status stays `FAILED` | | `EXPIRED` | Quote has expired. Terminal | TransactionPendingReason: type: string enum: - COUNTERPARTY_DECLARATION_REQUIRED - WALLET_VERIFICATION_REQUIRED - COUNTERPARTY_INFORMATION_REQUIRED - COMPLIANCE_REVIEW description: > Why a transaction is pending. | Reason | Description | |--------|-------------| | `COUNTERPARTY_DECLARATION_REQUIRED` | The customer must declare who controls the sending wallet. | | `WALLET_VERIFICATION_REQUIRED` | The customer must verify ownership of the sending wallet. | | `COUNTERPARTY_INFORMATION_REQUIRED` | Information about the sender is required. | | `COMPLIANCE_REVIEW` | The customer's action is complete and the deposit remains under compliance review. | TransactionType: type: string enum: - INCOMING - OUTGOING - CARD description: Type of transaction TransactionDirection: type: string enum: - CREDIT - DEBIT description: >- Whether the transaction credits (funds in) or debits (funds out) the customer's account. Independent of `type`: an incoming transaction is normally a `CREDIT`, but an inbound ACH pull, for example, is an `INCOMING` transaction with a `DEBIT` direction. TransactionDestinationOneOf: oneOf: - $ref: '#/components/schemas/AccountTransactionDestination' - $ref: '#/components/schemas/UmaAddressTransactionDestination' discriminator: propertyName: destinationType mapping: ACCOUNT: '#/components/schemas/AccountTransactionDestination' UMA_ADDRESS: '#/components/schemas/UmaAddressTransactionDestination' Refund: type: object required: - reference - initiatedAt - status properties: reference: type: string description: The unique reference ID of the refund example: UMA-Q12345-REFUND initiatedAt: type: string format: date-time description: When the refund was initiated example: '2025-08-15T14:30:00Z' settledAt: type: string format: date-time description: When the refund was settled example: '2025-08-15T14:35:00Z' status: $ref: '#/components/schemas/RefundStatus' reason: $ref: '#/components/schemas/RefundReason' CounterpartyInformation: type: object description: >- Additional information about the counterparty, if available and relevant to the transaction and platform. additionalProperties: true example: FULL_NAME: John Sender BIRTH_DATE: '1985-06-15' NATIONALITY: DE AccountTransactionSource: title: Account Source allOf: - $ref: '#/components/schemas/BaseTransactionSource' - type: object required: - accountId - sourceType properties: sourceType: type: string enum: - ACCOUNT accountId: type: string description: Source account identifier example: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 railDetails: $ref: '#/components/schemas/RailDetailsOneOf' onChainTransaction: $ref: '#/components/schemas/OnChainTransaction' deprecated: true description: >- Deprecated. Use `railDetails`, which carries the same hash and network when `paymentRail` is `ONCHAIN`. description: Source account details UmaAddressTransactionSource: title: UMA Address Source allOf: - $ref: '#/components/schemas/BaseTransactionSource' - type: object required: - umaAddress - sourceType properties: sourceType: type: string enum: - UMA_ADDRESS umaAddress: type: string description: UMA address of the sender example: $sender@uma.domain.com description: UMA address source details RealtimeFundingTransactionSource: title: External Funding Source allOf: - $ref: '#/components/schemas/BaseTransactionSource' - type: object required: - currency - sourceType properties: sourceType: type: string enum: - REALTIME_FUNDING customerId: type: string description: The customer on whose behalf the transaction was initiated. example: Customer:019542f5-b3e7-1d02-0000-000000000009 currency: type: string description: Currency code for the funding source example: USDC accountHolderName: type: string deprecated: true description: >- Deprecated. Use `railDetails.bankAccount.accountHolderName`. The name of the originator (sender) of the payment. Still populated on rails without a `railDetails` variant, such as SWIFT. example: John Sender accountIdentifier: type: string deprecated: true description: >- Deprecated. Use `railDetails.bankAccount.accountNumber`. The originator's account number or IBAN. May be masked or partial depending on the rail. Still populated on rails without a `railDetails` variant, such as SWIFT. example: '****6789' bankName: type: string deprecated: true description: >- Deprecated. Use `railDetails.bankAccount.bankName` on wires. The name of the originating bank. Still populated on rails without a `railDetails` variant, such as SWIFT. example: Chase Bank bankIdentifier: type: string deprecated: true description: >- Deprecated. Use `railDetails.bankAccount.routingNumber`. The identifier of the originating bank, such as a routing number, BIC, or SWIFT code. Still populated on rails without a `railDetails` variant, such as SWIFT. example: '021000021' paymentRail: deprecated: true description: >- Deprecated. Use `railDetails.paymentRail`. The payment rail the funds arrived on. Still populated on rails without a `railDetails` variant, such as SWIFT. allOf: - $ref: '#/components/schemas/PaymentRail' remittanceInformation: type: string deprecated: true description: >- Deprecated. Use `railDetails.addenda` for ACH, `railDetails.originatorToBeneficiaryInformation` for wires and `railDetails.remittanceInformation` for RTP and FedNow. Free-form information about the payment provided by the originator. Still populated on rails without a `railDetails` variant, such as SWIFT. example: '12345' endToEndId: type: string deprecated: true description: >- Deprecated. Use `railDetails.endToEndId`. The originator's own end-to-end reference for the payment. Still populated on rails without a `railDetails` variant, such as SWIFT. example: E2E-9f2c6b6f traceNumber: type: string deprecated: true description: >- Deprecated. Use `railDetails.traceNumber` for ACH and `railDetails.imad` for wires. Rail-level tracking identifier for the payment. Still populated on rails without a `railDetails` variant, such as SWIFT. example: '021000020123456' railDetails: $ref: '#/components/schemas/RailDetailsOneOf' onChainTransaction: $ref: '#/components/schemas/OnChainTransaction' deprecated: true description: >- Deprecated. Use `railDetails`, which carries the same hash and network when `paymentRail` is `ONCHAIN`. description: >- Transaction was funded using an external funding source. `railDetails` describes the transfer that delivered the funds; its fields are populated on a best-effort basis depending on what the funding source provides. Rails without a `railDetails` variant, such as SWIFT, carry the originator's details in the deprecated flat fields only. 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 FieldConstraint: type: object description: >- Machine-readable validator hint accompanying a 400 `INVALID_INPUT` error. Consumers use it to drive form UI (input types, dropdowns, masking, length limits) and to pre-validate the field client-side before re-submitting. Fields are additive. properties: format: type: string description: >- Named format the value must satisfy — HTML5 input type names (`email`, `tel`, `url`, `date`, ...) or semantic slugs (`iso3166-1-alpha-2`, `bcp47-language-tag`, `us-ssn`, `e.164`). example: email pattern: type: string description: Regular expression the value must match (JavaScript-flavor). example: ^\d{5}(-\d{4})?$ enum: type: array items: type: string description: Allowed values when the field is drawn from a fixed set. example: - SSN - ITIN - NON_US_TAX_ID minLength: type: integer description: Minimum length in characters. example: 1 maxLength: type: integer description: Maximum length in characters. example: 500 AccountTransactionDestination: title: Account Destination allOf: - $ref: '#/components/schemas/BaseTransactionDestination' - type: object required: - accountId - destinationType properties: destinationType: type: string enum: - ACCOUNT accountId: type: string description: Destination account identifier example: ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123 railDetails: $ref: '#/components/schemas/RailDetailsOneOf' onChainTransaction: $ref: '#/components/schemas/OnChainTransaction' deprecated: true description: >- Deprecated. Use `railDetails`, which carries the same hash and network when `paymentRail` is `ONCHAIN`. description: Destination account details UmaAddressTransactionDestination: title: UMA Address Destination allOf: - $ref: '#/components/schemas/BaseTransactionDestination' - type: object required: - umaAddress - destinationType properties: destinationType: type: string enum: - UMA_ADDRESS umaAddress: type: string description: UMA address of the recipient example: $receiver@uma.domain.com description: UMA address destination details RefundStatus: type: string enum: - PENDING - COMPLETED - FAILED description: Current status of the refund example: COMPLETED RefundReason: type: string enum: - TRANSACTION_FAILED - USER_CANCELLATION - TIMEOUT description: Reason for the refund example: TRANSACTION_FAILED BaseTransactionSource: type: object required: - sourceType properties: sourceType: $ref: '#/components/schemas/TransactionSourceType' currency: type: string description: Currency code for the source example: USD RailDetailsOneOf: description: >- The rail transfer that moved funds for this side of the transaction. `paymentRail` determines the shape: each rail carries its own identifiers. Absent until a rail transfer exists for this side, and on sides whose funds move within Grid. oneOf: - $ref: '#/components/schemas/OnChainRailDetails' - $ref: '#/components/schemas/AchRailDetails' - $ref: '#/components/schemas/WireRailDetails' - $ref: '#/components/schemas/FedNowRailDetails' - $ref: '#/components/schemas/RtpRailDetails' - $ref: '#/components/schemas/SwiftRailDetails' discriminator: propertyName: paymentRail mapping: ONCHAIN: '#/components/schemas/OnChainRailDetails' ACH: '#/components/schemas/AchRailDetails' ACH_SAME_DAY: '#/components/schemas/AchRailDetails' WIRE: '#/components/schemas/WireRailDetails' FEDNOW: '#/components/schemas/FedNowRailDetails' RTP: '#/components/schemas/RtpRailDetails' SWIFT: '#/components/schemas/SwiftRailDetails' OnChainTransaction: type: object required: - transactionHash - network properties: transactionHash: type: string description: >- On-chain transaction hash of the crypto transfer for this leg of the transaction. example: >- h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx network: $ref: '#/components/schemas/CryptoNetwork' description: >- Blockchain network the transaction settled on (mainnet vs test network is determined by your platform environment). PaymentRail: type: string enum: - ACH - ACH_COLOMBIA - ACH_SAME_DAY - BANK_TRANSFER - BRE_B - CIPS - FAST - FASTER_PAYMENTS - FEDNOW - INSTAPAY - MOBILE_MONEY - NEFT - PAYNOW - PESONET - PIX - RTGS - RTP - SEPA - SEPA_INSTANT - SPEI - SWIFT - UNIONPAY - UPI - WIRE description: >- The payment rail used for the transfer. Payment rails represent the underlying payment network or system used to move funds between accounts. `ACH_SAME_DAY` requests same-business-day settlement for a USD payout and is priced separately. It is subject to the NACHA per-entry same-day limit, which the network applies to every originator: $1,000,000 per entry, rising to $10,000,000 on 2027-09-17. A payout above that limit is rejected rather than slowed — check the amount before requesting this rail, or send it over `ACH`, which settles on the standard schedule and has no such limit. `ACH` will settle on the standard next-business-day schedule. Until a date we announce in advance, `ACH` continues to settle same-business-day on production platforms; it already settles next-business-day on sandbox platforms. To guarantee same-day settlement after that date, request `ACH_SAME_DAY`. example: ACH BaseTransactionDestination: type: object required: - destinationType properties: destinationType: $ref: '#/components/schemas/TransactionDestinationType' currency: type: string description: Currency code for the destination example: EUR TransactionSourceType: type: string enum: - ACCOUNT - UMA_ADDRESS - REALTIME_FUNDING description: Type of transaction source example: ACCOUNT OnChainRailDetails: title: On-Chain Transfer type: object required: - paymentRail - transactionHash - network properties: paymentRail: type: string enum: - ONCHAIN transactionHash: type: string description: >- On-chain transaction hash of the crypto transfer for this leg of the transaction. example: >- h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx network: $ref: '#/components/schemas/CryptoNetwork' description: >- Blockchain network the transaction settled on (mainnet vs test network is determined by your platform environment). description: A crypto transfer to or from an external wallet. AchRailDetails: title: ACH Transfer description: A transfer over the ACH network. allOf: - $ref: '#/components/schemas/BaseUsdBankRailDetails' - type: object required: - paymentRail - status properties: paymentRail: $ref: '#/components/schemas/AchPaymentRail' status: $ref: '#/components/schemas/AchRailStatus' traceNumber: type: string description: 15-digit ACH trace number of the entry. example: '021000020123456' statementDescriptor: type: string maxLength: 10 description: >- The entry's Company Entry Description, which the receiving bank shows on the account holder's statement. On payments you originate, this is the quote's `statementDescriptor`, or Grid's default. example: PAYROLL addenda: type: string description: >- Payment-related text carried in the entry's addenda record. On payments you originate, this is the `remittanceInformation` you provided. example: INV-12345 returnedAt: type: string format: date-time description: >- When the receiving bank returned the entry. Present once the entry has been returned, including after a later dishonor or contest. example: '2026-10-01T14:00:00Z' returnCode: type: string pattern: ^R[0-9]{2}$ description: >- The NACHA return reason code the receiving bank returned the entry under, such as `R01` (insufficient funds) or `R10` (customer advises unauthorized). Present whenever `returnedAt` is. Group returns by this code to track your return rate for each reason, or by `returnCategory` for Nacha's threshold categories. NACHA may add codes, so accept any value matching the pattern. example: R01 returnCategory: $ref: '#/components/schemas/AchReturnCategory' description: >- The Nacha return-rate category `returnCode` counts toward. Present only when the code is in one, so a return such as `R01` has `returnCode` but no `returnCategory`. dishonoredAt: type: string format: date-time description: >- When the originating bank dishonored the return. Present once `status` has reached `RETURN_DISHONORED`. example: '2026-10-04T14:00:00Z' contestedAt: type: string format: date-time description: >- When the receiving bank contested the dishonor. Present when `status` is `RETURN_CONTESTED`. example: '2026-10-07T14:00:00Z' reversedAt: type: string format: date-time description: >- When the originator reversed the entry. Present when `status` is `REVERSED`. example: '2026-10-01T14:00:00Z' WireRailDetails: title: Wire Transfer description: A domestic wire over Fedwire. allOf: - $ref: '#/components/schemas/BaseUsdBankRailDetails' - type: object required: - paymentRail - status properties: bankAccount: $ref: '#/components/schemas/WireBankAccountDetails' paymentRail: type: string enum: - WIRE status: $ref: '#/components/schemas/WireRailStatus' imad: type: string description: >- Fedwire Input Message Accountability Data assigned when the wire was sent. example: 20260929MMQFMP9C000123 originatorToBeneficiaryInformation: type: string description: >- Free-form originator-to-beneficiary information (OBI) sent with the wire. example: INV-12345 FedNowRailDetails: title: FedNow Transfer description: An instant payment over the FedNow Service. allOf: - $ref: '#/components/schemas/BaseUsdBankRailDetails' - type: object required: - paymentRail - status properties: paymentRail: type: string enum: - FEDNOW status: $ref: '#/components/schemas/FedNowRailStatus' endToEndId: type: string description: The originator's end-to-end reference for the payment. example: E2E-9f2c6b6f remittanceInformation: type: string description: Unstructured remittance information sent with the payment. example: INV-12345 RtpRailDetails: title: RTP Transfer description: An instant payment over The Clearing House RTP network. allOf: - $ref: '#/components/schemas/BaseUsdBankRailDetails' - type: object required: - paymentRail - status properties: paymentRail: type: string enum: - RTP status: $ref: '#/components/schemas/RtpRailStatus' endToEndId: type: string description: The originator's end-to-end reference for the payment. example: E2E-9f2c6b6f remittanceInformation: type: string description: Unstructured remittance information sent with the payment. example: INV-12345 SwiftRailDetails: title: SWIFT Transfer description: >- An international wire over the SWIFT network. Present on payout destinations. type: object required: - paymentRail properties: paymentRail: type: string enum: - SWIFT uetr: type: string format: uuid description: >- Unique End-to-end Transaction Reference of the wire. Give it to the beneficiary's bank to trace the payment. example: f47bbdd1-3d90-44c4-998d-a02bd814d5d3 CryptoNetwork: type: string enum: - BITCOIN - ETHEREUM - SOLANA - BASE - POLYGON - TRON - PLASMA - ARBITRUM - SPARK description: >- The blockchain network an on-chain transaction settled on. Whether this is the mainnet or a test network (e.g. Solana devnet) is determined by your platform's environment — sandbox platforms operate on test networks, production platforms on mainnet — mirroring how `cryptoNetwork` is interpreted elsewhere in the API. example: SOLANA TransactionDestinationType: type: string enum: - ACCOUNT - UMA_ADDRESS description: Type of transaction destination example: ACCOUNT BaseUsdBankRailDetails: title: Base US Bank Rail Details type: object description: Fields shared by every US bank rail. properties: bankAccount: $ref: '#/components/schemas/UsdBankAccountDetails' settledAt: type: string format: date-time description: When the transfer settled. example: '2026-09-29T15:04:12Z' AchPaymentRail: type: string enum: - ACH - ACH_SAME_DAY AchRailStatus: type: string enum: - PENDING - SETTLED - RETURNED - RETURN_DISHONORED - RETURN_CONTESTED - REVERSED - FAILED description: >- Status of the entry on the ACH network. | Status | Description | |--------|-------------| | `PENDING` | Submitted to the ACH network and not yet settled. | | `SETTLED` | The entry settled. | | `RETURNED` | The receiving bank returned the entry, before or after it settled. | | `RETURN_DISHONORED` | The originating bank dishonored the return, so the returned funds came back. | | `RETURN_CONTESTED` | The receiving bank contested the dishonor, so the funds went back again. | | `REVERSED` | The originator reversed the entry after it settled. | | `FAILED` | The entry was rejected before submission and no funds moved. | A return, dishonor or contest can arrive days after the step before it. This status reports the ACH entry; the transaction's top-level `status` reports where the funds are now. A return moves the transaction to `FAILED`. On an incoming payment, a dishonor brings the credit back and moves it to `COMPLETED`, and a contest moves it to `FAILED` again. A returned payout stays `FAILED` through a dishonor, since it has already been refunded; the rail status still records the dishonor. example: SETTLED AchReturnCategory: type: string enum: - ADMINISTRATIVE - UNAUTHORIZED description: >- The Nacha return-rate category an ACH return counts toward. | Category | Return codes | Description | |----------|--------------|-------------| | `ADMINISTRATIVE` | `R02`, `R03`, `R04` | The account is closed, can't be found, or its number is invalid. | | `UNAUTHORIZED` | `R05`, `R07`, `R10`, `R11`, `R29`, `R51` | The account holder says they didn't authorize the debit. | Nacha sets a separate return-rate threshold for each category. Other return codes, such as `R01` (insufficient funds), belong to neither. example: UNAUTHORIZED WireBankAccountDetails: title: Wire Bank Account Details allOf: - $ref: '#/components/schemas/UsdBankAccountDetails' - type: object properties: bankName: type: string description: Name of the account's bank. example: Chase Bank WireRailStatus: type: string enum: - PENDING - SETTLED - FAILED description: >- Status of the wire on Fedwire. | Status | Description | |--------|-------------| | `PENDING` | Submitted to Fedwire and not yet delivered. | | `SETTLED` | Fedwire delivered the wire. | | `FAILED` | Fedwire or the receiving bank rejected the wire and no funds moved. | example: SETTLED FedNowRailStatus: type: string enum: - PENDING - SETTLED - FAILED description: >- Status of the payment on FedNow. | Status | Description | |--------|-------------| | `PENDING` | Submitted and awaiting the receiving bank's response. | | `SETTLED` | The receiving bank accepted the payment and the funds settled. | | `FAILED` | The receiving bank or the network rejected the payment and no funds moved. | example: SETTLED RtpRailStatus: type: string enum: - PENDING - SETTLED - FAILED description: >- Status of the payment on the RTP network. | Status | Description | |--------|-------------| | `PENDING` | Submitted and awaiting the receiving bank's response. | | `SETTLED` | The receiving bank accepted the payment and the funds settled. | | `FAILED` | The receiving bank or the network rejected the payment and no funds moved. | example: SETTLED UsdBankAccountDetails: title: US Bank Account Details type: object description: >- The account on the other end of the transfer: the sender's account on a source, the recipient's account on a destination. properties: accountHolderName: type: string description: Name of the account holder. example: John Sender routingNumber: type: string description: 9-digit ABA routing number of the account's bank. example: '021000021' accountNumber: type: string description: Account number, masked to its last four digits. example: '****6789' securitySchemes: BasicAuth: type: http scheme: basic description: >- API token authentication using format `:` 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.