HSRC Pay Overview
Architectural and product summary positioning HSRC Pay as a payment orchestration platform.
This page explains what HSRC Pay solves, which domain pieces it brings together, and why it should not be thought of as a simple payment form tied to a single provider.
HSRC Pay makes provider complexity manageable under a single payment lifecycle. Payment Method, Provider, Provider Config, Routing Plan, Provider Adapter, Confirm Orchestrator, Checkout Session, Sandbox Network, and Event/Webhook Delivery are parts of the same orchestration model.
What is HSRC Pay?
HSRC Pay is a fintech infrastructure product that unifies payment methods, providers, routing strategies, checkout session flows, payment lifecycle, charge attempts, sandbox/production separation, and merchant operations in one payment orchestration layer.
The core idea: the merchant creates a single payment intent; HSRC Pay runs it with the right payment method, routing plan, provider adapter call, normalized result, and event/webhook discipline.
What does it aim to solve?
In classic payment integration, teams deal with separate auth models, endpoint formats, error languages, status mapping, and 3DS behavior for each provider. As you scale, this becomes provider-specific execution complexity.
HSRC Pay addresses this problem in three layers:
- Separates provider behavior from core payment logic.
- Converts provider results into a normalized result model.
- Gives merchants a single lifecycle, a single API surface, and a single event/webhook discipline.
The classic integration problem
| Problem | Outcome |
|---|---|
| Each provider expects a different request/response model | Integration code fragments quickly |
| Error and status mapping varies by provider | Merchant UI and ops teams see inconsistent results |
| 3DS/redirect flows are provider-specific | Frontend and backend responsibilities blur |
| Fallback and retry are added later | Payment and charge attempt tracking gets harder |
| Sandbox is only a success card | Production surprises with decline, timeout, and webhook issues |
HSRC Pay approach
HSRC Pay manages payment behavior through the confirm orchestrator: routing plan candidates are selected, a charge is created for each candidate, the provider adapter runs pay or post-3DS resume; the result is written to confirmResult and Payment/Charge status.
Core building blocks
| Piece | Responsibility |
|---|---|
| Payment | Merchant business-level payment intent |
| Charge | Attempt or transaction at provider/rail level |
| Payment Method | Method or channel the user pays with |
| Provider | Bank, PSP, wallet provider, sandbox provider, or simulated provider that processes the payment |
| Provider config | Account-bound provider setting; enters candidate pool at confirm via routing_strategy or account policy |
| Provider adapter | Provider-specific pay, capture, refund, 3DS resume implementation |
| Confirm orchestrator | Tries routing candidates in order, maps adapter result to confirmResult and lifecycle status |
routing_strategy | Optional field in confirm body: narrows candidates via payment_provider_config_id or provider_identifier |
| Routing | Provider selection, fallback, failover, capability matching, and rule evaluation |
| Checkout Session | Session that manages hosted or semi-hosted payment experience |
| Event/Webhook Delivery | Layer that reliably delivers state changes to merchant systems |
Payment orchestration lifecycle
- Merchant creates a Payment.
- Payment Method is selected or collected inside Checkout Session.
- Confirm call starts execution.
- Routing produces suitable provider candidates.
- Orchestrator runs the provider adapter for the selected candidate.
- Result is converted to the normalized model.
- Payment and Charge state are updated.
- Event/webhook is delivered to the merchant system.
Sandbox and production separation
Sandbox does not create real money movement. Sandbox Network is designed to test payment lifecycle, provider behavior, issuer/BIN resolution, 3DS, decline, and routing fallback behavior before production.
Production involves real provider credentials, real merchant settings, real payment intent, and real financial outcomes. Credential, test data, logging, and operational boundaries for these two environments should be kept separate.
Developer experience
For developers, the goal is integration with HSRC Pay canonical payment lifecycle, not provider-specific complexity.
- Create payment (
CREATED). - Start execution with confirm; read
data.paymentanddata.confirmResultin the response. - Handle the distinction between adapter
kind(success,requires_action,declined,error) andpayment.status(SUCCEEDED,REQUIRES_ACTION,REQUIRES_PAYMENT_METHOD,AUTHORIZED, etc.). - Verify final state with webhook/event.
- Test behaviors beyond success in sandbox as well.
Merchant operations
Value for merchants is not only accepting payments. On the operations side, these questions must be answerable:
- Which provider was tried?
- Which charge attempt failed?
- Did fallback kick in?
- Did the user complete the 3DS challenge?
- Which transaction did refund or void run against?
- Was webhook delivery successful?
HSRC Pay aims to make these questions traceable through the payment/charge/routing/event model.
What it is not
- HSRC Pay does not replace the bank or PSP in every case.
- HSRC Pay is not a real card network.
- Sandbox providers and resolved sandbox issuer labels are not real financial institutions.
- HSRC Pay does not claim that adding a provider is solved by JSON/YAML definition alone.
- HSRC Pay does not eliminate provider complexity; it makes it manageable, testable, and traceable.
Next steps
- Payment flow map: Payment Flows
- Domain model: Business Flow - Payments & Charges
- Confirm behavior: Payment Lifecycle and Confirm
- Provider model: Provider and Adapter Model
- Sandbox approach: Sandbox Network
- Production readiness: Integration Readiness