The enrollment object (3DS)

The enrollment object allows to generate de 3DS transaction.

The cardholder can proceed to secured payments thanks to the 3D Secure protocole (transaction known as a strong authentification). The 3DS protocole improves the merchant protection against fraudulent chargebacks.

CentralPay delivers a complete service that takes care 3D Secure functionnality. Which means, you don’t need to use an external Message Passing Interface (Message Passing Interface)

The 3D Secure payment process starts like regular transactions.

You need to obtain a cardTokenID or use a CustomerID already existing.

Before processing to the transaction, you need to get beforehand those additional information.

  • Check if the card is considered as 3D Secure or not
  • If the card is considerd as 3D Secure you need to get the following parameters: a payer Autentification Request ("Pareq") and a URL pointing through the authentification service of the cardholder’s issuer.

Your customers are redirected on the card issuer’s website to check their Identity using the 3DS process.

You receive back then a confirmation, called as a payment authentification Response "PaRes" to use to finalize the transaction.

Proceed to the following steps for a 3D Secure transaction process:

1Create a card (thanks to the Customer and Cardtoken objects)

  • Create a cardToken (and potentially a Customer)
  • Or you can use a customerID already existing

2Check if the card needs 3D SECURE authentication

  • Execute a chekEnrollment with a cardTokenId or customerId.
  • Keep the field enrollmentId for future use.

3Redirect the cardholder to a Strong Customer Authentication (this process is done by the merchant)

In case of success, take the Payer authentification Request "paReq" and the «acsURL» received during the checkEnrollment execute the following redirection:

<form id="downloadForm" name="downloadForm" method="POST" action="<ASC_bank_url>">
  <input type="hidden" id="PaReq" name="PaReq" value="<value_of_paReq>">
  <input type="hidden" id="TermUrl" name="TermUrl" value"="<return_merchant_url>">
  <input type="hidden" id="MD" name="MD" value="<merchant_description>">

[..] Ds


This process allows to display the interface in which tha cardholder has to complete his personal data.

4Obtaining information from the ACS (this action is done by the merchant)

As en answer from the ACS you get a "paRes"» field.

5Process to the secure transaction

Proceed to a transaction with those 2 additional fields "3ds [enrollmentId]" and "3ds [paRes]":

  • The value of the field enrollmentId is obtained from the checkEnrollment
  • The value of the field paRes is obtained from the ACS

Note: all functions use the "MIME" type: "application/x-www-form-urlencoded".

Test / Sandbox environment

You can test totally the 3D Secure process in our test/sandbox environment. In order to make a simulation of a 3D Secure authenitiftion with the checkEnrollment fonctionality, please use the testing credit card number.

If you wish to proceed to a simulation with a card which is not 3D secure you can use the following numbers : 4100000000000019 and 4100000000000027.

The API will send back a failure message. You won’t be redirected to the ACS authentification window.


Process a 3DS transaction with Acceptance Rules 

An acceptance rule is a logic condition that makes it possible to Authorise, Restrict and/or Prohibit transactions. A rule is comprised of 4 aspects: The action, attributes, operators and values.

  • The syntax of a rule is as follows:
    • "Action" "if" "Attribute" "Relational operators" "Comparison value"
  • Example: REFUSE if card_country != 'FRA' 

The previous example refuses payments if the country of the card is not France. 
The syntax of the grammar selected by the platform for its acceptance engine is very similar to SQL syntax (used to converse with databases).

You can find more details about how to set Acceptance Rules in the API v2 documentation page. Read the content of this chapter if you are interested in applying the CentralPay API v2 rules engine to define the acceptance conditions of a payment.

Rules engine action

Manage a HTTP 307 response

If a transaction request is returned with a HTTP code 307 the merchant should request either a CVC (card verification code), an OTP (one time password) or send a request for 3DSecure.

  • For CVC requested:
    • Add the field cvcValidation with the value submited by cardholder to the transaction.
  • For OTP requested:
    • Add the field otp with the value submitted by cardholder to the transaction.
  • For 3DS requested:
    • Use the checkEnrollment object recieved in the HTTP 307 response to load the URL received in the field checkEnrollment.acsURLwith th following POST parameters:
      • PaReq: use the value of checkEnrollment.paReq.
      • MD: use the value of the checkEnrollment.merchantName.
      • TermUrl: the URL that will be loaded after 3DS validation, it has to read and manage the response from the 3DS bank page.
    • Read the 3DS response and make another transaction request adding the following parameters to the attempted previously:
      • 3ds[paRes] use the value of paRes from the 3DS response.
      • 3ds[enrollmentId] use the value of checkEnrollment.enrollmentId from the previous transaction object

