Perform a 3D Secure 2 Authentication Request

POST /threedsecure/v2/accounts/account_id/authentications

Once you have received the deviceFingerprintingId from the JavaScript SDK you should include it in your Authentication request along with the other required fields and contextual data.

See our full API documentation for a complete description of the parameters required for the Authentication request.

When the authentication is complete, Paysafe interprets the directory server response and returns a response containing the status and threeDResult* parameters along with the authenticationId.

  • If status=COMPLETED, then you should consult the Liability Shift matrix to determine whether to proceed with the Authorization request.
  • If status=PENDING and threeDResult*=C then the card issuer has challenged the authentication request and requires additional verification. In this situation the merchant should continue with the challenge flow.

*If the bank does not support 3D Secure 2, the API will automatically fall back to 3DS 1.0.2 and the threeDEnrollment parameter will replace threeDResult. See Scenarios and the threeDEnrollment parameter for more details.

  • If the directory server returns threeDEnrollment=N or U and status=COMPLETED, then the authentication is complete and the merchant should consult the Liability Shift matrix to determine whether to proceed with the Authorization request.
  • If the directory server returns threeDEnrollment=Y and status=COMPLETED, then the authentication is complete and the merchant should consult the Liability Shift matrix to determine whether to proceed with the Authorization request.
  • If the directory server returns threeDEnrollment=Y and status=PENDING, then the card issuer has challenged the cardholder and the merchant should continue with the challenge flow.
Request Example
curl -X POST https://api.test.paysafe.com/threedsecure/v2/accounts/89987201/authentications \
  -u devcentre322:B-qa2-0-53625f86-302c021476f52bdc9deab7aea876bb28762e62f92fc671e2d0214736abf501e9675e55940e83ef77f5c304edc7968 \
  -H 'Content-type: application/json' \
  -d '{
  "amount": 123,
  "currency": "EUR",
  "merchantRefNum": "Ref-1234",
  "merchantUrl": "https://mysite.com",
  "card": {
    "cardExpiry": {
      "month": 12,
      "year": 2019
    },
    "cardNum": "4111111111111111",
    "holderName": "John Smith"
  },
 "billingDetails": {
    "city": "New York",
    "country": "US",
    "state": "AL",
    "street": "My street 1",
    "street2": "My street 2",
    "zip": "CHY987"
  },
  "shippingDetails": {
    "city": "New York",
    "country": "US",
    "state": "AL",
    "street": "My street 1",
    "street2": "My street 2",
    "zip": "CHY987",
    "shipMethod": "S"
  },
  "profile": {
    "cellPhone": "+154657854697",
    "email": "example@example.com",
    "phone": "+154657854697"
  },
  "deviceFingerprintingId": "123e4567-e89b-12d3-a456-426655440000",
  "deviceChannel": "BROWSER",
  "requestorChallengePreference": "NO_PREFERENCE",
  "messageCategory": "PAYMENT",
  "transactionIntent": "GOODS_OR_SERVICE_PURCHASE",
  "authenticationPurpose": "PAYMENT_TRANSACTION",
  "orderItemDetails": {
    "preOrderItemAvailabilityDate": "2014-01-26",
    "preOrderPurchaseIndicator": "MERCHANDISE_AVAILABLE",
    "reorderItemsIndicator": "FIRST_TIME_ORDER",
    "shippingIndicator": "SHIP_TO_BILLING_ADDRESS"
  },
  "purchasedGiftCardDetails": {
    "amount": 1234,
    "count": 2,
    "currency": "USD"
  },
  "userAccountDetails": {
    "addCardAttemptsForLastDay": 1,
    "changedDate": "2010-01-26",
    "changedRange": "DURING_TRANSACTION",
    "createdDate": "2010-01-26",
    "createdRange": "NO_ACCOUNT",
    "passwordChangedDate": "2012-01-26",
    "passwordChangedRange": "NO_CHANGE",
    "paymentAccountDetails": {
      "createdRange": "NO_ACCOUNT",
      "createdDate": "2010-01-26"
    },
    "shippingDetailsUsage": {
      "cardHolderNameMatch": true,
      "initialUsageDate": "2014-01-26",
      "initialUsageRange": "CURRENT_TRANSACTION"
    },
    "suspiciousAccountActivity": true,
    "totalPurchasesSixMonthCount": 1,
    "transactionCountForPreviousDay": 1,
    "transactionCountForPreviousYear": 3,
    "userLogin": {
      "authenticationMethod": "NO_LOGIN",
      "data": "Some up to 2048 bytes undefined data",
      "time": "2014-01-26T10:32:28Z"
    }
  }
}'

Prior to trying the example, you should:

  • Replace the account number (89987201) in the URL with the test account number you received.

The request contains the following parameters.

Element Child Element Type Required? Description
amount integer
max=99999999999
Yes This is the amount of the request, in minor units.
currency string
length<=3
Yes This is the currency of the merchant account, e.g., USD or CAD.
merchantRefNum string
length<=255
Yes This is the merchant reference number created by the merchant and submitted as part of the request. It must be unique for each request.
merchantUrl string
length<=2048
Yes This is the fully qualified URL of the merchant's commercial or customer care website.
card cardExpiry object Yes

This is the card's expiry date. The following parameters are required:

  • month – integer, length=2
  • year – integer, length=4
