API objects at a glance
The API is composed of objects allowing to realize specific operations according to needs. The complete list is available here https://ref-api.centralpay.net/.
The most used objects are listed below:
The Cardtoken object
The Cardtoken object is an object that represents the "tokenized" payment card (as a token) that will be used to initiate a transaction.
The transaction object
The transaction object allows to debit your customer from his payment method, usually a credit card, using the cardTokenID that has just been created or from a customer object if it has been previously registered. During a transaction with a cardTokenID, a card object is returned as a cardID.
The enrollment object
enrollement this object allows to check is the card matches with the 3D Secure 1.0 protocole.
The Card object
The Card object represents the sustainable dematerialization of a payment card. It can be associated with a Customer object to allow recurring payment, setting up a subscription or a 1-click payment.
The Customer object
A Customer object represents your customer as a logical entity and allows to consolidate all of its activity.
The refund object
A refund object represents a refund from an existing transaction. This function is accessible once the transaction status is under "cleared" status.
The refund object allows you to refund a transaction already debited. You can refund a transaction partiallly or totally. The credit will appear on your client’s card between 3 to 5 working days after the process.
A refund cannot cannot be cancelled once it is done.
This process is doable from the Backoffice (transaction details) or from the API thanks to the refund object.
The Subscription object
The Subscription object allows you to define recurring payment cycles on one of your customers. They are defined by setting a subscription model:
- Interval unit (day / week / month)
- Interval count (distance between two interval counts)
- Interraction count (number of times the cycle is repeated)
The Installment payment object
The Installment payment object allows you to split an amount into several operations according to a defined intervalUnit, a starting date and potential charges.
You can manage payment sequences with a great agility, for example:
100 euros are charged during the transaction, then 4 payments of 300 euros for 4 months from a defined date.
The hooks object
The Hook objects generate "Events" that are addressed to your information system according to the status of the object with which they interact.
The acceptance rule engine object
If you want to control the mode of transaction acceptance on the "Platform", you can use the acceptance rule engine object.
According to the data context of an incoming transaction (card type, amount, country, currency, anti-fraud score) you can define the action to perform:
- Refuse
- Accept
- Request for OTP (code send by email or sms)
- Request for 3DS
- Request for conditional 3DS (normal transaction if the card is not 3DS)
There are more than a hundred rules available. You can also embed values / data in the rules and use them in a transaction.
The Payment claim object
A PaymentClaim is a payment request that wil be sent by email ou SMS to a customer to pay a transaction.
The transfer object
This object can only be used from an account that has the "Platform" authorization, which is itself a Payment Service Agent. It makes possible to distribute the funds received for a customer from a "Platform" account to the "Basic" account connected according to specific business rules to the Agent.
The transfers are done in this configuration, manually at the initiative of the agent or automatically since instructions given to Centralpay in the transaction.
The Payout object
This object is used to initiate an external transfer to a registered IBAN account beforehand.
The WireTransfer object
The WireTransfer object allows you to set up the incoming transfer receipt in order to address them directly to a specific account.
The cardTokenID object
This object represents the "tokenized" payment card that will be used to initiate a transaction.
The cardToken is created when a credit card is sent from the client's browser using a JavaScript (token.js) put at your disposal. Once the credit card is stored in our PCI-DSS environment, CentralPay returns it back to you as a token: the cardTokenID.
This cardTokenID has a lifetime of 5 minutes, the necessary time to initiate a transaction from your servers. This operation limits your PCI-DSS compliance perimeter since no sensitive data is transmitted or stored by your servers.
Tip: it can be useful once this operation is done to make a GET request on this object to know the attributes of the card allowing the calculation of interchange fees.
SCT Transaction
The "SCT Transaction" service allows you to receive external transfers and to associate them to a payment account. The service works like a transaction (please refer to part Transaction object). However, in order to facilitate the transactions reconciliation, a sepaReference is asked to the person executing the transfer. This reference is provided by the service in response to WireTransfer's request.
To initiate the SCT Transaction you have to define the following data :
- Amount
- Currency
- Transfer
- DestinationWalletId
- Amount
Doing so, when the transfer is received by the platform, it will be automatically assigned to the dedicated payment account concerned.
The transaction object
A transaction represents an accepted, refused or discontinued payment request, an application for authorization, reimbursement or credit or cancellation.
The transaction object allows to debit your customer from his payment method, usually a credit card, using the cardTokenId that has just been created or from a Customer object if it has been previously registered.
During a transaction with a cardTokenID, a Card object is returned as a cardId.
Transactions status
SUCCESS
The transaction has a "success" status when an application for authorization has been issued by the bank. The bank return code is = 0.
Transaction Success can be Capture. If Capture is not done, the card is not debited. You have 7 calendar days to capture a Transaction Success
FRAUD
This status indicates that a transaction encountered a blacklisted element. It can be an IP, a phone number, an email address, or a card number.
CAPTURED
If you "capture" a transaction success, Centralpay wil send charge the card and send the operation to CLEARING
FAILURE
The transaction has a "failure" status when the authorization has not been issued by the Bank issuing the card. You will receive in addition the code (Bank Code < 100)
See the return codes
CANCELED
This status is the cancellation of a capture request before it is cleared. It is possible to cancel a transaction between the transaction status success and cleared.
THREEDS_AUTH_FAILURE
The 3D authentification has failed. The card holder has submitted an incorrect code.
CLEARED
This status indicates that a transaction has been been debited on your customer's card. At this step, you can't Cancell it but you can still REFUND it.
NOT_ACCEPTED
The transaction has been refused because it encountered an element of an acceptance rule.
One-off payment
During the first payment, a CardTokenID is used to create a transaction.
A one-off payment (single transaction) is a transaction during which a debit/credit card is used for a single payment.
Once this step is completed, a Customer object can be created so that it can be used again in case of recurring payments.
There are two ways to manage payment cards during a one-off payment:
You can either use the card sub-object by sending all the data of the payment card (complete card number) that you have in your system (requires PCI-DSS Level 1 approval)
You can either use the CardTokenId object which serves as the unique identifier of a payment card that you obtain by using the Accessible tokenization service from the JavaScript "Token.js".
Recurring payment
To process recurring payments or transactions (1-click, subscription, installment...), you have to create first a Customer object in which one or more cards can be associated. This is processed as a result of a successful first transaction.
For more information, please refer to the "customer" object
Chargeback
A chargeback (also known as unpaid) occurs when a customer (cardholder) contests a transaction with the bank. The issuing Bank of the card then addresses a dispute to the acquiring bank so that it proceed to the payment immediately.
For any credit card payment, your customer has the possibility to contest a payment for up to 13 months. In France, an opposition is allowed only in case of a fraudulent card utilization. However, in other European countries, the bank card can be used as part of a commercial dispute.
Chargeback status:
RETRIEVAL_NOTICED
Object:
A request for information is sent to you by your client in order to obtain information on the nature of the carried out operation. At this stage, it is not considered as an unpaid transaction, however it should evolve according to the answers made.
Action:
To respond by providing the nature of the service issued, proof of customer's consent and/or proof of delivery.
RETRIEVAL_CLOSE
Object:
Notifies that the information request is closed. The provided information will prevent the unpaid.
Action:
No action to carry out
CHARGEBACK_NOTICED
Object:
An unpaid is addressed to you by your client. The transaction amount will be debited from your account in order to allow the refund. A non-refundable processing fee applies for the processing of the dispute.
Action:
You have a 3-week deadline to respond by providing proof of consent of the transaction and/or proof of delivery.
CHARGEBACK_WON
Object:
The unpaid was rejected. The funds will be reimbursed to you.
Action:
No action to carry out
CHARGEBACK_LOST
Object:
The unpaid is retained. The funds will not be reimbursed you.
Action:
No action to carry out
TRANSACTION_REFUNDED
Object:
The funds lost during the chargeback will be reimbursed to you.
Action:
No action to carry out
There is a dispute solution process that consists in contesting, in some cases, the unpaid and to prove that the payment is valid.
- If the dispute revolves in your favour, the amount contested and the expenses are returned to you.
- If a dispute remains confirmed, the card holder will be reimbursed.
A dispute receipt
When a dispute occurs, a notification mentionning the disputed payment is sent to CentralPay. CentralPay will send you as well a notification. An dispute object is created with a status that requires a response. If during your integration you have set up hooks you will also be informed by an event.
You are able to view the status of each of the disputes through the platform, to read the reasons the client has deferred to the card provider, and to deal with the dispute by contesting it either by submitting a relevant "proof" or by accepting it.
Payment receipt
When a transaction has been successfully completed, Centralpay can send a payment confirmation email to the address that is fulfilled in the receiptEmail parameters of the transaction request.
This payment confirmation has a formatted layout displaying the different payment information, however you can configure several settings from the Back-Office at your convenience.
Please check below an example of a payment confirmation email:
List of the elements marked with arrows:
- Sender's email address
- Email sender’s name
- Company logo
- Point of sale name
- Footer content
- Receipt language
Point of sale information:
The elements 1, 2, 3, 4 highlighted are set up in the "Point of sale" prameters of your account:
- In the "Back office", go into "Configuration" > Point of sales > Point of sale details.
- Click on the edition icon: you can complete or edit the fields 1, 2, 3 4 to update your email template.
- Sender's email address
- Email sender’s name
- Company logo
- Point of sale name
Bottom content of the receipt:
- Go to Configuration > "Receipt email templates" and click on the "create" button.
Note: a Merchant Admin profile is requirred to proceed to thoses set ups.
You can now go to the Receipt Email edition page and enter the following parameters:
- A name for the new receipt email template.
- The language selected for this template.
- The point of sale selected for this template.
- Insert a footer template.
The content of the Footer (field number 5) will be displayed at the end of the email.
This template will be used only for the selected point(s) of sale.
The language depends on the parameters of the browserUserAgent, browserAcceptLanguage and enduserLanguage sent in your transaction request.
The Payment Confirmation Language:
If you want the card holder to receive the payment confirmation in a specific language, you must fill in the endUserLanguage value.
Otherwise, the value filled in the browserAcceptLanguage field is used and English by default if nothing is completed.
| endUserLanguage string (2) |
User language (browser default) Required: NO Validation: [a-z]{2} Alpha2 ISO 639-1 language code Note: Payment Receipt language will be defined by endUserLanguage. |
| browserAcceptLanguage string (255) |
List of languages installed in the browser Required: NO Validation: [a-z]{2}([-A-Z]{2})? Alpha2 ISO 639-1 language code and, optional, Alpha2 ISO 3166-2 country code (optional) Examples: de, en-US, en-GB | fr, es-ES, it | es, en-GB, nl, ru |
| browserUserAgent string (255) |
Browser and operating system identifier Required: NO Validation: .{0,255} Example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/64.0.3282.186 Safari/537.36 |
The dispute object
A dispute object (also known as unpaid) is created when a customer (cardholder) contests a transaction with their bank. When a dispute occurs, a notification with the disputed payment is sent to CentralPay who will in turn send you a notification. A dispute object is created with a status requiring a response. If during your integration you’ve configured “hooks”, you’ll also be informed as an event.
You have the possibility to view status of each “disputes” via your platform, to read the reasons that the customer has reported to the card provider, and to deal with the dispute either by challenging it by submitting adequate “evidence” or by accepting it.
For any debit card payment, your customer has the possibility to dispute a payment for up to 13 month. In France, opposition is in principle only allowed in the context of fraudulent card use. However, in other European countries, the debit card can be used in a commercial dispute.
Dispute status :
RETRIEVAL_NOTICED
Object :
A request for information is sent to you in order to obtain information on the nature of the operation carried out. At this stage it is not considered as an unpaid transaction. It may turn into an unpaid transaction depending on the answers provided.
Action :
Answer within 7 days providing the nature of the service delivered, the proof of consent of the customer and/or the proof of delivery. In the absence of answer, your customer will be able to declare an unpaid invoice to his bank.
RETRIEVAL_CLOSE
Object :
Notifies that the information request is closed. The provided information will prevent the unpaid.
Action :
No action to carry out.
CHARGEBACK_NOTICED
Object :
An unpaid is addressed to you by your client. The amount of the transaction will be debited from your account to allow for reimbursement. A non-refundable processing fee will apply for the processing of the dispute.
NB: a Chargeback is not necessarily preceded by a Retrieval (Request for Information).
Action :
You have 20 calendar days to respond by providing proof of consent to the transaction and/or proof of delivery. If you do not respond within this period, it will no longer be possible to dispute the transaction.
NB: Please note that for non-secure transactions (non 3DS), you must provide proof of consent from the cardholder. You must at least make sure that the first and last name of your customer is the same as the one indicated on the payment card.
CHARGEBACK_WON
Object :
The unpaid was rejected. The funds will be reimbursed to you.
Action :
No action to carry out.
CHARGEBACK_LOST
Object :
The unpaid is retained. The funds will not be reimbursed you.
Action :
No action to carry out.
TRANSACTION_REFUNDED
Object :
The funds lost during the chargeback will be reimbursed to you.
Action :
No action to carry out.
There is a dispute solution process that consists in contesting, in some cases, the unpaid and to prove that the payment is valid.
- If the dispute revolves in your favour, the amount contested and the expenses are returned to you.
- If a dispute remains confirmed, the card holder will be reimbursed.
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>">
</form>
[..] Ds
<script>
document.getElementById("downloadForm").Submit();
</script>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.
- Use the checkEnrollment object recieved in the HTTP 307 response to load the URL received in the field checkEnrollment.acsURLwith th following POST parameters:
Example of transaction requests after 3DS rule engine action
First transaction request:
curl -v https://test-api.centralpay.net/v2/rest/transaction \
-u 'DEMOPSC:eUZG&DVD6cCD' \
-d merchantTransactionId=00201806876 \
-d pointOfSaleId=95f83a22-e0a2-4a57-9457-6fcd8198b82b \
-d amount=2500 \
-d currency=EUR \
-d receiptEmail=john.doe@outlook.fr \
-d customerId=20f26fd6-56a2-492a-9a87-2603c9a77ca5 \
-d cardId=943ed87f-92c6-4546-a312-c187453a9a86 \
-d endUserIp=172.24.72.54 \
-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": "https://test-threedsecure.centralpay.net/acs",
"amount": 2500,
"cardFingerprint": "b384a276872de0bc02bb858cab0a76d0dc9a607e",
"currency": "EUR",
"first6": "400000",
"last4": "0002",
"merchantCountry": "FR",
"merchantName": "Live Demo",
"merchantTransactionIdentifier": "180214125040048",
"merchantURL": "https://centralpay.net",
"paReq": "eJxVUttuwjAM/ZWq7yVJSUuL3CA... ...J+b6RfubH+fYVvye+/+Q==",
"status": "SUCCESS"
},
"otp": false,
"cvc": false
}
Transaction request after 3DS successful validation:
curl -v https://test-api.centralpay.net/v2/rest/transaction \
-u 'DEMOPSC:eUZG&DVD6cCD' \
-d merchantTransactionId=00201806876-#act \
-d pointOfSaleId=95f83a22-e0a2-4a57-9457-6fcd8198b82b \
-d amount=2500 \
-d currency=EUR \
-d receiptEmail=john.doe@outlook.fr \
-d customerId=20f26fd6-56a2-492a-9a87-2603c9a77ca5 \
-d cardId=943ed87f-92c6-4546-a312-c187453a9a86 \
-d endUserIp=172.24.72.54 \
-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": "172.24.72.54",
"receiptEmail": "john.doe@outlook.fr",
"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 3DS, CVC 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.
3DS 2.0
3D Secure 2 is a new solution of authentification which restrict fraud and bring a better experience for the consumer. By agreggate and transmit the datas created by the context of shopping, the consumer will not be bothered by the frictions created by a strong authentification. The card emitter (the bank) will thus be in position to know if the consumer is the real person that paid.
Process of the 3DS 2.0
Following, some explanations about the process which differ with the 3DS 1.0 :
Before, to create a 3DS sales, you used the checkEnrollement and obtained the response about if the card was 3DS or not. In the case the card was indeed 3DS, you received the informations required to help the consumers to authentificate at they bank.
You can see this subject is more complex with the 3DS 2.0.
We will show the more important steps of the process :
The great steps of 3D Secure 2.0 :
1) VERSIONING
- This step consist to submit the PAN of the card to the Centralpay API.
- In response :
- If the card is not 3DS 2.0, the transaction rejected. You need to redo the transaction with checkEnrollment (3DS 1.0).
- If the card is 3DS 2.0, you will receive an UUID identifier of the operation from the start till the final result and the datas required to achieve the "3DS Method" (URL + base64)
2)3DS METHOD
- You need to generate a request to the browser of the client ( 1 formular integrated by a hidden iframe create the request, as we insert into it the base64 data)
- This function allow you to insert the base64 data retrieved from the versioning of the ACS.
3)3DS AUTHENTICATION
- This request allow the sending of the contextual data of the consumer
- Possible responses :
- if OK : retrieval of the datas that need to be send in the transaction request (identical to the 3DS 1.0).
- if NOK : refusal
- if challenge : receive the equivalent of the result of the checkEnrolement with URL and base64
4) CHALLENGE
- You need to prepare the iframe used to display the strong authentification formular
- Then, post the result to the ACS
5) REPONSE
- You will receive a end notification of the challenge with Ok or KO
- If the result of the challenge is OK, as it integrate the 3DS datas, it will be received by Centralpay.
6) RESULTAT
- To know the resulte of the challenge response, you need to pass the UUID of the request 3DS 2.0.
- if OK : retrieval of the datas required to the transaction to occurs.
- if NOK : refusal
All this process must take place on the same web page.
For a better understanding of the process, upward is a global schema. For the technical documentation please consult here.
3DS2 authentication types
Le 3DS2 possède deux types d'intégrations possible :
The "BRW" 3DS2 or "Browser Authentication" (participating carrier - 1st transaction)
Represents the majority of 3DS 2 integrations.
It requires the authentication of the customer to verify that he is the legitimate owner of the card at the time of the transaction. It triggers a challenge if necessary to verify the identity of the cardholder (SCA).
The "3RI Authentification" 3DS2 (non-participating holder - Nth payment recurent)
3DS Requestor Initiated (3RI) Authentications, or Merchant Initiated Authentications when the cardholder is not present or participating.
3RI offers the ability to generate the necessary 3DS authentications without the client being involved. This allows to use an authentication previously generated with a client. It is used in the following recurring payment contexts : Payment in X times, Subscription, Refund, etc. .
Download 3DS 2.0 sources
You can download the sources here : 3ds2.zip
Intégration Custom - Exemple
1. PREREQUISITES TO OPERATE THE TEST FORM
- Server configuration :
- PHP 7.2 mini
- PHP Curl activated
- Dependency Manager « Composer » installed
- Configure the site so that all urls are redirected to the index.php file (via an htaccess file [AM1] or a server configuration [AM2])
- Exemple Apache
<Directory "/var/www/htdocs"> RewriteEngine on RewriteBase "/var/www/htdocs" RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule . index.php [L,QSA] </Directory> - Exemple .htaccess
RewriteEngine on RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^.*$ /index.php [L,QSA]
- Configuration CENTRALPAY, you need :
- To hold an API account
- To authorize the HOST of your form in your Account configuration menu (BO Centralpay)
2. INSTALLATION & CONFIGURATION OF THE FORM
- Copy sources to the web server
- Unzip and go to the application directory
- Launch the "composer update" command in order to download the following libraries :
- twig/twig (https://packagist.org/packages/twig/twig)
- curl/curl (https://packagist.org/packages/curl/curl)
- league/rout (https://packagist.org/packages/league/route)
- league/container (https://packagist.org/packages/league/container)
- symfony/dotenv (https://packagist.org/packages/symfony/dotenv)
- laminas/laminas-diactoros (https://packagist.org/packages/laminas/laminas-diactoros)
- laminas/laminas-httphandlerrunner (https://packagist.org/packages/laminas/laminas-httphandlerrunner)
these libraries are necessary for the proper functioning of the 3DS 2.0 test form
- Configure the form using the “.env” file located at the root of the folder.
APP_ENV=dev HOST_CENTRALPAY_API_CORE='https://test-api.centralpay.net/v2/rest/' POS_UUID='change_it' API_USER='change_it' API_PASSWORD='change_it'
| Champ | Description |
|---|---|
| APP_ENV | In development, the code always uses the same IP address (8.8.8.8) In production, use the client's IP address |
| HOST_CENTRALPAY_API_CORE | Centralpay api url: "https://test-api.centralpay.net/v2/rest/" for test mode |
| POS_UUID | Uuid of the point of sale |
| API_USER | API account login |
| API_PASSWORD | API account password |
Once the configuration is done, the form can be used.
3. FOLDERS/FILES STRUCTURE
-
"Css" directory: includes the Bootstrap library to manage the layout of the form
-
"JS" directory: includes the jquery, boostrap and jquery.validate libraries to manage javascript calls, form validation, etc.
-
"Templates" directory: contains the files that manage the display of the form
-
"Vendor" directory: contains the libraries downloaded by composer
-
".env" file: form configuration file
-
"Composer.json" file: Composer configuration file
-
"Index.php" file: file containing all the actions used to manage the form.
4. PAYMENT FORM PAGE
When the form is loaded in your browser, the form displays the following :
Several test card numbers are provided :
| Numéro de carte | Nom de l'action | Description |
|---|---|---|
| 4000001000000091 | BROWSER_CHALLENGE | Challenge to be performed for the payment to be accepted |
| 4000001000000067 | AUTHENTICATED_BROWSER_FRICTIONLESS | Payment accepted without having to make the challenge |
| 4000001000000075 | NOT_AUTHENTICATED_BROWSER_FRICTIONLESS | Payment refused without having to make the challenge |
| 4000000000000002 | Pas dans le range | Payment accepted without having to make the challenge |
5. PRINCIPLE OF OPERATION OF THE FORM
All the stages of the form are carried out on a single page (integrated Iframe mode).
In this example, the checks are basic (fields completed, validity of the email address) : there is no check on the data format for example
13DS Versioning
When the customer clicks on the "Submit" button, if the form data is valid, an ajax call is made to the following Centralpay API url: "3ds2/versioning"
Note : Only the card number is sent to the API.
Example of calling the api in the "index.php" file Tag ##API_VERSIONING##
23DS Method
Request made in the backend by the browser to the bank simultaneously with the authentication.
An Iframe calls the url returned by the "3ds2/versioning" API call.
This url corresponds to the element : " threeDSMethodDataForm.threeDSMethodData " returned by the API.
33DS Authentication
Request made in parallel with the 3DS Method.
Another Ajax call is addressed to the following url of the CentralPay API: "3ds2/authentication
Example of call of the api in the file "index.php" Tag ##API_AUTHENTICATION##
The information sent to the API concerns the client's browser :
- Browser language,
- Screen size,
- and so on.
Other values are also returned such as the following fields :
- threeDSServerTransID : returned by the call to 3ds2/versionning
- acctNumber : card number
- deviceChannel : leave 02
- messageCategory : leave 01
- purchaseAmount : payment amount in cents
- purchaseCurrency : currency of the payment
- threeDSRequestorAuthenticationInd : leave 01
- notificationURL : notification url after the challenge
- threeDSRequestorURL : url of the site calling the API
Based on this data, the api will return a transaction status ("transStatus").
- If Y : the transaction is directly validated,
- If N : the transaction is automatically rejected,
For all other values, a 'challenge' will be required to validate the transaction.
If the client needs to perform a challenge, an Iframe submits a form to the url returned by the API when calling "3ds2/authentication".
This url corresponds to the value : acsURL
The only parameter sent is : crep which includes the value base64EncodedChallengeRequest
At the end of the challenge, the configured url (parameter notificationURL ) in the "3ds2/authentication" call is called.
43DS Challenge
The information about the challenge is available in the variable cres which is accessible with the POST method. This variable is a JSON data encoded in base 64.
To decode this value, the following functions can be used :
$retour = json_decode(base64_decode($_POST['cres']), true)If the value of the variable $retour['threeDSServerTransID'] is equal to Y or A then the client has completed the challenge correctly.
It is then necessary to call the following API url :
" 3ds2/results/'.$retour['threeDSServerTransID']”
Example of calling the api in the file « index.php » Tag ##API_3DS2_RESULTS##
This call will return all the information about the WBS made by the customer. This information will be needed to finalise the transaction.
To finalise this you need to call the API transaction object :
Example of calling the api in the file « index.php » Tag ##API_TRANSACTION##
Available parameters :
| Nom du champ | Description |
|---|---|
| currency | Currency of payment |
| amount | Amount in cents |
| endUserIp | Customer IP address |
| merchantTransactionId | Merchant transaction reference |
| pointOfSaleId | Uuid of the point of sale |
| browserUserAgent | Browser user agent |
| browserAcceptLanguage | Browser language |
| card[number] | Bank card number |
| card[cvc] | Cvc of the bank card |
| card[expirationMonth] | Month of expiry of the bank card |
| card[expirationYear] | Year of expiry of the bank card |
| card[holderName] | Name of the cardholder |
| order[cardholderEmail] | Customer email |
| card[holderEmail] | Customer email |
| order[firstName] | Customer's first name |
| order[email] | Customer email |
| 3ds[xid] | Unique identifier of the 3ds auto generated by the merchant site |
| 3ds[cavv] | AuthenticationValue received from the 3ds2/result call |
| 3ds[eci] | Eci is received from the 3ds2/result call |
| 3ds[status] | TransStatus received from the 3ds2/result call |
| 3ds[threeDSServerTransID] | The ID of the 3DS server received from the 3ds2/result call |
If the http return code of the transaction is equal to 200, then the transaction is valid.
ANNEX A: DIAGRAM
ANNEX B: SAMPLE FORM
Payment form
Challenge
- 1234 returns Y for successful Challenge
- 4444 returns A for successful Challenge
- 1111 returns N for Challenge failed
- 2222 returns R for Challenge failed
- 3333 returns U for Challenge failed
Paramètres 3DS2.0
The "transStatus" parameters :
Valeurs :
- Y = Authentication verification successful.
- N = Not authenticated / Account not verified. Transaction declined.
- U = Authentication/account verification could not be completed. Technical or other problem, as indicated in ARes or RReq.
- A = Attempts processed. Not authenticated/verified, but proof of attempted authentication/verification is provided.
- C = Challenge required. Additional authentication is required using CReq/CRes.
- D = Challenge required. Decoupled authentication confirmed.
- R = Account authentication/verification rejected. Issuer rejects authentication/verification and requests not to attempt authorization.
- I = Information only. Acknowledgement of the requester's preference for the 3DS challenge.
F.A.Q. 3DS2.0
Frequently asked questions about 3-D Secure 2.0.
Are there any test cards to do 3DS2 transactions in a test environment?
- Yes, here is the link to the test cards for the test environment :
https://ref-api.centralpay.net/glossary-0#77-test-cards
Authentication BRW/3RI ?
CentralPay EMV® 3-D Secure supports 2 device channels : Browser-based (BRW) and 3DS Requestor Initiated (3RI).
The Browser flow (BRW) in EMV® 3-D Secure, is an enhanced flow compared to its predecessor. During a Browser flow, the 3DS Method is used to allow the ACS to obtain additional browser information before the authentication is started.
The 3DS Requestor Initiated (3RI) is used to confirm account information when the cardholder is not directly involved (e.g. confirm that an account is still valid in a subscription).
Frequent refusal bank return code in 3DS2
My transaction received the bank return code 5, what does this mean ?
- This means, that the bank refuses without giving any particular status.
It could be a wrong CVV code or another decision that we do not know.
This status does not mean that the bank will not accept the authorization after further attempts.
My transaction received the bank return code 12, what does this mean ?
- This means that the bank refuses without giving any particular status.
The reason can be :
- Simply an invalid transaction
- A code 75 from the issuing bank (the PIN code of the card has been incorrect too many times)
- A wrong CAVV (provided by the ACS during a 3DS authentication)
- Or another decision that we do not know.
Questions & Answers
The transaction API returns a "Soft Decline" error, but the "threeDSServerTransID" parameter is the one returned by the cres.
How should we interpret this return and what should we do ?
- The soft decline is returned by the bank when the 3DS is not present in the transaction.
Check if any of the fields presented in this part of the documentation are missing : https://ref-api.centralpay.net/payment#106-3ds-sub-object
My Versioning request returns a "404" error with the message "Card account number not found in card ranges from Directory Server".
What does this mean and what should I do?
- This means that the card used is not enrolled in 3DS2.0 and that the transaction cannot be made in 3DS2.0.
In this case, we advise you to switch to 3DS1 for this type of card.
The response from the Result query returned the transStatus to U.
How should we interpret this return and what should we do in this case?
-
The value U of transStatus in response to the result request means that the authentication or verification could not be done due to a technical problem or other problems.
On the side of the smart form during the challenge with the result request, only the values Y and A allow to validate the challenge and to continue the payment.
The other values make the challenge and the payment fail.
But in the case of a custom form the operation can be different, you can use the value U to make a new challenge attempt and if it fails again then the payment goes to 3DS1 or is refused, or to directly retry the payment in 3DS1 or consider it as a payment failure.
These different cases are possible to realize.
We submitted the form to the url returned by the authentication with the base64EncodedChallengeRequest.
But the client came back to our site without CRES but with an ERROR parameter containing the value "eyJ0aHJlZURTU...Mi4xLjAifQ==" and the "THREEDSSESSIONDATA" parameter which was empty.
How should we interpret this return and what should we do in this case?
- When you get this kind of feedback, you should check that your 3DS2 process is running on a single page with the iframe solution.
If the process is compliant then contact the technical support with the necessary information.
As a reminder, all the steps of the form are done on a single page without redirection to a bank page or other.
This is done thanks to the Iframe solution.
The whole 3DS2.0 procedure is on the same page!
We received a 303 error: "acquirerBIN, acquirerMerchantID not recognized" when calling authentication.
How should we interpret this return and what should we do in this case?
- It is either the contract that is not 3DS2 or other problems.
In the case of another problem, you must contact the technical support by providing the electronic payment contract number (if known) and other information that may be necessary.
On the authentication step, we got an error 203: "Validation of 3DS Requestor Authentication data failed.
Data element not in the required format or value is invalid" for the merchant.merchantName field.
How should we interpret this feedback and what should we do in this case?
- Error 203 means that there is an invalid character in the "merchant.merchantName" parameter.
When calling the 3DS2 function "authentication", the following error is returned in the "card data" key: "There is no unique source of card".
What does this mean?
- The error "There is no unique source of card" is common to the whole platform and is present when you send card information twice: for example via a cardToken and a cardId or a PAN and a cardToken etc.
Versioning query, two possible answers ?
Version 1 (most frequent) :
{
"threeDSServerTransID":"9cc6b33c-dd35-4fbd-81cd-fd9cf0aeed9c",
"threeDSMethodURL":"https://test-3dss-demo.centralpay.net/acs/3ds-method",
"threeDSMethodDataForm":{
"threeDSMethodData":"eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly90ZXN0LTNkc3MuY2VudHJhbHBheS5uZXQvM2RzLzNkcy1tZXRob2Qtbm90aWZpY2F0aW9uLyIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiOWNjNmIzM2MtZGQzNS00ZmJkLTgxY2QtZmQ5Y2YwYWVlZDljIn0="
},
"errorDetails": null
}
This response is returned when the bank needs the acs url in the authentication request.
Version 2 :
{
"threeDSServerTransID":"9cc6b33c-dd35-4fbd-81cd-fd9cf0aeed9c",
"threeDSMethodURL": null,
"threeDSMethodDataForm": null,
"errorDetails": null
}
This response is returned when the bank does not need the acs url in the authentication request.
The versioning returns a response where only "threeDSServerTransID" has a non-null value.
The Card object
The Card object represents a sustainable dematerialization of a payment card. It can be associated to a customer object to allow recurring payment, setting up a subscription or a 1-click payment.
As a consequence, you no longer need to store cards on your servers. Once this feature is implemented in a customer object you can process secure recurring payments with a single click.
This object also includes attributes related to the issue context of the card. A GET request on a cardId can reveal :
- commercialBrand: MASTERCARD ou VISA ou aMEX...
- cardType: DEBIT, CREDIT, PREPAID
- region: EU, USA...
- productType: CORPORATE, CONSUMER
- Product: Electron, gold
- Country: France...
- EEA: yes / no
The customer object
A customer object is the logical representation of your customer that is equivalent to a container of means of payment. In other words, you can store several cards that will all have a cardId. The customer object has the main advantage of collecting all the transactions that have been carried out on a customer:
- Transaction
- Refund
- Chargeback
- Subscription
Thanks to this object, one or more cards can be associated allowing you to keep the payment data without having to store the card numbers in your databases.
A customer is identified by his email, surname and first name. You can associate payment means, in other words cards, in order to carry out recurring payments:
- 1 clic payment
- Subscription payment
- X multi payment - installment
The customer has no longer need to be asked to re-enter his card number once registered in his customer profile.
Tip: please be careful not to register twice the same card as it would add more time to the customer object query.
The refund object
This object helps you to create refunds for already cleared transations.
You can refund totally or partially a transaction. The refund debit the account of the user who created the request. Your customer will see the operation in their account 3 to 5 days later.
Please note : You cannot cancel a refund after it was completed.
This operation can be accomplished from the Back Office, or from the API directly via the Refund object.
Smart Form
Simple to integrate, Smart Form is a smart payment form accessible by the API via the paymentRequest service. Hosted in CentralPay’s PCI-DSS area, it includes essential features to payment needs.
By using Smart Form, you avoid the most restrictive part of PCI-DSS requirements. All sensitive data is processed directly in CentralPay’s PCI-DSS environment. Therefore, credit card data never passes through your server.
Smart Form is linked to the following services :
- paymentRequest service that initiates payment claims
- “Push & Pay” service that automates and issues notifications
With Smart Form, most complex parts of the process are managed by CentralPay :
- Generating and hosting payment form,
- Verifying users information,
- Managing the various payment methods,
- Securing cards data,
- Generating payment reminders or requests,
- Managing the different payment methods and types.
The service is accessible through :
- CentralPay API integrated with a third party Information System :
- By HTTPS redirect to a website
- By e-mail/SMS notifications
- By displaying or printing a QR Code
- The web console or CentralPay mobile application :
- By e-mail/SMS notifications
- By displaying or printing a QR Code
Example of Smart Form
Available payment methods
CREDIT CARDS
Visa, Mastercard, Amex, Bancontact…
CREDIT CARDS
Payment in installments to stagger your customers payments.
Visa, Mastercard, CB
E-WALLET AND LOCAL PAYMENT SYSTEMS
PayPal, Alpay, WeChat, Ideal…
HOLIDAY VOUCHERS
ANCV
FIDELYPAY
Cashback, discounts, fidelity points
TRANSFER
SCT (SEPA Credit Transfer)
Choice of payment methods :
- Point of sale configuration defines the payment methods that will be accessible to the customer.
- Depending on the desirable interactions between combined payments, some methods may not be available.
Combined with the Push & Pay service, a Smart Form can integrate recurring payment methods :
- Multi-participants payments
- Combined payments on several payment methods
- Automation of requests, reminders and notifications
Payment request
paymentRequest defines terms and conditions of payment of an amount to be cashed. The instruction can be initiated to be either transmitted live from an HTTPS redirection from a website to the payment form, or from the PUSH & PAY service by e-mail/SMS notification or by displaying a QR Code.
With the PUSH & PAY service, it is possible to create complex workflows that allow for advanced interaction with consumers or third-party platforms. You need to set up email/SMS templates and scenarios before using this object.
Operation of a payment request
A payment claim allows to reserve an amount to be settled according to the terms defined in its request.
- Fixed amount :
- The settlement is set at a single amount (totalAmount).
- The Payer will not be able to change the amount.
- Free amount / Pay with multiples cards :
- The customer can pay the amount he wants and use several cards.
- To initiate a free amount, dont send a breakdown amount
- Fixed amount with staggered payment with installment :
- Allows the initial amount to be split into several payments (Installment) according to a defined frequency.
- Partial amount :
- The payment amount is free. The Payer will be able to pay in multiple installments by setting the amount himself or by re-filing the payment request to third parties.
- To initiate a partial amount and leave the cardholder to pay with more than one card, set the breakdown amount blank (Ex : -F breakdown[]='{"amount":, "email":"johnDoe@hotmail.com"}'.)
- Multi-participants payment based on fixed amounts :
- The total amount is broken down into several sub-amounts that are allocated to each participant.
- Each participant will then receive a notification by e-mail or SMS allowing them to go to the payment page in order to pay the amount allocated to them.
The configuration is equivalent to filling in the following data according to the context :
| I'm paying | |||||
|---|---|---|---|---|---|
| Alone | With several people | ||||
| Recipient | Amount | Recipient | Amount | ||
| Amount | Partial | @1 --> | N/A | @1 --> @2 --> @3 --> |
N/A N/A N/A |
| Fixed | @1 --> | 1 000 € | @1 --> @2 --> @3 --> |
500 € 300 € 200 € |
|
A successful payment request addresses in response :
- The address of the payment form and associated features in the form of :
- QR CODE
- URL
- UUID of the request
The list of available payment methods can be configured at the point of sale defined by :
- Crédit Card
- Credit Card (installment payments)
- redit Card (subscription)
- Holidays vouchers
- Transfer
- Wallet
- FidelyPay
STATUS
| Request status |
|
| Payment status |
|
| Breakdown status |
|
| Notification |
|
Initialization of requests
Payment requisitions are initializable from :
- CentralPay API
- CentralPay console
- CentralPay mobile app
Types of payment request
There are 3 types of payment requests in the backoffice :
1/ Instantaneous requests :
They are characterized in the interface by a lightning symbol and can be created as follows :
They include the possibility to carry out transactions, guarantees, subscriptions, X payments and transfers. It is also possible to create customers by saving your customer data, or to search for existing customers.
From it, it is possible to directly upload a CSV or JSON file, or to download a model (the data is fictitious and given as an example).
The "force import" option allows to submit the import despite syntax errors.
Additional settings will be available to configure X times payments and subscriptions :
2/ Programmed requests
They are characterized in the interface by a clock symbol and can be created as follows :
They include the same options as the instantaneous ones such as the possibility to carry out transactions, deposits, subscriptions, X times payments and transfers. It is also possible to create customers by saving your customer data, or to search for existing customers.
The difference with instant payment requests lies in the possibility of using a special profile, as well as some options :
- A payment deadline can be added, after which your customer will not be able to pay anymore.
- An expiration deadline, which is the date from which the payment form expires.
- The addition of a scenario that will allow you to configure specific notifications on this payment request.
- The addition of a payment confirmation email.
- Added a language for the payment request.
- A display rule that allows you to choose a display template and a custom SMART FORM if needed.
- The sending of an Attachment in the payment confirmation email.
3/ Importation of bulk payment request
The functionality is available from the import button on the payment request listing page (Backoffice 10.7.0) :
Be carefull, to have access to this functionality, you must be connected in Merchant and have the ACL 'cpay_core_payment_request' in CREATE.
When you click on the import button, a popin appears :
From it, it is possible to directly upload a CSV or JSON file, or to download a model (the data is fictitious and given as an example).
The "force import" option allows to submit the import despite syntax errors.
Listing of the fields of the file to be imported :
|
Label |
Description |
Comments |
|
profile_uuid* |
Payment Request Profile UUID |
Must exist and belong to the merchant Mandatory |
|
merchant_payment_request_id |
Merchant reference |
Between 0 and 100 characters |
|
description |
Description |
Between 0 and 255 characters |
|
total_amount* |
Amount of the request for payment |
Must be > 0 Mandatory |
|
last_name |
Name |
Between 0 and 35 characters |
|
first_name |
First name |
Between 0 and 35 characters |
|
Email * si phone vide |
|
Mandatory if Phone is empty Between 0 and 255 characters
*If the email is present in the Customer database (and create_customer to N), the Customer data will be taken over. *If the email (and possibly name and surname) is associated with several Customers, the last created will be taken over. |
|
Phone * si email vide |
Phone |
Required if Email is empty Between 0 and 255 characters International Format : ^\\+[0-9]{1,15}$ Ex : +33612345678
*If email is provided and is present in the Customer database (and create_customer to N), the Customer's data will be taken over.
*If an email is provided (and possibly name and surname) and is associated with several Customers, the last created will be taken over. |
|
create_customer* |
Create a customer |
Possible value : "Y" (yes) or "N" (no) Mandatory |
|
link_expiration_date |
Payment deadline |
if completed, overwrites the payment request profile.
Format: YYYY-MM-DD Must be > in NOW |
|
deadline |
Expiration date of the link |
if completed, overwrites the one in the payment request profile
Format: YYYY-MM-DD Must be > in NOW |
|
receipt_email |
Email of receipt confirmation of payment |
if completed, overwrites the payment request profile.
If not filled in, the value of the email field will be taken over. |
|
language |
Language used in the application |
if completed, overwrites the payment request profile. The default is : English. |
Be careful, it is necessary to put all the fields in the file, in no particular order.
If the file contains errors with respect to the constraints listed above, an error message will be displayed at the top of the popin so that the merchant can correct his :
If the file passes the checks, the merchant will be redirected to the payment request listing page with a :
It is then the batch that will create the payment requests and send a summary email to the email address of the profile that created the import.
Payment Request Profile
The profiles are linked to the Push & Pay service and to the payment requests. The profiles contain the parameters of the payment requests and the possibility to choose a scenario. They will constitute templates of already pre-made behaviors that will be automatically applied to the payment requests in which the profile will be selected. They can then be used in scheduled payment requests and mass payment requests.
In the general configuration part, it is possible to choose a name, a point of sale, a currency linked to the point of sale and a language, which will influence the language in which the information will be displayed for your customers.
In the payment methods section, it is possible to choose the nature of the payment request (Transaction, Deposit, Payment in X times, subscription or transfer).
Finally, in the options, it is possible to choose a payment limit (after which your customer will no longer be able to pay), a link expiration limit (after which your customer will no longer be able to pay through the form specifically), the possibility of choosing a scenario that will send notifications at key moments of the payment request, a payment confirmation reception email, display rules, the possibility of adding attachments and finally the possibility of automatically creating customers as soon as the profile is used.
Display rule - Smart form settings and redirection
Form settings are SMART FORM templates, customized according to your needs
They are called “Display Rules” in the payment request creation.
These templates are already integrated in the programmed payment requests, by a choice or via the chosen profile. They are also included in bulk payment requests via the chosen profile.
The available fields for templates are: the name of the template, the possibility to make the template by default, the possibility to display the CVV field as well as the possibility to force the creation of a customer. Also available are the fields including the redirection URL as well as the delay of redirection.
Finally, it is possible to add additional fields to the automatically generated forms, the checked fields will be added to the fields already present on the classic SMART FORM. The fields added may be delayed if the template is used for transfers or for a payment request by credit card.
The list of additional fields is as follows:
- Address 1
- Address 2
- Address 3
- Address 4
- City
- Country
- First name
Smart form integration
We will show you the different steps involved in a standard integration of our Smart Form.
First, you have to initialize a payment request with the payment information you want and that you have collected from the client. The initialization is usually done via a php curl. You can find a PHP curl on our example site.
For reasons of readability of the information sent, our example will be done in native cURL.
Native cURL example :
curl --location --request POST 'https://test-api.centralpay.net/v2/rest/paymentRequest' \
--header 'Authorization: Basic ZG9jdGVzdDo0STlISlJUZA==' \
--form 'paymentMethod[]="TRANSACTION"' \
--form 'currency="EUR"' \
--form 'totalAmount="100000"' \
--form 'partial="false"' \
--form 'breakdown[]="{amout:100000, email:johnDoe@hotmail.com}"' \
--form 'transfer[]="{destinationWalletId:10cfe034-ba9a-457e-b13d-fc68a5bfd171, amount:100000, email:johnDoe@hotmail.com}"'
Once this Payment request is correctly initiated, we return a JSON response. The information to display the smart form is present in this response, so you must retrieve and process it in order to retrieve the endpoint(s). There are several endpoints if you initiate a payment request with several payers, and therefore several breakdowns.
Example curl response :
{
"paymentRequestId": "4cd3c57c-a71e-4e5d-832c-46e0b30d85c6",
"creationDate": "2021-06-10T12:34:44.386219+02:00",
"pointOfSaleId": "cfc0b3c7-e666-4c52-b77a-96f234b873fe",
"deadline": null,
"linkExpirationDate": null,
"endingDate": null,
"scenarioId": null,
"scenarioStartingDate": null,
"paymentFormTemplateId": null,
"merchantPaymentRequestId": null,
"description": null,
"currency": "EUR",
"totalAmount": 100000,
"paymentRequestStatus": "ACTIVE",
"paymentStatus": "UNPAID",
"createCustomer": false,
"paymentMethods": [
"TRANSACTION"
],
"transaction": {
"paymentRequestTransactionId": "a094ba26-d5e3-41e1-a9d4-4d88bc6f838e",
"contractId": "71602dd0-2790-4743-877b-e72530d7576d",
"receiptEmail": null,
"source": "EC",
"capture": true,
"customAcceptanceData": {}
},
"installment": null,
"subscription": null,
"breakdowns": [
{
"paymentRequestBreakdownId": "d3d48c4d-50d8-46d1-ba54-720b673dcc27",
"customerId": null,
"lastEnteringDate": null,
"lastPaymentAttempt": null,
"amount": null,
"initiator": true,
"endpoint": "https://test-form.centralpay.net/b670bb15-c243-450c-aa2b-ea6b077231e2",
"email": "johnDoe@hotmail.com",
"phone": null,
"firstName": null,
"lastName": null,
"entered": false,
"paymentAttempted": false,
"paid": false,
"view": 0,
"payments": []
}
],
"transfers": [
{
"destinationWalletId": "10cfe034-ba9a-457e-b13d-fc68a5bfd171",
"escrowDate": null,
"amount": 100000,
"fee": 0,
"merchantTransferId": null
}
],
"wireTransfer": null,
"transferGroup": null,
"attachments": [],
"language": "eng",
"redirectUrl": null,
"closeComment": null,
"additionalData": {}
}Example of an endpoint :
"endpoint": "https://test-form.centralpay.net/b670bb15-c243-450c-aa2b-ea6b077231e2"
The last step is to display the smart form to your customer. You can either display the smart form in another page, or integrate it directly into your page via an iframe.
Example of iframe :
<!DOCTYPE html>
<html>
<head>
<title></title>
</head>
<body>
<iframe src="https://test-form.centralpay.net/b670bb15-c243-450c-aa2b-ea6b077231e2/transaction" id="iframeForm" width="1000" height="1000"></iframe>
</body>
</html>
Custom Form
Custom Form allows you to create your own payment forms and consume API objects in a unitary way in order to create a unique payment experience fully integrated into your services.
Therefore, a Custom Form is created and hosted by you while allowing you to strongly reduce the security risks when handling banking data. By integrating the payment process on your side, you keep control of the payment page and user experience.
Custom Form allows consumption of certain services not supported by Smart Form like subscription payments (subscription) or one-click upsell payment.
Example of Custom Form
Custom Form tutorial
This tutorial explains how to create transaction from your own payment form by using HTML and JavaScript languages (token.js) with a cardTokenID.
Token.js is the dedicated JavaScript that allows you to get the first required component called cardTokenID.
Once you get a cardTokenID, you are now able to create a transaction in order to debit your customer card.
Required steps :
1Creating an HTML payment form
Contrary to the SMART form which is generated by the platform, the CUSTOM form is to be created.
So you need to generate the HTML code at your convenience.
2Sending the debit/ credit card information with the Token.js
At this stage, you have now to send the card data from the client browser to the PCI platform. The platform will send you back a cardTokenId. To get it done you need to add the following script tag in the <body> part at the end of your code.
<script src="https://test-js.centralpay.net/js/token.js"></script>Then your merchantPublicKey in a separe tag.
<script type="text/javascript">
window.Centralpay ? Centralpay.card.setMerchantPublicKey('8ce4b92abd7c3110e2033ffbfa7cca0f097a66f1f1d267ff6c94429884ed82ac') : alert('Error loading html form');
</script>The merchantPublicKey identifies your requests to the platform. In the example above, you will have to use the one that has been sent to you.
3Getting back the cardTokenID in your system
This step consists in getting back the cardTokenID contained in the JavaScript in order to submit your request to the platform.
All card data are now stored in the cardTokenId for a duration of 5 minutes. This value is sent to the API instead of the sensitive credit card data.
4Submitting the form from your server
Now that you have a cardTokenID you can use it to trigger a transaction.
Unlike the previous steps that take place from the browser, this operation is executed from your servers. For example :
curl -v https://test-api.centralpay.net/v2/rest/transaction \
-u 'DEMOPSC:eUZG&DVD6cCD' \
-d amount= 100
-d currency= EUR
-d cardTokenId=d5bc9bec-aec2-4b92-b45c-23d53719a058 \
-d endUserIp=92.154.127.221 \5Saving the card information in a customer object in order to use it afterwards (1 click, subscription…)
CentralPay's cardTokenId can only be used once, but if you plan to use it afterwards, you need to create a customer object in which you can store all cards details.
Instead of charging the card immediately, you have to create a customer object. CentralPay then stores a cardtoken within this customer object during the process. This precise action will allow you to charge the customer at any time in the future.
SDD Transaction
An SDDTransaction is a direct account-to-account between a merchant (creditor) and a customer (debtor).
The first pre-requisite for a SDDTransaction to occurs is two bank account with the right types must exist. Only your (a merchant) account can be a creditor account. The debtor account can be created by the following process. The second pre-requisite is a Mandate must be signed by the two parts.
The steps to create a SDDTransaction
1Create a bank Account Identity (debtor)
- Retrieve the customer informations (and evenually create a customer)
- Once an identity created, an identityId will be generated
2Create the bank Account (with the identityId and the customer object)
- Retrive new informations from the customer
- Transmits it to us, with the identityId and the customerId of your customer
- A bankAccountId will be generated at the creation
3Create a mandate (with the two bankAccountId and the customer object)
- Multiple Mandates can be created with the two same bank accounts.
- Determine a type of mandate (Ponctual or Recurrent).
- Transmits to us the informations of the mandate, with the bankAccountId of the creditor, the bankAccountId of the debtor and the customerId
- A mandateId and an OTP will be generate at the creation. The OTP will be sent at your customer via SMS.
The OTP is a secret code system the customer will receive, and it will allow you and your customer to validate or sign contract safely.
The OTP has a lifespan of 15 minutes, so it is possible to renew it with or without a new phone number.
4Sign the mandate (with the OTP)
- Retrieve the secret code of your customer
- Transmits it to us, with the mandateId
- By this action, the mandate is regarded as sign by the two parts
5.1Create a SDDTransaction (with the mandate)
- You can now create a SDDTransaction.
- Configure your SDDTransaction, by enquire your wanted informations, and join the mandateId
- For more safety, you can force an OTP for he validation of each SDDTransaction : in this case, an OTP will be generated at the creation and sent at your customer via SMS. A sddTransactionId will also be generated at the creation.
- By default, the validation of the SDDTransaction is automatic.
5.2Validate the SDDTransaction (if an OTP validation has been configured)
- This step is necessary if you configured an OTP validation for the SDDTransaction
- Retrieve the secret code of your customer
- Transmits it to us, with the sddTransactionId .
- By this action, the SDDTransaction is regarded as validated and will be executed.
Here is the schema of the SDDTransaction, and for more technical informations you can visit the associate documentation :
And the schema of the SDDTransaction, if an OTP validation is configured :
Virtual IBAN
In order to facilitate the SEPA Credit Transfer (SCT) from a customer to his merchant, we have set the "virtual IBAN" up. With this solution you won't need to use SCT references anymore, each customer will have an unique virtual IBAN. You can find it in 4 different ways :
- With a customer
- With a merchant
- When you make a simple SCT
- Or an SCT payment request
Customer
-
It's possible to generate a virtual IBAN for a customer, either when creating or when updating the profile.
-
Here is the code to show you how you do it when creating but the process is the same when updating, we send the merchant walletId in the request :
-
curl -v -X POST 'https://test-api.centralpay.net/v2/rest/customer' \ -u 'doctest:4I9HJRTd' \ -d 'firstName=Carla' \ -d 'lastName=Mauru' \ -d 'addressLine1=17 rue de la poste' \ -d 'postalCode=37000' \ -d 'city=Tours' \ -d 'country=FR' \ -d 'email=carlamauru@gmail.com' \ -d 'cardTokenId=e03de50d-e864-43c4-8da5-95dfd28e2e8a' \ -d 'walletIdForIban=9b7f18d8-734f-4c72-8792-aea2ecdbdbaa'
Response :
{
"customerId": "55e7e32b-63b6-45b3-8a02-e91e185487c0",
"creationDate": "2023-03-17T10:22:10.215653+01:00",
"merchantCustomerId": null,
"firstName": "CARLA",
"lastName": "MAURU",
"email": "carlamauru@gmail.com",
"phone": null,
"addressLine1": "17 RUE DE LA POSTE",
"addressLine2": null,
"addressLine3": null,
"addressLine4": null,
"postalCode": "37000",
"city": "TOURS",
"country": "FRA",
"cards": [
{
"cardId": "dfa96807-7b0e-4386-b323-c99aea82456e",
"creationDate": "2023-03-17T10:21:55.538519+01:00",
"customerId": "55e7e32b-63b6-45b3-8a02-e91e185487c0",
"cardTokenId": "e61bc62c-4cc6-45d5-bf31-78ff6e4ffabd",
"infoId": null,
"merchantCardId": null,
"commercialBrand": "VISA",
"first6": "400000",
"last4": "0010",
"expirationMonth": 12,
"expirationYear": 2023,
"country": null,
"cardholderName": "D DEGEAI",
"cardholderEmail": "ddegeai@centralpay.eu",
"description": null,
"fingerprint": "b31d96aaa14cf7436c4ad6d4b95a1e15c7de7cb3",
"cardType": null,
"region": null,
"productType": null,
"europeanEconomicArea": null,
"check": false,
"additionalData": {}
}
],
"description": null,
"language": null,
"otpExpired": false,
"subscriptions": [],
"installmentPayments": [],
"fee": 0,
"totalCharge": 0,
"bankAccounts": [
{
"iban": "FR7699999000017163979804706",
"bic": "CEAYFR22"
}
],
"metaData": null,
"preferredCardId": null,
"cardMerchants": [],
"movementId": "1b4ca6a8-ce9a-4ed0-a68a-ac51c722c368",
"otpExpirationDate": null,
"additionalData": {}
}
This response is sent back when the customer has been created with a virtual IBAN.
Merchant
-
You can find the virtual IBAN on the merchant page in our backoffice :
SCT Transaction
-
When you call the /sctTransaction service yon can send the parameter ibanWalletId linked to the merchant's walletID that will receive the funds.
-
Curl code example :
-
curl -v -X POST 'https://test-api.centralpay.net/v2/rest/sctTransaction' \ -u 'doctest:4I9HJRTd' \ -d 'amount=100' \ -d 'currency=EUR' \ -d 'walletIdForIban=9b7f18d8-734f-4c72-8792-aea2ecdbdbaa'
Response :
{
"sctTransactionId": "61f08e17-ddbe-4b8a-95bd-7a9580bb3a29",
"creationDate": "2023-03-17T11:17:23.615075+01:00",
"receiptDate": null,
"cancellationDate": null,
"pointOfSaleId": "0ce87724-882c-443d-ad07-2afef674d1d7",
"customerId": null,
"destinationBankAccountId": "ae909782-18d2-42dc-b9b7-9e3c38dac167",
"merchantSctTransactionId": null,
"status": "PENDING",
"iban": "FR7612548029980000000150086",
"bic": "AXABFRPP",
"bankAccount": {
"iban": "FR7612548029980000000150086",
"bic": "AXABFRPP"
},
"sepaReference": "1UUKWHOA820DOH9",
"description": null,
"currency": "EUR",
"amount": 100,
"transferGroup": null,
"payoutCurrency": "EUR",
"payoutAmount": null,
"commission": null,
"fee": null,
"processed": null,
"processedDate": null,
"order": {
"firstName": null,
"lastName": null,
"addressLine1": null,
"addressLine2": null,
"addressLine3": null,
"addressLine4": null,
"postalCode": null,
"city": null,
"country": null,
"email": null,
"phone": null,
"cardCountry": null,
"cardholderName": null,
"cardholderEmail": null
},
"transactionTransfers": [],
"movementId": null,
"cancelMovementId": null,
"paymentRequestBreakdownId": null,
"paymentRequestId": null,
"additionalData": {}
}
This response is sent when the SCT has been successfully proccessed with a virtual IBAN
Payment request
-
You will also find a virtual IBAN on a SCT type payment request :
-
