Manage web redirection
Beta

Last updated: January 15, 2025

For the Identity Verification and Face Authentication solutions, the user can start their journey in your mobile app, mobile website, or desktop website. Checkout.com redirects them to complete the web flow in their mobile browser. This is a secure environment that makes users more likely to complete the flow.

Set up your redirect integration using any of the following options:
- Web redirection – App and website
- iframes – App and website
- WebView – App only
You can also customize the user interface of the web flow, and check which languages are supported.
For users who start their journey on your desktop website:
- They choose how to receive the URL for the web flow.
- After completing the flow, Checkout.com redirects the user to a return page in your app or website, which is updated in real time.

For web redirection from your app or website, Checkout.com supports the following environments and minimum browser versions:

Chrome 53 or later
Firefox 52 or later
Safari 11.1 or later
Edge 16 or later
Opera 58 or later

After you create an attempt and receive the verification_url, pass the URL to your web app and add it as a link:


1<a href="`${verificationUrl}`"></a>

Information

See an example web integration on our Identity Verification GitHub repository.

When the user completes or terminates the flow, they are redirected to your return page at the redirect_url you provided when you created the attempt.

The redirect URL includes:

The verification ID
The final event in the flow, which you also receive as a webhook notification
The response_code if the verification was unsuccessful


1https://your-redirect-url.com?id=idv_01h2623ysfkhpn7czed0bw8fd6&event=identity_verification_capture_aborted&response_code=61101

Your follow-up action depends on the webhook event you receive:

Webhook event	Follow-up action
`identity_verification_capture_aborted`	Create a new attempt.
`identity_verification_capture_completed`	You can ask the user to perform additional checks or to wait until the result is available. We recommend waiting for the `identity_verification_checks_completed` webhook to make your decision. In some instances, you may receive this simultaneously with the `identity_verification_capture_completed` webhook.
`identity_verification_capture_refused`	Suggest an alternative verification method to the user.
`identity_verification_link_expired`	Create a new attempt.

For iframe (or inline frame) redirection from your app or website, use the following SDK:

Include the SDK as a script tag:


1<script
2  src="https://cdn.ubble.ai/iframe-sdk-1.0.0.js"
3  type="application/javascript"
4></script>

Add a global method called onUbbleReady to the page that is triggered when the SDK is loaded:


1function onUbbleReady() {
2
3}

Initialize a new IDV object:


1function onUbbleReady() {
2  const ubbleIDV = new Ubble.IDV(document.getElementById("ubble"), options);
3}

onComplete(completeEvent) – Triggered when the user completes the capture


1{
2  "event": "capture_completion",
3  "redirectUrl": "https://your-redirect-url.com?id=<identity verification id>&event=identity_verification_capture_completed"
4}

onRefused(refusedEvent) – Triggered if the user refuses to complete the flow


1{
2  "event": "capture_refusal",
3  "responseCode": 63001,
4  "redirectUrl": "https://your-redirect-url.com?id=<identity verification id>&event=identity_verification_capture_refused"
5}

onAbort(abortEvent) – Triggered if the user terminates the capture


1{
2  "event": "capture_abortion",
3  "responseCode": 61111,
4  "redirectUrl": "https://your-redirect-url.com?id=<identity verification id>&event=identity_verification_capture_aborted&response_code=63001"
5}

onExpired – Triggered when the verification URL expires


1{
2  "event": "expiration",
3  "redirectUrl": "https://your-redirect-url.com?id=<identity verification id>&event=identity_verification_link_expired&response_code=63001"
4}

destroy() – Ends the flow


1const ubbleIDV = new Ubble.IDV("id", {
2  events: {
3    onComplete(event) {
4      console.log(`Done with ubble flow: ${event}`);
5      ubbleIDV.destroy();
6    },
7  },
8});


1const ubbleIDV = new Ubble.IDV("idv", {
2  width: "500",
3  height: "600",
4  allowCamera: true,
5  verificationUrl: "https://idv.checkout.com/4hryu5cei5",
6  events: {
7    onComplete(event) {
8      ubbleIDV.destroy();
9    },
10    onAbort(event) {
11      ubbleIDV.destroy();
12    },
13    onExpired(event) {
14      ubbleIDV.destroy();
15    }
16    onRefused(event) {
17      ubbleIDV.destroy();
18    }
19  },
20});

Note

If you encounter issues, ensure that:

You included a semicolon in the Content-Security-Policy: frame-src https://*.domain_name.fr; header.
The user gave permission to use their mobile device camera.

When the user completes or terminates the flow, use the destroy() method to return them to your return page redirect_url.

If the user starts the journey in your mobile app, you can redirect them to the web flow using WebView for a smooth, integrated experience. WebView redirection is supported by the following platforms:

Android
iOS 13 or later – via WebRTC running inside a WKWebView
iOS 12 or older – via the Safari browser by passing the verificationUrl to the UIApplication.open() method in your app code
React Native
Flutter – using the flutter_inappwebview dependency, with the WebRTC API so Identity Verification can launch a video stream

For a WebView integration, you must provide a deeplink to redirect the user on your mobile app.

Information

See example WebView integrations for each platform on our Identity Verification GitHub repository.

When the user completes or terminates the flow, they're redirected to your return page at the redirect_url you provided when you created the attempt.

The redirect URL includes:

The verification ID
The final event in the flow, which you also receive as a webhook notification
The response_code if the verification was unsuccessful


1https://your-redirect-url.com?id=idv_01h2623ysfkhpn7czed0bw8fd6&event=identity_verification_capture_aborted&response_code=61101

Your follow-up action depends on the webhook event you receive:

Webhook event Follow-up action

identity_verification_capture_aborted

Create a new attempt.

identity_verification_capture_completed

You can ask the user to perform additional checks or to wait until the result is available.

We recommend waiting for the identity_verification_checks_completed webhook to make your decision. In some instances, you may receive this simultaneously with the identity_verification_capture_completed webhook.

identity_verification_capture_refused

Suggest an alternative verification method to the user.

You can customize the following elements of the web flow user interface (UI):

Logo
Colors
Fonts
Button radius
Message prompt text

Use the customization tool to create the HTML to send to your Account Manager or [email protected].

The UI supports the following languages:

Chinese (simplified)
Dutch
English (UK)
English (US)
Estonian
Finnish
French
German
Italian
Latvian
Polish
Portuguese
Romanian
Slovak
Spanish
Swedish

If the user starts their journey on your desktop website, they must choose to securely receive the verification URL for the web flow via either QR code or SMS.

For SMS, Checkout.com requires the user's mobile phone number, which you are responsible for validating, in one of the following ways:

You can provide the number when creating an attempt, and this box is pre-filled in the web flow.
The user can enter the number in the web flow.

Manage web redirection
Beta

How it works

Web redirection

Information

Handle user return with web redirection

Iframe redirection

Iframe SDK

API

Events

Methods

Full example

Note

Handle user return with iframes

WebView redirection

Information

Handle user return with WebView

Customize the user interface

Supported languages

URL sharing options