cardNum string
length=8-20
Yes This is the card number used for the request.
holderName string
length<=45
No This is the name of the card holder.
billingDetails city string
length<=40
No This is the city in the billing address.
country enum
length=2
No This is the country in the billing address.
state string
length<=40
No This is the state/province in the billing address.
street string
length<=50
No This is the first line of the street address in the billing address.
street2 string
length<=50
No This is the second line of the street address in the billing address, if required (e.g., apartment number).
zip string
length<=10
No This is the postal/zip code in the billing address.
shippingDetails city string
length<=40
No This is the city in which the recipient resides.
country enum
length=2
No This is the country in which the recipient resides.
state string
length<=40
No This is the state in which the recipient resides.
street string
length<=50
No This is the recipient's street address.
street2 string
length<=255
No This is the second line of the street address in the shipping address, if required (e.g., apartment number).
zip string
length<=10
No This is the recipient's postal/zip code.
shipMethod enum No

This is the method of shipment. Possible values are:

  • N – Next Day/Overnight
  • T – Two-Day Service
  • C – Lowest Cost
  • O – Other
  • S – Same Day
profile cellPhone string
length<=40
No This is the customer's cell phone.
email

string
length<=255

No This is the email address of the customer.
phone string
length<=40
No This is the customer's primary phone.
deviceFingerprintingId string
length<=36
Yes This is the UUID used with device fingerprinting.
deviceChannel enum Yes

This is the type of channel interface used to initiate the transaction. Possible values are:

  • BROWSER
  • APP
  • 3RI
requestorChallengePreference enum No

This indicates whether a challenge is requested for this transaction. Possible values are:

  • NO_PREFERENCE
  • NO_CHALLENGE_REQUESTED
  • CHALLENGE_REQUESTED
  • CHALLENGE_MANDATED
messageCategory enum Yes

This is the category of the message for a specific use case. Possible values are:

  • PAYMENT
  • NON_PAYMENT
transactionIntent enum No

This identifies the type of transaction being authenticated. Possible values are:

  • GOODS_OR_SERVICE_PURCHASE
  • CHECK_ACCEPTANCE
  • ACCOUNT_FUNDING
  • QUASI_CASH_TRANSACTION
  • PREPAID_ACTIVATION

This element is only required in certain markets, e.g., Brazil.

authenticationPurpose enum Yes

This is the type of Authentication request. This data element provides additional information to the ACS to determine the best approach for handling an authentication request. Possible values are:

  • PAYMENT_TRANSACTION
  • RECURRING_TRANSACTION
  • INSTALMENT_TRANSACTION
  • ADD_CARDMAINTAIN_CARD
  • EMV_TOKEN_VERIFICATION
maxAuthorizationsForInstalmentPayment integer
max=999
No

This is the maximum number of authorizations permitted for installment payments.

This is required if authenticationPurpose=INSTALMENT_TRANSACTION.

initialPurchaseTime UTC formatted date No

This is the date and time of the purchase.The ISO 8601 date format is expected i.e., YYYY-MM-DD-THH:MM:SSZ.

This element is only required if messageCategory=NON_PAYMENT and authenticationPurpose=INSTALMENT_TRANSACTION or RECURRING_TRANSACTION.

billingCycle endDate UTC formatted date No This is the date after which no further authorizations will be performed. The ISO 8601 date format is expected, i.e., YYYY-MM-DD.
frequency integer
max=9999
No This is the minimum number of days between authorizations.
orderItemDetails preOrderItemAvailabilityDate UTC formatted date No For a pre-ordered purchase, this is the date that the merchandise is expected to be available. The ISO 8601 date format is expected, i.e., YYYY-MM-DD.
preOrderPurchaseIndicator enum No

This indicates whether the cardholder is placing an order for available merchandise or merchandise with a future availability or release date. Possible values are:

  • MERCHANDISE_AVAILABLE
  • FUTURE_AVAILABILITY
reorderItemsIndicator enum No

This indicates whether the cardholder is reordering merchandise. Possible values are:

  • FIRST_TIME_ORDER
  • REORDER
shippingIndicator enum No

This is the shipping method for the transaction. Possible values are:

  • SHIP_TO_BILLING_ADDRESS
  • SHIP_TO_VERIFIED_ADDRESS
  • SHIP_TO_DIFFERENT_ADDRESS
  • SHIP_TO_STORE
  • DIGITAL_GOODS
  • TRAVEL_AND_EVENT_TICKETS
  • OTHER
purchasedGiftCardDetails amount integer
max=99999999999
No This is the amount of the gift card, in minor units.
count integer
max=99
No This is the total count of individual prepaid or gift cards or codes purchased.
currency string
length=3
No This is the currency of the gift card, e.g., USD or CAD.
userAccountDetails addCardAttemptsForLastDay integer
max=999
No This is the number of Add Card attempts in the last 24 hours.
changedDate UTC formatted date No This is the date that the cardholder’s account with the 3DS Requestor was last changed. The ISO 8601 date format is expected, i.e., YYYY-MM-DD.
changedRange enum No

This is the length of time between the most recent change to the cardholder’s account information and the API call of the current transaction. Possible values are:

  • DURING_TRANSACTION
  • LESS_THAN_THIRTY_DAYS
  • THIRTY_TO_SIXTY_DAYS
  • MORE_THAN_SIXTY_DAYS
