Les objets de l'API
L’API est composée d’objets permettant de réaliser des opérations spécifiques en fonction des besoins. La liste complète est disponible ici https://ref-api.centralpay.net/.
Les objets les plus utilisés sont :
Cardtoken
cardToken est un objet qui représente la carte de paiement "tokenisée" (sous forme de jeton) qui sera utilisé pour initier une transaction.
Transaction
transaction permet de débiter votre client depuis son moyen de paiement, en général une carte de paiement, en utilisant le cardTokenId qui vient d’être créé ou depuis un customer si celui-ci a été précédemment enregistré. Lors d’une transaction réalisée avec un cardTokenId, un objet card est retourné sous forme de cardId.
Enrollment
enrollement permet de réaliser une transaction 3DS 1.0.
Card
card représente la dématérialisation durable d’une carte de paiement. S’il est associé à un customer, il peut permettre la mise en place d’un mode de paiement récurrent spécifique.
Customer
Un customer représente votre client comme entité logique et permet de consolider l’ensemble de son activité.
Refund
Un refund représente un remboursement depuis une transaction existante. Cette fonction est accessible une fois la transaction en statut "cleared".
Subscription
subscription permet de définir des cycles de paiements récurrents sous forme d’abonnement sur un de vos customer. Ils se définissent en paramétrant un subscriptionModel :
- Interval unit (jour/ semaine / mois)
- Interval count (distance entre deux interval count)
- Interraction count (nombre de fois où le cycle est répété)
Installment payment
Il permet de découper un montant en plusieurs opérations selon un intervalUnit défini, une date de démarrage et d’éventuelles charges.
Vous pouvez ainsi gérer des séquences de paiement avec beaucoup d’agilité, par exemple :
100 euros à la commande lors de la transaction, puis 4 règlements de 300 euros pendant 4 mois à partir d’une date définie.
Les hooks
Ils permettent de générer des événements dits "Events" qui seront adressés à votre système d’information selon l’état de l’objet avec lesquels ils interagissent.
Le moteur de règle d’acceptance
Si vous souhaitez encadrer le mode d’acceptation des opérations des transactions sur la "plateforme", vous pouvez utiliser le moteur de règle d’acceptance.
En fonction des données du contexte d’une transaction entrante (type de carte, montant, pays, devise, score anti-fraude), il est possible de choisir l’action à réaliser :
- Refuser
- Accepter
- Demande d’OTP (code envoyé par email ou sms)
- Demande de 3DS
- Demande de 3DS conditionnel (transaction normale si la carte n’est pas 3DS)
Il existe plus d’une centaine de règles disponibles. Vous pouvez également intégrer des valeurs/données dans les règles et les appeler dans une transaction.
Dispute
Une dispute est un objet qui permet de déclarer un impayé, et contester une transaction. Il pourra déclancher des notifications.
Payment request
Une paymentRequest est une demande de paiement évoluée associée à des scenarios d'envoie ou de relance. Elle permet le règlement d’une dette ou d’un projet en une ou plusieurs fois et depuis plusieurs participants
Smart Push
SMART PUSH est le service de notification et d'automatisation de CentralPay. Il permet d'émettre des notifications e-mail, SMS, HTTPS déclenchées depuis les étapes définies d'un scenario.
Transfer
Cet objet n’est utilisable que depuis un compte possédant l’habilitation "Plateforme". Il permet de répartir les fonds reçus pour un client depuis un compte "Plateforme" vers le compte "Basic" connecté selon des règles métiers spécifiques à la Plateforme.
Payout
Cet objet permet d’initier un virement externe vers un compte IBAN préalablement enregistré.
SCT Transaction
Cet objet permet de paramétrer la réception de virements entrants afin de les adresser directement à un compte spécifique.
SDD Transaction
Cet objet permet de réaliser un transfer de compte à compte direct entre un marchand et son customer.
L'objet cardTokenID
Cet objet représente la carte de paiement "tokenisée" qui sera utilisée pour initier une transaction.
Le cardToken est créé lors de l’envoi de la carte de paiement depuis le navigateur du client en utilisant un JavaScript (token.js) que nous mettons à votre disposition. Une fois que la carte de paiement est stockée dans notre environnement PCI-DSS, nous vous la restituons sous forme de jeton : le cardTokenID.
Celui-ci a une durée de vie de 5 mn, le temps nécessaire pour initier une transaction depuis vos serveurs. Cette opération limite ainsi votre périmètre de conformité PCI-DSS puisqu’aucune donnée sensible n’est transmise ou stockée par vos serveurs.
Conseil : un cardId est également envoyé avec le cardTokenId. Il peut être utile une fois cette opération effectuée de faire un GET sur cet objet afin de connaître les attributs de la carte permettant le calcul des frais d’Interchange.
Le cardTokenId est unique et ne peut être utilisé qu'une seule fois.
L'objet transaction
Une transaction représente une demande de paiement acceptée, refusée ou abandonnée, une demande d'autorisation, de remboursement ou de crédit ou d'annulation.
L’objet transaction permet de débiter votre client de sa méthode de paiement, généralement une carte de crédit, en utilisant le cardTokenId qui vient d'être créé ou à partir d'un customer s'il a été précédemment enregistré.
Lors d'une transaction avec un cardTokenID, un objet card est retourné en tant que cardId.
Statuts des transactions
SUCCESS
La transaction est en "succès" lorsqu’une demande d’autorisation a été émise par la Banque. Le code de retour banque est = 0.
FRAUD
Le statut indique que la transaction a rencontré un élément en "blacklist". Cela peut provenir d’une IP, d’un numéro de téléphone, d’un email ou d’un numéro de carte.
CAPTURED
Une transaction Success doit etre "capturé" dans un délai de 7 jours calendaire afin d'etre débité sur la carte de votre Client.
NB : par défaut une transaction est automatiquement "capturée".
FAILURE
La transaction est en "échec" lorsque l'autorisation n’a pas été délivrée par la Banque émettrice de la carte.
Vous recevez en complément un code de rejet émis par la banque de l'émetteur de carte (code bancaire < 100)
Voir les codes de retour
CANCELED
Ce statut reflète l’annulation de demande de capture avant son passage en compensation. Il est possible d’annuler une transaction entre le statut transaction success et cleared.
THREEDS_AUTH_FAILURE
L'authentification 3DS a échoué. Le détenteur de la carte a soumis un code incorrect.
CLEARED
Une transaction "Cleared" indique qu'un débit a été réalisé sur la carte de votre Client. A ce stade, vous ne pouvez donc plus annuler (cancell) la transaction mais vous pouvez la rembourser à, l'aide de la commande "REFUND".
NOT_ACCEPTED
La transaction a été refusée car elle a rencontré un élément d’une règle d'acceptation.
Le paiement unique
Lors du premier paiement, le cardTokenID est utilisé pour créer une transaction.
Une transaction unique est une transaction qui utilise une carte de débit/de crédit pour un paiement unique.
Une fois cette étape réalisée, un customer peut être créé afin qu'il puisse être utilisé à nouveau dans le cas de paiement récurrent.
Il existe deux façons de traiter une carte de paiement dans une transaction unique :
Soit vous pouvez utiliser le sous-objet card en adressant toutes les données de la la carte de paiement (Numéro de carte complet) que vous possédez dans votre système (nécessite un agrément PCI-DSS level 1)
Soit vous utilisez l’objet cardTokenId qui sert d’identifieur unique d’une carte de paiement que vous obtenez en utilisant le service de tokenisation accessible depuis le javascript "Token.js".
Le paiement récurrent
Pour traiter des paiements ou transactions récurrents (1-clic, souscription, installment...), vous devez d'abord créer un customer dans lequel une ou plusieurs card pourront être associées. Cette opération se réalise à la suite d’une première transaction réussie.
Pour plus d’information, voir l’objet "customer"
Chargeback
Un chargeback (également connu sous le nom de contestation, répudiation ou impayé) se produit lorsqu’un client (détenteur de carte) conteste une transaction auprès de sa banque. La banque émettrice de la carte adresse ensuite un litige auprès de la banque acquéreur afin que cette dernière lui reverse immédiatement le paiement.
Pour tout paiement par carte bancaire, votre client a la possibilité de contester un paiement pendant 13 mois maximum. En France, une opposition n'est en principe autorisée que dans le cadre d'une utilisation frauduleuse de la carte. Cependant, dans d'autres pays européens, la carte bancaire peut être utilisée dans le cadre d’un litige commercial.
Étant donné qu'un chargeback comme un refund est toujours rattaché à une transaction initiale, c'est l'initiateur de la transaction qui est débité . Dans le cas des comptes plate-forme ou revendeurs, charge à l'initiateur de récupérer ses fonds par le biais d'un transferReversal
Statuts des chargebacks :
RETRIEVAL_NOTICED
Objet :
Une demande d’information vous est adressée par votre client afin d’obtenir des informations sur la nature de l’opération réalisée. A ce stade ce n’est pas un impayé. Il pourra se transformer en impayé en fonction des réponses apportées.
Action :
Répondre en fournissant la nature du service délivré, la preuve de consentement du client et / ou la preuve de livraison.
RETRIEVAL_CLOSE
Objet :
Notification que la demande d’information est close. Les informations fournies auront permis d'éviter l’impayé.
Action :
Pas d’action à réaliser
CHARGEBACK_NOTICED
Objet :
Un impayé vous est adressé par votre client. Le montant de l’opération sera débité du compte qui a initié la transaction de manière à permettre le remboursement. Des frais de traitement non remboursables s’appliquent pour le traitement du litige.
Action :
Vous disposez d’un délai de 3 semaines pour répondre en fournissant la preuve de consentement de l’opération et / ou la preuve de livraison.
CHARGEBACK_WON
Objet :
Vous avez obtenu gain cause, l’impayé a été rejeté. Les fonds vont vous être remboursés.
Action :
Pas d’action
CHARGEBACK_LOST
Objet :
Vous n’avez pas obtenu gain cause, l’impayé est conservé. Les fonds ne pourront pas vous être remboursés.
Action :
Pas d’action
TRANSACTION_REFUNDED
Objet :
Les fonds perdus lors du chargeback vous ont été remboursés.
Action :
Pas d’action
Il existe un process de règlement des différends qui permet, dans certains cas, de contester l’impayé et de prouver que le paiement est valide.
- Si le litige tourne en votre faveur, le montant contesté et les frais vous sont retournés.
- Si un litige reste confirmé, le détenteur de la carte sera remboursé.
La réception d’un litige
Quand un litige se produit, une notification avec le paiement litigieux est adressée à CentralPay qui vous adressera une notification. Un objet dispute est créé avec un statut nécessitant une réponse. Si lors de votre intégration vous avez configuré des hooks vous serez également informé sous forme d’événement.
Vous avez la possibilité de consulter le statut de chacune des disputes via votre plateforme, de prendre connaissance des raisons que le client a reportées au fournisseur de carte, et de traiter le litige soit en le contestant par la soumission d’une "preuve" adéquate ou soit en l’acceptant.
Payment receipt
Quand une transaction a été réalisée avec succès, Centralpay peut adresser un email de confirmation de paiement à l’adresse renseignée dans les paramètres de receiptEmail de la requête de transaction.
Cette confirmation de paiement possède une mise en forme affichant les différentes informations de paiement, vous pouvez cependant configurer à votre convenance plusieurs paramètres à partir du backoffice.
Voir ci-dessous un exemple d’email de confirmation de paiement :
Détails des éléments marqués d’une flèche dans l’image ci-dessus.
- Adresse email de l’expéditeur
- Nom de l’expéditeur d’email
- Logo de l’entreprise
- Nom du point de vente
- Texte de pied de page
- Langue du reçu
Informations concernant le point de vente :
Les éléments 1, 2, 3, 4 mis en évidence sont configurés dans les paramètres de votre compte "Point de vente" :
- Dans le backoffice allez dans "Configuration" > Point de vente > Détail d'un point de vente.
- Cliquez sur l’icône d’édition : vous pouvez remplir ou éditer les champs 1, 2, 3, 4 pour mettre à jour le template de votre email.
- Adresse email de l’expéditeur
- Nom de l’expéditeur d’email
- Logo de l’entreprise
- Nom du point de vente
Texte du pied de page du reçu :
- Allez dans Configuration > "Receipt email templates" et cliquez sur le bouton "create".
N.B. : un profil Merchant Admin est requis pour procéder à ces paramètrages.
Vous pouvez dorénavant entrer les paramètres suivants dans la page d’édition de la confirmation de paiement (Receipt email edition page) :
- Un nom pour nouveau template receipt email.
- La sélection de la langue pour ce template.
- La sélection d’un ou plusieurs points de vente pour ce template.
- Insérer un template de pied de page.
Le contenu du pied de page (champ 5) sera affiché à la fin de l’email.
Ce template sera utilisé seulement pour le(s) point(s) de vente sélectionné(s).
La langue dépendra des paramètres du browserUserAgent, du browserAcceptLanguage et de l’endUserLanguage envoyés dans votre requête de transaction.
Langue de la confirmation de paiement :
Si vous désirez que le détenteur de carte reçoive la confirmation de paiement dans une langue spécifique, vous devez renseigner la valeur endUserLanguage.
Dans le cas contraire, nous utiliserons les valeurs du champ browserAcceptLanguage et par défaut l’anglais si aucun élément n’est renseigné.
| 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 |
Les cartes virtuelles (VCC)
Fonctionnement des OTA
Les grands OTA que sont Booking.com, Expedia.com, hotels.com ou Agoda.com peuvent collecter les règlements lors de la réservation. Dans ce cas, ils fournissent aux hôteliers, non pas les données de la carte du client, mais une alias, qui est une carte virtuelle ou VCC .
Cartes virtuelles ou virtual credit card (VCC)
Une carte virtuelle ou VCC est généralement émise pour un usage encadré afin de limiter les risques de compromission.
Une carte virtuelle représente en quelque sorte l’alias d’une carte existante qui ne pourra être utilisé qu’à partir d’une certaine date et depuis un MCC défini. En l’occurrence, dans le secteur du tourisme, il est nécessaire d’avoir un contrat avec le MCC 7011 (HOTELS) pour pouvoir la débiter.
Ainsi, dans le cas où le numéro de carte tombait entre les mains d’une personne mal intentionnée, elle ne pourrait pas déclencher de débit sur la carte source.
Etant donné la nature spéciale des cartes issues par ces OTA, il est en général impossible de réaliser des demandes d’autorisation, de pré-autorisation ou de vérification au moment de la commande.
Si la carte n’est débitable que le jour de la réservation par un MCC 7011 par exemple, l’émetteur, en général MASTERCARD B2B PRODUCT, renverra un code d’erreur pour transaction invalide (12).
Carte virtuelle Booking.com
Booking.com utilise des cartes virtuelles sur certaines destinations. En fonction du paramétrage réalisé sur le site de l’hôtel, une réservation pourra être réalisée avec ou sans prise d’empreinte carte. Si l’hôtelier a choisi de demander un moyen de paiement, alors BOOKING.com génèrera une carte virtuelle et l’adressera à l’hôtelier ou à son prestataire technique. Avec la crise du covid19, booking n'autorise plus les débits de ses VCC qu'un jour après le checkin du client.
En savoir plus sur le fonctionnement des cartes virtuelles de booking.com
Carte virtuelle Expedia
Chez EXPEDIA, il est possible de laisser le visiteur choisir entre la possibilité de payer à l’hôtel (Hotel Collect) ou de payer directement lorsqu’il réalise la réservation (Expedia Collect). Cette option est appelée Expedia Traveler Preference (ETP). Si un client utilise la méthode Expedia Collect, une carte virtuelle sera alors générée.
En savoir plus sur le fonctionnement des cartes virtuelles de expedia.com
Comment gérer une carte virtuelle avec Centralpay
La meilleure méthode pour stocker une VCC et de pouvoir l'utiliser une fois disponible est de créer un « Customer » et de lui associer la carte concernée.
Deux options sont ouvertes :
- Soit la carte est débitable au moment de la création et une demande de vérification est réalisable à la création du customer
- Soit la carte n’est pas utilisable à la création du customer et la carte doit etre créé sans vérification. Cela ne signifie pas qu’elle ne pourra pas être utilisée à terme. Cela veut simplement dire qu’elle ne doit être débitée qu’à une certaine date. En génaral les OTA auront préalablement vérifié les données de la carte pour s'assurer qu'elle était débitable.
Ainsi, créer un customer dans l’API Centralpay permet de tokeniser la carte virtuelle, sécuriser son stockage et de faciliter son utilisation lorsque les conditions d’acceptation initiales auront été réunies.
En savoir plus sur la création des customer
SCT Transaction
Le service "SCT Transaction" permet de recevoir des virements externes et de les associer à un compte de paiement. Le service fonctionne comme une transaction, vu précédemment. Néanmoins, afin de faciliter le rapprochement des opérations, une référence sepaReference sera demandée à la personne qui exécutera le virement. Cette référence est fournie par le service en réponse à la demande de wireTransfer.
Pour initialiser un SCT Transaction, vous devez préciser les données suivantes :
- amount
- currency
- destinationWalletId
De cette manière, lorsque le virement sera reçu par la plateforme, il sera automatiquement affecté au compte de paiement concerné.
L'objet dispute / impayé
Un objet dispute (également connu sous le nom de contestation, répudiation ou impayé) est créé lorsqu'un client (détenteur de carte) conteste une transaction auprès de sa banque. Quand un litige se produit, une notification avec le paiement litigieux est adressée à CentralPay qui vous adressera à son tour une notification. Un objet dispute est créé avec un statut nécessitant une réponse. Si lors de votre intégration vous avez configuré des hooks, vous serez également informé sous forme d'événement.
Vous avez la possibilité de consulter le statut de chacune des disputes via votre plateforme, de prendre connaissance des raisons que le client a reportées au fournisseur de carte, et de traiter le litige soit en le contestant par la soumission d'une "preuve" adéquate ou soit en l'acceptant.
Pour tout paiement par carte, votre client a la possibilité de contester un paiement :
- pendant 120 jours à compter de la transaction sur les réseaux "Visa" ou "Mastercard" (hors France)
- pendant 13 mois à compter de la date d'opération sur le réseau Français "Carte Bancaire".
En France, une opposition n'est en principe autorisée que dans le cadre d'une utilisation frauduleuse de la carte. Cependant, dans d'autres pays européens, la carte bancaire peut être utilisée dans le cadre d'un litige commercial.
Statuts des disputes :
RETRIEVAL_NOTICED
Objet :
Une demande d'information vous est adressée afin d'obtenir des informations sur la nature de l'opération réalisée. A ce stade ce n'est pas un impayé. Il pourra se transformer en impayé en fonction des réponses apportées.
Action :
Répondre dans les 7 jours en fornissant la nature du service délivré, la preuve de consentement du client et/ou la preuve de livraison. A défaut de réponse, votre client pourra dans decléncher un impayé aupres de sa banque.
RETRIEVAL_CLOSE
Objet :
Notification que la demande d'information est close. Les informations fournies auront permis d'éviter l'impayé.
Action :
Pas d'action à réaliser
CHARGEBACK_NOTICED
Objet :
Un impayé vous est adressé par votre client. Le montant de l'opération vous sera débité de votre compte de manière à permettre le remboursement. Des frais de traitement non remboursables s'appliquent pour le traitement du litige.
NB : un Chargeback n'est pas nécessairement précédé par un Retrieval (Demande d'information).
Action :
Vous disposez d'un délai de 20 jours calendaires pour répondre en fournissant la preuve de consentement de l'opération et / ou la preuve de livraison. A défaut de réponse dans les délais impartis, il ne sera plus possible de contester l'opération.
NB : Notez que dans le cadre des transactions non sécurisés (non 3DS), vous devez justifier du consentement du titulaire de la carte. Vous devez à minima vous assurer que le nom et prénom de votre client est bien le même que celui qui est indiqué sur la carte de paiement.
CHARGEBACK_WON
Objet :
Vous avez obtenu gain cause, l'impayé a été rejeté. Les fonds vont vous être remboursés.
Action :
Pas d'action
CHARGEBACK_LOST
Objet :
Vous n'avez pas obtenu gain cause, l'impayé est conservé. Les fonds ne pourront pas vous être remboursés.
Action :
Pas d'action
TRANSACTION_REFUNDED
Objet :
Les fonds perdus lors du chargeback vous ont été remboursés
Action :
Pas d'action
Il existe un process de règlement des différends qui permet, dans certains cas, de contester l'impayé et de prouver que le paiement est valide.
- Si le litige tourne en votre faveur, le montant contesté et les frais vous sont retournés.
- Si un litige reste confirmé, le détenteur de la carte sera remboursé.
3DS 2.2
3D Secure 2 est une nouvelle solution d'authentification apportant une meilleure expérience pour les consommateurs, tout en limitant la fraude. En agrégeant et transmettant des données issues du contexte d'achat à l'émetteur de la carte, le consommateur est censé éviter les frictions liées à une authentification forte. L'émetteur de la carte (la banque) est ainsi en mesure de vérifier que le consommateur est bien la personne en train de payer.
Le 3DS2 possède deux types d'intégration possibles :
Le 3DS2 "BRW" ou "Browser Authentication" (porteur participant - 1ère transaction)
Représente la majorité des intégrations de 3DS 2.
Il requiert l'authentification du client afin de vérifier qu'il est bien le porteur légitime de la carte au moment de la transaction. Il déclenche si necéssaire un challenge qui vérifie l'identité du porteur de carte (SCA).
Le 3DS2 "3RI Authentification" (porteur non participant - énième paiement récurrent)
3DS Requestor Initiated (3RI) Authentications, ou Authentification Initialisée par le marchand lorsque le porteur n'est pas présent ou non participant.
3RI offre la possibilité de générer les authentifications 3DS necéssaires sans que le client ne soit impliqué. Cela permet d'utiliser une authentification générée précédemment avec un client. Elle est utilisée dans les contextes suivants de paiements récurrents : Paiement en X fois, Abonnement, Refund, etc.
3DS 2.2 BRW
Tous ce processus doit se dérouler sur la même page web (Ceci est une contrainte du process bancaire).
Les grandes étapes du 3D Secure 2.0 :
1) VERSIONING
- Cette étape consiste à adresser le PAN de la carte à l'API Centralpay.
Exemple de code Curl :
curl -v POST 'https://test-api.centralpay.net/v2/rest/3ds2/versioning' \ -h 'Content-Type: application/x-www-form-urlencoded' \ -u 'doctest:4I9HJRTd' \ -d 'acctNumber=4000001000000067' - En réponse :
- Si la carte n'est pas 3DS 2.0, le versioning vous retournera une erreur 404. Cela signifie que la carte utilisée n'est pas enrôlée 3DS 2.0 et que la transaction ne peut pas se faire en 3DS 2.0.
- Si la carte est 3DS 2.0, vous recevrez un UUID identifiant l’opération jusqu’au résultat final + les données nécessaire pour réaliser le "3DS Method" (URL + base64)
Deux réponses au Versionning sont possibles si la carte est 3DS 2.0 :
Version 1 (la plus fréquente) :
{
"threeDSServerTransID":"7d031b8e-7fb7-4215-b866-eaacb395002f",
"threeDSMethodURL":"https://test-3dss-demo.centralpay.net/acs/3ds-method",
"threeDSMethodDataForm":{
"threeDSMethodData":"eyJ0aHJlZURTTWV0aG9kTm90aWZ
pY2F0aW9uVVJMIjoiaHR0cHM6Ly90ZXN0LTNkc3MuY2VudHJ
hbHBheS5uZXQvM2RzLzNkcy1tZXRob2Qtbm90aWZpY2F0aW9
uLyIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiOWNjNmIzM2M
tZGQzNS00ZmJkLTgxY2QtZmQ5Y2YwYWVlZDljIn0="
},
"errorDetails":null
}
Cette réponse est renvoyée quand la banque a besoin de l'acs url dans la requête de l'authentification.
Le process 3DS Method est alors nécessaire, vous pouvez passer au point 2 : 3DS METHOD.
Version 2 :
{
"threeDSServerTransID":"7d031b8e-7fb7-4215-b866-eaacb395002f",
"threeDSMethodURL": null,
"threeDSMethodDataForm": null,
"errorDetails": null
}
Cette réponse est renvoyée quand la banque n'a pas besoin de l'acs url dans la requête de l'authentification.
Le versioning renvoie une réponse où seul "threeDSServerTransID" possède une valeur non null.
Le process 3DS Method n'est alors pas nécessaire, vous pouvez passer au point 3 : 3DS AUTHENTICATION BRW.
2)3DS METHOD
- Lorsque le versioning renvoi les champs threeDSMethodURL et threeDSMethodDataForm en "Non Null", le process 3DS Method est alors nécessaire.
- Cette fonction a pour but de poster la donnée base64 reçue du versioning vers l'ACS.
- Le formulaire iframe doit être réalisée par le navigateur client vers la banque simultanément avec l’authentification.
- Il faut réaliser une iFrame cachée qui servira à poster la donnée base64 (threeDSMethodData) à l'URL reçue dans le versioning (threeDSMethodURL).
3)3DS AUTHENTICATION BRW
- L'appel devra être adressé vers l’url suivante de l’API CentralPay : « 3ds2/authentication »
- Cette requête permet l'envoi des données contextuelles liées au porteur
Le champ threeDSServerTransId est disponible pour un seul appel uniquement, si vous l'utilisez une seconde fois vous recevrez un code HTTP 400
Exemple d'appel (curl code)
curl --location --request POST 'https://test-api.centralpay.net/v2/rest/3ds2/authentication' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic ZG9jdGVzdDo0STlISlJUZA==' \
--data-urlencode 'threeDSServerTransID=7d031b8e-7fb7-4215-b866-eaacb395002f' \
--data-urlencode 'cardTokenId=5b9nb5cf-4470-4e58-b690-dd8965860eb8' \
--data-urlencode 'deviceChannel=02' \
--data-urlencode 'messageCategory=01' \
--data-urlencode 'purchaseAmount=1000' \
--data-urlencode 'purchaseCurrency=EUR' \
--data-urlencode 'threeDSRequestorAuthenticationInd=01' \
--data-urlencode 'browserJavaEnabled=true' \
--data-urlencode 'browserLanguage=fr-FR' \
--data-urlencode 'browserColorDepth=24' \
--data-urlencode 'browserScreenHeight=1052' \
--data-urlencode 'browserScreenWidth=1853' \
--data-urlencode 'browserTZ=120' \
--data-urlencode 'browserIP=127.0.0.1' \
--data-urlencode 'browserUserAgent=Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:68.0) Gecko/20100101 Firefox/68.0' \
--data-urlencode 'browserAcceptHeader=text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8' \
--data-urlencode 'notificationURL=http://urlduclient.sitexample.com:1101/requestor/challenge-notification' \
--data-urlencode 'threeDSRequestorURL=https://www.centralpay.eu'
L’api va retourner un statut de transaction (« transStatus »), voici les valeurs et leurs signification :
Pas d'authorisation (ne pas faire la transaction)
- N = Non authentifié /Compte non vérifié. Transaction refusée.
- U = L'authentification/la vérification du compte n'a pas pu être effectuée. Problème technique ou autre, comme indiqué dans ARes ou RReq.
- R = Authentification/vérification du compte rejetée. l'émetteur rejette l'authentification/vérification et demande de ne pas tenter d'autorisation
- I = Information seulement. Reconnaissance de la préférence du demandeur pour le défi 3DS.
Authorisation sans challenge :
- Y = Vérification de l'authentification réussie.
- A = Traitement des tentatives effectué. Non authentifié/vérifié, mais une preuve de tentative d'authentification/vérification est fournie.
Authorisation après challenge :
- C = Challenge requis. Une authentification supplémentaire est requise en utilisant le CReq/CRes.
- D = Challenge requis. Authentification découplée confirmée.
Exemples de réponses possibles :
C = Challenge requis :
{
"threeDSServerTransID": "7d031b8e-7fb7-4215-b866-eaacb395002f",
"transStatus": "C",
"acsURL": "https://test-3dss-demo.centralpay.net/acs/challenge",
"acsChallengeMandated": "Y",
"base64EncodedChallengeRequest": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImU2MDFlYjQ0LTU2N2MtNDM4Ny05MmZjLWU2ZjIzMjJiODIyYiIsImFjc1RyYW5zSUQiOiI3ZTQzZDI4ZC00M2RkLTRmM2MtYTcwOS00YjZkZDVlZjc5Y2QiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0=",
"contractId": "71602dd0-2790-4743-877b-e72530d7576d"
}
Le Challenge est nécessaire.
Y = authentification réussie :
{
"threeDSServerTransID": "7d994177-32d8-43f7-87a4-3a3cd734cbfe",
"transStatus": "Y",
"authenticationValue": "MTIzNDU2Nzg5MDA5ODc2NTQzMjEa",
"eci": "02",
"contractId": "71602dd0-2790-4743-877b-e72530d7576d"
}
Le Challenge n'est pas nécessaire.
Les champs requis au 3DS 2.0 sont dans la réponse (threeDSServerTransID, transStatus, authenticationValue (cavv), eci).
Note : Le xid n'est pas fourni car il s'agit d'une réference libre pour les marchands.
N = Transaction refusée :
{
"threeDSServerTransID": "6396b832-3e5b-4143-bde6-f5r1c1e47da0",
"transStatus": "N",
"eci": "00",
"contractId": "258128f3-5db9-4235-918a-f1d786f67c29"
}
Transaction refusé.
4) CHALLENGE
- Lorsque la réponse de l'authentification est "C", l'utilisateur doit effectuer un challenge, une Iframe doit alors soumettre un formulaire à l’url (acsURL) retournée par l’API lors de l’appel à « 3ds2/authentication ».
- Le seul paramètre envoyé est : creq qui comprend la valeur base64EncodedChallengeRequest qui provient de l’appel à « 3ds2/authentication ».
- Afin d'avoir un webhook sur votre serveur (backend) à la fin du challenge, l'URL configurée dans le paramètre notificationURL sera appelée.
Voici ce que vous aurez dans notre environnement de test pour l'affichage du Challenge OTP (dans des conditions de PROD, la fenetre affichée sera celle de l'ACS) :
Voici les OTP en environnement test :
- 1234 retourne Y pour Challenge réussi
- 4444 retourne A pour Challenge réussi
- 1111 retourne N pour Challenge échoué
- 2222 retourne R pour Challenge échoué
- 3333 retourne U pour Challenge échoué
5) REPONSE
- A l'issue du challenge, les informations concernant celui-ci sont disponibles dans la variable "finalCresValue"
- Pour recuperer les informations de cette valeur base 64 il faut la decoder, voici un exemple en php :
$retour = json_decode(base64_decode($_POST['cres']), true)
- Si celui-ci est égal à Y ou A alors le client a effectué le challenge correctement et le paiement est autorisé, vous devrez alors appelez GET /results afin de connaitre les données necessaire aux 3DS 2.0 pour votre transaction.
- Si le statut de transaction est égal à une autre valeur alors le client n'a pas effectué le challenge correctement et le paiement est refusé.
6) RESULTAT
- Pour connaitre les données 3DS 2.0 à renseigner à la création d'une transaction 3DS 2.0, vous devrez adresser le threeDSServerTransID de l'authentification 3DS 2.0 préalablement effectuée.
- Rappel : Si vous avez obtenu un transStatus à "Y" en réponse de l'authentification, les données 3DS 2.0 sont déjà contenu dans celui-ci.
Appel :
curl --location -g --request GET 'https://test-api.centralpay.net/v2/rest/3ds2/results/{{threeDSServerTransID}}' \
--header 'Authorization: Basic e3tERUZBVUxUX1VTRVJ9fTp7e0RFRkFVTFRfUEFTU1dPUkR9fQ=='
Réponse :
{
"threeDSServerTransID": "7d031b8e-7fb7-4215-b866-eaacb395002f",
"transStatus": "Y",
"authenticationValue": "JAmi21makAifmwqo2120cjq1AAA=",
"eci": "01"
}
7) Transaction
- Les données suivantes sont nécessaire afin de valider une transaction en 3DS 2.0 :
- 3ds[threeDSServerTransID] = threeDSServerTransID
- 3ds[status] = transStatus
- 3ds[cavv] = authenticationValue
- 3ds[eci] = eci
- 3ds[xid] = Paramètre Custom destiné au marchands.
Exemple d'une transaction 3DS 2.0 :
curl --location --request POST 'https://test-api.centralpay.net/v2/rest/transaction' \
--header 'Origin: https://example.centralpay.net' \
--header 'Authorization: Basic ZG9jdGVzdDo0STlISlJUZA==' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'currency=EUR' \
--data-urlencode 'amount=1500' \
--data-urlencode 'endUserIp=9.64.32.8' \
--data-urlencode 'endUserLanguage=ita' \
--data-urlencode 'merchantTransactionId=cpcg_12654de89ce44' \
--data-urlencode 'pointOfSaleId=1beb8574-cf4c-4b12-b065-d12b3f0eaa90' \
--data-urlencode 'browserUserAgent=Mozilla/5.0 (iPhone; CPU iPhone OS 16_1_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.1 Mobile/15E148 Safari/604.1' \
--data-urlencode 'browserAcceptLanguage=it_IT' \
--data-urlencode 'paymentRequestBreakdownId=5485d7e6-60c3-753c-94d3-682eaaf9ae6e' \
--data-urlencode 'email=support@centralpay.eu' \
--data-urlencode 'receiptEmail=support@centralpay.eu' \
--data-urlencode 'capture=true' \
--data-urlencode 'cardTokenId=5b9nb5cf-4470-4e58-b690-dd8965860eb8' \
--data-urlencode 'order[cardholderEmail]=support@centralpay.eu' \
--data-urlencode 'order[firstName]=John' \
--data-urlencode 'order[lastName]=Doe' \
--data-urlencode 'source=EC' \
--data-urlencode '3ds[xid]=35876533346561303461' \
--data-urlencode '3ds[cavv]=JAmi21makAifmwqo2120cjq1AAA=' \
--data-urlencode '3ds[eci]=01' \
--data-urlencode '3ds[status]=Y' \
--data-urlencode '3ds[threeDSServerTransID]=7d031b8e-7fb7-4215-b866-eaacb395002f'
3DS 2.2 3RI
PREREQUIS
- Afin de réaliser une transaction en 3DS 2.0 3RI, il faut que l'utilisateur est déjà réalisé une transaction 3DS 2.0 avec une authentification BRW.
- Une fois celle-ci effectuée, gardez l' acsTransId qui est envoyé, il faudra le passer dans threeDSReqPriorRef.
1)3DS AUTHENTICATION RI
- L'appel devra être adressé vers l’url suivante de l’API CentralPay : « 3ds2/authentication »
- L' acsTransId que vous avez gardez de l'authentification BRW doit être mit dans threeDSReqPriorRef.
- Si l’api vous retourne un statut de transaction (« transStatus ») à "Y" l'authentification 3RI est autorisé.
- Voici les valeurs possible de transStatus et leur signification :
- Y = Vérification de l'authentification réussie.
- N = Non authentifié /Compte non vérifié. Transaction refusée.
- U = L'authentification/la vérification du compte n'a pas pu être effectuée. Problème technique ou autre, comme indiqué dans ARes ou RReq.
- A = Traitement des tentatives effectué. Non authentifié/vérifié, mais une preuve de tentative d'authentification/vérification est fournie.
- C = Challenge requis. Une authentification supplémentaire est requise en utilisant le CReq/CRes.
- D = Challenge requis. Authentification découplée confirmée.
- R = Authentification/vérification du compte rejetée. l'émetteur rejette l'authentification/vérification et demande de ne pas tenter d'autorisation.
- I = Information seulement. Reconnaissance de la préférence du demandeur pour le défi 3DS.
Exemple d'appel 3RI (curl code) :
curl --location --request POST 'https://test-api.centralpay.net/v2/rest/3ds2/authentication' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic ZG9jdGVzdDo0STlISlJUZA==' \
--data-urlencode 'customerId=aae4d8c0-a555-4c2f-bfdf-18d5636b78a4' \
--data-urlencode 'cardId=44d0691b-b117-4799-ba07-31e0b02c5b08' \
--data-urlencode 'pointOfSaleId=08960d92-874b-4447-800b-aaa53fa976f5' \
--data-urlencode 'deviceChannel=03' \
--data-urlencode 'messageCategory=02' \
--data-urlencode 'acctType=03' \
--data-urlencode 'cardExpiryDate=9999' \
--data-urlencode 'purchaseAmount=4880' \
--data-urlencode 'purchaseCurrency=978' \
--data-urlencode 'purchaseExponent=2' \
--data-urlencode 'purchaseDate=20230101122345' \
--data-urlencode 'recurringExpiry=20330101' \
--data-urlencode 'recurringFrequency=0' \
--data-urlencode 'chAccAgeInd=03' \
--data-urlencode 'chAccChange=20220901' \
--data-urlencode 'chAccDate=20220901' \
--data-urlencode 'email=support@centralpay.eu' \
--data-urlencode 'nbPurchaseAccount=2' \
--data-urlencode 'paymentAccAge=20221001' \
--data-urlencode 'paymentAccInd=03' \
--data-urlencode 'threeDSReqPriorAuthMethod=02' \
--data-urlencode 'threeDSReqPriorAuthTimestamp=202209010123' \
--data-urlencode 'threeDSReqPriorRef=7d031b8e-7fb7-4215-b866-eaacb395002f' \
--data-urlencode 'threeDSRequestorDecReqInd=N' \
--data-urlencode 'threeDSRequestorAuthenticationInd=02' \
--data-urlencode 'threeDSRequestorChallengeInd=02' \
--data-urlencode 'threeRIInd=01'
Explication de certains paramètres
- deviceChannel 03 -> 3DS Requestor Initiated (3RI)
- messageCategory 02 -> La valeur 02 force la transactions en 3RI.
- purchaseAmount -> Montant de l'achat courant
- purchaseCurrency -> Monnaie au format ISO
- purchaseExponent -> Unité mineur de la monnaie courante
- purchaseDate -> Date de l'achat
- recurringExpiry -> Date à laquelle il n'y aura plus d'autorisations qui pourront être effectuées
- recurringFrequency -> Nombre de jours minimums entres deux autorisations.
- acctType -> Debit
- chAccAgeInd -> Durée pendant laquelle le titulaire de la carte possède le compte auprès du demandeur 3DS. Les valeurs acceptées sont :
- 01 -> Pas de compte
- 02 -> Créé durant la transaction
- 03 -> Moins de 30 jours
- 04 -> Entre 30 et 60 jours
- 05 -> Plus de 60 jours.
- chAccChange -> Date à laquelle le compte du titulaire de la carte auprès du demandeur 3DS a été modifié pour la dernière fois. Format de la date = YYYYMMDD.
- chAccDate -> Date à laquelle le titulaire de la carte a ouvert le compte auprès du demandeur 3DS. Format de la date = YYYYMMDD.
- nbPurchaseAccount -> Nombre d'achats effectués avec ce compte de titulaire de carte au cours des six derniers mois.
- paymentAccAge -> Date à laquelle le compte de paiement a été inscrit sur le compte du titulaire de la carte auprès du demandeur 3DS.
- paymentAccInd -> Indique la durée pendant laquelle le compte de paiement a été inscrit sur le compte du titulaire de la carte auprès du demandeur 3DS. Les valeurs acceptées sont :
- 01 -> Pas de compte
- 02 -> Créé durant la transaction
- 03 -> Moins de 30 jours
- 04 -> Entre 30 et 60 jours
- 05 -> Plus de 60 jours.
- threeDSReqPriorAuthMethod 02 -> Vérification du porteur de carte effectué par l'ACS.
- threeDSReqPriorAuthTimestamp -> Date et heure en UTC de l'authentification précédente. Le format de date accepté est YYYYMMDDHHMM.
- threeDSReqPriorRef -> Le champ doit contenir la valeur "acsTransId" de la transaction 3DS BRW précédente.
- threeDSRequestorDecReqInd N -> Ne pas utilisez l'authentification découplée.
- threeDSRequestorAuthenticationInd 02 -> Transaction récurrente
- threeDSRequestorChallengeInd 02 -> Pas de Challenge requis
- threeRIInd 01 -> Transaction récurrente
Exemple de réponse :
{
"threeDSServerTransID": "67dc456c-6c7a-987f-92cf-f68752525d0c",
"transStatus": "Y",
"eci": "02",
"contractId": "fb8736a5-8741-19b6-9d38-ec135888e0bf"
}
2) Transaction
- Les données suivantes sont nécessaire afin de valider une transaction en 3DS 2.0 :
- 3ds[threeDSServerTransID] = threeDSServerTransID (ajouter le nouveau génerer par l'authentification 3RI)
- 3ds[status] = transStatus
- 3ds[eci] = eci
- 3ds[xid] = Paramètre Custom destiné au marchands.
- Lors d'une transaction en 3RI, il ne faut pas envoyer le 3ds[cavv].
Exemple d'une transaction 3DS 2.0 :
curl --location --request POST 'https://test-api.centralpay.net/v2/rest/transaction' \
--header 'Origin: https://example.centralpay.net' \
--header 'Authorization: Basic ZG9jdGVzdDo0STlISlJUZA==' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'currency=EUR' \
--data-urlencode 'amount=1500' \
--data-urlencode 'endUserIp=9.64.32.8' \
--data-urlencode 'endUserLanguage=ita' \
--data-urlencode 'merchantTransactionId=cpcg_12654de89ce44' \
--data-urlencode 'pointOfSaleId=1beb8574-cf4c-4b12-b065-d12b3f0eaa90' \
--data-urlencode 'browserUserAgent=Mozilla/5.0 (iPhone; CPU iPhone OS 16_1_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.1 Mobile/15E148 Safari/604.1' \
--data-urlencode 'browserAcceptLanguage=it_IT' \
--data-urlencode 'paymentRequestBreakdownId=5485d7e6-60c3-753c-94d3-682eaaf9ae6e' \
--data-urlencode 'email=support@centralpay.eu' \
--data-urlencode 'receiptEmail=support@centralpay.eu' \
--data-urlencode 'capture=true' \
--data-urlencode 'customerId=aae4d8c0-a555-4c2f-bfdf-18d5636b78a4' \
--data-urlencode 'cardId=44d0691b-b117-4799-ba07-31e0b02c5b08' \
--data-urlencode 'order[cardholderEmail]=support@centralpay.eu' \
--data-urlencode 'order[firstName]=John' \
--data-urlencode 'order[lastName]=Doe' \
--data-urlencode 'source=EC' \
--data-urlencode '3ds[xid]=35876533346561303461' \
--data-urlencode '3ds[eci]=02' \
--data-urlencode '3ds[status]=Y' \
--data-urlencode '3ds[threeDSServerTransID]=67dc456c-6c7a-987f-92cf-f68752525d0c'
Téléchargement des sources 3DS 2.2
Vous pouvez télécharger les sources ici : 3ds2.zip
F.A.Q 3DS 2.2
Foire aux questions autour du 3-D Secure 2.0.
Existe-t-il des cartes de test pour des transactions 3DS2 en environnement RCT ?
- Oui voici le lien des cartes de tests en env. RCT :
https://ref-api.centralpay.net/glossary-0#77-test-cards
Ma transaction a reçu le code retour banque 5, qu'est-ce que ça signifie ?
- Cela signifie, que la banque refuse sans donner de statut particulier.
Cela peut être un code CVV erroné ou une autre décision que nous ne connaissons pas.
Ce statut ne permet pas d’affirmer que la banque n’acceptera pas l’autorisation après d’autres tentatives.
Ma transaction a reçu le code retour banque 12, qu'est-ce que ça signifie ?
- Cela signifie que la banque refuse sans donner de statut particulier.
La raison peut être :
- Simplement une transaction invalide
- Un code 75 de la part de la banque émetteur (le code PIN de la carte a été trop de fois incorrecte)
- Un CAVV erroné (fournit par l'ACS lors d'une authentification 3DS)
- Ou une autre décision que nous ne connaissons pas.
L'API transaction me retourne une erreur "Soft Decline" pourtant le paramètre "threeDSServerTransID" est bien celui retourné par le cres.
Comment devons-nous interpréter ce retour et que devons-nous faire ?
- Le soft decline est renvoyé par la banque lorsque que le 3DS n'est pas présent dans la transaction.
Il faut vérifier si il manque des champs présentés dans cette partie de la documentation : https://ref-api.centralpay.net/payment#106-3ds-sub-object
Ma requête du Versioning me retourne une erreur "404" avec le message "Card account number not found in card ranges from Directory Server".
Qu'est-ce que ça signifie et que dois-je faire ?
- Cela signifie que la carte utilisée n'est pas enrôlée 3DS2.0 et que la transaction ne peut pas se faire en 3DS2.0.
Pour ce cas, nous conseillons de prévoir un basculement vers un paiement en 3DS1 pour ce genre de carte.
La réponse de la requête Result nous a renvoyé le transStatus à U.
Comment devons-nous interpréter ce retour et que devons-nous faire dans ce cas ?
- La valeur U de transStatus en réponse de la requête result signifie que l'authentification ou la vérification n'a pas pu se faire suite à un problème technique ou autres problèmes.
Du côté du smart form lors du challenge avec la requête result, seules les valeurs Y et A permettent de valider le challenge et continuer le paiement.
Les autres valeurs font échouer le challenge et le paiement.
Mais dans le cas d'un custom form le fonctionnement peut être différent, vous pouvez utiliser la valeur U pour faire une nouvelle tentative de challenge et si ça échoue encore alors le paiement passe en 3DS1 ou est refusé, ou alors pour directement retenter le paiement en 3DS1 ou le considérer comme un échec de paiement.
Ces différents cas sont possible à réaliser.
Nous avons soumis le formulaire à l'url retournée par l'authentication avec le base64EncodedChallengeRequest.
Mais le client est aussitôt revenu sur notre site sans CRES mais avec un paramètre ERROR contenant la valeur "eyJ0aHJlZURTU...Mi4xLjAifQ==" ainsi que le paramètre "THREEDSSESSIONDATA" qui lui était vide.
Comment devons-nous interpréter ce retour et que devons-nous faire dans ce cas ?
- Lorsque vous avez un retour de ce genre, il faut vérifiez que votre processus du 3DS2 se déroule bien sur une seule et même page avec la solution d'un iframe.
Si le processus est conforme alors contactez le support technique avec les informations nécessaires.
Pour rappel, toutes les étapes du formulaire se réalisent sur une seule et même page sans redirection vers une page bancaire ou autre.
Cela se fait grâce à la solution de l'Iframe.
Toute la procédure du 3DS2.0 se passe sur la même page !
Nous avons reçu une erreur 303 : "acquirerBIN, acquirerMerchantID not recognized" lors d'un appel à l'authentication.
Comment devons-nous interpréter ce retour et que devons-nous faire dans ce cas ?
- Il s'agit soit du contrat qui n'est pas 3DS2, soit d'autres problèmes.
Dans le cas d'un autre problème, il faut alors contacter le support technique en fournissant le numéro de contrat monétique (si connu) et les autres informations pouvant être nécessaire.
Sur l'étape d'authentication, nous avons eu une erreur 203 : "Validation of 3DS Requestor Authentication data failed.
Data element not in the required format or value is invalid" pour le champ merchant.merchantName.
Comment devons-nous interpréter ce retour et que devons-nous faire dans ce cas ?
- L'erreur 203 signifie qu'il y a un caractère invalide dans le paramètre "merchant.merchantName".
Lors d’un test d’appel de la fonction 3DS2 « authentication », l’erreur suivante est retournée dans la clé « card data » : "There is no unique source of card".
Qu'est que ça signifie ?
- L'erreur "There is no unique source of card" est commune a toute la plateforme et est présent lorsque vous envoyez des informations de cartes deux fois : par exemple via un cardToken et un cardId ou un PAN et un cardToken etc...
L'objet Card
L’objet card représente la dématérialisation durable d’une carte de paiement. Il peut être associé à un customer afin de permettre le paiement récurrent, la mise en place d’un abonnement ou d’un paiement 1-clic.
Vous n’avez donc plus besoin de stocker des cartes sur vos serveurs. Une fois cette fonction implémentée dans un customer vous pouvez traiter des paiements récurrents sécurisés en un seul clic.
Cet objet comprend également des attributs liés au contexte d’émission de la carte. Un GET sur un cardId vous indiquera par exemple :
- commercialBrand : MASTERCARD / VISA / AMEX
- cardType : PREPAID / DEBIT / DIFF_DEBIT / CREDIT
- region : EU, USA
- productType : CORPORATE / CONSUMER
- Product : Electron, gold, Visa Classic, MASTERCARD STANDARD,
- Country : France...
- EEA : oui / non
L'objet customer
Un customer est la représentation logique de votre client qui équivaut à un conteneur de moyens de paiements. On peut donc y stocker plusieurs card qui possèderont toutes un cardId. Cet objet customer aura l’avantage de vous permettre de rassembler toutes les opérations qui auront été réalisées sur un customer :
- Transaction
- Refund
- Chargeback
- Subscription
Grace à cet objet, une ou plusieurs card peuvent être associées, vous permettant de conserver les données de paiement sans avoir à stocker le numéro de la carte dans vos bases.
Un customer est identifié par son email, nom et prénom. Vous pouvez lui associer des moyens de paiement, des cards, afin de réaliser des opérations de paiements récurrents :
- Paiement 1-clic
- Paiement sur abonnement
- Paiement sur X fois
Le client n’a ainsi plus besoin d’être sollicité pour ressaisir son numéro une fois enregistré dans son profil customer.
Conseil : veillez à ne pas enregistrer deux fois la même carte car cela viendrait alourdir les délais d’interrogation de l’objet customer. Pour cela, consultez ma section suivante "rechercher un customer Via l'API".
Rechercher un Customer
Afin de vérifier si un customer a déjà été créé vous avez deux possibilités.
1. Rechercher un Customer via le portail :
Vous pouvez retrouver tous vos customers déjà créés ainsi que les cartes qui y sont liés, via le menu Transaction cartes, Customer.
Vous avez la possibilité de chercher via le nom, le prenom, l’email ainsi que votre réference personnalisée ou notre uuid.
Une fois dans les détails du customer vous pouvez verifier les transactions, les abonnements ainsi que les cartes liées au customer choisis.
2. Rechercher un Customer via l’API
Vous pouvez vérifier si vous avez déjà enregistré un customer en se basant sur la recherche de valeurs dans des objets de l’API, notamment "Customer", "Card" et "CardToken"
A) Cas d'un CustomerId déja référencé
Nous vous conseillons d'enregistrer les customerId de Centralpay dans votre environnement de manière à pouvoir les réutiliser par la suite. Vous pourrez ensuite récuperer les informations liées a un customer en se basant sur son uuid pour initier une transaction.
Dans le Json de retour de la création d'un customer, les valeurs vous serons fournies, telles que les cartes liées à votre customer, vous pouvez donc verifier si une carte a déjà été enregistrée.
Exemple :
{
"customerId": "3feb0242-2594-44a3-a550-4790306dfcdf",
"creationDate": "2020-05-18T14:12:23.251530+02:00",
"merchantCustomerId": "Client-0001",
"firstName": "JOHN",
"lastName": "DOE",
"email": "john.doe@gmail.com",
"phone": null,
"addressLine1": "17 RUE DE LA POSTE",
"addressLine2": "APPT 51",
"addressLine3": null,
"addressLine4": null,
"postalCode": "37000",
"city": "TOURS",
"country": "FRA",
"cards": [
{
"cardId": "00bdce25-081d-49e6-b0d5-27a0ad57a841",
"creationDate": "2020-08-11T12:26:46.805601+02:00",
"customerId": "3feb0242-2594-44a3-a550-4790306dfcdf",
"cardTokenId": null,
"merchantCardId": null,
"commercialBrand": "VISA",
"first6": "400000",
"last4": "0010",
"expirationMonth": 1,
"expirationYear": 2022,
"country": null,
"cardholderName": "JDOE",
"cardholderEmail": "crichard@centralpay.eu",
"description": null,
"fingerprint": "10721aca1a21d1db476611da0978073ab30b8c08",
"cardType": null,
"region": null,
"productType": null,
"europeanEconomicArea": null,
"additionalData": {}
},
{
"cardId": "3a9bfa88-816f-467b-aea3-f89dbd9c2157",
"creationDate": "2020-08-11T11:57:18.686423+02:00",
"customerId": "3feb0242-2594-44a3-a550-4790306dfcdf",
"cardTokenId": null,
"merchantCardId": null,
"commercialBrand": "VISA",
"first6": "400000",
"last4": "0002",
"expirationMonth": 1,
"expirationYear": 2022,
"country": "FRA",
"cardholderName": "JDOE",
"cardholderEmail": null,
"description": null,
"fingerprint": "36c3da543d36020089ca151dc28cab87ccf36753",
"cardType": null,
"region": null,
"productType": null,
"europeanEconomicArea": null,
"additionalData": {}
},
{
"cardId": "a94d9def-025d-4631-84f4-d0a77ac88a3a",
"creationDate": "2020-08-11T11:53:29.301174+02:00",
"customerId": "3feb0242-2594-44a3-a550-4790306dfcdf",
"cardTokenId": null,
"merchantCardId": null,
"commercialBrand": "VISA",
"first6": "400000",
"last4": "0010",
"expirationMonth": 12,
"expirationYear": 2035,
"country": null,
"cardholderName": "JDOE",
"cardholderEmail": null,
"description": null,
"fingerprint": "c20b2edda5bea300b995b678556e637b04657720",
"cardType": null,
"region": null,
"productType": null,
"europeanEconomicArea": null,
"additionalData": {}
},
{
"cardId": "377c3954-6053-427b-8c77-2605a53be71c",
"creationDate": "2020-05-18T14:12:23.499364+02:00",
"customerId": "3feb0242-2594-44a3-a550-4790306dfcdf",
"cardTokenId": null,
"merchantCardId": null,
"commercialBrand": "VISA",
"first6": "400000",
"last4": "0002",
"expirationMonth": 12,
"expirationYear": 2020,
"country": null,
"cardholderName": "JDOE",
"cardholderEmail": null,
"description": null,
"fingerprint": "7d601480c486eb5445e72a4b4e53ff4084679bcb",
"cardType": null,
"region": null,
"productType": null,
"europeanEconomicArea": null,
"additionalData": {}
}
],
"description": null,
"language": null,
"otpExpired": false,
"subscriptions": [],
"installmentPayments": [],
"fee": 0,
"totalCharge": 0,
"movementId": null,
"otpExpirationDate": null,
"additionalData": {}
}
B) Cas d'un CustomerId non référencé
Dans le cas ou vos customer ne sont pas référencés dans votre système avec leur customerId, nous vous conseillons aussi de vérifier que la carte qui se présente n'est pas déjà ratachée à un CustomerId existant. Cela, afin de ne pas enregistrer deux identités pour un même customer.
Pour se faire, au dela du fait de vérifier l'adresse email, vous pouvez vérifier que l'empreinte de la carte (identifié en tant que fingerprint dans centralpay) n'est pas déjà présente dans le cardId d'un customer existant. Le fingerprint étant l'empreinte unique identifiant une carte dans notre système. Elle est semblable pour chaque carte identique. Ainsi vous pouvez vous retrouver plusieurs fois le même fingerprint dans vos transactions. Il s'agira dans ce cas, de la même carte.
Exemple :
{
"cardId": "f5c1598f-fff6-46c7-8b05-57723f07d637",
"creationDate": "2020-09-22T11:32:47.870048+02:00",
"customerId": "88dfd3c5-c034-4403-9b21-f14bed00436f",
"cardTokenId": null,
"merchantCardId": null,
"commercialBrand": "VISA",
"first6": "400000",
"last4": "0002",
"expirationMonth": 9,
"expirationYear": 2035,
"country": "FRA",
"cardholderName": null,
"cardholderEmail": null,
"description": null,
"fingerprint": "cac21ea48d5b703930ff688ade9a115aadda9d92",
"cardType": null,
"region": null,
"productType": null,
"europeanEconomicArea": null,
"check": true,
"additionalData": {}
}
Conseil : A la création du cardToken, avant de faire une Transaction, vous disposez du fingerprint. Vous pouvez donc puis faire l’appel à l’objet carte pour comparer si la valeur existe avant de créer ou non un nouveau customer avec la carte qui se présente. Si une carte est déjà créé vous pouvez même utiliser cette carte et garder une tracabilité sur votre customer.
Remboursement
Fontionnement du remboursement via le Backoffice CentralPay.
L'objet refund
Cet objet vous permet de rembourser une transaction préalablement débitée.
Vous pouvez rembourser une transaction de manière partielle ou totale. Le refund vient débiter le compte de celui qui a émit la demande.
Votre Client verra le crédit apparaître sur sa carte entre 3 et 5 jours ouvrés après l'opération.
Notez que vous ne pouvez pas annuler un refund une fois celui-ci réalisé.
Cette opération est réalisable depuis le backoffice (détail de la transaction) ou depuis l'API avec l'objet Refund.
Smart Form
Simple à intégrer, Smart Form est un formulaire de paiement intelligent accessible par l’API via le service paymentRequest. Hébergé dans la zone PCI-DSS de CentralPay, il intègre les fonctionnalités de paiement les plus essentielles.
En utilisant Smart Form, vous évitez la partie la plus contraignante des exigences PCI-DSS. En effet, toutes les données sensibles sont directement traitées dans l'environnement PCI-DSS de CentralPay. Par conséquent, les données cartes bancaires ne transitent jamais par votre serveur.
Smart Form est rattaché aux services :
- paymentRequest qui initialise des demandes de paiement via l’API
- "Push & Pay" qui assure l’automatisation et l’émission des notifications de demande de paiement
Avec Smart Form, les parties les plus complexes des traitements sont gérées par CentralPay :
- La génération et l’hébergement du formulaire de paiement
- les vérifications des informations utilisateur,
- la gestion des différents moyens de paiement,
- la sécurisation des données de carte,
- les notifications de relances ou de demandes de paiement,
- les différents modes et types de paiement.
Le service est accessible :
- Via l’API CentralPay en intégration avec un SI tiers :
- Par redirection HTTPS vers un site internet
- Par des notifications e-mail/SMS
- Par l’affichage ou l’impression d’un QR code
- • Via la console web ou l’application mobile CentralPay
- Par des notifications e-mail/SMS
- Par des notifications e-mail/SMS
Exemple de formulaire de paiement "Smart Form"
Moyens de paiement disponibles
CARTES BANCAIRES
Visa, Mastercard, Amex, Bancontact…
CARTES BANCAIRES
Paiement en X fois pour échelonner les règlements de vos clients.
Visa, Mastercard, CB
Paiements SEPA
SCT - SEPA Credit Transfer (Virement SEPA)
SDD - SEPA Direct Debit (Prélèvement SEPA Core)
| Moyen de paiement | Etat | Type |
|---|---|---|
| AliPay | Not live | Wallet |
| American Express | Live | Card |
| ANCV | Not live | Voucher |
| Apple Pay / Google Pay | Not live | Wallet |
| Bancontact | Not live | Card |
| Carte Bancaire | Live | Card |
| Diners | Live | Card |
| Discover | Live | Card |
| GiroPay | Not live | Direct Debit |
| Ideal | Not live | Direct Debit |
| JCB | Not live | Card |
| Maestro | Live | Card |
| MasterCard | Live | Card |
| PayPal | Not live | Wallet |
| Postfinance | Not live | Card |
| Visa | Live | Card |
| Visa Electron | Live | Card |
Choix des moyens de paiement :
- Le paramétrage du point de vente permet de définir les moyens de paiement qui seront accessibles au client.
- En fonction des interactions souhaitables entre les règlements combinés, certains moyens ne sont pas nécessairement accessibles.
Associé au service Push & Pay, un Smart Form peut intégrer des modes de paiement évolués :
- Règlement à plusieurs participants
- Règlements combinés sur plusieurs moyens de paiement
- Automatisation des demandes, relances et notifications
Payment request
paymentRequest permet de définir les conditions et les modalités de règlement d’un montant à encaisser. L’instruction peut-être initiée pour être soit transmise en direct depuis une redirection HTTPS depuis un site Internet vers le formulaire de paiement, soit depuis le service PUSH & PAY par notification e-mail/SMS ou par affichage d’un QR Code.
Avec le service PUSH & PAY, il est ainsi possible de créer des workflows complexes permettant l’interaction poussée avec les consommateurs ou des plateformes tierces. Vous devez donc paramétrer les modèles e-mail/SMS et les scénarios avant d’utiliser cet objet.
Fonctionnement d’une demande de paiement
Une demande de paiement permet de réserver un montant à régler selon des modalités définies dans sa requête.
- Montant Fixe :
- Le règlement est fixé à un seul montant (totalAmount).
- Le Payeur ne pourra pas modifier le montant.
- Montant Fixe avec règlement échelonné avec installment :
- Permet de découper le montant initial en plusieurs règlements (Installment) selon une fréquence définie.
- Abonnement avec l'object subscription :
- Par le biais de la demande de paiement, le payeur souscrit à un abonnement que vous définissez.
- Montant Partiel :
- Le montant du règlement est libre. Le Payeur pourra payer en plusieurs fois en fixant lui-même le montant ou réadresser la demande de paiement à des tiers.
- Règlement à plusieurs à base de montants fixes :
- Le montant total se subdivise en plusieurs sous-montants qui sont affectés à chaque participant
- Chaque participant recevra ensuite une notification par e-mail ou SMS lui permettant de se rendre sur la page de paiement afin de régler le montant qui lui a été alloué.
Le paramétrage revient à renseigner les données suivantes en fonction du contexte :
| Je paie | |||||
|---|---|---|---|---|---|
| Seul | À plusieurs | ||||
| Destinataire | Montant | Destinataire | Montant | ||
| Montant | Partiel | @1 --> | N/A | @1 --> @2 --> @3 --> |
N/A N/A N/A |
| Fixe | @1 --> | 1 000 € | @1 --> @2 --> @3 --> |
500 € 300 € 200 € |
|
Une demande de paiement réussie adresse en réponse :
- L’adresse du formulaire de paiement et les caractéristiques associées sous forme de :
- QR CODE
- URL
- UUID de la requête
La liste des moyens de paiement disponibles est paramétrable sur le point de vente défini par :
- Carte Bancaire
- Carte bancaire en X fois
- Chèque Vacances
- Virement
- Wallet
- FidelyPay
Initialisation des demandes
Les demandes de paiement sont initialisables depuis :
- L’API
- La console CentralPay
- L’application mobile CentralPay
Les types de demandes de paiement
Il existe 3 types de demandes de paiement depuis le Back office :
1/ Les demandes instantanées :
Elles sont caractérisées dans l’interface par un symbole d’éclair et peuvent être créées comme ce qui suit :
Elles comprennent la possibilité de réaliser des transactions, des cautions, des abonnements, des paiements en X fois, en CB ou en SDD et des virements. Il est également possible de créer des customers en enregistrant les données de vos clients, ou de rechercher des customers déjà existant.
Des paramètrages supplémentaires seront disponibles pour configurer les paiements en X fois et les abonnements :
2/ Les demandes programmées :
Elles sont caractérisées dans l’interface par un symbole d’horloge et peuvent être créées comme ce qui suit :
Elles comprennent les même options que les instantanées comme la possibilité de réaliser des transactions, des cautions, des abonnements, des paiements en X fois, en CB ou en SDD et des virements. Il est également possible de créer des customers en enregistrant les données de vos clients, ou de rechercher des customers déjà existant.
La différence avec les demandes de paiement instantané reside dans la possibilité d’utiliser un profil spécial, ainsi que certaines options :
- Une date limite de paiement est ajoutable, date à partir de laquelle votre client ne pourra plus payer.
- Une date limite d’expiration, qui est la date à partir de laquelle le formulaire de paiement expire.
- L’ajout d’un scénario qui va vous permettre de configurer des notifications précises sur cette demande de paiement.
- L’ajout d’un email de réception de confirmation de paiement.
- Une langue pour la demande de paiement.
- Une règle d’affichage qui permet de choisir un template d’affichage et un formulaire SMART FORM customisé si besoin.
- L'envoi d'une Pièce jointe dans le mail de confirmation de paiement.
3/ Importation de demande de paiement de masse :
La fonctionnalité est disponible depuis via le bouton import sur la page de listing des demandes de paiements (Backoffice 10.7.0) :
Attention pour avoir accès à cette fonctionnalité, il faut être connecté en Marchand et avoir l’ACL ‘cpay_core_payment_request’ en CREATE.
Au clic sur le bouton importer, une popin apparait :
A partir de celle-ci, il est possible de directement uploader un fichier CSV ou JSON, ou bien de télécharger un modèle (les données sont fictives et données à titre d’exemple).
L’option « forcer l’importation » permet de soumettre l’import malgré des erreurs de syntaxe.
Listing des champs du fichier à importer :
|
Libellé |
Description |
Commentaires |
|
profile_uuid* |
UUID du profil de demande de paiement |
Doit exister et appartenir au marchand |
|
merchant_payment_request_id |
Référence marchand |
Entre 0 et 100 caractères |
|
description |
Description |
Entre 0 et 255 caractères |
|
total_amount* |
Montant de la demande de paiement |
Doit être > 0 |
|
last_name |
Nom |
Entre 0 et 35 caractères |
|
first_name |
Prénom |
Entre 0 et 35 caractères |
|
Email * si phone vide |
|
Obligatoire si Phone vide *Si l’email est présent dans la base Customer (et create_customer à N), les données du Customer seront reprises. *Si l'email (et éventuellement nom et prénom) est associé à plusieurs Customer, c’est le dernier crée qui sera repris. |
|
Phone * si email vide |
Téléphone |
Obligatoire si Email vide Entre 0 et 255 caractères Format International : ^\\+[0-9]{1,15}$ Ex : +33612345678 * Si email est fourni et est présent dans la base Customer (et create_customer à N), les données du Customer seront reprises.
* Si un email est fourni (et éventuellement nom et prénom) et est associé à plusieurs Customer, c’est le dernier crée qui sera repris. |
|
create_customer* |
Création d'un customer |
Valeur possible : "Y" (oui) ou "N" (non) |
|
link_expiration_date |
Date limite de paiement |
Si rempli, surcharge celle du profil de demande de paiement. |
|
deadline |
Date d'expiration du lien |
Si rempli, surcharge celle du profil de demande de paiement |
|
receipt_email |
Email de réception confirmation de paiement |
Si rempli, surcharge celle du profil de demande de paiement.
|
|
language
|
Langue utilisée dans la demande |
Si rempli, surcharge celle du profil de demande de paiement. |
Attention, il est nécessaire de mettre tous les champs dans le fichier, sans ordre précis.
Si le fichier contient des erreurs par rapport aux contraintes listées ci-dessus, un message d’erreur sera affiché en haut de la popin afin que le marchand corrige son fichier :
Si le fichier passe les vérifications, le marchand sera redirigé sur la page de listing des demandes de paiement avec un message :
C’est ensuite le batch qui va créer les demandes de paiement et envoyer un mail récapitulatif à l’adresse mail du profil qui a créé l’import.
Statuts de demandes de paiements
Un certain nombre de statuts liés à la demande de paiement sont disponibles afin de faciliter le suivis de celle-ci. Les statuts s’influencent entre eux et sont changés suite à certaines actions manuelles ou automatiques sur notre plateforme.
Il faut distinguer les statuts de la demande de paiement elle-même et ceux du moyen de paiement mis en place pour y répondre.
Nous pouvons distinguer 4 paramètres de statuts différents sur une demande de paiement :
- Les statuts de la demande
- Les statuts du paiement
- Les statuts du Breakdown
- Les statuts du débit
Les statuts de la demande peuvent être accompagné d’une raison pour certains.
Statuts de la demande :
Concerne les statuts de la demande paiement par elle même.
Active
La demande de paiement est ouverte
Fermée
Les opérations ont été correctements réalisées par l'utilisateur et le client, aucune actions disponible désormais
Annulée
Une erreur a été commise par l'utilisateur, ou le paiement n'a pas été réalisé à temps par le client
Concernant l’action de fermeture d’une demande de paiement, une raison est demandé en plus de la fermeture.
L’annulation de la demande de paiement n’entraine pas un remboursement ou l’annulation sur le moyen de paiement utilisé.
Statuts du paiement :
Concerne les statuts du paiement par lui même. Les moyens de paiement mis en place dependent du choix effectué lors de la création de la demande de paiement, mais tous possèdent les mêmes statuts.
Payé
La demande de paiement à été honorée, entraine un statut de la demande Fermée
Partiel
La demande de paiement à été partiellement honorée, le statut de la demande est toujours Active
Non Payé
La demande de paiement n’est pas honorée. Ce statut est présent au début, tant que la demande de paiement n’est pas honorée mais est également présent à l’annulation de la demande de paiement
Statuts du Breakdown :
Le Breakdown contient les données d'un client : les status des paiements individuels.
Dans le cadre d’une transaction avec un client unique, la payment request, le breakdown et le paiement ont le même statut.
Dans le cadre d’une transaction avec plusieurs clients alors il peut y avoir une disparité au niveau des statuts du breakdown.
Payé
Le client a honoré la demande de paiement
Partiel
Le client a honoré partiellement la demande de paiement, le statut de la demande est toujours Active et le statut du paiement est Partiel
Non Payé
Le client n’a pas honoré la demande de paiement. Ce statut est présent au début, tant que la demande de paiement n’est pas honorée mais est également présent à l’annulation de la demande de paiement
Selon le nombre de client, les statuts peuvent se combiner et donner des cas où plusieurs statuts cohabitent.
Statuts du debit :
Le statut du débit décrit l’état du débit, une fois la demande de paiement honorée.
Uncaptured
Il est possible de faire des transactions ou les paiements ne seront pas sécurisé immédiatement. Ce statut apparait dans ce cas uiquement.
Captured
Le paiement est sécurisé et sera bientôt débité
Cleared
Le paiement est débité
Pending
Aucune action de capture ou de pré-capture sur le paiement n'ont été effectuées, paiement non sécurisé.
Profil de Demande de Paiement
Les profils sont liés au service Push & Pay et aux demandes de paiements. Les profils reprennent les paramètres des demandes de paiements et la possibilité de choisir un scénario. Ils vont constituer des templates de comportements déjà pré-fait qui seront appliqués automatiquement aux demandes de paiement dans lesquelles le profil sera selectionné. Ils peuvent ensuite être utilisés dans les demandes de paiement programmées et les demandes de paiement de masse.
Dans la partie configuration générale, il est possible de choisir un nom, un point de vente, une devise liée au point de vente et une langue, qui va influencer la langue dans laquelle les informations seront affichées pour vos clients.
Dans la partie moyens de paiement, il est possible de choisir la nature de la demande de paiement (Transaction, Caution, Paiement en X fois, abonnement ou virement).
Enfin dans les options, il est possible de choisir une limite de paiement (après laquelle votre client ne sera plus en possibilité de payer), une limite d’expiration du lien (après laquelle votre client ne sera plus en possibilité de payer par le formulaire spécifiquement), la possibilité de choisir un scénario qui va envoyer des notifications aux moments clefs de la demande de paiement, un email de réception de confirmation de paiement, des règles d’affichage, la possibilité d’ajouter des pièces jointes et enfin la possibilité de créer automatiquement des customers dès que le profil est utilisé.
Règles d'affichage - Paramètrage de Formulaire et redirection du smart form
Les paramètrages de formulaire sont des templates de SMART FORM, customisés selon vos besoins. Ils sont appellés “Régles d’affichages” dans la création des demandes de paiement. Ces templates sont présents dans les demandes de paiement programmées, par un choix ou via le profil choisis. Ils sont également présent dans les demandes de paiement de masses via le profil choisis.
Les champs disponibles pour les templates sont : le nom du template, la possibilité d’en faire le template par défault, la possibilité d’afficher le champ CVV ainsi que la possibilité de forcer le fait de créer un customer. Sont également disponibles les champs comprenant l’URL de redirection ainsi que le delais avant la redirection.
Enfin, il est possible d’ajouter des champs supplémentaires aux formulaires générés automatiquement, les champs cochés seront ajoutés aux champs déjà présent sur le SMART FORM classique. Les champs ajoutés peuvent différés si le template est utilisé pour les virements ou pour une demande de paiement avec une carte.
Le liste des champs supplémentaire est la suivante :
- Adresse 1
- Adresse 2
- Adresse 3
- Adresse 4
- Ville
- Pays
- Prénom
- Téléphone
- Code Postal
Cas d'usage
Demande de paiement unitaire
Il s’agit d’une demande de paiement à une transaction comprenant un montant et une devise. Elle reste associée à un scénario permettant de gérer les cas définis par l’utilisateur.
Règlement simple d’un montant unique :
- Montant
- Devise
- Langue
Exemple cURL :
curl -v https://test-api.centralpay.net/v2/rest/paymentRequest \
-u 'doctest:4I9HJRTd' \
-F paymentMethod[]='TRANSACTION' \
-F currency='EUR' \
-F totalAmount=100000 \
-F partial=false \
-F breakdown[]='{"amount":100000, "email":"johnDoe@hotmail.com"}' \
-F transfer[]='{"destinationWalletId":"10cfe034-ba9a-457e-b13d-fc68a5bfd171", "amount":100000, "email":"johnDoe@hotmail.com"}'Réponse JSON :
{
"paymentRequestId": "cd80f9c9-d121-44a6-a6a9-3f775a5acff8",
"creationDate": "2020-08-13T15:34:02.004118+02:00",
"pointOfSaleId": "cfc0b3c7-e666-4c52-b77a-96f234b873fe",
"deadline": null,
"linkExpirationDate": null,
"endingDate": null,
"scenarioId": null,
"paymentFormTemplateId": null,
"merchantPaymentRequestId": null,
"description": null,
"currency": "EUR",
"totalAmount": 100000,
"paymentRequestStatus": "ACTIVE",
"paymentStatus": "UNPAID",
"createCustomer": false,
"paymentMethods": [ "TRANSACTION" ],
"transaction": {
"paymentRequestTransactionId": "2f813571-dc15-4149-a39c-0a671d301bb2",
"contractId": "71602dd0-2790-4743-877b-e72530d7576d",
"receiptEmail": null,
"source": "EC"
},
"installment": null,
"subscription": null,
"breakdowns": [
{
"paymentRequestBreakdownId": "4dc27147-4d46-4b68-ba2f-49f6f3a8871b",
"customerId": null,
"lastEnteringDate": null,
"lastPaymentAttempt": null,
"amount": 100000,
"initiator": true,
"endpoint": "https://test-form.centralpay.net/25cd87d7-2dd8-4f08-8b78-2f84f5496ffd",
"email": "johnDoe@hotmail.com",
"phone": null,
"firstName": null,
"lastName": null,
"entered": false,
"paymentAttempted": false,
"paid": null,
"view": 0,
"status": "UNPAID",
"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": {}
}
Intégration du Smart form
Nous allons vous présenter les différentes étapes présentent lors d'une intégration standard de notre Smart Form.
Dans un premier temps, il faut initier une payment request avec les informations de payment que vous souhaitez et que vous avez récuperrer auprès du client. L'initialisation se fait généralement via un curl php. Vous pouvez retrouver un cURL PHP sur notre site example.
Pour des raison de lisibilité des informations envoyées notre exemple se fera en cURL natif.
Exemple cURL natif :
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}"'
Une fois cette Payment request correctement initée, nous renvoyons une réponse en JSON. Les informations pour afficher le smart form sont présentes dans cette réponse, aussi vous devez la récuperer et la traiter afin de pouvoir récuperer le ou les endpoint(s). Il y a plusieurs endpoints si vous initiez une payment request avec plusieurs payeur, et donc plusieurs breakdowns.
Réponse du curl exemple :
{
"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": {}
}Exemple de endpoint :
"endpoint": "https://test-form.centralpay.net/b670bb15-c243-450c-aa2b-ea6b077231e2"
La dernière étape consiste à afficher le smart form à votre client. Vous pouvez ou vrir le smart form dans un autre page, ou l'intégrer diréctement à votre page via un iframe.
Exemple de 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 vous permet de créer vos propres formulaires de paiement et de consommer les objets de l’API de manière unitaire afin de créer une expérience de paiement unique totalement intégré à votre service.
Un Custom Form est donc créé et hébergé par vos soins tout en vous permettant de réduire fortement les risques sécuritaires quant à la manipulation de données bancaires. En intégrant le processus de paiement de votre côté, vous gardez le contrôle de la page de paiement et de l’expérience utilisateur.
Tutoriel Custom Form
Ce tutoriel explique comment utiliser le langage HTML et Token.js pour obtenir un cardTokenID afin de créer une transaction depuis votre propre formulaire de paiement.
Le Token.js est le JavaScript que nous mettons à votre disposition pour vous aider à implémenter le premier composant dont vous avez besoin pour créer un cardTokenID.
Une fois que vous obtenez un cardTokenId, vous serez en mesure d’initialiser une transaction pour débiter la carte de votre client.
Voici les étapes :
1Créer un formulaire de paiement HTML
Contrairement au SMART FORM qui est généré par la plate-forme sur la base d’une initialisation de votre part, le CUSTOM FORM est à créer.
Vous devez donc générer le code HTML qui vous convient.
2Envoyer les informations de carte de débit/crédit avec le Token.js
Vous devez maintenant envoyer les données cartes du navigateur du client à la plateforme PCI qui vous adressera un cardTokenId. Pour se faire, vous devez ajouter dans le <body> le tag suivant :
<script src="https://test-js.centralpay.net/js/token.js"></script>Puis votre merchantPublicKey dnas un tag séparé :
<script type="text/javascript">
window.Centralpay ? Centralpay.card.setMerchantPublicKey('8ce4b92abd7c3110e2033ffbfa7cca0f097a66f1f1d267ff6c94429884ed82ac') : alert('Error loading html form');
</script>La merchantPublicKey identifie vos requêtes vers la Plateforme. Dans l'exemple ci-dessus, il faudra utiliser celle qui vous a été communiqué.
3Réceptionner le cardTokenID dans votre système
Cette étape va consister à récupérer le cardTokenID que vous récupérerez dans le JavaScript afin de pouvoir soumettre votre requête à la plateforme.
Toutes les données de la carte sont maintenant stockées dans cardTokenID pendant une durée de 5 mn. C’est donc cette valeur que vous présentez à l’API et non les données de la carte bancaire.
4Créer une transaction à l'aide de la cardTokenID
Maintenant que vous êtes en possession du cardTokenID vous allez pouvoir l’utiliser pour initialiser une transaction.
À la différence des étapes précédentes qui se déroulent depuis le navigateur, celle-ci sera exécutée depuis vos serveurs. Par exemple :
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 \5Sauvegarder les informations d'une carte dans un customer en vue d'un usage ultérieur (1 click, subscription...)
cardTokenId n’est utilisable qu’une fois. Si vous prévoyez d’utiliser les données de la carte ultérieurement, vous devez donc créer un customer et y enregistrer une card.
Ainsi, la prochaine fois, au lieu d’utiliser un nouveau cardTokenId , vous utiliserez le customerID correspondant.
SDD Transaction
Une SDDTransaction est un transfert compte à compte direct entre un marchand (créditeur) et un customer (débiteur).
Les pré-requis pour qu’une SDDTransaction puisse se faire est qu’il y ait deux comptes bancaires. Le compte bancaire "Marchand" sera le compte "créditeur". Le compte de votre Client que vous pouvez créer vous même, sera le comptes "débiteur". Le mandat précisant les modalités sera signé électroniquement par les débiteurs.
Attention : Le débiteur peut demander le remboursement du prélèvement SDD Core dans un délai de 8 semaines, quel que soit le motif, et de 13 mois pour "opération non autorisée", c'est à dire invalidité ou absence de mandat.
La durée de validité d’un mandat n'excède pas 36 mois.
Voici les étapes de création d'une SDDTransaction
1 Créer le compte bancaire (à l'aide de l'objet customer)
- Récuperer les nouvelles informations de votre client
- Nous les transmettre grace aux champs owner[] , ainsi que le customerId existant de votre client
- Un bankAccountId va être généré à la création
2 Créer le mandat (à l'aide des deux bankAccountId et de l'objet customer)
- Plusieurs mandats peuvent être créés avec les deux même comptes bancaires.
- Determiner un type de mandat (Ponctuel ou Récurrent).
- Nous transmettre les informations du mandat, ainsi que le bankAccountId du créditeur et le bankAccountId du débiteur et le customerId existant
- Un mandateId et un OTP vont être générés à la création. L'OTP va être envoyé à votre client par SMS.
L'OTP est un système de code secret que va recevoir votre client, et qui va vous permettre d'effectuer des validations ou des signatures en toute securité.
L'OTP a une durée de vie de 15 minutes, aussi il est possible de le renouveler avec ou sans un nouveau numéro de téléphone.
Séquencement des prélèvements : pour un prélèvement unique ou un premier prélèvement d'une série, le délai minimum de remise du prélèvements SDD est fixé à 5 jours ouvrés avant l’échéance.
3 Signer le mandat (avec l'OTP)
- Récuperer auprès de votre client son code secret
- Nous le transmettre, ainsi que le mandateId
- En faisant cela, le mandat est concidéré comme signé de la part des deux parties
4.1Créer une SDDTransaction (à l'aide du mandat)
- Vous pouvez maintenant créer une SDDTransaction.
- Configurez vos SDDTransaction, en mettant les informations correspondent à vos souhaits, et précisez le mandateId
- Pour plus de sécurité, vous pouvez configurer un OTP pour la validation de chaque SDDTransaction : un OTP sera alors généré à la création et envoyé à votre client par SMS. Un sddTransactionId sera également généré à la création.
- Par défaut la validation des SDDTransaction est automatique.
4.2Valider une SDDTransaction (si une validation OTP à été configurée)
- Cette étape est necéssaire que si vous avez configuré une validation OTP pour la SDDTransaction
- Récuperer auprès de votre client son code secret
- Nous le transmettre, ainsi que le sddTransactionId .
- Par cette action, la SDDTransaction sera considéré comme validée et sera donc effectuée.
Voici le schéma détaillé de la SDDTransaction, et pour plus d'information technique vous pouvez consulter la documentation associée :
Et un schéma de la SDDTransaction, si une validation OTP est mise en place :
5.3Inverser un SDDTransaction
- Il est possible d'inverser un SDDTransaction si celui-ci est "Cleared"
- Pour cela vous pouvez procéder via l'interface du SDDTransaction concerné dans le Back Office ou via une requète /sddTransactionReversal
Virtual IBAN
Afin de simplifier le lien entre le customer et le marchand lorsque ce premier souhaite déposer des fonds via virement, nous avons mis en place le "Virtual Iban". Il n'y aura avec celui-ci plus besoin d'utiliser de référence sur les virements, chaque customer aura un vitual iban spécifique. Vous pourrez trouver celui-ci à 4 endroits :
- Sur un customer
- Sur un marchand
- Lors de la réalisation d'un SCT Transaction
- Sur une demande de paiement
Customer
-
Il est possible de génerer un virtual iban sur un customer, soit à la création, soit à l'update si dèjà créé
-
Ici nous allons le faire a la création mais le process est le meme pour l'update, voici le code curl, on passe ici le walletId du marchand :
-
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'
Réponse :
{
"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": {}
}
Cette réponse est renvoyée quand le customer a bien été créé avec un virtual IBAN
Marchand
-
Il est possible de trouver un virtual iban sur un marchand via le backoffice :
-
Réalisation d'un SCT Transaction
-
Lorsque vous allez appelez le service /sctTransaction vous allez pouvoir passer en paramètre l'ibanWalletId lié au wallet ID du marchand où l'argent va aller.
-
Exemple de code Curl :
-
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'
Réponse :
{
"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": {}
}
Cette réponse est renvoyée quand le SCT Transaction a bien été effectué avec un virtual IBAN
Demande de Paiement
-
Vous pourrez trouver un virtual iban sur une demande de paiement de type virement :
-
