Evervault 3D Secure API
3D Secure is a security protocol designed to prevent fraud in online card transactions. It adds an additional layer of authentication during the payment process.
OpenAPI Specification
openapi: 3.1.0
info:
title: Evervault 3D Secure API
version: 0.0.1
description: The Evervault API allows developers to interact programmatically with their Evervault apps using HTTP requests.
contact:
email: support@evervault.com
name: Evervault Support Team
url: https://evervault.com
servers:
- url: https://api.evervault.com
description: The Evervault API server
tags:
- name: 3D Secure
description: '3D Secure is a security protocol designed to prevent fraud in online card transactions. It adds an additional layer of authentication during the payment process.
'
paths:
/payments/3ds-sessions:
post:
x-section: Payments
x-group: 3D Secure
summary: Create a 3DS Session
description: '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())
'
operationId: createThreeDSSession
tags:
- 3D Secure
security:
- ApiKey:
- threeDSSession:create
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
merchant:
description: The merchant details. Either an inline merchant object or the unique identifier of a Merchant created with the [Merchants API](/api#merchants).
oneOf:
- type: object
description: An inline merchant object.
properties:
name:
type: string
description: The name of the merchant.
example: Ollivanders Wand Shop
website:
type: string
description: The website of the merchant.
example: https://www.ollivanders.co.uk
categoryCode:
type: string
description: The category code of the merchant.
example: '5945'
country:
type: string
format: iso-3166-1-alpha-2
description: The country code of the merchant.
example: ie
required:
- name
- website
- categoryCode
- country
- type: string
description: The unique identifier of a Merchant created with the [Merchants API](/api#merchants).
example: merchant_eead1d640d7c
card:
description: The card details. Either an inline card object or the unique identifier of a Card created with the [Cards API](/api#cards).
oneOf:
- type: object
description: An inline card object.
properties:
number:
type: string
description: The card number. Needs to be an Evervault-encrypted card number or a plaintext card number.
example: '4242424242424242'
expiry:
$ref: '#/components/schemas/CardExpiry'
required:
- number
- expiry
- type: string
description: The unique identifier of a Card created with the [Cards API](/api#cards).
example: card_eead1d640d7c
acquirer:
description: '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.
'
oneOf:
- $ref: '#/components/schemas/Acquirer'
- type: string
description: The unique identifier of an acquirer created with the [Acquirers API](/api#acquirers).
example: acquirer_adk3kdljc3
customer:
type: object
description: The details of the customer who initiated the transaction.
properties:
name:
type: string
description: The name of the customer.
pattern: ^[a-zA-Z0-9 !"#$%&'()*+,-./:;<=>?@[\]^_`{|}~]{2,45}$
example: Seamus Finnigan
phone:
type: array
description: The phone number of the customer.
items:
type: object
properties:
type:
type: string
description: The type of phone number.
enum:
- mobile
- home
- work
example: mobile
countryCode:
type: string
description: The numerical country calling code of the phone number.
example: '353'
number:
type: string
description: The phone number of the customer.
example: '873451276'
required:
- type
- countryCode
- number
email:
type: string
format: email
description: The email address of the customer.
example: seamus@hogwarts.edu
shipping:
type: object
description: The shipping details of the customer.
properties:
address:
description: The shipping address.
$ref: '#/components/schemas/Address'
billing:
type: object
description: The billing details of the customer.
properties:
address:
$ref: '#/components/schemas/Address'
taxIdentifier:
type: string
description: The tax identifier of the cardholder.
example: IE123456789
payment:
type: object
description: The payment details of the 3D Secure Authentication. This field is mandatory for transactions involving payment authentications but not required for non-payment authentications.
oneOf:
- $ref: '#/components/schemas/PaymentOneOff'
- $ref: '#/components/schemas/PaymentInstallment'
- $ref: '#/components/schemas/PaymentRecurring'
preferredVersions:
type: array
description: '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.
'
items:
type: string
enum:
- 2.2.0
challenge:
$ref: '#/components/schemas/ThreeDSChallenge'
initiator:
$ref: '#/components/schemas/ThreeDSInitiator'
required:
- card
- merchant
examples:
SimpleExample:
value:
merchant:
name: Ollivanders Wand Shop
website: https://www.ollivanders.co.uk
categoryCode: '5945'
country: gb
card:
number: '4242424242424242'
expiry:
month: 09
year: '26'
payment:
type: one-off
amount: 1000
currency: eur
responses:
'201':
description: Returns a 3DS Session object.
x-content: 'Returns the [3DS Session object](#the-3ds-session-object) that was created.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ThreeDSSession'
examples:
ActionRequired:
summary: Action Required
value:
id: tds_57aa862f8bf7
merchant:
name: Ollivanders Wand Shop
website: https://www.ollivanders.co.uk
categoryCode: '5945'
country: gb
card:
lastFour: '4242'
expiry:
month: 09
year: '26'
brand: visa
funding: debit
segment: consumer
country: gb
currency: gbp
initiator:
type: customer
challenge:
preference: no-preference
reason: null
acquirer:
bin: '567834'
merchantIdentifier: '530249576123943'
country: gb
payment:
type: one-off
amount: 1000
currency: eur
version: 2.2.0
status: action-required
nextAction:
type: use-sdk
ares:
transStatus:
value: C
detail: Challenge Required; Additional authentication is required using the CReq/CRes
transStatusReason: null
cres: null
rreq: null
accessControlServer:
transactionIdentifier: 0f651348-c519-4cfb-b349-0b302af9861f
referenceNumber: 3DS_LOA_ACS_STIN_020200_00417
directoryServer:
transactionIdentifier: 71c5d726-5d4b-426c-9d7d-131970f41c5c
referenceNumber: 3DS_LOA_DIS_VISA_020200_00828
network: visa
threeDSServer:
transactionIdentifier: a623edc1-54bc-455d-9dea-c909783a37c3
createdAt: 1692972623233
updatedAt: 1692972623768
Successful:
summary: Successful
value:
id: tds_57aa862f8bf7
merchant:
name: Ollivanders Wand Shop
website: https://www.ollivanders.co.uk
categoryCode: '5945'
country: gb
card:
lastFour: '4242'
expiry:
month: 09
year: '26'
brand: visa
funding: debit
segment: consumer
country: gb
currency: gbp
initiator:
type: customer
challenge:
preference: no-preference
reason: null
acquirer:
bin: '567834'
merchantIdentifier: '530249576123943'
country: gb
payment:
type: one-off
amount: 1000
currency: eur
accessControlServer:
transactionIdentifier: d351441b-f9e6-46e3-a726-9fc4f39bbaaa
referenceNumber: 3DS_LOA_ACS_STIN_020200_00417
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: success
authentication:
flow: frictionless
cryptogram: MTIzNDU2Nzg5MDA5ODc2NTQzMjE=
eci:
value: '05'
descriptor: fully-authenticated
liabilityShift: true
ares:
transStatus:
value: Y
detail: Authentication/Account Verification Successful
transStatusReason: null
cres: null
rreq: null
createdAt: 1692972623233
updatedAt: 1692972623768
Failure:
summary: Failed
value:
id: tds_57aa862f8bf7
merchant:
name: Ollivanders Wand Shop
website: https://www.ollivanders.co.uk
categoryCode: '5945'
country: gb
card:
lastFour: '4242'
expiry:
month: 09
year: '26'
brand: visa
funding: debit
segment: consumer
country: gb
currency: gbp
initiator:
type: customer
challenge:
preference: no-preference
reason: null
acquirer:
bin: '567834'
merchantIdentifier: '530249576123943'
country: gb
payment:
type: one-off
amount: 1000
currency: eur
version: 2.2.0
status: failure
failureReason: card-not-enrolled
ares:
transStatus:
value: N
detail: Not Authenticated/Account Not Verified; Transaction denied
transStatusReason:
value: '13'
detail: Cardholder not enrolled in service
cres: null
rreq: null
accessControlServer:
transactionIdentifier: 0f651348-c519-4cfb-b349-0b302af9861f
referenceNumber: 3DS_LOA_ACS_STIN_020200_00417
directoryServer:
transactionIdentifier: 71c5d726-5d4b-426c-9d7d-131970f41c5c
referenceNumber: 3DS_LOA_DIS_VISA_020200_00828
network: visa
threeDSServer:
transactionIdentifier: a623edc1-54bc-455d-9dea-c909783a37c3
createdAt: 1692972623233
updatedAt: 1692972623768
'400':
description: 'The request was invalid or cannot be otherwise served.
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
ShortNameRequired:
summary: Short Name Required
value:
code: payments/3ds-sessions/short-name-required
title: Short Name Required
detail: Merchant merchant_eead1d640d7c's name is 50 characters, which exceeds the 3DS 40-character limit. Set a `shortName` on the merchant to use it for 3DS sessions.
/payments/3ds-sessions/{3ds_session_id}:
get:
summary: Retrieve a 3DS Session
description: 'Retrieve a 3DS Session.
'
operationId: retrieveThreeDSSession
tags:
- 3D Secure
security:
- ApiKey:
- threeDSSession:read
parameters:
- name: 3ds_session_id
in: path
description: The id of the session
required: true
schema:
type: string
responses:
'200':
description: Returns a 3DS Session object.
x-content: 'Returns the [3DS Session object](#the-3ds-session-object).
'
content:
application/json:
schema:
$ref: '#/components/schemas/ThreeDSSession'
examples:
ActionRequired:
summary: Action Required
value:
id: tds_57aa862f8bf7
merchant:
name: Ollivanders Wand Shop
website: https://www.ollivanders.co.uk
categoryCode: '5945'
country: gb
card:
lastFour: '4242'
expiry:
month: 09
year: '26'
brand: visa
funding: debit
segment: consumer
country: gb
currency: gbp
initiator:
type: customer
challenge:
preference: no-preference
reason: null
acquirer:
bin: '567834'
merchantIdentifier: '530249576123943'
country: gb
payment:
type: one-off
amount: 1000
currency: eur
version: 2.2.0
status: action-required
nextAction:
type: use-sdk
threeDSServer:
transactionIdentifier: a623edc1-54bc-455d-9dea-c909783a37c3
createdAt: 1692972623233
updatedAt: 1692972623768
Successful:
summary: Successful
value:
id: tds_57aa862f8bf7
merchant:
name: Ollivanders Wand Shop
website: https://www.ollivanders.co.uk
categoryCode: '5945'
country: gb
card:
lastFour: '4242'
expiry:
month: 09
year: '26'
brand: visa
funding: debit
segment: consumer
country: gb
currency: gbp
initiator:
type: customer
challenge:
preference: no-preference
reason: null
acquirer:
bin: '567834'
merchantIdentifier: '530249576123943'
country: gb
payment:
type: one-off
amount: 1000
currency: eur
version: 2.2.0
status: success
authentication:
flow: challenge
methods:
- sms-otp
cryptogram: MTIzNDU2Nzg5MDA5ODc2NTQzMjE=
eci:
value: '05'
descriptor: fully-authenticated
liabilityShift: true
ares:
transStatus:
value: C
detail: Challenge Required; Additional authentication is required using the CReq/CRes
transStatusReason: null
cres:
transStatus:
value: Y
detail: Authentication/Account Verification Successful
rreq:
transStatus:
value: Y
detail: Authentication Verification Successful.
accessControlServer:
transactionIdentifier: 0f651348-c519-4cfb-b349-0b302af9861f
referenceNumber: 3DS_LOA_ACS_STIN_020200_00417
directoryServer:
transactionIdentifier: 71c5d726-5d4b-426c-9d7d-131970f41c5c
referenceNumber: 3DS_LOA_DIS_VISA_020200_00828
network: visa
threeDSServer:
transactionIdentifier: a623edc1-54bc-455d-9dea-c909783a37c3
createdAt: 1692972623233
updatedAt: 1692972623768
Failure:
summary: Failed
value:
id: tds_57aa862f8bf7
merchant:
name: Ollivanders Wand Shop
website: https://www.ollivanders.co.uk
categoryCode: '5945'
country: gb
card:
lastFour: '4242'
expiry:
month: 09
year: '26'
brand: visa
funding: debit
segment: consumer
country: gb
currency: gbp
initiator:
type: customer
challenge:
preference: no-preference
reason: null
acquirer:
bin: '567834'
merchantIdentifier: '530249576123943'
country: gb
payment:
type: one-off
amount: 1000
currency: eur
version: 2.2.0
status: failure
failureReason: suspected-fraud
accessControlServer:
transactionIdentifier: 0f651348-c519-4cfb-b349-0b302af9861f
referenceNumber: 3DS_LOA_ACS_STIN_020200_00417
directoryServer:
transactionIdentifier: 71c5d726-5d4b-426c-9d7d-131970f41c5c
referenceNumber: 3DS_LOA_DIS_VISA_020200_00828
network: visa
threeDSServer:
transactionIdentifier: a623edc1-54bc-455d-9dea-c909783a37c3
createdAt: 1692972623233
updatedAt: 1692972623768
/payments/3ds-sessions/{3ds_session_id}/messages:
get:
x-hidden: true
summary: Retrieve 3DS Messages
description: 'Retrieve messages for a 3DS Session. This endpoint can be helpful for debugging 3DS sessions, providing insight into the raw 3DS messages that were exchanged between the 3DS Server and the Directory Server.
'
operationId: retrieveThreeDSMessages
tags:
- 3D Secure
security:
- ApiKey:
- threeDSSession:read
parameters:
- name: 3ds_session_id
in: path
description: The id of the 3DS session
required: true
schema:
type: string
responses:
'200':
description: Returns 3DS messages for the session.
x-content: 'Returns an array of [3DS Message objects](#the-3ds-message-object).
'
content:
application/json:
schema:
type: object
properties:
messages:
type: array
description: Array of 3DS messages for the session
items:
type: object
properties:
type:
type: string
description: The type of 3DS message (e.g., AReq, ARes, CReq, CRes, RReq, RRes)
example: AReq
created_at:
type: integer
description: Timestamp when the message was created
example: 1751039450228
data:
type: object
description: The message data payload
examples:
MessagesExample:
summary: 3DS Messages
value:
messages:
- type: AReq
created_at: 1751039450228
data:
type: AReq
threeDSCompInd: N
threeDSRequestorAuthenticationInd: '01'
threeDSRequestorChallengeInd: '82'
threeDSRequestorID: 10085939*Example
threeDSRequestorName: Example 3DSS_Merchant
threeDSRequestorURL: https://example.com/
threeDSServerRefNumber: EXAMPLE_3DS_REF_NUMBER
threeDSServerOperatorID: '10085939'
threeDSServerTransID: 274af11d-2f5a-4050-b70e-8eda1e76f782
threeDSServerURL: https://example.3ds.com/result
acctType: '03'
acquirerBIN: '123456'
acquirerMerchantID: '123456789012'
browserAcceptHeader: '*/*'
browserIP: 192.168.1.1
browserJavaEnabled: false
browserJavascriptEnabled: true
browserLanguage: en-GB
browserColorDepth: '24'
browserScreenHeight: '1080'
browserScreenWidth: '1920'
browserTZ: '0'
browserUserAgent: Mozilla/5.0 (Example Browser)
cardExpiryDate: '2712'
acctNumber: '************1234'
deviceChannel: '02'
mcc: '1234'
merchantCountryCode: '372'
merchantName: Example Merchant
messageCategory: '01'
notificationURL: https://example.3ds.com/notification
purchaseAmount: '100000'
purchaseCurrency: '978'
purchaseExponent: '2'
purchaseDate: '20250627155050'
transType: '01'
- type: ARes
created_at: 1751039450626
data:
type: ARes
threeDSServerTransID: 274af11d-2f5a-4050-b70e-8eda1e76f782
acsChallengeMandated: Y
acsOperatorID: '123456789'
acsReferenceNumber: EXAMPLE_ACS_REF_NUMBER
acsTransID: '123456789012'
acsURL: https://example.3ds.com/creq
authenticationType: '02'
dsReferenceNumber: EXAMPLE_DS_REF_NUMBER
dsTransID: 4912cee8-3c89-4504-ac5b-0b2a3ef9489d
transStatus: Y
eci: '05'
components:
schemas:
PaymentOneOff:
type: object
summary: One-Off Payment
description: A payment that is made in a single transaction.
properties:
type:
type: string
description: The value `one-off`.
enum:
- one-off
example: one-off
amount:
type: integer
description: The amount of the payment in the smallest currency unit (e.g. cents).
example: 1000
currency:
type: string
format: iso-4217-alphabetic
description: The currency of the payment.
example: gbp
required:
- type
- amount
- currency
ThreeDSSession:
type: object
summary: The 3DS Session Object
description: '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.
'
properties:
id:
type: string
description: A unique identifier assigned to each 3DS Authentication.
example: tds_57aa862f8bf7
card:
type: object
properties:
lastFour:
type: string
description: The last four digits of the card number.
example: '4242'
expiry:
$ref: '#/components/schemas/CardExpiry'
brand:
type: string
description: The card brand.
example: visa
funding:
type: string
description: The card funding type.
example: debit
segment:
type: string
description: The card segment.
example: consumer
issuer:
type: string
description: The name of the card issuer.
example: Fifth Third Bank, The
country:
type: string
format: iso-3166-1-alpha-2
description: The country code of the card.
example: gb
currency:
type: string
description: The currency code of the card. (ISO 4217 three-letter code)
example: gbp
required:
- lastFour
- expiry
- brand
- funding
- segment
- country
- currency
acquirer:
$ref: '#/components/schemas/Acquirer'
merchant:
type: object
description: The merchant details.
properties:
name:
type: string
description: The name of the merchant.
example: Ollivanders Wand Shop
website:
type: string
description: The website of the merchant.
example: https://www.ollivanders.co.uk
categoryCode:
type: string
description: The category code of the merchant.
example: '5945'
country:
type: string
format: iso-3166-1-alpha-2
description: The country code of the merchant.
example: ie
required:
- name
- website
- categoryCode
- country
payment:
type: object
description: The payment details of the 3D Secure Authentication.
oneOf:
- $ref: '#/components/schemas/PaymentInstallment'
- $ref: '#/components/schemas/PaymentOneOff'
- $ref: '#/components/schemas/PaymentRecurring'
challenge:
$ref: '#/components/schemas/ThreeDSChallenge'
initiator:
$ref: '#/components/schemas/ThreeDSInitiator'
accessControlServer:
$ref: '#/components/schemas/ThreeDSAccessControlServer'
directoryServer:
$ref: '#/components/schemas/ThreeDSDirectoryServer'
threeDSServer:
type: object
description: Details about the 3DS Server involved in the 3DS transaction.
properties:
transac
# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/evervault/refs/heads/main/openapi/evervault-3d-secure-api-openapi.yml