New Fields in Transaction Event

We are introducing an event-level network_info to the transaction object, to assist you with locating transactions using identifiers shared between you, Lithic, the card network, and in some cases the acquirer. This will go into effect in sandbox on Tuesday, December 10th and in production on Tuesday, December 17th. More fields may be added here in the future.

"network_info": {
    "acquirer": {
      "acquirer_reference_number": String | null,
      "retrieval_reference_number": String | null
    },
    "mastercard": {
      "banknet_reference_number": String | null,
      "switch_serial_number": String | null
    },
    "visa": {
      "transaction_id": String | null
    }
}

Definitions

acquirer - contains fields assigned by the acquirer, that are standard between Visa and Mastercard. These fields can be used as common identifiers between the acquirer and the issuer to locate a particular transaction, such as during processing of disputes/chargebacks.

• acquirer_reference_number - applies to dual-message transactions.*
• retrieval_reference_number - applies to dual- and single-message transactions.

mastercard - contains fields assigned by Mastercard.

• banknet_reference_number - applies to dual- and single-message transactions.**
• switch_serial_number - applies to single-message transactions.

visa - contains fields assigned by Visa.

• transaction_id - applies to dual- and single-message transactions.

*The acquirer reference number (ARN) is only populated once a transaction has been cleared, and it is not available in all transactions (such as automated fuel dispenser transactions). A single transaction can contain multiple ARNs if the merchant sends multiple clearings. We will deprecate the existing acquirer_reference_number in the transaction object in favor of the new acquirer_reference_number in the event-level network_info.

**For single-message transactions, the banknet reference number (BRN) is only populated in certain cases, such as if the transaction is completed by a dual-message event (i.e. a financial authorization followed by a clearing).

Each field is populated contingent on the network and the dual- vs single- message system the given transaction event occurs on. If the field is populated by the network or the acquirer, we will pass it through. All fields are optional.

• If acquirer_reference_number and retrieval_reference_number are not populated, then acquirer is null.
• If banknet_reference_number and switch_serial_number are not populated, then mastercard is null.
• If transaction_id is not populated, then visa is null.
• If acquirer, mastercard, and visa are all null, then the entire network_info is null.

Simulating in Sandbox

For each event you simulate, Lithic generates a network_info object based on the networks’ guidelines for what fields can occur in what events, and what fields typically stay the same across the events in a transaction.

Keep in mind that real-life events will not always contain the fields that Lithic populates in sandbox, because these fields are ultimately set at the discretion of the acquirer or the network.

Lithic determines which network guidelines to follow based on the PAN of the card you use.

• If the PAN starts with 5, then Lithic treats the event (as well as the entire transaction this event constitutes) as if it occurs over Mastercard.
• If the PAN starts with 4, then Lithic treats the event (as well as the entire transaction this event constitutes) as if it occurs over Visa.

For instance, if you simulate an authorization using a PAN starting with 5, then the clearing you simulate against that authorization will automatically be associated with Mastercard.

Both networks

retrieval_reference_number is populated in each event.

acquirer_reference_number is not populated in any event.

Mastercard

switch_serial_number is populated in each single-message event, and has the same value across all events in a single-message transaction.

banknet_reference_number is populated in each event, and has the same value across all events* in a transaction.

*except for authorization advices. Lithic generates a new value for any authorization advice, to mirror what Mastercard typically does.

Visa

transaction_id is populated in each event, and has the same value across all events in a transaction.

If you have any questions or concerns, please contact us via the HELP link in your Lithic Dashboard.

The Lithic changelog has an RSS feed! To monitor for new update announcements, subscribe with your preferred RSS reader.