External Host Interface (EHI) Integration Guide

Back
Next

10.1 Applicable identifiers

Authorization reversal messages are identified using the original EHI fields included in the forwarded payload.

10.2 Authorization reversal flow

10.3 How your system should process authorization reversal messages

When your system receives an authorization reversal message, they should:

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

  2. Identify the message as an authorization reversal using Txn_Type=D and the applicable MTID.

  3. Check whether the reversal message was already received and processed.

  4. Match the reversal to the original 0100 / A authorization request using the EHI matching criteria.

  5. If the reversal matches a previous authorization, release or adjust the related blocked amount.

  6. If Txn_Amt in the reversal matches Txn_Amt in the original authorization request, treat it as a full reversal and unblock the amount that was originally blocked.

  7. If the reversal amount is lower than the original authorization amount, treat it as a partial reversal and adjust only the applicable remaining blocked amount.

  8. If a related 0120 / J authorization advice was received before the reversal, apply the block update from the advice before applying the reversal.

  9. Never unblock more than the amount currently blocked for the related transaction set.

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

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

If Txn_Amt in the reversal matches Txn_Amt in the original authorization request, it indicates a full reversal. It also notes that Bill_Amt may differ from the original because of exchange rate fluctuations, and that system should never unblock more than the amount currently blocked for the same transaction set.

10.4 Authorization reversal matching criteria

Your system should match authorization reversal messages to the original 0100 / A authorization request using the original EHI fields.

The matching logic can be understood as:

OTHER.Token = THIS.Token
AND, if THIS.traceid_lifecycle exists:
    OTHER.traceid_lifecycle = THIS.traceid_lifecycle
AND, if THIS.Auth_Code_DE38 exists:
    OTHER.Auth_Code_DE38 = THIS.Auth_Code_DE38
AND, if THIS.Trans_link exists:
    OTHER.Trans_link = THIS.Trans_link

If neither THIS.traceid_lifecycle nor THIS.Trans_link is present, there is no match. If the reversal is due to a timeout at the acquirer, THIS.traceid_lifecycle may not be present. Also the Auth_Code_DE38 is not mandatory for Visa authorization reversal transactions, and Auth_Code_DE38 = '000000' should be treated the same as blank.

10.5 Processing outcome

10.6 Required response

Authorization reversal messages must be acknowledged.

For 0400 / D and 0420 / D, your system should return a successful acknowledgement when the reversal has been processed.

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

  • Responsestatus: Required. Indicates the reversal response status.

Typical reversal response values:

  • Reversal processed successfully

    • Acknowledgement = 1

    • Responsestatus = 00

  • Temporary processing issue / resend requested

    • Acknowledgement = 0

    • Responsestatus = 91, 92 or 96

If your system cannot process the reversal because of a temporary issue, such as a database connection failure that prevents updating outstanding blocks, your system may request the message to be resent using Acknowledgement=0 and Responsestatus=96. It is also allowed response codes 91, 92, or 96 for this resend scenario.

10.7 Authorization reversal request example

{
    "AuthenticationAmountUpper": 0.0000,
    "FxProviderCardholderRate": 0.0,
    "DCC_Indicator": 0,
    "multi_part_txn": 0,
    "multi_part_txn_final": 0,
    "auth_type": "0",
    "auth_expdate_utc": "2022-12-26 07:27:14.180",
    "Matching_Txn_ID": 0,
    "Reason_ID": 0,
    "Merch_Name": "Travel Like A Pro",
    "Merch_Country": "HRV",
    "Merch_Tax_id": "0",
    "GPS_POS_Capability": "0011000010000000000000000000000000100000000001016",
    "GPS_POS_Data": "0168000800000Nx000",
    "Response_Source_Why": 0,
    "Message_Why": 0,
    "traceid_lifecycle": "BNET-20221219-MC 004279",
    "PaymentToken_id": 0,
    "PaymentToken_creatorStatus": " ",
    "PaymentToken_lang": "  ",
    "PaymentToken_activationMethod": 0,
    "Acquirer_id_DE32": "0852729540",
    "ActBal": 3535.47,
    "Amt_Tran_Fee_DE28": "D00000010",
    "Auth_Code_DE38": "183715",
    "Avl_Bal": 3401.72,
    "Bill_Amt": 10.00,
    "Bill_Ccy": "826",
    "BlkAmt": -133.75,
    "FX_Pad": 0.00,
    "Fee_Fixed": 0.50,
    "Fee_Rate": 0.00,
    "MCC_Code": "4111",
    "MCC_Desc": "Commuter Transport, Ferries",
    "MCC_Pad": 0.00,
    "Merch_ID_DE42": "4111           ",
    "Merch_Name_DE43": "Travel Like A Pro HRV",
    "Note": "Testing  User - Dhanya.B Date - 19/12/2022 16:18:08 BillAmt - 10.00 Location - Travel Like A Pro    ",
    "POS_Data_DE22": "010",
    "POS_Data_DE61": "2000000006000191",
    "POS_Termnl_DE41": "        ",
    "POS_Time_DE12": "072714",
    "Proc_Code": "000000",
    "Resp_Code_DE39": "00",
    "Ret_Ref_No_DE37": "235303504279",
    "Settle_Amt": 10.00,
    "Settle_Ccy": "826",
    "Status_Code": "00",
    "Token": 107612119,
    "Trans_link": "221219004279729540",
    "Txn_Amt": 10.0000,
    "Txn_CCy": "826",
    "Txn_Ctry": "HRV",
    "Txn_Desc": "Travel Like A Pro HRV",
    "Txn_GPS_Date": "2022-12-19 10:48:03.580",
    "TXn_ID": 6155806244,
    "Txn_Stat_Code": "A",
    "TXN_Time_DE07": "1219072714",
    "Txn_Type": "D",
    "Authorised_by_GPS": "N",
    "CU_Group": "CRN-CU-001",
    "InstCode": "TEST",
    "ProductID": 99884,
    "SubBIN": 52729540,
    "TLogIDOrg": 0,
    "VL_Group": "CRN-VL-100",
    "Dom_Fee_Fixed": 0.50,
    "Non_Dom_Fee_Fixed": 0.00,
    "Fx_Fee_Fixed": 0.00,
    "Other_Fee_Amt": 0.00,
    "Fx_Fee_Rate": 0.00,
    "Dom_Fee_Rate": 0.00,
    "Non_Dom_Fee_Rate": 0.00,
    "SendingAttemptCount": 0
}

10.8 Response examples

Successful reversal response

{  
    "Acknowledgement": "1",
    "Responsestatus": "00"
}

Temporary issue / resend requested response

{  
    "Acknowledgement": "0",
    "Responsestatus": "96"
}

10.9 Implementation notes

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

  • 0400 / D and 0420 / D should be treated the same in practice.

  • Authorization reversals should not be declined because they indicate that a reversal has already happened.

  • Your system should check whether the reversal was already received and processed before applying any balance or block impact.

  • Your system should match the reversal to the original 0100 / A authorization when possible.

  • If Txn_Amt in the reversal matches Txn_Amt in the original authorization request, treat it as a full reversal.

  • If Bill_Amt differs from the original authorization, do not automatically treat that as a mismatch; it may differ because of exchange rate changes.

  • Your system should apply any related 0120 / J authorization advice block update before applying the reversal.

  • Your system should never unblock more than the amount currently blocked for the same transaction set.

  • If Auth_Code_DE38 is 000000, treat it the same as blank for matching purposes.

  • If no matching authorization is found, store the reversal for reconciliation or exception handling.