Appearance
Payments
TiruPay delegates payment processing to an external Payment Processor microservice. TiruPay itself stores only a minimal payment reference - the Payment Processor is the source of truth for payment status, amounts, and partner details.
How Payments Work
When an order is finalized, TiruPay creates a payment and sends it to the Payment Processor. The Payment Processor communicates with a partner (e.g. Mollie, Stripe) to handle the actual money movement. After payment, the partner notifies the Payment Processor via webhook, which in turn notifies TiruPay.
Payment Methods
A payment method defines a way customers can pay. Each method has an identifier, a partner, and a revoke deadline.
| Field | Type | Description |
|---|---|---|
name | string | Display name (e.g. "Credit Card", "SEPA Direct Debit") |
identifier | string | Technical identifier (e.g. credit_card, sepa_direct_debit). Needs to be one of Available Identifiers |
partner | enum | Which payment partner handles this method (mollie, stripe, or nemo) |
revoke_deadline_days | integer | Days after payment during which the customer can still revoke (e.g. 180 for credit cards, 56 for SEPA) |
is_active | boolean | Whether this method is currently available |
allows_manual_capture | boolean | Whether this method may be used with capture_mode: manual (see Capture Modes) |
allows_mandate_creation | boolean | Whether this method can be used to create a mandate. Some methods don't support mandates (e.g. Paysafecard) - a method with this set to false can never be configured for subscription order type (see Payment Method Configuration per Service) |
Available Identifiers
credit_card, sepa_transfer, sepa_direct_debit, apple_pay, google_pay, paypal, twint, sofort, klarna, giropay, eps, bancontact, ideal, paysafecard, alipay, wechat_pay
Payment Method Availability
Not every payment method is available for every article in every country. Payment methods are linked to articles per country via Article Availability. This lets you control which payment methods customers can use for specific articles in specific countries.
Partners
A partner is an external payment provider that processes the actual transactions. TiruPay currently supports:
| Partner | Description |
|---|---|
mollie | Mollie - supports credit cards, SEPA, PayPal, and many local methods |
stripe | Stripe - credit cards and other methods |
nemo | In-house provider for SEPA Direct Debit and bank transfers |
Checkout Modes
When finalizing an order, you choose a checkout mode that determines how the customer completes the payment:
| Mode | Description |
|---|---|
partner_hosted_checkout | Customer is redirected to the partner's checkout page (e.g. Mollie checkout). Recommended for most cases. |
self_hosted_checkout | Payment is handled on your own checkout page. Requires PCI compliance for credit cards. |
mandate | Payment is charged automatically using an existing mandate. No customer interaction needed. Used for subscription renewals. |
Capture Modes
When finalizing an order, you also choose a capture mode - whether the payment is captured immediately or held for confirmation:
| Mode | Description |
|---|---|
automatic (default) | Payment is captured as soon as it's authorized. |
manual | Payment is authorized/reserved but not captured until a Service or Admin confirms it. |
For manual capture, the order moves to NEEDS_MANUAL_CAPTURE once the payment is authorized (see Order Lifecycle). From there:
POST /orders/{order_id}/capture(Service/Admin only) - confirms the capture. The order returns toPENDINGand continues through the normal payment flow toCOMPLETED_OUTSTANDING. Positions can still be edited (by a Service/Admin, not the customer) before confirming, as long as the new total doesn't exceed the reserved amount - see Orders.POST /orders/{order_id}/cancel_capture(Service/Admin only) - releases the reservation and cancels the order.- If nobody confirms or cancels in time, the payment partner eventually expires the reservation on its own, which also cancels the order.
SEPA Direct Debit and SEPA Transfer don't get a real reservation
Unlike capture-native methods (e.g. credit cards), which get a genuine authorization hold at the partner, SEPA Direct Debit and SEPA Transfer have no such hold concept. With capture_mode: manual, TiruPay doesn't contact the partner at all until you confirm. We simply wait before issuing the actual debit or transfer request. Nothing is reserved or guaranteed at the partner in the meantime.
This is also why checkout_mode: partner_hosted_checkout cannot be combined with capture_mode: manual for these two methods - finalization fails outright. TiruPay needs to control exactly when the debit/transfer request fires, which only works when it collects the SEPA details itself (self_hosted_checkout), not when the partner's hosted page would normally trigger the request immediately. Use self_hosted_checkout for manual capture with SEPA.
Mandates
A mandate is an authorization from the customer to charge their payment method for recurring payments. Mandates are required for subscriptions to enable automatic renewals without customer interaction.
Mandate Fields
| Field | Type | Description |
|---|---|---|
customer_id | string | The customer who authorized the mandate |
service_id | string | The service this mandate belongs to |
partner | enum | Which payment partner holds the mandate |
payment_method_id | string | Which payment method the mandate is for |
partner_mandate_id | string | The mandate ID at the partner |
status | enum | Current mandate status |
Mandate Statuses
| Status | Description |
|---|---|
PENDING | Created but not yet active |
VALID | Active and can be used for recurring charges |
INVALID | Failed verification |
REVOKED | Explicitly revoked by the customer |
EXPIRED | Expired |
How Mandates Are Created
Mandates can be created in two ways:
During order finalization
For subscription orders, provide the relevant data alongside the payment selection:
- SEPA Direct Debit - Provide IBAN, BIC, and signature date. The mandate is created at the partner immediately.
- PayPal - Provide a billing agreement ID or vault ID. The mandate is created at the partner.
- Credit Card (Mollie) - No explicit mandate creation needed. The first successful credit card payment automatically creates a mandate at Mollie. TiruPay syncs it after the first payment webhook.
Standalone
(POST /payment/mandates/checkout) - Create a mandate without an order. Useful when a customer wants to register a new payment method outside of a purchase flow. The Payment Processor is responsible for handling any partner-specific requirements (e.g. a test charge to activate a card mandate). Requires that no VALID or PENDING mandate already exists for the same service, partner, and payment method combination.
One Mandate Per Combination
A customer can only have one active mandate per combination of service, partner, and payment method.
Redirect-based mandate creation
Payment methods that require a redirect flow to create a mandate accept a completion_redirect_url - it must resolve to your service's own domain or the TiruPay frontend. See Redirect Security.
Payment Method Configuration per Service
Each service can configure how TiruPay behaves for a specific payment method combination via ServicePaymentMethodConfig. This is particularly useful for invoice-style payment methods (e.g. bank transfer) where payment confirmation is delayed.
Configuration Fields
| Field | Type | Default | Description |
|---|---|---|---|
order_type | enum | one_time | Whether this config applies to one_time or subscription orders. A payment method must be configured separately for each order type it should support. |
activate_features_on | enum | completed | When to activate features: pending (at invoice creation) or completed (after successful payment) |
payment_due_days | integer | 14 | Days from order date until payment is due. Only relevant when activate_features_on is pending. |
grace_period_days | integer | 0 | Extra tolerance days after due_date before the order is revoked and dunning starts. Applies to both invoice-style orders waiting on payment and mandate-based orders being retried after a failed charge - see Activate Features on Pending and Mandate-Based Orders below. |
One config per order type
A single payment method (e.g. bank transfer) can have separate configs for one_time and subscription orders, since the appropriate activate_features_on/payment_due_days behavior often differs between a single purchase and a recurring subscription. PAYG billing is treated as subscription since it charges repeatedly over time, even though it isn't tied to a TiruPay Subscription record.
Activate Features on Pending
When activate_features_on is set to pending, features are activated immediately when the order is finalized (before payment is received). This is the right choice for invoice payment methods where you trust the customer to pay later.
For a customer's first order on a subscription article, the Subscription record itself is also created at this point, not deferred to payment confirmation - so started_at reflects the moment features were granted.
The order then tracks a due_date (order_date + payment_due_days). If the customer does not pay within due_date + grace_period_days, a daily job revokes the order - deactivating features and (if the service has an active dunning policy) starting escalation. When payment eventually arrives, the order is automatically restored and completed normally.
Also applies to balance top-ups and article documents
activate_features_on controls the timing for everything an order can unlock, not just features: balance top-ups and Article Documents follow the same pending/completed timing and are reverted together with features if the order is revoked.
plain
Order finalized
→ PENDING, features activated, due_date set
→ [no payment by due_date + grace_period_days]
→ REVOKED (features deactivated, dunning starts)
→ [payment received via webhook]
→ PENDING (restored) → COMPLETED_OUTSTANDING (features reactivated)Mandate-Based Orders
Subscription renewals and PAYG billing orders never go through activate_features_on = pending - they charge an existing mandate immediately instead of waiting on a bank transfer. If that charge fails for a genuine customer-caused reason (e.g. card declined), the order stays PENDING and gets a due_date stamped on it too, so it's picked up by the same overdue-revocation mechanism as invoice-style orders above - reusing grace_period_days as the retry window instead of introducing a separate one.
While due_date is set, the order is retried automatically via the mandate on a daily schedule. Once due_date + grace_period_days passes without a successful charge, the order is revoked the same way an unpaid invoice-style order is, and dunning takes over from there.
Invoice-style and mandate-based orders on the same payment method can therefore use different values for grace_period_days if you want a shorter or longer retry window for each - just create separate ServicePaymentMethodConfig rows per order_type, one for one_time/invoice-style orders and one for subscription/mandate-based orders.
Who Can Manage Configs
Only Service and Admin roles can view or manage payment method configuration - there is no customer-facing access.
Checkout Sessions
When a service creates an order and wants the user to pay via the TiruPay frontend, it creates a checkout session. The session stores payment parameters that the user should not control directly:
| Field | Description |
|---|---|
checkout_mode | How the payment is processed (see Checkout Modes) |
capture_mode | Whether to capture automatically or manually |
final_redirect_url | Where to redirect the user after payment - must resolve to your service's own domain or the TiruPay frontend, see Redirect Security |
The service gets back a checkout_url that it can redirect the user to. The user then finalizes the order in the TiruPay frontend, and TiruPay reads the stored session parameters.
See User Checkout for the full flow.
Payment Lifecycle
Order Finalization
When you finalize an order, the following payment steps happen:
- Customer sync - The customer is created in the Payment Processor if they don't exist yet.
- Payment creation - A payment record is created in both TiruPay and the Payment Processor.
- Mandate handling - For subscriptions: an existing mandate is used, or a new one is created from the provided SEPA/PayPal data.
- Payment selection - The payment is activated at the partner with the chosen payment method and checkout mode.
- Redirect URL - A checkout URL is returned for
partner_hosted_checkout, or thefinal_redirect_urlfor mandate-based payments.
After Payment
The partner notifies the Payment Processor via webhook, which forwards the status to TiruPay via a signed webhook (HMAC-SHA256). Based on the payment status:
| Partner Status | TiruPay Action |
|---|---|
paid | Complete the order - activate features, top up balances, create next subscription order. If the order was previously revoked while overdue (invoice-style or mandate-based), it is restored to PENDING first and then completed normally. A payment arriving for an already WRITTEN_OFF order is not auto-completed - see Dunning. |
failed | For one-time orders: revert to DRAFT, customer can retry. For subscription renewal/PAYG orders: stay PENDING with due_date set, retried automatically via the mandate - see Mandate-Based Orders. |
canceled | Cancel the order |
expired | Cancel the order. If the order is NEEDS_MANUAL_CAPTURE, this is how an unconfirmed manual capture reservation expiring at the partner is handled. |
ready_for_capture | Move the order to NEEDS_MANUAL_CAPTURE - see Capture Modes |
charged_back | Revoke the order - deactivate features, reverse balances, start dunning |
refunded | Refund the order |
Subscription Renewals
For recurring subscription payments, TiruPay uses the customer's existing mandate:
- The next order in the subscription chain activates (status
IN_FUTURE→PENDING). - A payment is created with
checkout_mode: mandate- no customer interaction. - The partner charges the customer's payment method using the mandate.
- On success, the order completes and the next cycle is created.
Good to know
Payment Processor Is Source of Truth
TiruPay stores only a reference to the payment in the Payment Processor. All payment details (status, amount, partner data) live in the Payment Processor.
Revoke Deadline
Each payment method has a revoke_deadline_days field. This defines how long a customer can chargeback a payment. After the deadline passes, the order transitions from COMPLETED_OUTSTANDING to COMPLETED_FINALIZED.
Failed Payments
A failed one-time order reverts to DRAFT - the customer can modify it and try again with a different payment method. A failed subscription renewal or PAYG order stays PENDING instead and is retried automatically via the mandate - see Mandate-Based Orders.
Access Control
Any role can list and view active payment methods. Creating, updating, or deactivating a payment method is reserved for TiruPay operators - not available to User, Service, or Admin roles.
Relationships
- Orders - Each payment belongs to an order. An order can have multiple payment attempts.
- Customers - Mandates are linked to customers for recurring payments.
- Services - Mandates are scoped to a service.
- Taxation - Article availability controls which payment methods are available per country.
- Redirect Security - Checkout and mandate redirect URLs are validated against your service's whitelist.
- Dunning - Both invoice-style and mandate-based overdue orders are revoked via
grace_period_daysand escalate through the same dunning policy.