Simulate a transaction
Beta
Last updated: May 31, 2023
You can use the sandbox environment to simulate transaction flows with issued cards.
To get started, create a new test cardholder in the sandbox and issue them a card.
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
1{2"card": {3"id": "crd_fa6psq242dcd6fdn5gifcq1491",4"expiry_month": 5,5"expiry_year": 20256},7"transaction": {8"type": "purchase",9"amount": 2500,10"currency": "GBP"11}12}
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.
1{2"id": "trx_3vs4p7sagwlu3ejw7gkrssj2s4",3"status": "Authorized"4}
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
1{2"amount": 35003}
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.
1{2"status": "Authorized"3}
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
1{2"amount": 25003}
If the reversal amount is less 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.
1{2"status": "Reversed"3}
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
1{2"amount": 25003}
If the presentment amount is less 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 network cutoff times.