Skip to content

Right of Withdrawal ​

TiruPay supports the statutory right of withdrawal (gesetzliches Widerrufsrecht) as a first-class feature. Services configure withdrawal rules per article and country; TiruPay handles the entire process - consent at checkout, authenticated and unauthenticated withdrawal flows, deadlines, refunds, and webhook notifications.

Legal Compliance Reminder

Withdrawal rights are governed by local consumer protection law (e.g. § 312g BGB in Germany). Deadlines, required disclosures, and eligible order types vary by jurisdiction.

This documentation describes how TiruPay implements the technical flow. It does not constitute legal advice. Always consult applicable law and legal counsel for compliance requirements.

Concepts ​

ArticleWithdrawalConfig ​

Defines the withdrawal rules for a specific article, optionally scoped to a country. If no country-specific config exists, TiruPay falls back to the config with country_code = null (the wildcard). If no config exists at all, the article has no withdrawal right.

FieldDescription
article_idThe article these rules apply to (mutually exclusive with article_extension_id)
article_extension_idThe article extension these rules apply to (mutually exclusive with article_id)
country_codeCountry scope. null = applies to all countries without a more specific config
statusConfig lifecycle status: DRAFT, ACTIVE, SUPERSEDED, ARCHIVED (see Config Versioning)
effective_fromWhen this config version becomes effective. null = immediately (only valid for ACTIVE on creation)
previous_config_idInformational link to the config version this one supersedes
withdrawal_policyHow refunds are calculated (see Policies)
withdrawal_period_daysHow many days after order the customer may withdraw. null only for EXPIRES_ON_START
handling_modeAUTO - TiruPay executes the refund; NOTIFY - TiruPay notifies the service and waits
withdrawal_policy_document_idDocument shown at checkout. TiruPay resolves the currently published version at runtime

Config lookup order: (article_id, country_code) → (article_id, null) → no config. Only configs with status = ACTIVE are considered for lookup.

WithdrawalRequest ​

An immutable fiscal record of a single withdrawal. Created when the customer submits a withdrawal. Cannot be deleted.

FieldDescription
statusCurrent state of the request (see Statuses)
withdrawal_config_idThe config that governed this withdrawal
submitted_atWhen the withdrawal was received
deadline_atExpiry of the withdrawal period (based on order date + configured period). null for EXPIRES_ON_START
is_authenticatedWhether the request came from an authenticated user
order_refund_idSet when TiruPay executed the refund internally (AUTO mode or service-triggered with execute_refund=true)
external_refund_idOpaque reference provided by the service when the refund was processed outside TiruPay
processed_by_user_idThe service or admin user who manually completed or rejected this request. null for AUTO mode
requester_first_name, requester_last_name, requester_emailPII collected during the unauthenticated flow - GDPR-erasable

WithdrawalToken ​

A single-use, time-limited token (1 hour TTL) used in the unauthenticated withdrawal flow. Sent to the customer by email. Once consumed, used_at is set and the token cannot be reused.

Policies ​

PolicyRefund behavior
full_refundFull refund of the order amount
expires_on_startWithdrawal right expires immediately when service delivery begins. No withdrawal_period_days needed
proportionalPartial refund for subscriptions based on unused days. Requires handling_mode=notify — TiruPay cannot determine the correct amount automatically. The service passes refund_amount when calling the complete endpoint.

Statuses ​

StatusMeaning
pendingUnauthenticated request received, magic link not yet confirmed
confirmedWithdrawal confirmed (email sent, service notified)
processingNOTIFY mode: service has been notified, waiting for manual completion or rejection
completedWithdrawal completed and refund processed
rejectedWithdrawal rejected (outside deadline, policy expired, or manually rejected by service)
expiredUnauthenticated request whose magic link expired before the customer confirmed it. Kept so support can see the attempt; it no longer blocks a new request and can still be accepted as a goodwill gesture.

Handling Modes ​

AUTO ​

TiruPay executes the refund immediately when the withdrawal is confirmed. The order is set to WITHDRAWN, subscriptions are cancelled, and a WITHDRAWAL_COMPLETED webhook and email are sent automatically.

NOTIFY ​

TiruPay tracks the withdrawal but does not execute a refund. The status moves to PROCESSING and a WITHDRAWAL_RECEIVED webhook is sent. The service is responsible for processing the refund and must call the complete or reject endpoint to finalize.

Authenticated Withdrawal ​

Used when the customer is logged in.

POST /user/withdrawals/{order_id}/withdraw

