Authorization events

During the authorization workflow, the Pismo platform generates events that allow you to verify transaction status and other information.

The Network Authorization event is the primary event for verifying an authorization. However, you should consume all the authorization events to make sure that you don't miss anything.

The Full and zero balance workflows detail the events that Full balance and Zero balance will see. They are similar, but slightly different.

Authorization event characteristics

The Pismo platform generates events related to specific authorization messages received from the card network. For any given transaction, Pismo might or might not generate all of the events, depending on the transaction life cycle. Also, various steps in the authorization process might issue the same event, so an event could be issued many times for one transaction.

Base contract

Each event contains a common set of fields, (base contract) such as event_id, domain, and event_type. The aforementioned fields uniquely identify each event. The data field contains data unique to each event.

Authorization event types

The Pismo platform supports the following authorization event types:

  • Network authorization ISO8583 message
  • Network authorization
  • Card network authorization return
  • Timeline
  • Clearing/Base II (raw messages)

These events are described in the following sections.

Network Authorization ISO8583 Message event

Domain: networktransactions

Type:

This event represents the raw message received from the card network in the authorization workflow. You can use it to verify all non-sensitive data received for a specific message (that is, messages other than Clearing/Base II messages). The Pismo platform issues an iso8583 event after parsing the message and removing any sensitive data from the payload. The event is not issued if an error or timeout prevents the message from reaching the platform.

An iso8583 event payload contains a base contract with any custom data included in the data field.

📘

Zero balance

This is the one event Zero balance issuers do not get, as they get the raw message as part of what is sent when Pismo calls the issuer's webhook as detailed in Steps 4 and 5 in the Full and zero balance workflows.

You can use the base contract's cid field to relate this event to other related events. For more details, visit Linking events in an authorization workflow.

📘

Message type indicator field

You can identify what kind of message is associated with an event using the mti field of the message. Here are a few examples of values for mti and the type of message each one represents.

  • 0100 - Authorization request
  • 0120 - Authorization advice
  • 0400 - Reversal request

For more information, see message type indicator

In the message field, there's a JSON payload representing all the fields present in the message received from the card network. The payload does not include fields for sensitive messages. The message field does not have a fixed payload, because it varies depending on the network. To identify each field present in the message, you need to look up the field in the network manual.

iso8583-message event examples

The following iso8583-message event examples illustrate the fields coming from different card networks. The content varies according to the request being processed, where some fields may or may not be present. Refer to the network specification to find all possible fields.

Mastercard example - iso8583-message event
Visa example - iso8583-message event
Tecban example - iso8583-message event

Network Authorization event

Domain: networktransactions

Type:

This event represents an action taken for an authorization. All actions performed in an authorization must emit a Network Authorization event. The Pismo platform issues the event after the message is processed and a decision is made about the action to take.

The field authorization_category identifies which type of action the event represents (authorization, declined, confirmation, cancellation, or partial cancellation). An operation can issue one or more Network Authorization events. Each event identifies an action performed during the operation. For example, if an operation is authorized, confirmed, and then canceled, three Network Authorization events must be issued with the categories AUTHORIZATION, CONFIRMATION, and CANCELLATION, respectively.

The payload of a Network Authorization event includes the base contract and the data field, which contains the details of the event in JSON format.

A Network Authorization event can be used as a base point to link other events issued in the authorization workflow. The Pismo platform sends this event for all actions related to an authorization record. The event contains all the information you need to identify the relationship between events, including the authorization id (authorization_id), correlation id (cid), and other values. For more details, visit Linking events in an authorization workflow.

📘

The Pismo platform does not issue a Network Authorization event if you use a Zero Balance workflow, since you control the authorization life cycle.

Card Network Authorization Return event

Domain: networktransactions

Type:

This event represents the response the Pismo platform sends to the card network in the online workflow for one operation. The platform issues it immediately before it sends the same response to the network. It can be used to verify that the authorization event emitted for this operation has the same result as the one sent to the network.

It's possible that the Pismo platform will approve an operation, issuing a Network Authorization event, but an error in processing will occur after the approval. In this case, the online response event will show a declined response while the Network Authorization event will show an approved response. The platform will notify the cardholder that the transaction was declined for an unknown reason and that they should try again. You can use both events to identify the error in the processing.

The platform uses the Card Network Authorization Return event to reconcile the previously saved status of an operation against the response sent to the network. If the two values are different, it indicates that an error occurred between the time when the decision was made and when the decision was sent to the network. In this case, an appropriate action is taken. For example, an authorization might be canceled, or the authorization team might be alerted so that they can fix the inconsistency.

The payload of this event consists of the base contract and the contents of the data field in JSON format: network-message-json-schema.

📘

A Card Network Authorization Return event is issued in both full and zero balance workflows.

Timeline events

The platform generates timeline events at the same time as the Network Authorization event and contain similar information. You can use the information from both events to obtain all information about the authorization, but the Network Authorization event is the primary source.

Domain: timeline

Types:

📘

Timeline events are not issued if you use a zero balance workflow, since you control the authorization life cycle.

Clearing/Base II events

Clearing/Base II events are emitted in two domains – networktransactions and authorization.

Domain: networktransactions

Type: clearing - This is the recommended Clearing/Base II event to use. In addition to raw data, it contains useful information to identify the account, card, program, file type, and network.

Domain: authorization

Types:

A Clearing/Base II event should be used to verify all non-sensitive data received for Clearing/Base II messages. These events have the same purpose as iso8583 events, since they also represent raw messages received from the card network. The Pismo platform issues a Clearing/Base II event after parsing the message and removing any sensitive data from the payload.

To identify each field present in the message, you need to look up the field in the network manual. The field names are the same as in the manual.

📘

Full vs zero balance

Clearing/Base II events are issued in both Full and Zero Balance workflows.

Clearing event examples

The following examples of the clearing event illustrate the fields from different card networks. The content varies according to the request being processed, where some fields may or may not be present. Refer to the network specification to find all possible fields.

Mastercard T112 dual message example - clearing event
Mastercard T464 single message example - clearing event
Mastercard fee collection event example
Visa EPIN example - clearing event
Tecban ServiceB example - clearing event