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.

iduuid

This is the unique ID returned in the response.

Possible values: <= 36 characters

deviceFingerprintingIduuid

This is the UUID used with device fingerprinting.

Possible values: <= 36 characters

merchantRefNumstring

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

Possible values: <= 255 characters

Example: fc5b62df1202e491475d
processboolean

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

merchantUrlstring

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

Possible values: <= 2048 characters

Example: https://api.qa.paysafe.com/checkout/v2/demo-store/index.html
deviceChannelstring

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

Possible values: [BROWSER, APP, 3RI]

Example: BROWSER
requestorChallengePreferencestring

This indicates whether a challenge is requested for this transaction.

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

messageCategorystring

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

Possible values: [PAYMENT, NON_PAYMENT]

Example: PAYMENT
transactionIntentstring

This identifies the type of transaction being authenticated.

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

authenticationPurposestring

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: [PAYMENT_TRANSACTION, RECURRING_TRANSACTION, INSTALMENT_TRANSACTION, ADD_CARD, MAINTAIN_CARD, EMV_TOKEN_VERIFICATION]

Example: PAYMENT_TRANSACTION
billingCycle object

Details of the billing cycle information for recurring payments.

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

endDatedate

This is the date after which no further authorizations will be performed. The ISO 8601 date format is expected, i.e., YYYY-MM-DD.

frequencynumber

This is the minimum number of days between authorizations.

orderItemDetails object
preOrderItemAvailabilityDatedate

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.

preOrderPurchaseIndicatorstring

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

Possible values: [MERCHANDISE_AVAILABLE, FUTURE_AVAILABILITY]

reorderItemsIndicatorstring

This indicates whether the cardholder is reordering merchandise.

Possible values: [FIRST_TIME_ORDER, REORDER]

shippingIndicatorstring

This is the shipping method for the transaction.

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

purchasedGiftCardDetails object
amountnumber

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

Possible values: <= 99999999999

Example: 1234
countnumber

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

Possible values: <= 99

Example: 2
currencystring

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

Example: USD
userAccountDetails object

These are the user account details from the merchant website.

addCardAttemptsForLastDaynumber

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

changedDatedate

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.

changedRangestring

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: [DURING_TRANSACTION, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS]

createdDatedate

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.

createdRangestring

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: [NO_ACCOUNT, DURING_TRANSACTION, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS]

passwordChangedDatedate

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.

passwordChangedRangestring

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: [NO_CHANGE, DURING_TRANSACTION, LESS_THAN_THIRTY_DAYS, THIRTY_TO_SIXTY_DAYS, MORE_THAN_SIXTY_DAYS]

suspiciousAccountActivityboolean

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

totalPurchasesSixMonthCountnumber

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

Possible values: <= 9999

transactionCountForPreviousDaynumber

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.

Possible values: <= 999

transactionCountForPreviousYearnumber

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.

Possible values: <= 999

shippingDetailsUsage object

This is the shipping usage information.

cardHolderNameMatchboolean

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

initialUsageDatedate

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.

initialUsageRangestring

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

userLogin object

This is the cardholder login information.

authenticationMethodstring

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

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

datastring

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

Possible values: <= 2048 characters

Example: Some up to 2048 bytes undefined data
timedate-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.

createdRangestring

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

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

createdDatedate

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.

idstring

This is the previous authentication ID for the cardholder.

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

Possible values: <= 36 characters

Example: 123e4567-e89b-12d3-a456-426655440000
datastring

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

Example: Some up to 2048 bytes undefined data
methodstring

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

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

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

isAirTravelboolean

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

Default value: false
airlineCarrierstring

This is the selected airline carrier.

Possible values: <= 256 characters

departureDatedate

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.

destinationstring

This is the airport code of the destination airport.

Possible values: <= 5 characters

originstring

This is the airport code of the originating airport.

Possible values: <= 5 characters

passengerFirstNamestring

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

Possible values: <= 99 characters

passengerLastNamestring

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

