Transaction carte via wallet

Estimated reading: 14 minutes

1. Apple Pay (Smart Form)

Apple Pay est intégré nativement au parcours de paiement carte du SmartForm (PaymentRequest > paymentMethod[]=TRANSACTION) dès que l’appareil de votre client est compatible.

Aucune action n’est requise de votre part. Le service est entièrement opéré par CentralPay (détection de l’appareil, gestion des certificats et des tokens Apple, sécurité PCI-DSS). Aucune donnée de carte n’est exposée côté marchand (périmètre PCI-DSS SAQ-A).

2. Apple Pay (Custom Form)

2.1. Via token Apple Pay déchiffré

CentralPay permet le traitement des paiements par carte effectués via Apple Pay, dans le cadre d’une intégration Custom (hors Smart Form).

ℹ️ CentralPay ne prend actuellement en charge que les tokens Apple Pay déchiffrés. Cette méthode implique une responsabilité PCI-DSS importante de votre part (formulaire SAQ-D). Renseignez-vous et assurez-vous d'être en conformité avant de développer ce mode d'intégration.

Prérequis

1. Créer un compte Apple Developer :

  • Inscrivez-vous au programme Apple Developer
  • Créez vos identifiants de marchand Apple Pay (Merchant ID)
  • Générez votre certificat de traitement Apple Pay via le portail Apple
  • Déclarez votre domaine (Apple Pay Merchant Domain)

2. Intégration côté device :

  • Implémentez Apple Pay côté frontend via Apple Pay JS (pour les sites web) ou PassKit (pour les apps iOS)
  • Collectez le token Apple Pay (ApplePayToken) après validation du paiement par l’utilisateur (Face ID, Touch ID…)
🔐 Certificats requis pour une intégration Apple Pay
Pour traiter des paiements Apple Pay dans le cadre d’une intégration directe, le marchand doit disposer des éléments suivants :
• un certificat Merchant ID Identity ;
• un certificat Merchant Payment Processing G2.

Le marchand doit veiller à conserver l’ensemble des clés privées utilisées lors de la génération des CSR associées à ces certificats.

1. Merchant ID Identity
La génération d’un CSR basé sur une clé EC (256 bits) est requise.
Cette CSR sera générée par Centralpay

2. Merchant Payment Processing Certificate

Étapes principales :
• Demander le CSR généré par Centralpay
• Soumettre le CSR depuis le compte développeur Apple afin d’obtenir le Merchant Payment Processing Certificate.
• Installer le certificat sur le même poste macOS ayant servi à la génération de la CSR afin qu’il soit associé à la clé privée.
• Exporter l’identité complète au format .p12 (certificat + clé privée).

⚠️ Si l’option d’export au format .p12 n’est pas disponible, cela indique qu’une étape du processus n’a pas été correctement réalisée (clé privée manquante ou non associée).

Le fichier .p12 constitue un conteneur sécurisé permettant l’exploitation ultérieure de la clé privée associée au certificat, conformément au flux Apple Pay.

Notes importantes :
• Toute perte de la clé privée nécessite la recréation complète du certificat depuis le portail Apple Developer.
• La documentation Apple Pay peut prêter à confusion : l’utilisation d’OpenSSL ne concerne que le certificat Merchant ID Identity, et ne s’applique pas au Merchant Payment Processing Certificate.

Étape 1 : Déchiffrement du token Apple Pay

Le déchiffrement du token Apple Pay doit être effectué sur votre backend, à l’aide de :

  • Votre certificat de traitement Apple Pay
  • Votre clé privée
  • La documentation Apple : Payment Token Format

Le résultat contiendra :

{
  "applicationPrimaryAccountNumber": "5454********2664",
  "applicationExpirationDate": "YYMMDD",
  "paymentData": {
    "cryptogram": "base64-cryptogram",
    "eciIndicator": "05"
  }
}

Étape 2 : Création du cardToken CentralPay

Utilisez l’endpoint POST /cardToken de l’API CentralPay

