Page History

This 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 adviceDeze documentatie biedt best practices voor het gebruik van bepaalde velden, om de uniciteit en consistentie van identificators gedurende het hele betaalproces te waarborgen. Daarnaast bevat het technisch implementatieadvies.

Table of Contents

Note

This section of the online documentation explains how to identify and manage payments within the Deze sectie van de online documentatie legt uit hoe u betalingen kunt identificeren en beheren binnen het 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

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.

Info

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.

-platform. Hierin worden de verschillende velden beschreven die worden gebruikt om een betaling te identificeren, zowel vanuit het perspectief van de handelaar als vanuit dat van het betaalplatform.

Definities

Term	Beschrijving
Betaling	Een betaalproces dat uit meerdere acties bestaat. Elke actie komt overeen met een stap in het proces (bv. authenticatie, autorisatie, capture, terugbetaling).
Actie	Een specifieke stap in het betaalproces, geïdentificeerd door een xId (bv. autorisatie, annulering).

Identificatie van betalingen

Kant van de handelaar

Er zijn 2 velden die door de handelaar worden gebruikt om een betaling te identificeren:

Veld	Beschrijving	Formaat	Voorbeeld
`transId`	Transactie-identifier specifiek voor het systeem van de handelaar. Moet uniek zijn en voldoen aan het ‘ans64’-formaat (64 alfanumerieke en speciale tekens).	`ans64`	`TRANS_20231001_001!@#`
`refNr`	Referentienummer om de betaling gedurende de hele levenscyclus te identificeren (tot aan de acquirer). Moet voldoen aan het ‘an12’-formaat (12 alfanumerieke tekens, geen speciale tekens).	`an12`	`REF1234567890`

Info

💡 Best Practices:

transId:
- Gebruik dit veld om de betaling te koppelen aan uw interne systeem.
- Indien geen specifieke beperkingen: gebruik een UUID-v4 voor uniciteit.
refNr:
- Wordt automatisch gegenereerd door Axepta BNP Paribas Online om uniciteit te garanderen.
- U kunt uw eigen refNr opgeven, mits het formaat en de uniciteit gewaarborgd zijn.

Kant van Axepta BNP Paribas Online

Er zijn 2 parameters die door Axepta BNP Paribas worden gegenereerd:

Parameter Beschrijving Kenmerken

payId

Betaalidentifier gegenereerd door Axepta BNP Paribas Online.

- Uniek en constant gedurende de hele transactielevenscyclus (autorisatie, capture, etc.)

- Wordt geretourneerd via feedback-URLs (return, cancel, webhook).

- Vereist voor handmatige acties (bv. capture, annulering).

- Gebruik dit veld om de transactiestatus op te vragen (bv. GET /payments/getByPayId/).

xId

Actie-identifier voor een specifieke stap in het betaalproces.

- Elke actie (bv. autorisatie, annulering) heeft een eigen xId.

- Uniek en gegenereerd door Axepta BNP Paribas Online.

Bedrijfsgegevens van de handelaar

Order- en factuuridentificatie

Betalingen worden geïdentificeerd via het order-object, met twee sleutvelden:

Veld	Beschrijving	Formaat
`order.merchantReference`	Identificeert de order, gedefinieerd door de handelaar.	`ANS30`
`order.invoiceId`	Factuuridentifier gekoppeld aan de betaling, gedefinieerd door de handelaar.	`ANS30`

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.

Code Block

language	json
linenumbers	true

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

title	📌 Opmerkingen

Deze velden worden weergegeven op de betaalpagina.
Minstens één van deze velden is vereist om de dubbelcontrole-functie in te schakelen.
Formaat: ANS30 (30 alfanumerieke of speciale tekens).

Identificatie van de klant

Klantgerelateerde gegevens worden meegegeven in het customerInfo-object. Belangrijke velden:

Veld Beschrijving Formaat Voorbeeld

customerInfo.email

Essentieel voor transactieverwerking (bv. verzending bevestigingse-mail, Visa-reguleringen, zoekopdrachten).

Wordt gebruikt voor velocity checks (fraudebescherming).

E-mailformaat

klant@example.com

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)

Code Block

language	json
linenumbers	true

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

Velocity checks related to the email address
If you want the email address-related velocity checks rules to apply, you must enter the customer's email address in the customerInfo.email field.

In general, velocity checks can only be created and viewed by Axepta BNP Paribas Helpdesk.
To create, modify, or delete these controls, please contact Axepta Helpdesk.

Info

Merchant-Specific Data

⚠ Belangrijk:

Velocity checks (controles op verdachte activiteiten) kunnen alleen door de klantendienst van Axepta BNP Paribas worden ingesteld.
Neem contact op met de klantendienst van Axepta BNP Paribas Benelux om deze controles aan te maken, wijzigen of te verwijderen.

Handelaarspecifieke gegevens

U kunt niet-betaalgerelateerde bedrijfsgegevens meezenden in het metadata-veld tijdens het initiëren van een betaling It is possible to transmit non-payment business data during payment initiation requests (POST /payments/sessions or of GET /payments requests).

These data will be returned in the payment request response and in transaction information requests (GET /payments/getByPayId/ or GET /payments/getByTransId/).

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)

Vereisten voor metadata :

✅ Formaat: Moet een geldig JSON-object zijn (anders wordt het verzoek afgewezen).

✅ Inhoud: Alleenparen "sleutel":"waarde" van het type string (geen integers, geen sub-objecten).

✅ Geen gevoelige gegevens: Mag geen betaalgerelateerde gegevens of persoonsgegevens (namen, adressen, etc.) bevatten.

⚠ Niet beschermd onder PCI/AVG: Het is de verantwoordelijkheid van de handelaar om geen gevoelige gegevens op te nemen.

Code Block

language	json
title	Exemple d'objet 'metadata'
linenumbers	true

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

Implementation Recommendations

Implementatieaanbevelingen

Idempotency

Idempotentie

The

De Axepta BNP Paribas Online 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'

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

elk verzoek wordt slechts één keer verwerkt.

Voordelen: Voorkomt dubbele transacties bij herhaalde verzoeken.
Werking:
- Voor POST en PATCH-verzoeken moet een Idempotency-Key in de HTTP-header worden meegegeven.
- De waarde moet uniek zijn per verzoek (aanbevolen: UUID-v4).

Authenticatie

Alle verzoeken aan de Axepta BNP Paribas Online-server moeten geauthenticeerd worden via OAuth 2.0.

Tokengeldigheid: 1 uur.
Vernieuwing: Na verlopen van het token moet u opnieuw authenticeren.
Beveiliging: Gebruik TLS 1.2 of hoger voor alle verbindingen

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

.

Page tree

Versions Compared

Old Version 1

New Version Current

Key

Payment Identification

Merchant Side

Identificatie van betalingen

Kant van de handelaar

Kant van Axepta BNP Paribas Online

Bedrijfsgegevens van de handelaar

Order- en factuuridentificatie

Axepta BNP Paribas Online Side

Merchant Business Data

Order and Invoice Identifier

Customer Identifier

Identificatie van de klant

Merchant-Specific Data

Handelaarspecifieke gegevens

Vereisten voor metadata :

Implementatieaanbevelingen

Idempotentie

Authentication

Authenticatie

Help

Intranet Tools