> ## Documentation Index > Fetch the complete documentation index at: https://docs.lightspark.com/llms.txt > Use this file to discover all available pages before exploring further. # Simulate a card authorization reversal > Simulate a merchant cancelling a card authorization before it settles — a hotel releasing a hold, or a store voiding a purchase that never went through. Use it to see how your integration handles an authorization that disappears without ever clearing. Send `amount` to reverse only part of the authorization, or leave it out to reverse all of it. The transaction must still be fully open: once any part of it has settled, it can no longer be reversed. Grid processes the reversal in the background and sends a card transaction webhook once it lands, the same as the other simulators. Production returns `404` on this path. ## OpenAPI ````yaml https://app.stainless.com/api/spec/documented/grid/openapi.documented.yml post /sandbox/cards/{id}/simulate/authorization_reversal 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: 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: 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 (experimental), 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 an action requires approval, the resulting transaction enters a pending state and must be approved by the platform via `POST /transactions/{transactionId}/approve`. - name: Cards description: >- Card management endpoints. Issue debit cards against an internal account, freeze / unfreeze, close, manage card funding sources, 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. paths: /sandbox/cards/{id}/simulate/authorization_reversal: post: tags: - Sandbox summary: Simulate a card authorization reversal description: > Simulate a merchant cancelling a card authorization before it settles — a hotel releasing a hold, or a store voiding a purchase that never went through. Use it to see how your integration handles an authorization that disappears without ever clearing. Send `amount` to reverse only part of the authorization, or leave it out to reverse all of it. The transaction must still be fully open: once any part of it has settled, it can no longer be reversed. Grid processes the reversal in the background and sends a card transaction webhook once it lands, the same as the other simulators. Production returns `404` on this path. operationId: sandboxSimulateCardAuthorizationReversal parameters: - name: id in: path required: true description: The id of the card the reversal applies to. schema: type: string example: Card:019542f5-b3e7-1d02-0000-000000000010 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SandboxCardReversalRequest' examples: fullReversal: summary: Reverse the whole open authorization value: cardTransactionId: Transaction:019542f5-b3e7-1d02-0000-000000000100 partialReversal: summary: Reverse part of it and leave the rest authorized value: cardTransactionId: Transaction:019542f5-b3e7-1d02-0000-000000000100 amount: 500 responses: '202': description: >- Simulation accepted. The resulting card operation is delivered asynchronously via the issuer's events webhook. Returns the issuer transaction token that correlates the simulated event. content: application/json: schema: $ref: '#/components/schemas/SandboxCardSimulationResponse' '400': description: >- Bad request - Invalid parameters, or the transaction is not an open authorization content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden - request was made with a production platform token content: application/json: schema: $ref: '#/components/schemas/Error403' '404': description: Card or card transaction not found content: application/json: schema: $ref: '#/components/schemas/Error404' '409': description: >- Conflict. The simulation targets a card in a program where the card issuer makes authorization decisions. These sandbox simulators support only card programs where Grid makes authorization decisions. This is a property of the card's program, so retrying will not help. 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: SandboxCardReversalRequest: type: object required: - cardTransactionId description: >- Request body for `POST /sandbox/cards/{id}/simulate/authorization_reversal`: which authorization to reverse, and optionally how much of it. properties: cardTransactionId: type: string description: >- The authorization to reverse. It must still be fully open, with nothing settled against it yet. example: Transaction:019542f5-b3e7-1d02-0000-000000000100 amount: type: integer format: int64 description: >- How much to reverse, in the smallest unit of the transaction's currency (cents for USD). Leave it out to reverse the whole authorization. Send an amount to reverse only that much and leave the rest on hold. exclusiveMinimum: 0 example: 1250 SandboxCardSimulationResponse: type: object required: - issuerTransactionToken description: >- Response body for the sandbox card-event simulators. The simulate call pokes the card issuer's sandbox; the resulting card operation is delivered asynchronously via the issuer's events webhook, never synchronously in this response. properties: issuerTransactionToken: type: string description: >- The card issuer's transaction token for the simulated event. Correlates the eventual webhook-delivered card operation back to this simulate call. example: f3a1c2d4-5b6e-7890-abcd-ef0123456789 Error400: type: object required: - message - status - code properties: status: type: integer enum: - 400 description: HTTP status code code: type: string description: > | Error Code | Description | |------------|-------------| | INVALID_INPUT | Invalid input provided | | END_USER_TERMS_VERSION_NOT_FOUND | The submitted End User Terms version is not supported | | 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 | | QUOTE_REQUEST_FAILED | An issue occurred during the quote process; this is retryable | | INVALID_PAYREQ_RESPONSE | Counterparty Payreq response was invalid | | 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 | Sender is not accepted | | 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 | | LOOKUP_REQUEST_FAILED | Lookup request failed | | 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 | An EMAIL_OTP credential is already registered on the target internal account; only one email OTP credential is supported per internal account at this time | | 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 | | 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 | | CARDHOLDER_KYC_NOT_APPROVED | The cardholder's KYC status is not `APPROVED`, so a card cannot be 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 | enum: - INVALID_INPUT - END_USER_TERMS_VERSION_NOT_FOUND - MISSING_MANDATORY_USER_INFO - INVITATION_ALREADY_CLAIMED - INVITATIONS_NOT_CONFIGURED - INVALID_UMA_ADDRESS - INVITATION_CANCELLED - QUOTE_REQUEST_FAILED - INVALID_PAYREQ_RESPONSE - 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 - LOOKUP_REQUEST_FAILED - 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 - STABLECOIN_PROVIDER_ACCOUNT_INVALID - STABLECOIN_PROVIDER_ACCOUNT_REVOKED - STABLECOIN_PROVIDER_ACCOUNT_SELECTION_REQUIRED - CARDHOLDER_KYC_NOT_APPROVED - TRANSACTION_SIZE_LIMIT_EXCEEDED - EXTERNAL_ACCOUNT_VERIFICATION_REQUIRED message: 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' additionalProperties: true Error401: type: object required: - message - status - code properties: status: type: integer enum: - 401 description: HTTP status code 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 message: type: string description: Error message details: type: object description: Additional error details additionalProperties: true Error403: type: object required: - message - status - code properties: status: type: integer enum: - 403 description: HTTP status code code: type: string description: > | Error Code | Description | |------------|-------------| | FORBIDDEN | Insufficient permissions | | USER_NOT_READY | Customer exists but is not ready for operation | | COUNTERPARTY_NOT_ALLOWED | Counterparty has not been enabled for your account | | VELOCITY_LIMIT_EXCEEDED | Counterparty has exceeded velocity limits | | END_USER_TERMS_NOT_ACCEPTED | Customer has not accepted the End User Terms | enum: - FORBIDDEN - USER_NOT_READY - COUNTERPARTY_NOT_ALLOWED - VELOCITY_LIMIT_EXCEEDED - END_USER_TERMS_NOT_ACCEPTED message: type: string description: Error message details: type: object description: Additional error details additionalProperties: true Error404: type: object required: - message - status - code properties: status: type: integer enum: - 404 description: HTTP status code 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 | 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 message: type: string description: Error message details: type: object description: Additional error details additionalProperties: true Error409: type: object required: - message - status - code properties: status: type: integer enum: - 409 description: HTTP status code 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 | | EMAIL_OTP_CREDENTIAL_SET_CHANGED | Tied EMAIL_OTP credential set changed after the signed-retry challenge was issued | | PASSKEY_ALREADY_ENROLLED | The customer already has an enrolled passkey factor; only one passkey per customer is supported. Delete the existing 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_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 | | INVALID_STATE_TRANSITION | The requested card `state` transition is not one of `ACTIVE ⇄ FROZEN` or `ACTIVE \| FROZEN → CLOSED` | | CARD_ALREADY_CLOSED | `state: CLOSED` was requested for a card that is already `CLOSED` | | CARD_NOT_MUTABLE | The card is `CLOSED`, so it can no longer be mutated | | 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 | | 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 | enum: - TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL - TRANSACTION_NOT_CANCELLABLE - UMA_ADDRESS_EXISTS - EMAIL_OTP_EMAIL_ALREADY_EXISTS - EMAIL_OTP_CREDENTIAL_SET_CHANGED - PASSKEY_ALREADY_ENROLLED - SCA_SESSION_REQUIRED - BENEFICIARY_TRUSTED - INVALID_STATE_TRANSITION - CARD_ALREADY_CLOSED - CARD_NOT_MUTABLE - CARD_LIMIT_REACHED - STABLECOIN_GRID_ENABLEMENT_NOT_REQUESTABLE - CONFLICT message: type: string description: Error message details: type: object description: Additional error details additionalProperties: true Error500: type: object required: - message - status - code properties: status: type: integer enum: - 500 description: HTTP status code 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 message: type: string description: Error message details: type: object description: Additional error details additionalProperties: true 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. 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 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/{code}/redeem`. Agent credentials are user-scoped: all requests are automatically bound to the agent's associated customer and subject to the agent's policy. ````