> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinkbill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How Payments Work

> Checkout Session, Order, and the merchant order — what each one actually means.

## What actually happens during a payment

**1. The customer clicks Buy**

The frontend sends the product and quantity to the merchant backend. It does not call Clink.

**2. The backend creates a merchant order first**

Record what was bought, for how much, and by whom. This record is the source of truth in the merchant system, and every status below hangs off it.

**3. The backend creates a Checkout Session**

Clink returns a `sessionId` and a `url`. That `url` is the checkout page.

**4. The customer pays**

Choosing a payment method, entering card details, and passing 3DS all happen on Clink's page. Card numbers never reach the merchant.

**5. Clink sends the result to the webhook**

`order.succeeded` on success, `order.failed` on failure.

**6. The backend confirms payment, then fulfills**

Shipping, top-ups, and access are granted only after the event is received, verified, and matched to the merchant order.

Step 2 is the one people skip. Using Clink's Session as the order record breaks reconciliation later: Clink knows someone paid 19.99 USD, but not which user bought which item.

## Three things called "order"

Three things in those six steps can all be called an order: the **Checkout Session** Clink creates, the **Order** the customer's payment produces, and the merchant backend's own record. Similar names, completely different jobs.

| Object | What it is | Created by | Used for |
| - | - | - | - |
| Checkout Session | One checkout visit — a time-limited payment entry point | Clink, on an API call | Getting the customer to a checkout page |
| Order | The result of one payment attempt | Clink, when the customer pays | Deciding whether the money actually arrived |
| Merchant order | The business record in the merchant database | The merchant backend | Deciding whether to fulfill, and reconciling later |

One Session can produce several Orders. A customer whose first card is declined and who then pays with a second card produces two Orders under the same Session. So read the Order to determine the payment result, not the Session.

## Reading the statuses

### Checkout Session

`status` reports whether the payment entry point is still usable:

| Session `status` | Meaning | What to do |
| - | - | - |
| `open` | Still valid, payment is still possible | Wait for the customer, or send them back to checkout |
| `completed` | The session flow finished; no further attempts accepted | Whether money was collected comes from the Order (or the Invoice, for subscriptions) |
| `expired` | The entry point expired; no new attempts | Create a new Session to keep collecting |

`paymentStatus` separately reports `unpaid`, `processing`, or `paid`, which is convenient for showing progress in the UI. For reconciliation, still read the Order.

> [!WARNING]
>
> `expired` does not mean the payment failed. A customer may have started a payment moments before expiry, and that Order can still succeed afterwards. Do not mark the merchant order as failed just because the Session expired.
>
> `completed` does not mean money arrived either. A successful one-time payment does move the Session to `completed`, but a subscription with a free trial also completes its session without a single charge. The status only says the entry point is done.

### Order

`status` is the payment result, and the field that maps onto the merchant business status:

| Order `status` | Meaning | What to do |
| - | - | - |
| `success` | Payment succeeded | Fulfill, idempotently |
| `pending` | In progress, no result yet | Wait for the webhook, or poll `GET /order/{id}`. **Do not charge again** |
| `failed` | Payment failed | Record `failureCode` and `failureMessage`; let the customer retry once nothing is in flight |
| `requires_action` | The customer must do one more step, such as 3DS | Use the returned `action` to guide them through it |
| `partial_refunded` | Partially refunded | Update the refunded total |
| `refunded` | Fully refunded | Revoke access or run the returns flow |

`pending` causes the most damage. It means "not known yet", not "failed". Starting a second charge here is how customers get billed twice.

## What counts as grounds for fulfillment

Exactly one thing: the backend received a signature-verified `order.succeeded` event, or polled `GET /order/{id}` and got `success`, and that Order matches the merchant order record.

> [!WARNING]
>
> These four look like the money arrived. On their own, none of them count:
>
> * The customer landed on the `successUrl` — anyone can type that address
> * The Session `status` became `completed` — that only says the entry point closed
> * The webhook returned HTTP 200 — that only tells Clink something was received
> * A frontend SDK fired `complete` or `session-success` — browser events can be forged

## Two environments

Clink has a sandbox and a production environment. The sandbox is what people usually call the test environment; no real money moves.

| | Sandbox | Production |
| - | - | - |
| Dashboard | `https://uat-dashboard.clinkbill.com` | `https://dashboard.clinkbill.com` |
| API | `https://uat-api.clinkbill.com` | `https://api.clinkbill.com` |
| Key prefixes | `sk_uat_` / `pk_uat_` | `sk_prod_` / `pk_prod_` |
| Money | No real funds move | Real charges |

The two environments are separate dashboards. Sandbox payment-domain resources and environment-specific configuration are not copied to production, including products, customers, orders, API keys, webhook endpoints, signing keys, and verification applications and details. On first access to production, Clink synchronizes the tenant, merchant, user sign-in credentials, and role assignments required for production access.

The sandbox is for payment integration and test transactions and does not collect production account-verification details. Do not use it for load testing, and do not put real customer names, emails, or card numbers into it. Test data cannot be used as production data.

> [!WARNING]
>
> During development, log in to the sandbox dashboard at `uat-dashboard.clinkbill.com`. Keys initialized in the production dashboard start with `sk_prod_`, and using one against the sandbox API fails authentication with an error that does not mention environments at all.

Test card `4242 4242 4242 4242`, any 3-digit CVC, any future expiry. It works in the sandbox only.

## Next

> [card] [Quickstart](https://docs.clinkbill.com/quickstart.md)
>
> Follow along and see a successful order in about fifteen minutes.

> [card] [Choose an integration](https://docs.clinkbill.com/choose-integration)
>
> Redirect to checkout, or embed it in a merchant-owned page.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.