Simulating Card Transactions
Simulate card transactions in Sandbox.
Because the sandbox environment is not connected to payment networks, it cannot receive card transactions. The sandbox environment has additional endpoints to simulate transaction events originating from a merchant acquirer.
Simulated transaction events will trigger transaction webhooks and will be returned in subsequent GET /transactions
responses.
Simulate Authorizations
API Reference: Simulate authorization
Simulate an authorization request from the payment network as if it came from a merchant acquirer.
POST https://sandbox.lithic.com/v1/simulate/authorize
Sample Request
curl https://sandbox.lithic.com/v1/simulate/authorize \
-X POST \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"descriptor":"Sample Transaction","amount":3831,"pan":"4111111289144142", "merchant_acceptor_id": "OODKZAPJVN4YS7O"}'
Sample Response
{
"debugging_request_id":"d31645af-da9e-4952-b7dc-3ffb06618b39",
"token":"fabd829d-7f7b-4432-a8f2-07ea4889aaac"
}
In the case of an error processing the authorization, a 422 Unprocessable Entity
response code will be returned with a description of the error.
{
"debugging_request_id": "9399c6b5-4e8d-4357-ae75-116eb4299fe8",
"message": "Exceeds transaction limit"
}
amount (required) | Amount (in cents) to authorize. |
descriptor (required) | Short description of payment card acceptor. |
pan (required) | 16 digit card number. |
merchant_acceptor_id (optional) | Identifier for the payment card acceptor. |
status (optional) | The type of authorization the user is attempting to simulate. The four potential types are: - AUTHORIZATION : Standard dual message authorization that a merchant sends requesting an approve or decline decision for a purchase.- FINANCIAL_AUTHORIZATION : Single message authorization that a merchant sends requesting an approve or decline decision for a purchase or cash withdrawal.- CREDIT_AUTHORIZATION : Dual message authorization that a merchant sends requesting an approve or decline decision to push a credit (e.g., return) to the card.- FINANCIAL_CREDIT_AUTHORIZATION : Single message authorization that a merchant sends requesting an approve or decline decision to push a credit (e.g., return) to the card.- BALANCE_INQUIRY : Indicate that a balance inquiry (typically a $0 authorization) has occurred on a card. |
merchant_currency (optional) | 3-digit alphabetic ISO 4217 currency code. |
merchant_amount (optional) | Amount of the transaction to be simulated in currency specified in merchant_currency, including any acquirer fees. |
partial_approval_capable (optional) | Set to true if the terminal is capable of partial approval otherwise false. Partial approval is when part of a transaction is approved and another payment method must be used for the remainder. |
Simulate Voids
API Reference: Simulate void transaction
Void an existing, uncleared (aka pending) authorization.
POST https://sandbox.lithic.com/v1/simulate/void
Sample Request
curl https://sandbox.lithic.com/v1/simulate/void \
-X POST \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"amount":0,"token":"fabd829d-7f7b-4432-a8f2-07ea4889aaac"}'
Sample Response
{
"debugging_request_id":"3ec51ef1-b68d-4243-be6c-2204229b09cf"
}
token (required) | The transaction token returned from the /v1/simulate/authorize response |
amount | Amount (in cents) to void. Typically this will match the original authorization, but may be less |
type | AUTHORIZATION_REVERSAL or AUTHORIZATION_EXPIRY |
Simulate Clearings
API Reference: Simulate clearing transaction
Clear an existing authorization. After this event, the transaction is no longer pending.
POST https://sandbox.lithic.com/v1/simulate/clearing
Sample Request
curl https://sandbox.lithic.com/v1/simulate/clearing \
-X POST \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"amount":0,"token":"fabd829d-7f7b-4432-a8f2-07ea4889aaac"}'
Sample Response
{
"debugging_request_id":"58352315-cd15-407d-bdbc-6324784d959e"
}
token (required) | The transaction token returned from the /v1/simulate/authorize response |
amount | Amount (in cents) to complete. Typically this will match the original authorization, but may be more or less |
Simulate Returns
API Reference: Simulate return
Return (aka refund) an amount back to a card. Returns settle immediately and do not spend time in a PENDING
state.
POST https://sandbox.lithic.com/v1/simulate/return
Sample Request
curl https://sandbox.lithic.com/v1/simulate/return \
-X POST \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"descriptor":"Sample Return","amount":2934,"pan":"4111111503827704"}'
Sample Response
{
"debugging_request_id":"66312f8a-78a3-4238-a87b-16d6cba78108",
"token":"6b9b4635-5bd6-4409-88d1-d598ceb56156"
}
amount (required) | Amount (in cents) to return to the card |
descriptor (required) | Merchant descriptor |
pan (required) | 16 digit card number |
Simulate Declines
You can simulate declines by simulating authorizations that should be declined.
Sample Decline Simulation with Spend Limits
- Create a card with spend limit
curl https://sandbox.lithic.com/v1/card \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: YOUR_API_KEY \
-H 'Content-Type: application/json' \
-d '
{
"type": "VIRTUAL",
"spend_limit": 1000
}
'
- Retrieve PAN from the response.
- Simulate decline with an authorization over the spend limit.
curl https://sandbox.lithic.com/v1/simulate/authorize \
-X POST \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"descriptor":"Sample Transaction","amount":2000,"pan":"CREATED_PAN"}'
- You should see a response of the form:
{"message": "Transaction exceeds user-set transaction limit", "token": "d1f276ff-1a27-4d7b-a607-9485bf063b26", "debugging_request_id": "960db679-a242-49a5-ace7-cd2e6970569d"}
Updated 26 days ago