CUSTOM payment form

The Transaction API service lets you perform an authorisation followed by a capture of funds on your customer’s bank card. All card payment methods (one-off payments, recurring payments, MoTo, etc.) are managed via this service.

When a customer wants to make a first payment, their card data must be collected to generate a cardTokenId, using CentralPay’s tokenisation service “token.js”. This temporary token can then be used to create a Card resource, identified by a cardId, which can be stored in a Customer object. This linking is required to enable subsequent payments without asking for the card again (1-click payments, recurring payments, etc.).

ℹ️ With a custom payment form (CUSTOM FORM), integrating 3DS 2.2 authentication is mandatory before executing a transaction.

Payment flow diagram with cardTokenId:

ℹ️ If you have PCI-DSS Level 1 certification and you handle card data, you can create a /card object directly by sending the data (PAN, expiry date, CVC) to the API, without using token.js.

1. Prerequisites

1.1. Declare your domains

Before using token.js, you must declare the domains hosting your Custom forms in your Merchant Portal. Go to Administration My merchant profile Technical Edit , then complete the Allowed Custom Forms Hosts field.

Access:

1.2. Secure your form

Ensure that your payment pages use the HTTPS protocol with TLS 1.2 or higher.

1.3. PCI-DSS compliance

Using token.js means you manage the form display and the token trigger yourself. This method requires compliance with PCI DSS SAQ A-EP requirements.

Download the A-EP form ➝

2. Payment form integration

2.1. Create an HTML payment form

Unlike the Smart Form hosted by CentralPay, the Custom Form is created by you, using your own HTML code. You must implement the following fields:

• Card number: 16 digits for CB/Visa/Mastercard, 15 for American Express
• Expiry date: MM/YYYY format
• CVC: 3 digits (CB/Visa/Mastercard), 4 digits (Amex)

You can view our Custom Form examples:

• See the example of a Custom Form without 3DS 2.2 ➝
• See the example of a Custom Form with 3DS 2.2 ➝

2.2. token.js script integration

Add the token.js script to your page to generate a cardTokenId:

<script src="https://js.centralpay.net/js/token.js"></script>

Then add your merchant public key (MerchantPublicKey) in a separate tag:

<script type="text/javascript">
  window.Centralpay ? Centralpay.card.setMerchantPublicKey('VOTRE_CLE_PUBLIQUE') : alert('Error loading html form');
</script>

You can see where to find your MerchantPublicKey on the API authentication page.

Integration in a mobile application

If you use a WebView in your application, you can integrate either a custom form with token.js or a hosted form via the PaymentRequest service. These options let you externalise card data collection while providing a smooth user experience.

In a native mobile application, the token.js script is not compatible. You must then collect card data via the application fields, then call the cardToken API directly using your merchantPublicKey.

The call to the cardToken API must include an HTTP Origin header matching a URL declared in your CentralPay Merchant profile (see 2.1 Prerequisites).

For your tests, you can use the following Origin: https://example.centralpay.net

ℹ️ For native mobile applications, card data is transmitted directly from the user’s device to CentralPay, without going through the merchant’s servers. However, this type of integration requires ensuring compliance with the security and PCI-DSS requirements applicable to collecting and transmitting card data in a native environment. 

2.3. Create a Customer and link a card

ℹ️ The cardTokenId is a single-use token, for which the CVC is temporary (10 minutes in production, 5 minutes in RCT). After this time, the token automatically expires (status=EXPIRED) and can no longer be used, which will result in the following error: "cardTokenId": "Card token already used".   

Whether you use the card immediately (one-off payment) or want to reuse it later (1-click payment, recurring, etc.), it is recommended to start by creating a Customer object, then save a Card using the cardTokenId. As 3DS 2.2 authentication can sometimes increase processing time, this sequence helps prevent the CVC associated with the cardToken from expiring.

1. Create a customer object via the POST /customer endpoint, or retrieve the customerId if it is already known
2. Create a card using POST /card by specifying the cardTokenId issued by token.js and the customerId

Once the card is linked to a customer, the CVC becomes permanent and future transactions can be initiated with no time limit.

If you do not use token.js (PCI-DSS certification required), you can create a card directly without using the cardToken by providing the PAN + expiry + CVC +  customerId

3. 3DS 2.2 authentication

Before initiating a card transaction, you must verify the cardholder’s identity via 3DS 2.2 authentication. This step is mandatory for one-off card transactions as well as for recurring card transactions.

ℹ️ Exception: MoTo (Mail Order / Telephone Order) transactions are not subject to 3DS authentication. You can create the transaction directly after creating the card.