Simulate authorizations

Go through different scenarios to simulate authorizations.

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. You can simulate a real-world authorization in the sandbox environment with a POST request to the transaction simulation endpoint as described in the API reference. 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 and generates corresponding events.

📘

The simulation process generates the network authorization event, which is used for authorization, confirmation, and cancellation.

The simulation process does not generate the following:

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

  1. Run the initial authorization request (authorization/base I).
  2. Use the authorization_code returned by the response 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 --location --request POST 'https://api-sandbox.pismolabs.io/networktransactions/v1/authorizations' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJQYXNzcG9ydCIsInN1YiI6IkFVVEgtMTE2YTViNzgtOTFiOS00MjM0LTkyZjAtMmNmMWNmZGRmOGQ5IiwiZXhwIjoxNjMwNDQxMzYzLCJpYXQiOjE2MzA0NDA3NjMsInVpZCI6IlROLWVmMjNmZmUzLWM2OWItNGU5Yy1hYjIyLWQ4NjVmZTBhMjVlZTo2MGYzYWE5NzdjNmIzMGNjMGI2ZThjNzcwNTM1ODZiYmViMDAwNjAwIiwidGt2ZXIiOiIyIn0.oL-yLoTuyU16Yqk9SraNn1vYKRrl9esYugI9YJGbKjXRaE42pA9EqexxnWu7a1kXBubHVFGivo2x0m_KFCWZEg' \
--header 'Content-Type: application/json' \
--data-raw '{
  "caller": "visa",
  "card_id": 6661703,
  "local_amount": 501,
  "local_currency": "986",
  "settlement_amount": 151,
  "settlement_currency": "840",
  "entry_mode": "001",
  "processing_code": "00",
  "response_code": "00",
  "account_type": "30",
  "mti": "0100",
  "merchant": {
        "name": "MERCHANT TESTE",
        "city": "MERCHANT CITY",
        "country": "BR",
        "code": "5542"
  },
  "installments": {
        "is_crediario": true,
        "number": 5,
        "with_interest": false
    }
}'

In this request, the following fields are important:

Field

Values

Description

mti

  • 0100: authorization request

Message type indicator

processing_code

  • 00: purchase
  • 01: withdrawal
  • 20: credit (also used to simulate cancellation)
  • 28: payment

Defines the type of operation to be performed.

installments

Property to send the installment information.
Note: For cash transactions, do not send the installments property.

is_crediario

true or false

Defines whether this is a crediário transaction, which is a type of installment plan specific to Brazil.

number

Numeric value

Defines the number of installments.

with_interest

true or false

Defines whether it is a purchase with interest or without interest.

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

Scenario

Parameters

Additional 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": "56798A",
"response_code": "00",
"authorization_date_time": "2021-11-12T10:00:00",
"custom_code": "",
"authorization_id": 99999,
"account_id": 123,
"installment_value": "100.00",
"interest_rate": 0,
"number_of_installments": 1,
"contract_amount": "100.00",
"crediario_responses": []
}

Save the authorization_code from this response to use it in the 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 issues, 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 that was returned in the first response.
  2. Change the mti value to 0400, which indicates the reversal request.
  3. Run the request.
{
  "caller": "visa",
  "card_id": 6661703,
  "local_amount": 501,
  "local_currency": "986",
  "settlement_amount": 151,
  "settlement_currency": "840",
  "entry_mode": "001",
  "processing_code": "00",
  "response_code": "00",
  "account_type": "30",
  "mti": "0400",
  "authorization_code": "56798A",
  "merchant": {
        "name": "MERCHANT TESTE",
        "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:

Field

Value

Description

mti

clearing

Defines the message type. In case of a transaction confirmation, the text should be clearing.

authorization_code

XYZ123

This field is returned on the initial authorization request and must be used on the confirmation request.

acquirer_reference_number

ABC123YZ25

This is a value that Pismo receives from the acquirer.

message_number

02

In 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_date

1239

Date 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": 6661703,
  "local_amount": 501,
  "local_currency": "986",
  "settlement_amount": 151,
  "settlement_currency": "840",
  "entry_mode": "001",
  "processing_code": "00",
  "response_code": "00",
  "account_type": "30",
  "mti": "clearing",
  "authorization_code": "56798A",
  "acquirer_reference_number": "ABC123YZ25",
  "message_number": "02",
  "processing_julian_date": "1239",
  "merchant": {
        "name": "MERCHANT TESTE",
        "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": 6661703,
  "local_amount": 250,
  "local_currency": "986",
  "settlement_amount": 151,
  "settlement_currency": "840",
  "entry_mode": "001",
  "processing_code": "20",
  "response_code": "00",
  "account_type": "30",
  "mti": "clearing",
  "authorization_code": "56798A",
  "acquirer_reference_number": "ABC123YZ25",
  "message_number": "03",
  "processing_julian_date": "1239",
  "merchant": {
        "name": "MERCHANT TESTE",
        "city": "MERCHANT CITY",
        "country": "BR",
        "code": "5542"
  },
  "installments": {
        "is_crediario": true,
        "number": 5,
        "with_interest": false
    }
}

Related pages

API reference / Simulate authorizations


Did this page help you?