# Authenticate payments

This guide shows you how to integrate [3D Secure (3DS)](https://www.checkout.com/docs/payments/authenticate-payments/3d-secure.md) into your payment flows.

> **Information**
>
> Checkout.com supports all versions of the 3DS protocol up to and including 2.2.0.

You can authenticate online payments using any of the following integration options:

- Integrated authentication
- Standalone Sessions authentication
- Third-party authentication

---

## Integrated authentication

With the integrated authentication solution, Checkout.com automatically routes the customer to 3DS authentication or [Google Secure Payment Authentication (SPA)](https://www.checkout.com/docs/payments/authenticate-payments/google-secure-payment-authentication.md), depending on which is most likely to result in a successful completion. Google SPA enables cardholders to complete biometric authentication directly from your domain, which enhances the user experience.

For the automatic routing to function, you must provide 3DS authentication data in all of your payment requests.

If the initial authentication experience fails or is declined by the customer, we automatically fall back to the alternative authentication experience to prevent a lost transaction.

When you submit a payment request with the `3ds.enabled` field set to `true`, we redirect the customer to a Checkout.com page to gather the data required for 3DS authentication. We automatically add the required fields to your payment request.

If you provide the device data required for 3DS authentication directly in the payment request, and the transaction is eligible for frictionless authentication, we skip the redirect and return the payment's final status in the response. If you use Flow, we collect this device data for you automatically. For more information, see [Skip the redirect for a frictionless authentication](#skip-the-redirect-for-a-frictionless-authentication).

If you host the payment page in an iframe, you must explicitly add payment permission to the iframe to allow payments to complete. Include the `allow="payment *"` attribute in all parent frames:

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

Follow these steps:

1. Create a card token.
2. Request a card token payment
3. Redirect your customer, or [skip the redirect](#skip-the-redirect-for-a-frictionless-authentication) if you provide device data and the transaction is eligible for frictionless authentication.
4. Verify the payment.

### Create a card token

To exchange the customer's card details for a card token, call the [Request a token](https://api-reference.checkout.com/tag/Tokens/#operation/requestAToken) endpoint.

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/tokens`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/tokens`

### Request example

```json
{
  "type": "applepay",
  "token_data": {
    "version": "EC_v1",
    "data": "t7GeajLB9skXB6QSWfEpPA4WPhDqB7ekdd+F7588arLzvebKp3P0TekUslSQ8nkuacUgLdks2IKyCm7U3OL/PEYLXE7w60VkQ8WE6FXs/cqHkwtSW9vkzZNDxSLDg9slgLYxAH2/iztdipPpyIYKl0Kb6Rn9rboF+lwgRxM1B3n84miApwF5Pxl8ZOOXGY6F+3DsDo7sMCUTaJK74DUJJcjIXrigtINWKW6RFa/4qmPEC/Y+syg04x7B99mbLQQzWFm7z6HfRmynPM9/GA0kbsqd/Kn5Mkqssfhn/m6LuNKsqEmbKi85FF6kip+F17LRawG48bF/lT8wj/QEuDY0G7t/ryOnGLtKteXmAf0oJnwkelIyfyj2KI8GChBuTJonGlXKr5klPE89/ycmkgDl+T6Ms7PhiNZpuGEE2QE=",
    "signature": "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",
    "header": {
      "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEX1ievoT8DRB8T5zGkhHZHeDr0oBmYEgsDSxyT0MD0IZ2Mpfjz2LdWq6LUwSH9EmxdPEzMunsZKWMyOr3K/zlsw==",
      "publicKeyHash": "tqYV+tmG9aMh+l/K6cicUnPqkb1gUiLjSTM9gEz6Nl0=",
      "transactionId": "3cee89679130a4b2617c76118a1c62fd400cd45b49dc0916d5b951b560cd17b4"
    }
  }
}
```

### Response example

```json
{
  "type": "applepay",
  "token": "tok_ymu4qlccztkedmd6b7c3hcf6ae",
  "expires_on": "2024-10-21T10:48:35Z",
  "expiry_month": 1,
  "expiry_year": 2025,
  "scheme": "VISA",
  "last4": "6222",
  "bin": "481891",
  "card_type": "DEBIT",
  "card_category": "CONSUMER",
  "issuer": "Test Bank",
  "issuer_country": "GB",
  "product_id": "F",
  "product_type": "CLASSIC"
}
```

The response returns the `token`, which you need for the payment request.

### Request a card token payment

Call the [Request a payment or payout](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout) endpoint, and set `source.type` to `token`.

To request 3DS authentication for the payment, set the `3ds.enabled` field in your request to `true`.

> **Information**
>
> You can automatically downgrade your payment to a non-3DS payment if there are any technical issues during the 3DS authentication process that would otherwise cause the payment to fail. Set the `attempt_n3d` field in the request to `true` and we automatically attempt to process the payment without 3DS authentication.

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/payments`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments`

#### Request example

```json
{
  "source": {
    "type": "token",
    "token": "tok_f6z4mnoububudpqnvhwa5ff27u"
  },
  "amount": 2000,
  "currency": "USD",
  "3ds": {
    "enabled": true
  },
  "success_url": "https://example.com/payments/success",
  "failure_url": "https://example.com/payments/failure"
}
```

#### Response example

```json
{
  "id": "pay_hehfmlkpykeupofyxf7nbr6yyy",
  "status": "Pending",
  "customer": {
    "id": "cus_u4a4zosnrw7ehhzr7jipbkdzo4"
  },
  "3ds": {
    "downgraded": false,
    "enrolled": "Y"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_hehfmlkpykeupofyxf7nbr6yyy"
    },
    "redirect": {
      "href": "https://{prefix}.api.sandbox.checkout.com/sessions-interceptor/sid_feixbit6us3utfedjulm6egnsu"
    }
  }
}
```

The response returns the URL to redirect your customer to in the `_links.redirect.href` field.

If the card is enrolled for 3DS or eligible for Google SPA, you receive a `202 - Accepted` response.

> **Information**
>
> Use [test cards](https://www.checkout.com/docs/developer-resources/testing/test-cards.md#3D_Secure_test_cards) in the sandbox environment to simulate 3DS and Google SPA authentication flows, and test transactions statuses.

### Skip the redirect for a frictionless authentication

If you provide device data in your payment request, and the transaction qualifies for a frictionless authentication, we can authenticate the payment without redirecting your customer. Instead, we return the payment's final status synchronously in the response.

To provide device data, include either of the following in your request:

- All of the following fields in the `risk.device` object:
  - `accept_header`
  - `color_depth`
  - `iframe_payment_allowed`
  - `ip_address`
  - `java_enabled`
  - `javascript_enabled`
  - `language`
  - `screen_height`
  - `screen_width`
  - `timezone`
  - `user_agent`
  - `user_agent_client_hint`
- The `risk.device_session_id` field.

> **Note**
>
> If any of the `risk.device` fields are missing, or the transaction doesn't qualify for a frictionless authentication, we redirect the customer. For more information, see [Redirect your customer](#Redirect_your_customer).

#### Request example

```json
{
  "amount": 2000,
  "capture": false,
  "currency": "USD",
  "payment_method": {
    "type": "card",
    "expiry_month": "12",
    "expiry_year": "2029",
    "number": "4556085951507152",
    "cvv": "123",
    "name": "John Smith",
    "stored": false,
    "store_for_future_use": true
  },
  "payment_type": "Regular",
  "authorization_type": "Final",
  "risk": {
    "device": {
      "user_agent": "user_agent_something",
      "timezone": "00",
      "java_enabled": false,
      "javascript_enabled": true,
      "color_depth": "16",
      "screen_height": "1080",
      "screen_width": "1920",
      "accept_header": "application/json"
    },
    "device_session_id": "dsid_ipsmclhxwq72phhr32iwfvrflm"
  },
  "merchant_initiated": false,
  "reference": "87ec01b5-7066-46b9-8b92-2d4b71",
  "3ds": {
    "enabled": true
  },
  "authentication": {
    "preferred_experiences": [
      "3ds"
    ]
  },
  "success_url": "https://example.com/?success",
  "failure_url": "https://example.com/?failure",
  "processing_channel_id": "pc_s73vxa6iqvvepafrsx5dbzy4ue",
  "processing": {
    "pan_preference": "fpan",
    "provision_network_token": false
  }
}
```

#### Response example

```json
{
  "id": "pay_ivureuydw74uzah5nla6jn7dgy",
  "action_id": "act_27jjyr42wkke7chivqyq4pcj4m",
  "amount": 2000,
  "currency": "USD",
  "approved": true,
  "status": "Authorized",
  "auth_code": "VMPV6O",
  "response_code": "10000",
  "response_summary": "Approved",
  "3ds": {
    "authentication_response": "Y",
    "cryptogram": "AAABAVIREQAAAAAAAAAAAAAAAAA=",
    "eci": "05",
    "xid": "7cf74c6e-4eed-43dc-b669-a0fb451a3969",
    "version": "2.2.0",
    "exemption": "none",
    "is_redirect": false
  },
  "risk": {
    "flagged": false,
    "score": 0
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/payments/pay_ivureuydw74uzah5nla6jn7dgy"
    },
    "actions": {
      "href": "https://{prefix}.api.checkout.com/payments/pay_ivureuydw74uzah5nla6jn7dgy/actions"
    },
    "capture": {
      "href": "https://{prefix}.api.checkout.com/payments/pay_ivureuydw74uzah5nla6jn7dgy/captures"
    },
    "void": {
      "href": "https://{prefix}.api.checkout.com/payments/pay_ivureuydw74uzah5nla6jn7dgy/voids"
    }
  }
}
```

The response's `3ds.is_redirect` field returns `false`, and the response doesn't include a `_links.redirect` link.

### Redirect your customer

Redirect the customer to the URL returned in the Request a payment response.

In a 3DS authentication experience, the customer may be prompted to verify their identity on a 3DS challenge screen. For example, using a password.

![3DS challenge screen](https://www.checkout.com/docs/Risk management/3ds2_challenge.png)

In a Google SPA authentication experience, the customer is prompted to verify their identity on their device using biometric authentication.

![Google SPA biometric authentication screen](https://www.checkout.com/docs/Risk management/google-spa-authentication.png)

If the customer successfully completes the 3DS challenge or Google SPA biometric authentication, they are redirected back to your site.

The success URL contains a `cko-session-id` query string. For example:

`http://example.com/success?cko-session-id=sid_ubfj2q76miwundwlk72vxt2i7q`

### Verify the payment

If you've [configured your webhook server](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/configure-your-webhook-server.md), you can check the payment's status using the following webhooks:

- Successful payment – You receive a [Payment approved](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/payment_approved.md) webhook.
- Unsuccessful payment – You receive a [Payment declined](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/payment_declined.md) webhook.

Alternatively, you can check if the payment was authenticated and authorized by calling the [Get payment details](https://api-reference.checkout.com/tag/Payments/#operation/getPaymentDetails) endpoint.
Provide the `cko-session-id` query string from the Redirect your customer step as the `{id}` path parameter.

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`GET` `https://{prefix}.api.checkout.com/payments/{id}`

**Sandbox**

`GET` `https://{prefix}.api.sandbox.checkout.com/payments/{id}`

#### Response example

**Pending**

```json
{
  "id": "pay_5o3zluz2oh2u7gbonujy33765e",
  "requested_on": "2024-01-23T14:45:55.1258Z",
  "source": {
    "type": "card",
    "expiry_month": 12,
    "expiry_year": 2029,
    "name": "Jia Tsang",
    "scheme": "Visa",
    "last4": "6584",
    "fingerprint": "B16D9C2EF0C861A8825C9BD59CCE9171D84EBC45E89CC792B5D1D2D0DDE3DAB7",
    "bin": "448504",
    "card_type": "CREDIT",
    "card_category": "COMMERCIAL",
    "issuer": "GE CAPITAL FINANCIAL, INC.",
    "issuer_country": "US"
  },
  "amount": 100,
  "currency": "EUR",
  "payment_type": "Regular",
  "reference": "a19c5c40-a5be-4307-a14c-d8ebd9ef995a",
  "status": "Pending",
  "3ds": {
    "downgraded": false,
    "enrolled": "Y",
    "version": "2.2.0"
  },
  "risk": {
    "flagged": false,
    "score": 0
  },
  "customer": {
    "id": "cus_gd2oabkekwru3fckbb2b5xdqbe",
    "email": "jia.tsang@example.com",
    "name": "Jia Tsang"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/gateway/payments/pay_5o3zluz2oh2u7gbonujy33765e"
    },
    "actions": {
      "href": "https://{prefix}.api.checkout.com/gateway/payments/pay_5o3zluz2oh2u7gbonujy33765e/actions"
    },
    "redirect": {
      "href": "https://{prefix}.api.checkout.com/sessions-interceptor/sid_6jih2nadzfvevi655gysadzkyq"
    }
  }
}
```

**Approved**

```json
{
  "id": "pay_5o3zluz2oh2u7gbonujy33765e",
  "requested_on": "2024-01-23T14:45:55.1258Z",
  "source": {
    "id": "src_aqqoqgffnbqehoqekvttwfrr3a",
    "type": "card",
    "expiry_month": 12,
    "expiry_year": 2029,
    "name": "Jia Tsang",
    "scheme": "Visa",
    "last4": "6584",
    "fingerprint": "B16D9C2EF0C861A8825C9BD59CCE9171D84EBC45E89CC792B5D1D2D0DDE3DAB7",
    "bin": "448504",
    "card_type": "CREDIT",
    "card_category": "COMMERCIAL",
    "issuer": "GE CAPITAL FINANCIAL, INC.",
    "issuer_country": "US",
    "product_type": "PURCHASING",
    "avs_check": "G",
    "cvv_check": "Y",
    "payment_account_reference": "V001345447391180899"
  },
  "expires_on": "2024-01-24T14:46:26.6329548Z",
  "amount": 100,
  "currency": "EUR",
  "payment_type": "Regular",
  "reference": "a19c5c40-a5be-4307-a14c-d8ebd9ef995a",
  "status": "Authorized",
  "approved": true,
  "3ds": {
    "downgraded": false,
    "enrolled": "Y",
    "authentication_response": "Y",
    "cryptogram": "AAABAVIREQAAAAAAAAAAAAAAAAA=",
    "xid": "347d50f2-c903-4a6a-a3dd-e9b1200f2ac4",
    "eci": "05",
    "version": "2.2.0",
    "exemption": "none",
    "challenged": false,
    "exemption_applied": "none"
  },
  "balances": {
    "total_authorized": 100,
    "total_voided": 0,
    "available_to_void": 100,
    "total_captured": 0,
    "available_to_capture": 100,
    "total_refunded": 0,
    "available_to_refund": 0
  },
  "risk": {
    "flagged": false,
    "score": 0
  },
  "customer": {
    "id": "cus_gd2oabkekwru3fckbb2b5xdqbe",
    "email": "jia.tsang@example.com",
    "name": "Jia Tsang"
  },
  "processing": {
    "acquirer_transaction_id": "226009856104463057233",
    "retrieval_reference_number": "049179801690",
    "merchant_category_code": "0742",
    "scheme_merchant_id": "502177",
    "scheme": "VISA",
    "partner_response_code": "00",
    "acquirer_name": "Checkout Visa",
    "acquirer_country_code": "GB",
    "aft": false,
    "pan_type_processed": "fpan",
    "cko_network_token_available": false
  },
  "eci": "05",
  "scheme_id": "661856082822182",
  "actions": [
    {
      "id": "act_wl5dv2xperdu5canyu2jz72mom",
      "type": "Authorization",
      "response_code": "10000",
      "response_summary": "Approved"
    }
  ],
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/gateway/payments/pay_5o3zluz2oh2u7gbonujy33765e"
    },
    "actions": {
      "href": "https://{prefix}.api.checkout.com/gateway/payments/pay_5o3zluz2oh2u7gbonujy33765e/actions"
    },
    "capture": {
      "href": "https://{prefix}.api.checkout.com/gateway/payments/pay_5o3zluz2oh2u7gbonujy33765e/captures"
    },
    "void": {
      "href": "https://{prefix}.api.checkout.com/gateway/payments/pay_5o3zluz2oh2u7gbonujy33765e/voids"
    }
  }
}
```

**Declined**

```json
{
  "id": "pay_ggiqdmmp7m6ehl5rcjxzw46hgq",
  "requested_on": "2024-01-23T14:49:25.2151969Z",
  "source": {
    "id": "src_h2xxsn5unfzedlrbmxnh3s7n2m",
    "type": "card",
    "expiry_month": 12,
    "expiry_year": 2029,
    "name": "Jia Tsang",
    "scheme": "Visa",
    "last4": "7863",
    "fingerprint": "3D91433E7E3218ED2447E8EA0E8CDEA03085786D0DE7746EB6EA4E513C684CD6",
    "bin": "453962",
    "card_type": "DEBIT",
    "card_category": "CONSUMER",
    "issuer": "BANC INTERNACIONAL DANDORRA, S.A.",
    "issuer_country": "AD",
    "product_type": "ELECTRON"
  },
  "amount": 100,
  "currency": "EUR",
  "payment_type": "Regular",
  "reference": "a19c5c40-a5be-4307-a14c-d8ebd9ef995a",
  "status": "Declined",
  "approved": false,
  "3ds": {
    "downgraded": false,
    "enrolled": "Y",
    "authentication_response": "N",
    "authentication_status_reason": "01",
    "eci": "07",
    "version": "2.2.0"
  },
  "risk": {
    "flagged": false,
    "score": 0
  },
  "customer": {
    "id": "cus_gd2oabkekwru3fckbb2b5xdqbe",
    "email": "jia.tsang@example.com",
    "name": "Jia Tsang"
  },
  "actions": [
    {
      "id": "act_7dkwh4uflaeuvhdjwrnhnpc7c4",
      "type": "Authorization",
      "response_code": "20151",
      "response_summary": "Cardholder failed 3D-Secure authentication"
    }
  ],
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/gateway/payments/pay_ggiqdmmp7m6ehl5rcjxzw46hgq"
    },
    "actions": {
      "href": "https://{prefix}.api.checkout.com/gateway/payments/pay_ggiqdmmp7m6ehl5rcjxzw46hgq/actions"
    }
  }
}
```

The result of the 3DS authentication is returned in the `3ds.authentication_response` field. This can be one of:

- `Y` – The cardholder was successfully authenticated.
- `A` – The authentication was processed by a stand-in service, and is classed as successful.
- `N` – The authentication failed.
- `U` – The authentication could not be completed due to technical or other problems.

The result of the authorization is returned in the `approved` boolean. This can be one of:
- `true` – The payment was successfully authorized.
- `false` – The payment was not authorized. The card may be invalid, expired, or have an insufficient balance.

You receive separate [Electronic Commerce Indicator (ECI) values](https://www.checkout.com/docs/developer-resources/codes/eci-values.md) for the authorization and authentication in the response, which indicate the transaction's security level and liability shift:

- Authorization – The `eci` field represents the final ECI security level received from the issuer to authorize the payment.
- Authentication – The `3ds.eci` field represents the final ECI security level received from the issuer to authenticate the payment.

> **Information**
>
> To retrieve a summary of all actions performed during a payment's lifecycle, call the [Get payment actions](https://api-reference.checkout.com/tag/Payments/#operation/getPaymentActions) endpoint.

### Successful non-3DS authorization request

![Diagram of successful non-3DS authorization request flow](https://www.checkout.com/docs/Risk management/Non-3DS-authorization.png)

If you make a payment request without the `3ds` object, or with `"3ds.enabled": false`, and the issuer does not require 3DS authorization for the transaction, the payment completes successfully.

### Non-3DS authorization request flow with soft decline

![Diagram of non-3DS authorization flow with soft decline](https://www.checkout.com/docs/Risk management/Non-3DS-authorization-with-soft-decline.png)

If you make a payment request without the `3ds` object, or with `"3ds.enabled": false`, and the issuer does require 3DS authorization for the transaction, you receive soft decline response code `20154`. You must re-request the payment with 3DS.

### Handle non-enrolled cards

If the customer's card is not enrolled for any version of 3DS, you can set the `attempt_n3d` field to `true` to downgrade the transaction to non-3DS. This means that if the customer's bank does not support 3DS, we automatically attempt to process the payment without 3DS authentication instead.

> **Note**
>
> If you downgrade the payment to non-3DS, liability shift no longer applies. This means you're not be protected against potentially fraudulent payments or chargebacks.

#### Request example

```json
{
  "source": {
    "type": "token",
    "token": "tok_vtvlbgpyoaaubmldynpm32bali"
  },
  "amount": 2000,
  "currency": "USD",
  "3ds": {
    "enabled": true,
    "attempt_n3d": true
  }
}
```

---

## Standalone Sessions authentication

[Standalone Sessions authentication](https://www.checkout.com/docs/risk-management/3d-secure/sessions.md) enables you to authenticate online transactions with the EMV 3DS protocol and helps you fulfil Strong Customer Authentication (SCA) requirements.

You can authorize payments using the identifier returned in the API response.

This simplified integration reduces the maintenance effort caused by regular 3DS protocol updates. It also ensures you do not need to handle any differences between local and global scheme requirements to perform a successful authorization.

Payments requested using this integration display as a single payment transaction line in your Dashboard.

If you want to authorize payments using fields in the `3ds` object (such as `eci`, `cryptogram`, `xid`, `version`), you can do so using the authentication data from a third-party provider. You can also use Standalone Sessions as a third-party provider for authorizing payments.

Call the [Request a session](https://api-reference.checkout.com/tag/Standalone/#operation/createSession) endpoint.

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/sessions`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/sessions`

### Request example

```json
{
  "source": {
    "type": "card",
    "scheme": "amex",
    "number": "4242424242424242",
    "expiry_month": 12,
    "expiry_year": 2077
  },
  "amount": 257,
  "currency": "USD",
  "3ds": {
    "enabled": true,
    "authentication_id": "sid_y3oqhf46pyzuxjbcn2giaqnb441"
  }
}
```

### Response example

```json
{
  "id": "pay_7a4355cden2upo2pkve6sxzzwm",
  "action_id": "act_rkzwx7sagtyuxnqnu3hbyld2ay",
  "amount": 100,
  "currency": "GBP",
  "approved": true,
  "status": "Authorized",
  "auth_code": "124203",
  "response_code": "10000",
  "response_summary": "Approved",
  "balances": {
    "total_authorized": 100,
    "total_voided": 0,
    "available_to_void": 100,
    "total_captured": 0,
    "available_to_capture": 100,
    "total_refunded": 0,
    "available_to_refund": 0
  },
  "risk": {
    "flagged": false
  },
  "source": {
    "id": "src_lflzuabkdlkevaopjpk27ex3w4",
    "type": "card",
    "expiry_month": 12,
    "expiry_year": 2023,
    "scheme": "Mastercard",
    "last4": "3276",
    "fingerprint": "CF79B91401CB4BF771BD423DBE275C2D85C39728874D15528B06F75D4B63C7C6",
    "bin": "539704",
    "card_type": "CREDIT",
    "card_category": "CONSUMER",
    "issuer": "Test Bank",
    "issuer_country": "US",
    "product_id": "MCG",
    "product_type": "Gold MasterCard(r) Card",
    "avs_check": "S",
    "cvv_check": "Y",
    "payment_account_reference": ""
  },
  "customer": {
    "id": "cus_xoar4xyvwbpeph2m2besbp52rq",
    "email": "john.smith@example.com",
    "name": "John Smith"
  },
  "processed_on": "2022-08-02T14:48:34.371324Z",
  "reference": "Reference",
  "scheme_id": "435166469706885",
  "processing": {
    "acquirer_transaction_id": "067757716527430582022",
    "retrieval_reference_number": "456111356278"
  },
  "expires_on": "2022-09-01T14:48:34.371324Z",
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_7a4355cden2upo2pkve6sxzzwm"
    },
    "actions": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_7a4355cden2upo2pkve6sxzzwm/actions"
    },
    "capture": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_7a4355cden2upo2pkve6sxzzwm/captures"
    },
    "void": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_7a4355cden2upo2pkve6sxzzwm/voids"
    }
  }
}
```

If the `approved` field returns:

- `true` – The authorization was successful.
- `false` – The authorization was unsuccessful. The card may be invalid, expired, have insufficient funds.

If you receive a `422 Unprocessable entity` response, the authentication was not successfully completed.
For more information, see the `error_codes` object.

---

## Third-party authentication

Authenticate a payment using a third-party provider and authorize it with Checkout.com.

Call the [Request a payment or payout](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout) endpoint.

In the request body:

| Parameter | Description |
| --- | --- |
| `3ds`<br><br>`required`<br>`object` | Information required for 3D Secure payments. |
| `3ds.challenge_indicator`<br><br>`optional`<br>`string` | Indicates your preference for whether or not a 3DS challenge should be performed. The customer’s bank has the final say on whether the customer is challenged. If `3ds.exemption` and `3ds.challenge_indicator` are provided, then `3ds.exemption` overrides `3ds.challenge_indicator`.<br><br>For more information about exemptions, see [SCA compliance](https://www.checkout.com/docs/business-operations/ensure-regulatory-compliance/sca-compliance.md#SCA_exemptions). |
| `3ds.cryptogram`<br><br>`required`<br>`string` | Base-64 cryptographic identifier used by card schemes to validate the token verification result. Required unless the `previous_payment_id` is specified.<br><br>For more information, see [Pay with stored card details](https://www.checkout.com/docs/payments/accept-payments/pay-with-stored-card-details.md). |
| `3ds.eci`<br><br>`required`<br>`string` | The Electronic Commerce Indicator security level associated with the token. Required unless the `previous_payment_id` is specified. For 3D Secure payments the ECI must be provided in the `3ds` payment field.<br><br>For more information, see [Pay with stored card details](https://www.checkout.com/docs/payments/accept-payments/pay-with-stored-card-details.md). |
| `3ds.enabled`<br><br>`required`<br>`boolean` | Whether to process this payment as a 3D Secure. Set this to `true`. |
| `3ds.exemption`<br><br>`optional`<br>`string` | Requests an SCA exemption for the transaction. The customer’s bank has the final say on whether or not it applies. If the requested `3ds.exemption` is not supported or enabled, `3ds.challenge_indicator` is used as a fallback.<br><br>For more information about exemptions, see [SCA compliance](https://www.checkout.com/docs/business-operations/ensure-regulatory-compliance/sca-compliance.md#SCA_exemptions). |
| `3ds.version`<br><br>`required`<br>`string` | Indicates the version of 3D Secure used for authentication. Defaults to `1.0.2` if not provided. |
| `3ds.xid`<br><br>`required` (for Mastercard and American Express requests)<br>`optional` (for Visa requests)<br>`string` | The 3D Secure transaction identifier. In 3DS with Mastercard, the value is the directory server transaction ID. |

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/payments`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments`

#### Request example

```json
{
  "source": {
    "type": "card",
    "number": "5436031030606378",
    "expiry_month": 12,
    "expiry_year": 2025
  },
  "amount": 257,
  "currency": "USD",
  "3ds": {
    "enabled": true,
    "eci": "06",
    "cryptogram": "AgAAAAAAAIR8CQrXcIhbQAAAAAA=",
    "xid": "79f6205c-ff5c-4a4c-8fca-90f67f3a6470",
    "version": "2.0.1"
  }
}
```

### Response example

If the `approved` field returns:

- `true` – The authorization was successful.
- `false` – The authorization was unsuccessful. The card may be invalid, expired, have insufficient funds.

If you receive a `202` response, the payment requires a redirect.

> **Information**
>
> If the card scheme provided us with an `eci` value, it is returned in the response. The value indicates the security level that the card scheme decided to authorize the payment with.

---

## Related topics

- [Google Secure Payment Authentication](https://www.checkout.com/docs/payments/authenticate-payments/google-secure-payment-authentication.md): Enable Google Secure Payment Authentication (SPA) to allow cardholders to complete biometric authentication directly from the merchant domain.
- [3D Secure](https://www.checkout.com/docs/payments/authenticate-payments/3d-secure.md): Verify your customers' card payments with the new authentication standard.
- [Verify a card](https://www.checkout.com/docs/payments/authenticate-payments/verify-a-card.md): Accept and verify a cardholder's payment details without billing them.
- [Flagged payments](https://www.checkout.com/docs/payments/authenticate-payments/flagged-payments.md): Identify and follow up on suspicious transactions.
- [Manage SCA retries](https://www.checkout.com/docs/payments/authenticate-payments/manage-sca-retries.md): Optimize authorization acceptance rates using automated SCA soft decline retries.
- [Scheme passkeys](https://www.checkout.com/docs/payments/authenticate-payments/scheme-passkeys.md): Enable scheme passkeys to let cardholders verify payments with biometrics instead of a one-time password or 3D Secure challenge.