Simulate Authorization

Simulate authorization

post/v1/simulate/authorize

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.

Body Parameters

amountnumber

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.

minimum0

descriptorstring

Merchant descriptor.

maxLength25

minLength1

panstring

Sixteen digit card number.

maxLength16

minLength16

mccstring

optional

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

optional

Unique identifier to identify the payment card acceptor.

maxLength15

minLength1

merchant_amountnumber

optional

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

merchant_currencystring

optional

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

partial_approval_capableboolean

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

pinstring

optional

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

maxLength12

minLength4

statusenum

optional

Accepts one of the following: "AUTHORIZATION", "BALANCE_INQUIRY", "CREDIT_AUTHORIZATION", 2 more

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.

Hide ParametersShow Parameters

"AUTHORIZATION"

"BALANCE_INQUIRY"

"CREDIT_AUTHORIZATION"

"FINANCIAL_AUTHORIZATION"

"FINANCIAL_CREDIT_AUTHORIZATION"

Returns

tokenstring

optional

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

formatuuid

debugging_request_idstring

optional

Debugging request ID to share with Lithic Support team.

formatuuid

Request example Request

curl https://api.lithic.com/v1/simulate/authorize \
    -H 'Content-Type: application/json' \
    -H "Authorization: $LITHIC_API_KEY" \
    -d '{
      "amount": 3831,
      "descriptor": "COFFEE SHOP",
      "pan": "4111111289144142",
      "mcc": "5812",
      "merchant_acceptor_id": "OODKZAPJVN4YS7O",
      "merchant_currency": "GBP",
      "pin": "1234",
      "status": "AUTHORIZATION"
    }'

200 Example

{
  "token": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "debugging_request_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
}