> ## 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. # Get platform configuration > Retrieve the current platform configuration ## OpenAPI ````yaml /openapi.yaml get /config 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: /config: get: tags: - Platform Configuration summary: Get platform configuration description: Retrieve the current platform configuration operationId: getPlatformConfig responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/PlatformConfig' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error401' '500': description: Internal service error content: application/json: schema: $ref: '#/components/schemas/Error500' security: - BasicAuth: [] components: schemas: PlatformConfig: type: object properties: id: type: string description: System-generated unique identifier example: PlatformConfig:019542f5-b3e7-1d02-0000-000000000003 umaDomain: type: string pattern: ^[^\u0000-\u001f\u007f]*$ maxLength: 200 description: UMA domain for this platform example: platform.uma.domain proxyUmaSubdomain: type: string pattern: ^[^\u0000-\u001f\u007f]*$ maxLength: 200 description: The subdomain that incoming requests will be proxied to example: platform webhookEndpoint: type: string description: URL where webhook notifications will be sent example: https://api.mycompany.com/webhooks/uma supportedCurrencies: type: array items: $ref: '#/components/schemas/PlatformCurrencyConfig' description: > List of currencies supported by the platform. This is what the platform's customers are able to hold, send, and receive. isRegulatedFinancialInstitution: type: boolean description: > Whether the platform is a regulated financial institution. This is used to determine if the platform's customers must be KYC/KYB'd by Lightspark via the KYC link flow. This can only be set by Lightspark during platform creation. example: false embeddedWalletConfig: $ref: '#/components/schemas/EmbeddedWalletConfig' description: | Embedded-wallet branding and OTP settings for this platform. Present only when the platform has configured embedded-wallet support; omitted otherwise. cardTokenization2faConfig: $ref: '#/components/schemas/CardTokenization2FAConfig' description: > Branding and sender configuration for card-tokenization authentication messages. This configuration is independent of embedded-wallet support. cardConfigs: $ref: '#/components/schemas/CardConfig' description: Platform-level settings for cards issued by this platform. feeConfigs: type: array items: $ref: '#/components/schemas/FeeConfigOneOf' description: | Platform-collected fees that should be added on top of Grid-collected fees. Contains every currently-active fee config for the platform. createdAt: type: string format: date-time description: Creation timestamp example: '2025-06-15T12:30:45Z' updatedAt: type: string format: date-time description: Last update timestamp example: '2025-06-15T12:30:45Z' 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 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 PlatformCurrencyConfig: type: object properties: currencyCode: type: string description: Three-letter currency code (ISO 4217) example: USD minAmount: type: integer format: int64 description: >- Minimum amount that can be sent in the smallest unit of this currency minimum: 0 example: 100 maxAmount: type: integer format: int64 description: >- Maximum amount that can be sent in the smallest unit of this currency minimum: 0 example: 1000000 requiredCounterpartyFields: type: array items: $ref: '#/components/schemas/CounterpartyFieldDefinition' description: >- List of fields which the platform requires from the counterparty institutions about counterparty customers. Platforms can set mandatory to false if the platform does not require the field, but would like to have it available. Some fields may be required by the underlying UMA provider. example: - name: FULL_NAME mandatory: true - name: BIRTH_DATE mandatory: true - name: NATIONALITY mandatory: true providerRequiredCustomerFields: type: array items: $ref: '#/components/schemas/CustomerInfoFieldName' description: >- List of customer info field names that are required by the underlying UMA provider when creating a customer for this currency. These fields must be supplied when creating or updating a customer if this currency is intended to be used by that customer. If no fields are required, this field is omitted. readOnly: true example: - NATIONALITY - BIRTH_DATE providerRequiredCounterpartyCustomerFields: type: array items: $ref: '#/components/schemas/CustomerInfoFieldName' description: >- List of fields that are required by the underlying UMA provider for this currency. If the counterparty does not provide these fields, quote requests will fail. readOnly: true example: - FULL_NAME - COUNTRY_OF_RESIDENCE enabledTransactionTypes: type: array items: $ref: '#/components/schemas/TransactionType' description: List of transaction types that are enabled for this currency. example: - OUTGOING - INCOMING required: - currencyCode - minAmount - maxAmount - requiredCounterpartyFields - enabledTransactionTypes EmbeddedWalletConfig: type: object description: | Per-platform embedded-wallet configuration. Controls branding and OTP behavior for the email sent when a customer authenticates with an EMAIL_OTP credential. Fields omitted from a request are left unchanged. properties: appName: type: string maxLength: 255 description: App name displayed in the default OTP email template. example: Acme Wallet otpLength: type: integer minimum: 6 maximum: 9 description: | Number of digits / characters in the OTP code. Defaults to 6 when not set. example: 6 alphanumeric: type: boolean description: | If true, OTP includes letters in addition to digits. Defaults to numeric-only when not set. example: false expirationSeconds: type: integer minimum: 1 maximum: 600 description: | OTP validity window in seconds. Defaults to 300 when not set. example: 300 sendFromEmailAddress: type: string format: email maxLength: 255 description: Custom sender email address for OTP emails. example: noreply@acme.com sendFromEmailSenderName: type: string maxLength: 255 description: > Custom sender display name. Defaults to "Notifications" when not set. example: Acme Notifications replyToEmailAddress: type: string format: email maxLength: 255 description: Custom reply-to email address for OTP emails. example: support@acme.com logoUrl: type: string format: uri maxLength: 512 description: URL to a PNG logo for the OTP email. Resized to 340x124px. example: https://acme.com/logo.png CardTokenization2FAConfig: type: object description: >- Per-platform branding for authentication codes sent when a cardholder adds a Grid-issued card to a digital wallet. Updates apply to subsequent delivery attempts. Invalid sender or provider configuration can cause delivery to fail. properties: displayName: type: string maxLength: 255 description: | Name shown in authentication messages and used to build the default subject, body, and sender name. Defaults to the platform's name. example: Acme logoUrl: type: string format: uri pattern: ^https:// maxLength: 512 description: HTTPS URL of the logo displayed in email messages. example: https://acme.com/card-email-logo.png email: $ref: '#/components/schemas/CardTokenization2FAEmailConfig' sms: $ref: '#/components/schemas/CardTokenization2FASmsConfig' CardConfig: type: object description: Platform-level settings that apply to cards issued by the platform. properties: pinTargetOrigin: anyOf: - type: string format: uri pattern: >- ^https://(?:[^\s/?#@:\[\]\\]+|\[[0-9A-Fa-f:.]+\])(?::[0-9]{1,5})?$ - type: 'null' description: >- Canonical HTTPS origin of the page that hosts the PIN-entry iframe returned by `GET /cards/{id}/pin-entry-url`. Include the scheme, host, and optional port, without a path, trailing slash, query, fragment, or credentials. The iframe is restricted to this origin, so it must match the embedding page's origin exactly. Different user-specific paths on the same origin use this one setting. Required before requesting a PIN-entry URL. Omit this field when updating platform configuration to preserve its value; set it to `null` to clear it. If unset, PIN-entry URL requests return `409 CONFLICT`. Changes apply to newly requested URLs. example: https://app.example.com maxNetworkRiskScore: anyOf: - type: integer minimum: 0 maximum: 999 - type: 'null' description: >- Maximum normalized network risk score allowed for real-time card authorizations. Scores range from 0 (lowest risk) to 999 (highest risk). Visa scores are normalized by multiplying the raw 0–99 score by 10. Scores equal to the ceiling are allowed. Authorizations without a score are also allowed. The lowest configured card or platform ceiling applies. Omit to preserve the current setting or send null to clear this scope. example: 700 allowedMccs: anyOf: - type: array minItems: 1 maxItems: 500 items: type: string pattern: ^[0-9]{4}$ - type: 'null' description: >- Merchant category codes allowed for cards on this platform where Grid makes authorization decisions. Every configured allow list must admit the category, and any block list can refuse it. Card restrictions, default agent blocks, and Lightspark's controls also apply; this list cannot loosen them. Changes apply to new authorizations on existing and future cards. Omit to preserve the current list, or send null to remove this platform restriction. An empty allow list is invalid. example: - '5411' blockedMccs: anyOf: - type: array maxItems: 500 items: type: string pattern: ^[0-9]{4}$ - type: 'null' description: >- Merchant category codes declined for cards on this platform where Grid makes authorization decisions. Blocks combine with card restrictions, default agent blocks, and Lightspark's controls and take precedence over allow lists. Changes apply to new authorizations on existing and future cards. Omit to preserve the current list; send null or an empty list to clear only this platform's blocks. example: - '7995' panRevealCssUrl: anyOf: - type: string format: uri pattern: ^https://[^@]*$ maxLength: 512 - type: 'null' description: >- HTTPS URL of a stylesheet that styles the card-details iframe returned by `POST /cards/{id}/reveal`, so the revealed PAN, expiry, and CVV carry your branding instead of the default. The card processor's page links the stylesheet and the cardholder's browser fetches it, so it must be reachable over HTTPS without credentials. Style the `card`, `pan`, `expiry`, and `cvv` ids and the `pan-separator` class; the rest of the page structure is not a contract. The stylesheet loads into the page rendering the live card details, so host it somewhere you would trust with them. `null` restores the default styling. A `cssUrl` in the body of `POST /cards/{id}/reveal` overrides this for one reveal. Applies to cards whose `cardCapabilities.supportsPanReveal` is true; cards revealed through the card issuer's own hosted flow are styled by that issuer. example: https://acme.com/card-reveal.css realTimeAuthorization: anyOf: - $ref: '#/components/schemas/CardRealTimeAuthorization' - type: 'null' description: >- Real-time authorization settings. While set, Grid sends a `CARD_AUTHORIZATION.REQUEST` to your `webhookEndpoint` for each card authorization that Grid's own checks approve, and your response decides whether it proceeds. See the `CARD_AUTHORIZATION.REQUEST` webhook for the request and the decision it must return. `null` while real-time authorization is off, in which case Grid's own checks decide every authorization. Omit this field to preserve the setting. Send an object to turn real-time authorization on or change its settings, or send `null` to turn it off. Changes apply to authorizations that arrive after the update returns. example: timeoutBehavior: DECLINE FeeConfigOneOf: oneOf: - $ref: '#/components/schemas/CrossCurrencyTransactionFeeConfig' - $ref: '#/components/schemas/RailFeeConfig' discriminator: propertyName: feeType mapping: CROSS_CURRENCY_TRANSACTION: '#/components/schemas/CrossCurrencyTransactionFeeConfig' RAIL: '#/components/schemas/RailFeeConfig' CounterpartyFieldDefinition: type: object properties: name: $ref: '#/components/schemas/CustomerInfoFieldName' mandatory: type: boolean description: Whether the field is mandatory example: true required: - name - mandatory CustomerInfoFieldName: type: string enum: - FULL_NAME - BIRTH_DATE - NATIONALITY - PHONE_NUMBER - EMAIL - POSTAL_ADDRESS - TAX_ID - REGISTRATION_NUMBER - USER_TYPE - COUNTRY_OF_RESIDENCE - ACCOUNT_IDENTIFIER - FI_LEGAL_ENTITY_NAME - FI_ADDRESS - PURPOSE_OF_PAYMENT - ULTIMATE_INSTITUTION_COUNTRY - IDENTIFIER - BUSINESS_TYPE - COMPANY_LEGAL_NAME - ID_TYPE - ID_NUMBER description: >- Name of a type of field containing info about a platform's customer or counterparty customer. example: FULL_NAME TransactionType: type: string enum: - INCOMING - OUTGOING - CARD description: Type of transaction CardTokenization2FAEmailConfig: type: object description: >- Email branding and sender settings for card-tokenization authentication messages. Invalid or unverified sender identities can cause delivery to fail. properties: fromAddress: type: string format: email maxLength: 255 description: Sender address for card-tokenization authentication emails. example: cards@acme.com fromName: type: string maxLength: 255 description: Sender display name. Defaults to `displayName`. example: Acme Cards replyToAddress: type: string format: email maxLength: 255 description: Reply-to address for card-tokenization authentication emails. example: support@acme.com subject: type: string maxLength: 255 description: | Subject for the authentication email. Defaults to "Your {displayName} verification code". example: Your Acme card verification code bodyText: type: string maxLength: 2000 description: > Plain-text message content. Lightspark inserts the authentication code into a controlled text and HTML template; arbitrary HTML and template variables are not supported. Defaults to "Use this code to finish adding your {displayName} card to your wallet." example: >- Use this code to finish adding your Acme card to your digital wallet. CardTokenization2FASmsConfig: type: object description: >- SMS settings for card-tokenization authentication messages delivered through a Lightspark-managed Twilio sender. properties: templateSid: type: string maxLength: 64 description: > Twilio Verify template SID to use for this platform. An invalid or unavailable template can cause delivery to fail. example: HJaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa bodyText: type: string maxLength: 480 description: > Plain-text fallback message used when Twilio Verify is unavailable for the authentication code. Lightspark appends the code to this text. Defaults to "Your {displayName} verification code is:". example: >- Use this code to finish adding your Acme card to your digital wallet. CardRealTimeAuthorization: title: Card Real-Time Authorization type: object properties: timeoutBehavior: $ref: '#/components/schemas/CardAuthorizationTimeoutBehavior' description: >- What Grid answers when your `webhookEndpoint` does not return a valid decision in time. Defaults to `DECLINE` when omitted from an update. Always returned when reading the config. CrossCurrencyTransactionFeeConfig: allOf: - $ref: '#/components/schemas/FeeConfig' - type: object properties: feeType: enum: - CROSS_CURRENCY_TRANSACTION sourceCurrency: type: string description: >- Currency code of the sending side this fee applies to. Only `USD` is accepted today; other currencies return a `NOT_IMPLEMENTED` error. example: USD required: - sourceCurrency description: >- A fee charged for a cross-currency transaction. There can be at most one cross-currency transaction fee config for a given source currency. The fee will apply to all cross-currency transactions that originate in the source currency. RailFeeConfig: allOf: - $ref: '#/components/schemas/FeeConfig' - type: object properties: feeType: enum: - RAIL rail: $ref: '#/components/schemas/PaymentRail' description: >- The rail used in the transaction. `ACH`, `ACH_SAME_DAY`, `RTP`, `FEDNOW` and `WIRE` are accepted today; other rails return a `NOT_IMPLEMENTED` error. direction: $ref: '#/components/schemas/FeeDirection' originator: $ref: '#/components/schemas/FeeOriginator' required: - rail - direction - originator description: >- A fee charged when a transaction uses the specified rail. There can be at most one for a given rail, direction and originator. For example, a config with rail: ACH, direction: OUT, originator: GRID will charge a fee on all outgoing ACH transactions. `ACH` and `ACH_SAME_DAY` are separate rails, so price each one with its own config. CardAuthorizationTimeoutBehavior: type: string enum: - DECLINE - APPROVE description: > What Grid answers for a card authorization when your `webhookEndpoint` does not return a valid decision to a `CARD_AUTHORIZATION.REQUEST` in time. | Value | Behavior | |-------|----------| | `DECLINE` | Grid declines the authorization with `cardDeclinedReason: PLATFORM_UNAVAILABLE`. | | `APPROVE` | Grid proceeds as though you approved. Grid's own funding check still applies. | A non-`200` status, a body that does not match `CardAuthorizationDecision`, a network error, and a timeout all count as no valid decision. example: DECLINE FeeConfig: type: object description: >- A platform-configured fee collected by Grid and settled to the platform internal account. These fields are shared by every platform fee config. properties: feeType: $ref: '#/components/schemas/FeeType' variableFeeBps: type: integer minimum: 0 maximum: 10000 description: >- Variable fee in basis points (1 bps = 0.01%) to apply to a transaction's source-currency amount. example: 30 fixedFee: $ref: '#/components/schemas/FixedFee' required: - feeType - variableFeeBps - fixedFee 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 FeeDirection: type: string enum: - IN - OUT description: >- Whether the money is coming in or going out, relative to Grid. Only `OUT` is accepted today. example: OUT FeeOriginator: type: string enum: - GRID - EXTERNAL description: >- Who originated the movement over the rail. An ACH OUT where Grid is the originator means Grid is pushing out the funds, while an ACH OUT with an EXTERNAL originator indicates Grid received an ACH pull request from an external source. example: GRID FeeType: type: string enum: - CROSS_CURRENCY_TRANSACTION - RAIL description: > The kind of activity this fee applies to. - `CROSS_CURRENCY_TRANSACTION` — a fee charged on transactions where the sending currency differs from the receiving currency - `RAIL` — a fee charged on any transaction that uses the specified payment rail example: CROSS_CURRENCY_TRANSACTION FixedFee: type: object description: Fixed fee charged per transaction. required: - amount - currency properties: amount: type: integer format: int64 minimum: 0 maximum: 9007199254740991 description: >- Fee amount in the smallest unit of the fixed fee's `currency` (e.g., cents for USD). example: 100 currency: type: string description: >- Three-letter currency code (ISO 4217) the fixed fee is denominated in. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.) example: USD 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.