Simulate a card return reversal

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

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({cardTransactionId: 'CardTransaction:019542f5-b3e7-1d02-0000-000000000100'})
};

fetch('https://api.lightspark.com/grid/2025-10-13/sandbox/cards/{id}/simulate/return_reversal', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"cardTransactionId\": \"CardTransaction:019542f5-b3e7-1d02-0000-000000000100\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/sandbox/cards/{id}/simulate/return_reversal")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

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

{
  "status": 400,
  "message": "<string>",
  "details": {}
}

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

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

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

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

Sandbox

Simulate a card return reversal

Simulate a RETURN_REVERSAL against an existing REFUNDED card transaction in the sandbox environment — reversing a previously settled return. The parent transaction must be in REFUNDED state. The resulting card operation is delivered asynchronously via the issuer’s events webhook.

Note: authorization reversal / void has no dedicated card-issuer simulate path (the void simulator emits a distinct VOID event), so — like authorization expiry — it is not exposed here.

Production returns 404 on this path.

POST

sandbox

cards

{id}

simulate

return_reversal

Simulate a card return reversal

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

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({cardTransactionId: 'CardTransaction:019542f5-b3e7-1d02-0000-000000000100'})
};

fetch('https://api.lightspark.com/grid/2025-10-13/sandbox/cards/{id}/simulate/return_reversal', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"cardTransactionId\": \"CardTransaction:019542f5-b3e7-1d02-0000-000000000100\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/sandbox/cards/{id}/simulate/return_reversal")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

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

{
  "status": 400,
  "message": "<string>",
  "details": {}
}

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

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

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

{
  "status": 500,
  "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 return reversal applies to.

Body

application/json

Sandbox-only request body for simulate endpoints keyed only by an existing card transaction — currently POST /sandbox/cards/{id}/simulate/return_reversal.

cardTransactionId

string

required

The id of the CardTransaction to act against.

Example:

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

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"

Simulate a card credit authorization advice

Create an UMA invitation

⌘I

Using the API

API documentation

Simulate a card return reversal

Authorizations

Path Parameters

Body

Response