curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/sandbox/cards/{id}/simulate/authorization_reversal \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "cardTransactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000100"
}
'

{
  "issuerTransactionToken": "f3a1c2d4-5b6e-7890-abcd-ef0123456789"
}

{
  "status": 400,
  "code": "INVALID_INPUT",
  "message": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ]
  }
}

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "<string>",
  "details": {}
}

{
  "status": 403,
  "code": "FORBIDDEN",
  "message": "<string>",
  "details": {}
}

{
  "status": 404,
  "code": "TRANSACTION_NOT_FOUND",
  "message": "<string>",
  "details": {}
}

{
  "status": 409,
  "code": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "message": "<string>",
  "details": {}
}

{
  "status": 500,
  "code": "GRID_SWITCH_ERROR",
  "message": "<string>",
  "details": {}
}

Sandbox

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.

POST

sandbox

cards

{id}

simulate

authorization_reversal

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/sandbox/cards/{id}/simulate/authorization_reversal \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "cardTransactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000100"
}
'

{
  "issuerTransactionToken": "f3a1c2d4-5b6e-7890-abcd-ef0123456789"
}

{
  "status": 400,
  "code": "INVALID_INPUT",
  "message": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ]
  }
}

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "<string>",
  "details": {}
}

{
  "status": 403,
  "code": "FORBIDDEN",
  "message": "<string>",
  "details": {}
}

{
  "status": 404,
  "code": "TRANSACTION_NOT_FOUND",
  "message": "<string>",
  "details": {}
}

{
  "status": 409,
  "code": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "message": "<string>",
  "details": {}
}

{
  "status": 500,
  "code": "GRID_SWITCH_ERROR",
  "message": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

API token authentication using format <api token id>:<api client secret>

Path Parameters

string

required

The id of the card the reversal applies to.

Body

application/json

Request body for POST /sandbox/cards/{id}/simulate/authorization_reversal: which authorization to reverse, and optionally how much of it.

cardTransactionId

string

required

The authorization to reverse. It must still be fully open, with nothing settled against it yet.

Example:

"Transaction:019542f5-b3e7-1d02-0000-000000000100"

amount

integer<int64>

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.

Example:

1250

Response

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.

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.

issuerTransactionToken

string

required

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"

Using the API

API documentation

Simulate a card authorization reversal

Authorizations

Path Parameters

Body

Response