External Host Interface (EHI) Integration Guide

9. Authorization-Related Messages

Authorization messages include authorization decisioning messages, authorization repeats, and authorization advice messages.

Authorization decisioning messages ask your system to make or return a real-time authorization decision. Authorization advice messages notify your systems of an authorization-related event that has already occurred or was generated outside the standard real-time authorization request flow.

9.1 Authorization decisioning identifiers

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

For this integration, your system should treat authorization messages as decisional when a response is required by the EHI flow.

9.2 Authorization decisioning flow

9.3 How your system should process authorization decisioning messages

When your system receives an authorization message, the message should be processed in the synchronous authorization path.

Validate Payblr’s integration headers, signature, timestamp, and raw payload before processing.
Identify the message as an authorization using MTID=0100 and Txn_Type=A.
Check whether the message was already received or processed using the applicable EHI identifiers.
Identify the card, cardholder, or account using Token and your internal mapping.
Calculate the total transaction impact using billing amount, transaction amount, fees, pads, and any applicable adjustments.
Evaluate available balance, account status, fraud rules, merchant rules, country rules, velocity rules, and other client-side business controls.
Determine whether the transaction should be approved, declined, or partially approved.
Return the required authorization response within the configured processing window.
Store the request, response, decision outcome, transaction identifiers, and x-correlation-id for audit, duplicate handling, and reconciliation.

9.4 Important fields for authorization decisioning

The following fields are commonly useful when evaluating an authorization request. Your system may use additional fields depending on your program rules and internal processing logic.

9.5 Balance and authorization impact

Your system are responsible for calculating the total authorization impact and deciding whether the transaction should be approved, declined, or partially approved.

9.6 Required response for authorization decisioning messages

For authorization messages, your system must return an authorization response using the expected EHI response structure.

The required response fields for authorization messages include:

Acknowledgement – Required. Indicates that your system received and processed the message.
Responsestatus – Required. Indicates the authorization decision returned by your system.

Typical authorization response values include:

Approve – Return Acknowledgement = 1 and Responsestatus = 00.
Decline – Return Acknowledgement = 1 and Responsestatus = 05.
Partial approval – Return Acknowledgement = 1 and Responsestatus = 10 when partial approval is supported and applicable.

A controlled decline is preferred over a timeout or unhandled error when your systems cannot approve the transaction. This allows the transaction to be handled predictably instead of failing because of a missing or delayed response.

9.7 Request example

The following example shows a Visa authorization request in the original EHI JSON format.

Payblr forwards the EHI payload to your system without transforming the transaction payload. Your system should expect the original message structure, field names, field casing, populated values, and empty elements to be preserved.

This example is intended to show the size and structure of the payload your system may receive. Your implementation should not depend only on the fields shown as populated in this example. Additional fields may be present, and some fields may be empty when they are not applicable to the transaction.

{
    "Acquirer_Country": "GBR",
    "FxProviderCardholderRate": 0.0,
    "POS_Date_DE13": "00000000",
    "Traceid_Message": "VIS1-20221219-002353117950020",
    "Visa_POS_Data_DE60": "020000000000",
    "Network_Transaction_ID": "0002353117950020",
    "DCC_Indicator": 0,
    "multi_part_txn": 0,
    "multi_part_txn_final": 0,
    "auth_type": "0",
    "auth_expdate_utc": "2022-12-27 07:28:36.045",
    "Merch_Name": "Travel Like A Pro",
    "Merch_Country": "HRV",
    "GPS_POS_Capability": "00001001000000000000000100010010001000000001130C0",
    "GPS_POS_Data": "9968000800000Nx000NNNNNU0NUUXXU",
    "Response_Source_Why": 0,
    "Message_Why": 0,
    "traceid_lifecycle": "VIS1-20221219-002353117950020",
    "Balance_Sequence": 114,
    "Balance_Sequence_Exthost": 0,
    "Acquirer_id_DE32": "0844622180",
    "ActBal": 10001.0000,
    "Auth_Code_DE38": "143088",
    "Avl_Bal": 10001.0000,
    "Bill_Amt": 1.0000,
    "Bill_Ccy": "826",
    "BlkAmt": 0.0000,
    "FX_Pad": 0.0000,
    "Fee_Fixed": 0.0000,
    "Fee_Rate": 0.0000,
    "MCC_Code": "4111",
    "MCC_Desc": "Commuter Transport, Ferries",
    "MCC_Pad": 0.0000,
    "Merch_ID_DE42": "4111",
    "Merch_Name_DE43": "Travel Like A Pro HR",
    "POS_Data_DE22": "0110",
    "Proc_Code": "200000",
    "Resp_Code_DE39": "00",
    "Ret_Ref_No_DE37": "235303502517",
    "Settle_Amt": 1.0000,
    "Settle_Ccy": "826",
    "Status_Code": "00",
    "Token": 107419774,
    "Trans_link": "221219002517622180",
    "Txn_Amt": 1.0000,
    "Txn_CCy": "826",
    "Txn_Ctry": "HRV",
    "Txn_Desc": "Travel Like A Pro HR",
    "Txn_GPS_Date": "2022-12-19 07:28:37.526",
    "TXn_ID": 6155805913,
    "Txn_Stat_Code": "A",
    "TXN_Time_DE07": "1219072835",
    "Txn_Type": "A",
    "Authorised_by_GPS": "N",
    "CU_Group": "DEF_PV",
    "InstCode": "TEST",
    "MTID": "0100",
    "ProductID": 99883,
    "SubBIN": 44622180,
    "TLogIDOrg": 0,
    "VL_Group": "MLMS_PV_GB",
    "Dom_Fee_Fixed": 0.0000,
    "Non_Dom_Fee_Fixed": 0.0000,
    "Fx_Fee_Fixed": 0.0000,
    "Other_Fee_Amt": 0.0000,
    "Fx_Fee_Rate": 0.0000,
    "Dom_Fee_Rate": 0.0000,
    "Non_Dom_Fee_Rate": 0.0000,
    "PIN": "0",
    "SendingAttemptCount": 0
}