Possible values: <= 99 characters

priorThreeDSAuthentication object

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

idstring

This is the previous authentication ID for the cardholder.

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

Possible values: <= 36 characters

Example: 123e4567-e89b-12d3-a456-426655440000
datastring

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

Example: Some up to 2048 bytes undefined data
methodstring

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

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

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

cardHolderNameMatchboolean

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

initialUsageDatedate

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.

initialUsageRangestring

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

suspiciousAccountActivityboolean

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

totalPurchasesSixMonthCountnumber

Transaction count for last 6 months.

Possible values: <= 9999

transactionCountForPreviousDaynumber

Transaction count for last 24 hours

Possible values: <= 999

transactionCountForPreviousYearnumber

Transaction count for last 1 year.

Possible values: <= 999

travelDetails object

These are the Amex-specific travel details.

isAirTravelboolean

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

Default value: false
airlineCarrierstring

This is the selected airline carrier.

Possible values: <= 256 characters

departureDatedate

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.

destinationstring

This is the airport code of the destination airport.

Possible values: <= 5 characters

originstring

This is the airport code of the originating airport.

Possible values: <= 5 characters

passengerFirstNamestring

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

Possible values: <= 99 characters

passengerLastNamestring

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

Possible values: <= 99 characters

userLogin object

This is the cardholder login information.

authenticationMethodstring

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

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

datastring

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

Possible values: <= 2048 characters

Example: Some up to 2048 bytes undefined data
timedate-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.

acceptHeaderstringrequired

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

Possible values: <= 2048 characters

colorDepthBitsstringrequired

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

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

customerIpstringrequired

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

javaEnabledbooleanrequired

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

javascriptEnabledbooleanrequired

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

languagestringrequired

This is the language in the browser.

Possible values: <= 8 characters

screenHeightnumberrequired

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

Possible values: <= 999999

screenWidthnumberrequired

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

Possible values: <= 999999

timezoneOffsetnumberrequired

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

Possible values: <= 99999

userAgentstringrequired

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

Possible values: <= 256 characters

cavvstring

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

ecinumber

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

statusstring

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.

Possible values: [COMPLETED, PENDING, FAILED]

threeDResultstring

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

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

txnTimestring

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.

directoryServerTransactionIduuid

This is the directory server transaction ID required for Mastercard.

Note: This exists only for 3D Secure 2.

Possible values: <= 36 characters

threeDSecureVersionstring

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.

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

acsUrlstring

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

payloadstring

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

sdkChallengePayloadstring

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

xidstring

This is the transaction identifier returned by the card issuer.

Note: This exists only for 3DS 1.0.2.

Possible values: <= 40 characters

threeDEnrollmentstring

Possible values for ThreeDEnrollment are:

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

Possible values: [Y, N, U]

maxAuthorizationsForInstalmentPaymentnumber

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

Possible values: >= 1 and <= 999

electronicDelivery object
emailstring

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

Possible values: <= 240 characters

Example: example@example.com
isElectronicDeliveryboolean

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

initialPurchaseTimestring

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.

amountnumber

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

Possible values: <= 99999999999

