Simulate a transaction
Last updated: April 11, 2024
You can use the sandbox environment to simulate transaction flows with an issued card prior to going live. The sandbox environment enables you to run transactions without making any real purchases whilst retaining the same merchant and card network experience.
This enables you to test declined transactions because of a revoked card or lack of funds, reversals, refunds, and webhooks. Whilst running the test transactions, your issuing balance will be updated so that you can see how these simulations also impact your sandbox balance.
To get started, create a new test cardholder in the sandbox and issue them a card.
Whilst you can simulate transactions directly from the Dashboard, to simulate transactions using the API, follow these steps:
- Locate the card you want to simulate transactions by navigating to Card Issuing > Cards, and then select the card. Alternatively, to simulate a transaction from the transactions list, navigate to Cards Issuing, then Transactions; you will require a card ID.
- Click Simulate transaction in the top right corner.
- Define the transaction details, such as amount and merchant category code, then click Simulate.
- Once authorization is successfully simulated, you can also add events.
- From the transaction details page, click Add event in the top right corner.
- Choose the event type and amount, then click Simulate.
To simulate an authorization or pre-authorization request with a test card, call the following endpoint with the card ID. Use authorization for a known final amount, or pre-authorization for an estimated amount.
post
https://api.sandbox.checkout.com/issuing/simulate/authorizations
If you’ve configured the authorization relay service, you’ll receive an authorization request that you can approve or decline.
When the authorization request is processed, you’ll receive a webhook notification for the authorization event.
The status field returns Authorized if the authorization was successful, or Declined if not.
Authorization may be unsuccessful if the card is invalid or expired, or if the card is valid but the cardholder has exceeded their spending limits.
To simulate incremental authorization, follow these steps:
- Simulate a pre-authorization request.
- Call the following endpoint with the transaction ID received in the pre-authorization response:
post
https://api.sandbox.checkout.com/issuing/simulate/authorizations/{id}/authorizations
If you've configured the authorization relay service, you'll receive an authorization request that you can approve or decline.
When the authorization request is processed, you'll receive a webhook notification for the authorization event.
The status field returns Authorized if the authorization was successful, or Declined if not.
Authorization may be unsuccessful if the card is invalid or expired, or if the card is valid but the cardholder has exceeded their spending limits.
To simulate the reversal of a previous authorization, call the following endpoint with the transaction ID:
post
https://api.sandbox.checkout.com/issuing/simulate/authorizations/{id}/reversals
If the reversal amount is lower than the previously authorized amount, then only a portion of the authorized amount will be reversed. If the reversal amount is not specified, the full authorization amount will be reversed.
The status field returns Reversed if the reversal was successful, or Declined if not.
Reversal may be unsuccessful if the reversal amount is greater than the previously authorized amount, or if the authorization has already been cleared.
To simulate the clearing of a previous authorization, call the following endpoint with the transaction ID:
post
https://api.sandbox.checkout.com/issuing/simulate/authorizations/{id}/presentments
If the presentment amount is lower than the previously authorized amount, then only a portion of the authorized amount will be cleared. If the presentment amount is not specified, the full authorization amount will be cleared.
When an authorization request is cleared, you’ll receive a presentment_received webhook notification containing a clearing_type field.
The clearing type represents whether the associated Issuing balance account will be credited or debited.
Note
Clearing times in production will vary from those in the sandbox environment due to acquirer and card scheme cutoff times.
Before you can simulate a refund, you must first:
- Simulate an authorization request.
- Simulate clearing the authorization.
To simulate a refund of a previous authorization, call the following endpoint with the transaction ID:
post
https://api.sandbox.checkout.com/issuing/simulate/authorizations/{id}/refunds
If the refund amount is lower than the previously cleared amount, only a portion of the cleared amount will be refunded. If the refund amount is not specified, the full cleared amount will be refunded.