# Hosted standalone

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.

---

## Eligibility

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.

---

## Allow Google Payment Request API

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:

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

---

## Payment authorization

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.

---

## Authenticate your requests

### Access tokens

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.

### Session secret

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.

---

## Step 1: Request a session

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.

#### Request example

```json
{
  "source": {
    "type": "card",
    "number": "4485040371536584",
    "expiry_month": 1,
    "expiry_year": 2030
  },
  "amount": 100,
  "currency": "USD",
  "authentication_type": "regular",
  "authentication_category": "payment",
  "challenge_indicator": "no_preference",
  "reference": "ORD-5023-4E89",
  "transaction_type": "goods_service",
  "shipping_address": {
    "address_line1": "123 Anywhere St.",
    "address_line2": "Apt. 456",
    "city": "Anytown",
    "state": "AL",
    "zip": "123456",
    "country": "US"
  },
  "completion": {
    "type": "hosted",
    "success_url": "http://example.com/sessions/success",
    "failure_url": "https://example.com/payments/failure"
  },
  "preferred_experiences": ["google_spa", "3ds"]
}
```

#### Response example

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

```json
{
  "id": "sid_y3oqhf46pyzuxjbcn2giaqnb441",
  "transaction_id": "9aea641d-0549-4222-9ca9-d90b43a4f38c",
  "amount": 120,
  "currency": "USD",
  "authentication_type": "regular",
  "authentication_category": "payment",
  "status": "pending",
  "next_actions": [
    "redirect_cardholder"
  ],
  "protocol_version": "2.2.0",
  "reference": "ORD-5023-4E89",
  "preferred_experiences": {
    "3ds": {
      "status": "available"
    },
    "google_spa": {
      "status": "available"
    }
  },
  "_links": {
    "redirect": {
      "href": "http://3ds2.checkout.com/interceptor/sid_y3oqhf46pyzuxjbcn2giaqnb44"
    },
    "self": {
      "href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2giaqnb441"
    }
  }
}
```

#### Key fields

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

---

## Step 2: Redirect the customer

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.

---

## Step 3: Complete Challenge

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](#Allow_Google_Payment_Request_API)

---

## Step 4: Get session details

To retrieve the details of the authentication, call the [Get session details](https://api-reference.checkout.com/tag/Standalone/#operation/getSession) endpoint setting the `{id}` query parameter using the `id` value you received in the sessions response, prefixed with `sid_`.

### Response example

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

```json
{  
    "id": "sid_did5wxsbpsouredqq777scjnie",  
    "transaction_id": "5edb071a-7c41-489d-9070-87fff9092d41",  
    "amount": 100,  
    "currency": "GBP",  
    "authentication_type": "regular",  
    "authentication_category": "payment",  
    "status": "approved",  
    "status_reason": "rreq_status",  
    "approved": true,  
    "next_actions": [],  
    "challenged": true,  
    "cryptogram": "ADYBAJBXIwAANiQGEVcjmAdXIwA=",  
    "transaction_type": "goods_service",  
    "eci": "05",  
    "session_secret": "sek_/24zXia+6TaT9k9ZYhBqwFLINbDY5mtdB9vRwX68uiU=",  
    "scheme": "visa",  
    "authentication_date": "2024-09-17T09:59:56.4833830Z",  
    "flow_type": "challenged",  
    "challenge_indicator": "no_preference",  
    "preferred_experiences": {  
        "3ds": {  
            "status": "unprocessed"  
        },  
        "google_spa": {  
            "status": "processed"  
        }  
    },  
    "experience": "google_spa",  
    "google_spa": {  
        "token": {  
            "number": "4895379980026585",  
            "expiry_month": 1,  
            "expiry_year": 30  
        }  
    },  
    "_links": {  
        "self": {  
            "href": "https://sessions.cko-qa.ckotech.co/sessions/sid_did5wxsbpsouredqq777scjnie"  
        },  
        "success_url": {  
            "href": "https://google.com/"  
        },  
        "failure_url": {  
            "href": "https://google.com/"  
        }  
    }  
}
```
For the full API specification, see the [API reference](https://api-reference.checkout.com/).

### Key fields

| Field name | Description |
| --- | --- |
| `experience`<br>`string` | The experience used to process the authentication. For example, `google_spa` |
| `google_spa`<br>`object` | Provides details related to google spa experience |
| `google_spa.token`<br>`object` | Details of the Device Primary Account Number (DPAN) token. |
| `google_spa.token.number`<br>`string` | The Device Primary Account Number (DPAN) token. |
| `google_spa.token.expiry_month`<br>`integer` | The expiry month of the Device Primary Account Number (DPAN) token. |
| `google_spa.token.expiry_year`<br>`integer` | The expiry year of the Device Primary Account Number (DPAN) token. |
| `google_spa.initial_timeout`<br>`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`<br>`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.

### Session properties

#### Session status

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

#### Next actions

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