Welcome to the documentation
Introduction to HSRC Pay docs: payment orchestration, sandbox, checkout, routing, and the path to production.
Start here
HSRC Pay is not a payment button; it is an orchestration layer that models, tests, and runs payment behavior. This documentation is designed to help you understand payment lifecycle, provider adapters, sandbox network, routing, and event/webhook discipline in a single product language.
What does HSRC Pay provide?
HSRC Pay does not fit the classic payment gateway narrative. It brings together the merchant payment intent, payment method data, provider selection, provider execution results, charge attempts, webhook/event delivery, and operational visibility under one lifecycle.
The goal is to make provider complexity manageable for merchants through a single API, a single state model, and a single event discipline.
Payment orchestration
Unifies payment, charge, provider, routing, and webhook behavior in one lifecycle.
Payment flows
Explains create, confirm, requires_action, decline, capture, refund, void, and the webhook map.
Hosted checkout
Manages the payment experience with Checkout Session, 3DS handling, and post-redirect verification.
Provider and adapter model
Covers provider catalog, config, adapter execution, and the confirm orchestrator overview.
Sandbox network
Tests lifecycle, provider, issuer, 3DS, and decline behavior without real money movement.
Routing simulation
Validates provider selection, capability matching, fallback, and retry decisions before production.
Webhook delivery
Explains how payment state changes are delivered to merchant systems reliably and idempotently.
API Reference
Endpoint-level request/response schemas and the operational API surface.
Where should you start?
Position the product
Read HSRC Pay Overview to understand why the platform is an orchestration layer that reduces provider dependency, not just a gateway.
Learn the payment lifecycle
On Payment Lifecycle and Confirm, clarify the difference between creating a payment and starting provider execution.
Choose an integration model
For hosted checkout, follow the Checkout Session Guide. For API-only, start from Payment Flows.
Rehearse in sandbox
Use Sandbox Network, Sandbox Cards, 3DS Simulation, and Testing Declines to test behaviors beyond success as well.
Complete production readiness checks
Validate webhook, idempotency, trace, credential separation, and operational controls with Integration Readiness.
Persona-based routes
| Profile | First read | Next step | Watch out for |
|---|---|---|---|
| Developer integrating for the first time | HSRC Pay Overview | Payment Lifecycle and Confirm | Creating a payment is not the same as starting collection |
| Merchant using hosted checkout | Checkout Session Guide | Webhook Delivery | Redirect result alone is not final payment proof |
| Team doing API-only integration | Payment Flows | Data Models | requires_action and decline outcomes must be handled |
| Team reviewing provider/routing architecture | Provider and Adapter Model | Routing Simulation | Provider behavior should be read through adapter and confirm orchestrator language |
| QA/engineering doing sandbox testing | Sandbox Network | Testing Declines | Testing with only a success card is not enough |
Core concepts
| Concept | Short meaning |
|---|---|
| Payment | Merchant payment intent or business record |
| Charge | Authorization or financial attempt at provider/rail level |
| Confirm | Controlled step that moves a payment into provider execution |
| Payment Method | How the user pays: card, wallet, bank transfer, or local method |
| Provider adapter | Provider-specific pay / capture / refund / 3DS resume implementation |
| Confirm orchestrator | Tries routing candidates; produces confirmResult and lifecycle status |
routing_strategy | Confirm API field (narrows via config or provider identifier) |
| Normalized Result | Adapter kind (success, requires_action, declined, error) mapped to Payment status |
| Sandbox Network | Test network that rehearses payment behavior without real money movement |
Before going to production
- Clarify the Payment and Charge distinction within your team.
- Verify checkout redirect results with webhook or server-side query.
- Test
requires_action, timeout, hard decline, and soft decline scenarios. - Separate sandbox credentials from production credentials.
- Mask card data, provider secrets, signature material, and raw provider payload logs.
- Design your webhook handler to be idempotent.
- Confirm you can trace payment attempts with trace/request id.
Security boundary
The sandbox environment does not create real money movement. Do not move production cards, production credentials, or real customer data into sandbox test payloads.