Transaction

Simulate authorization

Changed on

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

  • Base URL
    https://sandbox.lithic.com
  • URL
    https://sandbox.lithic.com/v1/simulate/authorize
  • Auth
    API key in header Authorization

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.

billing_currencystring

3-character alphabetic ISO 4217 currency code for the cardholder billing amount. Permitted values are USD, GBP, EUR and CAD, and any other ISO 4217 code returns a 422. Defaults to USD

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 for the merchant amount. Only used when merchant_amount is set, and defaults to GBP in that case. Without merchant_amount, the merchant amount uses the billing currency. Permitted values are USD, GBP, EUR and CAD, and any other ISO 4217 code returns a 422

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.

settlement_currencystring

3-character alphabetic ISO 4217 currency code for the settlement amount. Permitted values are USD, GBP, EUR and CAD, and any other ISO 4217 code returns a 422. Defaults to the value of billing_currency. Only single message (financial) authorizations carry a settlement amount, and the value is ignored for dual message authorizations

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

{
  "billing_currency": "CAD",
  "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",
  "settlement_currency": "CAD",
  "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.

Changes

  • 9798275dc379Revision changes
    • info

      added the new optional request property

    • info

      added the new optional request property