Simulate authorizations

Go through different scenarios to simulate authorizations.

At certain times, you may want to simulate card transactions in the sandbox environment when implementing a new product, testing a new condition, or integration.

You can simulate a real-world authorization from the network in the sandbox environment with the Simulate authorization endpoint. This simulation does not go through all the card network services as it would in production, but it does check for card status and balance. The call gives you a chance to see how Pismo might respond to a network authorization. The fields returned can be used to cancel or confirm the request with the same endpoint.

The simulator can be used to generate a network authorization event that you can receive and view , which can occur, in production, when Pismo cancels or confirms an authorization. The simulator also gives you a chance to test out connectivity to your anti-fraud webhook URL.

In production, a Pismo-issued card transaction executes a number of interlinked services from the PIN pad to the acquirer, to Pismo, to the issuer, and back again to the originating PIN pad.

Simulation features

You can use the Simulate authorization endpoint to run four scenarios:

Base 1 (online)

  1. Run the initial authorization request (authorization/base 1)
  2. Cancel the transaction via an authorization request

Base II (confirmation)

  1. Confirm the authorization (clearing/base II)
  2. Cancel the transaction via clearing

Note that in order for an authorization to show as a transaction (for example, in the client statement or via the List transactions endpoint, it has to first be approved in Base I then confirmed in Base II. Be sure to run both simulations if this is what you want to test.

📘

Simulation events

The simulator allows you to verify your event notification setup. For more information on setting this up, see the Data and reporting overview.

For authorization confirmation and cancellation, the simulator generates a network authorization event in the EXT environment. For more information on this event, click here.

In production, this event is generated during step 6 in the Full and zero balance workflows.

The simulator does NOT generate the following:

For more information on these events, see Authorization events.

You can go through the authorization simulation in the following order:

  1. Run the initial authorization request (authorization/base I). (See below)
  2. Use the response's authorization_code to cancel the transaction via an authorization request.
  3. Use the same authorization_code to reopen and confirm the transaction (clearing/base II).
  4. Cancel the transaction via clearing.

Run the initial authorization request (authorization/base I)

To begin authorization, start with an authorization/base I request similar to the following:

curl -L -X  POST 'https://api-sandbox.pismolabs.io/networktransactions/v1/authorizations' 
-H 'Accept: application/json'
-H 'Content-Type: application/json' 
-H 'x-tenant: <Org ID>' 
-d '{
  "caller": "visa",
  "card_id": <card ID>,
  "local_amount": 501,
  "local_currency": "986",
  "settlement_amount": 501,
  "settlement_currency": "840",
  "entry_mode": "901",
  "processing_code": "00",
  "response_code": "00",
  "account_type": "30",
  "mti": "0100",
  "anti_fraud_url", <Your anti-fraud webhook>
  "merchant": {
    "name": "MERCHANT TEST",
    "city": "MERCHANT CITY",
    "country": "BR",
    "code": "5542"
  },
  "installments": {
    "is_crediario": true,
    "number": 5,
    "with_interest": false
  }
}

In this request, the following fields are important:

FieldValuesDescription
mti0100: auth. request
0110: auth. response
0120: auth. advice
...
Message type indicator. For more information, see MTI
anti_fraud_urlURLYour anti-fraud webhook URL. For example: https://api.ext.client.info/webhook/provider/client/authorize
processing_code- 00: p urchase
- 01: withdrawal
- 20: credit (also used to simulate cancellation)
- 28: payment
Type of operation to be performed. For more information, see Processing codes and transaction types
local_currency and settlement_currencyString
Examples:
986 - Brazil
840 - US
ISO 4217 currency codes
entry_modestring
Example: 901
This field is required and must have 3 or 4 digits. For example, try 901 or 9010 for magnetic stripe transaction simulation.
installmentsobject(s)Object to send the installment information.
Note: For cash transactions, do not send the installments object.
    is_crediariotrue or falseIs this a crediário transaction - a Brazil specific installment plan?
    numberNumeric valueNumber of installments.
    with_interesttrue or falseIs this a purchase with interest or without interest?
merchantobject
    countryExamples:
BR - Brazil
US - United States
ISO 3166 country codes

You can change the corresponding parameters according to the different scenarios as shown in the following table:

ScenarioParametersAdditional notes
Domestic purchase"processing_code": "00", "local_currency": "986",986 for the Brazilian real.
Domestic withdrawal"processing_code": "01", "local_currency": "986",986 for the Brazilian real.
International purchase"processing_code": "00", "local_currency": "840",840 for the US dollar. If this value is anything other than 840, add the settlement_amount and settlement_currency values as needed.
International withdrawal"processing_code": "01", "local_currency": "840",840 for the US dollar. Update the transaction's local_currency code as needed.
Installment purchase"processing_code": "00", "installments": { "is_crediario": true, "number": 2, "with_interest": true },

After you send the initial sample authorization request, you will receive a response similar to the following:

{
  "mti": "0110",
  "authorization_code": "EK6JXC",
  "response_code": "57",
  "authorization_date_time": "2023-02-21T10:49:23",
  "retrieval_reference_number": "",
  "custom_code": "ANF",
  "authorization_id": 51123840,
  "account_id": <account ID>,
  "mode_type": "CREDIT",
  "card_mode": "CREDIT",
  "installment_value": 0,
  "interest_rate": 0,
  "number_of_installments": 5,
  "contract_amount": 0,
  "principal_amount": 0,
  "crediario_responses": [],
  "is_domestic_transaction": true, // Not returned for international transactions
  "settlement_amount": "501.00"
}

