Client-hosted APIs for Authorizations

Purpose

This guide defines what the Client endpoint (EHI - External Host Interface) must implement when integrating with Payblr for authorizations handling.

Payblr validates inbound traffic, resolves routing, signs outbound requests, and relays payloads to your endpoint. Your endpoint remains the owner of business decisions and transaction processing logic.

What You Receive

Your endpoint receives:

1. POST request body with the raw JSON payload.

2. Integration headers:

   • x-correlation-id

   • x-ehi-signature

   • x-ehi-signature-algorithm (always hmac-sha256)

   • x-ehi-signature-timestamp

Security Requirements for Client

1. Verify x-ehi-signature-algorithm == hmac-sha256.

2. Rebuild signing payload exactly as:

   • <timestamp>.<rawRequestBody>

3. Compute HMAC-SHA256 with the shared secret and compare with x-ehi-signature.

4. Reject stale timestamps (recommended anti-replay window: 5 minutes).

If signature validation fails, return a controlled error (do not process the transaction).

Response Contract (Required)

Return valid JSON with values as strings/numbers (no null for numeric response fields).

1) Authorisation (MTID=0100, Txn_Type=A)

• Required in decisional paths: Acknowledgement="1" + Responsestatus.

• With this middleware, ehiMode=1 is treated as decisional even if Authorised_by_GPS=Y.

• Typical values:

  • Approve: Responsestatus="00"

  • Decline: Responsestatus="05"

  • Partial: Responsestatus="10" (when applicable)

2) Reversal (MTID=0400/0420, Txn_Type=D)

• Normal success:

  • Acknowledgement="1" + Responsestatus="00"

• Retry requested (temporary failure):

  • Acknowledgement="0" + Responsestatus in 91/92/96

3) Financial / Advice / Non-decisional

• Acknowledgement="1" is valid.

• Responsestatus is optional for these flows.

4) Cut-off (CutOffId present)

• Preferred:

  • Cut_OffResult="1" when processed successfully

  • Cut_OffResult="0" when processing failed

• Acknowledgement="1" is also accepted by middleware for compatibility.

Idempotency and Duplicate Handling

Your endpoint must be idempotent. Duplicates can happen due to retries/timeouts.

Recommended dedupe keys:

1. Txn_ID (or case variant in payload)

2. CutOffId for cut-off traffic

3. Traceid_Lifecycle fallback

If request is duplicate:

• Do not apply business impact twice.

• Return the same logical response as the original handling.

Business Responsibilities (ClientDomain)

These responsibilities must be implemented by Client systems as needed by your program and processing mode:

1. Authorisation decisioning rules (approve/decline/partial).

2. Balance and reserve handling.

3. Reversal and internal reconciliation logic.

4. 3DS/SCA amount-currency-merchant consistency checks.

5. STIP/balance update business policies (where applicable).

6. Transaction matching and post-processing.

Performance Targets

1. Keep client systems processing low-latency (recommended p95 < 1s).

2. Always respond before timeout (timeout_ms routing or global timeout).

3. Avoid long blocking operations in the synchronous decision path.

Do/Do Not

Do:

1. Preserve JSON validity.

2. Return deterministic responses for retries/duplicates.

3. Implement structured logs with x-correlation-id.

Do not:

1. Return malformed JSON.

2. Return null in numeric response fields.

3. Ignore signature verification in production.

Minimal Response Examples

Authorisation approve:

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

Authorisation decline:

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

Reversal retry:

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

Cut-off success:

{ "Cut_OffResult": "1" }

Go-Live Checklist for Client

1. HMAC signature verification implemented and tested.

2. Idempotency implemented for Txn_ID / CutOffId.

3. Response matrix implemented for authorisation/reversal/financial/cut-off.

4. Timeout budget validated under load.

5. Structured logs include x-correlation-id, key transaction fields, and decision outcome.