createdDate UTC formatted date No This is the date when the cardholder opened the account with the 3DS Requestor. The ISO 8601 date format is expected, i.e., YYYY-MM-DD.
createdRange enum No

This is the length of time between the cardholder opening the account with the 3DS Requestor and the API call of the current transaction. Possible values are:

  • NO_ACCOUNT
  • DURING_TRANSACTION
  • LESS_THAN_THIRTY_DAYS
  • THIRTY_TO_SIXTY_DAYS
  • MORE_THAN_SIXTY_DAYS
passwordChangedDate UTC formatted date No This is the date when the cardholder’s account was reset or the password was changed. The ISO 8601 date format is expected, i.e., YYYY-MM-DD.
passwordChangedRange enum No

This is the length of time between the most recent password change or cardholder account reset and the API call of the current transaction. Possible values are:

  • NO_CHANGEDURING_TRANSACTION
  • LESS_THAN_THIRTY_DAYS
  • THIRTY_TO_SIXTY_DAYS
  • MORE_THAN_SIXTY_DAYS
paymentAccountDetails No

Details of the current payment account of the cardholder.

  • createdRange – Indicates the length of time that the payment account was enrolled in the cardholder’s account with the 3DS Requestor. Possible values are:
    • NO_ACCOUNT
    • DURING_TRANSACTION
    • LESS_THAN_THIRTY_DAYS
    • THIRTY_TO_SIXTY_DAYS
    • MORE_THAN_SIXTY_DAYS
  • createdDate – Date that the payment account was enrolled in the cardholder’s account with the 3DS Requestor. UTC formatted date
priorThreeDSAuthentication data string
max=2048 bytes
No This field is reserved for future iterations of 3D Secure 2.
method enum No

This is the mechanism used previously by the cardholder to authenticate to the 3DS Requestor. Possible values are:

  • FRICTIONLESS_AUTHENTICATION
  • ACS_CHALLENGE
  • AVS_VERIFIED
  • OTHER_ISSUER_METHOD
id string
length<=36
No

This is the previous authentication ID for the cardholder.

For recurring payments, this is the authenticationId of the first authentication.

time UTC formatted date No This is the date and time of the cardholder authentication. The ISO 8601 date format is expected, i.e., YYYY-MM-DD-THH:MM:SSZ.
shippingDetailsUsage cardHolderNameMatch boolean No This indicates whether the cardholder name on the account is identical to the shipping name used for this transaction.
initialUsageDate UTC formatted date No This is the date when the shipping address for this transaction was first used with the 3DS Requestor. The ISO 8601 date format is expected, i.e., YYYY-MM-DD.
initialUsageRange enum No

This is the length of time between the first use of this shipping address and the current transaction. Possible values are:

  • CURRENT_TRANSACTION
  • LESS_THAN_THIRTY_DAYS
  • THIRTY_TO_SIXTY_DAYS
  • MORE_THAN_SIXTY_DAYS
suspiciousAccountActivity boolean No This indicates whether the 3DS Requestor has experienced suspicious activity, including previous fraud, on the cardholder account.
totalPurchasesSixMonthCount integer
max=9999
No This is the total number of purchases from this cardholder account in the previous six months.
transactionCountForPreviousDay integer
max=999
No This is the number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours.
transactionCountForPreviousYear integer
max=999
No This is the number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year.
travelDetails isAirTravel boolean No This indicates whether the transaction is an air travel related purchase, e.g., a ticket purchase. Default is false.
airlineCarrier string
length<=256
No

This is the selected airline carrier.

This is required if isAirTravel=true.

departureDate string
UTC formatted date
No

This is the date of departure in the time zone of the departure location. The ISO 8601 date format is expected, i.e., YYYY-MM-DD.

This is required if isAirTravel=true.

destination string
length<=5
No

This is the airport code of the destination airport.

This is required if isAirTravel=true.

origin string
length<=5
No

This is the airport code of the originating airport.

This is required if isAirTravel=true.

passengerFirstName string
length<=99
No

This is the first name of the cardholder from the billing details.

This is required if isAirTravel=true.

passengerLastName string
length<=99
No

This is the last name of the cardholder from the billing details.

This is required if isAirTravel=true.

userLogin authenticationMethod enum No

This is the mechanism used by the cardholder to authenticate to the 3DS Requestor. Possible values are:

  • NO_LOGIN
  • INTERNAL_CREDENTIALS
  • FEDERATED_ID
  • ISSUER_CREDENTIALS
  • THIRD_PARY_AUTHENTICATION
  • FIDO_AUTHENTICATOR
data string
max=2048 bytes
No This is the data that documents and supports a specific authentication process. Not currently specified in detail, intended to carry data that the ACS can use to verify the authentication process.
time UTC formatted date No This is the date and time of the cardholder authentication. The ISO 8601 date format is expected, i.e., YYYY-MM-DD-THH:MM:SSZ.

browserDetails

If this object is included, all the child elements are required.

No
acceptHeader string
length<=2048
Yes This is the exact content of the HTTP accept header as sent to the 3DS Requestor from the cardholder’s browser.
colorDepthBits enum Yes

This is the bit depth of the color palette for displaying images, in bits per pixel. Possible values are:

  • 1
  • 4
  • 8
  • 15
  • 16
  • 24
  • 32
  • 48