Save the response's authorization_code to use in subsequent steps.

📘

Response codes

Approved transactions generate the response code 00. Any other response code indicates a rejected transaction. Some common response codes for rejected transactions are:

  • 14: no card found or no acceptances configured
  • 51: insufficient funds
  • 57: card not active
  • 96: system failure or issuer timeout

In addition to the response code, it is important to note the custom code. The platform uses the same response code for some issuers, and, in those cases, the difference is specified by the custom code. For example, with Mastercard:

  • response_code 14 and custom_code FR7: no card found
  • response_code 51 and custom_code 810: insufficient funds
  • response_code 57 and custom_code UBT: card not active
  • response_code 96 and custom_code OP1: system failure

For the full list of response codes and custom codes for rejected transactions, see Validation codes for authorization events.

Cancel the transaction via an authorization request

At this stage, you can cancel the transaction in the following way:

  1. In the same request as above, add the authorization_code from the first response.
  2. Change the mti value to 0400(reversal request).
  3. Run the request.
{
  "caller": "visa",
  "card_id": <card ID>,
  "local_amount": 501,
  "local_currency": "986",
  "settlement_amount": 151,
  "settlement_currency": "840",
  "entry_mode": "901",
  "processing_code": "00",
  "response_code": "00",
  "account_type": "30",
  "mti": "0400",
  "authorization_code": "EK6JXC",
  "merchant": {
		"name": "MERCHANT TEST",
		"city": "MERCHANT CITY",
		"country": "BR",
		"code": "5542"
  },
  "installments": {
		"is_crediario": true,
		"number": 5,
		"with_interest": false
    }
}

Confirm the authorization (clearing/base II)

The authorization confirmation, known as clearing/base II, is the process of finalizing the transaction. To simulate the clearing process, you need to add certain purchase payload fields to the same transactions endpoint.

📘

This simulation of the clearing process is not possible for the Zero Balance solutions since in this case the authorization confirmation is performed by the clearing/base II (raw messages) events from the card network.

To simulate the clearing process, configure the request as follows:

  1. Set the mti field to clearing.
  2. Keep the same processing_code as in the initial request.
  3. Add the following fields:
    • authorization_code with the same value as in the first response
    • processing_julian_date with a valid date (ydddd)
    • message_number
    • acquirer_reference_number
  4. Run the request.

The following fields are important for the confirmation step in clearing/base II:

FieldValueDescription
mticlearingDefines the message type. In case of a transaction confirmation, the text should be clearing.
authorization_codeEK6JXCThis field is returned on the initial authorization request and must be used on the confirmation request.
acquirer_reference_numberABC123YZ25This is a value that Pismo receives from the acquirer.
message_number02In the production environment, this is a unique sequential number assigned to the clearing message in the card network clearing file. In the simulation, you can use any numeric value.
processing_julian_date1239Date in flag format YDDD, where the last digit of the year is concatenated with the number corresponding to the day in the calendar. For example, February 26, 2021 is 1057, where 2021 is 1 and 26/02 is 57.

The other payload fields must have the same values as the initial authorization request to keep the original values from Authorization/Base I. If any field values in the clearing request are different from the values in the initial request, these values get updated since the information from the clearing confirmation takes precedence.

Sample confirmation clearing request:

{
  "caller": "visa",
  "card_id": <card ID>,
  "local_amount": 501,
  "local_currency": "986",
  "settlement_amount": 151,
  "settlement_currency": "840",
  "entry_mode": "901",
  "processing_code": "00",
  "response_code": "00",
  "account_type": "30",
  "mti": "clearing",
  "authorization_code": "EK6JXC",
  "acquirer_reference_number": "ABC123YZ25",
  "message_number": "02",
  "processing_julian_date": "1239",
  "merchant": {
		"name": "MERCHANT TEST",
		"city": "MERCHANT CITY",
		"country": "BR",
		"code": "5542"
  },
  "installments": {
		"is_crediario": true,
		"number": 5,
		"with_interest": false
    }
}

🚧

Other important considerations for the clearing process:

  • If you need to process more than one clearing for the same authorization, make sure that at least one of the following fields - message_number, processing_julian_date, or acquirer_reference_number - is different from the previous message.
  • Clearing messages for the same purchase should be processed at least 2 minutes apart. Processing is denied if the second message is sent at a shorter interval.

Cancel the transaction via clearing

Another way to cancel a transaction is via clearing:

  1. Change the processing_code field value to 20.
  2. Keep the mti value as clearing.
  3. Keep the same authorization_code.
  4. Change one of the values in the message_number, processing_julian_date, or acquirer_reference_number fields, which indicates that it is a new clearing message.

To generate a partial cancellation, send the clearing message with the field local_amount with a value lower than the authorization/confirmation value.

{
  "caller": "visa",
  "card_id": <card ID>,
  "local_amount": 250,
  "local_currency": "986",
  "settlement_amount": 151,
  "settlement_currency": "840",
  "entry_mode": "901",
  "processing_code": "20",
  "response_code": "00",
  "account_type": "30",
  "mti": "clearing",
  "authorization_code": "EK6JXC",
  "acquirer_reference_number": "ABC123YZ25",
  "message_number": "03",
  "processing_julian_date": "1239",
  "merchant": {
		"name": "MERCHANT TEST",
		"city": "MERCHANT CITY",
		"country": "BR",
		"code": "5542"
  },
  "installments": {
		"is_crediario": true,
		"number": 5,
		"with_interest": false
    }
}

Other examples

The Simulate authorization endpoint has other example payloads you can view:

Related pages

API reference / Simulate authorizations