External Host Interface (EHI) Integration Guide

Back
Next

13. Chargeback and Chargeback Reversal Messages

Chargeback messages are sent when a dispute-related financial event occurs after a transaction has already been presented. A chargeback can only be created for a transaction that has a linked presentment. In the EHI transaction flow, a chargeback notification is sent to your system, and your system returns an acknowledgement.

As with all EHI messages, Payblr forwards the EHI JSON payload to your configured endpoint. Your system should process the message using the EHI fields, optionally match it to the related financial notification or chargeback, and update dispute, ledger, and reconciliation records according to your internal rules.

Chargeback messages are different from authorization, authorization reversal, and financial reversal messages. They are dispute-related financial notifications and should not be treated as new authorization requests.

Note: For the Payblr integration, document chargeback processing using 1240 / H for chargeback notification and 1240 / K for chargeback reversal.

13.1 Applicable identifiers

Chargeback and chargeback reversal messages are identified using the EHI fields included in the forwarded JSON payload.

1240 / H identifies a chargeback notification, non-credit, and 1240 / K identifies a chargeback reversal.

13.2 Chargeback flow

13.3 Chargeback reversal flow

13.4 How your system should process chargeback messages

When your system receives a chargeback message, they should:

  1. Validate Payblr’s integration headers, signature, timestamp, and original EHI JSON payload before processing.

  2. Identify the message as a chargeback using MTID = 1240 and Txn_Type = H.

  3. Check whether the chargeback message was already received or processed using the applicable EHI identifiers.

  4. Optionally match the chargeback to the related financial notification using the EHI matching criteria.

  5. Review dispute-related fields such as Reason_ID, Dispute_Condition, and Network_Chargeback_Reference_Id, when present.

  6. Update dispute, ledger, transaction history, and reconciliation records according to your internal rules.

  7. If no matching financial notification is found, store the chargeback as unmatched and process it according to your reconciliation or exception-handling process.

  8. Return the required acknowledgement response.

  9. Store the chargeback message, matching result, response returned, and x-correlation-id for audit, duplicate handling, and reconciliation.

13.5 How your system should process chargeback reversal messages

When your system receives a chargeback reversal message, they should:

  1. Validate Payblr’s integration headers, signature, timestamp, and EHI JSON payload before processing.

  2. Identify the message as a chargeback reversal using MTID = 1240 and Txn_Type = K.

  3. Check whether the chargeback reversal was already received or processed.

  4. Optionally match the chargeback reversal to the original 1240 / H chargeback message.

  5. Reverse or adjust the previous chargeback-related ledger or dispute impact according to your internal rules.

  6. If no matching chargeback is found, store the chargeback reversal as unmatched and process it according to your reconciliation or exception-handling process.

  7. Return the required acknowledgement response.

  8. Store the chargeback reversal message, matching result, response returned, and x-correlation-id for audit, duplicate handling, and reconciliation.

A 1240 / K chargeback reversal reverses the effect of a chargeback, for example reversing the impact on the account balance if the original chargeback changed it.

13.6 Chargeback matching criteria

Your system may match chargeback notifications to the related financial notification using the original EHI fields.

When matching chargeback notifications, your system may use the following fields when available:

Some fields may be blank or unavailable in certain chargeback messages. Your system should store unmatched chargebacks for reconciliation or exception handling when a reliable match cannot be confirmed.

13.7 Chargeback reversal matching criteria

Your system may match a chargeback reversal to the original chargeback message using the original EHI fields.

The matching logic can be understood as:

OTHER.MTID = '1240'
AND OTHER.Txn_Type = 'H'
AND OTHER.Acquirer_Reference_Data_031 = THIS.Acquirer_Reference_Data_031
AND OTHER.Token = THIS.Token
AND OTHER.Auth_Code_DE38 = THIS.Auth_Code_DE38
AND OTHER.Trans_link = THIS.Trans_link

1240 / K follows the same matching approach as chargeback matching, except the original transaction to match has Txn_Type = H.

13.8 Processing outcome

13.9 Required response

Chargeback and chargeback reversal messages should be acknowledged after your system receives and processes the message.

  • Acknowledgement: Indicates that your system received and processed the chargeback or chargeback reversal message.

  • Responsestatus: Optional. May be included when required by the EHI response contract or program configuration.

For chargeback and chargeback reversal messages, your system generally returns an acknowledgement response instead of a new approve or decline decision.

13.10 Chargeback request examples

Chargeback request example with Txn_Type = C, for Mastercard:

13.11 Chargeback reversal request examples

Chargeback reversal request example with Txn_Type = K, for Mastercard:

13.12 Response example

Minimal acknowledgement response:

13.13 Implementation notes

  • Chargeback messages should not be treated as authorization requests.

  • Chargeback messages should be processed as dispute-related financial notifications.

  • 1240 / H identifies a chargeback notification, non-credit.

  • 1240 / K identifies a chargeback reversal.

  • Your system may match chargebacks to the related financial notification when possible.

  • Your system may match chargeback reversals to the original 1240 / H chargeback when possible.

  • Your system should use Reason_ID, Dispute_Condition, and Network_Chargeback_Reference_Id when available for dispute and reconciliation handling.

  • If no reliable match is found, your system should store the message and route it to reconciliation or exception handling.

  • Your system should avoid duplicate dispute, ledger, balance, or reconciliation impact if the same chargeback or chargeback reversal is received more than once.

  • Your system should store key identifiers such as Token, TXn_ID, Acquirer_Reference_Data_031, Auth_Code_DE38, Trans_link, Reason_ID, Network_Chargeback_Reference_Id, and x-correlation-id.