ChampDescription
card[number]PAN de la carte extrait du token Apple Pay
card[expirationMonth]Mois d’expiration de la carte (format MM)
card[expirationYear]Année d’expiration de la carte (format YYYY)
onlinePaymentCryptogramCryptogramme issu du token Apple Pay (CAVV)
eciIndicatorIndice d’authentification issu du token Apple Pay (eci)
applePayTransactionIdID de la transaction Apple Pay
amountMontant en centimes (ex : 2500 = 25,00 €)
currencyCode alpha ISO (ex : EUR, USD, etc.)
merchantPublicKeyClé publique fournie par CentralPay
ℹ️ Où trouver la merchantPublicKey ?
Connectez-vous à votre portail         
            CentralPay Back Office  Administration  Technique  Merchant Public Key

Exemple :

card[number]=5454696696312664
card[expirationMonth]=12
card[expirationYear]=2031
onlinePaymentCryptogram=MGnp3S1LBgJxAANgdNCRAoABFIA=
applePayTransactionId=3d2b17abed2696ca...
amount=2500
currency=EUR
merchantPublicKey=abcdef123456...

Le cardToken généré contient toutes les données nécessaires à l’authentification Apple Pay.

Étape 3 : Création de la transaction CentralPay

Utilisez l’endpoint POST /transaction de l’API CentralPay

Champs requis :

cardToken=...
amount=2500
currency=EUR
pointOfSaleId=...
endUserIp=...
merchantTransactionId=...

Le cardToken encapsule déjà le contexte Apple Pay et les données d’authentification.

Étape 4 : Testing avant mise en production

L’environnement de test CentralPay permet de valider l’ensemble de votre intégration Apple Pay sans déclencher de véritables paiements. Il est fortement recommandé d’utiliser cet environnement pour toutes les phases de développement, de debug et de validation côté frontend comme backend.

Portail de test
API de test
Cartes de test

Différences entre environnement de test et de production :

2.2. Via token ApplePay chiffré (hybride)

ℹ️ Si cette méthode d’intégration vous intéresse, veuillez contacter le support CentralPay afin de connaître les livrables associés et les modalités d’accès.

2.2.1. Paramétrage du compte Apple

– Se connecter sur « https://developer.apple.com/ », créer un compte et valider le compte déveloper à 99$)

– Aller sur https://developer.apple.com/account/resources/identifiers/list

– Dans « App IDs », choisir « Merchant IDs » :

Puis cliquer sur le « + » pour ajouter un « Identifier » :

Choisir « Merchant IDs » : 

Renseigner le nom de l’identifier et cliquez sur « Register » : 

Aller à https://developer.apple.com/account/resources, puis cliquer sur Identifiers 

Sur Identifier, selectionner un Merchant IDs en utilisant le filtre en haut à droite

Sous « Apple Pay Payment Processing Certificate », cliquer sur « Create Certificate« .

Indiquez que ce « Merchant ID » ne sera PAS (No) utilisé uniquement pour la Chine.

A ce moment là cliquez sur « Choose File » afin d’envoyer le fichier CSR qui vous a été envoyé par CentralPay(uniquement CentralPay)

Vous pouvez télécharger le fichier généré.
Il reste à créer le certificat « Apple Pay Merchant Identity Certificate » 
Pour cela aller à https://developer.apple.com/account/resources, puis cliquer sur Identifiers et enfin cliquer sur l’Identifier que vous voulez éditer.
Une fois ouvert, cliquez sur « Create Certificate ».

Ajoutez votre certificat : 

Ajouter le domaine associé

Indiquez le nom de domaine en question : 

Téléchargez le fichier indiqué par Apple

Déployez le fichier indiqué par Apple sur un serveur du nom de domaine en question accessible à Apple, puis cliquez sur « Verify » :

Vous pourrez alors télécharger le certificat nécessaire.

2.2.2. Paiement via Applepay

