Non-hosted standalone

Last updated: April 2, 2025

For full control over your authentication flow, use non-hosted sessions. The authentication process is managed by your back end.

To use Google Secure Payment Authentication (SPA), your authentication request must include the following fields:

challenge_indicator set to one of the following:
- no_preference – Default value
- no_challenge_requested
- challenge_requested
- challenge_requested_mandate
authentication_type set to regular – Default value
channel_data.channel set to browser

Additionally, Google SPA requires Android devices using Chrome browsers.

Note

Google SPA does not support network token payments.

If Google deems your authentication request ineligible for SPA, Checkout.com automatically fall backs your request to 3DS if it's included in your preferred experiences. Otherwise, the authentication will fail.

Google SPA relies on Google's Payment Request API to complete the payment.

If you host the payment page within an iframe, you must configure it to allow cross-origin resources to use the Payment Request API. Ensure you add this permission to the iframe that loads the authentication and all its parent iframes:


1<iframe src="https://example.com" allow="payment *"></iframe>

After a successful Google SPA authentication, you receive a provisioned Device Primary Account Number (DPAN) token, along with the ECI and cryptogram.

You must submit your subsequent payment request as a token payment using the DPAN token retrieved from authentication along with the ECI and cryptogram with your chosen PSP.

All Sessions API endpoints will accept a valid JSON web token (JWT) bearer token. These short-lived tokens can be generated using your client ID and secret, which you received after creating your account.

Tokens must contain the scope sessions:browser for browser channel flows. Google SPA only supports the browser channel, meaning other channel types (like apps) are not supported.

When you create a session, you get a session_secret property. You must use this session secret in the Authorization header of subsequent requests for that session.

The session_secret is a short-lived randomly generated string that can only be used for actions taken on a specific session, minimizing the risk of exposure. Unlike client secrets used for JWT token generation, the session_secret is not shared with the frontend, reducing the vulnerability to malicious third-party access.

Include google_spa in the request's preferred_experiences field.

Ensure you include multiple options in your authentication request. This approach provides you additional insight to help you determine your strategy and retry the authentication using an alternative experience if needed.

The experience that you list first takes precedence and becomes the preferred option.

If the authentication request is deemed ineligible by Google prior to the authentication being processed, Checkout.com automatically falls back to 3DS.

When you create a session with channel data, you don't need to update the channel data later on.


1{
2  "source": {
3    "type": "card",
4    "number": "4485040371536584",
5    "expiry_month": 1,
6    "expiry_year": 2030
7  },
8  "amount": 100,
9  "currency": "USD",
10  "authentication_type": "regular",
11  "authentication_category": "payment",
12  "challenge_indicator": "no_preference",
13  "reference": "ORD-5023-4E89",
14  "transaction_type": "goods_service",
15  "shipping_address": {
16    "address_line1": "123 Anywhere St.",
17    "address_line2": "Apt. 456",
18    "city": "Anytown",
19    "zip": "AB12 3CD",
20    "country": "GB"
21  },
22  "completion": {
23    "type": "non_hosted",
24    "callback_url": "http://example.com/sessions/callback"
25  },
26  "preferred_experiences": [
27    "google_spa",
28    "3ds"
29  ]
30}

If you receive a 202 - Accepted response, your request was successful. The response contains:

The session ID (prefixed by sid_)
A next_actions property, which indicates the next steps required to finalize the session.


1{
2  "id": "sid_uyf763hgstqena6ei5omawyxs4",
3  "transaction_id": "e9df0645-38dc-4823-8f9e-4378d0625b13",
4  "amount": 100,
5  "currency": "GBP",
6  "completed": false,
7  "authentication_type": "regular",
8  "authentication_category": "payment",
9  "status": "pending",
10  "next_actions": [
11    "collect_channel_data"
12  ],
13  "transaction_type": "goods_service",
14  "scheme": "visa",
15  "authentication_date": "2024-09-17T15:19:44.2393677Z",
16  "challenge_indicator": "no_preference",
17  "preferred_experiences": {
18    "preferred_experiences": {
19      "3ds": {
20        "status": "available"
21      },
22      "google_spa": {
23        "status": "available"
24      }
25    },
26    "_links": {
27      "self": {
28        "href": "https://sessions.cko-qa.ckotech.co/sessions/sid_uyf763hgstqena6ei5omawyxs4"
29      },
30      "collect_channel_data": {
31        "href": "https://sessions.cko-qa.ckotech.co/sessions/sid_iudn72o4harurd46in4nays3cm/collect-data"
32      },
33      "callback_url": {
34        "href": "https://google.com/"
35      }
36    }
37  }
38}

