Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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

TermBeschrijving
BetalingEen betaalproces dat uit meerdere acties bestaat. Elke actie komt overeen met een stap in het proces (bv. authenticatie, autorisatie,
vastlegging
capture, terugbetaling).
ActieEen specifieke stap in het betaalproces, geïdentificeerd door een xId (bv. autorisatie, annulering).


Identificatie van betalingen

Handelaarszijde

Kant van de handelaar

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

VeldBeschrijvingFormaatVoorbeeld
transIdTransactie-identifier specifiek voor het systeem van de handelaar. Moet uniek zijn en voldoen aan het ‘ans64’-formaat (64 alfanumerieke en speciale tekens).ans64TRANS_20231001_001!@#
refNrReferentienummer 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).an12REF1234567890



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

-zijde

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

ParameterBeschrijvingKenmerken
payIdBetaalidentifier gegenereerd door Axepta BNP Paribas Online.

- Uniek en constant gedurende de hele transactielevenscyclus (autorisatie,

vastlegging

capture, etc.)

.<br>

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

<br>

- Vereist voor handmatige acties (bv.

vastlegging

capture, annulering).

<br>

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

xIdActie-identifier voor een specifieke stap in het betaalproces.- Elke actie (bv. autorisatie, annulering) heeft een eigen xId.<br>- 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:

VeldBeschrijvingFormaat
order.merchantReferenceIdentificeert de order, gedefinieerd door de handelaar.ANS30
order.invoiceIdFactuuridentifier gekoppeld aan de betaling, gedefinieerd door de handelaar.ANS30



Code Block
languagejson
linenumberstrue
"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
title📌 Opmerkingen
  • Deze velden worden weergegeven op de betaalpagina.
  • Minstens één van deze velden is vereist om de 
dubbelcheck
  • dubbelcontrole-functie in te schakelen.
  • Formaat: ANS30 (30 alfanumerieke of speciale tekens).



Klantidentificatie

Identificatie van de klant

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

VeldBeschrijvingFormaatVoorbeeld
customerInfo.email

Essentieel voor transactieverwerking (bv. verzending

bevestigingsmail

bevestigingse-mail, Visa-reguleringen, zoekopdrachten).

<br>Wordt

Wordt gebruikt voor velocity checks (fraudebescherming).

E-mailformaatklant@example.com



Code Block
languagejson
linenumberstrue
"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:

  • Velocity checks (controles op verdachte activiteiten) kunnen alleen door de helpdesk van Axepta
Helpdesk 
  • BNP Paribas worden ingesteld.
  • Neem contact op met de
 Axepta Helpdesk
  • Helpdesk 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).

Eisen

Vereisten voor metadata :

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

✅ Inhoud: Alleen

 sleutel-waarde-paren 

paren "sleutel":"waarde" van het type string

 

(geen integers, geen sub-objecten).

✅ Geen gevoelige gegevens:

Bevat 

Mag geen betaalgerelateerde gegevens of persoonsgegevens (namen, adressen, etc.) bevatten.

⚠ Niet beschermd onder PCI/

RGPD

AVG: Het is de verantwoordelijkheid van de handelaar om geen gevoelige gegevens op te nemen.



Code Block
languagejson
titleExemple d'objet 'metadata'
linenumberstrue
"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.