Création d’un ApplePayToken avec Apple Pay JS API (Démo à https://applepaydemo.apple.com/apple-pay-js-api)

Frontend : 

<script crossorigin
     src="https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js">        
</script>
<style>
        apple-pay-button {
        --apple-pay-button-width: 250px;
        --apple-pay-button-height: 100px;
        --apple-pay-button-border-radius: 99px;
        --apple-pay-button-padding: 0px 0px;
        --apple-pay-button-box-sizing: border-box;
        }
</style>
<apple-pay-button id="btn-card" buttonstyle="white-outline" type="plain" locale="fr-FR"></apple-pay-button>
<br />
<div data-info="gateway-link" class="text-small text-gray-light font-weight-normal ml-1">
        <img src="https://docs.centralpay.com/wp-content/uploads/2024/10/paysecure_reassurance_1-fond_blanc.png" alt="CentralPay" style="max-width:200px"></a>
</div>
var request = {
    countryCode: 'FR',
    currencyCode: 'EUR',
    supportedNetworks: ['visa', 'masterCard', 'amex'],
    merchantCapabilities: ['supports3DS'],
    total: { label: 'Your Merchant Name', amount: '10.00' },
}
var applepayversion = 3;
var session = new ApplePaySession(applepayversion, request);

session.onvalidatemerchant = event => {
    // Call your own server to request a new merchant session.
    console.log("event.validationURL :"+event.validationURL);

    fetch('/applepay-session')
    .then(res => res.json()) // Parse the response as JSON.
    .then(merchantSession => {
        session.completeMerchantValidation(merchantSession);
    })
    .catch(err => {
        console.error("Error fetching merchant session : ", err);
    });
};

session.onpaymentauthorized = (event) => {

    var token = event.payment.token;
    fetch(`https://api.centralpay.net/cardToken`, {
        method: "post",
        body: JSON.stringify(
                { 
                    applePayToken: "xxxxxx",
                    merchantPublicKey: "xxxxxx",
                    endUserIp: "127.0.0.1"
                    }),
    })
    .then(res => res.json())
    .then(captureResult => {
        console.log(captureResult);

        // Récupération du token CPAY 
        // Envoi du token vers le backoffice pour /card ou /transaction
    })
    .catch(captureError => console.error(captureError));
};

session.begin();

Backend : 

$router->map('GET', '/applepay-session', function (ServerRequestInterface $request) use ($twig) : ResponseInterface {
    
    $APPLE_URL = "https://apple-pay-gateway.apple.com/paymentservices/paymentSession"; 

    $curl = new Curl();
    $curl->setHeader('Content-Type', 'application/json');
    $curl->setOpt(CURLOPT_POSTFIELDS, '{
            merchantIdentifier: "merchant.net.centralpay.test-form",
            displayName: "MyStore",
            initiative: "web",
            initiativeContext: "merchant.net.centralpay.test-form"
        }'
    );
    $curl->setOpt(CURLOPT_CUSTOMREQUEST, "POST");
    $curl->setOpt(CURLOPT_URL, $APPLE_URL);
    $curl->exec();
    ...
    return new Laminas\Diactoros\Response\JsonResponse($curl->getResponse());
    ...
});

Création de CardToken avec votre token Apple pay chiffré.

Lors de votre appel API, en plus des champs obligatoires, il faudra utiliser le champ « applePayToken«  au format JSON comprenant votre token Apple Pay qui incluent les éléments paymentData, paymentMethod et transactionIdentifier.
Vous pourrez ensuite effectuer une transaction à l’aide de votre cardToken normalement.

Utilisez l’endpoint POST /cardToken de l’API CentralPay
Champs requis :

curl --location 'https://test-api.centralpay.net/cardToken' \
--header 'Origin: https://example.centralpay.net' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'merchantPublicKey=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--data-urlencode 'endUserIp=xxxx.xxxx.xxxx.xxxx'
--data-urlencode 'applePayToken=xxxxxxxxxxxxxxxxxxxxxx'

Création de la transaction :

Utilisez l’endpoint POST /transaction de l’API CentralPay
Champs requis :

curl --location 'https://api.centralpay.net/transaction' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ••••••' \
--data-urlencode 'customerId=870005ca-xxxx-xxxx-xxxx-140fa71d6e01' \
--data-urlencode 'cardTokenId=xxxxxxxxxxxxxxxxxxxxxxxx'
--data-urlencode 'currency=EUR' \
--data-urlencode 'amount=1000' \
--data-urlencode 'endUserIp=xxxx.xxxx.xxxx.xxxx' \
--data-urlencode 'endUserLanguage=fre' \
--data-urlencode 'source=EC' \
--data-urlencode 'browserUserAgent=Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.41 Safari/537.36' \
--data-urlencode 'browserAcceptLanguage=en_US' \
--data-urlencode 'email=xxxxx@example.com' \
--data-urlencode 'country=FRA' \
--data-urlencode 'merchantTransactionId=1234567890123456789'

