External Host Interface (EHI) Integration Guide

Back
Next

12. Financial Reversal Messages

Financial reversal messages are sent when a previous financial or presentment impact needs to be reversed or adjusted.

As with all EHI messages, Payblr forwards this payload without transformation. Your system should process the EHI JSON payload using the EHI fields and return the required response for the message type.

A financial reversal is different from an authorization reversal. An authorization reversal releases or adjusts a previous authorization block. A financial reversal reverses or adjusts a previous financial or presentment transaction after funds were posted or taken.

A financial reversal may represent the cancellation or adjustment of all or part of a prior financial transaction, such as a purchase, refund, cashback, cash transaction, PIN change, or other transaction type.

12.1 Applicable identifiers

Financial reversal messages are identified using the EHI fields included in the forwarded JSON payload.

Financial notifications can include first presentments and financial reversals, including 1240 / E and Visa 25pp / E, 26pp / E, and 27pp / E.

12.2 Financial reversal flow

12.3 How your system should process financial reversal messages

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

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

  2. Identify the message as a financial reversal using Txn_Type = E and the applicable MTID.

  3. Check whether the financial reversal was already received or processed using the applicable EHI identifiers.

  4. Match the financial reversal to the prior financial notification or presentment using the EHI matching criteria.

  5. If a matching financial notification is found, reverse or adjust the previous posted financial impact according to your ledger rules.

  6. If the financial reversal reverses only part of the original financial impact, adjust only the applicable amount.

  7. If the financial reversal relates to a refund or credit-to-cardholder, apply your internal refund or credit reversal rules.

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

  9. Return the required acknowledgement response.

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

12.4 Financial reversal matching criteria

Your system should match financial reversal messages to the prior financial notification using the EHI fields.

When matching financial reversals, your system should use the available EHI matching fields in the following order where applicable:

Visa financial reversals 25pp / E, 26pp / E, and 27pp / E follow the same approach as 1240 / E. If matching cannot be done using Acquirer_Reference_Data_031, try traceid_lifecycle and Trans_link, and then Auth_Code_DE38 and Merch_ID_DE42.

12.5 Processing outcome

12.6 Required response

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

  • Acknowledgement: Required. Indicates that your system received and processed the financial reversal message.

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

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

12.7 Financial reversal request example

Available JSON guide example:

Actual request fields may vary by network, transaction type, configuration, and available transaction data. Use the full official Thredd JSON guide example or a confirmed UAT JSON payload when adding a complete request example to this page.

12.8 Response example

Minimal acknowledgement response:

12.9 Implementation notes

  • Financial reversal messages should not be treated as new authorization requests.

  • Financial reversals are different from authorization reversals. Authorization reversals release or adjust authorization blocks, while financial reversals reverse or adjust posted financial impact.

  • Your system should attempt to match the financial reversal to the prior financial notification when possible.

  • Your system should use Acquirer_Reference_Data_031 for matching when available.

  • If Acquirer_Reference_Data_031 cannot be matched, your system should try traceid_lifecycle and Trans_link.

  • If those fields cannot be matched, your system should try Auth_Code_DE38 and Merch_ID_DE42.

  • If no matching financial notification is found, your system should store the reversal and route it to reconciliation or exception handling.

  • Your system should avoid duplicate posting, balance, block, reserve, or ledger impact if the same financial reversal is received more than once.

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