Skip to main content

threeDS

Denotes the status of threeDs object. If true and is configured in the backend for the respective accountId, it is mandatory to pass this parameters. If false, parameters need not be passed.

    id uuid

    Possible values: <= 36 characters

    This is the unique ID returned in the response.

    deviceFingerprintingId uuid

    Possible values: <= 36 characters

    This is the UUID used with device fingerprinting.

    merchantRefNum string

    Possible values: <= 255 characters

    This is the merchant reference number created by the merchant and submitted as part of the request. It must be unique for each request.

    process boolean

    This is an indicator representing whether to call authenticate end point or not.

    merchantUrl string

    Possible values: <= 2048 characters

    This is the fully qualified URL of the merchant's commercial or customer care website.

    deviceChannel string

    Possible values: [BROWSER, APP, 3RI]

    This is the type of channel interface used to initiate the transaction.

    requestorChallengePreference string

    Possible values: [NO_PREFERENCE, NO_CHALLENGE_REQUESTED, CHALLENGE_REQUESTED, CHALLENGE_MANDATED]

    This indicates whether a challenge is requested for this transaction.

    messageCategory string

    Possible values: [PAYMENT, NON_PAYMENT]

    This is the category of the message for a specific use case.

    transactionIntent string

    Possible values: [GOODS_OR_SERVICE_PURCHASE, CHECK_ACCEPTANCE, ACCOUNT_FUNDING, QUASI_CASH_TRANSACTION, PREPAID_ACTIVATION]

    This identifies the type of transaction being authenticated.

    authenticationPurpose string

    Possible values: [PAYMENT_TRANSACTION, RECURRING_TRANSACTION, INSTALMENT_TRANSACTION, ADD_CARD, MAINTAIN_CARD, EMV_TOKEN_VERIFICATION]

    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.

    billingCycle

    object

    Details of the billing cycle information for recurring payments.

    Note: This object is required if authenticationPurpose = INSTALMENT_TRANSACTION or RECURRING_TRANSACTION.

    endDate date

    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 number

    This is the minimum number of days between authorizations.

    orderItemDetails

    object

    preOrderItemAvailabilityDate date

    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 string

    Possible values: [MERCHANDISE_AVAILABLE, FUTURE_AVAILABILITY]

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

    reorderItemsIndicator string

    Possible values: [FIRST_TIME_ORDER, REORDER]

    This indicates whether the cardholder is reordering merchandise.

    shippingIndicator string

    Possible values: [SHIP_TO_BILLING_ADDRESS, SHIP_TO_VERIFIED_ADDRESS, SHIP_TO_DIFFERENT_ADDRESS, SHIP_TO_STORE, DIGITAL_GOODS, TRAVEL_AND_EVENT_TICKETS, OTHER]

    This is the shipping method for the transaction.

    purchasedGiftCardDetails

    object

    amount number

    Possible values: <= 99999999999

    This is the amount of the gift card, in minor units.

    count number

    Possible values: <= 99

    This is the total count of individual prepaid or gift cards or codes purchased.

    currency string

    This is the currency of the gift card, e.g., USD or CAD. See Currency Codes

    userAccountDetails

    object

    These are the user account details from the merchant website.

    addCardAttemptsForLastDay number

    This is the number of Add Card attempts in the last 24 hours.

    changedDate date

    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 string

    Possible values: [DURING_TRANSACTION, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS]

    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.

    createdDate date

    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 string

    Possible values: [NO_ACCOUNT, DURING_TRANSACTION, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS]

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

    passwordChangedDate date

    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 string

    Possible values: [NO_CHANGE, DURING_TRANSACTION, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS]

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

    suspiciousAccountActivity boolean

    This indicates whether the 3DS Requestor has experienced suspicious activity, including previous fraud, on the cardholder account.

    totalPurchasesSixMonthCount number

    Possible values: <= 9999

    This is the total number of purchases from this cardholder account in the previous six months.

    transactionCountForPreviousDay number

    Possible values: <= 999

    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 number

    Possible values: <= 999

    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.

    shippingDetailsUsage

    object

    This is the shipping usage information.

    cardHolderNameMatch boolean

    This indicates whether the cardholder name on the account is identical to the shipping name used for this transaction.

    initialUsageDate date

    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 string

    Possible values: [CURRENT_TRANSACTION, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS]

    userLogin

    object

    This is the cardholder login information.

    authenticationMethod string

    Possible values: [NO_LOGIN, INTERNAL_CREDENTIALS, FEDERATED_ID, ISSUER_CREDENTIALS, THIRD_PARY_AUTHENTICATION, FIDO_AUTHENTICATOR]

    This is the mechanism used by the cardholder to authenticate to the 3DS Requestor.

    data string

    Possible values: <= 2048 characters

    This field is reserved for future iterations of 3D Secure 2.

    time date-time

    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.

    paymentAccountDetails

    object

    These are the details of the current payment account of the cardholder.

    createdRange string

    Possible values: [NO_ACCOUNT, DURING_TRANSACTION, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS]

    This indicates the length of time that the payment account was enrolled in the cardholder’s account with the 3DS Requestor.

    createdDate date

    This is the date that the cardholder opened the account with the 3DS Requestor. The ISO 8601 date format is expected, i.e., YYYY-MM-DD.e.

    priorThreeDSAuthentication

    object

    This is the previous authentication information used with current merchant, cardholder, and card.

    id string

    Possible values: <= 36 characters

    This is the previous authentication ID for the cardholder.

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

    data string

    This field is reserved for future iterations of 3D Secure 2.

    method string

    Possible values: [FRICTIONLESS_AUTHENTICATION, ACS_CHALLENGE, AVS_VERIFIED, OTHER_ISSUER_METHOD]

    This is the mechanism used previously by the cardholder to authenticate to the 3DS Requestor.

    time date-time

    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.

    travelDetails

    object

    These are the Amex-specific travel details.

    isAirTravel boolean

    This indicates whether the transaction is an air travel related purchase, e.g., a ticket purchase

    airlineCarrier string

    Possible values: <= 256 characters

    This is the selected airline carrier.

    departureDate date

    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.

    destination string

    Possible values: <= 5 characters

    This is the airport code of the destination airport.

    origin string

    Possible values: <= 5 characters

    This is the airport code of the originating airport.

    passengerFirstName string

    Possible values: <= 99 characters

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

    passengerLastName string

    Possible values: <= 99 characters

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

    priorThreeDSAuthentication

    object

    This is the previous authentication information used with current merchant, cardholder, and card.

    id string

    Possible values: <= 36 characters

    This is the previous authentication ID for the cardholder.

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

    data string

    This field is reserved for future iterations of 3D Secure 2.

    method string

    Possible values: [FRICTIONLESS_AUTHENTICATION, ACS_CHALLENGE, AVS_VERIFIED, OTHER_ISSUER_METHOD]

    This is the mechanism used previously by the cardholder to authenticate to the 3DS Requestor.

    time date-time

    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

    object

    This is the shipping usage information.

    cardHolderNameMatch boolean

    This indicates whether the cardholder name on the account is identical to the shipping name used for this transaction.

    initialUsageDate date

    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 string

    Possible values: [CURRENT_TRANSACTION, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS]

    suspiciousAccountActivity boolean

    This indicates whether the 3DS Requestor has experienced suspicious activity, including previous fraud, on the cardholder account.

    totalPurchasesSixMonthCount number

    Possible values: <= 9999

    Transaction count for last 6 months.

    transactionCountForPreviousDay number

    Possible values: <= 999

    Transaction count for last 24 hours

    transactionCountForPreviousYear number

    Possible values: <= 999

    Transaction count for last 1 year.

    travelDetails

    object

    These are the Amex-specific travel details.

    isAirTravel boolean

    This indicates whether the transaction is an air travel related purchase, e.g., a ticket purchase

    airlineCarrier string

    Possible values: <= 256 characters

    This is the selected airline carrier.

    departureDate date

    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.

    destination string

    Possible values: <= 5 characters

    This is the airport code of the destination airport.

    origin string

    Possible values: <= 5 characters

    This is the airport code of the originating airport.

    passengerFirstName string

    Possible values: <= 99 characters

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

    passengerLastName string

    Possible values: <= 99 characters

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

    userLogin

    object

    This is the cardholder login information.

    authenticationMethod string

    Possible values: [NO_LOGIN, INTERNAL_CREDENTIALS, FEDERATED_ID, ISSUER_CREDENTIALS, THIRD_PARY_AUTHENTICATION, FIDO_AUTHENTICATOR]

    This is the mechanism used by the cardholder to authenticate to the 3DS Requestor.

    data string

    Possible values: <= 2048 characters

    This field is reserved for future iterations of 3D Secure 2.

    time date-time

    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

    object

    These are the browser details.

    Note: This object is not required if the Paysafe SDK is used for device fingerprinting.

    acceptHeader stringrequired

    Possible values: <= 2048 characters

    This is the exact content of the HTTP accept header as sent to the 3DS Requestor from the cardholder’s browser.

    colorDepthBits stringrequired

    Possible values: [1, 4, 5, 15, 16, 24, 32, 48]

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

    customerIp stringrequired

    This is the customer's IP address. Valid Ip address format are IPv4 / IPv6.

    javaEnabled booleanrequired

    This indicates whether the cardholder's browser is able to execute Java.

    javascriptEnabled booleanrequired

    This indicates whether the cardholder's browser is able to execute JavaScript.

    language stringrequired

    Possible values: <= 8 characters

    This is the language in the browser.

    screenHeight numberrequired

    Possible values: <= 999999

    This is the total height of the cardholder’s screen in pixels.

    screenWidth numberrequired

    Possible values: <= 999999

    This is the total width of the cardholder’s screen in pixels.

    timezoneOffset numberrequired

    Possible values: <= 99999

    This is the time-zone offset in minutes between UTC and the local time of the cardholder's browser.

    userAgent stringrequired

    Possible values: <= 256 characters

    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

    cavv string

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

    eci number

    This is the Electronic Commerce Indicator code, which gets returned by the card issuer indicating whether the cardholder was successfully authenticated.

    status string

    Possible values: [COMPLETED, PENDING, FAILED]

    This is the status of the authentication request.

    • COMPLETED – The transaction has been completed.

    • PENDING – The transaction has not been completed yet.

    • FAILED – The authentication request failed.

    threeDResult string

    Possible values: [Y, A, N, U, E, C, R]

    ThreeDResult possible values are:

    • Y - AUTHENTICATION_SUCCESSFUL
    • A - AUTHENTICATION_ATTEMPTED
    • N - AUTHENTICATION_FAILED
    • U - AUTHENTICATION_UNAVAILABLE
    • E - AUTHENTICATION_ERROR
    • C - CHALLENGE_REQUIRED
    • R - REJECTED_TRANSACTION
    txnTime string

    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.

    directoryServerTransactionId uuid

    Possible values: <= 36 characters

    This is the directory server transaction ID required for Mastercard.

    Note: This exists only for 3D Secure 2.

    threeDSecureVersion string

    Possible values: >= 5 characters and <= 8 characters

    This is the 3D Secure protocol version, returned in the response.

    Note: If version 2 is not available for the card provided, the value defaults to 1.0.2.

    acsUrl string

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

    payload string

    This is the encoded Payment Authentication Request generated by the merchant authentication processing system (MAPS).

    sdkChallengePayload string

    This is a payload that, if returned, should be passed to the challenge function of the JavaScript SDK to continue with the challenge.

    xid string

    Possible values: <= 40 characters

    This is the transaction identifier returned by the card issuer.

    Note: This exists only for 3DS 1.0.2.

    threeDEnrollment string

    Possible values: [Y, N, U]

    Possible values for ThreeDEnrollment are:

    • Y - AVAILABLE
    • N - NOT_ENROLLED
    • U - UNAVAILABLE
    maxAuthorizationsForInstalmentPayment number

    Possible values: >= 1 and <= 999

    This is the maxAuthorizationsForInstalmentPayment of the request, in minor units.

    electronicDelivery

    object

    email string

    Possible values: <= 240 characters

    This is the email address to which the merchandise was delivered.

    isElectronicDelivery boolean

    This indicates whether there is an electronic delivery for the product.

    initialPurchaseTime string

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

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

    amount number

    Possible values: <= 99999999999

    This is the amount of the request, in minor units.