To make an authentication request you must gather the details of the browser that initiated the session.

To get this data, call the Get session details endpoint setting the {id} query parameter using the id value you received in the sessions response, prefixed with sid_.

Information

You can skip this step if your back end forwards the response of requesting a new session to your front end.

If the request is successful, you receive a 200 - OK response, along with a response containing the details of the authentication, along with the next_actions property, which indicates you what to do next:


1{  
2    "id": "sid_y2tlt2pd6ptu7fwlsz5ovmndea",  
3    "transaction_id": "e9b9a6c6-f3e3-4fe7-96cb-967aeab1a320",  
4    "amount": 100,  
5    "currency": "GBP",  
6    "completed": false,  
7    "authentication_type": "regular",  
8    "authentication_category": "payment",  
9    "status": "pending",  
10    "next_actions": ["collect_channel_data"],  
11    "challenge_indicator": "no_preference",  
12     "preferred_experiences": {  
13        "3ds": {  
14            "status": "available"  
15        },  
16        "google_spa": {  
17            "status": "available"  
18        }  
19    },  
20    "_links": {  
21        "self": {  
22            "href": "https://sessions.cko-qa.ckotech.co/sessions/sid_y2tlt2pd6ptu7fwlsz5ovmndea"  
23        },  
24        "collect_channel_data": {  
25            "href": "https://sessions.cko-qa.ckotech.co/sessions/sid_y2tlt2pd6ptu7fwlsz5ovmndea/collect-data"  
26        },  
27        "callback_url": {  
28            "href": "https://google.com/"  
29        }  
30    }  
31}

For the full API specification, see the API reference.

Field name	Description
`id` string	The unique identifier of the session.
`next_actions` array	Specifies what action to take to complete the session. Will be one of: `collect_channel_data`, `challenge_cardholder`, or `complete`.
`status` string	The status of the session.
`preferred_experiences` object	Provides information about the list of preferred experiences passed in the sessions request and their status
`preferred_experiences.3ds` object	Contains all information about 3DS experience at that stage of authentication
`preferred_experiences.3ds.status` string	The status of 3DS experience
`preferred_experiences.3ds.status_reason` string	The status reason in case of failure if authentication was processed using 3DS experience
`preferred_experiences.google_spa` object	Contains all information about google_spa experience
`preferred_experiences.google_spa.status` string	The status of google_spa experience
`preferred_experiences.google_spa.status_reason` string	The status reason in case of failure if authentication was processed using google_spa experience

If the next_actions field returns collect_channel_data, you must update the session with the device channel data.

To update the session, call the Update a session endpoint:

put

https://api.checkout.com/sessions/{session_id}/collect-data


1{
2  "channel": "browser",
3  "accept_header": "Accept: ., q=0.1",
4  "java_enabled": true,
5  "javascript_enabled": true,
6  "language": "FR-fr",
7  "color_depth": "16",
8  "screen_height": "1080",
9  "screen_width": "1920",
10  "timezone": "60",
11  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
12  "three_ds_method_completion": "U",
13  "ip_address": "1.12.123.255",
14  "iframe_payment_allowed": true,
15  "user_agent_client_hint": "'Sec-CH-UA: ' Not A;Brand';v='99', 'Chromium';v='96', 'Google Chrome';v='96''\n'"
16}

Field name	Description
`channel` string	Required. Indicates the interface (browser) being used to initiate the transaction. Set this to the browser.
`accept_header` string	Required. Exact content of the HTTP accept headers from the cardholder's browser.
`java_enabled` boolean	Required. Boolean that represents the ability of the cardholder browser to execute Java. The value is returned from the navigator.javaEnabled property.
`javascript_enabled` boolean	Boolean that represents the ability of the cardholder browser to execute JavaScript. Default: true
`language` string	Required. Value representing the browser language as defined in IETF BCP47. Returned from the navigator.language property.
`color_depth` string	Required. Value representing the bit depth of the color palette for displaying images, in bits per pixel. Obtained from the cardholder's browser using the `screen.colorDepth` property.
`screen_height` string	Required. Total height of the cardholder's screen in pixels. Value is returned from the `screen.height` property.
`screen_width` string	Required. Total width of the cardholder's screen in pixels. Value is returned from the `screen.width` property.
`timezone` string	Required. Time difference between UTC time and the local time of the cardholder's browser, in minutes.
`user_agent` string	Required. Exact content of the HTTP `user-agent` header.
`ip_address` string	Required. IP address of the browser as returned by the HTTP headers.
`user_agent_client_hint` string	The raw `Sec-CH-UA` header value. This can improve Google SPA support. For example – `"Chromium";v="96"`

