Integratieaanbevelingen

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.

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

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`

💡 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`

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

📌 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

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

⚠ 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 (POST /payments/sessions of GET /payments).

Vereisten voor metadata :

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

✅ Inhoud: Alleen paren "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.

Exemple d'objet 'metadata'

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

Page tree