Deze 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 | ||||||
|---|---|---|---|---|---|---|
Deze sectie van de online documentatie legt uit hoe u betalingen kunt identificeren en beheren binnen het Axepta BNP Paribas Online-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
|
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:
|
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. |
xId | Actie-identifier voor een specifieke stap in het betaalproces. | - Elke actie (bv. autorisatie, annulering) heeft een eigen - 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 |
| 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 | ||
|---|---|---|
| ||
|
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 |
| 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 |
|---|
⚠ Belangrijk:
|
Handelaarspecifieke gegevens
U kunt niet-betaalgerelateerde bedrijfsgegevens meezenden in het metadata-veld tijdens het initiëren van een betaling (POST /payments/sessions of GET /payments).
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 | ||||||
|---|---|---|---|---|---|---|
| ||||||
"metadata": {
"userData": "my user data",
"plain": "some plain text",
"key1": "value1",
"key2": "value2"
} |
Implementatieaanbevelingen
Idempotentie
De Axepta BNP Paribas Online REST API v2 is idempotent: elk verzoek wordt slechts één keer verwerkt.
- Voordelen: Voorkomt dubbele transacties bij herhaalde verzoeken.
- Werking:
- Voor POST en PATCH-verzoeken moet een
Idempotency-Keyin de HTTP-header worden meegegeven. - De waarde moet uniek zijn per verzoek (aanbevolen: UUID-v4).
- Voor POST en PATCH-verzoeken moet een
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.