After providing channel data, an authentication request is sent to Google, resulting in one of the following authentication responses:

unavailable
declined
rejected
challenged

This outcome is reflected in the next_actions property of the update response.

Field name	Description
`id` string	The unique identifier of the session.
`next_actions` array	Specifies what action to take to complete the session. Will be one of: `challenge_cardholder`, or `complete`.
`status` string	The status of the session.
`preferred_experiences` object	Provides information about the list of preferred experiences passed in the sessions request and their status.
`preferred_experiences.3ds` object	The field contains all information about 3DS experience.
`preferred_experiences.3ds.status` string	The status of 3DS experience.
`preferred_experiences.3ds.status_reason` string	The status reason in case of failure if authentication was processed using 3DS experience.
`preferred_experiences.google_spa` object	The field contains all information about `google_spa` experience.
`preferred_experiences.google_spa.status` string	The status of `google_spa` experience.
`preferred_experiences.google_spa.status_reason` string	The status reason in case of failure if authentication was processed using `google_spa` experience.
`google_spa` object	Provides more details related to `google_spa` experience.
`google_spa.challenge_url` string	Fully qualified URL of the Google SPA frontend for user challenge.
`google_spa.initial_timeout` string	Indicates amount of time (in minutes) allowed for establishing initial connection to user's specific authentication session (as determined by `challengeURL` and `params`)
`google_spa.max_timeout` string	Indicates maximum amount of time (in minutes) allowed for completing all PSP-Google message exchanges for the current authentication session.
`google_spa.iframe` object	Contains the information about the iframe to render challenge.
`google_spa.iframe.height` string	A string value which gives the percentage height of the iframe. The possible values are 0 and 100%.
`google_spa.iframe.width` string	A string value which gives the percentage width of the iframe. The possible values are 0 and 100%.

The possible statuses of the experiences are:

unavailable – Google SPA is unavailable due to ineligibility or technical issue, if you provided 3DS as a preferred experience, we will automatically fallback to 3DS.
available – The experience is available.
processed – The authentication was processed with this experience.
unprocessed – The authentication was not processed with this experience.


1{
2  "id": "sid_uyf763hgstqena6ei5omawyxs4",
3  "transaction_id": "6cff0ba6-94e6-46e0-83c4-475cc05b1797",
4  "amount": 100,
5  "currency": "GBP",
6  "completed": false,
7  "authentication_type": "regular",
8  "authentication_category": "payment",
9  "status": "challenged",
10  "next_actions": [
11    "challenge_cardholder"
12  ],
13  "transaction_type": "goods_service",
14  "scheme": "visa",
15  "authentication_date": "2024-09-18T10:54:57.7287097Z",
16  "flow_type": "challenged",
17  "challenge_indicator": "no_preference",
18  "preferred_experiences": {
19    "3ds": {
20      "status": "unprocessed"
21    },
22    "google_spa": {
23      "status": "processed"
24    }
25  },
26  "experience": "google_spa",
27  "google_spa": {
28    "challenge_url": "https://sessions-ext.cko-qa.ckotech.co/simulator/google-authentication/auth?sid=8af7a367-d087-4f94-8002-ce7b73133543&cid=6cff0ba6-94e6-46e0-83c4-475cc05b1797&origin=",
29    "initial_timeout": "00:15:00",
30    "max_timeout": "00:01:00",
31    "iframe": {
32      "height": "100%",
33      "width": "100%"
34    }
35  },
36  "_links": {
37    "self": {
38      "href": "https://sessions.cko-qa.ckotech.co/sessions/sid_uyf763hgstqena6ei5omawyxs4"
39    },
40    "callback_url": {
41      "href": "https://google.com/"
42    }
43  }
44}

