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:

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.
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 the id of the card you want to test with, and optionally the expiry information.
In the transaction object:
- The type field must be set to purchase.
- Optionally, provide the amount, currency, and merchant.category_code.
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.

post

https://api.sandbox.checkout.com/issuing/simulate/authorizations


1{
2  "card": {
3    "id": "crd_fa6psq242dcd6fdn5gifcq1491",
4    "expiry_month": 5,
5    "expiry_year": 2025
6  },
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": 3500
3}

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": 2500
3}

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": 2500
3}

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:

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": 2500
3}

If successful, you receive a 202 response code.

Simulate a transaction

How it works

Simulate transactions in the Dashboard

Simulate an authorization or pre-authorization

Request example

Response example

Simulate an incremental authorization

Request example

Response example

Simulate a reversal

Request example

Response example

Simulate a clearing

Request example

Response example

Information

Simulate a refund

Request example

Response example