customerIp string
Valid IPv4/IPv6
Yes This is the customer's IP address.
javascriptEnabled boolean Yes This indicates whether the cardholder's browser is able to execute JavaScript.
javaEnabled boolean Yes This indicates whether the cardholder's browser is able to execute Java.
language string
length<=8
Yes This is the language in the browser.
screenHeight integermax=999999 Yes This is the total height of the cardholder’s screen in pixels.
screenWidth integermax=999999 Yes This is the total width of the cardholder’s screen in pixels.
timezoneOffset integer
max=99999
Yes This is the time-zone offset in minutes between UTC and the local time of the cardholder's browser.
userAgent string
length<=256
Yes This is the User-Agent header from the customer's browser. For example:Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1985.125 Safari/537.36
"Frictionless" Response Example
{
  "id": "123e4567-e89b-12d3-a456-4266554456745",
  "cavv": "BwAQATkhGAEAABVIFSEYEGkybeU=",
  "eci": 5,
  "status": "COMPLETED",
  "threeDResult": "Y",
  "txnTime": "2019-01-21T16:28:17.735Z",
  "amount": 123,
  "currency": "EUR",
  "merchantRefNum": "Ref-1234",
  "merchantUrl": "https://mysite.com",
  "card": {
    "cardExpiry": {
      "month": 12,
      "year": 2019
    },
    "cardBin": "411111",
    "lastDigits": "1111",
    "holderName": "John Smith"
  },
  "billingDetails": {
    "city": "New York",
    "country": "US",
    "state": "AL",
    "street": "My street 1",
    "street2": "My street 2",
    "zip": "CHY987"
  },
  "shippingDetails": {
    "city": "New York",
    "country": "US",
    "state": "AL",
    "street": "My street 1",
    "street2": "My street 2",
    "zip": "CHY987",
    "shipMethod": "S"
  },
  "profile": {
    "cellPhone": "+154657854697",
    "email": "example@example.com",
    "phone": "+154657854697"
  },
  "directoryServerTransactionId": "123e4567-e89b-12d3-a456-4266554456745",
  "threeDSecureVersion": "2.1.0"
}

The response parameters not contained in the request are described below:

Element Child Element Type Description
id string
length<=36
This is the unique ID returned in the response.
cavv string
length<=2048

This is the Cardholder Authentication Verification Value, indicating that the transaction has been authenticated.

This only exists when no challenge is required, i.e., a successful frictionless authentication.

eci integer
length<=2

This is the Electronic Commerce Indicator code, which gets returned by the card issuer indicating whether the cardholder was successfully authenticated. Note that in some cases the eci value includes a leading zero, e.g., 01 or 02.

Visa, Amex, JCB, and Diners Club

  • 5 – Identifies a successfully authenticated transaction.
  • 6 – Identifies an attempted authenticated transaction.
  • 7 – Identifies a non-authenticated transaction.

Mastercard

  • 0 – Identifies a non-authenticated transaction.
  • 1 – Identifies an attempted authenticated transaction.
  • 2 – Identifies a successfully authenticated transaction.

This only exists when no challenge is required, i.e., a frictionless authentication.

status enum

This is the status of the Authentication request. Possible values are:

  • COMPLETED – The transaction has been completed.
  • PENDING – The transaction has not been completed yet.

  • FAILED – The authentication request failed.
threeDResult enum

This indicates the outcome of the authentication. Possible values are:

  • Y – The cardholder successfully authenticated with their card issuer.
  • A – The cardholder authentication was attempted.
  • N – The cardholder failed to successfully authenticate with their card issuer.
  • U – Authentication with the card issuer was unavailable.
  • C – Challenge Required; additional authentication is required.
  • R – Rejected transaction.

The C and R values exist only for 3D Secure 2.

See 3D Secure 2 Results for more information on these Authentication outcome values.

txnTime

string

UTC date format

This is the date and time the request was processed. The ISO 8601 date format is expected, i.e., YYYY-MM-DD-THH:MM:SSZ.
card cardBin string
length<=6-8
This is the card Bank Identification Number (BIN). This is typically the first 6 digits of the card.
lastDigits string
length=4
This is the last four digits of the card used for the request.
directoryServerTransactionId string
length<=36

This is the directory server transaction ID required for Mastercard.

This exists only for 3D Secure 2.

