Simulate a card return

Simulate a merchant-initiated RETURN against an existing settled card transaction in the sandbox environment. Creates a CardRefund on the parent and either flips the parent to REFUNDED (full refund) or keeps it SETTLED with a non-zero refundedAmount (partial refund).

Production returns 404 on this path.

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

cURL

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": "CardTransaction:019542f5-b3e7-1d02-0000-000000000100",
  "amount": 1500
}
'

200

{
  "id": "CardTransaction:019542f5-b3e7-1d02-0000-000000000100",
  "cardId": "Card:019542f5-b3e7-1d02-0000-000000000010",
  "merchant": {
    "descriptor": "BLUE BOTTLE COFFEE SF",
    "mcc": "5814",
    "country": "US"
  },
  "authorizedAmount": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "pullSummary": {
    "count": 2,
    "totalAmount": 1500,
    "pendingCount": 0
  },
  "refundSummary": {
    "count": 0,
    "totalAmount": 0
  },
  "settlementSummary": {
    "count": 1,
    "totalAmount": 1500
  },
  "authorizedAt": "2026-05-08T14:30:00Z",
  "createdAt": "2026-05-08T14:30:00Z",
  "updatedAt": "2026-05-08T15:42:11Z",
  "issuerTransactionToken": "lithic_txn_b81c2a4f",
  "settledAmount": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "refundedAmount": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "lastEventAt": "2026-05-08T15:42:11Z"
}

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 pushes the parent transaction towards REFUNDED (full) or keeps it SETTLED (partial).

cardTransactionId · string · required

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

Example:

"CardTransaction: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

200

application/json

Simulated return processed. Returns the updated card transaction.

Parent transaction row for a card authorization and all of the pulls / settlements / refunds that reconcile against it. Child events are rolled up into the pullSummary, refundSummary, and settlementSummary aggregates. Delivered as the payload of the generic transaction webhook stream (extends the Transaction model with a card destination type) on every transition.

id · string · required · read-only

System-generated unique card transaction identifier

Example:

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

cardId · string · required

The id of the Card this transaction was made on.

Example:

"Card:019542f5-b3e7-1d02-0000-000000000010"

status · enum<string> · required

Lifecycle status of a card transaction.

Status	Description
AUTHORIZED	The auth has been approved and a hold placed on the funding source; no clearing has arrived yet.
PARTIALLY_SETTLED	At least one clearing has arrived and posted, but more clearings are still expected (split shipments, tips, multi-leg trips).
SETTLED	All clearings for the auth have posted and the transaction is closed against the funding source.
REFUNDED	A RETURN was received from the merchant; the net settled amount has been refunded in part or whole.
EXCEPTION	The transaction settled to the card network but the corresponding pull from the funding source failed (e.g. balance no longer covers the post-hoc clearing). Surfaces high-urgency alerts and is the dashboard query for stuck reconciliations.

Available options: AUTHORIZED, PARTIALLY_SETTLED, SETTLED, REFUNDED, EXCEPTION

merchant · object · required

Show child attributes

authorizedAmount · object · required

Show child attributes

accountId · string · required

Internal account id that funded this transaction (the funding source selected by Authorization Decisioning at auth time).

Example:

"InternalAccount:019542f5-b3e7-1d02-0000-000000000002"

pullSummary · object · required

Show child attributes

refundSummary · object · required

Show child attributes

settlementSummary · object · required

Show child attributes

authorizedAt · string<date-time> · required

When the auth was approved.

Example:

"2026-05-08T14:30:00Z"

createdAt · string<date-time> · required · read-only

Creation timestamp (same as authorizedAt for card transactions).

Example:

"2026-05-08T14:30:00Z"

updatedAt · string<date-time> · required · read-only

Last update timestamp.

Example:

"2026-05-08T15:42:11Z"

issuerTransactionToken · string · read-only

Opaque identifier for the transaction on the underlying issuer. Used to cross-reference Grid records against issuer dashboards and webhooks.

Example:

"lithic_txn_b81c2a4f"

settledAmount · object

Show child attributes

refundedAmount · object

Show child attributes

lastEventAt · string<date-time>

Timestamp of the most recent reconcile event (pull / clearing / refund) against this transaction.

Example:

"2026-05-08T15:42:11Z"