TiruPay validates access rights, checks that a withdrawal config exists for the article, that the customer is not a business, that the withdrawal period has not expired, and that no open withdrawal request already exists for the order.

On success:

  • AUTO mode: refund is executed immediately, status moves to COMPLETED
  • NOTIFY mode: status moves to PROCESSING, WITHDRAWAL_RECEIVED webhook sent to service
  • If the order has positions with different withdrawal configs, TiruPay cannot determine which config governs the whole order and falls back to NOTIFY regardless of the configured handling_mode

Unauthenticated Withdrawal ​

A two-step flow for customers without an account or without a session.

POST /withdrawals/unauthenticated?service_id={id}

json
{
  "email": "customer@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "invoice_number": "INV-2024-001"
}

TiruPay looks up the order by invoice_number within the given service and verifies that the name and email match the order's customer. The response is always 200 OK regardless of whether a match was found - this prevents information leaks about whether an account or order exists.

If a match is found:

  • A WithdrawalRequest with status PENDING is created
  • A WithdrawalToken (1 hour TTL) is generated
  • A magic link email is sent to the provided address

POST /withdrawals/confirm/{token}?service_id={id}

Consumes the token (validates TTL, single-use), sets used_at, and activates the withdrawal. The same flow as authenticated withdrawal applies from this point.

Returns the WithdrawalRequest on success.

Token Expiry

Tokens expire 1 hour after creation and can only be used once. Once the token has expired, the request moves to expired (at the latest within an hour) and the customer can restart the unauthenticated flow from step 1 - within the withdrawal period.

NOTIFY Mode: Complete or Reject ​

When handling_mode = NOTIFY, the service must finalize the withdrawal manually.

Complete ​

POST /service/withdrawals/{withdrawal_request_id}/complete

All fields are optional.

FieldDefaultDescription
execute_refundtrueIf false, TiruPay skips refund execution. Use when the refund was processed externally. TiruPay always refunds to the original payment method (ALL_TO_MONEY).
refund_amount—Gross refund amount to process. If omitted, TiruPay refunds the full remaining order amount. Use this for PROPORTIONAL configs where the service determines the correct partial amount.
external_refund_id—External refund identifier (e.g. PSP refund ID) to record on the withdrawal request.

Marks the request as COMPLETED, sets the order to WITHDRAWN, and sends a WITHDRAWAL_COMPLETED webhook and email.

Reject ​

POST /service/withdrawals/{withdrawal_request_id}/reject

json
{
  "rejection_reason": "Withdrawal period has expired."
}

Marks the request as REJECTED and sends a WITHDRAWAL_REJECTED webhook and email. If the withdrawal had set the subscription to WITHDRAWAL_PENDING, that status is reverted.

Overdue reminder

A request that is still confirmed or processing 10 days after submission triggers a one-time withdrawal_overdue notification to the service's admins. The reimbursement is due within 14 days of the withdrawal.

Accept an expired request ​

POST /service/withdrawals/{withdrawal_request_id}/accept-expired

Processes an expired request as if the customer had confirmed it - for example when a customer contacts support because they missed the magic link email. The withdrawal period is not checked again, since the request itself was submitted in time. The usual flow follows (AUTO: refund, NOTIFY: PROCESSING and WITHDRAWAL_RECEIVED webhook).

Fails with 409 if the request isn't expired, the order can no longer be withdrawn, or another open withdrawal request exists for the order.

Listing and Retrieving Requests ​

EndpointDescription
GET /service/withdrawalsList withdrawal requests with optional filters, newest first
GET /service/withdrawals/{withdrawal_request_id}Get a single withdrawal request

The list is paginated like the other list endpoints: the response is { "count": <total matching>, "items": [...] }.

Available filters for GET /service/withdrawals (and GET /admin/withdrawals):

ParameterDescription
service_idFilter by service
order_idFilter by order
customer_idFilter by customer
withdrawal_statusFilter by status (pending, confirmed, processing, completed, rejected, expired); repeat the parameter to match several statuses
offset / limitPagination (default: offset=0, limit=100, max: 1000)

Config Versioning ​

Configs follow a status lifecycle to protect existing customers from unintended changes. At most one ACTIVE and one DRAFT config may exist per (article_id|article_extension_id, country_id) slot at any time.

StatusMeaning
DRAFTBeing prepared. Not used for any withdrawal lookup. Can be updated freely.
ACTIVECurrently in effect. Used for all new withdrawal lookups.
SUPERSEDEDWas previously ACTIVE but has been replaced by a newer version. Retained for audit.
ARCHIVEDManually retired. No longer used for lookup.

