# Simulate authorizations Walk-through of different scenarios to simulate authorizations. At times, you may want to simulate card transactions in the sandbox (test) 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](https://developers.pismo.io/pismo-docs/reference/post_v1-authorizations) 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 received](https://developers.pismo.io/events/docs/networktransactions-network-authorization-1) 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](https://developers.pismo.io/pismo-docs/docs/anti-fraud-integration). You can also use Simulate authorization endpoint to cancel (total or partial) the simulated authorization in the test environment. To cancel in the production environments, use the [Cancel authorization](https://developers.pismo.io/pismo-docs/reference/cancel-network-authorizations) endpoint. > 📘 > > The `Simulate authorization` endpoint does not issue a [clearing event](https://developers.pismo.io/pismo-docs/docs/clearingbase). When you use the endpoint for simulation with `MTI Clearing (1240)`, it generates a [network authorization received](https://developers.pismo.io/events/docs/networktransactions-network-authorization-1) event with the category **CONFIRMATION**, which represents the clearing. 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](https://developers.pismo.io/pismo-docs/reference/post_v1-authorizations) 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](https://developers.pismo.io/pismo-docs/docs/listtransactions) 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](https://developers.pismo.io/pismo-docs/docs/data-reporting-overview). > > For authorization confirmation and cancellation, the simulator generates a [network authorization](https://developers.pismo.io/events/docs/networktransactions-network-authorization-1) event in the EXT environment. For more information on this event, [click here](https://developers.pismo.io/pismo-docs/docs/authorization-events#network-authorization-event). > > In production, this event is generated during step 6 in the [Full and zero balance workflows](https://developers.pismo.io/pismo-docs/docs/full-and-zero-balance-workflows). > > The simulator does **NOT** generate the following: > > * Network authorization [iso8583-message-1](https://developers.pismo.io/events/docs/networktransactions-iso8583-message-1) event > * Clearing/base II (raw messages) events > * [raw\_credit\_mastercard-1](https://developers.pismo.io/events/docs/authorization-raw-credit-mastercard-1) > * [raw\_debit\_mastercard-1](https://developers.pismo.io/events/docs/authorization-raw-debit-mastercard-1) > * [raw\_credit\_visa-1](https://developers.pismo.io/events/docs/authorization-raw-credit-visa-1) > * [raw\_debit\_visa-1](https://developers.pismo.io/events/docs/authorization-raw-debit-visa-1) > * Card [network-authorization-1](https://developers.pismo.io/events/docs/networktransactions-network-authorization-1) return event > > For more information on these events, see [Authorization events](https://developers.pismo.io/pismo-docs/docs/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](https://developers.pismo.io/pismo-docs/docs/simulate-authorizations#cancel-the-transaction-via-an-authorization-request). 3. Use the same `authorization_code` to reopen and [confirm the transaction (clearing/base II)](https://developers.pismo.io/pismo-docs/docs/simulate-authorizations#confirm-the-authorization-clearingbase-ii). 4. [Cancel the transaction via clearing](https://developers.pismo.io/pismo-docs/docs/simulate-authorizations#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: ```json Sample request curl -L -X POST 'https://api-sandbox.pismolabs.io/networktransactions/v1/authorizations' -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'x-tenant: ' -d '{ "caller": "visa", "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", "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:
Field Values Description
mti `0100`: auth. request\ `0110`: auth. response \ `0120`: auth. advice\ ... Message type indicator. For more information, see MTI
anti\_fraud\_url URL Your anti-fraud webhook URL. For example: [https://api.ext.client.info/webhook/provider/client/authorize](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](https://developers.pismo.io/pismo-docs/docs/processing-codes-and-transaction-types)
local\_currency and settlement\_currency String\ Examples:\ `986` - Brazil\ `840` - US ISO 4217 currency codes
entry\_mode string\ Example: `901` This field is required and must have 3 or 4 digits. For example, try `901` or `9010` for magnetic stripe transaction simulation.
installments object(s) Object to send the installment information. * \*Note:\*\* For cash transactions, do not send the installments object.
    is\_crediario `true` or `false` Is this a crediário transaction - a Brazil specific installment plan?
    number Numeric value Number of installments.
    with\_interest `true` or `false` Is this a purchase with interest or without interest?
merchant object
    country Examples:\ `BR` - Brazil\ `US` - United States ISO 3166 country codes
> 📘 FRH - POS (point-of-sale) entry mode validation > > FRH - POS is the denial list for terminal capability validation (POS or input device) and entry mode. This validation checks how the card data was acquired (card machine, online purchase, NFC, etc.) and the entry mode information. For example, in e-commerce, it’s not possible to retrieve the card chip data, so it’s not a valid entry mode and should be denied. For Visa, entry mode is in Field 22. For Mastercard, it's in DE 61. > > For full details on entry mode validation and possible codes, refer to the [Validation code definitions](https://developers.pismo.io/pismo-docs/docs/validation-code-definitions#frh---pos-point-of-sale-entry-mode-validation) guide. 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 },` | | > 🚧 Important considerations for Processing Codes > > It is highly recommended to never use custom processing codes. Instead, **always use** the standardized processing codes provided by the card network, such as `00`, `20`, `28`, `01`, among others. The platform itself will transform these into custom processing codes as needed. > > **Never use** processing codes such as `003100` or `003800`, among others. After you send the initial sample authorization request, you will receive a response similar to the following: ```json Sample response (success) { "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": , "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](https://developers.pismo.io/pismo-docs/docs/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. ```json Cancel authorization request { "caller": "visa", "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: | Field | Value | Description | | :-------------------------- | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | mti | `clearing` | Defines the message type. In case of a transaction confirmation, the text should be `clearing`. | | authorization\_code | `EK6JXC` | 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: ```json Sample confirmation clearing request { "caller": "visa", "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. ```json Partial cancellation request { "caller": "visa", "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](https://developers.pismo.io/pismo-docs/reference/post_v1-authorizations) endpoint has other example payloads you can view: Screen capture of the Simulate authorization endpoint payloads. # Related pages [API reference / Simulate authorizations](https://developers.pismo.io/pismo-docs/reference/post_v1-authorizations)