External Host Interface Integration Guide
6. What Your System Receives
Your system receives a request from Payblr containing:
The EHI payload.
Payblr integration headers used for tracing and request validation.
6.1 Request body
The request body contains the EHI message payload.
Your system should be prepared to receive the full EHI message, including transaction, merchant, balance, fee, network, tokenization, authentication, matching, and lifecycle fields. Click here for an example of an Authorization Request body.
The payload may include:
| Payload may include | Examples |
|---|---|
| Message identifiers | MTID, Txn_Type, Txn_Stat_Code, TXn_ID, Txn_ID |
| Card / token fields | Token, ProductID, SubBIN, payment token fields |
| Amount and currency fields | Txn_Amt, Txn_CCy, Bill_Amt, Bill_Ccy, Settle_Amt, Settle_Ccy |
| Balance fields | ActBal, Avl_Bal, BlkAmt |
| Fee fields | Fee_Fixed, Fee_Rate, Dom_Fee_Fixed, Dom_Fee_Rate, Fx_Fee_Fixed, Other_Fee_Amt |
| Merchant fields | MCC_Code, MCC_Desc, Merch_ID_DE42, Merch_Name_DE43, Merch_Country |
| POS fields | POS_Data_DE22, POS_Termnl_DE41, POS_Time_DE12, POS_Date_DE13 |
| Matching fields | traceid_lifecycle, Traceid_Message, Traceid_Original, Trans_link, Auth_Code_DE38, Ret_Ref_No_DE37 |
| Network / reference fields | Network_Transaction_ID, SchemeTransactionIdentifier, Acquirer_Reference_Data_031 |
| Authentication fields | AuthenticationCurrency, AuthenticationAmountUpper, AuthenticationMerchantHash |
| Retry / delivery fields | SendingAttemptCount |
| Cut-off fields | CutOffId, when present |
6.2 Payblr integration headers
Payblr includes integration headers so your systems can trace and validate the request.
Your systems should log x-correlation-id together with the EHI transaction identifiers and the response returned to Payblr.
| Header | Purpose |
|---|---|
x-correlation-id | Used for tracing. Your systems should log x-correlation-id together with the EHI transaction identifiers and the response returned to Payblr. |
x-ehi-signature | Used for request validation with the HMAC signature generated by Payblr. |
x-ehi-signature-algorithm | Identifies the signature algorithm. Expected value: hmac-sha256. |
x-ehi-signature-timestamp | Used for timestamp validation and anti-replay checks. |
6.3 Payload handling expectations
Your system should be designed to process EHI messages safely and consistently.
Process the full payload
Do not assume that only a small subset of fields will be present.
Preserve field casing
Treat EHI field names as case-sensitive.
Handle empty fields
Empty fields may be present and should not automatically be treated as errors.
Ignore unexpected fields safely
Additional fields should not break your integration.
Store key identifiers
Store transaction and lifecycle identifiers for matching, retries, and reconciliation.
Use original EHI logic
Apply transaction matching and response logic based on the original EHI fields.
Note: Field capitalization and spelling matters. Your system should ignore unexpected fields safely when new EHI fields or values are introduced.
Next steps
Continue to What Your System Responds.