Skip to content

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.

FieldTypeDescription
namestringDisplay name (e.g. "Credit Card", "SEPA Direct Debit")
identifierstringTechnical identifier (e.g. credit_card, sepa_direct_debit). Needs to be one of Available Identifiers
partnerenumWhich payment partner handles this method (mollie, stripe, or nemo)
revoke_deadline_daysintegerDays after payment during which the customer can still revoke (e.g. 180 for credit cards, 56 for SEPA)
is_activebooleanWhether this method is currently available
allows_manual_capturebooleanWhether this method may be used with capture_mode: manual (see Capture Modes)
allows_mandate_creationbooleanWhether 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:

PartnerDescription
mollieMollie - supports credit cards, SEPA, PayPal, and many local methods
stripeStripe - credit cards and other methods
nemoIn-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:

ModeDescription
partner_hosted_checkoutCustomer is redirected to the partner's checkout page (e.g. Mollie checkout). Recommended for most cases.
self_hosted_checkoutPayment is handled on your own checkout page. Requires PCI compliance for credit cards.
mandatePayment 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:

ModeDescription
automatic (default)Payment is captured as soon as it's authorized.
manualPayment 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 to PENDING and continues through the normal payment flow to COMPLETED_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 ​

FieldTypeDescription
customer_idstringThe customer who authorized the mandate
service_idstringThe service this mandate belongs to
partnerenumWhich payment partner holds the mandate
payment_method_idstringWhich payment method the mandate is for
partner_mandate_idstringThe mandate ID at the partner
statusenumCurrent mandate status

Mandate Statuses ​

StatusDescription
PENDINGCreated but not yet active
VALIDActive and can be used for recurring charges
INVALIDFailed verification
REVOKEDExplicitly revoked by the customer
EXPIREDExpired

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 ​

FieldTypeDefaultDescription
order_typeenumone_timeWhether 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_onenumcompletedWhen to activate features: pending (at invoice creation) or completed (after successful payment)
payment_due_daysinteger14Days from order date until payment is due. Only relevant when activate_features_on is pending.
grace_period_daysinteger0Extra 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:

FieldDescription
checkout_modeHow the payment is processed (see Checkout Modes)
capture_modeWhether to capture automatically or manually
final_redirect_urlWhere 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:

  1. Customer sync - The customer is created in the Payment Processor if they don't exist yet.
  2. Payment creation - A payment record is created in both TiruPay and the Payment Processor.
  3. Mandate handling - For subscriptions: an existing mandate is used, or a new one is created from the provided SEPA/PayPal data.
  4. Payment selection - The payment is activated at the partner with the chosen payment method and checkout mode.
  5. Redirect URL - A checkout URL is returned for partner_hosted_checkout, or the final_redirect_url for 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 StatusTiruPay Action
paidComplete 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.
failedFor 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.
canceledCancel the order
expiredCancel 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_captureMove the order to NEEDS_MANUAL_CAPTURE - see Capture Modes
charged_backRevoke the order - deactivate features, reverse balances, start dunning
refundedRefund the order

Subscription Renewals ​

For recurring subscription payments, TiruPay uses the customer's existing mandate:

  1. The next order in the subscription chain activates (status IN_FUTURE → PENDING).
  2. A payment is created with checkout_mode: mandate - no customer interaction.
  3. The partner charges the customer's payment method using the mandate.
  4. 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_days and escalate through the same dunning policy.