Simulate a transaction
Last updated: November 6, 2024
You can simulate transaction flows for an issued card in the sandbox environment before going live. This enables you to test transactions without making a real purchase to check the merchant and card scheme experience.
You can test successful transactions, reversals, refunds, webhooks, and declined transactions. When testing transactions, your sandbox Issuing balance is updated to demonstrate the impact on your total sandbox balance.
To get started, create a test cardholder in the sandbox and issue them a card.
In the Dashboard, you can simulate transactions and add events. For example, incremental authorizations, reversals, clearings, and refunds.
Via the API, you can:
- Simulate an authorization or pre-authorization.
- Simulate an incremental authorization.
- Simulate a reversal.
- Simulate a clearing.
- Simulate a refund.
- Sign in to the Dashboard.
- If simulating a transaction:
- Using a card, go to Issuing > Cards, and then select the card you want to test with.
- From the transactions list, go to Issuing > Transactions. For this, you require a card ID.
- Select Simulate transaction.
- In the Simulate transaction window > Authorization type field, if the final transaction amount is:
- Estimated – Select
Pre_authorization
. - Known – Select
Authorization
.
- Estimated – Select
- In the Amount field, provide the pre-authorization or authorization amount.
- Optionally, provide the merchant category code.
- Select Simulate.
Next, you can add events in the transaction journey:
- Go to Issuing > Transactions, and select the transaction you want to add events to.
- On the Transaction details page, select Simulate event.
- Select the event type. This can be one of:
Incremental authorization
Reversal
Clearing
Refund
- Provide the amount for the event type.
- Select Simulate.
Call the Simulate authorization endpoint:
- In the
card.id
field, provide theid
of the card you want to test with, and optionally the expiry information. - In the
transaction
object:- The
type
field must be set topurchase
. - Optionally, provide the
amount
,currency
, andmerchant.category_code
.
- The
- In the
authorization_type
field, if the final transaction amount is:- Estimated – Set to
pre_authorization
. - Known – Set to
authorization
, or do not include this field.
- Estimated – Set to
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"authorization_type": "pre_authorization"12}13}
If you’ve configured the authorization relay service, you receive an authorization request to approve or decline. When the authorization request is processed, if you've set up your webhook receiver, you receive a webhook notification for the authorization event.
A successful response returns the transaction id
and status
, which can be one of the following:
Authorized
– The authorization was successful.Declined
– The authorization was not successful – For example, because the card is invalid or expired, or the cardholder has exceeded the spending limit.
1{2"id": "trx_3vs4p7sagwlu3ejw7gkrssj2s4",3"status": "Authorized"4}
To simulate an incremental authorization, first simulate a pre-authorization request.
Then, call the Simulate incrementing an authorization endpoint:
- Provide the transaction ID received in the pre-authorization response as the
id
path parameter. - Optionally, provide the
amount
to increase the pre-authorization by in the minor unit of the transaction currency.
post
https://api.sandbox.checkout.com/issuing/simulate/authorizations/{id}/authorizations
1{2"amount": 35003}
If you’ve configured the authorization relay service, you receive an authorization request to approve or decline. When the authorization request is processed, if you've set up your webhook receiver, you receive a webhook notification for the authorization event.
A successful response returns the transaction status
. This can be one of the following:
Authorized
– The authorization was successful.Declined
– The authorization was not successful – For example, because the card is invalid or expired, or the cardholder has exceeded the spending limit.
1{2"status": "Authorized"3}
To simulate reversing a previous authorization, call the Simulate reversal endpoint:
- Provide the transaction ID as the
id
path parameter. - Optionally, provide the
amount
to reverse in the minor unit of the transaction currency.
If the reversal amount is lower than the previously authorized amount, only the specified part of the authorized amount is reversed. If not provided, the full authorization amount is reversed.
post
https://api.sandbox.checkout.com/issuing/simulate/authorizations/{id}/reversals
1{2"amount": 25003}
A successful response returns the transaction status
. This can be one of the following:
Reversed
– The reversal was successful.Declined
– The reversal was not successful – For example, because the reversal amount is greater than the previously authorized amount, or if the authorization has already been cleared.
1{2"status": "Reversed"3}
To simulate clearing a previous authorization, call the Simulate clearing endpoint:
- Provide the transaction ID as the
id
path parameter. - Optionally, provide the
amount
to clear in the minor unit of the transaction currency.
If the presentment amount is lower than the previously authorized amount, only the specified part of the authorized amount is cleared. If not provided, the full authorization amount is cleared.
post
https://api.sandbox.checkout.com/issuing/simulate/authorizations/{id}/presentments
1{2"amount": 25003}
If successful, you receive a 202
response code.
When an authorization request is cleared, you receive a presentment_received
webhook notification containing a clearing_type
field. This field indicates if your Issuing balance account will be credited or debited.
Information
Clearing times in the sandbox environment are different to the live environment due to acquirer and card scheme cutoff times.
To simulate a refund of a previous authorization:
- Simulate an authorization request.
- Simulate clearing the authorization.
- Call the Simulate refund endpoint:
- Provide the transaction ID as the
id
path parameter. - Optionally, provide the
amount
to refund in the minor unit of the transaction currency.
If the refund amount is lower than the previously cleared amount, only the specified part of the cleared amount is refunded. If not provided, the full cleared amount is refunded.
post
https://api.sandbox.checkout.com/issuing/simulate/authorizations/{id}/refunds
1{2"amount": 25003}
If successful, you receive a 202
response code.