Sign in

v33

latestOpenAPI 3.1.0Proprietaryraw.githubusercontent.com2026-05-28103497709.6 KB
Sandbox

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

Path parameters

idstring required

The id of the card the return applies to.

Request body

cardTransactionIdstring required

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

amountinteger 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 request

{
  "cardTransactionId": "CardTransaction:019542f5-b3e7-1d02-0000-000000000100",
  "amount": 1500
}

Response

Simulated return processed. Returns the updated card transaction.

idstring required

System-generated unique card transaction identifier

cardIdstring required

The id of the Card this transaction was made on.

issuerTransactionTokenstring

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

status'AUTHORIZED' | 'PARTIALLY_SETTLED' | 'SETTLED' | 'REFUNDED' | 'EXCEPTION' required

Lifecycle status of a card transaction.

StatusDescription
AUTHORIZEDThe auth has been approved and a hold placed on the funding source; no clearing has arrived yet.
PARTIALLY_SETTLEDAt least one clearing has arrived and posted, but more clearings are still expected (split shipments, tips, multi-leg trips).
SETTLEDAll clearings for the auth have posted and the transaction is closed against the funding source.
REFUNDEDA RETURN was received from the merchant; the net settled amount has been refunded in part or whole.
EXCEPTIONThe 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.
accountIdstring required

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

authorizedAtstring date-time required

When the auth was approved.

lastEventAtstring date-time

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

createdAtstring date-time required

Creation timestamp (same as authorizedAt for card transactions).

updatedAtstring date-time required

Last update timestamp.

Example response

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