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.

See our full API documentation for a complete description of the parameters required for the Enrollment Lookup request.
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
		}
	}
}'

Prior to trying the example, you should:

  • Replace the account number (89987201) in the URL with the test account number you received.
  • Replace the API key (after the -u) in the example with the API key you have received.
  • Replace the currency (USD) in the example with the currency of the account referenced by the account number.

The request contains the following parameters:

Element Child Element Type Required? Description
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.
amount integer
max=99999999999
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.
currency string
length=3
Yes This is the three-digit currency code of the merchant account specified in the account_id request URL parameter account_id.
customerIp

string
length<=39

Yes This is the customer's IP address.
userAgent string
length<=256
Yes This is the User-Agent header from the customer's browser.
acceptHeader string
length<=2048
No This is the Accept header from the customer's browser. Paysafe recommends including this parameter.
merchantUrl string
length<=2048
Yes This is the fully qualified URL of the merchant's commercial or customer care website.
card cardNum

string
length=8-20

Yes This is the card number used for the request.
cardExpiry object Yes

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

  • month – number, length=2
  • year – number, length=4

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 threeDEnrollment = 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 threeDEnrollment = 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 response parameters not contained in the request are described below:

Element Child Element Type Description
acsURL string
length<=255
This is the fully qualified URL for the ACS Server. This value is available only if threeDEnrollment = Y. Redirect the customer to this URL using an HTTP form POST.
txnTime string
UTC date format
This is the date and time the request was processed.
status enum

This is the status of the Enrollment Lookup request. Possible values are:

  • COMPLETED – The transaction has been completed.
  • FAILED – The Enrollment Lookup request failed. Check the error code for details.
threeDEnrollment enum

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

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

string
length=4

This is the last four digits of the card used for the request.
type enum

The type of card used in the request. Possible values are:

  • AM – American Express
  • DC – Discover
  • JC – JCB
  • MC – Mastercard
  • MD – Maestro
  • SO – Solo
  • VI – Visa
  • VD – Visa Debit
  • VE – Visa Electron
id

string
length<=36

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

It can also be used to retrieve this Enrollment Lookup.

paReq string
length<=2048

This is the encoded Payment Authentication Request generated by the merchant authentication processing system (MAPS). This value is required by the ACS server and is available if the value for threeDEnrollment = Y.

links array of link objects This array contains a single self link object which can be used to fetch details about this enrollment lookup at any time.
eci integer This is the e-commerce indicator (ECI). This value is available if threeDEnrollment = N and the card scheme supports non-participating issuers.
error object This is the error code and message if the enrollment lookup request fails.

If the value for threeDEnrollment = 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.

Did you find this page useful?