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

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

Json

{
    "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.
card	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.

PREV NEXT

Create a TestAccount

Perform an Enrollment Lookup

Create a Test
Account