threeDSecureVersion string
min=5, max=8
This is the 3D secure protocol version.
Response with Issuer Challenge Example
{
  "id": "123e4567-e89b-12d3-a456-4266554456745",
  "acsUrl": "https://www.acs.com",
  "status": "PENDING",
  "threeDResult": "C"
 "txnTime": "2019-01-21T16:28:17.735Z",
  "amount": 123,
  "currency": "EUR",
  "merchantRefNum": "Ref-1234",
  "merchantUrl": "https://mysite.com",
  "card": {
    "cardExpiry": {
      "month": 12,
      "year": 2019
    },
    "cardBin": "411111",
    "lastDigits": "1111",
    "holderName": "John Smith"
  },
  "billingDetails": {
    "city": "New York",
    "country": "US",
    "state": "AL",
    "street": "My street 1",
    "street2": "My street 2",
    "zip": "CHY987"
  },
  "shippingDetails": {
    "city": "New York",
    "country": "US",
    "state": "AL",
    "street": "My street 1",
    "street2": "My street 2",
    "zip": "CHY987",
    "shipMethod": "S"
  },
  "profile": {
    "cellPhone": "+154657854697",
    "email": "example@example.com",
    "phone": "+154657854697"
  },
  "directoryServerTransactionId": "123e4567-e89b-12d3-a456-4266554456745",
  "threeDSecureVersion": "2.1.0",
  "payload": "eyJtZXNzYWdlVHlwZSI6IkNSZXMiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI
4NWUxZDA1Mi1iM2NkLTRmM2YtOWVlZC1lMDdjYzQxOTk0OTkiLCJhY3NUcmFuc0lEIjoiM2QzZmVmMDUtMWJmMC00Yjk3LWEyYmUtMTk
5MzQ0YTYwMDg4IiwiYWNzVWlUeXBlIjoiMDEiLCJjaGFsbGVuZ2VBZGRJbmZvIjoiQWRkaXRpb25hbCBpbmZvcm1hdGlvbiBvbiB3aHk
geW91IGFyZSBiZWluZyBjaGFsbGFuZ2VkISIsImNoYWxsZW5nZUNvbXBsZXRpb25JbmQiOiJOIiwiY2hhbGxlbmdlSW5mb0hlYWRlciI
6Ik9UUCBIZWFkZXIiLCJjaGFsbGVuZ2VJbmZvTGFiZWwiOiJPVFAiLCJjaGFsbGVuZ2VJbmZvVGV4dCI6IlBsZWFzZSBlbnRlciB5b3V
yIE9UUCIsImNoYWxsZW5nZUluZm9UZXh0SW5kaWNhdG9yIjoiTiIsImlzc3VlckltYWdlIjp7Im1lZGl1bSI6Imh0dHBzOi8vd3d3LmN
hcmRpbmFsY29tbWVyY2UuY29tL2ltYWdlcy9jYXJkaW5hbC1sb2dvLnN2ZyIsImhpZ2giOiJodHRwczovL3d3dy5jYXJkaW5hbGNvbW1
lcmNlLmNvbS9pbWFnZXMvY2FyZGluYWwtbG9nby5zdmciLCJleHRyYUhpZ2giOiJodHRwczovL3d3dy5jYXJkaW5hbGNvbW1lcmNlLmN
vbS9pbWFnZXMvY2FyZGluYWwtbG9nby5zdmcifSwicHNJbWFnZSI6eyJtZWRpdW0iOiJodHRwczovL3d3dy5jYXJkaW5hbGNvbW1lcmN
lLmNvbS9pbWFnZXMvY2FyZGluYWwtbG9nby5zdmciLCJoaWdoIjoiaHR0cHM6Ly93d3cuY2FyZGluYWxjb21tZXJjZS5jb20vaW1hZ2V
zL2NhcmRpbmFsLWxvZ28uc3ZnIiwiZXh0cmFIaWdoIjoiaHR0cHM6Ly93d3cuY2FyZGluYWxjb21tZXJjZS5jb20vaW1hZ2VzL2NhcmR
pbmFsLWxvZ28uc3ZnIn0sInJlc2VuZEluZm9ybWF0aW9uTGFiZWwiOiJTZW5kIGEgbmV3IE9UUCIsInNka1RyYW5zSUQiOiIzNzYxODR
jMS1hZmJkLTQ2NmMtYTRkZi01OTkwYTFjNTkxMDQiLCJzdWJtaXRBdXRoZW50aWNhdGlvbkxhYmVsIjoiU3VibWl0IiwidHJhbnNTdGF
0dXMiOiJZIiwiYWNzQ291bnRlckF0b1MiOiIwMDAiLCJleHBhbmRJbmZvTGFiZWwiOiJXaHkgdXNlIDNEUyBTZWN1cmU/Pz8/Pz8/Pz8
/PyIsImV4cGFuZEluZm9UZXh0IjoiWW91IHBheSBsb3dlciBpbnRlcmNoYW5nZSByYXRlcyBhbmQgZ2V0IGNoYXJnZWJhY2sgcHJvdGV
jdGlvbiEhISEhISEhISEhIiwid2h5SW5mb0xhYmVsIjoiV2h5IHVzZSAzRFMgU2VjdXJlPyIsIndoeUluZm9UZXh0IjoiWW91IHBheSB
sb3dlciBpbnRlcmNoYW5nZSByYXRlcyBhbmQgZ2V0IGNoYXJnZWJhY2sgcHJvdGVjdGlvbiEifQ==",

 "sdkChallengePayload": "eyJtZXNzYWdlVHlwZSI6IkNSZXMiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI
4NWUxZDA1Mi1iM2NkLTRmM2YtOWVlZC1lMDdjYzQxOTk0OTkiLCJhY3NUcmFuc0lEIjoiM2QzZmVmMDUtMWJmMC00Yjk3LWEyYmUtMTk
5MzQ0YTYwMDg4IiwiYWNzVWlUeXBlIjoiMDEiLCJjaGFsbGVuZ2VBZGRJbmZvIjoiQWRkaXRpb25hbCBpbmZvcm1hdGlvbiBvbiB3aHk
geW91IGFyZSBiZWluZyBjaGFsbGFuZ2VkISIsImNoYWxsZW5nZUNvbXBsZXRpb25JbmQiOiJOIiwiY2hhbGxlbmdlSW5mb0hlYWRlciI
6Ik9UUCBIZWFkZXIiLCJjaGFsbGVuZ2VJbmZvTGFiZWwiOiJPVFAiLCJjaGFsbGVuZ2VJbmZvVGV4dCI6IlBsZWFzZSBlbnRlciB5b3V
yIE9UUCIsImNoYWxsZW5nZUluZm9UZXh0SW5kaWNhdG9yIjoiTiIsImlzc3VlckltYWdlIjp7Im1lZGl1bSI6Imh0dHBzOi8vd3d3LmN
hcmRpbmFsY29tbWVyY2UuY29tL2ltYWdlcy9jYXJkaW5hbC1sb2dvLnN2ZyIsImhpZ2giOiJodHRwczovL3d3dy5jYXJkaW5hbGNvbW1
lcmNlLmNvbS9pbWFnZXMvY2FyZGluYWwtbG9nby5zdmciLCJleHRyYUhpZ2giOiJodHRwczovL3d3dy5jYXJkaW5hbGNvbW1lcmNlLmN
vbS9pbWFnZXMvY2FyZGluYWwtbG9nby5zdmcifSwicHNJbWFnZSI6eyJtZWRpdW0iOiJodHRwczovL3d3dy5jYXJkaW5hbGNvbW1lcmN
lLmNvbS9pbWFnZXMvY2FyZGluYWwtbG9nby5zdmciLCJoaWdoIjoiaHR0cHM6Ly93d3cuY2FyZGluYWxjb21tZXJjZS5jb20vaW1hZ2V
zL2NhcmRpbmFsLWxvZ28uc3ZnIiwiZXh0cmFIaWdoIjoiaHR0cHM6Ly93d3cuY2FyZGluYWxjb21tZXJjZS5jb20vaW1hZ2VzL2NhcmR
pbmFsLWxvZ28uc3ZnIn0sInJlc2VuZEluZm9ybWF0aW9uTGFiZWwiOiJTZW5kIGEgbmV3IE9UUCIsInNka1RyYW5zSUQiOiIzNzYxODR
jMS1hZmJkLTQ2NmMtYTRkZi01OTkwYTFjNTkxMDQiLCJzdWJtaXRBdXRoZW50aWNhdGlvbkxhYmVsIjoiU3VibWl0IiwidHJhbnNTdGF
0dXMiOiJZIiwiYWNzQ291bnRlckF0b1MiOiIwMDAiLCJleHBhbmRJbmZvTGFiZWwiOiJXaHkgdXNlIDNEUyBTZWN1cmU/Pz8/Pz8/Pz8
/PyIsImV4cGFuZEluZm9UZXh0IjoiWW91IHBheSBsb3dlciBpbnRlcmNoYW5nZSByYXRlcyBhbmQgZ2V0IGNoYXJnZWJhY2sgcHJvdGV
jdGlvbiEhISEhISEhISEhIiwid2h5SW5mb0xhYmVsIjoiV2h5IHVzZSAzRFMgU2VjdXJlPyIsIndoeUluZm9UZXh0IjoiWW91IHBheSB
sb3dlciBpbnRlcmNoYW5nZSByYXRlcyBhbmQgZ2V0IGNoYXJnZWJhY2sgcHJvdGVjdGlvbiEifQ=="
 }

