External Host Interface Integration Guide
2. Scope
This guide covers Payblr’s client-facing EHI integration.
In this integration, Payblr forwards EHI messages to your configured endpoint, and your system returns the required authorization response, acknowledgement, or cut-off result based on the message type.
Covered areas
This guide covers the following EHI integration areas.
EHI authorization
Your system maintains the cardholder balance and makes authorization decisions for applicable transactions.
Transaction message forwarding
Payblr forwards EHI transaction messages to your configured endpoint.
EHI payload handling
Your system receives the EHI payload structure and processes the message using the EHI fields provided.
Request validation
Your system validates Payblr’s request before processing the transaction message.
Authorization responses
Your system returns approve, decline, or partial approval responses when required.
Reversals and advice messages
Your system processes reversal, advice, and other transaction lifecycle messages.
Financial and presentment messages
Your system processes transaction events for posting, ledger handling, and reconciliation.
Cut-off messages
Your system processes cut-off traffic when CutOffId is present.
Transaction matching
Your system applies EHI transaction matching logic using the EHI fields.
Duplicate handling
Your system prevents duplicate transaction, balance, block/reserve, or ledger impact when duplicate or retried messages are received.
Timeout and retry behavior
Your system responds within the required processing window and handles retries safely.
System responsibilities
Your system owns the business logic and operational handling required to process EHI messages safely.
| Responsibility | What your system must support |
|---|---|
| Receive EHI messages | Receive EHI messages from Payblr at your configured external host URL endpoint. |
| Validate the request | Validate the request before processing the transaction message. |
| Process the EHI payload | Process the EHI payload structure and use the EHI fields for authorization, lifecycle handling, matching, and reconciliation. |
| Return the required response | Return the required authorization response, acknowledgement, or cut-off result based on the message type. |
| Prevent duplicate impact | Handle retries and duplicate messages without duplicate balance, block/reserve, or ledger impact. |
Message handling
The response and processing behavior depends on the EHI message type received.
- Authorization messages require a real-time approve, decline, or partial approval response when applicable.
- Advice and reversal messages must be processed as transaction lifecycle messages.
- Financial and presentment messages must be processed for posting, ledger handling, and reconciliation.
- Cut-off messages must be processed when CutOffId is present.
- Transaction matching must use the EHI fields provided in the message.
- Duplicate handling must be implemented before moving to production.
Duplicate handling and timeout-safe retry behavior are in scope because your system must prevent duplicate balance, block/reserve, or ledger impact when messages are retried.
Implementation notes
Use these notes to align your implementation with the intended EHI guide scope.
- This page defines the scope of the Payblr client-facing EHI guide.
- Payblr forwards EHI messages to your configured endpoint.
- Your system returns the required response based on the message type.
- Your system is responsible for request validation, message processing, duplicate handling, timeout-safe retry behavior, and transaction matching.
- Your system should process the EHI fields as received and should not depend on Payblr-specific field renaming or payload transformation.
Next steps
Continue to Client System Expectations to review what your system must be prepared to support before receiving EHI messages from Payblr.