Hosted standalone

Last updated: April 2, 2025

Hosted authentication is the simplest solution for authenticating transactions leveraging 3D Secure (3DS) or Google SPA.

Start an authentication and then redirect the customer using the URL provided in the response. Checkout.com collets the necessary payment, device, and cardholder data and manages the rest of authentication.

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 if no other value is provided
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 front end, 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 authentication.


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    "state": "AL",
20    "zip": "123456",
21    "country": "US"
22  },
23  "completion": {
24    "type": "hosted",
25    "success_url": "http://example.com/sessions/success",
26    "failure_url": "https://example.com/payments/failure"
27  },
28  "preferred_experiences": ["google_spa", "3ds"]
29}

if you receive a 202 - Accepted response, your request was successful.


1{
2  "id": "sid_y3oqhf46pyzuxjbcn2giaqnb441",
3  "transaction_id": "9aea641d-0549-4222-9ca9-d90b43a4f38c",
4  "amount": 120,
5  "currency": "USD",
6  "authentication_type": "regular",
7  "authentication_category": "payment",
8  "status": "pending",
9  "next_actions": [
10    "redirect_cardholder"
11  ],
12  "protocol_version": "2.2.0",
13  "reference": "ORD-5023-4E89",
14  "preferred_experiences": {
15    "3ds": {
16      "status": "available"
17    },
18    "google_spa": {
19      "status": "available"
20    }
21  },
22  "_links": {
23    "redirect": {
24      "href": "http://3ds2.checkout.com/interceptor/sid_y3oqhf46pyzuxjbcn2giaqnb44"
25    },
26    "self": {
27      "href": "https://api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2giaqnb441"
28    }
29  }
30}

Field name	Description
`preferred_experiences` object	Provides information about the list of preferred experiences passed in the request and their status.
`preferred_experiences.3ds` object	This object contains information about the 3DS experience.
`preferred_experiences.3ds.status` string	The status of the 3DS experience.
`preferred_experiences.3ds.status_reason` string	The status reason in case of failure, if authentication was processed using 3DS.
`preferred_experiences.google_spa` object	This object contains information about the 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

The possible experience statuses are:

unavailable – The chosen authentication authentication experience could not be processed.
available – The experience is available for the authentication to be processed.
processed – The authentication was processed using the experience.
unprocessed – The authentication was not processed using the experience.

Redirect the customer to the _links.redirect_url you receive in the response.

Checkout.com then gathers the necessary device data and manage the challenge flow where applicable.

After completing the authentication, your customer is redirected to your success_url or failure_url.

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

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

If the request is successful, you receive a 200 - OK response, along with a response containing the details of the authentication:


1{  
2    "id": "sid_did5wxsbpsouredqq777scjnie",  
3    "transaction_id": "5edb071a-7c41-489d-9070-87fff9092d41",  
4    "amount": 100,  
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    "session_secret": "sek_/24zXia+6TaT9k9ZYhBqwFLINbDY5mtdB9vRwX68uiU=",  
17    "scheme": "visa",  
18    "authentication_date": "2024-09-17T09:59:56.4833830Z",  
19    "flow_type": "challenged",  
20    "challenge_indicator": "no_preference",  
21    "preferred_experiences": {  
22        "3ds": {  
23            "status": "unprocessed"  
24        },  
25        "google_spa": {  
26            "status": "processed"  
27        }  
28    },  
29    "experience": "google_spa",  
30    "google_spa": {  
31        "token": {  
32            "number": "4895379980026585",  
33            "expiry_month": 1,  
34            "expiry_year": 30  
35        }  
36    },  
37    "_links": {  
38        "self": {  
39            "href": "https://sessions.cko-qa.ckotech.co/sessions/sid_did5wxsbpsouredqq777scjnie"  
40        },  
41        "success_url": {  
42            "href": "https://google.com/"  
43        },  
44        "failure_url": {  
45            "href": "https://google.com/"  
46        }  
47    }  
48}

For the full API specification, see the API reference.

Field name	Description
`experience` string	The experience used to process the authentication. For example, `google_spa`
`google_spa` object	Provides details related to 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 current authentication session

Information

For the subsequent payment, you must use the Google DPAN token (google_spa.token.number) and process it as a token payment.

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

Status	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 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.

Action	Description
`redirect_cardholder`	Redirect the customer so we can handle all the other necessary actions (collect channel data, issuer fingerprint, and challenge) for you.
`complete`	The authentication is complete. You should now perform a GET sessions details to retrieve the details for the authentication.

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

Key fields

Step 2: Redirect the customer

Step 3: Complete Challenge

Information

Step 4: Get session details

Response example

Key fields

Information

Session properties

Session status

Next actions