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.
| Note |
|---|
Cette section de la documentation en ligne explique comment identifier et gérer les paiements au sein de la plateforme Axepta 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 :
|
Identification du paiement
Côté Commerçant
Il existe 2 champs coté marchant, servant à identifier le paiement:
- transId : Transaction Identifiant
- refNr: Reference Number
Le 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.
Axepta BNP Paribas Online valorisera cette donnée en garantissant son unicité.
| Info |
|---|
Best Practice:
|
Côté Axepta Online
Il existe 2 paramètres:
- payId: identifiant du paiement généré par Axepta BNP Paribas Online
- xId: Identifiant d'une action
Le champ payId (Payment Id) est utilisé pour identifier le paiement sur Axepta BNP Paribas Online:
- Cette donnée est générée par Axepta BNP Paribas Online et est garantie unique.
- Il reste constant tout au long du cycle de vie de la transaction (autorisation, capture, crédit, annulation...)
- Elle est retournée via les url de feedback (return, cancel et 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'utilisé cette donnée pour récupérer le statut de la transaction. (cf <lien getByXXX> )
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
L'identification du paiement est portée par l'objet 'order' et 2 de ses champs sont important 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
Les données relatives au client sont transportées dans l'objet 'customerInfo' et les 2 champs suivant sont particulièrement important:
- 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 marchant
Il est possible de transmettre des données métier non liées au paiement lors des requêtes initiant un paiement.
(requêtes POST /payments/sessions ou POST /payments)
Ces données seront retournées lors de la réponse, et lors des GET sur le statut de la transaction.
Ces données sont transportée dans l'objet 'metadata' et doivent respecter les contraintes suivantes:
- Doit respecter le format JSON.
Le champs metadata doit être un object JSON valide, sinon, l'ensemble de la requête de paiement sera refusée. - Ne doit contenir que des paires "cle":"valeur" de type string
Pas d'entier, pas de sous objet... - Ne doit pas comporter de données propre au paiement.
Ce champ n'est pas protégé au sens des règlementations pci / gdpr.
Il est de la responsabilité du marchant de ne pas mettre de données sensible 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ée par les champs dédiée de la requête).
| Code Block | ||||
|---|---|---|---|---|
| ||||
"metadata": {
"userData": "my user data",
"plain": "some plain text",
"key1": "value1",
"key2": "value2"
} |