Sign in

v66

latestOpenAPI 3.1.0Apache 2.0raw.githubusercontent.com2026-08-042174421.1 MB
Transaction

Simulate authorization

Simulates an authorization request from the card network as if it came from a merchant acquirer. If you are configured for ASA, simulating authorizations requires your ASA client to be set up properly, i.e. be able to respond to the ASA request with a valid JSON. For users that are not configured for ASA, a daily transaction limit of $5000 USD is applied by default. You can update this limit via the update account endpoint.

post/v1/simulate/authorize

Request body

amountinteger required

Amount (in cents) to authorize. For credit authorizations and financial credit authorizations, any value entered will be converted into a negative amount in the simulated transaction. For example, entering 100 in this field will result in a -100 amount in the transaction. For balance inquiries, this field must be set to 0.

descriptorstring required

Merchant descriptor.

mccstring

Merchant category code for the transaction to be simulated. A four-digit number listed in ISO 18245. Supported merchant category codes can be found here.

merchant_acceptor_idstring

Unique identifier to identify the payment card acceptor.

merchant_acceptor_citystring

Merchant acceptor city

merchant_acceptor_statestring

Merchant acceptor state/province (ISO 3166-2 subdivision code)

merchant_acceptor_countrystring

Merchant acceptor country code (ISO 3166-1 alpha-3)

merchant_amountinteger

Amount of the transaction to be simulated in currency specified in merchant_currency, including any acquirer fees.

merchant_currencystring

3-character alphabetic ISO 4217 currency code. Note: Simulator only accepts USD, GBP, EUR and defaults to GBP if another ISO 4217 code is provided

panstring required

Sixteen digit card number.

partial_approval_capableboolean

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 must be used for the remainder.

pinstring

Simulate entering a PIN. If omitted, PIN check will not be performed.

status'AUTHORIZATION' | 'BALANCE_INQUIRY' | 'CREDIT_AUTHORIZATION' | 'FINANCIAL_AUTHORIZATION' | 'FINANCIAL_CREDIT_AUTHORIZATION'

Type of event to simulate.

  • AUTHORIZATION is a dual message purchase authorization, meaning a subsequent clearing step is required to settle the transaction.
  • BALANCE_INQUIRY is a $0 authorization requesting the balance held on the card, and is most often observed when a cardholder requests to view a card's balance at an ATM.
  • CREDIT_AUTHORIZATION is a dual message request from a merchant to authorize a refund, meaning a subsequent clearing step is required to settle the transaction.
  • FINANCIAL_AUTHORIZATION is a single message request from a merchant to debit funds immediately (such as an ATM withdrawal), and no subsequent clearing is required to settle the transaction.
  • FINANCIAL_CREDIT_AUTHORIZATION is a single message request from a merchant to credit funds immediately, and no subsequent clearing is required to settle the transaction.

Example request

{
  "descriptor": "COFFEE SHOP",
  "mcc": "5812",
  "merchant_acceptor_id": "OODKZAPJVN4YS7O",
  "merchant_acceptor_city": "LOS ANGELES",
  "merchant_acceptor_state": "CA",
  "merchant_acceptor_country": "USA",
  "merchant_currency": "GBP",
  "pan": "4111111289144142",
  "pin": "1234",
  "status": "AUTHORIZATION"
}

Response

OK

debugging_request_idstring uuid

Debugging request ID to share with Lithic Support team.

tokenstring uuid

A unique token to reference this transaction with later calls to void or clear the authorization.