Formulaire de paiement CUSTOM

Le service API Transaction permet d’effectuer une autorisation suivie d’une capture des fonds sur la carte bancaire de votre client. Tous les modes de paiement par carte (paiement simple, récurrents, MoTo, etc.) sont gérés via ce service.

Lorsqu’un client souhaite effectuer un premier paiement, ses données de carte doivent être collectées pour générer un cardTokenId, grâce au service de tokenisation « token.js » de CentralPay. Ce token temporaire permet ensuite de créer une ressource Card, identifiée par un cardId, pouvant être enregistrée dans un objet Customer. Ce rattachement est indispensable pour permettre des paiements ultérieurs sans redemander la carte (paiement en 1 clic, récurrents, etc.).

ℹ️ Avec un formulaire de paiement personnalisé (CUSTOM FORM), l'intégration de l'authentification 3DS 2.2 est obligatoire avant d'exécuter une transaction.

Schéma du flux de paiement avec cardTokenId :

ℹ️ Si vous disposez d'une certification PCI-DSS de niveau 1 et que vous gérez les données de carte, vous pouvez directement créer un objet /card en envoyant les données (PAN, date d'expiration, CVC) à l'API, sans passer par token.js.

1. Prérequis

1.1. Déclarer vos domaines

Avant d’utiliser le token.js, vous devez déclarer les domaines hébergeant vos formulaires Custom dans votre Portail Marchand. Allez dans Administration Mon profil marchand Technique Modifier , puis complétez le champ Hosts Custom Forms autorisés.

Accès :

1.2. Sécuriser votre formulaire

Assurez-vous que vos pages de paiement utilisent le protocole HTTPS avec TLS 1.2 ou supérieur.

1.3. Conformité PCI-DSS

L’utilisation de token.js implique que vous gérez vous-même l’affichage du formulaire et le déclenchement du token. Cette méthode impose de respecter les exigences PCI DSS SAQ A-EP.

Téléchargez le formulaire A-EP ➝

2. Intégration du formulaire de paiement

2.1. Créer un formulaire de paiement HTML

Contrairement au Smart Form hébergé par CentralPay, le Custom Form est créé par vos soins, via votre propre code HTML. Vous devez implémenter les champs suivants :

• Numéro de carte : 16 chiffres pour CB/Visa/Mastercard, 15 pour American Express
• Date d’expiration : format MM/AAAA
• CVC : 3 chiffres (CB/Visa/Mastercard), 4 chiffres (Amex)

Vous pouvez consulter nos exemples de formulaires Custom Form :

• Consultez l’exemple de formulaire Custom Form sans 3DS 2.2 ➝
• Consultez l’exemple de formulaire Custom Form avec 3DS 2.2 ➝

2.2. Intégration du script token.js

Ajoutez dans votre page le script token.js pour générer un cardTokenId :

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

Ajoutez ensuite votre clé publique marchand (MerchantPublicKey) dans un tag distinct :

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

Vous pouvez voir où retrouver votre MerchantPublicKey depuis la page Authentification de nos API.

Intégration dans une application mobile

Si vous utilisez une WebView dans votre application, vous pouvez intégrer soit un formulaire personnalisé avec token.js, soit un formulaire hébergé via le service PaymentRequest. Ces options vous permettent d’externaliser la collecte des données carte tout en offrant une expérience utilisateur fluide.

Dans une application mobile native, le script token.js n’est pas compatible. Vous devez alors collecter les données de carte via les champs de l’application, puis appeler directement l’API cardToken en utilisant votre merchantPublicKey.

L’appel à l’API cardToken doit inclure un en-tête HTTP Origin correspondant à une URL déclarée dans votre profil Marchand CentralPay (voir 2.1 Prérequis).

Pour vos tests, vous pouvez utiliser l’Origin suivant : https://example.centralpay.net

ℹ️ Pour les applications mobiles natives, les données de carte sont transmises directement depuis le device de l’utilisateur vers CentralPay, sans passer par les serveurs du marchand. Cependant, ce type d’intégration nécessite de veiller à respecter les exigences de sécurité et de conformité PCI-DSS applicables à la collecte et la transmission de données de carte dans un environnement natif.

2.3. Créer un Customer et rattacher une carte

ℹ️ Le cardTokenId est un token à usage unique, dont le CVC est temporaire (10 minutes en production, 5 minutes en RCT). Passé ce délai, le token expire automatiquement (status=EXPIRED) et ne peut plus être utilisé, ce qui entraînera l’erreur suivante : "cardTokenId": "Card token already used". 

Que vous utilisiez la carte immédiatement (paiement simple) ou que vous souhaitiez la réutiliser plus tard (paiement en 1 clic, récurrent, etc.), il est recommandé de commencer par créer un objet Customer, puis d’enregistrer une Card à l’aide du cardTokenId. L’authentification 3DS 2.2 pouvant parfois allonger le délai de traitement, cette séquence permet d’éviter l’expiration du CVC associé au cardToken.

1. Créez un objet customer via l’endpoint POST /customer ou récupérez le customerId s’il est déjà connu
2. Créez une card en utilisant POST /card en spécifiant le cardTokenId émis par le token.js et le customerId

Une fois la card rattachée à un customer, le CVC devient permanent et les transactions futures peuvent être initiées sans limite de temps.

Si vous n'utilisez pas le token.js (certification PCI-DSS requise), vous pouvez directement créer une card sans passer par le cardToken en fournissant le PAN + expiration + CVC + customerId

3. Authentification 3DS 2.2

Avant d’initier une transaction par carte, vous devez vérifier l’identité du porteur via une authentification 3DS 2.2. Cette étape est obligatoire pour les transactions carte unitaire comme pour les transactions carte récurrente.

ℹ️ Exception : Les transactions de type MoTo (Mail Order / Telephone Order) ne sont pas soumises à l’authentification 3DS. Vous pouvez créer la transaction directement après la création de la carte.