Le cardToken encapsule déjà le contexte Apple Pay et les données d’authentification.

Création de Transaction avec votre token Apple pay chiffré.

Lors de votre appel API, en plus des champs obligatoires, il faudra utiliser le champ « applePayToken » au format JSON comprenant votre token Apple Pay qui inclus les éléments paymentData, paymentMethod et transactionIdentifier.

Puis utilisez l’endpoint POST /transaction de l’API CentralPay

Champs requis :

curl --location 'https://api.centralpay.net/transaction' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ••••••' \
--data-urlencode 'customerId=870005ca-xxxx-xxxx-xxxx-140fa71d6e01' \
--data-urlencode 'currency=EUR' \
--data-urlencode 'amount=1000' \
--data-urlencode 'endUserIp=xxxx.xxxx.xxxx.xxxx' \
--data-urlencode 'endUserLanguage=fre' \
--data-urlencode 'source=EC' \
--data-urlencode 'browserUserAgent=Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.41 Safari/537.36' \
--data-urlencode 'browserAcceptLanguage=en_US' \
--data-urlencode 'email=xxxxx@example.com' \
--data-urlencode 'country=FRA' \
--data-urlencode 'merchantTransactionId=1234567890123456789'
--data-urlencode 'applePayToken=xxxxxxxxxxxxxxxxxxxxxxxx'

3. Google Pay (Smart Form)

Google Pay est nativement au parcours de paiement carte du SmartForm (PaymentRequest > paymentMethod[]=TRANSACTION), dès que l’appareil ou le navigateur de votre client est compatible.

Aucune action ne sera nécessaire de votre part. Le service sera entièrement opéré par CentralPay (détection de compatibilité Google Pay, gestion des certificats et des tokens, sécurité PCI-DSS). Aucune donnée de carte ne transite côté marchand, le flux relève du périmètre PCI-DSS SAQ-A.

4. Google Pay (Custom Form)

CentralPay permet l’intégration de Google Pay via le mode PAYMENT_GATEWAY, tel qu’imposé par Google Pay dans un contexte PSP multi-marchands, sans nécessiter de déchiffrement du token côté serveur.

Prérequis

1. Créer un compte Google Pay Business :

  • Accédez au Google Pay Business Console
  • Créez un Merchant Profile ou connectez-en un existant.
  • Renseignez vos coordonnées de société et d’activité.

2. Enregistrer votre domaine :

  • Dans la console Google Pay, allez dans l’onglet « Domains »
  • Ajoutez votre domaine de production et de test (ex : example.com)
  • Google vous demandera d’y héberger un fichier de vérification pour valider votre propriété
⚠️ Google Pay fournit un merchantId spécifique au domaine validé.
Ce merchantId est obligatoire pour toute Payment Request Google Pay.
L’utilisation d’un merchantId non associé au domaine entraîne une erreur Google Pay (Error 11).

3. Réaliser votre intégration frontend Google Pay :

  • Implémentez Google Pay côté frontend via Google Pay JS (pour les sites web) ou Google Pay API Android (pour les applications mobiles)
  • Collectez le token Google Pay (tokenizationData.token) après validation du paiement par l’utilisateur (code PIN, empreinte digitale, reconnaissance faciale…).
ℹ️ Google propose un tutoriel officiel pour cette intégration : Google Pay API | Google for Developers

4. Récupérez vos identifiants CentralPay :

  • MerchantPublicKey : Connectez-vous à votre portail CentralPay Back Office → Administration → Technique → Merchant Public Key
  • Login API : Connectez-vous à votre portail CentralPay Back Office → Administration → Technique → Identifiant API et copiez l’identifiant
  • Pass API : Connectez-vous à votre portail CentralPay Back Office → Administration → Technique → Cliquez sur votre Identifiant API → Modifier → Générer , copiez votre pass API et mettez à jour

