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

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


Identificatie van betalingen

Handelaarszijde

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



💡 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 om uniciteit te garanderen.
    • U kunt uw eigen refNr opgeven, mits het formaat en de uniciteit gewaarborgd zijn.



Axepta BNP Paribas Online-zijde

Er zijn 2 parameters die door Axepta worden gegenereerd:

ParameterBeschrijvingKenmerken
payIdBetaalidentifier gegenereerd door Axepta.- Uniek en constant gedurende de hele transactielevenscyclus (autorisatie, vastlegging, etc.).<br>- Wordt geretourneerd via feedback-URLs (return, cancel, webhook).<br>- Vereist voor handmatige acties (bv. vastlegging, 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.



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



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



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



Klantidentificatie

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

VeldBeschrijvingFormaatVoorbeeld
customerInfo.emailEssentieel voor transactieverwerking (bv. verzending bevestigingsmail, Visa-reguleringen, zoekopdrachten).<br>Wordt gebruikt voor velocity checks (fraudebescherming).E-mailformaatklant@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 Axepta Helpdesk worden ingesteld.
  • Neem contact op met de Axepta Helpdesk 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 voor metadata :

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

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

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

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



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