Business Flow - Payments & Charges · HsrcPay Documentation

Understand Payment and Charge separation, routing/fallback attempt model, and the business flow of payment operations.

This page explains the high-level map of payment flows and HSRC Pay Payment/Charge domain separation.

Payment is the merchant business goal; Charge is the attempt at provider level. This split makes routing, fallback, retry, capture, refund, void, reporting, and webhook behavior easier to understand.

What is a payment flow?

A payment flow is not only calling endpoints; it is state, provider behavior, risk, routing, and event discipline.

HSRC Pay typically follows:

Payment is created.
Payment Method is selected or collected inside Checkout Session.
Confirm starts execution.
Routing produces provider candidates.
Orchestrator calls provider adapter pay for the selected candidate.
Charge attempt is created.
Result is converted to normalized result model.
Payment state is updated.
Event/webhook is sent to the merchant system.

What is a Payment?

Payment is the merchant payment intent or business record for collecting from a customer. It may correspond to an order, subscription, invoice, or checkout transaction.

Payment carries:

Amount and currency
Customer or checkout session context
Metadata
Secure mode and capture preference
Overall lifecycle state

Payment is the main payment record the merchant system should see.

Charge is the attempt or financial movement representation at provider/rail level. Authorization, capture effect, provider reference, attempt number, routing origin, and refund relationship can be tracked on Charge.

One Payment can have multiple Charge attempts. This model gives critical visibility especially in routing fallback, provider timeout, soft decline, or retry scenarios.

Why are they separate?

Question	Payment	Charge
What is the business goal?	Payment to collect from customer	Attempt at provider level
What does merchant report?	Single payment/order outcome	Attempt and provider performance
Routing fallback effect	Payment stays the same	New charge attempt may be created
Refund/capture relationship	Top-level payment context	Financial operation level
Debug value	User/order state	Provider, attempt, route, and error trace

One payment, multiple charge attempts

Example scenario:

Merchant creates a 1000 TRY Payment.
During confirm the first provider returns soft decline.
Routing engine falls back to second provider.
Payment stays the same.
First Charge declined, second Charge succeeds.
Payment becomes SUCCEEDED (or AUTHORIZED if auto_capture: false).
Merchant sees one Payment; ops can trace two Charge attempts.

{
  "id": "pay_123",
  "status": "SUCCEEDED",
  "charges": [
    { "id": "ch_1", "attempt_no": 1, "status": "DECLINED" },
    { "id": "ch_2", "attempt_no": 2, "status": "CAPTURED" }
  ]
}