Étape 1: Configuration de Google Pay côté frontend

ℹ️ Le bouton Google Pay est fourni par le SDK officiel Google Pay.
L’initiation du paiement et la génération du token sont entièrement contrôlées par Google Pay (hosted button).

1. Définir la version de l’API :

const baseRequest = {
  apiVersion: 2,
  apiVersionMinor: 0
};

2. Utiliser CentralPay comme passerelle de paiement :

Configurez la tokenisation comme suit :

const tokenizationSpecification = {
  type: 'PAYMENT_GATEWAY',
  parameters: {
    gateway: 'centralpay',
    gatewayMerchantId: 'YOUR_GATEWAY_MERCHANT_ID'
  }
};

Remplacez YOUR_GATEWAY_MERCHANT_ID par votre MerchantPublicKey fourni par CentralPay.

3.Définir les types de cartes acceptées : 

const allowedCardNetworks = ["AMEX", "MASTERCARD", "VISA"];

4. Définir le type de moyen de paiement :

Il existe deux type différents : PAN_ONLY et CRYPTOGRAM_3DS

⚠️​Le type PAN_ONLY permet de tokeniser le PAN d’un carte bancaire, cependant ce token n’est pas sécurisé pour effectuer un paiement, il est donc important de ne pas l’utiliser pour effectuer des paiements sur la plateforme Centralpay

const allowedCardAuthMethods = ["CRYPTOGRAM_3DS"];

5. Environnement de test ou production :

// Environnement de test
const paymentsClient = new google.payments.api.PaymentsClient({ environment: 'TEST' });

// Environnement de production
const paymentsClient = new google.payments.api.PaymentsClient({ environment: 'PRODUCTION' });

Étape 2 : Récupération du token Google Pay

Lorsqu’un utilisateur final valide un paiement via Google Pay, l’API retourne un token au format JSON dans :

paymentData.paymentMethodData.tokenizationData.token

Ce champ contient une chaîne JSON représentant un objet du type :

{
  "signature": "MEYCIQDn...",
  "protocolVersion": "ECv2",
  "intermediateSigningKey": {
    "signedKey": "{...}",
    "signatures": ["MEUCID..."]
  },
  "signedMessage": "{...}"
}

Ce bloc devra être transmis tel quel à l’API CentralPay lors de la création du cardToken dans le champ googlePayToken.

Étape 3 : Envoi du token à CentralPay (création du cardToken)

Faites un appel à l’endpoint POST /cardToken de CentralPay avec les paramètres suivants :

Paramètres requis :

ChampDescription
amountMontant en centimes (ex : 2500 pour 25,00 €)
currencyCode ISO alpha (ex : EUR, USD, etc.)
googlePayTokenLe JSON complet retourné par Google Pay (tokenizationData.token)
merchantPublicKeyClé publique CentralPay disponible dans le backoffice

Exemple de requête (format x-www-form-urlencoded) :

amount=2500
currency=EUR
merchantPublicKey=abcdef123456...
googlePayToken={"signature":"MEYCIQDn...","protocolVersion":"ECv2",...}

Ne déchiffrez pas le token vous-même : CentralPay s’occupe de sa validation côté serveur.

Étape 4 : Création de la transaction

Une fois que le cardToken est obtenu, vous pouvez déclencher une transaction de manière standard via l’endpoint POST /transaction.

Exemple de paramètres :

cardToken=...
amount=2500
currency=EUR
pointOfSaleId=...
endUserIp=...
merchantTransactionId=...

Le cardToken contient déjà toutes les informations d’authentification : pas besoin d’ajouter de cryptogramme ou de champ CVV.

Étape 5 : Testing avant mise en production

L’environnement de test CentralPay permet de valider l’ensemble de votre intégration Google Pay sans déclencher de véritables paiements. Il est fortement recommandé d’utiliser cet environnement pour toutes les phases de développement, de debug et de validation côté frontend comme backend.

Portail de test
API de test
Cartes de test

Différences entre environnement de test et de production :

Transaction carte via wallet - PreviousTransaction carte récurrenteNext - Transaction carte via walletR-transaction carte
CONTENU