The response parameters not contained in the request are described below:

Element Child Element Type Description
id string
length<=36
This is the unique ID returned in the response.
acsUrl string
length<=2048

This is the fully qualified URL to redirect the consumer to complete the payer authentication transaction.

status enum

This is the status of the Authentication request. Possible values are:

  • COMPLETED – The transaction has been completed.
  • PENDING – The transaction has not been completed yet.

  • FAILED – The authentication request failed.
threeDResult enum

This indicates the outcome of the authentication. Possible values are:

  • Y – The cardholder successfully authenticated with their card issuer.
  • A – The cardholder authentication was attempted.
  • N – The cardholder failed to successfully authenticate with their card issuer.
  • U – Authentication with the card issuer was unavailable.
  • C – Challenge Required; additional authentication is required.
  • R – Rejected transaction.

The C and R values exist only for 3D Secure 2.

See 3D Secure 2 Results for more information on these Authentication outcome values.

txnTime

string

UTC date format

This is the date and time the request was processed. The ISO 8601 date format is expected, i.e., YYYY-MM-DD-THH:MM:SSZ.
card cardBin string
length=6-8
This is the card Bank Identification Number (BIN). This is typically the first 6 digits of the card.
lastDigits string
length=4
This is the last four digits of the card used for the request.
directoryServerTransactionId string
length<=36

This is the directory server transaction ID required for Mastercard.

This exists only for 3D Secure 2.

