Card transaction via wallet

1. Apple Pay (Smart Form)

Apple Pay is natively integrated into the SmartForm card payment flow (PaymentRequest > paymentMethod[]=TRANSACTION) as long as your customer’s device is compatible.

No action is required on your part. The service is fully managed by CentralPay (device detection, management of Apple certificates and tokens, PCI-DSS security). No card data is exposed on the merchant side (PCI-DSS SAQ-A scope).

2. Apple Pay (Custom Form)

2.1. Requirements

1. Create an Apple Developer account:

• Sign up for the Apple Developer Program
• Create your Apple Pay merchant credentials (Merchant ID)
• Generate your Apple Pay processing certificate through the Apple portal
• Register your domain (Apple Pay Merchant Domain)

2. Device-side integration:

• Implement Apple Pay on the front end using Apple Pay JS (for websites) or PassKit (for iOS apps)
• Retrieve the Apple Pay token (ApplePayToken) after the user has confirmed the payment (Face ID, Touch ID, etc.)

🔐 Certificates required for Apple Pay integration 
(https://developer.apple.com/help/account/certificates/create-a-certificate-signing-request)

To process Apple Pay payments through a direct integration, the merchant must have the following:
• a Merchant ID Identity certificate;
• a Merchant Payment Processing G2 certificate.

The merchant must ensure that all private keys used to generate the CSRs associated with these certificates are retained.

1. Merchant ID Identity
A CSR based on an EC key (256 bits) must be generated.
This CSR will be generated by Centralpay

2. Merchant Payment Processing Certificate

Main steps:
• Request the CSR generated by Centralpay
• Submit the CSR through the Apple Developer Account to obtain the Merchant Payment Processing Certificate.
• Install the certificate on the same macOS computer used to generate the CSR so that it is associated with the private key.
• Export the complete identity in .p12 format (certificate + private key).

⚠️ If the option to export in .p12 format is not available, this indicates that a step in the process was not completed correctly (private key is missing or not associated).

The .p12 file is a secure container that allows the private key associated with the certificate to be used later, in accordance with the Apple Pay workflow.

Important notes:
• If you lose your private key, you must completely recreate the certificate through the Apple Developer portal.
• The Apple Pay documentation can be confusing: the use of OpenSSL applies only to the Merchant ID Identity certificate and does not apply to the Merchant Payment Processing Certificate.

2.2. Via a decrypted Apple Pay token

CentralPay enables the processing of card payments made via Apple Pay as part of a custom integration (excluding Smart Form).

ℹ️ CentralPay currently supports only decrypted Apple Pay tokens. This method entails significant PCI-DSS liability on your part (SAQ-D form). Please research this and ensure you are in compliance before developing this integration method.  

Step 1: Decrypting the Apple Pay token (Backend)

The Apple Pay token must be decrypted on your backend using:

• Your Apple Pay treatment certificate
• Your private key
• Apple Documentation: Payment Token Format

The result will contain:

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

Step 2: Creating the CentralPay cardToken (Backend)

Use the /cardToken POST endpoint of the CentralPay API

Field	Description
card[number]	PAN of the card extracted from the Apple Pay token
card[expirationMonth]	Card expiration month (MM format)
card[expirationYear]	Card expiration year (YYYY format)
onlinePaymentCryptogram	Cryptogram derived from the Apple Pay token (CAVV)
eciIndicator	Authentication Index Derived from the Apple Pay Token (ECI)
applePayTransactionId	Apple Pay Transaction ID
amount	Amount in cents (e.g., 2,500 = €25.00)
currency	ISO alpha code (e.g., EUR, USD, etc.)
merchantPublicKey	Public key provided by CentralPay

ℹ️ Where can I find the merchantPublicKey?
        
            Log in to your CentralPay Back Office portal  Administration  Technical  Merchant Public Key        
        

Example:

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

The generated cardToken contains all the data needed for Apple Pay authentication.

Step 3: Creating the CentralPay Transaction (Backend)

Use the /transaction POST endpoint of the CentralPay API

Required fields:

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

The cardToken already encapsulates the Apple Pay context and authentication data.

Step 4: Testing before deployment

The CentralPay test environment allows you to validate your entire Apple Pay integration without triggering actual payments. We strongly recommend using this environment for all phases of development, debugging, and validation, both on the front end and the back end.

Differences between the test and production environments:

• The API URLs are different: They use the “test-” prefix
  • Test: https://test-api.centralpay.net/v2/rest/transaction
  • Deployment: https://api.centralpay.net/v2/rest/transaction
• The API credentials (login and secret) are specific to the test environment. They are not interchangeable with those used in production.
• The CentralPay public key (merchantPublicKey) is also environment-specific

2.3. Via an encrypted Apple Pay token (hybrid)

ℹ️ If you are interested in this integration method, please contact CentralPay support to learn about the associated deliverables and access procedures.

2.3.1. Apple account settings

– Log in on “https://developer.apple.com/“, create an account, and verify your “developer” account for $99)

– Go to https://developer.apple.com/account/resources/identifiers/list

– Under “App IDs”, select “Merchant IDs“:

Then click the “+” to add an “Identifier“:

Select “Merchant IDs“:

Enter your username and click”Register”:

Go to https://developer.apple.com/account/resources, then click Identifiers

On the “Identify” page, select a Merchant ID using the filter in the upper-right corner

Under “Apple Pay Payment Processing Certificate”, click “Create Certificate“.

Please note that this “Merchant ID” will NOT be used exclusively for China.

At that point, click “Choose File” to upload the CSR file that was sent to you by CentralPay (CentralPay only).

You can download the generated file.
Next, you need to create the “Apple Pay Merchant Identity Certificate.”
To do this, go to https://developer.apple.com/account/resources, then click Identifiers and finally click the identifier you want to edit.
Once it’s open, click “Create Certificate”.

Upload your certificate:

Add the associated domain

Enter the domain name in question:

Download the file specified by Apple

Deploy the file specified by Apple to a server on the domain in question that is accessible to Apple, then click “Verify”:

You will then be able to download the required certificate.

2.3.2. Payment via Apple Pay

Generating the certificate and key in the same file:

openssl pkcs12 -in certificat.p12 -out certificat.pem -clcerts

Creating an ApplePayToken with the Apple Pay JS API (Demo at https://applepaydemo.apple.com/apple-pay-js-api)

Front end:

<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/transaction`, {
 method: "post",
 body: JSON.stringify(
  {  
 applePayToken: token,
 endUserIp: "127.0.0.1",
 currency: "EUR",
 amount: 1000,
 source="EC",
 browserUserAgent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.41 Safari/537.36",
 merchantTransactionId="1234567890123456789"
  }),
  })
 .then((response) =>  {
 if (response.ok) {
 return response.json();
  }
 appleSession.completePayment(ApplePaySession.STATUS_FAILURE);
  })
 .then((responseJson) =>  {
 // Do something with the response
 appleSession.completePayment(ApplePaySession.STATUS_SUCCESS);
  })
 .catch((error) =>  {
 appleSession.completePayment(ApplePaySession.STATUS_FAILURE);
 });
};

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($ch, CURLOPT_SSLCERT, getcwd() . 'certificat.pem'); 
 $curl->setOpt($ch, CURLOPT_SSLCERTPASSWD, "thesslpassword");
 $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());
...
});

Creating a CardToken with your encrypted Apple Pay token. (Frontend)

When making your API call, in addition to the required fields, you must include the “applePayToken” field in JSON format, containing your Apple Pay token, which includes the elements paymentData,paymentMethod, and transactionIdentifier.
You can then complete a transaction using your cardToken as usual.

Use the CentralPay API’s POST /cardToken endpoint
Required fields:

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'

Creating the transaction: (Backend)

Use the /transaction POST endpoint of the CentralPay API
Required fields:

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'

The cardToken already encapsulates the Apple Pay context and authentication data.

Create a transaction using your encrypted Apple Pay token. (Backend)

When making your API call, in addition to the required fields, you must include the “applePayToken” field in JSON format, containing your Apple Pay token, which includes the elements paymentData, paymentMethod and transactionIdentifier.

Then use the /transaction POST endpoint of the CentralPay API

Required fields:

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 is natively integrated into the SmartForm card payment flow (PaymentRequest > paymentMethod[]=TRANSACTION), provided your customer’s device or browser is compatible.

No action is required on your part. The service will be fully managed by CentralPay (Google Pay compatibility detection, certificate and token management, PCI-DSS security). No card data passes through the merchant’s system; the payment flow falls within the scope of PCI-DSS SAQ-A.

4. Google Pay (Custom Form)

CentralPay enables the integration of Google Pay via the PAYMENT_GATEWAY mode, as required by Google Pay in a multi-merchant PSP environment, without requiring server-side decryption of the token.

Requirements

1. Create a Google Pay Business account:

• Access the Google Pay Business Console
• Create a Merchant Profile or link an existing one.
• Please enter your company and business information.

2. Register your domain:

• In the Google Pay console, go to the “Domains” tab
• Add your production and test domains (e.g., example.com)
• Google will ask you to upload a verification file there to confirm your ownership

⚠️ Google Pay provides a domain-specific merchantId.
This merchantId is required for all Google Pay Payment Requests.
Using a merchantId that is not associated with the domain results in a Google Pay error (Error 11).

3. Implement your Google Pay front-end integration:

• Implement Google Pay on the front end using Google Pay JS (for websites) or Google Pay Android API (for mobile apps)
• Collect the Google Pay token (tokenizationData.token) after the user has authorized the payment (PIN, fingerprint, facial recognition, etc.).

ℹ️ Google offers an official tutorial for this integration: Google Pay API | Google for Developers

4. Retrieve your CentralPay login credentials:

• MerchantPublicKey: Log in to your CentralPay Back Office portal → Administration → Technical → Merchant Public Key
• API Login: Log in to your CentralPay Back Office portal → Administration → Technical → API ID and copy the ID
• API Pass: Log in to your CentralPay Back Office portal → Administration → Technical → Click on your API ID → Edit → Generate, copy your API pass, and update it

Step 1: Configuring Google Pay on the front end

ℹ️ The Google Pay button is provided by the official Google Pay SDK.
Payment initiation and token generation are entirely controlled by Google Pay (hosted button).

1. Specify the API version:

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

2. Use CentralPay as a payment gateway:

Configure tokenization as follows:

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

Replace YOUR_GATEWAY_MERCHANT_ID with your MerchantPublicKey provided by CentralPay.

3. Specify the types of cards accepted:

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

4. Select the payment method:

There are two different types: PAN_ONLY and CRYPTOGRAM_3DS

⚠️​CentralPay does not allow the use of the PAN_ONLY type because it requires compliance with specific security standards. Only the CRYPTOGRAM_3DS type is allowed.

const allowedCardAuthMethods = ["CRYPTOGRAM_3DS"];

5. Test or production environment:

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

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

Step 2: Retrieving the Google Pay token

When an end user authorizes a payment via Google Pay, the API returns a token in JSON format in:

paymentData.paymentMethodData.tokenizationData.token

This field contains a JSON string representing an object of the following type:

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

This block must be sent as-is to the CentralPay API when creating the cardToken in the googlePayToken field.

Step 3: Sending the token to CentralPay (creating the cardToken)

Make a POST request to CentralPay’s /cardToken endpoint with the following parameters:

Required parameters:

Field	Description
amount	Amount in centimes (e.g., 2,500 for €25.00)
currency	ISO alpha code (e.g., EUR, USD, etc.)
googlePayToken	The complete JSON returned by Google Pay (tokenizationData.token)
merchantPublicKey	CentralPay public key available in the back office

Example request (x-www-form-urlencoded format):

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

Do not decrypt the token yourself: CentralPay handles its validation on the server side.

Step 4: Creating the transaction

Once you have obtained the cardToken, you can initiate a transaction in the standard way via endpoint POST /transaction.

Example settings:

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

The cardToken already contains all the authentication information: there is no need to add a cryptogram or a CVV field.

Step 5: Testing before deployment

The CentralPay test environment allows you to validate your entire Google Pay integration without triggering actual payments. We strongly recommend using this environment for all phases of development, debugging, and validation, both on the front end and the back end.

Differences between the test and production environments:

• The API URLs are different: they use the “test-” prefix
  • Test: https://test-api.centralpay.net/v2/rest/transaction
  • Deployment: https://api.centralpay.net/v2/rest/transaction
• The API credentials (login + secret) are specific to the test environment.
  They are not interchangeable with those used in production.
• The CentralPay public key (merchantPublicKey) is also environment-specific