Use this guide to configure valid values for returnUrl, failReturnUrl, and callbackUrl.

• Set returnUrl to the address the frontend should open after the user completes the flow
• Set failReturnUrl to the address the frontend should open after the user does not complete the flow
• Set callbackUrl to your server callback endpoint if the product supports it

Supported URL Types

returnUrl and failReturnUrl support these formats:

• Standard web URLs, for example https://www.example.com/result
• Custom app URL schemes, for example myapp://verification/result

callbackUrl only supports standard web URLs with http:// or https://.

When Each URL Is Used

returnUrl

Use returnUrl for the redirect after the user completes the frontend flow.

Examples:

https://www.example.com/verification/success

myapp://verification/success

failReturnUrl

Use failReturnUrl for the redirect after the user does not complete the frontend flow.

Examples:

https://www.example.com/verification/fail

myapp://verification/fail

callbackUrl

Use callbackUrl for the server-to-server notification endpoint when the product supports callbacks.

Example:

https://api.example.com/verification/callback

Redirect URL Requirements

Apply these rules to both returnUrl and failReturnUrl.

• Use a value that is not empty
• Do not include control characters such as line breaks, carriage returns, tabs, or null bytes
• Use a value that can be parsed as a valid URI
• Use a valid scheme format
• Do not use restricted schemes such as javascript, data, file, about, blob, or intent
• Include a host in the format scheme://host/...

Valid examples:

• https://example.com/callback
• myapp://callback/success
• alipays://platformapi/startapp?id=1

Rejected examples:

• javascript:alert(1)
• myapp:
• myapp://
• https://host/\npath

callbackUrl Requirements

Apply these rules to callbackUrl.

• Use http:// or https:// only
• Do not use a custom app scheme such as myapp://...
• Use a callback address that your backend can receive directly

Valid example:

https://api.example.com/verification/callback

Rejected example:

myapp://verification/callback

App Integration Notes

If you use a custom app URL scheme such as myapp://..., follow these requirements:

• Register the scheme in your app before going live
• Keep the scheme and path stable across your app integrations
• Encode query parameter values if you append additional parameters to the URL
• Test the redirect on every platform where your app is available

Examples

Web Redirect Example

{
  "returnUrl": "https://www.example.com/verification/success",
  "failReturnUrl": "https://www.example.com/verification/fail"
}

Custom Scheme Redirect Example

{
  "returnUrl": "myapp://verification/success",
  "failReturnUrl": "myapp://verification/fail"
}

Callback URL Example

{
  "callbackUrl": "https://api.example.com/verification/callback"
}

Notes

• Keep returnUrl and failReturnUrl consistent within the same application flow
• Use URLs that your client application can handle directly
• Keep callbackUrl on a backend endpoint, not an app deep link
• For product-specific redirect behavior, refer to the relevant Generate URL API page and frontend integration page