Simulate a card return

Simulate a merchant-initiated RETURN against an existing settled card transaction in the sandbox environment. Creates a CardRefund and posts the return as its own dated CREDIT CardTransaction linked to the purchase via originalTransactionId; the purchase keeps its SETTLED status, whether the return is full or partial.

Production returns 404 on this path.

POST /sandbox/cards/{id}/simulate/return

Simulate a card return

cURL

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

202

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

Authorizations

Authorization · string · header · required

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

Path Parameters

id · string · required

The id of the card the return applies to.

Body

application/json

Sandbox-only request body for POST /sandbox/cards/{id}/simulate/return. Drives a RETURN event against an existing settled CardTransaction, which creates a CardRefund and posts the return as its own dated CREDIT CardTransaction linked to the purchase via originalTransactionId.

cardTransactionId · string · required

The id of the CardTransaction to refund against. Must have at least one settled clearing.

Example:

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

amount · integer<int64> · required

Return amount in the smallest unit of the transaction's currency. Must be less than or equal to the net settled amount (settled minus previously-refunded).

Example:

1500

Response

202

application/json

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"