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.


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 :

  • Paiement : Un paiement est un processus de paiement constitué de plusieurs actions. Chaque action correspond à une étape du paiement (ex : authentification, autorisation, capture).
  • Action : Une action est une étape spécifique du processus de paiement, identifiée par un xId.


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



Best Practice:

  • Le transId doit être utiliser pour lier le paiement avec votre system d'information.
    • Si vous n'avez pas de contrainte particulière sur cette donnée, il est conseillé d'utiliser un uuid-v4 pour garantir son unicité.
  • Le refNr est renseigné par Axepta BNP Paribas Online afin de garantir une valeur garantie unique
    • Si vous le souhaitez, vous pouvez envoyer cette donnée mais vous devez respecter le format et garantir son unicité.



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.


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



  • Ces 2 données sont affichées sur la page de paiement.
  • Au moins une de ces données est nécessaire si vous voulez activer le contrôle des doublons.
  • Elles doivent tous les deux respecter le format ANS30: 30 charactères, alphanumérique ou spéciaux.



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


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