This documentation provides best practices for using certain fieldssome fields, to ensure the uniqueness and consistency of identifiers throughout the payment process. It also offers technical implementation advice.
| Table of Contents |
|---|
| Note |
|---|
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 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.
| Info |
|---|
Best Practice:
|
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 | ||||
|---|---|---|---|---|
| ||||
"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 |
|---|
|
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
| 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"
}, |
| Info |
|---|
Velocity checks related to the email address
|
Merchant-Specific Data
It is possible to transmit non-payment business data during payment initiation requests (POST /payments/sessions or 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).
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
"metadata": {
"userData": "my user data",
"plain": "some plain text",
"key1": "value1",
"key2": "value2"
} |
Implementation Recommendations
Idempotency
The 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
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.