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.

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.
mcc

string

length=4

No This overrides the static configured merchant code for the specific authentication request.
merchantName

string

length=1-25

No This overrides the static configured merchant name for the specific authentication request.
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
Yes 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.
useAsShippingAddress boolean No Indicates if the billingDetails will be used as shippingDetails as well.
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
  • 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
Did you find this page useful?