Perform an Enrollment Lookup

POST /threedsecure/v1/accounts/account_id/enrollmentchecks

To perform a 3D Secure enrollment lookup, you must make a POST request to the enrollmentchecks endpoint. This will perform a lookup on the card number and tell you if 3D Secure is available for the transaction you are trying to process. If 3D Secure is available, this call will return the information you need to proceed to the next step in the process.

Request Example
curl -X POST https://api.test.paysafe.com/threedsecure/v1/accounts/89987201/enrollmentchecks \
  -u devcentre322:B-qa2-0-53625f86-302c021476f52bdc9deab7aea876bb28762e62f92fc671e2d0214736abf501e9675e55940e83ef77f5c304edc7968 \
  -H 'Content-type: application/json' \
  -d '{
        "merchantRefNum": "merchantABC-123-enrollmentchecks",
        "amount": 5000,
        "currency" : "USD",
        "customerIp": "172.0.0.1",
        "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1985.125 Safari/537.36",
        "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
        "merchantUrl": "https://www.example.com",
        "card": {
            "cardNum": "4206720814705635",
            "cardExpiry": {
                "month": 2,
                "year": 2027
            }
        }
    }'

Replace the following values to use the example:

  • The API key (after the -u) in the example with the API key you have received.
  • The account_id value in the endpoint URL in the example with your own account ID. This must be the same account ID that you will use later to take payment using the Card Payments API.
  • The currency in the example with the currency of the account referenced by the account_id.

The request contains the following parameters:

Value Type Required? Description Example
acceptHeader string No This is the Accept header from the customer's browser. Up to 2048 characters. Paysafe recommends including this parameter. text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
amount integer Yes The amount in minor units that you wish to charge the customer's card once 3D Secure checks are complete. Use the correct minor units amount for the account currency. Up to 99999999999. 5000
card complex

Yes

Details of either the card used for the request (including cardNum and cardExpiry), or a payment token.

currency string Yes The currency of the account referenced by the account_id URL parameter. Up to 3 characters. USD
customerIp string Yes The customer's IP address. Up to 39 characters. 172.0.0.1
merchantRefNum string 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. Up to 255 characters. merchantABC-123-enrollmentchecks
merchantUrl string Yes This is the fully qualified URL of the merchant's commercial or customer care website. Up to 2048 characters. https://www.example.com
userAgent string Yes This is the User-Agent header from the customer's browser. Up to 256 characters. Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1985.125 Safari/537.36

You can obtain the userAgent and acceptHeader from the cardholder's browser headers upon the submission of the payment request and pass them through with the enrollment lookup.

For a card that is enrolled in 3D Secure, a response with the following structure will be returned:

Response Example
{
    "acsURL": "https://vbv.issueracs.com/3ds/acsendpoint?foo=bar",
    "txnTime": "2014-12-11T12:21:33Z",
    "customerIp": "127.0.0.1",
    "status": "COMPLETED",
    "threeDEnrollment": "Y",
    "merchantRefNum": "merchantABC-123-enrollmentchecks",
    "currency": "USD",
    "amount": 5000,
    "card": {
        "lastDigits": "5635",
        "cardExpiry": {
            "month": 12,
            "year": 2027
        },
        "cardType": "VI"
    },
    "id": "5da985f9-8671-4048-ab85-856be2885ce3",
    "paReq": "eJxVUttOwkAQ/RXCO91LS2nJsEmVqBgwRAlGX0izndgGe2G7pfD37kIr+jZnLmfPnFnYpApx/oayUShghXUdf+EgS2ZDtT9Thzpsd8xHCR5HsR5RvmMeC1xKvdDdudwNfddk6FDAOnrFg4AjqjorC8HMJAfSQ0OsZBoXWkAsD3eLF+GFPKQUSAchR7WYCz9gQeiZwSuEIs5RyBTlvmy0xloDuaRAlk2h1VkE3AfSA2jUt0i1ruopIW3bOlldObLMgdgCkJuIdWOj2hCdskQkOdWfj1u+fH+gy0103nycn7erpI7aaAbEdkASaxScmu05YwPGp5xNXRfIJQ9xbhWIMXeokdMhqOwjUV+ylb8ZMI4rLGS/Q48AT1VZoOkwNvzGQG6S75+si1IbgzxDO+E0YN6Ejn13bP28FCxLZiwxkq80FgCxo6Q7FemObaJ/n+AHOYusjA==",
    "links": [
        {
            "rel": "self",
            "href": "http://apikey@api.test.paysafe.com/threedsecure/v1/accounts/89996498/enrollmentchecks/5da985f9-8671-4048-ab85-856be2885ce3"
        }
    ]
}
  • If the value for the threeDEnrollment parameter = Y, the card is enrolled in 3D Secure. In this case, the result will contain the acsURL and paReq fields that are required to continue the authentication process.
  • If the value for the threeDEnrollment parameter = N, the card is not enrolled in 3D Secure. In this case, you can decide either to submit the authorization for processing via the Card Payments API or to decline the transaction yourself.

The main response parameters are as follows:

Value Type Description Example
acsURL string This is the fully qualified URL for the ACS Server. Up to 256 characters.This value is available only if threeDEnrollment = Y. Redirect the customer to this URL using an HTTP Form Post. https://vbv.issueracs.com/3ds/acsendpoint?foo=bar
card complex

Details of either the card used for the request, or a payment token.

eci integer The e-commerce indicator. Displayed when the card not 3D Secure enrolled. 6
error complex The error code and error message when the enrollment lookup fails.

id string

The ID value returned in the response is used as the enrollment_id in the later 3D Secure authentication call.

It can also be used to lookup this Enrollment lookup. Up to 36 characters.

5da985f9-8671-4048-ab85-856be2885ce3
links array of link objects contains a single "self" link object pointing to this enrollment lookup
paReq string

value required by the ACS Server

eJxVUttOwkAQ/RXCO91LS2nJsEmVqBgwRAlGX0izndgGe2G7pfD37kIr+jZnLmfPnFnYpApx/oayUShghXUdf+EgS2ZDtT9Thzpsd8xHCR5HsR5RvmMeC1xKvdDdudwNfddk6FDAOnrFg4AjqjorC8HMJAfSQ0OsZBoXWkAsD3eLF+GFPKQUSAchR7WYCz9gQeiZwSuEIs5RyBTlvmy0xloDuaRAlk2h1VkE3AfSA2jUt0i1ruopIW3bOlldObLMgdgCkJuIdWOj2hCdskQkOdWfj1u+fH+gy0103nycn7erpI7aaAbEdkASaxScmu05YwPGp5xNXRfIJQ9xbhWIMXeokdMhqOwjUV+ylb8ZMI4rLGS/Q48AT1VZoOkwNvzGQG6S75+si1IbgzxDO+E0YN6Ejn13bP28FCxLZiwxkq80FgCxo6Q7FemObaJ/n+AHOYusjA==
status enum
  • COMPLETED – The transaction has been completed.
  • FAILED - The Enrollment Lookup request failed. Check the error code for details.
COMPLETED
threeDEnrollment enum
  • Y - Cardholder authentication available
  • N - Cardholder not enrolled in authentication
  • U - Cardholder authentication unavailable
Y
txnTime string This is the date and time the request was processed. UTC formatted date. 2016-04-09T17:59:55Z

If the value for the threeDEnrollment parameter = N, you can proceed to authorize the card payment using the Card Payments API.

For more information on liability shift with different 3D Secure responses, see 3D Secure Results and Liability Shift.

See our API Reference section for a list of all the enrollment lookup parameters.

Did you find this page useful?