Linking events in an authorization workflow

Using events to map the life cycle of an authorization.

The authorization platform emits multiple events for each action in an operation. These events can be used to verify the life cycle of the operation and to monitor the impacts of those events in other parts of the flow, outside of the authorization itself.

Each event represents one step in the life cycle of the authorization process and provides all the relevant information for that step. For example, an authorization request that is approved and then confirmed in the clearing/base II flow issues the following events.

Authorization request (online flow):

  • iso8583-message – Represents the raw message received in the authorization request.
  • network-authorization – category: AUTHORIZATION. Represents the approval of the request.
  • timeline/authorization_authorize – Represents the approval of the request.
  • network-message – Represents the approval response sent to the network.

Clearing/base II (reconciliation flow):

  • raw_credit_visa – Represents the raw message received in the clearing/base II flow. It could be any type of event, depending on the type of the operation and network used.
  • network-authorization – category: CONFIRMATION. Represents the confirmation of the request).
  • timeline/confirmation_authorize – Represents the confirmation of the request.

To map the entire life cycle of an authorization, you need to identify every issued event that is related to it. Each action performed for an authorization will generate events that need to be linked to other events generated by the authorization. The following sections show how to link the events of a single action and how to link events of different actions.

Mapping the events associated with a single action

A single action is any message received from the network and processed by the Pismo platform. It can be an authorization request, a cancellation request, or a message in the reconciliation flow.

Linking online flow events

This section uses an authorization request as an example of how to link events. Any action performed in an online flow (cancellations, advice messages, and declined transactions) will follow the same rules.

In the online flow, the platform receives a message from the network indicating that an authorization request has been made. This message has its own kind of encoding and also contains sensitive data, so the Pismo platform parses it and removes any sensitive data (after first validating it). The platform then issues an iso8583 event containing the information. The event payload contains a base contract with a cid field. This field is used to link this event with later events issued by the platform.

Next, the Pismo platform processes the request and issues a network-authorization event and a timeline event. The network-authorization event has the same cid value as the iso8583-message event. It also contains a data.authorization_id field. This field contains the internal authorization_id generated for the authorization. This id will be used to link the events of other actions over this authorization.

At the end of the flow, right before responding to the network, the platform issues a network-message event with the same cid value.

So, the easiest way to link these events is to use the cid field.

The flow is depicted below.

10301030

📘

For Zero Balance workflows, you must use the field id present in the payload that is sent in the authorization flow to find the respective network-message event. The value in this field is the same as the value in the cid field.

Linking reconciliation flow events

This section uses a confirmation message as an example of how to link reconciliation events. Any other action performed in the reconciliation flow will follow the same rules.

In the reconciliation flow, the Pismo platform receives a message from the network indicating that an authorization is confirmed or cancelled. The platform parses the message and removes any sensitive data. The platform then issues an event with this raw information (raw**). The event payload contains a base contract with a cid field that you can use to link this event with later events.

Next, the platform processes the request and issues a network-authorization event and a timeline event. The network-authorization event has a cid field with the same value as in the raw** event. It also has a data.authorization_id field. This is the internal id generated for the authorization. This id is the same as the one in the online flow. It links the events of all actions taken by this authorization.

The easiest way to link these events is to use the cid field.

The flow is depicted below.

10301030

🚧

A reconciliation message may not be related to an authorization. When a new authorization is created, the events issued are the same as those described here, but the category of the network-authorization event will be “AUTHORIZATION”. The authorization_id will contain a new id and will not be related to previous network-authorization events.

📘

For Zero Balance workflows, you receive the raw reconciliation event and must use this event to perform the reconciliation flow on your side.

Mapping events of different actions taken over an authorization

After linking the events of a single action, you need to link the events issued by different actions in the same authorization. You can use the network-authorization event to do this.

Here are two examples.

Linking authorization with cancellation in online flow

If an operation is approved and then cancelled, the platform issues events for both actions (approval and cancellation). You can use the network-authorization event to link these events.

For example, suppose an operation is approved that has an authorization_id of 12345, a cid equal to uuid-abc-777, and an authorization_code of ABC123. The network-authorization event for the approval will have the following payload.

{
    "event_id": "unique-event-id",
    "domain": "networktransactions",
    "event_type": "network-authorization",
    "schema_version": "1",
    "org_id": "org-id",
    "cid": "uuid-abc-777",
    "timestamp": "2021-01-01T00:00:00.000Z",
    "data": {
        "mti": "0100",
        "authorization_category": "AUTHORIZATION",
        "authorization_type": "NETWORK",
        "authorization_id": 12345,
        "authorization_code": "ABC123",
        "authorization_status":1,
        "ledger_update_id": "uuid-ledger-id",
        ...
        other fields omitted
        ...
    }
}

