Cloud API

The Cloud API is secured by mutual TLS (mTLS). Your POS presents a client certificate on

every request. There is no login, session, API key, token, or username/password. You obtain

the certificate once, during onboarding.

The full onboarding guide is available in the Help Center:

Authentication — mTLS certificates

How you get a certificate

1. You generate a Certificate Signing Request (CSR) and a private key, and send the.csr to your Market Pay implementation manager.
2. The Market Pay AppOps team issues the certificate and returns it to you.
3. You install the certificate on your system.

Warning
Send only the .csr file. Never send the private key (.key) — keep it securely stored on
your side. Market Pay never needs it, and no one should ever ask you for it.

Generate the CSR and private key

Use OpenSSL. For pre-production:

openssl req -nodes -newkey rsa:2048 \
  -keyout POS_MerchantName_PREPROD_PRIVATEKEY.key \
  -out    POS_MerchantName_PREPROD_CSR.csr

For production:

openssl req -nodes -newkey rsa:2048 \
  -keyout POS_MerchantName_PROD_PRIVATEKEY.key \
  -out    POS_MerchantName_PROD_CSR.csr

Replace MerchantName with your merchant identifier. Use a separate certificate per

environment — never reuse a pre-production certificate in production.

Fields to provide

When OpenSSL prompts, fill in:

Warning
The Organizational Unit (OU) must clearly indicate the certificate usage — this field is
mandatory. Other fields can be left empty.

For scripting or CI, the same result without the interactive prompts:

openssl req -nodes -newkey rsa:2048 \
  -keyout POS_MerchantName_PREPROD_PRIVATEKEY.key \
  -out    POS_MerchantName_PREPROD_CSR.csr \
  -subj "/C=FR/O=MyShop SAS/OU=POS Cloud/CN=myshop.com"

Note
For testing only, a CSR can be generated with an online tool. This is not recommended for
production, because the private key is generated outside your control.

What to send to Market Pay

Send the .csr file together with the context needed to scope the certificate:

• the environment (pre-production or production);
• the storeCode(s) the certificate should be provisioned for;
• your ecrId and terminal serial(s), if already known.

Being signed by the Market Pay CA is necessary but not sufficient: the certificate must also be

provisioned for your storeCode. A correctly signed certificate used against a store it is

not registered for will still be refused.

What you receive

Two things that commonly surprise integrators:

• The issued certificate's subject may differ from what you put in the CSR. Market Pay appliesits own naming convention. This is expected — what matters is that the certificate is signed bythe Market Pay CA and matches your private key.
• Check the validity dates on receipt and plan renewal ahead of expiry. An expired certificatefails exactly like a missing one: a connection reset with no HTTP status.

Verify before you install

Three checks that prevent most onboarding problems.

1. The certificate matches your private key. The two hashes must be identical:

openssl x509 -in POS_MerchantName_PREPROD.crt -noout -pubkey | openssl sha256
openssl pkey -in POS_MerchantName_PREPROD_PRIVATEKEY.key -pubout | openssl sha256

If they differ, the certificate was issued from a different CSR — request a re-issue. A

certificate cannot be used without its matching private key.

2. Subject, issuer and validity:

openssl x509 -in POS_MerchantName_PREPROD.crt -noout -subject -issuer -dates

3. It chains to the Market Pay CA:

openssl verify -CAfile MarketPay_Root_CA POS_MerchantName_PREPROD.crt

Configure your client

The certificate and key are presented during the TLS handshake, from your server. A browser or

mobile client must never hold the private key.

curl

curl --cert POS_MerchantName_PREPROD.crt \
     --key  POS_MerchantName_PREPROD_PRIVATEKEY.key \
     -H "User-Agent: MyPOS/1.0" \
     "https://eci-stg.market-pay.com/terminals?storeCode=YOUR_STORE"

Postman — requires Postman Desktop; the web version does not support client certificates.

Go to Settings → Certificates → Add Certificate, then set Host eci-stg.market-pay.com,

Port 443, your CRT file and KEY file, no passphrase.

Node.js

const https = require('https');
const fs = require('fs');

const agent = new https.Agent({
  cert: fs.readFileSync('POS_MerchantName_PREPROD.crt'),
  key:  fs.readFileSync('POS_MerchantName_PREPROD_PRIVATEKEY.key'),
  rejectUnauthorized: true          // keep server-certificate validation enabled
});

// Node does not send a User-Agent by default - set one explicitly.
https.request(url, { agent, headers: { 'User-Agent': 'MyPOS/1.0' } }, callback);

Deployment: never commit the key to source control. Inject it as a platform secret (for

example an environment variable holding the base64-encoded PEM) and load it at startup.

The User-Agent header

Independently of mTLS, every request must send a non-empty User-Agent header. Any value is

accepted, for example MyPOS/1.0.

Warning
A request sent without a User-Agent is rejected with an empty-body HTTP 400, which
looks like a malformed request rather than an authentication problem. Most HTTP clients set the
header automatically, but some do not — notably Node.js's native https module. If you are
seeing unexplained empty 400 responses, check this first.

Troubleshooting: read the failure shape

The shape of the failure tells you which layer rejected the request. This is the fastest way to

diagnose an integration problem.

Confirm mTLS works in a single command. Any HTTP code printed means the handshake succeeded:

curl -sS -o /dev/null -w "HTTP %{http_code}\n" \
     --cert POS_MerchantName_PREPROD.crt \
     --key  POS_MerchantName_PREPROD_PRIVATEKEY.key \
     -H "User-Agent: MyPOS/1.0" \
     "https://eci-stg.market-pay.com/terminals?storeCode=YOUR_STORE"

Note
On Windows, curl may report 000 (connection failure) even with a valid certificate, because
of differences in the TLS backend it was built against. If that happens, cross-check with
Postman Desktop or the Node.js snippet above before concluding the certificate is at fault.

Security requirements

• Never transmit the private key — not to Market Pay, not by email, not in a support ticket.Only the .csr and the issued .crt are ever shared.
• Never commit the key to source control, and never expose it to a browser or mobile client.All API calls must be made from your server.
• One certificate per environment. Pre-production certificates do not work in production.
• Restrict file permissions on the key and store it in a secrets manager where possible.
• Track expiry and renew ahead of time.