Skip to content

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.

FieldTypeDescription
idstringUnique identifier
service_idstringThe service this entry belongs to
urlstringAn HTTPS URL on the domain you want to allow
labelstringOptional human-readable label
is_activebooleanWhether this entry is currently enforced
created_atdatetimeWhen the entry was created
updated_atdatetimeWhen 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 ​

FlowParameterWhere
OIDC loginredirect_urlOIDC Login
Checkout sessionfinal_redirect_urlCheckout Sessions
Redirect-based mandate setupcompletion_redirect_urlMandates

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:

MethodPathDescription
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 ​

RoleCan listCan viewCan createCan updateCan delete
ServiceOwn serviceOwn serviceOwn serviceOwn serviceOwn service
AdminOwn servicesOwn servicesOwn servicesOwn servicesOwn services
SuperadminAllAllAllAllAll

Relationships ​

  • Services - Each whitelist entry belongs to one service; default_url also lives on the service.
  • User Roles & Permissions - The OIDC login flow's redirect_url goes through this check.
  • Payments - Checkout session and mandate redirects go through this check.