External Host Interface Integration Guide
1. Overview
Payblr supports an External Host Interface integration for real-time transaction authorization and transaction event delivery.
This guide explains how your system receives EHI messages from Payblr, validates each request, processes the original EHI payload, and returns the required JSON response.
The required response depends on the message type. Authorization messages require an authorization decision. Advice, reversal, financial, chargeback, and cut-off messages generally require an acknowledgement or cut-off result.
1.1 EHI Transaction Message Flow
The EHI transaction flow delivers real-time card and payment-related messages in JSON format.
Payblr forwards the original EHI payload to the external host URL endpoint configured for your system and relays your response through the transaction flow.
Message types may include authorizations, advice messages, reversals, financial / presentment messages, financial reversals, chargebacks, chargeback reversals, and cut-off messages.
EHI Transaction Message Flow
Parties involved in the payment authorization process
involved in the payment authorization process
Cardholder
Initiates the purchase.
Merchant
Submits the transaction.
Acquirer
Routes the authorization request.
Card Scheme
Card network routes the message.
Processor
Processes the card program message.
Payblr
Forwards the EHI payload.
Client
Receives and responds through EHI.
Forward path
Solid arrows show the authorization request moving from the cardholder and merchant through the network, processor, Payblr, and your system.
Response path
Dashed arrows show the response path returning through the same authorization chain.
Payblr role
Payblr forwards the original EHI payload to the client external host interface and relays the client response back through the transaction flow.
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.
Message categories
The required processing and response behavior depends on the EHI message type.
| Message category | Purpose | Typical response |
|---|---|---|
| Authorization messages | Used when your system must return an authorization decision for an applicable transaction. | Approve, decline, or partial approval response when applicable. |
| Advice messages | Used to notify your system of an authorization-related event that has already occurred. | Acknowledgement response. |
| Reversal messages | Used to release, reverse, or adjust previous transaction impact. | Acknowledgement or retry-related response when applicable. |
| Financial / presentment messages | Used for posting, final transaction handling, transaction history, ledger, or reconciliation processing. | Acknowledgement response. |
| Chargeback and chargeback reversal messages | Used for dispute-related financial notifications and chargeback lifecycle processing. | Acknowledgement response. |
| Cut-off messages | Used when cut-off traffic is present and the message includes a CutOffId. | Cut-off result response. |
Response behavior
Your system must return the required JSON response based on the message type received.
Authorization decision
Authorization messages require an approval, decline, or partial approval response when applicable.
Acknowledgement
Advice, reversal, financial, presentment, and chargeback messages generally require acknowledgement after processing.
Cut-off result
Cut-off messages require a cut-off result when CutOffId is present.
Implementation focus
This guide is organized around the responsibilities your system needs to implement for EHI message handling.
- Receive EHI messages from Payblr at your configured external host URL endpoint.
- Validate each request before processing the EHI payload.
- Process the original EHI payload using the message fields and transaction logic.
- Return the required JSON response based on the message type.
- Store key transaction, lifecycle, matching, and correlation identifiers for audit and reconciliation.
- Prevent duplicate balance, block, reserve, or ledger impact when duplicate or retried messages are received.
Your system should be designed to handle retries, duplicates, reversals, final presentments, chargebacks, cut-off messages, and reconciliation scenarios without creating duplicate transaction impact.
Next steps
Continue to the Scope page to review what is included in the Payblr client-facing EHI integration and which areas your system must support.