When the Pismo platform processes the cancellation, it issues an event with a new cid, which is used to link all the events of the cancellation flow. But the information for the operation, such as the authorization_id and the authorization_code, must be the same. The cancellation event will have the following payload.

{
    "event_id": "unique-event-id",
    "domain": "networktransactions",
    "event_type": "network-authorization",
    "schema_version": "1",
    "org_id": "org-id",
    "cid": "uuid-333-zzz",
    "timestamp": "2021-01-02T00:00:00.000Z",
    "data": {
        "mti": "0400",
        "authorization_category": "CANCELLATION",
        "authorization_type": "NETWORK",
        "authorization_id": 12345,
        "authorization_code": "ABC123",
        "authorization_status":4,
        "ledger_update_id": "uuid-ledger-id-cancel",
        ...
        other fields omitted
        ...
    }
}

In this case, you can link both events using the authorization_id field, since it's a unique identifier for that authorization. It's possible to use fields like tid and retrieval_reference_number to link authorization messages, but those fields are not guaranteed to be the same for all messages, since they are generated by the acquirer and the network, so Pismo recommends that you use the authorization_id for this linking.

Linking authorization with confirmation events

You can use the network-authorization event to link an authorization with a confirmation received from the reconciliation flow.

Here's the network-authorization event for the previous example.

{
    "event_id": "unique-event-id",
    "domain": "networktransactions",
    "event_type": "network-authorization",
    "schema_version": "1",
    "org_id": "org-id",
    "cid": "uuid-abc-777",
    "timestamp": "2021-01-01T00:00:00.000Z",
    "data": {
        "mti": "0100",
        "authorization_category": "AUTHORIZATION",
        "authorization_type": "NETWORK",
        "authorization_id": 12345,
        "authorization_code": "ABC123",
        "authorization_status":1,
        "ledger_update_id": "uuid-ledger-id",
        ...
        other fields omitted
        ...
    }
}

When the Pismo platform processes the confirmation for this authorization, it issues a new event. The event contains the following payload.

{
    "event_id": "unique-event-id",
    "domain": "networktransactions",
    "event_type": "network-authorization",
    "schema_version": "1",
    "org_id": "org-id",
    "cid": "uuid-abc-777",
    "timestamp": "2021-01-01T00:00:00.000Z",
    "data": {
        "mti": "0100",
        "authorization_category": "CONFIRMATION",
        "authorization_type": "NETWORK",
        "authorization_id": 12345,
        "authorization_code": "ABC123",
        "authorization_status":2,
        ...
        other fields omitted
        ...
    }
}

You can link both events using the authorization_id field, since it's a unique identifier for that authorization. It's possible to use fields like tid and retrieval_reference_number to link authorization messages, but those fields are not guaranteed to be the same for all messages, since they are generated by the acquirer and the network. So Pismo recommends that you use the authorization_id for this linking.

📘

In the reconciliation flow, there could be different amounts in the confirmation payload. This indicates that the authorization was confirmed with a different value, and this difference impacted the account limits. Also, there could be many partial cancellation events for the same authorization, all of them with amounts less than the total amount of the authorization.

Using these two types of linking -- events of a single action and events of different actions -- you can map the entire life cycle of an operation. You can tell if it was approved or declined; if it was approved, confirmed, and then cancelled; or if it was partially cancelled. The purpose of the events issued by the platform is to provide you with the information you need to monitor and control your tenant accounts and the operations realized through the network authorization flow.

Mapping events external to the network-authorization events

Using the network-authorization event, it's possible to link external events created by other APIs or other groups. Those events are transaction creation and account limits impacts.

Linking transaction creation events

When the Pismo platform approves and confirms an authorization, it creates a transaction and posts it to the cardholder. This generates a transaction creation event (domain: transaction, type: creation). The data.authorization.id field for this event should contain the same authorization id as the data.authorization.id field of the network-authorization event. This confirms that the platform created a transaction for the authorization.

Linking account limits impact events

If an action should have an impact on the limit of an account, the authorization platform calls the Ledger API to perform this impact. The Ledger API registers a unique id for the impact. You can use this id to link the impact with the action that caused it. The Ledger API emits an event to indicate the impact (domain: availables, type: change_available)

The network-authorization event has a ledger_update_id field that contains the id for the impact event. You can use this to link the network-authorization event to the impact event. This confirms that Pismo applied the impact to the account limits.

📘

A network-authorization event can have a null value in the ledger_update_id field. This indicates that the operation had no impact on the account limits. For example, when there is a confirmation in the reconciliation flow with the same amount that was approved, there is no impact on the account limits.


Did this page help you?