Cette documentation fournit des bonnes pratiques pour l'utilisation de certains champs, afin de garantir l'unicité et la cohérence des identifiants tout au long du processus de paiement.
Elle propose aussi des conseils techniques d'implémentationThis documentation provides best practices for using some fields, to ensure the uniqueness and consistency of identifiers throughout the payment process. It also offers technical implementation advice.
| Table of Contents |
|---|
| Note |
|---|
Cette section de la documentation en ligne explique comment identifier et gérer les paiements au sein de la plateforme This section of the online documentation explains how to identify and manage payments within the Axepta BNP Paribas Online . Elle détaille les différents champs utilisés pour identifier un paiement, tant du côté du commerçant que du côté de la plateforme de paiement. Définitions : platform. It details the various fields used to identify a payment, both from the merchant's perspective and from the payment platform's perspective. Definitions:
|
Payment Identification
du paiementCôté Commerçant
Merchant Side
There are 2 fields on the merchant side used to identify the paymentIl existe 2 champs coté marchant, servant à identifier le paiement:
- transId: Transaction Identifiant
- Identifier
- refNr: Reference Number
Le The transId (identifiant de transaction ) est propre au system d'information du commerçant. Il doit être unique, et respecter le format 'ans64': 64 charactères alphanumériques et spéciaux
Il n'est échangé qu’entre le commerçant et la plateforme de paiement.
Le refNr (Reference Number) sert à identifier le paiement durant tout son cycle de paiement, jusqu’à l'acquéreur.
Le format de ce champ dépend du moyen de paiement utilisé, et pour assurer son traitement tout au long de la chaine, il doit respecter le format : 'an12' : 12 charactères alphanumériques, pas de caractères spéciaux.
identifier) is specific to the merchant's information system. It must be unique and comply with the 'ans64' format: 64 alphanumeric and special characters. It is only exchanged between the merchant and the payment platform.
The refNr (Reference Number) is used to identify the payment throughout its entire payment cycle, up to the acquirer.
The format of this field depends on the payment method used, and to ensure its processing throughout the chain, it must comply with the 'an12' format: 12 alphanumeric characters, no special characters.
Axepta BNP Paribas Online will ensure the uniqueness of this dataAxepta BNP Paribas Online valorisera cette donnée en garantissant son unicité.
| Info |
|---|
Best Practice:
|
Côté Axepta BNP Paribas Online
|
Axepta BNP Paribas Online Side
There are 2 parameters:
- payId: Payment identifier generated by
Il existe 2 paramètres:
- payId: identifiant du paiement généré par
- Axepta BNP Paribas Online
- xId: Identifiant d'une action
- Action identifier
The Le champ payId (Payment Id) est utilisé pour identifier le paiement sur is used to identify the payment on Axepta BNP Paribas Online:
- Cette donnée est générée par
- This data is generated by Axepta BNP Paribas Online et est garantie
- and is guaranteed to be unique. Il reste constant tout au long du cycle de vie de la transaction (autorisation
- It remains constant throughout the transaction lifecycle (authorization, capture, crédit
- credit, annulation
- cancellation...) Elle est retournée via les url de feedback
- It is returned via feedback URLs (return, cancel et
- , and webhook).
- Le PayId est requis pour toute opération complémentaire sur la transaction, comme par exemple la capture manuelle ou l'annulation. Il est aussi fortement conseillé d'utiliser cette donnée pour récupérer le statut de la transaction. (
- The PayId is required for any additional operation on the transaction, such as manual capture or cancellation.
- It is also highly recommended to use this data to retrieve the transaction status. (see requests: cf. requêtes:
- GET /payments/getByPayId/ <id> ou
- or GET /payments/getByTransId/ <id>
- )
Le champ xId identifie lui l'action ou l'opération effectuée sur le paiement, qui va amener à un changement d'état de cette dernière.
- Un même paiement peut avoir plusieurs actions / opérations, et donc, plusieurs xId.
- Cette données est générée par Axepta BNP Paribas Online et est garantie unique.
Données métier du marchand
Identifiant de la commande et de la facture
The xId identifies the action or operation performed on the payment, which will result in a change of state.
- A single payment can have multiple actions/operations, and therefore multiple xIds.
- This data is generated by Axepta BNP Paribas Online and is guaranteed to be unique.
Merchant Business Data
Order and Invoice Identifier
Payment identification is carried by the 'order' object, with two key fields for transaction processing:
order.merchantReference: This data should be used to identify the order, as defined by the merchant.
order.invoiceId: The invoice identifier associated with this payment, it is defined by the merchant
L'identification du paiement est portée par l'objet 'order' et 2 de ses champs sont importants pour le traitement de la transaction :
- order.merchantReference: cette donnée doit être utilisé pour identifier la commande, elle est définie par le commerçant. order.invoiceId: l'identifiant de la facture associé à ce paiement, elle est définie par le commerçant
.
| Code Block | ||||
|---|---|---|---|---|
| ||||
"order": {
"merchantReference": "112-445-34567",
"numberOfArticles": 1,
"creationDate": "2025-03-31T11:58:37Z",
"invoiceId": "555-333-2222",
"items": [
{
"id": "1",
"sku": "19-402-DEU",
"name": "BatteryPowerPack",
"quantity": 1,
"quantityUnit": "pcs",
"taxRate": 0,
"netPrice": 1000,
"grossPrice": 1000,
"taxAmount": 0,
"discountAmount": 0,
"description": "BatteryPowerPack",
"type": "physical",
"productInfo": {
"brand": "Intel",
"categories": [
"Electronics Store",
"Computers",
"Desktops"
],
"globalTradeItemNumber": "EAN",
"manufacturerPartNumber": "BOXNUC5CPYA",
"imageUrl": "https://www.exampleobjects.com/logo.png",
"productUrl": "https://www.estore.com/products/f2a8d7e34"
}
}
]
}, |
| Info |
|---|
|
Identifiant du client
|
Customer Identifier
Customer-related data is carried in the 'customerInfo' object and the following two fields are particularly important:
email: Essential for transaction processing (sending payment confirmation email, Visa regulations, transaction searches)
merchantCustomerId: Required for the Wallet/Customer Vault feature
Les données relatives au client sont transportées dans l'objet 'customerInfo' et les 2 champs suivants sont particulièrement importants:
- email: indispensable au traitement de la transaction (envoi du mail de confirmation de paiement, réglementation Visa, recherche de transactions) merchantCustomerId: nécessaire pour la fonctionnalité Wallet / Customer Vault
| Code Block | ||||
|---|---|---|---|---|
| ||||
"customerInfo": {
"merchantCustomerId": "cus_1234567890abcdef",
"customerType": "individual",
"firstName": "Max",
"lastName": "Mustermann",
"email": "customer@example.com",
"phone": {
"countryCode": "+49",
"number": "1236547890"
},
"salutation": "Ms",
"title": "Dr",
"gender": "female",
"maidenName": "Mustermann",
"middleName": "sam",
"birthDate": "2001-01-01",
"birthPlace": "Bamberg",
"socialSecurityNumber": "123443534"
}, |
Données propriétaire du marchant
| Info |
|---|
Velocity checks related to the email address
|
Merchant-Specific Data
It is possible to transmit non-payment business data during payment initiation requests (Il est possible de transmettre des données métier non liées au paiement lors des requêtes initiant le paiement.
(requêtes POST /payments/sessions ou or GET /payments requests)
.
These data will be returned in the payment request response and in transaction information requests (Ces données seront retournées lors de la réponse à la requête de paiement, et lors des demande d'information sur la transaction.
(requêtes: GET /payments/getByPayId/ <id> ou or GET /payments/getByTransId/<id>)
Ces données sont transportées dans l'objet 'metadata' et doivent respecter les contraintes suivantes:
Le champs metadata doit être un object JSON valide, sinon, l'ensemble de la requête de paiement sera refusée.
Pas d'entier, pas de sous objet...
.
These data are carried in the 'metadata' object and must comply with the following constraints:
Must be in JSON format. The metadata field must be a valid JSON object, otherwise the entire payment request will be rejected.
Must contain only "key":"value" pairs of string type No integers, no sub-objects...
Must not contain payment-specific data.
This field is not protected under PCI/RGDP regulations.
It is the merchant's responsibility to avoid including sensitive data in this field, such as customer identification data (names, addresses...), or data related to the payment method used.
(Payment-required data must be carried in the dedicated fields of the request
Ne doit pas comporter de données propre au paiement.Ce champ n'est pas protégé au sens des règlementations pci / rgdp.
Il est de la responsabilité du marchant de ne pas mettre de données sensibles dans ce champs, comme des données d'identification du client (noms, adresse...), ou des données relatives au moyen de paiement utilisé.
(les données nécessaires au paiement doivent être portées par les champs dédiées de la requête
).
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
"metadata": {
"userData": "my user data",
"plain": "some plain text",
"key1": "value1",
"key2": "value2"
} |
Conseils d'implémentation
Idempotence
Implementation Recommendations
Idempotency
The Le serveur REST API v2 d' Axepta BNP Paribas Online est idempotent: il ne traite la même requête qu'une seule fois.
Si de multiples requêtes identiques sont reçues, la même réponse sera renvoyée sans générer une nouvelle opération coté serveur.
Cette fonctionnalité permet d'éviter les doublons en cas de répétition du message de paiement.Pour les messages POST et PATCH, l'idempotence est garantie par l'utilisation du header http REST API v2 is idempotent: it processes each request only once.
If multiple identical requests are received, the same response will be returned without generating a new server-side operation.
This feature prevents duplicates in case of repeated payment messages.
For POST and PATCH messages, idempotence is ensured by using the HTTP header 'Idempotency-Key'
.Sa valeur doit être unique par requête http émise vers le serveur, et il est de la responsabilité du client la générer.
Il est conseillé d'utiliser un uuid-v4 pour ce header http.
Authentification
Its value must be unique for each HTTP request sent to the server, and it is the client's responsibility to generate it.
It is recommended to use a uuid-v4 for this HTTP header.
Authentication
All requests to the Axepta BNP Paribas Online server must be authenticated.
Authentication must be performed using the OAuth-V2 protocol.
The access token returned by the Axepta BNP Paribas platform is valid for 1 hour.
After this period, you must re-authenticate to obtain a valid token.
The connection to the Axepta BNP Paribas REST API must use TLS 1.2 or higher
Toutes les requêtes au serveur Axepta BNP Paribas Online doivent être authentifiées.
L'authentification doit se faire en utilisant le protocole OAuth-V2.
Le token d'accès retourné par la plateforme Axepta BNP Paribas est valable 1 heure.
Passé ce délai, vous devez refaire une authentification pour avoir un token valide.
La connexion à l'API REST Axepta BNP Paribas doit être faite en TLS 1.2 minimum.