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.
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 | 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 | 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 | 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:
|
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:
{
"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:
| |
threeDEnrollment | enum | This indicates whether or not the cardholder is enrolled in 3D Secure. Possible values are:
| |
card | lastDigits | string | 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:
| |
id | string | 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.