9.8 Response examples

Approval response

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

Decline response

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

Partial approval response, when applicable

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

9.9 Authorization repeats

Authorization repeat messages may be received when an authorization request is repeated through the EHI transaction flow.

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

Authorization repeats are important because your system must avoid duplicate balance, block/reserve, or ledger impact when the repeat relates to an authorization that was already processed.

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

Authorization repeat flow

When your system receive an authorization repeat, they should:

Validate Payblr’s integration headers, signature, timestamp, and raw payload before processing.
Identify the message as an authorization repeat using MTID=0101 and Txn_Type=A.
Search for the original authorization request using the EHI matching criteria.
If the original 0100 / A authorization is found, treat the repeat as the same authorization.
If the original authorization is found, do not block, reserve, post, or adjust funds again.
Return the same authorization response returned for the original 0100 / A authorization.
If the original authorization is not found, process the repeat as a new authorization request.
Store the repeat message, matching result, response returned, and x-correlation-id for audit and reconciliation.

9.10 Authorization repeat matching criteria

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

Processing outcome

Response behavior

Authorization repeats use authorization-style responses.

If the original authorization is found, your system should return the same logical response that was returned for the original authorization.

Implementation note

Authorization repeats should not automatically be treated as duplicate messages only because they are repeated.

Your system should first try to match the 0101 / A repeat to the original 0100 / A authorization. If the original authorization is found, the repeat represents the same authorization. If the original authorization is not found, your system should process the repeat as a new authorization request.

The more matching criteria your system can confirm, the more reliable the match

9.11 Authorization advice messages

Authorization advice messages are authorization-related messages that notify your system of an authorization event that has already occurred or was generated outside the standard real-time authorization request flow.

Unlike an authorization decisioning message, an authorization advice message is generally not asking your system to make a new approve or decline decision. Instead, your system should process the advice for transaction history, balance or block updates, ledger handling, and reconciliation.

Your system should process the advice using the original EHI fields and match it to the original authorization when possible.

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

Authorization advice flow

When your system receive an authorization advice message, they should:

Validate Payblr’s integration headers, signature, timestamp, and raw payload before processing.
Identify the message as an authorization advice using MTID=0120 and Txn_Type=J.
Check whether the advice message was already received or processed using the applicable EHI identifiers.
Attempt to match the advice to the original 0100 / A authorization request using the EHI matching criteria.
Review Resp_Code_DE39 to determine whether the advised authorization was approved or declined, when this field is populated.
If the advice indicates approval, update or replace the existing block for the transaction using the amount in the advice, when applicable.
If the advice indicates decline, remove the block for the transaction, when applicable.
If the processing code indicates a credit, apply your internal credit-handling rules. Your system may choose not to change blocks for credit scenarios.
If no matching original authorization is found, store the advice as unmatched and process it according to your reconciliation or exception-handling rules.
Store the advice message, matching result, response returned, and x-correlation-id for audit, duplicate handling, and reconciliation.

9.12 Authorization advice matching criteria

Your system should match the 0120 / J authorization advice to the original 0100 / A authorization request using the original EHI fields.

Payblr does not modify, normalize, or create separate matching fields. Your system should apply the matching criteria using the original field names and values received in the EHI payload.

The matching logic can be understood as:

OTHER.Token = THIS.Token
AND (
    OTHER.traceid_lifecycle = THIS.traceid_lifecycle, if THIS.traceid_lifecycle exists
    OR OTHER.Auth_Code_DE38 = THIS.Auth_Code_DE38, if THIS.Auth_Code_DE38 exists
    OR OTHER.Trans_link = THIS.Trans_link, if THIS.Trans_link exists
)

