This documentation provides best practices for using certain fields, to ensure the uniqueness and consistency of identifiers throughout the payment process. It also offers technical implementation advice.


Cette section de la documentation en ligne explique comment identifier et gérer les paiements au sein de la plateforme 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.

This section of the online documentation explains how to identify and manage payments within the Axepta BNP Paribas Online 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: A payment is a payment process consisting of several actions. Each action corresponds to a step in the payment process (e.g., authentication, authorization, capture, credit).
  • Action: An action is a specific step in the payment process, identified by an xId.


Payment Identification

Merchant Side

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é.

There are 2 fields on the merchant side used to identify the payment:

  • transId: Transaction Identifier
  • refNr: Reference Number

The transId (transaction 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 data.


Best Practice:

  • The transId should be used to link the payment with your information system.
    • If you don't have specific constraints on this data, it is recommended to use a uuid-v4 to ensure its uniqueness.

  • The refNr is provided by Axepta BNP Paribas Online to ensure a guaranteed unique value.

    • If you wish, you can send this data but you must respect the format and ensure its uniqueness.



Axepta BNP Paribas Online Side

There are 2 parameters:

  • payId: Payment identifier generated by Axepta BNP Paribas Online
  • xId: Action identifier

The payId (Payment Id) is used to identify the payment on Axepta BNP Paribas Online:

  • This data is generated by Axepta BNP Paribas Online and is guaranteed to be unique.
  • It remains constant throughout the transaction lifecycle (authorization, capture, credit, cancellation...)
  • It is returned via feedback URLs (return, cancel, and webhook).
  • 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: GET /payments/getByPayId/ or GET /payments/getByTransId/)

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.


"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"
          }
        }
      ]
    },



  • These 2 data points are displayed on the payment page.
  • At least one of these data points is required if you want to enable duplication check.
  • Both must comply with the ANS30 format: 30 alphanumeric or special characters.



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


"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

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 GET /payments ) 

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  GET /payments/getByTransId/<id> )


Ces données sont transportées 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 / 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).



"metadata": {
    "userData": "my user data",
    "plain": "some plain text",
    "key1": "value1",
    "key2": "value2"
  }



Conseils d'implémentation


Idempotence

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 '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


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.