Appearance
Redirect Security
Several flows end with TiruPay sending the customer's browser back to a URL your service controls - after login, after payment, or after mandate setup. Because some of these URLs are supplied at request time (e.g. a redirect_url or final_redirect_url parameter), TiruPay validates them before redirecting: the target must be reachable over HTTPS, and its origin must be on your service's redirect whitelist. If either check fails, the customer is shown a TiruPay-hosted notice page instead of being sent to the untrusted URL.
Configure this before going live
Any redirect flow described here fails closed if the whitelist is empty or missing the right origin - test each flow (login, checkout, mandate setup) after adding your domain.
Redirect Whitelist
A whitelist entry allows redirects to a given origin for one service.
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier |
service_id | string | The service this entry belongs to |
url | string | An HTTPS URL on the domain you want to allow |
label | string | Optional human-readable label |
is_active | boolean | Whether this entry is currently enforced |
created_at | datetime | When the entry was created |
updated_at | datetime | When the entry was last updated |
Matching is by origin, not full URL
Only the scheme, host, and port of url are compared - the path and query string are ignored. Adding https://shop.example.com/checkout allows redirects anywhere on https://shop.example.com, including paths you didn't explicitly list.
TiruPay's own hosted frontend is always implicitly allowed, in addition to whatever you add here - the default login and checkout journey passes through it before optionally continuing on to your domain.
Which Redirects This Covers
| Flow | Parameter | Where |
|---|---|---|
| OIDC login | redirect_url | OIDC Login |
| Checkout session | final_redirect_url | Checkout Sessions |
| Redirect-based mandate setup | completion_redirect_url | Mandates |
Relative paths are always safe
redirect_url may be a path relative to the TiruPay frontend (e.g. /checkout?order_id=123) rather than a full URL - relative paths never leave the current origin, so they're always allowed and don't need a whitelist entry. A full URL, or a protocol-relative path like //example.com, is checked against your whitelist instead.
JWT Token Exchange redirects are your own
In the JWT Token Exchange flow, your backend builds the redirect to the TiruPay frontend itself rather than calling a TiruPay redirect endpoint - TiruPay never sees that URL, so it isn't checked against the whitelist. Only pass through redirect values you trust.
Partner-hosted checkout is not affected
When a payment uses partner_hosted_checkout, the checkout URL comes directly from the payment partner (e.g. Mollie) and is never checked against your whitelist - you don't need to add partner domains to it.
When a Redirect Is Blocked
Instead of redirecting to a rejected URL, TiruPay shows a notice page with a link back to your service, using the service's default_url field (see Services). Set default_url to your service's homepage so customers always have a way back, even if a redirect gets misconfigured.
Endpoints
Available under both /admin and /service:
| Method | Path | Description |
|---|---|---|
GET | /redirect-whitelist/ | List whitelist entries for a service |
GET | /redirect-whitelist/{entry_id} | Get a single entry |
POST | /redirect-whitelist/?service_id={id} | Add a URL to the whitelist |
PATCH | /redirect-whitelist/{entry_id} | Update a URL, label, or active status |
DELETE | /redirect-whitelist/{entry_id} | Remove an entry |
Access Control
| Role | Can list | Can view | Can create | Can update | Can delete |
|---|---|---|---|---|---|
| Service | Own service | Own service | Own service | Own service | Own service |
| Admin | Own services | Own services | Own services | Own services | Own services |
| Superadmin | All | All | All | All | All |
Relationships
- Services - Each whitelist entry belongs to one service;
default_urlalso lives on the service. - User Roles & Permissions - The OIDC login flow's
redirect_urlgoes through this check. - Payments - Checkout session and mandate redirects go through this check.