All authentications processed with Google SPA are challenged.

If next_action is challenge_cardholder, you must handle the challenge flow for Google SPA.

This step is not applicable if the google_spa experience status field returns unavailable.

You can either fully redirect, or host the challenge page in an iframe. Google recommends that you render the challenge inside an iframe so you have full control over the final size on your page.

Information

If you host the challenge page within an iframe, ensure you configure it to allow cross-origin resources as instructed in Allow Google Payment Request API

You must redirect the cardholder to the google_spa.challenge_url URL returned in the response.

Iframe Size

If you use an iframe, refer to the google_spa.iframe object to determine the size and render the iframe that embeds Google's challenge_url. These values are decided by Google and you must comply with them when you display the challenge to the cardholder.

Possible iframe sizes are:

0 x 0
100% x 100%

To be informed of the outcome of the authentication, use the message event on the front end to listen to a window.postMessage method from the iframes.

For example, if the Google landing page executes the following script:


1window.parent.postMessage( 'SPA_AUTHENTICATION_SUCCEEDED' , MERCHANT_WEBSITE_ORIGIN);

The embedding page must add the following listener:


1window.addEventListener( "message" , (e)=>
2 {
3    if (msg.origin ==='MERCHANT_WEBSITE_ORIGIN' ) {
4        if (msg.data === 'SPA_AUTHENTICATION_SUCCEEDED' ) {
5        // close the iframe, do other specific action
6        }
7        if (msg.data === 'SPA_AUTHENTICATION_FAILED' ) {
8        // close the iframe, do other specific action
9        }
10        if (msg.data === 'SPA_AUTHENTICATION_CANCELLED' ) {
11        // close the iframe, do other specific action
12        }
13    }
14 });

After receiving the notification, call the Get session details endpoint setting the {id} query parameter using the id value you received in the sessions response to retrieve the updated details of the authentication. The ID is prefixed with sid_.

If you are using the full page redirect, you must ensure that you include the google_spa object in your request. This object must contain the continue_url, which serves as the redirection URL the cardholder is redirected to after completing the authentication step.

Do not use continue_url if you're using an iframe as it will not be loadable and you will risk a broken flow.


1{  
2    "source": {  
3        "type": "card",  
4        "number": "4895379980026585",  
5        "expiry_month": 7,  
6        "expiry_year": 2024,  
7        "scheme": "visa",  
8        "name": "Hannah Bret",  
9        "email": "[email protected]"  
10    },  
11    "processing_channel_id": "pc_h43ig6azpm7uxlqndurrz7pfbu",  
12    "preferred_experiences": ["google_spa", "3ds"],  
13    "amount": "100",  
14    "currency": "GBP",  
15    "completion": {  
16        "type": "non_hosted"  
17    },  
18    "google_spa":{  
19        "continue_url": "https://google.com"  
20    }  
21}

After completing the challenge flow, the session moves to a final state where you to choose to complete the session.

To access the eci, cryptogram, and google_spa.token fields required for authorization after a successful Google SPA authentication, retrieve the session details using a JWT token instead of the session secret. Using a JWT token safeguards these sensitive values from potential client-side exposure.

The authentication must be completed within 15 minutes of the request being submitted, otherwise the authentication expires.

After the Google SPA authentication is completed, you must call the Get session details endpoint to retrieve the required information.


1{
2  "id": "sid_uyf763hgstqena6ei5omawyxs4",
3  "transaction_id": "3c741b93-d949-4851-8751-21bc299690f2",
4  "amount": 10,
5  "currency": "GBP",
6  "authentication_type": "regular",
7  "authentication_category": "payment",
8  "status": "approved",
9  "status_reason": "rreq_status",
10  "approved": true,
11  "next_actions": [],
12  "challenged": true,
13  "cryptogram": "ADYBAJBXIwAANiQGEVcjmAdXIwA=",
14  "transaction_type": "goods_service",
15  "eci": "05",
16  "scheme": "visa",
17  "authentication_date": "2024-10-07T11:02:14.2766861Z",
18  "flow_type": "challenged",
19  "challenge_indicator": "no_preference",
20  "preferred_experiences": {
21    "3ds": {
22      "status": "unprocessed"
23    },
24    "google_spa": {
25      "status": "processed"
26    }
27  },
28  "experience": "google_spa",
29  "google_spa": {
30    "token": {
31      "number": "4485040371536584",
32      "expiry_month": 1,
33      "expiry_year": 30
34    }
35  },
36  "_links": {
37    "self": {
38      "href": "https://sessions.cko-qa.ckotech.co/sessions/sid_uyf763hgstqena6ei5omawyxs4"
39    }
40  }
41}