threeDSecureVersion string
min=5, max=8
This is the 3D secure protocol version.
payload stringlength<=2048 This is the encoded Payment Authentication Request generated by the merchant authentication processing system (MAPS).
sdkChallengePayload stringlength<=9999 This is a payload that, if returned, should be passed to the challenge function of the JavaScript SDK to continue with the challenge.
Response with 1.0.2 Fallback Example
{
  "id": "123e4567-e89b-12d3-a456-4266554456745",
  "acsUrl": "https://www.acs.com",
  "xid": "MTU0ODE1MjExNDYzMXBVY1ZqU3k=",
  "status": "PENDING",
  "threeDEnrollment": "Y",
  "txnTime": "2019-01-21T16:28:17.735Z",
  "amount": 123,
  "currency": "EUR",
  "merchantRefNum": "Ref-1234",
  "merchantUrl": "https://mysite.com",
  "card": {
    "cardExpiry": {
      "month": 12,
      "year": 2019
    },
    "cardBin": "411111",
    "lastDigits": "1111",
    "holderName": "John Smith"
  },
  "billingDetails": {
    "city": "New York",
    "country": "US",
    "state": "AL",
    "street": "My street 1",
    "street2": "My street 2",
    "zip": "CHY987"
  },
  "shippingDetails": {
    "city": "New York",
    "country": "US",
    "state": "AL",
    "street": "My street 1",
    "street2": "My street 2",
    "zip": "CHY987",
    "shipMethod": "S"
  },
  "profile": {
    "cellPhone": "+154657854697",
    "email": "example@example.com",
    "phone": "+154657854697"
  },
  "threeDSecureVersion": "1.0.2",
  "payload": "eyJtZXNzYWdlVHlwZSI6IkNSZXMiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI
4NWUxZDA1Mi1iM2NkLTRmM2YtOWVlZC1lMDdjYzQxOTk0OTkiLCJhY3NUcmFuc0lEIjoiM2QzZmVmMDUtMWJmMC00Yjk3LWEyYmUtMTk
5MzQ0YTYwMDg4IiwiYWNzVWlUeXBlIjoiMDEiLCJjaGFsbGVuZ2VBZGRJbmZvIjoiQWRkaXRpb25hbCBpbmZvcm1hdGlvbiBvbiB3aHk
geW91IGFyZSBiZWluZyBjaGFsbGFuZ2VkISIsImNoYWxsZW5nZUNvbXBsZXRpb25JbmQiOiJOIiwiY2hhbGxlbmdlSW5mb0hlYWRlciI
6Ik9UUCBIZWFkZXIiLCJjaGFsbGVuZ2VJbmZvTGFiZWwiOiJPVFAiLCJjaGFsbGVuZ2VJbmZvVGV4dCI6IlBsZWFzZSBlbnRlciB5b3V
yIE9UUCIsImNoYWxsZW5nZUluZm9UZXh0SW5kaWNhdG9yIjoiTiIsImlzc3VlckltYWdlIjp7Im1lZGl1bSI6Imh0dHBzOi8vd3d3LmN
hcmRpbmFsY29tbWVyY2UuY29tL2ltYWdlcy9jYXJkaW5hbC1sb2dvLnN2ZyIsImhpZ2giOiJodHRwczovL3d3dy5jYXJkaW5hbGNvbW1
lcmNlLmNvbS9pbWFnZXMvY2FyZGluYWwtbG9nby5zdmciLCJleHRyYUhpZ2giOiJodHRwczovL3d3dy5jYXJkaW5hbGNvbW1lcmNlLmN
vbS9pbWFnZXMvY2FyZGluYWwtbG9nby5zdmcifSwicHNJbWFnZSI6eyJtZWRpdW0iOiJodHRwczovL3d3dy5jYXJkaW5hbGNvbW1lcmN
lLmNvbS9pbWFnZXMvY2FyZGluYWwtbG9nby5zdmciLCJoaWdoIjoiaHR0cHM6Ly93d3cuY2FyZGluYWxjb21tZXJjZS5jb20vaW1hZ2V
zL2NhcmRpbmFsLWxvZ28uc3ZnIiwiZXh0cmFIaWdoIjoiaHR0cHM6Ly93d3cuY2FyZGluYWxjb21tZXJjZS5jb20vaW1hZ2VzL2NhcmR
pbmFsLWxvZ28uc3ZnIn0sInJlc2VuZEluZm9ybWF0aW9uTGFiZWwiOiJTZW5kIGEgbmV3IE9UUCIsInNka1RyYW5zSUQiOiIzNzYxODR
jMS1hZmJkLTQ2NmMtYTRkZi01OTkwYTFjNTkxMDQiLCJzdWJtaXRBdXRoZW50aWNhdGlvbkxhYmVsIjoiU3VibWl0IiwidHJhbnNTdGF
0dXMiOiJZIiwiYWNzQ291bnRlckF0b1MiOiIwMDAiLCJleHBhbmRJbmZvTGFiZWwiOiJXaHkgdXNlIDNEUyBTZWN1cmU/Pz8/Pz8/Pz8
/PyIsImV4cGFuZEluZm9UZXh0IjoiWW91IHBheSBsb3dlciBpbnRlcmNoYW5nZSByYXRlcyBhbmQgZ2V0IGNoYXJnZWJhY2sgcHJvdGV
jdGlvbiEhISEhISEhISEhIiwid2h5SW5mb0xhYmVsIjoiV2h5IHVzZSAzRFMgU2VjdXJlPyIsIndoeUluZm9UZXh0IjoiWW91IHBheSB
sb3dlciBpbnRlcmNoYW5nZSByYXRlcyBhbmQgZ2V0IGNoYXJnZWJhY2sgcHJvdGVjdGlvbiEifQ==",

 "sdkChallengePayload": "eyJtZXNzYWdlVHlwZSI6IkNSZXMiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI
4NWUxZDA1Mi1iM2NkLTRmM2YtOWVlZC1lMDdjYzQxOTk0OTkiLCJhY3NUcmFuc0lEIjoiM2QzZmVmMDUtMWJmMC00Yjk3LWEyYmUtMTk
5MzQ0YTYwMDg4IiwiYWNzVWlUeXBlIjoiMDEiLCJjaGFsbGVuZ2VBZGRJbmZvIjoiQWRkaXRpb25hbCBpbmZvcm1hdGlvbiBvbiB3aHk
geW91IGFyZSBiZWluZyBjaGFsbGFuZ2VkISIsImNoYWxsZW5nZUNvbXBsZXRpb25JbmQiOiJOIiwiY2hhbGxlbmdlSW5mb0hlYWRlciI
6Ik9UUCBIZWFkZXIiLCJjaGFsbGVuZ2VJbmZvTGFiZWwiOiJPVFAiLCJjaGFsbGVuZ2VJbmZvVGV4dCI6IlBsZWFzZSBlbnRlciB5b3V
yIE9UUCIsImNoYWxsZW5nZUluZm9UZXh0SW5kaWNhdG9yIjoiTiIsImlzc3VlckltYWdlIjp7Im1lZGl1bSI6Imh0dHBzOi8vd3d3LmN
hcmRpbmFsY29tbWVyY2UuY29tL2ltYWdlcy9jYXJkaW5hbC1sb2dvLnN2ZyIsImhpZ2giOiJodHRwczovL3d3dy5jYXJkaW5hbGNvbW1
lcmNlLmNvbS9pbWFnZXMvY2FyZGluYWwtbG9nby5zdmciLCJleHRyYUhpZ2giOiJodHRwczovL3d3dy5jYXJkaW5hbGNvbW1lcmNlLmN
vbS9pbWFnZXMvY2FyZGluYWwtbG9nby5zdmcifSwicHNJbWFnZSI6eyJtZWRpdW0iOiJodHRwczovL3d3dy5jYXJkaW5hbGNvbW1lcmN
lLmNvbS9pbWFnZXMvY2FyZGluYWwtbG9nby5zdmciLCJoaWdoIjoiaHR0cHM6Ly93d3cuY2FyZGluYWxjb21tZXJjZS5jb20vaW1hZ2V
zL2NhcmRpbmFsLWxvZ28uc3ZnIiwiZXh0cmFIaWdoIjoiaHR0cHM6Ly93d3cuY2FyZGluYWxjb21tZXJjZS5jb20vaW1hZ2VzL2NhcmR
pbmFsLWxvZ28uc3ZnIn0sInJlc2VuZEluZm9ybWF0aW9uTGFiZWwiOiJTZW5kIGEgbmV3IE9UUCIsInNka1RyYW5zSUQiOiIzNzYxODR
jMS1hZmJkLTQ2NmMtYTRkZi01OTkwYTFjNTkxMDQiLCJzdWJtaXRBdXRoZW50aWNhdGlvbkxhYmVsIjoiU3VibWl0IiwidHJhbnNTdGF
0dXMiOiJZIiwiYWNzQ291bnRlckF0b1MiOiIwMDAiLCJleHBhbmRJbmZvTGFiZWwiOiJXaHkgdXNlIDNEUyBTZWN1cmU/Pz8/Pz8/Pz8
/PyIsImV4cGFuZEluZm9UZXh0IjoiWW91IHBheSBsb3dlciBpbnRlcmNoYW5nZSByYXRlcyBhbmQgZ2V0IGNoYXJnZWJhY2sgcHJvdGV
jdGlvbiEhISEhISEhISEhIiwid2h5SW5mb0xhYmVsIjoiV2h5IHVzZSAzRFMgU2VjdXJlPyIsIndoeUluZm9UZXh0IjoiWW91IHBheSB
sb3dlciBpbnRlcmNoYW5nZSByYXRlcyBhbmQgZ2V0IGNoYXJnZWJhY2sgcHJvdGVjdGlvbiEifQ=="
 }

