Appearance
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.
| Field | Description |
|---|---|
article_id | The article these rules apply to (mutually exclusive with article_extension_id) |
article_extension_id | The article extension these rules apply to (mutually exclusive with article_id) |
country_code | Country scope. null = applies to all countries without a more specific config |
status | Config lifecycle status: DRAFT, ACTIVE, SUPERSEDED, ARCHIVED (see Config Versioning) |
effective_from | When this config version becomes effective. null = immediately (only valid for ACTIVE on creation) |
previous_config_id | Informational link to the config version this one supersedes |
withdrawal_policy | How refunds are calculated (see Policies) |
withdrawal_period_days | How many days after order the customer may withdraw. null only for EXPIRES_ON_START |
handling_mode | AUTO - TiruPay executes the refund; NOTIFY - TiruPay notifies the service and waits |
withdrawal_policy_document_id | Document 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.
| Field | Description |
|---|---|
status | Current state of the request (see Statuses) |
withdrawal_config_id | The config that governed this withdrawal |
submitted_at | When the withdrawal was received |
deadline_at | Expiry of the withdrawal period (based on order date + configured period). null for EXPIRES_ON_START |
is_authenticated | Whether the request came from an authenticated user |
order_refund_id | Set when TiruPay executed the refund internally (AUTO mode or service-triggered with execute_refund=true) |
external_refund_id | Opaque reference provided by the service when the refund was processed outside TiruPay |
processed_by_user_id | The service or admin user who manually completed or rejected this request. null for AUTO mode |
requester_first_name, requester_last_name, requester_email | PII 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
| Policy | Refund behavior |
|---|---|
full_refund | Full refund of the order amount |
expires_on_start | Withdrawal right expires immediately when service delivery begins. No withdrawal_period_days needed |
proportional | Partial 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
| Status | Meaning |
|---|---|
pending | Unauthenticated request received, magic link not yet confirmed |
confirmed | Withdrawal confirmed (email sent, service notified) |
processing | NOTIFY mode: service has been notified, waiting for manual completion or rejection |
completed | Withdrawal completed and refund processed |
rejected | Withdrawal rejected (outside deadline, policy expired, or manually rejected by service) |
expired | Unauthenticated 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:
AUTOmode: refund is executed immediately, status moves toCOMPLETEDNOTIFYmode: status moves toPROCESSING,WITHDRAWAL_RECEIVEDwebhook 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
NOTIFYregardless of the configuredhandling_mode
Unauthenticated Withdrawal
A two-step flow for customers without an account or without a session.
Step 1 - Request a magic link
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
WithdrawalRequestwith statusPENDINGis created - A
WithdrawalToken(1 hour TTL) is generated - A magic link email is sent to the provided address
Step 2 - Confirm via magic link
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.
| Field | Default | Description |
|---|---|---|
execute_refund | true | If 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
| Endpoint | Description |
|---|---|
GET /service/withdrawals | List 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):
| Parameter | Description |
|---|---|
service_id | Filter by service |
order_id | Filter by order |
customer_id | Filter by customer |
withdrawal_status | Filter by status (pending, confirmed, processing, completed, rejected, expired); repeat the parameter to match several statuses |
offset / limit | Pagination (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.
| Status | Meaning |
|---|---|
DRAFT | Being prepared. Not used for any withdrawal lookup. Can be updated freely. |
ACTIVE | Currently in effect. Used for all new withdrawal lookups. |
SUPERSEDED | Was previously ACTIVE but has been replaced by a newer version. Retained for audit. |
ARCHIVED | Manually retired. No longer used for lookup. |
Typical workflow
POST /service/withdrawals/configwitheffective_fromset → creates aDRAFTPATCH /service/withdrawals/config/{id}→ update the draft while preparingPOST /service/withdrawals/config/{id}/activate→ promotesDRAFTtoACTIVE, existingACTIVEmoves toSUPERSEDED- Alternatively:
POST /service/withdrawals/configwithouteffective_from→ creates directly asACTIVE(only if noACTIVEexists for that slot)
To retire a config without a replacement: POST /service/withdrawals/config/{id}/archive
Managing Configs
| Endpoint | Description |
|---|---|
POST /service/withdrawals/config | Create 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}/activate | Promote a DRAFT to ACTIVE |
POST /service/withdrawals/config/{config_id}/archive | Archive an ACTIVE or DRAFT config |
Webhooks
| Reason | When |
|---|---|
WITHDRAWAL_RECEIVED | Always, when a withdrawal is confirmed (both AUTO and NOTIFY) |
WITHDRAWAL_COMPLETED | When the withdrawal is finalized (AUTO: immediately; NOTIFY: on service completion) |
WITHDRAWAL_REJECTED | When a withdrawal is rejected, regardless of mode |
Emails
| Type | Sent to | When |
|---|---|---|
WITHDRAWAL_RECEIVED | Customer | On confirmation - the legally required durable medium receipt |
WITHDRAWAL_COMPLETED | Customer | When completed |
WITHDRAWAL_REJECTED | Customer | When 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
| Role | Configs | Withdrawal Requests | Complete/Reject |
|---|---|---|---|
| User | - | Submit own orders | - |
| Service | Own service (CRUD) | Own service (read, complete, reject) | Own service |
| Admin | Own services (CRUD) | Own services (read, complete, reject) | Own services |
| Superadmin | All | All | All |
| 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
WITHDRAWNon completion. - Subscriptions - Subscriptions are locked during processing and cancelled on completion.
- Legal Documents - The
withdrawal_policy_document_idlinks 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.