EVevervault
Payments
3D Secure

Create a 3DS Session

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

post/payments/3ds-sessions

Request

Request body

preferredVersionsstring[]

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.

externalCustomerReferencestring

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.

Example request

{
  "merchant": {
    "name": "Ollivanders Wand Shop",
    "website": "https://www.ollivanders.co.uk",
    "categoryCode": "5945",
    "country": "ie"
  },
  "card": {
    "number": "4242424242424242",
    "expiry": {
      "month": "12",
      "year": "29"
    }
  },
  "acquirer": {
    "bin": "42424242",
    "merchantIdentifier": "5945",
    "country": "ie"
  },
  "customer": {
    "name": "Seamus Finnigan",
    "phone": [
      {
        "type": "mobile",
        "countryCode": "353",
        "number": "873451276"
      }
    ],
    "email": "seamus@hogwarts.edu",
    "shipping": {
      "address": {
        "line1": "123 Main St",
        "line2": "Floor 4",
        "city": "Springfield",
        "state": "ny",
        "country": "us"
      }
    },
    "billing": {
      "address": {
        "line1": "123 Main St",
        "line2": "Floor 4",
        "city": "Springfield",
        "state": "ny",
        "country": "us"
      },
      "taxIdentifier": "IE123456789"
    },
    "deviceId": "5f2c1e8a-device",
    "clientIp": "203.0.113.42"
  },
  "payment": {
    "type": "one-off",
    "amount": 1000,
    "currency": "gbp"
  },
  "externalCustomerReference": "order_8f2a1c"
}

Response

Returns a 3DS Session object.

idstring required

A unique identifier assigned to each 3DS Authentication.

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.

cryptogramstring

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.

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.

externalCustomerReferencestring

The identifier you provided when creating the 3DS Session. Only present if one was provided.

createdAtinteger required

The exact time, in epoch milliseconds, when this 3DS-Session was created.

updatedAtinteger

The exact time, in epoch milliseconds, when this 3DS-Session was last updated.

Example response

{
  "id": "tds_57aa862f8bf7",
  "card": {
    "lastFour": "4242",
    "expiry": {
      "month": "12",
      "year": "29"
    },
    "brand": "visa",
    "funding": "debit",
    "segment": "consumer",
    "issuer": "Fifth Third Bank, The",
    "country": "gb",
    "currency": "gbp"
  },
  "acquirer": {
    "bin": "42424242",
    "merchantIdentifier": "5945",
    "country": "ie"
  },
  "merchant": {
    "name": "Ollivanders Wand Shop",
    "website": "https://www.ollivanders.co.uk",
    "categoryCode": "5945",
    "country": "ie"
  },
  "payment": {
    "amount": 1000,
    "currency": "gbp",
    "installments": 12,
    "frequency": "monthly"
  },
  "accessControlServer": {
    "transactionIdentifier": "d351441b-f9e6-46e3-a726-9fc4f39bbaaa",
    "referenceNumber": "3DS_LOA_ACS_STIN_020200_00417",
    "operatorIdentifier": "Evervault"
  },
  "directoryServer": {
    "transactionIdentifier": "18030e14-fafa-462e-bfc0-da733196e808",
    "referenceNumber": "3DS_LOA_DIS_VISA_020200_00828",
    "network": "visa"
  },
  "threeDSServer": {
    "transactionIdentifier": "a623edc1-54bc-455d-9dea-c909783a37c3"
  },
  "version": "2.2.0",
  "status": "action-required",
  "authentication": {
    "flow": "frictionless",
    "methods": [
      "sms-otp",
      "push-confirmation"
    ]
  },
  "nextAction": {
    "type": "use-sdk"
  },
  "cryptogram": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=",
  "eci": {
    "value": "05",
    "descriptor": "fully-authenticated",
    "liabilityShift": true
  },
  "ares": {
    "transStatus": {
      "value": "Y",
      "detail": "Authentication/Account Verification Successful"
    },
    "transStatusReason": {
      "value": "11",
      "detail": "Suspected fraud"
    },
    "cardholderInfo": "Please contact your bank."
  },
  "cres": {
    "transStatus": {
      "value": "Y",
      "detail": "Authentication/Account Verification Successful"
    }
  },
  "rreq": {
    "transStatus": {
      "value": "Y",
      "detail": "Authentication Verification Successful."
    }
  },
  "dcap": {
    "qualified": true,
    "accepted": true
  },
  "externalCustomerReference": "order_8f2a1c",
  "createdAt": 1692972623233,
  "updatedAt": 1692972623768
}

Changes

No recorded changes to this operation across all 1 revision of this API.