threeDS
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "deviceFingerprintingId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "merchantRefNum": "fc5b62df1202e491475d",
  "process": true,
  "merchantUrl": "https://api.qa.paysafe.com/checkout/v2/demo-store/index.html",
  "deviceChannel": "BROWSER",
  "requestorChallengePreference": "NO_PREFERENCE",
  "messageCategory": "PAYMENT",
  "transactionIntent": "GOODS_OR_SERVICE_PURCHASE",
  "authenticationPurpose": "PAYMENT_TRANSACTION",
  "billingCycle": {
    "endDate": "2024-07-29",
    "frequency": 0
  },
  "orderItemDetails": {
    "preOrderItemAvailabilityDate": "2024-07-29",
    "preOrderPurchaseIndicator": "MERCHANDISE_AVAILABLE",
    "reorderItemsIndicator": "FIRST_TIME_ORDER",
    "shippingIndicator": "SHIP_TO_BILLING_ADDRESS"
  },
  "purchasedGiftCardDetails": {
    "amount": 1234,
    "count": 2,
    "currency": "USD"
  },
  "userAccountDetails": {
    "addCardAttemptsForLastDay": 0,
    "changedDate": "2024-07-29",
    "changedRange": "DURING_TRANSACTION",
    "createdDate": "2024-07-29",
    "createdRange": "NO_ACCOUNT",
    "passwordChangedDate": "2024-07-29",
    "passwordChangedRange": "NO_CHANGE",
    "suspiciousAccountActivity": true,
    "totalPurchasesSixMonthCount": 0,
    "transactionCountForPreviousDay": 0,
    "transactionCountForPreviousYear": 0,
    "shippingDetailsUsage": {
      "cardHolderNameMatch": true,
      "initialUsageDate": "2024-07-29",
      "initialUsageRange": "CURRENT_TRANSACTION"
    },
    "userLogin": {
      "authenticationMethod": "NO_LOGIN",
      "data": "Some up to 2048 bytes undefined data",
      "time": "2024-07-29T15:51:28.071Z"
    },
    "paymentAccountDetails": {
      "createdRange": "NO_ACCOUNT",
      "createdDate": "2024-07-29"
    },
    "priorThreeDSAuthentication": {
      "id": "123e4567-e89b-12d3-a456-426655440000",
      "data": "Some up to 2048 bytes undefined data",
      "method": "FRICTIONLESS_AUTHENTICATION",
      "time": "2024-07-29T15:51:28.071Z"
    },
    "travelDetails": {
      "isAirTravel": false,
      "airlineCarrier": "string",
      "departureDate": "2024-07-29",
      "destination": "string",
      "origin": "string",
      "passengerFirstName": "string",
      "passengerLastName": "string"
    }
  },
  "priorThreeDSAuthentication": {
    "id": "123e4567-e89b-12d3-a456-426655440000",
    "data": "Some up to 2048 bytes undefined data",
    "method": "FRICTIONLESS_AUTHENTICATION",
    "time": "2024-07-29T15:51:28.071Z"
  },
  "shippingDetailsUsage": {
    "cardHolderNameMatch": true,
    "initialUsageDate": "2024-07-29",
    "initialUsageRange": "CURRENT_TRANSACTION"
  },
  "suspiciousAccountActivity": true,
  "totalPurchasesSixMonthCount": 0,
  "transactionCountForPreviousDay": 0,
  "transactionCountForPreviousYear": 0,
  "travelDetails": {
    "isAirTravel": false,
    "airlineCarrier": "string",
    "departureDate": "2024-07-29",
    "destination": "string",
    "origin": "string",
    "passengerFirstName": "string",
    "passengerLastName": "string"
  },
  "userLogin": {
    "authenticationMethod": "NO_LOGIN",
    "data": "Some up to 2048 bytes undefined data",
    "time": "2024-07-29T15:51:28.071Z"
  },
  "browserDetails": {
    "acceptHeader": "string",
    "colorDepthBits": "1",
    "customerIp": "string",
    "javaEnabled": true,
    "javascriptEnabled": true,
    "language": "string",
    "screenHeight": 0,
    "screenWidth": 0,
    "timezoneOffset": 0,
    "userAgent": "string"
  },
  "cavv": "string",
  "eci": 0,
  "status": "COMPLETED",
  "threeDResult": "Y",
  "txnTime": "string",
  "directoryServerTransactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "threeDSecureVersion": "string",
  "acsUrl": "string",
  "payload": "string",
  "sdkChallengePayload": "string",
  "xid": "string",
  "threeDEnrollment": "Y",
  "maxAuthorizationsForInstalmentPayment": 0,
  "electronicDelivery": {
    "email": "example@example.com",
    "isElectronicDelivery": true
  },
  "initialPurchaseTime": "string",
  "amount": 0
}