Typical workflow ​

  1. POST /service/withdrawals/config with effective_from set → creates a DRAFT
  2. PATCH /service/withdrawals/config/{id} → update the draft while preparing
  3. POST /service/withdrawals/config/{id}/activate → promotes DRAFT to ACTIVE, existing ACTIVE moves to SUPERSEDED
  4. Alternatively: POST /service/withdrawals/config without effective_from → creates directly as ACTIVE (only if no ACTIVE exists for that slot)

To retire a config without a replacement: POST /service/withdrawals/config/{id}/archive

Managing Configs ​

EndpointDescription
POST /service/withdrawals/configCreate a new config (ACTIVE if no effective_from, else DRAFT)
GET /service/withdrawals/config?service_id={id}List configs for a service
PATCH /service/withdrawals/config/{config_id}Update a DRAFT config
POST /service/withdrawals/config/{config_id}/activatePromote a DRAFT to ACTIVE
POST /service/withdrawals/config/{config_id}/archiveArchive an ACTIVE or DRAFT config

Webhooks ​

ReasonWhen
WITHDRAWAL_RECEIVEDAlways, when a withdrawal is confirmed (both AUTO and NOTIFY)
WITHDRAWAL_COMPLETEDWhen the withdrawal is finalized (AUTO: immediately; NOTIFY: on service completion)
WITHDRAWAL_REJECTEDWhen a withdrawal is rejected, regardless of mode

Emails ​

TypeSent toWhen
WITHDRAWAL_RECEIVEDCustomerOn confirmation - the legally required durable medium receipt
WITHDRAWAL_COMPLETEDCustomerWhen completed
WITHDRAWAL_REJECTEDCustomerWhen rejected

Subscriptions ​

When a withdrawal is received for an order that belongs to a subscription, TiruPay sets the subscription status to WITHDRAWAL_PENDING. This blocks the renewal cron from billing the subscription while the withdrawal is being processed.

On completion, the subscription is cancelled with status WITHDRAWN. On rejection, the WITHDRAWAL_PENDING status is reverted and the subscription resumes its normal renewal cycle.

Orders ​

When a withdrawal is completed, the order status is set to WITHDRAWN. This is distinct from regular refunds (PARTIALLY_REFUNDED, REFUNDED) and ensures the reason for the status change is unambiguous in reporting.

Balances ​

Prepaid balance top-up articles (using ArticleBalanceTopup) follow the same withdrawal config flow as any article. If a withdrawal is processed in AUTO mode, TiruPay automatically reverts the balance top-up.

For subscriptions that activate a PAYG balance (ArticlePaygActivation), a balance freeze is created when the withdrawal is received, preventing new reservations during processing. The freeze is lifted on rejection or finalized on completion.

When a FULL_REFUND withdrawal completes in AUTO mode, any PENDING PAYG usages (not yet billed) are set to WAIVED. This prevents the billing cron from issuing a PAYG invoice for usage that accumulated during the withdrawal period after the full refund has already been issued.

GDPR ​

The requester_first_name, requester_last_name, and requester_email fields on WithdrawalRequest are PII collected during the unauthenticated flow. These fields are included in GDPR data disclosure responses and can be erased on a GDPR erasure request.

processed_by_user_id is audit data (who processed the request), not PII - it is retained and not erasable.

The rest of the WithdrawalRequest record is a fiscal record and is retained.

Access Control ​

RoleConfigsWithdrawal RequestsComplete/Reject
User-Submit own orders-
ServiceOwn service (CRUD)Own service (read, complete, reject)Own service
AdminOwn services (CRUD)Own services (read, complete, reject)Own services
SuperadminAllAllAll
Unauthenticated-Submit via magic link flow-

Relationships ​

  • Articles - Each config is scoped to an article and optional country.
  • Orders - Withdrawals are submitted against orders. Order status moves to WITHDRAWN on completion.
  • Subscriptions - Subscriptions are locked during processing and cancelled on completion.
  • Legal Documents - The withdrawal_policy_document_id links to the document shown at checkout.
  • Webhooks - Three withdrawal webhook reasons notify services of received, completed, and rejected withdrawals.
  • Email - Three email types send confirmation receipts and status updates to customers.
  • Balances - Balance top-ups are reverted on AUTO withdrawal. PAYG balances are frozen during processing.