Linking authorization events

The authorization platform emits multiple events for each operation action. You can use these events to verify operation life cycle and monitor how events impact other parts of the flow, outside of the authorization itself.

Each event represents one step in the authorization process life cycle 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 – Raw message in the authorization request.
• network-authorization – Request approval. AUTHORIZATION category
• timeline/authorization_authorize – Request approval
• network-message – Approval response

Clearing/base II (reconciliation flow):

• raw_credit_visa – Raw message received in the clearing/base II flow. Event type depends on the operation type and network used.
• network-authorization – CONFIRMATION category. Request confirmation.
• timeline/confirmation_authorize – Request confirmation.

To map an authorization's entire life cycle, you need to identify every related issued event. Each authorization action generates events that need to be linked to other events the authorization generates. The following sections show how to link the events of a single action and how to link events of different actions.

Single action event mapping

A single action is any message received from the network that Pismo processes such as:

• Authorization request
• Cancellation request
• Reconciliation flow message

Authorization online flow events

Online flow steps:

1. Pismo 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, after first validating it, Pismo removes any sensitive data.
2. Pismo issues an iso8583 event containing the information. The event payload contains a base contract with a cid (correlation identifier) field. This field is used to link this event with later Pismo-issued events.
3. Pismo 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 is used to link the events of other actions over this authorization.
4. At the end of the flow, right before responding to the network, the platform issues a network-message event with the same cid value.

As should be evident, the easiest way to link events is via the cid field.

The flow is depicted below.

📘

Zero balance and the cid field

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.

Reconciliation flow events

Reconciliation flow events:

1. Pismo receives a message from the network indicating that an authorization is confirmed or cancelled. Pismo parses the message and removes any sensitive data.
2. Pismo 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.
3. Pismo 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.

As usual, the easiest way to link events is via the cid field.

Reconciliation flow:

🚧

Reconciliation message notes

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 network-authorization event category will be “AUTHORIZATION”. The authorization_id will contain a new id and will not be related to previous network-authorization events.

📘

Zero balance notes

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 a single action's events, you need to link the events from actions for 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.