Terminology and Quick Notes
Quick glossary for payment orchestration, routing, adapter, and webhook terms used in HSRC Pay docs.
This page defines concepts used in HSRC Pay documentation in a short, consistent way. The goal is for developer, merchant, and operations teams to share the same domain model using the same words.
| Term | Definition |
|---|
| Payment | The merchant's intent to collect from a customer, or the business-level payment record. Creating a payment does not always mean moving money. |
| Charge | A provider/rail-level attempt, authorization, or financial movement. One Payment can produce multiple Charge attempts. |
| Confirm | The controlled step that moves a Payment into provider execution. Payment method, payer identity, routing plan, and optional routing_strategy enter at this stage. |
| Capture | Finalizing the amount after pre-authorization. Treated as a separate operation when auto-capture is off. |
| Refund | Refund after successful capture or payment. Usually tracked in Charge context. |
| Void | Canceling an authorization that was not captured. Must not be confused with Refund. |
| Resume / 3DS callback | Continuation step triggered after provider challenge via gateway three-d-secure-callback-urls/:chargeId (resumeThreeDSecure). |
| Term | Definition |
|---|
| Payment Method | The method or channel the user pays with: card, wallet, bank transfer, local method, or alternative method. Must not be confused with Provider. |
| Provider | The bank, PSP, wallet provider, sandbox provider, or internal/simulated provider that processes the payment. |
| Provider Method | Provider support for payment method, network, category, and type context. |
| Provider config | Account-scoped provider settings; part of the confirm routing candidate pool. |
| Provider adapter | Provider-specific pay, capture, refund, and 3DS resume implementation. |
| Confirm orchestrator | Tries routing candidates and writes adapter outcome to confirmResult and Payment/Charge status. |
routing_strategy | Confirm body field: narrows candidates with payment_provider_config_id or provider_identifier (API name is as shown; there is no separate "Strategy Execution" step). |
| Routing | Provider selection, fallback, failover, capability matching, and policy/rule-based decision process. |
| Routing Plan | Plan showing provider candidates to try and their order during confirm. |
| Fallback | Trying an alternative provider/route when the first route is unsuitable or returns a retryable outcome. |
| Normalized Result | Mapping adapter kind (success, requires_action, declined, error) to Payment status (SUCCEEDED, REQUIRES_ACTION, REQUIRES_PAYMENT_METHOD, etc.). |
| Term | Definition |
|---|
| Checkout Session | Session that manages hosted or semi-hosted payment experience. Collects payment method and checkout context from the user. |
| Hosted Checkout | Model where payment form and some flow handling run inside the HSRC Pay checkout experience. |
| API-only Flow | Model where the merchant collects payment method with their own frontend and backend and handles requires_action and webhooks directly. |
| Return URL | URL that returns the user to the merchant screen. It is not final payment proof. |
| Cancel URL | URL the user can return to when canceling checkout flow. |
| Term | Definition |
|---|
| Sandbox Network | Test network that simulates payment lifecycle and provider behavior without real money movement. |
| Sandbox Card | Test card data in sandbox for card allowlist validation. With secure_mode: true, a valid sandbox card can enter the 3DS simulation flow. It is not a real payment instrument and does not trigger issuer-specific errors. |
| Sandbox Issuer Resolution | Sandbox-only card-prefix resolution that stores issuer, network, country, IIN, brand, and card type on the payment method. It is not an issuer behavior simulation engine. |
| Sandbox Provider | Provider model that simulates provider behavior for test and development. Does not replace a production provider. |
| Production | Environment with real provider credentials, real merchant settings, real payment intent, and real financial outcomes. |
| Term | Definition |
|---|
| Idempotency | Approach where the same request safely preserves the same outcome when retried. Critical in confirm, webhook, and retry flows. |
| Trace ID | Operational identifier for end-to-end tracking of a request or payment attempt. |
| Credential Boundary | Security boundary: provider credentials and sensitive settings must not appear in public docs, logs, or sandbox test payloads. |
| Masking | Hiding sensitive fields such as card data, CVV, credentials, signature material, and raw provider secrets in logs. |
| Secure Mode | Payment mode that may require 3DS or extra authentication/authorization behavior. |
| Requires Action | Normalized result showing the Payment waits for user action, redirect, challenge, or resume. |
| Term | Definition |
|---|
| Event | Domain signal for payment, charge, refund, or system state change. |
| Webhook | Delivery of an Event to the merchant backend over HTTP. |
| Webhook Delivery | Sending an event to the merchant endpoint, retries, and delivery status tracking. |
| Duplicate Delivery | The same webhook event may arrive more than once. Merchant handler must be idempotent. |
| Reconciliation | Process of aligning payment, charge, provider reference, and merchant order states. |
| Term | Definition |
|---|
| Merchant Operations | Operational management of payment state, provider attempts, webhook delivery, refund/capture/void, and incident tracking. |
| Provider Health | Operational signal such as degraded, unavailable, or timeout from a provider. May be simulated in sandbox. |
| Decline Type | Splitting decline into hard or soft. Hard decline is not retried; soft decline may get fallback/retry when appropriate. |
| Pre-production Readiness | Validating sandbox, webhook, credential, trace, decline, and 3DS behavior before production. |
- Payment and Charge are not the same thing.
- Payment Method and Provider are not the same thing.
- Sandbox is not a real financial network.
- Return URL does not replace webhook.
- Provider raw response does not replace the public normalized model.
- Adding a provider must not be described as writing JSON/YAML files; the safe public model is provider catalog, config, adapter,
routing_strategy, and confirm orchestrator concepts.
- "Strategy Execution" is not a product step in code; in docs use provider adapter execution or confirm orchestrator.