---
title: "Create a 3DS Session"
method: POST
path: "/payments/3ds-sessions"
tags: ["Payments", "3D Secure"]
---

# Create a 3DS Session

`POST /payments/3ds-sessions`

## Request

- Base URL: `https://api.evervault.com`
- URL: `https://api.evervault.com/payments/3ds-sessions`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/evervault/apis/evervault-api/docs/payments/3ds-sessions/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a 3DS Session to initiate the 3DS Authentication process. The session ID must then be passed to our client-side SDK to complete the authentication process. [Learn more](/sdks/javascript#ui.threedsecure())

## Request body

- object
  - `merchant` union, required: The merchant details. Either an inline merchant object or the unique identifier of a Merchant created with the [Merchants API](/api#merchants).
    - object: An inline merchant object.
      - `name` string, required: The name of the merchant.
      - `website` string, required: The website of the merchant.
      - `categoryCode` string, required: The category code of the merchant.
      - `country` string, iso-3166-1-alpha-2, required: The country code of the merchant.
    - string: The unique identifier of a Merchant created with the [Merchants API](/api#merchants).
  - `card` union, required: The card details. Either an inline card object or the unique identifier of a Card registered for [Card Account Updates](/api#card-account-updates).
    - object: An inline card object.
      - `number` string, required: The card number. Needs to be an Evervault-encrypted card number or a plaintext card number.
      - `expiry` CardExpiry, required: The card expiry date.
        - `month` string, required: The card expiry month, in MM format (e.g. 12 for December)
        - `year` string, required: The card expiry year, in YY format (e.g. 29 for 2029)
    - string: The unique identifier of a Card registered for [Card Account Updates](/api#card-account-updates).
  - `acquirer` union: The acquirer details to use for the 3DS session. Either an inline acquirer object or the unique identifier of an acquirer created with the [Acquirers API](/api#acquirers). If omitted, Evervault resolves the default acquirer configuration for the card's network.
    - Acquirer: The acquirer of the payment.
      - `bin` string, required: The Bank Identification Number (BIN) of the acquirer. Must be 6 to 11 digits.
      - `merchantIdentifier` string, required: The merchant identifier assigned by the acquirer.
      - `country` string, iso-3166-1-alpha-2, required: The country code of the acquirer
    - string: The unique identifier of an acquirer created with the [Acquirers API](/api#acquirers).
  - `customer` object: The details of the customer who initiated the transaction.
    - `name` string: The name of the customer.
    - `phone` object[]: The phone number of the customer.
      - `type` 'mobile' | 'home' | 'work', required: The type of phone number.
      - `countryCode` string, required: The numerical country calling code of the phone number.
      - `number` string, required: The phone number of the customer.
    - `email` string, email: The email address of the customer.
    - `shipping` object: The shipping details of the customer.
      - `address` Address
        - `line1` string, required: The first line of the address.
        - `line2` string: The second line of the address.
        - `city` string, required: The city where the address is located.
        - `state` string, iso-3166-2-subdivision: The state or province code. Required when `country` is `us`, `ca`, or `au`.
        - `postalCode` string, required: The postal code of the address.
        - `country` string, iso-3166-1-alpha-2, required: The country where the address is located.
    - `billing` object: The billing details of the customer.
      - `address` Address
        - `line1` string, required: The first line of the address.
        - `line2` string: The second line of the address.
        - `city` string, required: The city where the address is located.
        - `state` string, iso-3166-2-subdivision: The state or province code. Required when `country` is `us`, `ca`, or `au`.
        - `postalCode` string, required: The postal code of the address.
        - `country` string, iso-3166-1-alpha-2, required: The country where the address is located.
      - `taxIdentifier` string: The tax identifier of the cardholder.
    - `deviceId` string: A unique identifier for the cardholder's device, generated by you. Must not contain whitespace. Required to qualify for [Visa's Digital Commerce Authentication Program](/cards/3d-secure#visa-data-only-authentication).
    - `clientIp` string: The IP address of the cardholder's device, as either IPv4 or IPv6. Required to qualify for [Visa's Digital Commerce Authentication Program](/cards/3d-secure#visa-data-only-authentication).
  - `payment` union: The payment details of the 3D Secure Authentication. This field is mandatory for transactions involving payment authentications but not required for non-payment authentications.
    - object: A payment that is made in a single transaction.
      - `type` 'one-off', required: The value `one-off`.
      - `amount` integer, required: The amount of the payment in the smallest currency unit (e.g. cents).
      - `currency` string, iso-4217-alphabetic, required: The currency of the payment.
    - object: A repeating payment for paying a total amount in multiple installments.
      - `type` 'installment', required: The value `installment`.
      - `amount` integer, required: The amount of the payment in the smallest currency unit (e.g. cents).
      - `currency` string, iso-4217-alphabetic, required: The currency of the payment.
      - `installments` integer, required: The number of installments.
      - `frequency` 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'annually', required: Indicates the minimum time between authorizations.
      - `expiry` integer: The epoch time in seconds when the installment expires. Maximum value is 4102394400 (equivalent to 2099-12-31).
    - object: A repeating payment with a regular interval.
      - `type` 'recurring', required: The value `recurring`.
      - `amount` integer, required: The amount of the payment in the smallest currency unit (e.g. cents).
      - `currency` string, iso-4217-alphabetic, required: The currency of the payment.
      - `frequency` 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'annually', required: Indicates the minimum time between authorizations.
      - `expiry` integer, required: The epoch time in seconds when the recurring payment expires. Maximum value is 4102394400 (equivalent to 2099-12-31).
  - `preferredVersions` string[]: A prioritized list of preferred 3D Secure versions. If the first version is not supported, the next version in the list is attempted. If no preferred version is provided, the most optimal version is selected. If none of the specified versions are supported by the issuer, the session fails.
  - `challenge` ThreeDSChallenge: Details about the 3DS challenge.
    - `preference` 'no-preference' | 'challenge-requested' | 'challenge-mandated' | 'no-challenge-requested', required: The 3DS challenge preference.
    - `reason` 'null' | 'data-sharing' | 'low-value' | 'low-risk' | 'secure-corporate-payment' | 'authentication-already-performed', nullable: The reason for not requesting a challenge. This value should only be present when the preference is `no-challenge-requested`.
  - `initiator` union: Details about the transaction initiation process.
    - object
      - `type` 'customer': The value `customer`.
    - object
      - `type` 'merchant': The value `merchant`.
      - `reason` 'recurring' | 'installment' | 'mail-order' | 'telephone-order' | 'add-card' | 'maintain-card' | 'other-payment' | 'account-verification' | 'split-shipment' | 'delayed-shipment': The reason for the transaction to be initiated by the merchant. This field is mandatory when the `type` is `merchant`.
      - `initialSession` string: The ID of the initial session. This can either be an Evervault 3DS Session ID or a `threeDSServer.transactionIdentifier`. This field should be provided if the merchant has previously authenticated the cardholder using 3DS. The API does not currently enforce this requirement, but it is recommended to always provide this field. In some cases Authentications will error if this field is not populated. If the initial session's `status` isn't `success`, the request fails with a `400` `invalid-request` error.
  - `externalCustomerReference` string: Your own identifier for this 3DS Session, such as an order or payment ID. It's stored on the session and returned with it, but isn't sent to the card network.

## Response `201`

Returns a 3DS Session object.

- ThreeDSSession: The 3D Secure API can be used in combination with our [Client-Side SDK's](/sdks/javascript#uithreedsecure) to authenticate cardholders using 3D Secure. This API allows you to create, retrieve and update 3D Secure sessions.
  - `id` string, required: A unique identifier assigned to each 3DS Authentication.
  - `card` object, required
    - `lastFour` string, required: The last four digits of the card number.
    - `expiry` CardExpiry, required: The card expiry date.
      - `month` string, required: The card expiry month, in MM format (e.g. 12 for December)
      - `year` string, required: The card expiry year, in YY format (e.g. 29 for 2029)
    - `brand` string, required: The card brand.
    - `funding` string, required: The card funding type.
    - `segment` string, required: The card segment.
    - `issuer` string: The name of the card issuer.
    - `country` string, iso-3166-1-alpha-2, required: The country code of the card.
    - `currency` string, required: The currency code of the card. (ISO 4217 three-letter code)
  - `acquirer` Acquirer, required: The acquirer of the payment.
    - `bin` string, required: The Bank Identification Number (BIN) of the acquirer. Must be 6 to 11 digits.
    - `merchantIdentifier` string, required: The merchant identifier assigned by the acquirer.
    - `country` string, iso-3166-1-alpha-2, required: The country code of the acquirer
  - `merchant` object, required: The merchant details.
    - `name` string, required: The name of the merchant.
    - `website` string, required: The website of the merchant.
    - `categoryCode` string, required: The category code of the merchant.
    - `country` string, iso-3166-1-alpha-2, required: The country code of the merchant.
  - `payment` union: The payment details of the 3D Secure Authentication.
    - object: A repeating payment for paying a total amount in multiple installments.
      - `type` 'installment', required: The value `installment`.
      - `amount` integer, required: The amount of the payment in the smallest currency unit (e.g. cents).
      - `currency` string, iso-4217-alphabetic, required: The currency of the payment.
      - `installments` integer, required: The number of installments.
      - `frequency` 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'annually', required: Indicates the minimum time between authorizations.
      - `expiry` integer: The epoch time in seconds when the installment expires. Maximum value is 4102394400 (equivalent to 2099-12-31).
    - object: A payment that is made in a single transaction.
      - `type` 'one-off', required: The value `one-off`.
      - `amount` integer, required: The amount of the payment in the smallest currency unit (e.g. cents).
      - `currency` string, iso-4217-alphabetic, required: The currency of the payment.
    - object: A repeating payment with a regular interval.
      - `type` 'recurring', required: The value `recurring`.
      - `amount` integer, required: The amount of the payment in the smallest currency unit (e.g. cents).
      - `currency` string, iso-4217-alphabetic, required: The currency of the payment.
      - `frequency` 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'annually', required: Indicates the minimum time between authorizations.
      - `expiry` integer, required: The epoch time in seconds when the recurring payment expires. Maximum value is 4102394400 (equivalent to 2099-12-31).
  - `challenge` ThreeDSChallenge: Details about the 3DS challenge.
    - `preference` 'no-preference' | 'challenge-requested' | 'challenge-mandated' | 'no-challenge-requested', required: The 3DS challenge preference.
    - `reason` 'null' | 'data-sharing' | 'low-value' | 'low-risk' | 'secure-corporate-payment' | 'authentication-already-performed', nullable: The reason for not requesting a challenge. This value should only be present when the preference is `no-challenge-requested`.
  - `initiator` union: Details about the transaction initiation process.
    - object
      - `type` 'customer': The value `customer`.
    - object
      - `type` 'merchant': The value `merchant`.
      - `reason` 'recurring' | 'installment' | 'mail-order' | 'telephone-order' | 'add-card' | 'maintain-card' | 'other-payment' | 'account-verification' | 'split-shipment' | 'delayed-shipment': The reason for the transaction to be initiated by the merchant. This field is mandatory when the `type` is `merchant`.
      - `initialSession` string: The ID of the initial session. This can either be an Evervault 3DS Session ID or a `threeDSServer.transactionIdentifier`. This field should be provided if the merchant has previously authenticated the cardholder using 3DS. The API does not currently enforce this requirement, but it is recommended to always provide this field. In some cases Authentications will error if this field is not populated. If the initial session's `status` isn't `success`, the request fails with a `400` `invalid-request` error.
  - `accessControlServer` ThreeDSAccessControlServer: Details about the Access Control Server involved in the 3DS transaction.
    - `transactionIdentifier` string, required: The Access Control Server's transaction identifier.
    - `referenceNumber` string, required: The Access Control Server's reference number assigned by EMVCo.
    - `operatorIdentifier` string, nullable: The identifier of the Access Control Server's operator, when the ACS provides it.
  - `directoryServer` ThreeDSDirectoryServer: Details about the Directory Server involved in the 3DS transaction.
    - `transactionIdentifier` string, required: The Directory Server's transaction identifier.
    - `referenceNumber` string, required: The Directory Server's reference number assigned by EMVCo.
    - `network` 'visa' | 'mastercard' | 'american-express' | 'discover' | 'jcb' | 'unionpay' | 'rupay', required: The network of the Directory Server.
  - `threeDSServer` object: Details about the 3DS Server involved in the 3DS transaction.
    - `transactionIdentifier` string: The unique identifier for the 3DS transaction.
  - `version` '2.2.0', required: The 3D Secure version used to authenticate the session.
  - `status` 'action-required' | 'success' | 'failure', required: The status of the 3DS Authentication.
  - `authentication` object: The details of the 3DS Authentication. This field is present when the status is `success`.
    - `flow` 'frictionless' | 'challenge' | 'attempt', required: The authentication flow.
    - `methods` string[]: The authentication method(s). This field is only present when the flow is `challenge`.
  - `nextAction` object: The next action required to complete the 3DS Authentication.
    - `type` 'use-sdk', required: The next action required to progress the 3DS Authentication. If the type is `use-sdk` you must use our [Client-Side SDK](/sdks/javascript#ui.threedsecure()) to complete the 3DS Authentication.
  - `cryptogram` string: The 3DS cryptogram (also called Authentication Value). This value must be retrieved and provided to the payment gateway when processing the payment. This value is only present when the status is `success` and is retained for one hour.
  - `eci` object: The details of the Electronic Commerce Indicator. This value is only present when the status is `success`.
    - `value` '00' | '01' | '02' | '04' | '05' | '06' | '07': The value of the ECI. Below are descriptions of each of the possible values: Mastercard: - `00`: Not authenticated. No liability shift. - `01`: Attempted (Stand-in) authentication. Liability shift applies. - `02`: Successful authentication. Liability shift applies. - `04`: Data only authentication. No liability shift. - `06`: Transaction is exempt from SCA. No liability shift. - `07`: Recurring transaction authenticated. Liability shift applies for initial transaction only. Visa, American Express, Discover, Diners Club, JCB: - `05`: Successful authentication. Liability shift applies. - `06`: Attempted (Stand-in) authentication. Liability shift applies. - `07`: Not authenticated. No liability shift.
    - `descriptor` 'fully-authenticated' | 'attempted' | 'not-authenticated': The descriptor of the ECI. This value must be retrieved and provided to the payment gateway when processing the payment.
    - `liabilityShift` boolean: A boolean value indicating whether the liability shift has occurred.
  - `failureReason` 'failed-authentication' | 'card-not-enrolled' | 'no-card-record' | 'suspected-fraud' | 'invalid-acquirer-details' | 'cancelled' | 'unsupported-version' | 'challenge-required' | 'authentication-timed-out' | 'acs-unavailable' | 'directory-server-unavailable' | 'transient-system-failure' | 'invalid-card-details' | 'transaction-not-permitted' | 'required-data-element-missing' | 'protocol-error': The reason for the 3DS Authentication failure. This field is present when the status is `failure` and can be used for troubleshooting.
  - `ares` object: The details of the 3DS Authentication Response (ARes).
    - `transStatus` object: The transaction status.
      - `value` 'Y' | 'N' | 'U' | 'A' | 'C' | 'D' | 'R' | 'I': The raw value of the transaction status.
      - `detail` string: The detailed description of the transaction status.
    - `transStatusReason` object, nullable: The reason for the transaction status if transStatus is 'N', 'U' or 'R'.
      - `value` string: The raw value of the transaction status reason.
      - `detail` string: The detailed description of the transaction status reason.
    - `cardholderInfo` string, nullable: A message from the card issuer to display to the cardholder, such as guidance to contact their bank. Maximum 128 characters.
  - `cres` object, nullable: The details of the 3DS Challenge Response (CRes).
    - `transStatus` object: The transaction status.
      - `value` 'Y' | 'N': The raw value of the transaction status.
      - `detail` string: The detailed description of the transaction status.
  - `rreq` object, nullable: The result of the 3DS authentication when a challenge has occurred.
    - `transStatus` object: The transaction status.
      - `value` 'Y' | 'N' | 'U' | 'A' | 'R': The raw value of the transaction status.
      - `detail` string: The detailed description of the transaction status. Below are descriptions of each of the possible values: - `Y` - Authentication Verification Successful. - `N` - Not Authenticated/Account Not Verified; Transaction denied. - `U` - Authentication/Account Verification Could Not Be Performed; Technical or other problem. - `A` - Attempts Processing Performed; Not Authenticated/Verified, but a proof of attempted authentication/verification is provided. - `R` - Authentication/Account Verification Rejected; Issuer is rejecting.
  - `dcap` ThreeDSDcap, nullable: The session's standing in Visa's Digital Commerce Authentication Program (DCAP). This value is only present for Visa sessions created with a `challenge.reason` of `data-sharing`, and is `null` otherwise.
    - `qualified` boolean, required: Whether the session supplied every data point the program requires, so the transaction was submitted to Visa for DCAP.
    - `accepted` boolean, nullable: Whether Visa reported the supplied data as meeting the program's data quality requirements. This value is `null` while Visa hasn't returned a verdict, and whenever `qualified` is `false`.
  - `externalCustomerReference` string: The identifier you provided when creating the 3DS Session. Only present if one was provided.
  - `createdAt` integer, required: The exact time, in epoch milliseconds, when this 3DS-Session was created.
  - `updatedAt` integer: The exact time, in epoch milliseconds, when this 3DS-Session was last updated.

## Other responses

- `400`: The request was invalid or cannot be otherwise served.

## Changes

- **2026-11-06** `8d0ca833fa04`: 11 breaking, 22 warning, 23 info
  - added the pattern `^[0-9a-zA-Z ]*$` to the request property `customer/billing/address/postalCode`
  - added the pattern `^[0-9a-zA-Z ]*$` to the request property `customer/shipping/address/postalCode`
  - added the pattern `^[0-9a-zA-Z _\-¡-￿]+$` to the request property `customer/billing/address/city`
  - added the pattern `^[0-9a-zA-Z _\-¡-￿]+$` to the request property `customer/shipping/address/city`
  - …52 more
- **2026-04-17** `5e1eb58d42d5`: 12 breaking, 2 warning, 12 info
  - removed the enum value `yearly` of the request property `payment/oneOf[#/components/schemas/PaymentInstallment]/frequency`
  - removed the enum value `yearly` of the request property `payment/oneOf[#/components/schemas/PaymentRecurring]/frequency`
  - added the pattern `^[a-zA-Z0-9 !"#$%&'()*+,-./:;<=>?@[\]^_`{|}~]{2,45}$` to the request property `customer/name`
  - the `customer/billing/address/country` request property format changed from no format to `iso-3166-1-alpha-2`
  - …22 more
- **2025-11-18** `30ea25af4354`: 6 breaking, 20 warning, 14 info
  - the `acquirer` request property type changed from `object` to `string`
  - the response property `ares/transStatusReason` became nullable for the status `201`
  - the response property `challenge/reason` became nullable for the status `201`
  - the response property `cres` became nullable for the status `201`
  - …36 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/evervault/apis/evervault-api/changes/payments/3ds-sessions/post.md)

---

[API](https://skmtc.dev/evervault/apis/evervault-api.md) - [All operations](https://skmtc.dev/evervault/apis/evervault-api/llms.txt) - [OpenAPI document](https://skmtc.dev/evervault/apis/evervault-api/revisions/8d0ca833fa04?raw)