> ## Documentation Index
> Fetch the complete documentation index at: https://www.twicecommerce.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# How Payments Work in TWICE
> Payment hierarchy, transaction lifecycle, deposits, partial refunds, and supported providers in TWICE Commerce.
export const lineItemDefinition = "A line item represents a single product or service entry within an order, containing the specific stock item(s), quantity, pricing, and fulfillment details for that part of the transaction.";
export const transactionDefinition = "A Transaction is comparable to a payment receipt from a payment terminal. A payment can include multiple transactions—for example, a split payment (lunch voucher + cash = 2 transactions, 1 payment) or a payment with a refund (original charge + refund = 2 transactions, 1 payment).";
export const checkoutDefinition = "A Checkout is created when an order is ready for payment, either manually from an order or via self-service online. Each checkout is always part of an order and can have multiple payments connected to it for partial payment scenarios.";
export const paymentDefinition = "A Payment is connected to a checkout and produces the VAT receipt. Payments always point to Line Items on the order and can include multiple transactions. A checkout can have multiple payments to support partial payment scenarios.";
## Definition
TWICE separates money movement into a four-level hierarchy: **Order → Checkout → Payment → Transaction**. The Order says what is being bought or rented. The Checkout collects payment intent. The Payment produces a VAT receipt. The Transaction is the actual money movement at the payment provider. Alongside Payments sit **Invoices** — the settlement documents that bill the money being moved. Refunds, deposits, partial payments, and split payment methods all map cleanly onto this hierarchy.
## Where do I use it?
* Configuring payment providers under **Settings → Payments**
* Charging customers at checkout (online or in admin)
* Handling deposits on rental orders
* Issuing full or partial refunds against captured transactions
* Reconciling reports against your payment provider's payouts
* Building API integrations that need to record manual payments or issue refunds
## Key Properties
### The payment hierarchy
```
Order > Line Items > Checkout > Payments > Transactions
```
The Order contains all the line items (what the customer is buying or renting). Every payment flow starts with an Order.
Read more: [Order Lifecycle](/docs/concepts/orders/order-lifecycle)
Line Items represent what the customer is purchasing or renting. Each line item references:
* A Listing (or a one-off line item)
* Quantity
* Price information
* Associated stock items (for fulfillment)
Checkout is created when an order is ready for payment. A checkout can be created:
* Manually from an Order (by staff)
* Via self-service online (by the customer)
A Checkout is always part of an Order and can have multiple Payments connected to it.
Payment is connected to a Checkout and produces the VAT receipt. Key characteristics:
* Always points to Line Items on the Order
* Can include multiple Transactions
* A Checkout can have multiple Payments (e.g., deposit + balance)
Transaction is comparable to a receipt from a payment terminal. One Payment can include multiple Transactions.
**Examples:**
* **Split payment**: Half with a gift card, half with cash → 2 Transactions, 1 Payment
* **Refund**: Original capture Transaction on the original Payment, refund Transaction on a linked refund Payment
### Payment types and methods
Every Payment has a **type** and a **method** describing how it was paid:
* **Types**: `sale` (charge), `deposit_auth`, `deposit_capture`, `refund`, `refund_reverse` (a refund clawed back to you), `cancel`, and `expire` (an authorisation that lapsed unclaimed).
* **Manual methods**: **Pay in store** (`PAY_STORE`) and merchant-named **custom methods** (`CUSTOM`) for in-person and offline payments.
* **Online methods**: card, Apple Pay, Google Pay, MobilePay, and Pay by Bank via Stripe; card, Apple Pay, and Google Pay via Adyen.
As a payment progresses it moves through stages for authorisation, capture, and refund. Each Payment carries a finer-grained state — pending, succeeded, partially refunded, refunded, refund reversed, cancelled, or expired. The **Payment chip** on an Order rolls everything up to a binary **Paid / Unpaid** (`paymentStatus`: `PAID` / `UNPAID`).
### Hierarchy visualization
```mermaid theme={null}
%%{init: {'flowchart': {'nodeSpacing': 30, 'rankSpacing': 40}}}%%
flowchart TB
Order["Order
Container"]
LineItem1["Line Item 1
Product A"]
LineItem2["Line Item 2
Product B"]
Checkout["Checkout
Ready for payment"]
Payment1["Payment 1
Produces VAT receipt"]
Payment2["Payment 2
Partial payment"]
Trans1["Transaction 1
Card payment"]
Trans2["Transaction 2
Cash payment"]
Trans3["Transaction 3
Original charge"]
Trans4["Transaction 4
Partial refund"]
Order -->|contains| LineItem1
Order -->|contains| LineItem2
Order <-->|"manual: Order creates Checkout
online: Checkout creates Order"| Checkout
Checkout -->|references| LineItem1
Checkout -->|references| LineItem2
Checkout -->|can have multiple| Payment1
Checkout -->|can have multiple| Payment2
Payment1 -->|charges for| LineItem1
Payment1 -->|charges for| LineItem2
Payment1 -->|can include multiple| Trans1
Payment1 -->|can include multiple| Trans2
Payment2 -->|can include multiple| Trans3
Payment2 -->|can include multiple| Trans4
style Order fill:#3b82f633,stroke:#3b82f6,stroke-width:3px
style LineItem1 fill:#fce7f3,stroke:#ec4899,stroke-width:2px
style LineItem2 fill:#fce7f3,stroke:#ec4899,stroke-width:2px
style Checkout fill:#d1fae5,stroke:#10b981,stroke-width:2px
style Payment1 fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
style Payment2 fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
style Trans1 fill:#e0e7ff,stroke:#6366f1,stroke-width:1px
style Trans2 fill:#e0e7ff,stroke:#6366f1,stroke-width:1px
style Trans3 fill:#e0e7ff,stroke:#6366f1,stroke-width:1px
style Trans4 fill:#e0e7ff,stroke:#6366f1,stroke-width:1px
```
### Invoices
Alongside Payments, TWICE issues **Invoices** — the settlement documents in the money model. A payment line without an invoice reference is unbilled money: when the sale succeeds, TWICE mints an Invoice from those lines and stamps the minted invoice ids back onto them. A payment line that already references an invoice settles that invoice line instead and never mints anything.
An Invoice's `status` tracks the document lifecycle only: `draft`, `open`, `cancelled`, `uncollectible` (a manual write-off), or `scheduled` (an upcoming subscription cycle, computed on demand — never stored). Paid-ness is derived separately from the invoice's `capturedTotal` and `refundedTotal`, mirroring the payment vocabulary: unpaid, partially paid, paid, partially refunded, refunded.
Subscription revenue sources from invoice lines: each billing cycle adds a line carrying the subscription id and billing period, so one Invoice can bill several subscriptions. See [Subscriptions](/docs/concepts/catalog/subscriptions).
## Relationships
* A Payment always references the **Line Items** it charges for — never the whole Order in the abstract.
* A refund Payment links back to the original Payment via `originalPaymentId`. Refund lines trace to the original payment lines internally (`originalPaymentLineId`); this per-line link is not exposed on the API.
* A Deposit is a separate Payment Object on the Order (with its own `authorised`, `captured`, `refunded`, and `cancelled` totals) so deposit movements never mix with charge movements.
* The Payment Provider (Adyen, Stripe, manual) determines which methods are available and whether authorise/capture is supported.
## Lifecycle
### From Order to Payment
An Order is created containing line items. Orders can be created manually in admin or automatically from a customer's online checkout.
Read more: [Order Lifecycle](/docs/concepts/orders/order-lifecycle)
When the Order is ready for payment, a Checkout is created — manually from admin or via the storefront's self-service flow. The Checkout is always linked to the parent Order.
One or more Payments are created within the Checkout:
* Each Payment points to specific line items
* Each Payment produces its own VAT receipt
* Multiple Payments enable partial-payment scenarios (deposit + balance, installments)
Each Payment can include multiple Transactions — split payment methods, refunds, etc.
### Authorize and capture
For providers that support it (Adyen and Stripe with cards), TWICE uses a two-step authorise/capture flow:
```mermaid theme={null}
flowchart LR
Order[Order Created] --> Checkout[Checkout Created]
Checkout --> Auth[Payment Authorized]
Auth --> Capture[Payment Captured]
Capture --> Complete[Payment Complete]
Complete --> Refund[Refund Transaction]
Complete --> Partial[Partial Refund Transaction]
Auth --> Void[Authorization Voided]
style Order fill:#3b82f633,stroke:#3b82f6,stroke-width:2px
style Checkout fill:#10b98133,stroke:#10b981,stroke-width:2px
style Complete fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
style Refund fill:#e0e7ff,stroke:#6366f1,stroke-width:2px
style Partial fill:#e0e7ff,stroke:#6366f1,stroke-width:2px
style Void fill:#ef444433,stroke:#ef4444,stroke-width:2px
```
* **Authorise**: hold funds on the card without taking them. Used for rental pickups so the merchant can adjust the final amount.
* **Capture**: take the authorised funds. Can be a full capture or a partial capture for less than the authorised amount.
* **Void**: release an authorisation without capturing. Used when an order is cancelled before pickup.
* **Expired**: the provider auto-cancelled the hold because it was not captured within the authorization window (typically \~7 days for Stripe).
### Deposits
Deposits are a separate Payment object alongside the main charge. On the Order they show as their own block with their own `authorised`, `captured`, `refunded`, and `cancelled` totals.
| Deposit method | How it works |
| :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Automatic (card)** | An additional authorisation is placed on the customer's card. Captured only if needed (damage, late return), otherwise voided. Requires a card payment method — `CARD_STRIPE` or `CARD_ADYEN`. |
| **Manual** | Staff records that a deposit was taken outside TWICE (cash, ID card, bank transfer). Released on return by setting the manual deposit back to zero. |
| **No deposit** | Most one-off sale orders. |
Deposit method availability is constrained per payment method — `PAY_STORE` and custom manual methods support manual deposits, while card methods support automatic card-based deposits.
Manual payment methods (Pay on pickup, custom methods) are allowed at checkout even when the order includes a security deposit. In this case the deposit is handled as a manual deposit. Only orders with auto-charged subscriptions require a card payment method — deposits alone do not.
If a card-based deposit hold is not captured within the provider's authorization window (typically \~7 days for Stripe), the provider cancels it automatically. The Payments tab shows these as **Expired**, distinct from a manual release which shows as **Cancelled**. See [Security Deposits](/docs/concepts/orders/deposits#authorization-expiry).
### Partial captures and partial refunds
A captured Transaction can be partially refunded multiple times until fully refunded. Each refund creates a new Payment record of type `refund` linked to the original Payment via `originalPaymentId`. A refund can itself be reversed by the provider (`refund_reverse`) — for example when a bank refund fails and the money comes back to you — and an uncaptured authorisation that lapses produces an `expire` record.
When you issue a refund:
1. You specify the **Transaction** to refund and the **total amount**.
2. Optionally, you specify which **payment lines** to refund and how much per line.
3. TWICE creates the refund Payment and updates the original Transaction's `modificationSummary`.
Specify exactly which payment lines to refund and how much for each. The per-line amounts must sum to the total refund amount. Setting a line's amount to `null` refunds that line's full remaining refundable amount.
**Use case**: Refund one product in a multi-product order without affecting the others.
Omit payment lines entirely. The refund amount is distributed proportionally across all refundable lines based on their remaining refundable amounts. Rounding remainder goes to the largest line.
**Use case**: Issue a flat goodwill refund spread evenly.
The original Transaction's `modificationSummary` tracks twelve fields:
| Field | Description |
| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `capturedTotal` | Sum of succeeded captures. |
| `refundedTotal` | Raw gross sum of succeeded refunds. **Not** netted against reversals — net it with `refundReversedTotal` before computing remaining refundable amounts. |
| `refundReversedTotal` | Sum of succeeded refund reversals — refund money clawed back to you. |
| `cancelledTotal` | Sum of cancelled (voided) authorisation amounts. |
| `expiredTotal` | Authorisation amount that lapsed unclaimed. |
| `pendingRefundsTotal` | Refunds initiated but not yet settled. |
| `pendingCapturesTotal` | Captures initiated but not yet settled. |
| `isPartiallyRefunded` | `true` when some (but not all) of the amount has been refunded. |
| `isFullyRefunded` | `true` when the entire captured amount has been refunded. |
| `isCancelled` | `true` when the authorisation was cancelled. |
| `isReversed` | `true` when a refund on this Transaction was reversed. |
| `isExpired` | `true` when the authorisation expired. |
`refundedTotal` is raw and gross. A reversed refund returns money to you, so the amount actually refunded is `refundedTotal - refundReversedTotal`. Reading `refundedTotal` alone overstates the refund.
Refunds are processed through the original payment provider. You can only refund Transactions with status `succeeded` and type `capture`.
### Reconciliation
For integrated providers, TWICE automatically matches Transactions to Payments, links Payments to Checkouts and Orders, and updates the Order's Payment State as Transactions complete.
For manual payments (cash, bank transfer, third-party platforms), record the Payment and Transaction directly. Use the payment date, method, and external reference fields to map back to your accounting.
Receipts are generated **per Payment**, not per Transaction. One Payment with two Transactions (gift card + cash) still produces a single receipt covering both methods.
## Supported Providers
TWICE supports two online payment providers and a manual flow for everything else.
### Online providers
| Provider | Methods | Recurring | Deposits | Notes |
| :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------- | :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Stripe** | Card (`CARD_STRIPE`), Apple Pay (`APPLE_PAY_STRIPE`), Google Pay (`GOOGLE_PAY_STRIPE`), MobilePay (`MOBILEPAY_STRIPE`), Pay by Bank (`PAY_BY_BANK_STRIPE`) | Yes (card and wallets) | Yes (automatic via card auth) | Connected via Stripe Connect under **Settings → Payments → Stripe**. Apple Pay and Google Pay activate automatically — no toggle needed. `CARD_ONLINE_STRIPE` is a legacy alias of `CARD_STRIPE`. |
| **Adyen** | Card (`CARD_ADYEN`), Apple Pay (`APPLE_PAY_ADYEN`), Google Pay (`GOOGLE_PAY_ADYEN`) | Yes (card) | Yes (automatic via card auth) | Managed under **Settings → Payments**. Per-method country/currency limitations apply. |
**Stripe** and **manual/offline** payments are available to every store. **Adyen** is enabled for selected merchants only (as is **SumUp** for in-person terminal payments) — see [Payments settings](/docs/settings/payments).
### Apple Pay and Google Pay on Stripe
Apple Pay and Google Pay activate automatically when you connect Stripe and enable card payments. There is no admin toggle — wallets are derived from the card method at runtime.
TWICE registers your storefront domains (subdomain and any custom domains) with Stripe for Apple Pay domain verification. Registration happens automatically when you:
* Connect your Stripe account
* Change your store subdomain
* Activate a custom domain
At checkout, Stripe renders the wallet buttons based on the customer's device and browser. Apple Pay appears on Safari and Apple devices; Google Pay appears on Chrome and Android. Both wallets support recurring payments (subscriptions) and security deposits — Stripe stores the underlying card as a reusable payment method.
Apple Pay does not appear when the checkout is embedded in an iframe. Google Pay is unaffected by this restriction.
### Manual / offline payments
Two manual methods exist:
* **Pay in store** (`PAY_STORE`) — the built-in method for payment collected at pickup.
* **Custom methods** (`CUSTOM`) — methods you name yourself, each with its own label and optional description. Create as many as you need — "Bank transfer", "Gift card", "External POS".
Use them for cash collected in-store, bank transfers received outside TWICE, card terminals not integrated via Adyen/Stripe, and store credit.
Manual payments still produce a VAT receipt, support refunds (manually entered), and aggregate into the Order's Payment State exactly like online payments.
## FAQs
At the Payment level. One Payment = one receipt, regardless of how many Transactions make up that Payment. If a customer pays €120 split across gift card and cash in one Payment, the receipt shows €120 with both methods detailed.
Refunds need their own VAT receipts and audit trail. By creating a linked refund Payment (`originalPaymentId` → original Payment), TWICE keeps the original Transaction immutable while still tracking the refund chain.
Yes. Set the capture amount lower than the authorised amount; the remainder is released — a partial capture.
No. Deposits use a separate Payment object alongside the charge, each with its own authorise/capture lifecycle. This keeps reporting and refunds clean.
Stripe and Adyen card payments. Apple Pay and Google Pay on Stripe also support subscriptions — Stripe saves the underlying card for recurring off-session charges. Redirect-based methods (MobilePay, Pay by Bank) and manual methods are one-off only.
The chip is a rollup. Each Payment has a finer-grained state behind the scenes — pending, succeeded, partially refunded, refunded, refund reversed, cancelled, expired; the chip reduces all Payments on the Order to a binary **Paid / Unpaid** (`paymentStatus`: `PAID` / `UNPAID`).
## Developer Reference
Transactions are tied to orders. Refunds and captures live under the `payments` endpoints; provider configuration under `paymentAccounts`.
Open the endpoint in the API reference.
## Related
Order, Payment, and Fulfillment states.
How purchase type shapes the payment flow.
Connect Stripe and manage payment providers.
Financial reports and reconciliation.