
Orders > [Order] > Payment
Definition
TWICE separates money movement into a four-level hierarchy: Order → Checkout → Payment → Transaction.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
Order
Line Items
Line Items
- A Listing (or a one-off line item)
- Quantity
- Price information
- Associated stock items (for fulfillment)
Checkout
Checkout
- Manually from an Order (by staff)
- Via self-service online (by the customer)
Payment
Payment
- Always points to Line Items on the Order
- Can include multiple Transactions
- A Checkout can have multiple Payments (e.g., deposit + balance)
Transaction
Transaction
- 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, andexpire(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, Pay by Bank and Swish via Stripe; card, Apple Pay and Google Pay via Adyen. Stripe offers MobilePay, Pay by Bank and Swish according to your store’s country, your currency and the capabilities on your Stripe account.
sale as Payment, refund as Refund, deposit_auth as Deposit Auth, deposit_capture as Deposit Capture and cancel as Cancellation.
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 Paid, Partially paid or Unpaid (paymentStatus: PAID, PARTIALLY_PAID, UNPAID).
Hierarchy visualization
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’sstatus 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.
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, andcancelledtotals) 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
Order created
Checkout created
Payment(s) created
- Each Payment points to specific line items
- Each Payment produces its own VAT receipt
- Multiple Payments let the customer pay in parts: a share up front, then the rest
Transaction(s) processed
Authorize and capture
For providers that support it (Adyen and Stripe with cards), TWICE uses a two-step authorise/capture flow:- 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 ownauthorised, captured, refunded, and cancelled totals.
PAY_STORE and custom manual methods support manual deposits, while card methods support automatic card-based deposits.
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 typerefund 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. An uncaptured authorisation that lapses produces an expire record.
Each refund is issued against one payment and is capped at that payment’s remaining refundable amount: what it charged, less what earlier refunds sent back. The order’s current total does not set the cap. An order paid in two payments is refunded one payment at a time, each against its own cap.
In the admin, Refund sits in the menu of a Payment or Deposit Capture row on the order’s Payments tab, for roles that hold Refunds and deposit captures. A row that failed or is already fully refunded offers no refund. Refund an order walks through it.
When you issue a refund:
- You specify the Transaction to refund and the total amount.
- Optionally, you specify which payment lines to refund and how much per line.
- TWICE creates the refund Payment and updates the original Transaction’s
modificationSummary.
Per-line (explicit)
Per-line (explicit)
null refunds that line’s full remaining refundable amount.Shipping, fees, deposits and rounding are payment lines of their own, beside the items, so a refund can cover the shipping charge alone.Use case: Refund one product in a multi-product order without affecting the others.Proportional (automatic)
Proportional (automatic)
modificationSummary tracks twelve fields:
Reconciliation
Automatic matching
Automatic matching
Manual reconciliation
Manual reconciliation
VAT receipts
VAT receipts
Supported Providers
TWICE supports two online payment providers and a manual flow for everything else.Online providers
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
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”.
FAQs
When is the VAT receipt generated?
When is the VAT receipt generated?
Why are refunds separate Payments rather than negative Transactions?
Why are refunds separate Payments rather than negative Transactions?
originalPaymentId → original Payment), TWICE keeps the original Transaction immutable while still tracking the refund chain.Which providers support subscriptions?
Which providers support subscriptions?
What's the difference between Payment State and the chip on the Order?
What's the difference between Payment State and the chip on the Order?
paymentStatus: PAID, PARTIALLY_PAID, UNPAID).Why is a refund refused as too large?
Why is a refund refused as too large?
Does a refund release the stock or cancel the order?
Does a refund release the stock or cancel the order?
The customer says the refunded money has not arrived
The customer says the refunded money has not arrived
A refund reads Refund Reversed
A refund reads Refund Reversed
I refunded a manual payment and no money moved
I refunded a manual payment and no money moved
The order still reads Unpaid or Partially paid after a payment
The order still reads Unpaid or Partially paid after a payment
Can I charge a customer in installments?
Can I charge a customer in installments?
Why does a payment row have no receipt number?
Why does a payment row have no receipt number?
Developer Reference
Transactions are tied to orders. Refunds and captures live under thepayments endpoints; provider configuration under paymentAccounts.