Example of transaction requests after 3DS rule engine action

First transaction request:

curl -v \ -u 'DEMOPSC:eUZG&DVD6cCD' \ -d merchantTransactionId=00201806876 \ -d pointOfSaleId=95f83a22-e0a2-4a57-9457-6fcd8198b82b \ -d amount=2500 \ -d currency=EUR \ -d \ -d customerId=20f26fd6-56a2-492a-9a87-2603c9a77ca5 \ -d cardId=943ed87f-92c6-4546-a312-c187453a9a86 \ -d endUserIp= \ -d order[firstName]=JOHN \ -d order[lastName]=DOE \ -d order[country]=GB \

Response after rule engine action (HTTP response code 307):

{   "checkEnrollment": {     "enrollmentId": "d43fa45f-e7c3-4b40-a886-cffc76d56fa7",     "creationDate": "2018-02-14T12:50:41.591+01:00",     "additionalData": {},     "acsURL": "",     "amount": 2500,     "cardFingerprint": "b384a276872de0bc02bb858cab0a76d0dc9a607e",     "currency": "EUR",     "first6": "400000",     "last4": "0002",     "merchantCountry": "FR",     "merchantName": "Live Demo",     "merchantTransactionIdentifier": "180214125040048",     "merchantURL": "",     "paReq": "eJxVUttuwjAM/ZWq7yVJSUuL3CA... ...J+b6RfubH+fYVvye+/+Q==",     "status": "SUCCESS"   },   "otp": false,   "cvc": false }

Transaction request after 3DS successful validation:

curl -v \ -u 'DEMOPSC:eUZG&DVD6cCD' \ -d merchantTransactionId=00201806876-#act \ -d pointOfSaleId=95f83a22-e0a2-4a57-9457-6fcd8198b82b \ -d amount=2500 \ -d currency=EUR \ -d \ -d customerId=20f26fd6-56a2-492a-9a87-2603c9a77ca5 \ -d cardId=943ed87f-92c6-4546-a312-c187453a9a86 \ -d endUserIp= \ -d order[firstName]=JOHN \ -d order[lastName]=DOE \ -d order[country]=GB \ -d 3ds[enrollmentId]=d43fa45f-e7c3-4b40-a886-cffc76d56fa7 \ -d 3ds[paRes]=eJydVlmzosgSfvdXnDjzaNvsKhPoRLEpss... ...mRz+79T1//eFx+PIif76GvD+W/AatUt1c= \

Mind new fields 3ds[enrollmentId] and 3ds[paRes] added in the second transaction request and the difference in the value of field merchantTransactionId:

  • First transaction request: 00201806876.
  • Second transaction request: 00201806876-#act.

The transaction response returned will contain, among others, the following details:

{   "transactionId": "14b7b7ef-3411-495a-b322-d1a77520b848",   "merchantTransactionId": "00201806876-#act",   "creationDate": "2018-02-14T12:50:52.752+01:00",   "totalAmount": 2500,   "customerId": "20f26fd6-56a2-492a-9a87-2603c9a77ca5",   "card": {     "cardId": "943ed87f-92c6-4546-a312-c187453a9a86",     "customerId": "20f26fd6-56a2-492a-9a87-2603c9a77ca5",     "fingerprint": "b384a276872de0bc02bb858cab0a76d0dc9a607e",   },   "3ds": true,   "endUserIp": "",   "receiptEmail": "",   "pointOfSaleId": "95f83a22-e0a2-4a57-9457-6fcd8198b82b",   "enrollmentId": "d43fa45f-e7c3-4b40-a886-cffc76d56fa7",   "additionalData": {} }

Match successful order reference

After receiving a transaction response from the API you may want to update your order reference in your backoffice/database.

Mind the following note if you set any acceptance rule to verify the transaction either with 3DSCVC or OTP:

If you used this order reference to submit the merchantTransactionId mind to substract the string added (prefixed or suffixed) before matching it with your original order reference.

Mind that you are free to submit additional fields using the additionalData parameter, e.g. additionalData=[referenceId]00032051. All the data sent into the additionalData object will be returned in the transaction response.