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.