The original authorization request may not always exist. If a matching 0100 / A authorization is not found, your system should still store the advice and process it according to your reconciliation or exception-handling rules.

Processing outcome

9.13 Authorization advice response and examples

Authorization advice messages should generally be acknowledged after your system receives and process the message.

Acknowledgement: Required. Indicates that the system received and processed the advice message.
Responsestatus: Optional. May be included when required by the EHI response contract or your program configuration.

For authorization advice messages, your system generally returns an acknowledgement response rather than a new approve or decline decision.

Authorization advice request example

{
    "FxProviderCardholderRate": 0.0,
    "POS_Date_DE13": "00000000",
    "Visa_ResponseInfo_DE44": "020000000000",
    "Visa_STIP_Reason_Code": "9020",
    "Network_Transaction_ID": "0002353127640022",
    "DCC_Indicator": 0,
    "multi_part_txn": 0,
    "multi_part_txn_final": 0,
    "auth_type": "0",
    "auth_expdate_utc": "2022-12-27 07:44:44.137",
    "Matching_Txn_ID": 0,
    "Reason_ID": 0,
    "Merch_Name": "Passenger Railway - SCAEx",
    "Merch_Country": "CYP",
    "Merch_Tax_id": "0",
    "GPS_POS_Capability": "00001001000000000000000100010010001000000001130C0",
    "GPS_POS_Data": "9968000800000Nx000",
    "Response_Source": "VISA-STIP",
    "Response_Source_Why": 5,
    "Message_Source": "VISA-STIP",
    "Message_Why": 5,
    "traceid_lifecycle": "VIS1-20221219-002353127640022",
    "PaymentToken_id": 0,
    "PaymentToken_creatorStatus": " ",
    "PaymentToken_lang": "  ",
    "PaymentToken_activationMethod": 0,
    "Acquirer_id_DE32": "0844622180",
    "ActBal": 10001.00,
    "Avl_Bal": 10001.00,
    "Bill_Amt": 1.00,
    "Bill_Ccy": "826",
    "BlkAmt": 0.00,
    "FX_Pad": 0.00,
    "Fee_Fixed": 0.00,
    "Fee_Rate": 0.00,
    "MCC_Code": "4112",
    "MCC_Pad": 0.00,
    "Merch_ID_DE42": "4112           ",
    "Merch_Name_DE43": "Passenger Railway - SCAEx CY",
    "POS_Data_DE22": "0110",
    "Proc_Code": "000000",
    "Resp_Code_DE39": "00",
    "Ret_Ref_No_DE37": "235303502519",
    "Settle_Amt": 0.00,
    "Status_Code": "00",
    "Token": 107419774,
    "Trans_link": "221219002519622180",
    "Txn_Amt": 1.0000,
    "Txn_CCy": "826",
    "Txn_Ctry": "CYP",
    "Txn_Desc": "Passenger Railway - SCAEx CY",
    "Txn_GPS_Date": "2022-12-19 07:44:44.203",
    "TXn_ID": 6155805963,
    "Txn_Stat_Code": "A",
    "TXN_Time_DE07": "1219074444",
    "Txn_Type": "J",
    "Authorised_by_GPS": "N",
    "InstCode": "TEST",
    "MTID": "0120",
    "ProductID": 99883,
    "SubBIN": 44622180,
    "TLogIDOrg": 0,
    "Dom_Fee_Fixed": 0.0000,
    "Non_Dom_Fee_Fixed": 0.0000,
    "Fx_Fee_Fixed": 0.0000,
    "Other_Fee_Amt": 0.0000,
    "Fx_Fee_Rate": 0.0000,
    "Dom_Fee_Rate": 0.0000,
    "Non_Dom_Fee_Rate": 0.0000,
    "SendingAttemptCount": 0
}

Minimal acknowledgement response

{  
    "Acknowledgement": "1"
}

9.14 Authorization advice implementation notes

Authorization advice messages should not be treated as new 0100 / A authorization requests.
Your system should attempt to match the advice to the original 0100 / A authorization when possible.
Your system should use Resp_Code_DE39 to determine whether the advised transaction was approved or declined when that field is populated.
If the advice indicates approval, your system should update or replace the existing block when applicable.
If the advice indicates decline, your system should remove the related block when applicable.
If the advice relates to a credit, your system may choose not to change blocks.
If the matching authorization does not exist, your system should store the advice and route it to reconciliation or exception handling according to your internal process.
Your system should avoid duplicate block, balance, block/reserve, or ledger impact if the same advice 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, and x-correlation-id.

9.15 Authorization duplicate or retry handling

If your system receives the same authorization message more than once, they should not automatically treat it as a new transaction.

Duplicates or retries may happen due to timeouts, network interruptions, or repeated delivery attempts. Your system should use the original EHI identifiers to determine whether the message was already processed.

Common identifiers for duplicate or retry handling include:

If the authorization has already been processed, your system should: