Skip to main content
The sandbox environment exposes simulation endpoints that produce authorizations, clearings, reversals, refunds, and declines on demand. Use them to test every state your integration needs to handle without waiting for a real card network event. Simulation is available in all sandbox projects. These endpoints return an error if called in a production environment. Simulated transactions expose the same fees: { atm, fx } fields as live traffic, but simulation currently records zero platform fees (atm: 0, fx: 0). Do not use sandbox fee values to validate fee logic against production ATM/FX markup. For the underlying status transitions and what to expect on each event, see Lifecycle.

​
Scenario 1: Authorization and clearing

  1. Create a card with type: VIRTUAL
  2. Simulate authorization with a cardId and amount
  3. Confirm CARD_TRANSACTION_CREATED webhook received with status: PENDING
  4. Simulate clearing with the transactionId
  5. Confirm CARD_TRANSACTION_UPDATED webhook received with status: CLEARED

​
Scenario 2: Declined transaction

  1. Create a card
  2. Simulate decline with a cardId, amount, and optional declineReason (defaults to INSUFFICIENT_BALANCE)
  3. Confirm CARD_TRANSACTION_CREATED webhook received with status: DECLINED
See Decline reasons for the full set of codes you can pass as declineReason.

​
Scenario 3: Decline against a frozen card

  1. Freeze a card
  2. Confirm CARD_STATUS_UPDATED webhook received with status: FROZEN
  3. Simulate authorization (confirm it is declined)
  4. Unfreeze a card
  5. Confirm CARD_STATUS_UPDATED webhook received with status: ACTIVE

​
Scenario 4: Refund on a cleared transaction

  1. Create a card
  2. Simulate authorization
  3. Simulate clearing with the transactionId
  4. Simulate refund with the transactionId
  5. Confirm CARD_TRANSACTION_UPDATED webhook received

​
Scenario 5: External authorization

Applies to External authorization mode projects only. In Managed projects, Reap decides the authorization and there is no endpoint to call.
In an External project, simulation fires a real signed CARD_AUTHORIZATION_REQUEST to your registered authorization endpoint and authorizes based on the decision you return. See The authorization request for the contract.
  1. Register your authorization endpoint (a webhook with mode: REQUEST) and create a card
  2. Simulate authorization with a cardId and amount
  3. Your endpoint receives a CARD_AUTHORIZATION_REQUEST; return { "decision": "APPROVE" } or a decline
  4. Confirm the CARD_TRANSACTION_CREATED webhook reflects your decision: status: PENDING on approve, status: DECLINED on decline

​
Scenario 6: Authorization with 3DS challenge (WEBHOOK)

Use this when the card uses 3dsChallengeMethod: WEBHOOK and you need to exercise the challenge → respond → transaction path end-to-end.
  1. Create a card with 3dsChallengeMethod: WEBHOOK (or update an existing card)
  2. Simulate authorization with 3DS with a cardId and amount
  3. Confirm CARD_3DS_CHALLENGE_CREATED — there is no CARD_TRANSACTION_CREATED yet
  4. Respond to 3DS challenge with approve: true or false
  5. On approve, confirm CARD_TRANSACTION_CREATED with status: PENDING. On reject, the challenge becomes REJECTED and no transaction is created (same as production — a rejected 3DS never produces a network authorization).

​
Simulating card statuses

To force a card into a status that is otherwise hard to trigger (BLOCKED, EXPIRED), see Simulating card statuses.