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)

3. Confirm the authorization (clearing/base II)
4. 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:

• Network authorization iso8583-message-1 event
• Clearing/base II (raw messages) events
  • raw_credit_mastercard-1
  • raw_debit_mastercard-1
  • raw_credit_visa-1
  • raw_debit_visa-1
• Card network-authorization-1 return event

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:

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

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:

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