For the full API specification, see the API reference.

Field name	Description
`id` string	The unique identifier of the session.
`next_actions` array	Specifies what action to take to complete the session. Should be `complete`.
`status` string	The status of the session. Should be one of the following: `expired`, `approved`, `unavailable`, `declined`, `rejected`.
`preferred_experiences` object	Provides information about the list of preferred experiences passed in the sessions request and their status.
`preferred_experiences.3ds` object	Contains all information about 3DS experience at that stage of authentication.
`preferred_experiences.3ds.status` string	The status of 3DS experience.
`preferred_experiences.3ds.status_reason` string	The status reason in case of failure if authentication was processed using 3DS experience.
`preferred_experiences.google_spa` object	Contains all information about `google_spa` experience.
`preferred_experiences.google_spa.status` string	The status of `google_spa` experience.
`preferred_experiences.google_spa.status_reason` string	The status reason in case of failure if authentication was processed using `google_spa` experience.
`experience` string	The experience used to process the authentication. For example, `google_spa`.
`google_spa` object	Provides details related to the google SPA experience.
`google_spa.token` object	Details of the Device Primary Account Number (DPAN) token.
`google_spa.token.number` string	The Device Primary Account Number (DPAN) token.
`google_spa.token.expiry_month` integer	The expiry month of the Device Primary Account Number (DPAN) token.
`google_spa.token.expiry_year` integer	The expiry year of the Device Primary Account Number (DPAN) token.
`google_spa.initial_timeout` string	Indicates amount of time (in minutes) allowed for establishing initial connection to user's specific authentication session (as determined by `challengeURL` and `params`).
`google_spa.max_timeout` string	Indicates maximum amount of time (in minutes) allowed for completing all PSP-Google message exchanges for the current authentication session.

If the authentication status is approved, you can authorize the payment. If the authentication is unavailable due to technical issues, you can decide whether or not to proceed with the payment, based on your risk assessment.

If the google_spa authentication was unsuccessful after being challenged, you can retry using 3DS by re-sending the request with the preferred_experience array set to 3ds.

After a successful Google SPA authentication, Checkout.com returns a google_spa.token object which contains the DPAN card number and its expiry month and year.

You must use this token (DPAN) to process the payment authorization as you would with a network token payment.

If Google SPA is unavailable due to ineligibility or a technical issue, Checkout.com automatically falls back to 3DS, if it's included in your preferred experiences. This fallback is only possible if the session status is not challenged.

If Google SPA fails after the status is challenged, you can retry using 3DS. To do so, submit a new request and set the preferred_experience array to 3ds.

The following table shows the possible values of the status field:

Field name	Description
`pending`	Authentication has been requested and the session has been started.
`approved`	The payment has been successfully authenticated.
`unavailable`	Authentication experience unavailable because of ineligibility or technical issues.
`declined`	The authentication was not authenticated. The issuer declined the authentication.
`rejected`	The authentication was rejected. The issuer is rejecting the authentication and it should not be retried nor should authorization not be attempted.
`challenged`	The issuer requires that the cardholder be presented with a challenge.
`expired`	The authentication was not completed within 15 minutes.

The following table shows the possible values for the next_actions field.

These values indicate the next steps required to finalize the session.

Field name	Description
`action`	The action to be taken.
`description`	The description of the action.

Non-hosted standalone

Eligibility

Note

Allow Google Payment Request API

Payment authorization

Authenticate your requests

Access tokens

Session secret

Step 1: Request a session

Request example

Response example

Step 2: Get sessions details

Information

Response example

Step 3: Collect channel data

Request example

Response example

Key response fields

Step 4: Challenge

Information

Render the challenge

Iframe Size

Notification of outcome

Full Redirect mode

Request example

Challenge completed

Step 5: Get sessions details (Post Challenge)

Response example

Key fields

Google Token (DPAN)

Fallback and Retries

Session properties

Session status

Next actions