The response parameters not contained in the request are described below:

Element Child Element Type Description
id string
length<=36
This is the unique ID returned in the response.
acsUrl string
length<=28
This is the fully qualified URL to redirect the consumer to complete the payer authentication transaction.
xid string
length<=40

This is the transaction identifier returned by the card issuer.

This exists only for 3DS 1.0.2.

status enum

This is the status of the Authentication request. Possible values are:

  • COMPLETED – The transaction has been completed.
  • PENDING – The transaction has not been completed yet.

  • FAILED – The authentication request failed.
threeDEnrollment enum

This indicates whether the cardholder is enrolled in 3D Secure. Possible values are:

  • Y – Cardholder authentication is available
  • N – Cardholder is not enrolled in authentication
  • U – Cardholder authentication unavailable

This only exists for 3DS 1.0.2. If an issuing bank does not support 3D Secure 2, the API will automatically fall back to 3DS 1.0.2 and the threeDEnrollment parameter will replace threeDResult. See Scenarios for more details.

txnTime

string

UTC date format

This is the date and time the request was processed. The ISO 8601 date format is expected, i.e., YYYY-MM-DD-THH:MM:SSZ.
card cardBin string
length=6-8
This is the card Bank Identification Number (BIN). This is typically the first 6 digits of the card.
lastDigits string
length=4
This is the last four digits of the card used for the request.
threeDSecureVersion string
min=5, max=8
This is the 3D secure protocol version.
payload string
length<=2048
This is the encoded Payment Authentication Request generated by the merchant authentication processing system (MAPS).
sdkChallengePayload string
length<=9999
This is a payload that, if returned, should be passed to the challenge function of the JavaScript SDK to continue with the challenge.
Did you find this page useful?