Authorization events

Events emitted during the authorization of network transactions and how to use them to verify the information associated with those transactions.

The Pismo platform emits a number of events during the authorization workflow. By handling these events, you can track the status of the transaction and verify relevant information.

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

In Full Balance workflows, you must rely on the authorization events to follow the progress of an authorization.

In Zero Balance workflows, you receive information about authorizations via webhooks, but Pismo recommends that you also consume the Card Network Authorization Return event to ensure that the response message was sent correctly to the card network. For example, if the Pismo platform authorizes a transaction, but an error happens in the platform's connection with the card network, checking the tcp_error field of this event will alert you to the error. The other authorization events can also provide useful information for Zero Balance workflows.

Authorization event characteristics

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

Each event emitted by the platform has a domain and a type. The platform uses the value pair domain/type to identify events. Each event uses a base contract for its payload. This defines a pattern inside the platform. The base contract includes fields for the event_id, domain, and event_type. It also has a data field that contains any custom data for the event in JSON format.

Authorization event types

The Pismo platform supports the following main types of authorization events.

  • Network Authorization ISO8583 Message event
  • Clearing/Base II (raw messages) events
  • Network Authorization event
  • Card Network Authorization Return event
  • Timeline events [Deprecated]

These events are described in the following sections.

Network Authorization ISO8583 Message event

Domain: networktransactions

Types:

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 will not be issued if an error or timeout prevents the message from reaching the platform.

The payload of an iso8583 event consists of a base contract with any custom data included in the data field.

To relate this event to other events, you use the cid field in the base contract. This field will have the same value as the other events issued for this message during authorization. For more details, visit Linking events in an authorization workflow.

📘

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

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.

📘

The Pismo platform does not issue the iso8583 event for Zero Balance workflows, since it sends the same raw message payload in the call it performs during the authorization workflow.

Clearing/Base II (raw messages) events

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.

📘

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

Network Authorization event

Domain: networktransactions

Types:

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

Types:

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 [DEPRECATED]

Timeline events are deprecated. You should use the Network Authorization event, instead. You can use the mti field of a Network Authorization event to tell which of the timeline event types it replaces.

Domain: timeline

Types:

📘

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


Did this page help you?