NAV Image

1. Overzicht

Wil je volledige vrijheid qua integratie van onze betaalopties? Dan kan je aan de slag met de API's of SDK's van PAY. In deze 'documentatie voor developers' geven we code- en responsevoorbeelden van de functies die je nodig hebt om PAY. te kunnen integreren binnen jouw webshop of verkooplocatie.

Om gebruik te kunnen maken van deze documentatie is enige ervaring met een programmeertaal een vereiste. Heb je geen programmeerkennis? Neem dan een kijkje bij onze kant-en-klare plugins.

1.1. API

Vanzelfsprekend kan je gebruik maken van de standaard API's. Deze zijn vooral handig als er geen SDK voor jouw favoriete programmeertaal aanwezig is of als de gewenste functionaliteit binnen de SDK ontbreekt. Je vindt API code- en responsevoorbeelden door rechtsboven te kiezen voor cURL.

Opbouw API URL

De URL voor een API-verzoek ziet er als volgt uit:
https://rest-api.pay.nl / versie / namespace / functie / uitvoer / parameters


Naam Omschrijving
versie Bij elk API verzoek dien je de versie van de functie aan te geven. Welke versies per functie beschikbaar zijn vind je in de API documentatie.
namespace Bij elk API verzoek dien je de namespace van de functie aan te geven. Ook deze vind je in de API documentatie. De namespace is het onderwerp van de functie.
functie De functie die je wil gebruiken, bijvoorbeeld de functie 'start' van de namespace 'Transaction'.
uitvoer geeft aan hoe wij het resultaat van de API call aan jou presenteren. Mogelijke opties zijn hier:
  • json
  • jsonp
  • xml
  • array
  • array_serialize
  • txt
Parameters De parameters geef je als volgt aan: <variabele> = <waarde> &

Voorbeeld API call

https://rest-api.pay.nl/v13/Transaction/getService/json/?token=abc123&serviceId=SL-1234-5678

1.2. SDK

SDK staat voor Software Development Kit en is een code wrapper voor de meestgebruikte standaard API's. PAY. heeft voor 5 verschillende programmeertalen een SDK ontwikkeld. Op deze manier kan je eenvoudig en met behulp van jouw eigen favoriete programmeertaal de functionaliteiten van het PAY. platform binnen jouw eigen webshop / verkooplocatie integreren.

In de onderstaande tabel vind je de beschikbare SDK's. Deze zijn beschikbaar op Github.


Programmeertaal Laatste versie Github URL
Image PHP v1.5.5 https://github.com/paynl/sdk
Image Node.js https://github.com/paynl/nodejs-sdk
Image C#.NET 1.0.0.8 https://github.com/paynl/csharp-sdk
Image Ruby - https://github.com/paynl/ruby-sdk
Image JAVA v0.2.0 https://github.com/paynl/java-sdk
Image Python v1.0.0 https://github.com/paynl/python-sdk
Image Python v1.0.0 https://github.com/paynl/python2-sdk

SDK PHP

# Installeer PHP SDK via Composer
$ composer require paynl/sdk

Je kan de SDK voor PHP installeren via de command line tool Composer

SDK Node.js

# Installeer Node.js SDK via NPM
$ npm install paynl-sdk --save

Je kan de SDK voor Node.js installeren via de command line tool NPM

SDK C#.NET

De SDK is beschikbaar als DotNet Assembly via Github

SDK ruby

# Installeer Ruby SDK via Rubygems
$ gem install paynl

Je kan de SDK voor Ruby installeren via Rubygems

SDK JAVA

Je kan nl.pay.sdk via de Maven repository importeren

SDK Python

# Installeer PHP SDK via pip
$ pip require paynlsdk

Je kan de SDK voor PHP installeren via de command line tool pip

SDK Python 2

# Installeer PHP SDK via pip
$ pip require paynlsdk2

U kunt de SDK voor PHP installeren via de command line tool pip

2. Aan de slag

In deze 'Documentatie voor developers' worden de volgende onderwerpen uitgelegd:

2.1. Payment CORE

PAY. biedt een hoofd payment CORE en een fallback payment CORE in tijd van nood. Je ontvangt de informatie over de cores van PAY. na de activatie van jouw overeenkomst.

Routeren & optimaliseren van betalingsverkeer

Er zijn dagelijks verstoringen, zowel bij banken, Acquirers en processoren. Meestal merk je er niks van. Indien een bepaalde route traag wordt of helemaal niet beschikbaar is, routeren wij de bezoeker naar andere routes. Indien een iDEAL-bank volledig onbereikbaar is, tonen wij soms het iDEAL backup plan. Indien een derde partij langer dan 15 minuten niet beschikbaar is en deze meer dan 5% van het betalingsverkeer via een gerelateerde betaaloptie wordt verwerkt, vermelden zij deze storing op Status-pay.nl. In het geval van iDEAL banken tonen we de status zoals door iDEAL wordt gecommuniceerd. Vaak loopt deze status enkele minuten achter op de informatie die PAY. inzichtelijk heeft. Wij monitoren realtime de connecties naar elke bank.

Fallback als PAY. maincore onbereikbaar is

Indien PAY. onbereikbaar is, kan je het verzoek routeren naar de FALLBACK-CORE. Hier dien je wel jouw software op voor te bereiden zoals PAY. haar in software logica heeft opgenomen om bij bepaalde scenario’s betalingsverkeer tijdelijk te verhuizen.

Reden waarom je de fallback in gebruik kan nemen:

  • Verstoringen binnen de netwerken naar PAY.
  • Verstoringen op delen van onze hardware
  • Problemen met DNS
  • Problemen in de routes tussen jouw datacenter en de onze

2.2. Ontwikkelaars

Voordat je begint, controleer je in jouw Admin Panel of er gebruikers zijn ingesteld die gaan werken aan de implementatie. Je gaat hiervoor naar merchant » gebruikers en controleert of er personen zijn waarbij 'Mail technische problemen' staat aangevinkt. Indien er fouten optreden, zullen wij deze personen per e-mail op de hoogte stellen.

2.3. Het betaalproces

Het betaalproces verloopt in verschillende stappen die in de afbeelding hiernaast worden weergegeven. Afbeelding: De verschillende stappen in het betaalproces

Image
De verschillende stappen in het betaalproces

Image Consumentenproces

Image Communicatie tussen PAY. en de webshop

Image Communicatie tussen PAY. en issuer

Toelichting betaalproces

  1. Ophalen beschikbare betaalmethoden

    De consument wil de producten in zijn winkelwagen afrekenen en komt terecht op de check-out pagina. Hier dienen de betaalopties (bijvoorbeeld iDEAL of creditcard) die beschikbaar zijn voor de consument te worden opgehaald en weergegeven.

    Request en response voorbeelden m.b.t het ophalen van de beschikbare betaalopties vind je hier

  2. Aanmaken transactie

    Nadat de consument de gewenste betaaloptie op de check-out pagina heeft geselecteerd en de bestelling heeft bevestigd, wordt de transactie aangemaakt op het platform van PAY. PAY. retourneert vervolgens een 'issuer URL' (betaal-URL). Dit is de URL waarnaar de consument gestuurd dient te worden om de betaling af te ronden. (bijvoorbeeld de Rabobank iDEAL pagina).

    Request en response voorbeelden m.b.t het aanmaken van een transacties vindt u hier

  3. Betaling

    De consument wordt doorgestuurd naar de issuer URL en rekent de bestelling af.

  4. Issuer informeert PAY.

    De issuer informeert PAY. over de afhandeling van de transactie.

  5. Aanroep exchange URL

    PAY. roept de exchange / communicatie URL aan bij jouw webshop / verkooplocatie om een statuswijziging van de transactie te communiceren

  6. Controleren transactie status

    De webshop vraagt de status van de transactie op bij PAY. en verwerkt vervolgens de order.

    Request en response voorbeelden m.b.t het opvragen van de status van een transactie vindt u hier

  7. Return URL

    Na stap 3 (betaling) wordt de consument doorgestuurd naar de return URL (ook wel finish URL of bedankpagina). Je kan de status van de betaling opvragen bij PAY. en op basis van de status de consument bedanken voor de betaling of informeren over eventuele fouten (indien die zijn opgetreden).

    De return URL is enkel bedoeld om de klant te informeren over een transactie. De daadwerkelijke verwerking van de transactie moet via de exchange URL plaatsvinden!

    Request en response voorbeelden m.b.t de return URL vindt u hier

2.4. Test modus

Binnen PAY. kan een verkooplocatie (webshop) de volgende statussen hebben:

  • Test modus
    Als jouw verkooplocatie in 'Test modus' staat, dan worden de betalingen afgerond via ons 'Sandbox' betaalscherm. Middels het invoeren van een API token kan een betaling worden gesimuleerd.
  • Live modus
    Jouw bezoekers worden naar het echte betaalscherm gestuurd en kunnen middels een echte betaling een transactie correct afronden.

Test modus inschakelen via Admin Panel

Je kan via het Admin Panel handmatig jouw verkooplocatie in test modus zetten. In het merchant document wordt stap voor stap beschreven hoe je dit bewerkstelligt.

Test modus inschakelen via API of SDK

Je kan bij het starten van een transactie meegeven of de transactie moet worden uitgevoerd in test modus.

2.5. Koppeling maken

Image
Ophalen API token en service-ID

Om een koppeling te kunnen maken tussen jouw webshop / verkooplocatie en het platform van PAY. dien je een api code, api token en service id in te voeren. Je vindt deze gegevens als volgt:

  • Ga in het Admin Panel naar het tabblad Verkooplocaties https://admin.pay.nl/programs/programs/

  • Je vindt hier een overzicht van jouw verkooplocaties. Als je nog geen verkooplocatie hebt aangemaakt dan vind je hier meer informatie.

  • Selecteer de verkooplocatie waarmee je de koppeling wil maken door op het service-ID te klikken (SL-code) of op de link 'Gegevens'.

  • Er wordt een popup geopend Afbeelding 1 met de api code, api token en service id van de betreffende verkooplocatie.

2.6. Rate Limits

PAY. hanteert een maximaal aantal aanroepen afhankelijk van het gekozen pakket. Deze limieten zijn ruim voldoende voor normaal gebruik: fair use policy. Wanneer men hierover heen gaat is er vrijwel altijd sprake van een "bad implementation".

Bij het overschrijden van de onderstaande limieten treedt de rate limiter in werking en kunnen uw verzoeken (tijdelijk) worden geblokkeerd. Afhankelijk van de overschrijding kan men 1, 5 of 15 minuten worden geblokkeerd. Bij "Excessive use" kan een definitieve blokkade worden toegepast. Neemt u in dat geval contact op met support@pay.nl.

Pakket Rate limit
Pioneer, Professional 100 aanroepen per 60 seconden
Business 300 aanroepen per 30 seconden
Corporate Maatwerk

Polling

In het geval van "bad implementation" is er vrijwel altijd sprake van polling, waarbij er bijvoorbeeld per seconde een aanroep naar het platform van PAY. wordt gedaan om de status te controleren. Polling is in veel gevallen niet nodig omdat er een exchange call wordt verstuurd vanuit PAY. zodra er een statusverandering plaatsvindt.

2.7. Implementatie error e-mail

Image
Voorbeeld e-mail notificatie

Indien je koppelt met op basis van de API van PAY. dien je jouw implementatie goed te testen. Bij onjuiste implementatie, onnodig veel verzoeken of foutieve verzoeken zal het beschermingssysteem van PAY. in werking treden. Dit kan één of een combinatie van de volgende gevolgen hebben:

  • Je ontvangt een BAD IMPLEMENTATION e-mail.
  • Jouw server of token wordt voor een periode van 5, 15, 60 minuten of 24 uur geblokkeerd.
  • Je overschrijdt de fair use policy waardoor extra kosten gerekend kunnen worden.
  • Wij kunnen de overeenkomst eenzijdig opzeggen.

Controleer jouw PAY. implementatie dus goed. Neem ruim de tijd voor foutafhandeling en error-logging binnen jouw eigen systemen.

Error codes (HTTP STATUSSEN)

Veel voorkomende redenen van errors zijn:

  • ERROR-400 - Aanroepen zonder correcte variabelen.
  • ERROR-401 - Ongeautoriseerd aanroepen van API calls zonder Authentication informatie of 'onvoldoende rechten'
  • ERROR-404 - Aanroepen van niet bestaande bestanden, of reeds gearchiveerde transacties.

Teveel aanroepen

De standaard fair-use policy geeft jou ruimte om maximaal 1.000 HTTP aanroepen per maand uit te voeren + per succesvol uitgevoerde transacties vier extra aanroepen.

  • getService: Om de verkooplocaties en geactiveerde betaalopties op te halen. CACHE
  • getBanks: Om de banken binnen iDEAL op te halen. CACHE
  • transactionStart: Om een betaling te starten.
  • transactionStatus: Om de betaalstatus van een transactie op te halen.

Doe je dus 1.000 betalingen per maand, dan kan je dus 1.000 + 4.000 = 5.000 API HTTP request uitvoeren.

3. Authenticatie

Request code: Authenticatie

curl --request POST \
  --url https://rest-api.pay.nl/<version>/<namespace>/<function>/json \
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \

Om een API request te authenticeren wordt gebruikt gemaakt van 'HTTP Basic Authentication'. Hierbij wordt een base64 gecodeerde hash username:password meegestuurd in de header van het verzoek. We noemen dit de Authorization header.

Een voorbeeld van een Authorization header: authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==

'dG9rZW46PHlvdXItYXBpLXRva2VuPg==' is in dit geval het resultaat van de base64 gecodeerde hash username:password (let op de dubbele punt!) De username is bij een PAY. API altijd waarde van de account code en begint met AT-, Het password is de waarde van de API token; een string van 40 karakters.

Voorbeeld genereren Authorization header
De Authorization header voor een API verzoek zouden we m.b.v PHP als volgt genereren: base64_encode('your-api-code:<your-api-token>');

4. Betaalopties ophalen

Een verkooplocatie bevat de instellingen van een merchant waaronder de URL, een omschrijving en een categorie waarbinnen de verkooplocatie valt. Tevens wordt in een verkooplocatie aangegeven hoe de verkooplocatie gekoppeld wordt en welke betaalopties er gebruikt kunnen worden.

Een verkooplocatie bevat betaalopties waarmee de klant een transactie kan afronden. De beschikbare betaalopties die door de merchant zijn ingesteld kan je via de API Transaction::getService of een SDK ophalen.

Je plaatst de beschikbare betaalopties op de check-out pagina van jouw webshop / verkooplocatie. De betaaloptie die door jouw klant wordt geselecteerd, wordt gebruikt om de transactie aan te maken.

Authenticatie

Basic Authentication

Authenticatie van de API Transaction::getService vindt plaats middels HTTP Basic Authentication

Request code: Betaalmethoden ophalen

curl --request POST \
  --url https://rest-api.pay.nl/v16/Transaction/getService/json \
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'serviceid=SL-1234-5678'

Request

In dit request voorbeeld halen we de beschikbare betaalopties op voor verkooplocatie SL-1234-5678.

Parameters

Parameter Type Omschrijving
serviceId string VERPLICHT Jouw verkooplocatie start met 'SL-' gevolgd door 8 cijfers. Je vindt een overzicht van jouw verkooplocatie(s) op https://admin.pay.nl/websites
paymentMethodId integer OPTIONEEL De volgende ID's zijn beschikbaar: 1: SMS, 2: pay fixed price, 3: pay per call, 4: pay per transaction, 5: pay per minute. Indien je geen keuze meegeeft, worden alle betaalmethoden weergegeven.

Response

Response: Betaalmethoden ophalen

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "request": {
    "result": "1",
    "errorId": "",
    "errorMessage": ""
  },
  "merchant": {
    "id": "M-3421-2120",
    "name": "Demoshop Pay.nl",
    "publicName": "Demoshop Pay.nl",
    "state": "1"
  },
  "service": {
    "id": "SL-1234-5678",
    "state": "1",
    "name": "My Demoshop",
    "description": "Description webshop",
    "publication": "http://www.shopdomain.com/",
    "basePath": "https://admin.pay.nl/images",
    "secret": "e820ad58594ab8fe769943eb465eacae35e77wq1",
    "tradename": "My Tradename"
  },
  "settings": "",
  "countryOptionList": {
    "NL": {
      "id": "NL",
      "name": "Netherlands",
      "visibleName": "Netherlands",
      "in_eu": "1",
      "img": "nl.gif",
      "path": "/flags/",
      "paymentOptionList": {
        "10": {
          "id": "10",
          "name": "iDEAL",
          "visibleName": "iDEAL",
          "image": "/payment_profiles/10.gif",
          "state": "1",
          "useOnlyInStore": "0",
          "paymentMethodId": "4",
          "min_amount": "1",
          "max_amount": "1000000",		  
          "brand": {
            "id": "1",
            "name": "iDEAL",
            "image": "/payment_profile_brands/100x100/1.png"",
            "public_description": "" 
          },
          "paymentOptionSubList": {
            "1": {
              "id": "1",
              "name": "ABN Amro",
              "visibleName": "ABN Amro",
              "image": "/payment_banks/1.png",
              "state": "1"
            },
            "2": {
              "id": "2",
              "name": "Rabobank",
              "visibleName": "Rabobank",
              "image": "/payment_banks/2.png",
              "state": "1"
            },
            "4": {
              "id": "4",
              "name": "ING Bank",
              "visibleName": "ING Bank",
              "image": "/payment_banks/4.png",
              "state": "1"
            },
            "5": {
              "id": "5",
              "name": "SNS Bank",
              "visibleName": "SNS Bank",
              "image": "/payment_banks/5.png",
              "state": "1"
            },
            "8": {
              "id": "8",
              "name": "ASN Bank",
              "visibleName": "ASN Bank",
              "image": "/payment_banks/8.png",
              "state": "1"
            },
            "9": {
              "id": "9",
              "name": "RegioBank",
              "visibleName": "RegioBank",
              "image": "/payment_banks/9.png",
              "state": "1"
            },
            "10": {
              "id": "10",
              "name": "Triodos Bank",
              "visibleName": "Triodos Bank",
              "image": "/payment_banks/10.png",
              "state": "1"
            },
            "11": {
              "id": "11",
              "name": "Van Lanschot Bankiers",
              "visibleName": "Van Lanschot Bankiers",
              "image": "/payment_banks/11.png",
              "state": "1"
            },
            "12": {
              "id": "12",
              "name": "Knab bank",
              "visibleName": "Knab bank",
              "image": "/payment_banks/12.png",
              "state": "1"
            },
            "5080": {
              "id": "5080",
              "name": "Bunq",
              "visibleName": "Bunq",
              "image": "/payment_banks/5080.png",
              "state": "1"
            }
          }
        }
      }
    },
    "BE": {
      "id": "BE",
      "name": "Belgium",
      "visibleName": "Belgium",
      "in_eu": "1",
      "img": "be.gif",
      "path": "/flags/",
      "paymentOptionList": {
        "436": {
          "id": "436",
          "name": "MisterCash / Bancontact",
          "visibleName": "MisterCash / Bancontact",
          "image": "/payment_profiles/436.gif",
          "state": "1",
          "useOnlyInStore": "0",
          "paymentMethodId": "4",
          "min_amount": "1",
          "max_amount": "1000000",
          "brand": {
            "id": "2",
            "name": "Bancontact",
            "image": "/payment_profile_brands/100x100/2.png"",
            "public_description": "" 
          },			  
          "paymentOptionSubList": ""
        }
      }
    }
  }
}

In dit response voorbeeld worden de betaalopties weergegeven voor verkooplocatie: SL-1234-5678. In dit geval zijn er twee betaalopties beschikbaar. iDEAL (Nederland) en Bancontact (België).

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result string 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
errorMessage string Als er een foutmelding is opgetreden dan vind je hier de omschrijving
merchant array Array met informatie over de merchant
id string Het merchant-ID, deze start met 'M-'
name string Bedrijfsnaam zoals bekend bij de KvK, KBO etc.
publicName string Bedrijfsnaam zoals deze aan klanten weergegeven moet worden
state string Status van de merchant: 0: niet actief, 1: actief
service array Array met informatie over de verkooplocatie
id string Het service-ID, deze start met 'SL-'
name string Naam van de verkooplocatie
description string Omschrijving van de verkooplocatie
publication string De URL van de website waarop de diensten worden gebruikt
basePath string Basepath voor de afbeeldingen van de betaalopties
secret string Secret van de verkooplocatie om dynamische QR-betalingen te genereren.
tradename string Handelsnaam die gebruikt wordt voor de betreffende verkooplocatie
state string Status van de verkooplocatie: 0: testmodus, 1: actief, -1: wordt gecontroleerd, -2: geblokkeerd
settings array Array met informatie over de instellingen (key - value)
countryOptionList array Array met informatie over de beschikbare betaalopties per land
Image array
id string ISO landcode, code ALL betekent in alle landen beschikbaar
name string Naam van het land in het Engels
visibleName string Naam van land zoals weergegeven in betaalscherm
in_eu string Geeft weer of het land zich binnen de EU bevindt. 0: buiten de EU, 1: binnen de EU
img string Afbeeldingslocatie van het desbetreffende land
path string Aanvulling op het basis pad naar de afbeelding
paymentOptionList array Beschikbare betaalmethoden binnen een land
Image array
id string Interne ID van de betaaloptie. Je vindt een overzicht op https://admin.pay.nl/data/payment_profiles
name string Naam van de betaaloptie, bijvoorbeeld iDEAL
visibleName string Naam van de betaaloptie zoals getoond dient te worden aan de betalende bezoekers
image string Afbeeldingslocatie van de desbetreffende betaaloptie
state string Status van de betaaloptie: 0 : Niet actief, 1 : Actief
useOnlyInStore string 0 : Betaaloptie niet geschikt voor pintransacties, 1 : Betaaloptie geschikt voor pintransacties
paymentMethodId string 1: SMS, 2: pay fixed price, 3: pay per call, 4: pay per transaction, 5: pay per minute
min_amount integer Minimum bedrag in centen waarvoor een transactie via deze betaaloptie kan worden gestart
max_amount integer Maximum bedrag in centen waarvoor een transactie via deze betaaloptie kan worden gestart
brand array
id integer Brand id van de betaaloptie. U kunt deze gebruiken bij het weergeven van een afbeelding van de betaaloptie
name string Naam van de betaaloptie
image string Locatie van de afbeelding van de betaaloptie.
public_description string Publieke omschrijving van de betaaloptie
paymentOptionSubList array Een lijst met sub betaalopties. Dit zijn bijvoorbeeld de beschikbare banken in het geval van iDEAL, Giropay of myBank
Image array
id string Interne id van de sub betaaloptie
name string Naam van de sub betaaloptie, bijvoorbeeld Rabobank
visibleName string Naam van de sub betaaloptie zoals getoond dient te worden aan de betalende bezoekers
image string Afbeeldingslocatie van de desbetreffende sub betaaloptie
state string Status van de betaaloptie. 0 : Niet actief, 1 : Actief

5. Transacties

5.1. Statuscodes

Image
Status flow

Als je de status van een betaling opvraagt dan kan je te maken krijgen met een aantal verschillende statussen. Algemeen geldt dat de status 100 moet zijn anders is de betaling (nog) niet gelukt.

  • Statuscode: 100: De betaling is succesvol
  • Statuscode: NEGATIEF: De betaling is geannuleerd of teruggeboekt
  • Statuscode: POSITIEF: De betaling is nog steeds wachtende, er is nog geen eindstatus bekend

Klik hier voor de volledige lijst met statuscodes.

5.2. Het transactieproces

Image
Het proces m.b.t het starten van een transactie en het ophalen van de status

Het proces m.b.t het starten van een transactie en het ophalen van de status wordt hiernaast weergegeven in de afbeelding.

Redirecten naar de betaalpagina

Indien je de bezoeker doorstuurt naar de betaalpagina dien je ervoor te zorgen dat dit in het huidige of een nieuw venster gebeurd. De URL en het slotje van de beveiligde verbindingen dienen te allen tijde zichtbaar te zijn. Dit geldt ook voor in-app betalingen. Indien je redirect in een ander type window, binnen een app of via een MODAL screen of iFrame kan de betaaloptie de betaalopdracht afwijzen.

5.3. Transaction:START (BASIC)

Voor het starten van een transactie binnen het PAY. platform gebruik je de API Transaction::start of een SDK. Voor vrijwel alle betaalopties zijn de onderstaande parameters en codevoorbeelden van toepassing. Uitzonderingen hierop gelden voor de volgende betaalopties:

Deze uitzonderingen voor de betaalopties worden daarom apart toegelicht en voorzien van eigen codevoorbeelden.

Een transactie wordt gestart zodra de order bekend is (winkelwagentje)

Authenticatie

Authenticatie van de API Transaction::start vindt plaats middels HTTP Basic Authentication

Request

Request code: Transactie starten

curl --request POST \
  --url https://rest-api.pay.nl/v13/Transaction/start/json \
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'serviceId=SL-3490-4320' \
  --data-urlencode 'amount=100' \
  --data-urlencode 'ipAddress=1.2.3.4' \
  --data-urlencode 'finishUrl=https://www.domain.com/return' \
  --data-urlencode 'paymentOptionId=436' \
  --data-urlencode 'transaction[description]=My first payment'
  --data-urlencode 'transaction[orderNumber]=123ABC'

In dit request voorbeeld starten we een transactie van € 1,- voor verkooplocatie SL-1234-5678 met de betaalmethode Bancontact (betaaloptie ID: 436)

Parameters

Paramater Type Omschrijving
serviceId string VERPLICHT Jouw verkooplocatie start met 'SL-' gevolgd door 8 cijfers. Je vindt een overzicht van jouw verkooplocatie(s) op https://admin.pay.nl/websites
amount integer VERPLICHT Bedrag in centen, dus €3,50 is 350.
ipAddress string VERPLICHT IP-adres van gebruiker. Let op dat je niet jouw eigen server IP meestuurt, bijvoorbeeld bij het gebruik van een loadbalancer. Zie https://github.com/paynl/sdk/ voor een voorbeeld.
finishUrl string VERPLICHT URL waar de bezoeker naar wordt doorgestuurd als de betaling is voltooid
paymentOptionId integer OPTIONEEL Interne ID van de betaaloptie waarvoor je een transactie wil starten. Je vindt een overzicht op https://admin.pay.nl/data/payment_profiles
paymentOptionSubId integer OPTIONEEL Interne ID van de sub betaaloptie waarvoor je een transactie wil starten. Bijvoorbeeld de Rabobank in het geval van een iDEAL betaling
testmode boolean OPTIONEEL Transactie uitvoeren in test modus. 0: Geen test modus ,1: Gebruik test modus
transaction Image array OPTIONEEL bekijk array
currency string OPTIONEEL Valuta volgens ISO 4217 (drielettercode). Indien leeg wordt EUR gebruikt. Je vindt een overzicht op https://admin.pay.nl/data/currencies
orderExchangeUrl string OPTIONEEL De URL voor het afleveren van de statussen, ook wel webhook of IPN genoemd.
description string OPTIONEEL Omschrijving van de order (maximaal 32 tekens)
orderNumber string OPTIONEEL Nummer van de order (maximaal 16 tekens, alphanummeriek)
expireDate string OPTIONEEL Verloopdatum van de transactie in het formaat: dd-mm-yyyy HH:ii:ss (31-12-2017 22:33:44). Maximale verloopdatum is +4 weken.
statsData Image array OPTIONEEL bekijk array
promotorId integer OPTIONEEL Het id van de promotor (webmaster)
info string OPTIONEEL Variabele 'info' die kan worden getraceerd in de statistieken
tool string OPTIONEEL Variabele 'tool' die kan worden getraceerd in de statistieken
extra1 string OPTIONEEL Vrije variabele 'extra1' die kan worden getraceerd in de statistieken. (advies: ID van de order)
extra2 string OPTIONEEL Vrije variabele 'extra2' die kan worden getraceerd in de statistieken. (advies: klant referentie)
extra3 string OPTIONEEL Vrije variabele 'extra3' die kan worden getraceerd in de statistieken
transferData string OPTIONEEL Een array van vrije waarden
enduser Image array OPTIONEEL bekijk array
language string OPTIONEEL Taal van de eindgebruiker, NL voor Nederlands en EN voor Engels
initials string OPTIONEEL Voornaam / initialen van de eindgebruiker
lastName string OPTIONEEL Achternaam van de eindgebruiker
gender string OPTIONEEL M: man, F: vrouw
dob string OPTIONEEL Geboortedatum in het formaat dd-mm-yyyy
phoneNumber string OPTIONEEL Telefoonnummer van de eindgebruiker
emailAddress string OPTIONEEL E-mailadres van de eindgebruiker
customerReference string OPTIONEEL Unieke referentie van de eindgebruiker. Maximaal 32 tekens, alphanumeriek.
customerTrust integer OPTIONEEL Geef aan of je de eindgebruiker vertrouwd op een schaal van -10 tot 10. -10 is onbetrouwbaar, 10 is betrouwbaar.
address array OPTIONEEL
streetName string OPTIONEEL Straatnaam van de eindgebruiker
streetNumber string OPTIONEEL Huisnummer van de eindgebruiker
streetNumberExtension string OPTIONEEL Toevoeging huisnummer
zipCode string OPTIONEEL Postcode van de eindgebruiker
city string OPTIONEEL Woonplaats van de eindgebruiker
countryCode string OPTIONEEL Landcode volgens ISO 3166 (tweelettercode). Je vindt een overzicht op https://admin.pay.nl/data/countries
invoiceAddress array OPTIONEEL
initials string OPTIONEEL Voornaam / initialen van de persoon die de factuur ontvangt
lastName string OPTIONEEL Achternaam van de persoon die de factuur ontvangt
gender string OPTIONEEL Geslacht van de persoon die de factuur ontvangt. M: man, F: vrouw
streetName string OPTIONEEL Straatnaam van de persoon die de factuur ontvangt
streetNumber string OPTIONEEL Huisnummer van de persoon die de factuur ontvangt
streetNumberExtension string OPTIONEEL Toevoeging huisnummer van de persoon die de factuur ontvangt
zipCode string OPTIONEEL Postcode van de persoon die de factuur ontvangt
city string OPTIONEEL Woonplaats van de persoon die de factuur ontvangt
countryCode string OPTIONEEL Landcode volgens ISO 3166 (tweelettercode) van de persoon die de factuur ontvangt. Je vindt een overzicht op https://admin.pay.nl/data/countries
company array OPTIONEEL
name string OPTIONEEL Naam van het bedrijf
cocNumber string OPTIONEEL KvK van het bedrijf
vatNumber string OPTIONEEL BTW nummer van het bedrijf
countryCode string OPTIONEEL Landcode volgens ISO 3166 (tweelettercode) waar het bedrijf is gevestigd. Je vindt een overzicht op https://admin.pay.nl/data/countries
saleData Image array OPTIONEEL bekijk array
invoiceDate string OPTIONEEL Datum van de factuur (YYYY-MM-DD)
deliveryDate string OPTIONEEL Verwachte leverdatum (YYYY-MM-DD) - In geval van ticketing datum evenement. Indien meerdaags, eerste dag meesturen.
orderData array OPTIONEEL
Image array OPTIONEEL Array met bestelde producten
productId string OPTIONEEL Het interne product ID binnen jouw systeem
productType string OPTIONEEL Type van de orderregel met de volgende mogelijke waarden: ARTICLE, SHIPPING, HANDLING, DISCOUNT
description string OPTIONEEL Omschrijving van het bestelde product
price integer OPTIONEEL Productprijs in centen, dus €3,50 is 350.
quantity integer OPTIONEEL Aantal bestelde producten met het betreffende product ID
vatCode string OPTIONEEL BTW code, mogelijke waarden: H: high, N: zero, L: low
vatPercentage string OPTIONEEL BTW percentage, bv: 21.00 of 6.00
transferData Image array OPTIONEEL bekijk array
gaClientId string OPTIONEEL ID van Google Tracking

Vanwege het grote aantal parameters worden de arrays beperkt weergegeven. Klik op de button 'bekijk array' om de volledige array te bekijken.


Response

Response: Transactie starten

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
   "request":{
      "result":"1",
      "errorId":"",
      "errorMessage":""
   },
   "endUser":{
      "blacklist":"0"
   },
   "transaction":{
      "transactionId":"805537291X770f36",
      "paymentURL":"https://bancontact.pay.be/start/805537291X770f36/95685556c567f4f28c7c1128f897f1a9e133c0b5/",

      "popupAllowed":"0",
      "paymentReference":"6000 0008 0553 7291"
   }
}

In dit response voorbeeld zie je het resultaat van een transactie van € 1,- die gestart is voor verkooplocatie SL-1234-5678 voor betaaloptie Bancontact.

Als resultaat ontvang je o.a een paymentURL (ook wel issuerURL). Dit is de URL waar je de eindgebruiker naar toe dient te sturen zodat de transactie kan worden betaald.

Het is aan te raden om transactionId bij jouw order in de database op te slaan. Dit is namelijk de unieke referentie van de transactie binnen het platform van PAY. en zal worden meegestuurd als GET / POST parameter aan de exchange- en return URL.

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result boolean 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
errorMessage string Als er een foutmelding is opgetreden dan vind je hier de omschrijving
enduser array
blacklist integer Geef aan of de eindgebruiker op de blacklist voorkomt. 0: Niet op blacklist, 1: Op blacklist voor merchant, 2: Op blacklist voor alle merchants
transaction array
transactionId integer Uniek ID van de transactie zoals die gebruikt wordt binnen het PAY. platform
paymentURL string URL van het betaalscherm waarnaar de bezoeker doorgestuurd dient te worden om de betaling te voltooien
popupAllowed boolean Geef aan of het betaalscherm in een popup mag worden geladen. 0: niet toegestaan, 1: toegestaan
paymentReference string Betaalkenmerk waarmee banktransacties geïdentificeerd worden.

5.4. Transaction:START (iDEAL)

Betaaloptie ID Naam
10 iDEAL

Om een iDEAL transactie te starten zou je het voorbeeld kunnen gebruiken dat staat weergegeven bij 'Transactie starten' In dat geval geef je het paymentOptionId de waarde 10 mee (iDEAL). Als resultaat zou je dan een paymentURL krijgen die de bezoeker naar de algemene iDEAL pagina stuurt.

Uitzondering

Voor een iDEAL betaling is echter een extra parameter paymentOptionSubId beschikbaar waar je het ID van de gekozen bank aan kan meegeven. Een compleet overzicht van alle iDEAL banken en de bijbehorende ID's vind je op Betaalmethoden » Bankenoverzicht

Als je een paymentOptionSubId meegeeft dan ontvang je de directe link naar de iDEAL bank in plaats van een link naar de algemene iDEAL pagina. Je kan het bankselectiescherm van iDEAL dus op jouw eigen check-out pagina weergeven wat een betere conversie oplevert en op basis van de gekozen bank de parameter paymentOptionSubId instellen.

Banken ophalen via een API

Het is mogelijk om de iDEAL banken paymentOptionSubId op te halen via de volgende API: https://rest-api.pay.nl/v13/Transaction/getBanks/json Omdat de banken vrijwel nooit wijzigen, is het aan te raden om het resultaat van deze API te cachen.

Request

Request code: Rabobank iDEAL transactie starten

curl --request POST \
  --url https://rest-api.pay.nl/v16/Transaction/start/json \
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'serviceId=SL-3490-4320' \
  --data-urlencode 'amount=100' \
  --data-urlencode 'ipAddress=1.2.3.4' \
  --data-urlencode 'finishUrl=https://www.domain.com/return' \
  --data-urlencode 'paymentOptionId=10' \
  --data-urlencode 'paymentOptionSubId=2' \
  --data-urlencode 'transaction[description]=My first payment'
  --data-urlencode 'transaction[orderNumber]=123ABC'

In dit request voorbeeld starten we een transactie van € 1,- voor verkooplocatie SL-1234-5678 met de betaalmethode iDEAL (betaaloptie ID: 10) en bank: Rabobank (sub betaaloptie ID: 2).

Response

Response code: Rabobank iDEAL transactie starten

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
   "request":{
      "result":"1",
      "errorId":"",
      "errorMessage":""
   },
   "endUser":{
      "blacklist":"0"
   },
   "transaction":{
      "transactionId":"805537292X770f55",
      "paymentURL":"https://betalen.rabobank.nl/ideal-betaling/landingpage?trxid=1529175",
      "popupAllowed":"0",
      "paymentReference":"6000 0008 0553 7292"
   }
}

In dit response voorbeeld zie je het resultaat van een transactie van € 1,- die gestart is voor verkooplocatie SL-1234-5678 voor betaaloptie iDEAL.

Als resultaat ontvang je o.a een paymentURL (ook wel issuerURL), dit is de URL waar je de eindgebruiker naar toe dient te sturen zodat de transactie kan worden betaald. In dit geval is dat niet de algemene iDEAL pagina maar de iDEAL pagina van de Rabobank omdat ernaast paymentOptionId 10 ook een paymentOptionSubId 2 mee is gegeven.


5.5. Transaction:START (FULL ORDER)

PAY. adviseert om bij elke betaling de volledige klant- en orderdata door te sturen, zodat je ook bij andere betaalopties een uniform overzicht houdt. De volgende achter- en gespreid betaalopties vereisen de klant- en orderdata om een kredietcheck uit te kunnen voeren om te bepalen of een transactie wordt geaccepteerd.

Betaaloptie ID Naam
2561 Riverty International
739 Riverty
1672 Billink
1675 Billink
2107 CreditClick
1813 iDEAL in3
1717 Klarna
1987 SprayPay

De kredietcheck wordt uitgevoerd op basis van historische data. Hiervoor is het verplicht dat men de volgende klant- en orderdata meestuurt bij het starten van de transactie. Indien deze data niet meegestuurd wordt dan zal de transactie worden geweigerd.

Parameter Type Omschrijving
enduser array VERPLICHT Bevat naam, geslacht, geboortedatum en contactgegevens van de eindgebruiker
address array VERPLICHT Bevat de adresgegevens van de eindgebruiker die de bestelling heeft geplaatst
invoiceAddress array VERPLICHT Bevat de adresgegevens van de persoon die de factuur ontvangt
saleData array VERPLICHT Bevat de producten die door de eindgebruiker zijn besteld

Request code: Transactie achteraf betaalmethode starten

curl --request POST \
  --url https://rest-api.pay.nl/v16/Transaction/start/json \
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'serviceId=SL-3490-4320' \
  --data-urlencode 'amount=100' \
  --data-urlencode 'ipAddress=1.2.3.4' \
  --data-urlencode 'finishUrl=https://www.domain.com/return' \
  --data-urlencode 'paymentOptionId=739' \
  --data-urlencode 'transaction[description]=My first payment' \
  --data-urlencode 'transaction[orderNumber]=123ABC'
  --data-urlencode 'enduser[initials]=T' \
  --data-urlencode 'enduser[lastName]=Testname' \
  --data-urlencode 'enduser[gender]=M' \
  --data-urlencode 'enduser[dob]=01-01-1999' \
  --data-urlencode 'enduser[phoneNumber]=0612345678' \
  --data-urlencode 'enduser[emailAddress]=test@email.com' \
  --data-urlencode 'enduser[address][streetName]=Teststreet' \
  --data-urlencode 'enduser[address][streetNumber]=10' \
  --data-urlencode 'enduser[address][zipCode]=1234 AB' \
  --data-urlencode 'enduser[address][city]=Amsterdam' \
  --data-urlencode 'enduser[address][countryCode]=NL' \
  --data-urlencode 'enduser[invoiceAddress][initials]=K' \
  --data-urlencode 'enduser[invoiceAddress][lastName]=Jansen' \
  --data-urlencode 'enduser[invoiceAddress][streetName]=Secondstreet' \
  --data-urlencode 'enduser[invoiceAddress][streetNumber]=15' \
  --data-urlencode 'enduser[invoiceAddress][zipCode]=2345 CD' \
  --data-urlencode 'enduser[invoiceAddress][city]=Rotterdam' \
  --data-urlencode 'enduser[invoiceAddress][countryCode]=NL' \
  --data-urlencode 'saleData[invoiceDate]=01-07-2017' \
  --data-urlencode 'saleData[deliveryDate]=03-07-2017' \
  --data-urlencode 'saleData[orderData][0][productId]=1' \
  --data-urlencode 'saleData[orderData][0][productType]=ARTICLE' \
  --data-urlencode 'saleData[orderData][0][description]=First product' \
  --data-urlencode 'saleData[orderData][0][price]=80' \
  --data-urlencode 'saleData[orderData][0][quantity]=1' \
  --data-urlencode 'saleData[orderData][0][vatCode]=H' \
  --data-urlencode 'saleData[orderData][0][vatPercentage]=21.00' \
  --data-urlencode 'saleData[orderData][1][productId]=101' \
  --data-urlencode 'saleData[orderData][1][productType]=SHIPPING' \
  --data-urlencode 'saleData[orderData][1][description]=Shipping costs' \
  --data-urlencode 'saleData[orderData][1][price]=20' \
  --data-urlencode 'saleData[orderData][1][quantity]=1' \
  --data-urlencode 'saleData[orderData][1][vatCode]=H' \
  --data-urlencode 'saleData[orderData][1][vatPercentage]=21.00'

Authenticatie

Authenticatie van de API Transaction::start vindt plaats middels HTTP Basic Authentication

Request

In dit request voorbeeld starten we een transactie van € 1,- voor verkooplocatie SL-1234-5678 met de betaalmethode Riverty (betaaloptie ID 739). In de voorbeeldcode hiernaast staat in het roze weergegeven wat de verplichte parameters zijn t.o.v. een standaard transactie.

Parameters

Parameter Type Omschrijving
serviceId string VERPLICHT Jouw verkooplocatie start met 'SL-' gevolgd door 8 cijfers. Je vindt een overzicht van jouw verkooplocatie(s) op https://admin.pay.nl/websites
amount integer VERPLICHT Bedrag in centen, dus €3,50 is 350
ipAddress string VERPLICHT IP-adres van gebruiker. Let op dat je niet jouw eigen server IP meestuurt bij het gebruik van een loadbalancer. Zie https://github.com/paynl/sdk/ voor een voorbeeld.
finishUrl string VERPLICHT URL waar de bezoeker naar wordt doorgestuurd als de betaling is voltooid
paymentOptionId integer OPTIONEEL Interne ID van de betaaloptie waarvoor je een transactie wil starten. Je vindt een overzicht op https://admin.pay.nl/data/payment_profiles
paymentOptionSubId integer OPTIONEEL Interne ID van de sub betaaloptie waarvoor je een transactie wil starten. Bijvoorbeeld de Rabobank in het geval van een iDEAL betaling
testMode boolean OPTIONEEL Transactie uitvoeren in test modus. 0: Geen test modus ,1: Gebruik test modus
transaction Image array OPTIONEEL bekijk array
currency string OPTIONEEL Valuta volgens ISO 4217 (drielettercode), indien leeg wordt EUR gebruikt. Je vindt een overzicht op https://admin.pay.nl/data/currencies
orderExchangeUrl string OPTIONEEL De URL voor het afleveren van de statussen, ook wel webhook of IPN genoemd.
description string OPTIONEEL Omschrijving van de order (maximaal 32 tekens alphanummeriek en spaties)
orderNumber string OPTIONEEL orderNumber (maximaal 16 tekens alphanummeriek), wordt bij iDEAL END2END als payment referentie op het afschrift geplaatst.
expireDate string OPTIONEEL Verloopdatum van de transactie in het formaat: dd-mm-yyyy HH:ii:ss (31-12-2017 22:33:44). Maximale verloopdatum is +4 weken.
statsData Image array OPTIONEEL bekijk array
promotorId integer OPTIONEEL Het ID van de promotor (webmaster)
info string OPTIONEEL Variabele 'info' die kan worden getraceerd in de statistieken
tool string OPTIONEEL Variabele 'tool' die kan worden getraceerd in de statistieken
extra1 string OPTIONEEL Vrije variabele 'extra1' die kan worden getraceerd in de statistieken (advies: ID van de order).
extra2 string OPTIONEEL Vrije variabele 'extra2' die kan worden getraceerd in de statistieken (advies: klant referentie).
extra3 string OPTIONEEL Vrije variabele 'extra3' die kan worden getraceerd in de statistieken
transferData string OPTIONEEL Een array van vrije waarden
enduser Image array OPTIONEEL bekijk array
language string OPTIONEEL Taal van de eindgebruiker, NL voor Nederlands, EN voor Engels
initials string OPTIONEEL Voornaam / initialen van de eindgebruiker
lastName string OPTIONEEL Achternaam van de eindgebruiker
gender string OPTIONEEL M: man, F: vrouw
dob string OPTIONEEL Geboortedatum in het formaat dd-mm-yyyy
phoneNumber string OPTIONEEL Telefoonnummer van de eindgebruiker
emailAddress string OPTIONEEL E-mailadres van de eindgebruiker
customerReference string OPTIONEEL Unieke referentie van de eindgebruiker, Maximaal 32 tekens, alphanumeriek.
customerTrust integer OPTIONEEL Geef aan of je de eindgebruiker vertrouwt, op een schaal van -10 tot 10. -10 is onbetrouwbaar, 10 is betrouwbaar.
address array OPTIONEEL
streetName string OPTIONEEL Straatnaam van de eindgebruiker
streetNumber string OPTIONEEL Huisnummer van de eindgebruiker
streetNumberExtension string OPTIONEEL Toevoeging huisnummer
zipCode string OPTIONEEL Postcode van de eindgebruiker
city string OPTIONEEL Woonplaats van de eindgebruiker
countryCode string OPTIONEEL Landcode volgens ISO 3166 (tweelettercode). Je vindt een overzicht op https://admin.pay.nl/data/countries.
invoiceAddress array OPTIONEEL
initials string OPTIONEEL Voornaam / initialen van de persoon die de factuur ontvangt
lastName string OPTIONEEL Achternaam van de persoon die de factuur ontvangt
gender string OPTIONEEL Geslacht van de persoon die de factuur ontvangt. M: man, F: vrouw
streetName string OPTIONEEL Straatnaam van de persoon die de factuur ontvangt
streetNumber string OPTIONEEL Huisnummer van de persoon die de factuur ontvangt
streetNumberExtension string OPTIONEEL Toevoeging huisnummer van de persoon die de factuur ontvangt
zipCode string OPTIONEEL Postcode van de persoon die de factuur ontvangt
city string OPTIONEEL Woonplaats van de persoon die de factuur ontvangt
countryCode string OPTIONEEL Landcode volgens ISO 3166 (tweelettercode) van de persoon die de factuur ontvangt. Je vindt een overzicht op . https://admin.pay.nl/data/countries
company array OPTIONEEL
name string OPTIONEEL Naam van het bedrijf
cocNumber string OPTIONEEL KvK van het bedrijf
vatNumber string OPTIONEEL BTW nummer van het bedrijf
countryCode string OPTIONEEL Landcode volgens ISO 3166 (tweelettercode) waar het bedrijf is gevestigd. Je vindt een overzicht op https://admin.pay.nl/data/countries
saleData Image array OPTIONEEL bekijk array
invoiceDate string OPTIONEEL Datum van de factuur (DD-MM-YYYY)
deliveryDate string OPTIONEEL Verwachte leverdatum (DD-MM-YYYY) - In geval van ticketing datum evenement. Indien meerdaags, eerste dag meesturen.
orderData array OPTIONEEL
Image array OPTIONEEL Array met bestelde producten
productId string OPTIONEEL Het interne product ID binnen jouw systeem (max. 25 karakters).
productType string OPTIONEEL Type van de orderregel met de volgende mogelijke waarden: ARTICLE, SHIPPING, HANDLING, DISCOUNT
description string OPTIONEEL Omschrijving van het bestelde product
price integer OPTIONEEL Productprijs in centen, dus € 3,50 is 350.
quantity integer OPTIONEEL Aantal bestelde producten met het betreffende product ID
vatCode string OPTIONEEL BTW code, mogelijke waarden: H: high, N: zero, L: low
vatPercentage string OPTIONEEL BTW percentage, bv: 21.00 of 6.00

Response

Response code: Transactie achteraf betaalmethode starten

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
   "request":{
      "result":"1",
      "errorId":"",
      "errorMessage":""
   },
   "endUser":{
      "blacklist":"0"
   },
   "transaction":{
      "transactionId":"807986149Xb9005b",
      "paymentURL":"https://safe.pay.nl/afterpay?orderId=807986149Xb9005b&profileID=739",
      "popupAllowed":"0",
      "paymentReference":"6000 0008 0798 6149"
   }
}

In dit response voorbeeld zie je het resultaat van een transactie van € 1,- die gestart is voor verkooplocatie SL-1234-5678 voor betaaloptie Riverty.

Als resultaat ontvang je o.a een paymentURL (ook wel issuerURL). Dit is de URL waar je de eindgebruiker naar toe dient te sturen zodat de transactie kan worden betaald.


5.6. OrderData

Image
Scherm eindgebruiker

Het is mogelijk om extra order- en productdata door te geven. Deze informatie wordt gebruikt voor:

  • Je kan snel zoeken op producten (artikelcode, artikelomschrijving) via de quicksearch functionaliteit in het dashboard.
  • Je kan snel zoeken op klantgegevens (naam, adres, postcode, woonplaats, telefoonnummer, e-mailadres) via de quicksearch in het dashboard.
  • Je kan achteraf betaalopties gebruiken zoals Riverty, Klarna, iDEAL in3 en Billink.
  • De informatie kan worden gebruikt bij de fraudeprotectie.
  • Je komt in geval van PayPal in aanmerking voor verkopersbescherming
  • Bij gebruik van de Second Chance module worden de productgegegevens in de klant e-mail getoond om de conversie te verhogen

Eindgebruiker

Object Omschrijving
initials Voornaam / intitialen van de eindgebruiker
lastName Achternaam van de eindgebruiker
gender M: man, F: vrouw
dob Geboortedatum in het formaat dd-mm-yyyy
phoneNumber Telefoonnummer van de eindgebruiker
emailAddress E-mailadres van de eindgebruiker, indien je digitale diensten met verhoogd risico verkoopt, dien je enkel uit te leveren op dit e-mailadres
streetName Straatnaam van de eindgebruiker
streetNumber Huisnummer van de eindgebruiker
zipCode Postcode van de eindgebruiker
city Woonplaats van de eindgebruiker
countryCode Landcode volgens ISO 3166 (tweelettercode).
customerReference Unieke waarde ter herkenning van jouw klant. Enkel alphanummerieke tekens. Bijvoorbeeld 123456 of A32B9230AA
customerTrust Waarde tussen de -10 en 10 die je toevoegt aan de betrouwbaarheid van de klant.

Verkoopgegevens

Object Omschrijving
invoiceDate Datum van de factuur (YYYY-MM-DD)
deliveryDate Verwachte leverdatum (YYYY-MM-DD)

Via de plugin of hosted solution

In de meeste plugins of hosted solutions het doorsturen van de klantdata optioneel en met een eenvoudige vink te activeren.

Via zelfbouw (API / SDK)

Je kan bij het starten van de transactie de gegevens doorgeven.

5.7. ProductData

Het doorgeven van productdata is van essentieel belang voor een goede en veilige transactieverwerking. Sommige betaalopties vereisen het toevoegen van productgegevens in verband met het overnemen van de facturen. Andere betaalmethoden in combinatie met bepaalde productcategorieën verhogen het risico op frauduleuze transacties. Het voeden van correcte Productdata aan het Payment Platform van PAY. zorgt ervoor dat de anti-fraudemonitoring optimaal functioneert en conversie optimaliseert terwijl het risico op fraude en chargebacks wordt geminimaliseerd.

Productdata wordt net zoals OrderData maximaal 13 maanden bewaard.

productData Array

Object Omschrijving
productId Het interne product-ID binnen jouw systeem
description Omschrijving van het product
productType Type van de orderregel met de volgende mogelijke waarden: ARTICLE, SHIPPING, HANDLING, DISCOUNT zie hieronder voor meer mogelijkheden.
price Productprijs in centen, dus € 3,50 is 350
quantity Aantal bestelde producten van het desbetreffende product-ID
vatCode BTW code, mogelijke waarden H: high, N: zero, L: low
vatPercentage BTW-percentage

Beschikbare productTypes per regel


Object Omschrijving
Image
 ARTICLE Artikel / product.
Image
 ARTICLE_H Hoog risico product (mobiele telefoon, laptop).
Image
 VOUCHER Gratis artikel of prijsverlaging die een waarde vertegenwoordigd.
Image
 GIFTCARD Kaart die eenmalig is in te wisselen (gemiddeld frauderisico).
Image
 EMONEY Hoger risico digitale waardedrager zoals (iTunes/steam/paysafecard etc.).
Image
 TOPUP Opwaardering van een bestaand account of wallet waarbij een gebruiker slechts 1 account kan openen. Voor tijdelijke accounts: gebruik EMONEY.
Image
 TICKET Ticket voor evenement, festival, museum of theater.
Image
 CRYPTO Digitale valuta, zoals BitCoin, Ethereum of andere altcoin.
Image
 IDENTITY Betaling ter bevestiging van een extern account.
Image
 INVOICE Betaling van een factuur, voor reeds geleverd diensten of producten.
Image
 DOWNLOAD Digitale overdracht van een bestand.
Image
 VIRTUAL Digitaal product, bewaard op de server van de ondernemer (bijvoorbeeld: asset binnen een game).
Image
 CREDIT Creditfactuur of product (van een eerdere order).
Image
 HANDLING Administratie- of handelingskosten.
Image
 PAYMENT Betalingskosten.
Image
 SHIPPING Verzendkosten.
Image
 DISCOUNT Algemene korting.
Image
 ROUNDING Door PAY. toegevoegde regel indien het totaal van de orderregels afwijkt van het ordertotaal.

5.8. Transaction:STATUS

Als je enkel de status van een transactie wil controleren dan kan je gebruik maken van de API Transaction::status

Authenticatie

Basic Authentication

Authenticatie van de API Transaction::status vindt plaats middels HTTP Basic Authentication.

Request

Request code: Transactie status

curl --request POST \
  --url https://rest-api.pay.nl/v13/Transaction/status/json\
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'transactionId=1198491141Xc70580'

In dit request voorbeeld vragen we de status op van transactie '1198491141Xc70580'.

Parameters

Parameter Type Omschrijving
transactionId string VERPLICHT Transactiecode zoals verstrekt bij het starten van de transactie

Response

Response: Transactie status

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "request": {
    "result": "1",
    "errorId": "",
    "errorMessage": ""
  },
  "paymentDetails": {
    "transactionId": "EX-1234-5678-9100",
    "orderId": "1198491141Xc70580",
    "paymentProfileId": "10",
    "state": "100",
    "stateName": "PAID",
    "amountOriginal": {
      "value": "995",
      "currency": "EUR",
    },
    "amount": {
      "value": "995",
      "currency": "EUR",
    },
    "amountPaidOriginal": {
      "value": "995",
      "currency": "EUR",
    },
    "amountPaid": {
      "value": "995",
      "currency": "EUR",
    },
    "amountRefundOriginal": {
      "value": "0",
      "currency": "EUR",
    },
    "created": "2019-01-31 12:34:56",
    "identifierName": "T. Testname",
    "identifierPublic": "NL12RABO123456789",
    "identifierHash": "f646d4e51aa88a3d5cda8d55034c22bedcc04161c",
    "startIpAddress": "101.99.98.97",
    "completedIpAddress": "101.99.98.97",
    "orderNumber": ""
  }
}

In dit response voorbeeld zie je als resultaat de status van transactie '1198491141Xc70580'.

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result boolean 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
paymentDetails Image array bekijk array   Array met informatie over de transactie
transactionId string
orderId string
paymentProfileId string
state integer
stateName string
amountOriginal array
value integer
currency string
amount array
value integer
currency string
amountPaidOriginal array
value integer
currency string
amountPaid array
value integer
currency string
amountRefundOriginal array
value integer
currency string
Image array Array met refunds
value integer
currency string
created string
identifierName string
identifierPublic string
identifierHash string
startIpAddress string
completedIpAddress string
orderNumber string

5.9. Transaction:INFO

Als je alle informatie van een transactie wil opvragen dan gebruik je de API Transaction::info of een SDK. Als resultaat ontvang je vanzelfsprekend de status van de transactie, maar ook de volgende gegevens:

  • Informatie over de verbinding zoals gebruikte IP-adressen, host en return URL.
  • Gegevens m.b.t de eindgebruiker zoals naam, IBAN, afleveradres, factuuradres.
  • Productgegevens, mits deze zijn meegegeven bij het starten van de transactie.
  • Betalingsgegevens zoals status, bedrag, valuta en de gebruikte betaaloptie.

De informatie die je terug krijgt verschilt per betaaloptie en is tevens afhankelijk van de data die je meegeeft tijdens het starten van een transactie.

Authenticatie

Basic Authentication

Authenticatie van de API Transaction::info vindt plaats middels HTTP Basic Authentication.

Request

Request code: Transactie informatie

curl --request POST \
  --url https://rest-api.pay.nl/v13/Transaction/info/json \
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'transactionId=798491141Xc70580'

In dit request voorbeeld vragen we de details op van transactie '798491141Xc70580'.

Parameters

Paramater Type Omschrijving
transactionId string VERPLICHT Transactie code zoals verstrekt bij het starten van de transactie

Response

Response: Transactie informatie

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "request": {
    "result": "1",
    "errorId": "",
    "errorMessage": ""
  },
  "connection": {
    "trust": "10",
    "country": "NL",
    "city": "Amsterdam",
    "locationLat": "52.379189",
    "locationLon": "4.899431",
    "browserData": "",
    "ipAddress": "101.99.98.97",
    "countryName": "Netherlands",
    "blacklist": "0",
    "host": "ip.hostname.nl",
    "orderIpAddress": "101.99.98.97",
    "orderReturnURL": "https://www.demoshop.com/return",
    "merchantCode": "M-1234-5678",
    "merchantName": "Demo Merchant"
  },
  "enduser": {
    "initials": "T",
    "lastName": "Testname",
    "gender": "M",
    "phoneNumber": "0031-6-12345678",
    "emailAddress": "test@gmail.com",
    "language": "NL",
    "address": {
      "streetName": "Teststreet",
      "streetNumber": "10",
      "zipCode": "1234 AB",
      "city": "Amsterdam",
      "countryCode": "NL",
      "streetNumberExtension": ""
    },
    "invoiceAddress": {
      "initials": "K",
      "lastName": "Jansen",
      "streetName": "Secondstreet",
      "streetNumber": "15",
      "zipCode": "2345 CD",
      "city": "Haarlem",
      "countryCode": "NL",
      "gender": "",
      "streetNumberExtension": ""
    },
    "accessCode": "",
    "dob": "",
    "bankAccount": "",
    "iban": "",
    "bic": "",
    "sendConfirmMail": "",
    "confirmMailTemplate": "",
    "customerReference": "",
    "customerTrust": ""
  },
  "saleData": {
    "orderData": [
      {
        "productId": "1",
        "productType": "ARTICLE",
        "description": "First product",
        "price": "80",
        "quantity": "1",
        "vatCode": "H",
        "vatPercentage": "21",
        "discount": "0"
      },
      {
        "productId": "101",
        "productType": "SHIPPING",
        "description": "Shipping costs",
        "price": "20",
        "quantity": "1",
        "vatCode": "H",
        "vatPercentage": "21",
        "discount": "0"
      }
    ],
    "deliveryDate": "21-04-2017",
    "invoiceDate": "23-04-2017"
  },
  "paymentDetails": {
    "amount": "100",
    "currenyAmount": "100",
    "paidAmount": "100",
    "paidCurrenyAmount": "100",
    "paidBase": "100",
    "paidCosts": "0",
    "paidCostsVat": "0",
    "paidCurrency": "EUR",
    "paidAttemps": "1",
    "paidDuration": "0",
    "description": "My first creditcard order",
    "processTime": "56",
    "state": "100",
    "stateName": "PAID",
    "stateDescription": "Paid",
    "exchange": "",
    "storno": "0",
    "paymentOptionId": "706",
    "paymentOptionSubId": "0",
    "secure": "1",
    "secureStatus": "Y",
    "identifierName": "T. Testname",
    "identifierPublic": "456353******0123",
    "identifierHash": "456353******0123",
    "cardExpire": "2018-12",
    "customerKey": "f646d4e51aa88a3d5cda8d55034c22bedcc04161c",
    "serviceId": "SL-1234-5678",
    "serviceName": "Demoshop Pay.nl",
    "serviceDescription": "Demowebshop Pay.nl",
    "created": "2017-04-21 10:59:57",
    "modified": "2017-04-21 11:00:53",
    "paymentMethodId": "4",
    "paymentMethodName": "Transacties ",
    "paymentMethodDescription": "Pay Per Transaction",
    "paymentProfileName": "Visa Mastercard",
    "cardBrand": "VISA",
    "cardType": "CREDIT",
    "cardCountryCode": "NL"
  },
  "statsDetails": {
    "tool": "",
    "info": "",
    "object": "",
    "extra1": "",
    "extra2": "",
    "extra3": "",
    "promotorId": "0",
    "transferData": "",
    "paymentSessionId": "798491141"
  },
  "stornoDetails": {
    "stornoId": "",
    "stornoAmount": "",
    "bankAccount": "",
    "iban": "",
    "bic": "",
    "city": "",
    "datetime": "",
    "reason": "",
    "emailAddress": ""
  }
}

In dit response voorbeeld ziet u als resultaat de details van transactie '798491141Xc70580'.

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result boolean 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
errorMessage string Als er een foutmelding is opgetreden dan vind je hier de omschrijving
connection Image array bekijk array   Array met informatie over het resultaat van de verbinding
trust integer Betrouwbaarheidsindicator tussen -10 en 10
country string Landcode volgens ISO 3166 (tweelettercode) gebaseerd op het IP-adres. Je vindt een overzicht op https://admin.pay.nl/data/countries
city string Woonplaats van de eindgebruiker gebaseerd op het IP-adres
locationLat string Latitude coordinaten van de locatie van de gebruiker gebaseerde op het IP-adres
locationLon string Longitude coordinaten van de locatie van de gebruiker gebaseerde op het IP-adres
browserData string Details van de browser gespecificeerd via de API Transaction start
ipAddress string IP-adres dat gebruikt is tijdens de betaling
blacklist integer Geef aan of de eindgebruiker op de blacklist voorkomt. 0: Niet op blacklist, 1: Op blacklist voor merchant, 2: Op blacklist voor alle merchants
host string Host adres van de eindgebruiker
orderIpAddress string IP-adres tijdens het aanmaken van de order
orderReturnURL string Return URL die gebruikt is bij de transactie
merchantCode string Unieke code van de merchant waarvoor de transactie is gestart, startend met een 'M-' gevolgd door 8 cijfers
merchantName string Naam van de merchant waarvoor de transactie is gestart
ensuser Image array bekijk array   Array met informatie over de eindgebruiker
accessCode string Accesscode van de klant (beschikbaar bij enkele modules)
language string Taal van de eindgebruiker, NL voor Nederlands, EN voor Engels
initials string Voornaam / initialen van de eindgebruiker
lastName string Achternaam van de eindgebruiker
gender string M: man, F: vrouw
dob string Geboortedatum in het formaat dd-mm-yyyy
phoneNumber string Telefoonnummer van de eindgebruiker
emailAddress string Emailadres van de eindgebruiker
bankaccount string Bankrekening van de eindgebruiker
iban string IBAN nummer van de eindgebruiker
bic string BIC code behorende bij de bankrekening van de eindgebruiker
sendConfirmMail boolean Bevestiging per e-mail bij iedere succesvolle betaling. True: Ja, False: Nee
sendConfirmMail string Het id van de mail template van PAY.
address array
streetName string Straatnaam van de eindgebruiker
streetNumber string Huisnummer van de eindgebruiker
zipCode string Postcode van de eindgebruiker
city string Woonplaats van de eindgebruiker
countryCode string Landcode volgens ISO 3166 (tweelettercode). Je vindt een overzicht op https://admin.pay.nl/data/countries
invoiceAddress array
initials string Voornaam / initialen van de persoon die de factuur ontvangt
lastName string Achternaam van de persoon die de factuur ontvangt
gender string Geslacht van de persoon die de factuur ontvangt. M: man, F: vrouw
streetName string Straatnaam van de persoon die de factuur ontvangt
streetNumber string Huisnummer van de persoon die de factuur ontvangt
zipCode string Postcode van de persoon die de factuur ontvangt
city string Postcode van de persoon die de factuur ontvangt
countryCode string Landcode volgens ISO 3166 (tweelettercode) van de persoon die de factuur ontvangt. Je vindt een overzicht op https://admin.pay.nl/data/countries
saleData Image array bekijk array   Array met informatie over de bestelde producten
invoiceDate string Datum van de factuur (YYYY-MM-DD)
deliveryDate string Verwachte leverdatum (YYYY-MM-DD)
orderData array
Image array Array met bestelde producten
productId integer Het interne product ID binnen jouw systeem
description string Omschrijving van het bestelde product
price integer Productprijs in centen, dus € 3,50 is € 350,-
quantity integer Aantal bestelde producten met het betreffende product ID
vatCode string BTW code, mogelijke waarden: H: high, N: zero, L: low
paymentDetails Image array bekijk array   Array met informatie over de betalingsgegevens
amount string Bedrag van de sessie
currencyAmount string Betaald bedrag in de gebruikte valuta
paidAmount string Betaald bedrag
paidCurrenyAmount string
paidBase string Basisbedrag zonder de kosten
paidCosts string Betaalde kosten door de eindgebruiker exclusief BTW
paidCostsVat string BTW tarief voor kosten
paidCurreny string Valuta gebruikt bij de betaling. Je vindt een overzicht van de valuta's op https://admin.pay.nl/data/currencies
paidAttemps string Aantal pogingen
paidDuration string Duur, bij telefoongesprekken
description string
processTime string Tijd verstreken tussen start betaling en afronding
state string Status van de betaling, betaalstatus 100 is betaald
exchange string Resultaat van de exchange call. -1: failed, 0: niet aangeroepen / niet van toepassing, 1: correct
storno string 0: transactie niet gestorneerd, 1: transactie gestorneerd
paymentOptionId string Interne ID van de betaaloptie
paymentOptionSubId string Interne ID van de sub betaaloptie
secure string 1 of 0 (indien een betaling extra zekerheden heeft, bijvoorbeeld bij 3D Secure, ApplePay of een gebruikt paypal account dat geverifieerd is)
secureStatus string secureStatus: Y = Ja A = Poging, maar niet geslaagd. N = Nee
identifierName string
identifierPublic string Kenmerk van de betaler zoals weer te geven aan eindgebruiker
identifierHash string Kenmerk van de betaler (telefoonnummer, bankrekening, creditcard)
customerKey string Kenmerk van de betaler (telefoonnummer, bankrekening, creditcard)
cardExpire string
serviceId string ID van de dienst / webshop waarvoor de betaling is verricht
serviceName string Naam van de dienst / webshop waarvoor de betaling is verricht
serviceDescription string Omschrijving van de dienst / webshop waarvoor de betaling is verricht
created string
modified string
paymentMethodId string
paymentMethodName string
paymentMethodDescription string
paymentProfileName string
cardBrand string
cardType string
cardCountryCode string
stornoDetails Image array bekijk array   Array met informatie over een eventuele stornering
stornoId string ID van de stornering
stornoAmount string Bedrag van de stornering
bankAccount string Rekeningnummer (deprecated)
iban string IBAN nummer van de rekeninghouder t.b.v de storno
bic string BIC code van de rekeninghouder t.b.v de storno
city string Woonplaats van de rekeninghouder t.b.v de storno
datetime string Stornering uitgevoerd: (YYYY-MM-DD HH:II:SS)
reason string Reden van de stornering
emailAddress string Hier wordt stornering bevestiging naar toe gezonden
statsDetails Image array bekijk array   Array met informatie over de statistische gegevens
paymentSessionId string Het id van de betaalsessie
tool string Tool statistieken waarde
info string Info statistieken waarde
promotorId string Het ID van de promotor (webmaster)
extra1 string Vrije extra 1 waarde
extra2 string Vrije extra 2 waarde
extra3 string Vrije extra 3 waarde
transferData string Vrije transferData waarde
object string vrije object waarde

Vanwege het grote aantal parameters worden de arrays beperkt weergegeven. Klik op de button 'bekijk array' om de volledige array te bekijken.

5.10. Transaction:DETAILS

Als je alle data van een transactie op wil vragen dan gebruikt je de API Transaction::details In het geval van een multipayment (deelbetaling) ontvang je een array met alle gerelateerde transacties.

Authenticatie

Basic Authentication

Authenticatie van de API Transaction::details vindt plaats middels HTTP Basic Authentication.

Request

Request code: Transactie details

curl --request POST \
  --url https://rest-api.pay.nl/v14/Transaction/details/json\
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'transactionId=1198491141Xc70580'

In dit request voorbeeld vragen we de details op van transactie '1198491141Xc70580'.

Parameters

Paramater Type Omschrijving
transactionId string VERPLICHT Transactie code zoals verstrekt bij het starten van de transactie
entranceCode string OPTIONEEL Unieke code gerelateerd aan de transactie

Response

Response: Transactie details

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "request": {
    "result": "1",
    "errorId": "",
    "errorMessage": ""
  },
  "paymentDetails": {
    "transactionId": "EX-1234-5678-9100",
    "orderId": "1198491141Xc70580",
    "orderNumber": "",
    "paymentProfileId": "10",
    "paymentProfileName": "iDEAL",
    "state": "100",
    "stateName": "PAID",
    "language": "NL",
    "startDate": "1564437405",
    "completedDate": "1564437443",
    "startIpAddress": "101.99.98.97",
    "completedIpAddress": "101.99.98.97",
    "amountOriginal": {
      "value": "995",
      "currency": "EUR"
    },
    "amount": {
      "value": "995",
      "currency": "EUR"
    },
    "amountPaidOriginal": {
      "value": "995",
      "currency": "EUR"
    },
    "amountPaid": {
      "value": "995",
      "currency": "EUR"
    },
    "amountRefundOriginal": {
      "value": "0",
      "currency": "EUR"
    },
    "amountRefund": {
      "value": "0",
      "currency": "EUR"
    },
    "transactionDetails": {
       "item": {
         "transactionId": "EX-1234-5678-9100",
         "orderId": "1198491141Xc70580",
         "reportingId": "RT-1142-5039-9200",
         "state": "100",
         "stateName": "PAID",
         "startDate": "1564437405",
         "completedDate": "1564437443",
         "paymentProfileId": "10",
         "paymentProfileName": "iDEAL",
         "identifierName": "T. Testname",
         "identifierType": "IBAN",
         "identifierPublic": "NL**RABO1234**789",
         "identifierHash": "f646d4e51aa88a3d5cda8d55034c22bedcc04161c"
      }
    }
  }
}

In dit response voorbeeld zie je als resultaat de details van transactie '1198491141Xc70580'.

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result boolean 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
errorMessage string Als er een foutmelding is opgetreden dan vind je hier de melding
paymentDetails Image array bekijk array Array met informatie over de transactie
transactionId string Het unieke ID van de transactie startend met EX-
orderId string Unieke ID van de order
orderNumber string Uniek interne order ID van de order
paymentProfileId string Interne ID van de betaaloptie
paymentProfileName string Naam van de betaaloptie
state integer Status van de betaling, betaalstatus 100 is betaald
stateName string Naam van de status: PAID, CANCEL, DENIED of PENDING
language string Taal van het betaalscherm waarin de betaling is afgerekend
startDate string Unix timestamp waarop de transactie is gestart
completedDate string Unix timestamp waarop de transactie is afgerond
startIpAddress string IP-adres vanwaar de transactie is gestart
completedIpAddress string IP-adres vanwaar de transactie is afgerond
amountOriginal array
value integer Bedrag van de transactie in de valuta waarvoor deze is gestart
currency string Valuta waarin de transactie is gestart
amount array
value integer bedrag van de transactie in EUR waarvoor deze is gestart
currency string Gebruikte valuta is EUR
amountPaidOriginal array
value integer Bedrag van de transactie dat is afgerekend in de valuta
currency string Valuta waarin de transactie is afgerekend
amountPaid array
value integer Bedrag van de transactie dat is afgerekend in EUR
currency string Gebruikte valuta is EUR
amountRefundOriginal array
value integer Bedrag in de valuta dat is teruggeboekt
currency string Valuta gebruikt bij het teruggeboekt bedrag
amountRefund array
value integer Bedrag in EUR dat is teruggeboekt
currency string Gebruikte valuta is EUR
transactionDetails aray Array met alle gerelateerde transacties. In het geval van een multipayment (deelbetaling) kunnen dit meerdere transacties zijn.
item aray
transactionId string Het unieke ID van de transactie startend met EX-
orderId string Unieke ID van de order
reportingId string
state string Status van de betaling, betaalstatus 100 is betaald
stateName string Naam van de status: SUCCES, CANCEL, DENIED of PENDING
startDate string Unix timestamp waarop de transactie is gestart
completedDate string Unix timestamp waarop de transactie is afgerond
paymentProfileId string Interne ID van de betaaloptie
paymentProfileName string Naam van de betaaloptie
identifierName string Naam van de betaler
identifierType string Type betaling, bv IBAN
identifierPublic string Geanonimiseerd kenmerk van de betaler
identifierHash string Hash van het kenmerk van de betaler (telefoonnummer, bankrekening, creditcard)
amount array
value integer Bedrag in centen
currency string Gebruikte valuta bij de betaling

5.11. Transaction:APPROVE

Transacties met de status verify 85 kunnen na controle worden goedgekeurd middels de API Transaction::approve

Basic Authentication

Authenticatie van de API Transaction::approve vindt plaats middels HTTP Basic Authentication.

Request

Request code: Restitutie aanmaken

curl --request POST \
  --url https://rest-api.pay.nl/v13/Transaction/approve/json \
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'orderID=1098491152Xc70580'

In dit request voorbeeld keuren we transactie met order ID '1098491152Xc70580' goed.

Parameters

Paramater Type Omschrijving
orderId string VERPLICHT Order ID zoals verstrekt bij het starten van de transactie

Response

Response: Transactie goedkeuren

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "request": {
    "result": "1",
    "errorId": "",
    "errorMessage": ""
  },
  "message": "Transaction approved"
}

In dit response voorbeeld ziet u het resultaat van transactie '1098491152Xc70580' die is goedgekeurd.

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result string 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
errorMessage string Als er een foutmelding is opgetreden dan vind je hier de omschrijving
message string Geeft aan of de transactie succesvol goedgekeurd is

5.12. Transaction:DECLINE

Transacties met de status verify 85 kunnen na controle worden afgekeurd middels de API Transaction::decline

Basic Authentication

Authenticatie van de API Transaction::decline vindt plaats middels HTTP Basic Authentication.

Request

Request code: Transactie afkeuren

curl --request POST \
  --url https://rest-api.pay.nl/v13/Transaction/decline/json \
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'orderID=1098491152Xc70580'

In dit request voorbeeld keuren we transactie met order ID '1098491152Xc70580' af.

Parameters

Paramater Type Omschrijving
orderId string VERPLICHT Order ID zoals verstrekt bij het starten van de transactie

Response

Response: Transactie afkeuren

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "request": {
    "result": "1",
    "errorId": "",
    "errorMessage": ""
  },
  "message": "Transaction denied"
}

In dit response voorbeeld ziet u het resultaat van transactie '1098491152Xc70580' die is afgekeurd.

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result string 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
errorMessage string Als er een foutmelding is opgetreden dan vind je hier de omschrijving
message string Geeft aan of de transactie succesvol afgekeurd is

5.13. Transaction:CAPTURE (volledig)

De transactiestatus authorize wordt gebruikt bij creditcard- of achteraf betaalopties (mits Delayed Capturing is ingeschakeld). Als een transactie de status Authorize heeft is er een additionele actie vereist om deze te converteren naar betaalde transactie.

Transacties met de status authorize 95 kunnen na controle worden gecaptured middels de API Transaction::capture

Basic Authentication

Authenticatie van de API Transaction::capture vindt plaats middels HTTP Basic Authentication.

Request

Request code: Transactie capturen

curl --request POST \
  --url https://rest-api.pay.nl/v16/Transaction/capture/json \
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'transactionId=1098491152Xc70580' \
  --data-urlencode 'tracktrace=DHL0123456789' \
  --data-urlencode 'amount=1995'

In dit request voorbeeld voeren we een volledige capture uit op een transactie met order ID '1098491152Xc70580'.

Parameters

Paramater Type Omschrijving
transactionId string VERPLICHT De EX-code of het order ID zoals verstrekt bij het starten van de transactie
products array OPTIONEEL Array met producten die gecaptured dienen te worden. De key van de Array is het artikelnummer, de value bevat het aantal producten van het artikelnummer dat gecaptured moet worden.
tracktrace string OPTIONEEL Sommige betaalopties vereisen een verzendbewijs. U kunt hier de Track & Trace code meegeven indien beschikbaar
amount integer OPTIONEEL Het bedrag in centen dat gecaptured dient te worden (in de valuta waarmee de transactie is gestart). Indien niet meegegeven wordt het gehele bedrag gecaptured.

Response

Response: Transactie capturen

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "request": {
    "result": "1",
    "errorId": "",
    "errorMessage": ""
  },
  "message": "Transaction captured"
}

In dit response voorbeeld ziet u het resultaat van transactie '1098491152Xc70580' die volledig is gecaptured.

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result string 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
errorMessage string Als er een foutmelding is opgetreden dan vind je hier de omschrijving
message string Geeft aan of de transactie succesvol gecaptured is

5.14. Transaction:CAPTURE (deel)

Naast een volledige capture is het ook mogelijk om een deel van de transactie te capturen. Dit kan op basis van een bedrag en/of product afhankelijk van de betaaloptie.

Betaaloptie Optie deelcapture
Riverty Op basis van bedrag en/of product
Klarna Enkel op basis van bedrag



Basic Authentication

Authenticatie van de API Transaction::capture vindt plaats middels HTTP Basic Authentication.

Request

Request code: Transactie capturen

curl --request POST \
  --url https://rest-api.pay.nl/v16/Transaction/capture/json \
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'transactionId=1498491152Xc70580' \
  --data-urlencode 'tracktrace=DHL0123456789' \
  --data-urlencode 'amount=1995' \
  --data-urlencode 'products[123]=1' \
  --data-urlencode 'products[456]=3'

In dit request voorbeeld capturen we een deel van de transactie met order ID '1498491152Xc70580'. De capture doen we op basis van producten.
We capturen 1 x artikelnummer '123' en 3 producten met artikelnummer '456'

Parameters

Paramater Type Omschrijving
transactionId string VERPLICHT De EX-code of het order ID zoals verstrekt bij het starten van de transactie
products array OPTIONEEL Array met producten die gecaptured dienen te worden. De key van de Array is het artikelnummer, de value bevat het aantal producten van het artikelnummer dat gecaptured moet worden.
tracktrace string OPTIONEEL Sommige betaalopties vereisen een verzendbewijs. U kunt hier de Track & Trace code meegeven indien beschikbaar
amount integer OPTIONEEL Het bedrag in centen dat gecaptured dient te worden (in de valuta waarmee de transactie is gestart). Indien niet meegegeven wordt het gehele bedrag gecaptured.

Response

Response: Transactie capturen

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "request": {
    "result": "1",
    "errorId": "",
    "errorMessage": ""
  },
  "message": "Transaction captured"
}

In dit response voorbeeld ziet u het resultaat van transactie '1498491152Xc70580' die voor een deel is gecaptured.

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result string 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
errorMessage string Als er een foutmelding is opgetreden dan vind je hier de omschrijving
message string Geeft aan of de transactie succesvol gecaptured is

5.15. Transaction:VOID

De transactiestatus authorize wordt gebruikt bij Creditcard of Achteraf betaalopties (mits Delayed Capturing is ingeschakeld). Als een transactie de status Authorize heeft en je wil de transactie annuleren dan is er een additionele actie vereist om de transactie te annuleren.

Transacties met de status authorize 95 kunnen geannuleerd worden middels de API Transaction::void

Basic Authentication

Authenticatie van de API Transaction::void vindt plaats middels HTTP Basic Authentication.

Request

Request code: Restitutie aanmaken

curl --request POST \
  --url https://rest-api.pay.nl/v13/Transaction/void/json \
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'orderID=1098491152Xc70580'

In dit request voorbeeld voiden (annuleren) we transactie met order ID '1098491152Xc70580'.

Parameters

Parameter Type Omschrijving
orderId string VERPLICHT Order ID zoals verstrekt bij het starten van de transactie

Response

Response: Transactie voided

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "request": {
    "result": "1",
    "errorId": "",
    "errorMessage": ""
  },
  "message": "Transaction voided"
}

In dit response voorbeeld ziet u het resultaat van transactie '1098491152Xc70580' die is gevoid.

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result string 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
errorMessage string Als er een foutmelding is opgetreden dan vind je hier de omschrijving
message string Geeft aan of de transactie succesvol gevoid is

5.16. Transaction:CANCEL

Transactions that have a status of pending can be CANCELLED by the following guidelines

Transactions with the status pending 20 implies that the payment is waiting for an action to change the exchange call status, naturally this type of transaction can be cancelled by using the Transaction::cancel API

Basic Authentication

Authentication of the Transaction::cancel API takes place through HTTP Basic Authentication.

Request

Request code: Cancel a transaction

curl --request POST \
      --url https://rest-api.pay.nl/v15/Transaction/cancel/xml\
      --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
      --header 'cache-control: no-cache' \
      --header 'content-type: application/x-www-form-urlencoded' \
      --data-urlencode 'orderID=1212967656X38e16'

In this request example we cancel the transaction with order ID '1212967656X38e16'.

Parameters

Parameter Type Description
transactionId string REQUIRED The order ID of the transaction
entranceCode string OPTIONAL Unique code related to the order.

Response

Response: Transaction cancelled

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
      "request": {
        "result": "1",
        "errorId": "",
        "errorMessage": ""
      },
      "transaction": {
        "statusAction": "CANCEL",
        "nextUrl": "demo.pay.nl/?orderId=1212967656X38e16&orderStatusId=-90&paymentSessionId=1212971292"
}

In this response example you see the result of transaction '1212967656X38e16' that has been cancelled.

200 application/json; charset=utf-8
Name Type Description
request array Array with information about the result of the request
result string 0: request failed, 1: request successful
errorId string If an error message has occurred, you will find the error code here
errorMessage string If an error message has occurred, you will find the description here
transaction string Indicates whether the transaction was successfully completed
statusAction string The status of the transaction.
nextUrl string The URL the customer can be forwarded to after the transaction.

5.17. Foutafhandeling

The following errors can occur with transaction API requests:

Errorcode ErrorMessage Info
PAY‑001 Transaction not found Wrong transactionId or transaction is archived.
PAY‑004 Service not found Calling the transaction API with a wrong ServiceId or in a wrong format (SL-####-####).
PAY‑404 Card not found
PAY‑405 Parameter 'paymentProfileId or amount' is invalid: One of them should be set No amount or paymentoption set.
PAY‑406 Transaction can't be cancelled, It's in a PAID, VERIFY or AUTHORISE state. Canceling by API can only be done with PENDING state.
PAY‑407 Boarding of Payment option (PAYMENT_OPTION_ID) is not completed for this sales location (SL-####-####) Transactions can only be started if a payment option is fully boarded.
PAY‑408 Payment option (PAYMENT_OPTION_ID) is not activated for this sales location (SL-####-####) or merchant (M-####-####) You can only start transactions if the Payment option is activated in the Sales location.
PAY‑409 Amount is not allowed (AMOUNT) The provided transaction amount is not allowed.
PAY‑410 Maximum amount (AMOUNT) exceeded for payment option (PAYMENT_OPTION_ID) The maximum transction amount for the used payment option is exceeded.
PAY‑411 There is no active reservation for this transaction ( (ORDERID)) The transaction cannot be captured as there is no active reservation.
PAY‑412 This Transactions( (ORDERID) is allready captured) The transaction has already been captured
PAY‑3002 Refund not successful because of an insufficient balance Balance should be sufficient to be able to refund.
PAY‑3003 Refund was not complete
PAY‑3008 Bank account holder name is not provided, log in to the PAY admin and enter the name of the bank account holder. SEPA refunds cannot be processed without a bank account holder name.

6. Card payments

Om een kaartbetaling te starten kunt u gebruik maken van de API Payment::authorize.

Authenticatie

Basic Authentication

Authenticatie van de API Payment::authorize vindt plaats middels HTTP Basic Authentication.

Request

Request code: kaartbetaling starten

curl --request POST \
  --url https://payment.pay.nl/v1/Payment/authorize/json\
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'transaction[type]=ecom'\
  --data-urlencode 'transaction[serviceId]=SL-1234-5678'\
  --data-urlencode 'transaction[amount]=100'\
  --data-urlencode 'transaction[currency]=EUR'\
  --data-urlencode 'transaction[description]=My first payment'\
  --data-urlencode 'transaction[reference]=TEST.210709461'\
  --data-urlencode 'transaction[expireDate]=1627689600'\
  --data-urlencode 'transaction[ipAddress]=10.20.30.40'\
  --data-urlencode 'transaction[language]=NL'\
  --data-urlencode 'transaction[finishUrl]=http://www,pay.nl/complete'\
  --data-urlencode 'transaction[exchangeUrl]=http://www,pay.nl/exchange'\
  --data-urlencode 'options[tokenization]=1'\
  --data-urlencode 'customer[firstName]=Robert'\
  --data-urlencode 'customer[lastName]=Van der Werf'\
  --data-urlencode 'customer[gender]=M'\
  --data-urlencode 'customer[dob]=1999-21-31'\
  --data-urlencode 'customer[phoneNumber]=0888866666'\
  --data-urlencode 'customer[emailAddress]=robert@pay.nl'\
  --data-urlencode 'customer[address][streetName]=Kopersteden'\ 
  --data-urlencode 'customer[address][streetNumber]=10'\ 
  --data-urlencode 'customer[address][streetNumberExtension]=A'\ 
  --data-urlencode 'customer[address][zipCode]=7547TK'\ 
  --data-urlencode 'customer[address][city]=Enschede'\ 
  --data-urlencode 'customer[address][state]=OV'\ 
  --data-urlencode 'customer[address][countryCode]=NL'\ 
  --data-urlencode 'customer[invoice][firstName]=Robert'\ 
  --data-urlencode 'customer[invoice][lastName]=Van der Werf'\ 
  --data-urlencode 'customer[invoice][gender]=M'\ 
  --data-urlencode 'customer[invoice][address][streetName]=Kopersteden'\ 
  --data-urlencode 'customer[invoice][address][streetNumber]=10'\ 
  --data-urlencode 'customer[invoice][address][streetNumberExtension]=A'\ 
  --data-urlencode 'customer[invoice][address][zipCode]=7547TK'\ 
  --data-urlencode 'customer[invoice][address][city]=Enschede'\ 
  --data-urlencode 'customer[invoice][address][state]=OV'\ 
  --data-urlencode 'customer[invoice][address][countryCode]=NL'\ 
  --data-urlencode 'order[deliveryDate]='\
  --data-urlencode 'order[invoiceDate]='\
  --data-urlencode 'order[products][0][id]=TEST_01'\
  --data-urlencode 'order[products][0][type]=ARTICLE'\
  --data-urlencode 'order[products][0][description]=Caramels sweet roll'\
  --data-urlencode 'order[products][0][amount]=199'\
  --data-urlencode 'order[products][0][quantity]=2'\
  --data-urlencode 'order[products][0][vatPercentage]=21'\
  --data-urlencode 'order[products][1][id]=TEST_02'\
  --data-urlencode 'order[products][1][type]=ARTICLE'\
  --data-urlencode 'order[products][1][description]=Cookie tart sugar'\
  --data-urlencode 'order[products][1][amount]=649'\
  --data-urlencode 'order[products][1][quantity]=1'\
  --data-urlencode 'order[products][1][vatPercentage]=21'\
  --data-urlencode 'stats[extra1]=Free variable 1'\
  --data-urlencode 'stats[extra2]=Free variable 2'\
  --data-urlencode 'stats[extra3]=Free variable 3'\
  --data-urlencode 'payment[method]=card'\
  --data-urlencode 'payment[card][number]=1234567812345678'\
  --data-urlencode 'payment[card][expire_month]=01'\
  --data-urlencode 'payment[card][expire_year]=2025'\
  --data-urlencode 'payment[card][cvc]=123'\
  --data-urlencode 'payment[card][name]=R. van der Werf'\ 
  --data-urlencode 'payment[card][type]=cit'\
  --data-urlencode 'payment[auth][cryptogram]=ABc ... eF='\
  --data-urlencode 'payment[auth][dsTransactionId]=b2fbc353-1234-1324-1234-b8fe2deff658"'\
  --data-urlencode 'payment[auth][version]=2.1.0'\
  --data-urlencode 'payment[auth][type]=challenged'\
  --data-urlencode 'payment[auth][eci]=05'

In dit request starten we een kaartbetaling van 1,00 EUR voor service ID SL-1234-5678

Parameters

Parameter Type Omschrijving
transaction array VERPLICHT
type string VERPLICHT Mogelijke waarde ecom. Andere waarden worden op een later moment toegevoegd.
serviceId string VERPLICHT Jouw verkooplocatie start met 'SL-' gevolgd door 8 cijfers. Je vindt een overzicht van jouw verkooplocatie(s) op https://admin.pay.nl/websites
amount string VERPLICHT Bedrag in centen, dus €3,50 is 350.
currency string VERPLICHT Valuta volgens ISO 4217 (drielettercode). Indien leeg wordt EUR gebruikt. Je vindt een overzicht op https://admin.pay.nl/data/currencies
description string VERPLICHT Omschrijving van de order (maximaal 32 tekens)
reference string VERPLICHT Unieke referentie van de eindgebruiker. Maximaal 32 tekens, alphanumeriek.
expireDate string VERPLICHT Verloopdatum van de transactie in het formaat: dd-mm-yyyy HH:ii:ss (31-12-2017 22:33:44). Maximale verloopdatum is +4 weken.
ipAddress string VERPLICHT IP-adres van gebruiker. Let op dat je niet jouw eigen server IP meestuurt, bijvoorbeeld bij het gebruik van een loadbalancer. Zie https://github.com/paynl/sdk/ voor een voorbeeld.
language string VERPLICHT Taal van de eindgebruiker, NL voor Nederlands en EN voor Engels
finishUrl string VERPLICHT URL waar de bezoeker naar wordt doorgestuurd als de betaling is voltooid
exchangeUrl string VERPLICHT De URL voor het afleveren van de statussen, ook wel webhook of IPN genoemd.
options array VERPLICHT
tokenization string VERPLICHT 1 = tokeniseren, -1 = transactie niet tokeniseren, 0 = volgt payment setting via PAY.
customer array VERPLICHT
firstName string VERPLICHT Voornaam van de eindgebruiker
lastName string VERPLICHT Achternaam van de eindgebruiker
gender string VERPLICHT M: man, F: vrouw
dob string VERPLICHT Geboortedatum in het formaat dd-mm-yyyy
phoneNumber string VERPLICHT Telefoonnummer van de eindgebruiker
emailAddress string VERPLICHT E-mailadres van de eindgebruiker
company array VERPLICHT
coc string VERPLICHT KvK nummer van het bedrijf
name string VERPLICHT Naam van het bedrijf
vat string VERPLICHT BTW nummer van het bedrijf
address array VERPLICHT
streetName string VERPLICHT Straatnaam van de eindgebruiker
streetNumber string VERPLICHT Huisnummer van de eindgebruiker
streetNumberExtension string VERPLICHT Toevoeging huisnummer
zipCode string VERPLICHT Postcode van de eindgebruiker
city string VERPLICHT Woonplaats van de eindgebruiker
state string VERPLICHT Provincie van de eindgebruiker
countryCode string VERPLICHT Landcode volgens ISO 3166 (tweelettercode) van het afleveradres. Je vindt een overzicht op https://admin.pay.nl/data/countries
invoice array VERPLICHT
firstName string VERPLICHT Voornaam / initialen van de persoon die de factuur ontvangt
lastName string VERPLICHT Achternaam van de persoon die de factuur ontvangt
gender string VERPLICHT Geslacht van de persoon die de factuur ontvangt. M: man, F: vrouw
company array VERPLICHT
cocNumber string VERPLICHT Kvk nummer van de onderneming op het factuuradres
vatNumber string VERPLICHT BTW nummer van de onderneming op het factuuradres
address array VERPLICHT
streetName string VERPLICHT Straatnaam van de persoon die de factuur ontvangt
streetNumber string VERPLICHT Huisnummer van de persoon die de factuur ontvangt
streetNumberExtension string VERPLICHT Toevoeging huisnummer van de persoon die de factuur ontvangt
zipCode string VERPLICHT Postcode van de persoon die de factuur ontvangt
city string VERPLICHT Woonplaats van de persoon die de factuur ontvangt
state string VERPLICHT Provincie van de persoon die de factuur ontvangt
countryCode string VERPLICHT Landcode volgens ISO 3166 (tweelettercode) van de persoon die de factuur ontvangt. Je vindt een overzicht op https://admin.pay.nl/data/countries
order array VERPLICHT
deliveryDate string VERPLICHT Verwachte leverdatum (YYYY-MM-DD) - In geval van ticketing datum evenement. Indien meerdaags, eerste dag meesturen.
invoiceDate string VERPLICHT Datum van de factuur (YYYY-MM-DD)
products array VERPLICHT Array met bestelde producten
[] array VERPLICHT
id string VERPLICHT Het interne product ID binnen jouw systeem
type string VERPLICHT Type van de orderregel met de volgende mogelijke waarden: ARTICLE, SHIPPING, HANDLING, DISCOUNT
description string VERPLICHT Omschrijving van het bestelde product
amount string VERPLICHT Productprijs in centen, dus €3,50 is 350.
quantity string VERPLICHT Aantal bestelde producten met het betreffende product ID
vatPercentage string VERPLICHT BTW percentage, bv: 21.00 of 6.00
stats array VERPLICHT
extra1 string VERPLICHT Vrije variabele 'extra1' die kan worden getraceerd in de statistieken. (advies: ID van de order)
extra2 string VERPLICHT Vrije variabele 'extra2' die kan worden getraceerd in de statistieken. (advies: klant referentie)
extra3 string VERPLICHT Vrije variabele 'extra3' die kan worden getraceerd in de statistieken
info string VERPLICHT Variabele 'info' die kan worden getraceerd in de statistieken
tool string VERPLICHT Variabele 'tool' die kan worden getraceerd in de statistieken
payment array VERPLICHT
method string VERPLICHT Mogelijke waarde card. Andere waarden worden op een later moment toegevoegd.
card array VERPLICHT
number string VERPLICHT Kaartnummer
expire_month string VERPLICHT maand van de vervaldatum van de kaart, bijvoorbeeld 01 voor januari (MM)
expire_year string VERPLICHT Jaar van de vervaldatum van de kaart (YYYY)
cvc string VERPLICHT CVC code van de kaart
name string VERPLICHT Naam kaarthouder
type string VERPLICHT Mogelijke waarde: cit
auth array VERPLICHT
cryptogram string VERPLICHT Hash die u terugkrijgt van de 3D secure
dsTransactionId string VERPLICHT Transaction ID die u terugkrijgt van de 3D secure
version string VERPLICHT Versie van de 3D secure die is gebruikt
type string VERPLICHT Type 3D secure gebruikt bij de betaling: Frictionless of Challenged
eci string VERPLICHT Geeft het resultaat weer van de authenticatie op 3D secure transacties.

Response: Starten kaartbetaling

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "request": {
    "result": "1",
    "errorId": "",
    "errorMessage": ""
  },
  "paymentDetails": {
    "transactionId": "EX-2275-5639-0960",
    "orderId": "1663939079Xc8b48",
    "paymentProfileId": "706",
    "state": "20",
    "stateName": "PENDING",
    "amountOriginal": {
      "value": "995",
      "currency": "EUR",
    },
    "amount": {
      "value": "995",
      "currency": "EUR",
    },
    "amountPaidOriginal": {
      "value": "995",
      "currency": "EUR",
    },
    "amountPaid": {
      "value": "995",
      "currency": "EUR",
    },
    "amountRefundOriginal": {
      "value": "0",
      "currency": "EUR",
    },
    "created": "1629908001",
    "identifierName": "R. van der Werf",
    "identifierPublic": "123456******4321",
    "identifierHash": "00b6 ... 3e8",
    "startIpAddress": "10.20.30.40",
    "completedIpAddress": "10.20.30.40",
    "reference": "210709461"
    "payment": {
      "bankCode": "0",
      "bankMessage": "Insufficient funds/over credit limit (Cvv: M)",
      "cvcCheck": "M",
      "threeDs": "FALSE",
      "approvalCode": "ZLJI2Q",
      "schemeTransactionId": "",
      "avsResult": "",
    },
    "tokenization": {
      "id": "VY-1234-1234-1234",
      "hash": "d04b98f48...16e7807340fa",
      "expirationDate": "2512",
      "label": "************2587",
  }  
}

Response

In dit response voorbeeld zie je het resultaat van het starten van een kaartbetaling van 1,00 EUR voor service ID SL-1234-5678

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result boolean 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
paymentDetails Image array bekijk array   Array met informatie over de transactie
transactionId string
orderId string
paymentProfileId string
state integer
stateName string
amountOriginal array
value integer
currency string
amount array
value integer
currency string
amountPaidOriginal array
value integer
currency string
amountPaid array
value integer
currency string
amountRefundOriginal array
value integer
currency string
Image array Array met refunds
value integer
currency string
created string
identifierName string
identifierPublic string
identifierHash string
startIpAddress string
completedIpAddress string
reference string

7. Dataverplichtingen per categorie

Afhankelijk van de branche waarin je opereert en welke producten of diensten je aanbiedt via PAY, kan het zijn dat er een aantal verplichte variabelen verwacht worden bij het starten van een transactie. Bij sommige productcategorieën is er een verhoogd risico op fraude. Om onze anti-fraudemodule zo goed mogelijk te voeden met de juiste data, zijn een aantal variabelen verplicht gesteld. Een overzicht per categorie vind je hieronder.

7.1. Toegangsbewijzen en ticketing

Voor ticketplatformen waarbij als agent óf Merchant of Record (MOR) wordt geopereerd, vereist PAY. de volgende variabelen in de transaction::start API:

Parameter Type Omschrijving
transaction array VERPLICHT
description string VERPLICHT Naam van het event waarvoor de tickets worden aangeschaft.
statsData array VERPLICHT
extra1 string VERPLICHT Organisator ID - eigen referentie (klantnummer of hash) naar de onderneming die het evenement organiseert.
extra2 string VERPLICHT Event ID - eigen referentie (eventnummer of hash) naar het event zelf.
extra3 string OPTIONEEL IBAN van de organisator indien er gebruik wordt gemaakt van Payouts vanuit het boeksaldo.
enduser array OPTIONEEL
emailAddress string AANBEVOLEN Het e-mailadres waarop de e-tickets worden uitgeleverd.
customerReference string AANBEVOLEN Unieke referentie van de eindgebruiker. Maximaal 32 tekens, alphanumeriek.
customerTrust string AANBEVOLEN Waarde tussen -10 en 10. Met deze variabele kan er extra sturing aan de VERIFY module worden gegeven waardoor events met een hoger frauderisico scherper gemonitord kunnen worden.
saleData array VERPLICHT
invoiceDate string VERPLICHT Datum van de factuur (DD-MM-YYYY).
deliveryDate string VERPLICHT Datum evenement. Indien meerdaags, eerste dag meesturen. (DD-MM-YYYY).
orderData Image array VERPLICHT bekijk array
Image array VERPLICHT Array met bestelde producten
product-ID string VERPLICHT Het interne product-ID binnen jouw systeem.
productType string VERPLICHT Type van de orderregel met de volgende mogelijke waarden: TICKET, SHIPPING, HANDLING, PAYMENT, DISCOUNT.
description string VERPLICHT Omschrijving van het bestelde product.
price integer VERPLICHT Productprijs in centen, dus €3,50 is 350.
quantity integer VERPLICHT Aantal bestelde producten met het betreffende product-ID.
vatCode string VERPLICHT BTW code, mogelijke waarden: H: high, N: zero, L: low.
vatPercentage string VERPLICHT BTW percentage, bv: 21.00 of 6.00.

7.2. Cadeaukaarten, vouchers en beltegoed

Voor merchants die beltegoed, cadeaukaarten of andere prepaid betaalmiddelen verkopen, vereist PAY. de volgende variabelen:

Parameter Type Omschrijving
transaction array VERPLICHT
description string VERPLICHT Omschrijving dient kaarttype en waarde te bevatten. Bijvoorbeeld: "paysafecard 25 EUR".
enduser array OPTIONEEL
customerReference string AANBEVOLEN Unieke referentie van de eindgebruiker, maximaal 32 tekens, alphanumeriek.
emailAddress string VERPLICHT Het e-mailadres van de eindgebruiker, in geval van levering van digitale vouchers of cadeaukaarten is dit tevens het afleveradres.
customerTrust string AANBEVOLEN Waarde tussen -10 en 10. Met deze variabele kan er extra sturing aan de VERIFY module gegeven worden waardoor bijvoorbeeld nieuwe klanten scherper gemonitord kunnen worden.
saleData array VERPLICHT
orderData Image array VERPLICHT bekijk array
Image array VERPLICHT Array met bestelde vouchers en/of cadeaukaarten en eventuele transactie-, administratie- of handelingskosten.
product-ID string OPTIONEEL Het interne product-ID binnen jouw systeem.
productType string VERPLICHT Type van de orderregel met de volgende mogelijke waarden: VOUCHER, GIFTCARD, EMONEY, TOPUP, HANDLING, PAYMENT, DISCOUNT, CREDIT.
description string VERPLICHT Omschrijving van de bestelde cadeaukaarten of vouchers.
price integer VERPLICHT Productprijs in centen, dus €3,50 is 350.
quantity integer VEPRLICHT Aantal bestelde producten met het betreffende product-ID.
vatCode string OPTIONEEL BTW code, mogelijke waarden: H: high, N: zero, L: low.
vatPercentage string OPTIONEEL BTW percentage, bv: 21.00 of 6.00.

7.3. Cryptocurrencies

Voor platformen die handelen in Cryptocurrencies vereist PAY. de volgende variabelen:

Parameter Type Omschrijving
transaction array VERPLICHT
description string VERPLICHT Omschrijving dient te verwijzen naar de Cryptomunt en het aantal te bevatten munten. Bijvoorbeeld: "Bitcoin 0.123". Bij de verificatie van een nieuw account dient de omschrijving "Verificatie Cryptoplatform" of "Verification Crypto Platform" te bevatten.
enduser array OPTIONEEL
customerReference string AANBEVOLEN Indien je een account aanmaakt voor een gebruiker die je verifieert, geef je een unieke referentie mee van de eindgebruiker. Maximaal 32 tekens, alphanumeriek.
emailAddress string AANBEVOLEN Het e-mailadres van de eindgebruiker.
customerTrust string AANBEVOLEN Waarde tussen -10 en 10. Indien de klant een niveau bereikt, overeenkomstig met het eigen risicobeleid, geef je deze informatie mee via de CustomerTrust. 0 voor de eerste gradatie. +1 voor elke volgende gradatie.
statsData array VERPLICHT
object string VERPLICHT Volledige hash van de wallet van de eindgebruiker waar de coins op gestort worden.
saleData array VERPLICHT
orderData Image array VERPLICHT bekijk array
Image array VERPLICHT Array met bestelde cryptocurrencies en eventuele transactie- administratie- of handelingskosten.
product-ID string OPTIONEEL Het interne product-ID binnen jouw systeem.
productType string VERPLICHT Type van de orderregel met de volgende mogelijke waarden: CRYPTO, IDENTITY, HANDLING, PAYMENT.
description string VERPLICHT Omschrijving van de bestelde cryptocoin(s).
price integer VERPLICHT Productprijs in centen, dus €3,50 is 350.
quantity integer OPTIONEEL Aantal bestelde producten met het betreffende product-ID.
vatCode string OPTIONEEL BTW code, mogelijke waarden: H: high, N: zero, L: low.
vatPercentage string OPTIONEEL BTW percentage, bv: 21.00 of 6.00.

7.4. Dataverplichting Technische partners en platformen

Voor Technische partners die een directe implementatie op de Transactie::start API hebben heeft PAY. een extra variabele beschikbaar voor tracking en eventuele debugging:

Parameter Type Omschrijving
statsData array  
object string VERPLICHT Naam van het platform of de technische partner, eventueel gevolgd door een pipeline met versienummers. Voorbeeld:
Magento PAY.-plugin versie | Magento versie | PHP Versie | free-field versie

8. Tokenisatie

Met behulp van de optie: 'Tokenisatie' worden automatisch de kaartgegevens van de betaler versleuteld opgeslagen binnen onze systemen. Je ontvangt vervolgens een token waarmee je een vervolgbetaling kan uitvoeren. Je hoeft dan niet opnieuw de kaartgegevens van jouw klant te vragen. Deze token kan vier soorten betalingen starten


  • Merchant inititated transaction
    Je bepaalt na ontvangst van een mandaat, wanneer en welk bedrag je afschrijft

  • Cardholder inititated transaction
    De kaarthouder voert een actie uit in een app of binnen jouw webomgeving waarna de betaling direct wordt afgeschreven en de status wordt teruggekoppeld naar de kaarthouder

  • MOTO transaction
    Er is een medewerker van het bedrijf die is ingelogd in de Admin van PAY. die de transactie uitvoert in opdracht van de kaarthouder

  • Doorlopende recurring transaction
    Periodieke afschrijving voor een lidmaatschap of donatie

  • Installment transaction
    Voor de afbetaling van een order

8.1. Tokenisatie proces

Image
De verschillende stappen van het betaalproces

Om een token te verkrijgen waarmee je een herhaaltransactie kan aanmaken, dien je eerst een standaard creditcard transactie aan te maken. Als tokenisatie voor jouw account is geactiveerd dan ontvang je de token via een exchange call waarmee je de vervolgtransactie kan uitvoeren.

Merchant Initiated Transaction (via: recurringId)

Indien je de VY-codes in jouw eigen database opslaat om op eigen initiatief een transactie uit te voeren, gebruik je de VY-code en een authenticatie token, behorende bij jouw merchant.

De parameter recurring_id start altijd met VY. Met dit ID kan je een herhaalbetaling starten, indien je op de API geautoriseerd bent met een authenticatieToken op basis van jouw bedrijf of persoonlijk account. Tevens heb je dit ID nodig om de gegevens van de token te bekijken, te wijzigen of indien je de token wilt verwijderen.

Cardholder Initiated Transaction (via: recurringToken)

Indien jouw klant zelf een aankoop uitvoert, dan gebruik je de recurringToken. Voor deze API is geen authenticatie nodig. Terugkoppeling van de status ontvang je door een exchange aanroep. Dit is geschikt voor in-app aankopen waarbij je de token niet wilt opslaan binnen jouw omgeving.

De parameter recurring_token is een HASH van 64 tekens. Met deze token kan je beperkte informatie over de kaarthouder ophalen om deze te tonen en kan je een herhaalbetaling toevoegen. Deze token kan ook gebruikt worden binnen een mobiele app of andere applicatie en kan zichtbaar zijn voor de gebruiker. De recurring_token is enkel te gebruiken voor betalingen (op verkooplocaties) binnen jouw onderneming of bij submerchant indien de eigenaar een Alliance aansluiting heeft.

8.2. Tokenisatie activeren

Om tokenisatie voor jouw account of verkooplocatie te activeren, dien je contact op te nemen met jouw accountmanager.

8.3. Transactie starten

Betaaloptie ID Naam
706 VISA / Mastercard

Om een token te verkrijgen waarmee je een herhaaltransactie kan starten, dien je eerst een standaard creditcardtransactie te starten. Je zou het voorbeeld kunnen gebruiken dat staat weergegeven bij 'Transactie starten. In dat geval geef je het paymentOptionId de waarde 706 mee (VISA / Mastercard). Als resultaat zou je dan een paymentURL krijgen die de bezoeker naar de betaalpagina stuurt waar de transactie kan worden afgerond.

In dit request voorbeeld starten we een transactie van €1,- voor verkooplocatie SL-1234-5678 met de betaalmethode creditcard (betaaloptie ID: 706)

Response

Response code: Creditcard transactie starten

HTTP/1.1
200 OK
Content-Type:
application/json;
charset=utf-8

{
   "request":{
      "result":"1",
      "errorId":"",
      "errorMessage":""
   },
   "endUser":{
      "blacklist":"0"
   },
   "transaction":{
      "transactionId":"805537292X770f55",
      "paymentURL":"https://3dsecure.pay.nl/start/805537292X770f55/3bcc24ede2dc03/NL",
      "popupAllowed":"0",
      "paymentReference":"6000 0008 0553 7292"
   }
}

In dit response voorbeeld zie je het resultaat van een transactie van € 1,- die gestart is voor verkooplocatie SL-1234-5678 voor betaaloptie VISA / MasterCard.

Transactie succesvol?

Als de klant de creditcard transactie succesvol afrond, ontvang je een token om een vervolgtransactie te kunnen starten. Je ontvangt deze token via de exchange call van de geslaagde transactie. Daarnaast vind je een overzicht van alle beschikbare tokens in het Admin Panel.

8.4. Exchange calls

Een communicatie- of exchange URL is een URL waar een script van jou staat om meldingen van onze servers te ontvangen. Bij alle typen betalingen geven onze servers meldingen aan jou door om de status van de betaling door te geven, bijvoorbeeld om aan te geven dat een recurring betaling succesvol is afgerond. Deze melding leveren wij dan af door het script op jouw exchange URL aan te roepen waarbij er een aantal parameters mee worden gegeven waarmee je de recurring betaling kan achterhalen en eventueel kan updaten in jouw systeem.

Het gehele exchange proces voor een normale online betaling wordt hier uitgebreid beschreven. Voor een exchange call van een recurring-opdracht gelden slechts enkele wijzigingen, die we hieronder toelichten.

Parameters

Bij het aanroepen van de exchange / communicatie URL stuurt PAY. de standaard POST / GET parameters mee zoals hier vermeld aangevuld met de parameters recurring_id en recurring_token

8.5. MIT (Merchant Initiated)

Als je een MIT (Merchant Initiated Transaction) wil uitvoeren, heb je het recurringId (VY-####-####-####) nodig en een token met voldoende rechten waarmee je de API Payment::authorize kan aanroepen.

Authenticatie

Basic Authentication

Authenticatie van de API Payment::authorize vindt plaats middels HTTP Basic Authentication.

Request

Request code: Herhaalde transactie aanmaken

curl --request POST \
  --url https://rest-api.pay.nl/v13/Transaction/byRecurringId/json \
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'recurringId=VY-1234-5678-9123 \
  --data-urlencode 'serviceId=SL-1234-5678' \
  --data-urlencode 'amount=995' \
  --data-urlencode 'description=My first recurring payment' \

In dit request voorbeeld starten we een herhaalde creditcard transactie van € 9,95 met token VY-1234-5678-9123

Parameters

Paramater Type Omschrijving
recurringId string VERPLICHT Het recurringId welke u ontvangt via de exchange call na een succesvolle creditcardbetaling, startend met 'VY-'
serviceId string VERPLICHT Uw verkooplocatie start met 'SL-' gevolgd door 8 cijfers. Je vindt een overzicht van jouw verkooplocatie(s) op https://admin.pay.nl/websites
amount integer VERPLICHT Bedrag in centen, dus € 3,50 is € 350,-
currency string OPTIONEEL Valuta volgens ISO 4217 (drielettercode), indien leeg wordt EUR gebruikt. Je vindt een overzicht op https://admin.pay.nl/data/currencies
description string OPTIONEEL Omschrijving van de recurring transactie
cvc string OPTIONEEL CVC code van de creditcard
statsData Image array OPTIONEEL bekijk array
promotorId integer OPTIONEEL Het ID van de promotor (webmaster)
info string OPTIONEEL Variabele 'info' die kan worden getraceerd in de statistieken
tool string OPTIONEEL Variabele 'tool' die kan worden getraceerd in de statistieken
extra1 string OPTIONEEL Vrije variabele 'extra1' die kan worden getraceerd in de statistieken. (advies: id van de order)
extra2 string OPTIONEEL Vrije variabele 'extra2' die kan worden getraceerd in de statistieken. (advies: klant referentie)
extra3 string OPTIONEEL Vrije variabele 'extra3' die kan worden getraceerd in de statistieken

Response

Response: Herhaalde transactie aanmaken

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
   "request":{
      "result":"1",
      "errorId":"",
      "errorMessage":""
   },
   "transaction":{
      "orderId":"105537291X770f36",
      "entranceCode":"1234abcd5678efgh",
      "orderDescription":"My first recurring payment",
      "amount":{
        "value":"995",
        "currency":"EUR"
      },
      "amountOriginal":{
        "value":"995",
        "currency":"EUR"
      },
      "amountPaid":{
        "value":"0",
        "currency":"EUR"
      },
      "amountPaidOriginal":{
        "value":"0",
        "currency":"EUR"
      }
   }
}

In dit response zie je het resultaat voor het aanmaken van een herhaalde transactie van € 9,95 met token VY-1234-5678-9123

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result string 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
errorMessage string Als er een foutmelding is opgetreden dan vind je hier de omschrijving
transaction array Array met informatie over de transactie
orderId string Unieke ID van de order
entranceCode string Unieke code gerelateerd aan de order
orderDescription string De omschrijving van de herhaalde transactie
amount array Gevraagd bedrag, in de basis currency van de merchant (indien gestart in GBP, wordt dit EUR)
value string Gevraagd bedrag in centen
currency string Valuta volgens ISO 4217 (drielettercode)
amountOriginal array Bedrag dat gevraagd is (trx:amount) in currency van de start. (indien gestart in GBP, is dit GBP)
value string Bedrag dat gevraagd is in centen
currency string Valuta volgens ISO 4217 (drielettercode)
amountPaid array Bedrag dat uitbetaald wordt aan de merchant. (deel dat echt reeds betaald is in de curreny van de merchant GPB wordt EUR)
value string Bedrag dat uitbetaald wordt in centen
currency string Valuta volgens ISO 4217 (drielettercode)
amountPaidOriginal array Bedrag dat betaald is door de klant, in de currency van de stats (Hoeveel GBP er betaald is)
value string Bedrag dat betaald is in centen
currency string Valuta volgens ISO 4217 (drielettercode)

8.6. CIT (Cardholder Initiated)

Als je een CIT (Cardholder Initiated Transaction) wil uitvoeren, heb je de recurringToken STRING(64) nodig. Deze ontvang je op basis van de exchange bij de eerste betaling. Transaction::byRecurringToken kan aanroepen.

Authenticatie

Geen authenticatie nodig

.

Request

Request code: Herhaalde transactie aanmaken

curl --request POST \
  --url https://rest-api.pay.nl/v13/Transaction/byRecurringToken/json \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'recurringToken=ABCDE12345 \
  --data-urlencode 'serviceId=SL-1234-5678' \
  --data-urlencode 'amount=995' \
  --data-urlencode 'description=My first recurring payment' \

In dit request voorbeeld starten we een herhaalde creditcard transactie van € 9,95 met token ABC12345

Parameters

Paramater Type Omschrijving
recurringToken string VERPLICHT De recurring token die je ontvangt via de exchange call na een succesvolle creditcardbetaling'
serviceId string VERPLICHT Uw verkooplocatie start met 'SL-' gevolgd door 8 cijfers. Je vindt een overzicht van uw verkooplocatie(s) op https://admin.pay.nl/websites
amount integer VERPLICHT Bedrag in centen, dus €3,50 is 350
currency string OPTIONEEL Valuta volgens ISO 4217 (drielettercode), indien leeg wordt EUR gebruikt. Je vindt een overzicht op https://admin.pay.nl/data/currencies
description string OPTIONEEL Omschrijving van de recurring transactie
cvc string OPTIONEEL CVC code van de creditcard
statsData Image array OPTIONEEL bekijk array
promotorId integer OPTIONEEL Het id van de promotor (webmaster)
info string OPTIONEEL Variabele 'info' die kan worden getraceerd in de statistieken
tool string OPTIONEEL Variabele 'tool' die kan worden getraceerd in de statistieken
extra1 string OPTIONEEL Vrije variabele 'extra1' die kan worden getraceerd in de statistieken. (advies: ID van de order)
extra2 string OPTIONEEL Vrije variabele 'extra2' die kan worden getraceerd in de statistieken. (advies: klant referentie)
extra3 string OPTIONEEL Vrije variabele 'extra3' die kan worden getraceerd in de statistieken

Response

Response: Herhaalde transactie aanmaken

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
   "request":{
      "result":"1",
      "errorId":"",
      "errorMessage":""
   },
   "transaction":{
      "orderId":"105537291X770f36",
      "entranceCode":"1234abcd5678efgh",
      "orderDescription":"My first recurring payment",
      "amount":{
        "value":"995",
        "currency":"EUR"
      },
      "amountOriginal":{
        "value":"995",
        "currency":"EUR"
      },
      "amountPaid":{
        "value":"0",
        "currency":"EUR"
      },
      "amountPaidOriginal":{
        "value":"0",
        "currency":"EUR"
      }
   }
}

In dit response zie je het resultaat voor het aanmaken van een herhaalde transactie van € 9,95 met token VY-1234-5678-9123

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result string 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
errorMessage string Als er een foutmelding is opgetreden dan vind je hier de omschrijving
transaction array Array met informatie over de transactie
orderId string Unieke ID van de order
entranceCode string Unieke code gerelateerd aan de order
orderDescription string De omschrijving van de herhaalde transactie
amount array Gevraagd bedrag, in de basis currency van de merchant (indien gestart in GBP, wordt dit euro)
value string Gevraagd bedrag in centen
currency string Valuta volgens ISO 4217 (drielettercode)
amountOriginal array Bedrag dat gevraagd is (trx:amount) in currency van de start. (indien gestart in GBP, is dit GBP)
value string Bedrag dat gevraagd is in centen
currency string Valuta volgens ISO 4217 (drielettercode)
amountPaid array Bedrag dat uitbetaald wordt aan de merchant. (deel dat echt reeds betaald is in de curreny van de merchant GPB wordt EUR)
value string Bedrag dat uitbetaald wordt in centen
currency string Valuta volgens ISO 4217 (drielettercode)
amountPaidOriginal array Bedrag dat betaald is door de klant, in de currency van de stats (Hoeveel GBP er betaald is)
value string Bedrag dat betaald is in centen
currency string Valuta volgens ISO 4217 (drielettercode)

9. Dynamic Payments

Met Dynamic Payments kan je dynamisch QR-codes genereren. Jouw bezoekers kunnen vervolgens een iDEAL betaling verrichten door het scannen van deze QR-code. De iDEAL QR-code als betaalmethode is geschikt voor een eindeloze range aan toepassingen. Je kan hem bijvoorbeeld aanbieden op jouw facturen of kassabonnen, in jouw webshop, jouw etalage, bij collectes of als alternatief voor jouw acceptgiro's.


Video Omschrijving

Dynamic Payments

Instructievideo: Wat zijn Dynamic Payments en hoe kan je het gebruiken?

Handige mogelijkheden bij PAY.

  • Met Dynamic Payments kan je het bedrag van een factuur na verzending verhogen bijvoorbeeld als de betaling te lang uitblijft of verlagen bijvoorbeeld wanneer je alsnog korting geeft. Zonder de QR-code aan te passen.
  • Je kan de betaalmogelijkheid blokkeren wanneer de betaling eenmaal is gedaan. Dat voorkomt dubbele overboekingen.
  • Het bedrag voor de betaling is vast te zetten zodat jouw klanten of debiteuren zich daar niet in kunnen vergissen. Of juist zo in te stellen dat de betaler het wel kan wijzigen of zelf invullen, bijvoorbeeld bij donaties. Eventueel voorzien van minimale en maximale waarden.
  • Je kan jouw klanten/donateurs laten kiezen voor eenmalige betaling of periodieke incasso.

9.1. Verkooplocatie instellen

Het is aan te raden om voor Dynamic Payments een aparte verkooplocatie aan te maken. Bij 'Exchange URL's' kan je dan kiezen voor de optie: Ja, een custom exchange URL gebruiken. Vervolgens voer je de exchange URL in zoals beschreven in 8.2 Exchange implementeren.

Image

9.2. Exchange implementeren

Voorbeeld: Exchange verzoek

# Aanroep communicatie URL vanuit PAY.
https://www.domain.com/exchange/?action=getOrder&uuid=bb196108-3490-4320-3132-313231323132

Response: Exchange verzoek

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "request": {
    "result": true,
    "errorId": "",
    "errorMessage": ""
  },
  "transaction": {
    "amount": "3132",
    "amountChangeable": "true",
    "amountMin": "3132",
    "amountMax": "4132",
    "finishUrl": "https://www.domain.com/complete/",
    "description": "Example",
    "orderNumber": "bb196108-3490-4320-3132-313231323132"   
    "statsData": {
      "extra1": "Extra1",
      "extra2": "Extra2",
      "extra3": "Extra3"
    },
  }
  "paymentProfileIdsAllowed": [
    {
      "id": "10",
      "costs": "0"
    },
    {
      "id": "436"
    }
  ]
}

Zodra de iDEAL QR-code wordt gescand, wordt er een URL op jouw server aangeroepen die de instellingen voor de betreffende betaling ophaalt. Deze aanroep noemen we een exchange call. Als PAY. jouw exchange URL aanroept met parameter action = getOrder dan dient de output te zijn met de onderstaande velden:

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result boolean false: request niet geslaagd, true: request geslaagd
errorId string Foutcode van een eventuele opgetreden foutmelding
errorMessage string Omschrijving van een eventuele opgetreden foutmelding
transaction array Array met informatie over de transactie
amount integer Het bedrag in centen dat je af wil laten rekenen, dus € 3,50 is 350
amountChangeable boolean Hiermee geef je aan of het bedrag na het scannen van de QR-code via de app gewijzigd mag worden. Dit is o.a van toepassing bij donaties.
amountMin integer Als het bedrag aangepast mag worden dan kan je hier aangeven wat het minimum bedrag in centen is.
amountMax integer Als het bedrag aangepast mag worden dan kan je hier aangeven wat het maximum bedrag in centen is.
finishUrl string URL waar de bezoeker naar wordt doorgestuurd als de betaling is voltooid
description string Omschrijving van de order (maximaal 32 tekens)
orderNumber string Het ID van de transactie in jouw eigen administratie.
statsData array
extra1 string Vrije variabele 'extra1' die kan worden getraceerd in de statistieken. (advies: ID van de order)
extra2 string Vrije variabele 'extra2' die kan worden getraceerd in de statistieken
extra3 string Vrije variabele 'extra3' die kan worden getraceerd in de statistieken
paymentProfileIdsAllowed array
Image array Array met beschikbare betaalopties. De betaalopties dienen vanzelfsprekend bij de verkooplocatie geactiveerd te zijn. Voor de iDEAL QR-code geef je betaaloptie: 10 mee.
id integer Interne ID van de betaaloptie waarvoor je een transactie wil starten. Je vindt een overzicht op https://admin.pay.nl/data/payment_profiles

9.3. UUID's genereren

Voorbeeld code: Encode UUID

<?php
require __DIR__ . '/vendor/autoload.php';

$UUID = \Paynl\DynamicUUID::encode(
    'SL-1234-5678',
    '<your-secret>',
    'Your reference'
);

echo $UUID;

Voorbeeld code: Decode UUID

<?php
require __DIR__ . '/vendor/autoload.php';

$uuid   = '<your-uuid>';
$secret = '<your-secret>';

try {
    $decoded = \Paynl\DynamicUUID::decode($uuid, $secret);
    var_dump($decoded);
} catch (\Paynl\Error\Error $e) {
    echo "Error: ".$e->getMessage();
}

Om gebruik te kunnen maken van Dynamic Payments moet je een UUID genereren. Een UUID is een gecodeerde hash van de volgende velden:

Paramater Omschrijving
serviceId Jouw verkooplocatie start met 'SL-' gevolgd door 8 cijfers. Je hebt deze verkooplocatie bij hoofdstuk 8.1 aangemaakt.
secret Je vindt de secret in de popup met details van de verkooplocatie. Ga hiervoor naar het tabblad Verkooplocaties in het Admin Panel en klik op de betreffende SL-code of op de link 'gegevens'.
Image

In de popup die nu wordt geopend vind je vervolgens de 'secret' terug:
Image
reference Vrij veld voor jouw eigen referentie die maximaal 16 karakters mag bevatten. Jouw eigen referentie zorgt er tevens voor dat de QR-code uniek wordt.

Handmatig een UUID genereren

Via https://qr.pisp.me/generate kan je handmatig een UUID genereren. Voer hiervoor het service ID, secret en reference veld in en klik op de button 'encode'.

Geautomatiseerd een UUID genereren

Als je regelmatig gebruik gaat maken van Dynamic Payments dan kan je gebruik maken van onze PHP SDK om geautomatiseerd een UUID te genereren.

Zoals eerder aangegeven, wordt het UUID als $_GET of $_POST variabele meegegeven aan de exchange call. Het is dus vrij eenvoudig om de QR-code dynamisch te maken. Je zou hierbij gebruik kunnen maken van de SDK decode functie om het service-ID en de eigen referentie te kunnen achterhalen.

9.4. iDEAL QR-code

Als je de UUID hebt aangemaakt dan kunnen we heel eenvoudig de iDEAL QR-code genereren:
<img src="https://ideal.pay.nl/qr/UUID" />

Deze URL zorgt dat de QR-code voorziet wordt van het iDEAL logo.
Indien je deze afbeelding zelf wil maken dan kan je hiervoor jouw eigen QR-code generator gebruiken. Je bent verplicht ter herkenning het iDEAL logo te plaatsen.

De te scannen data moet zijn:
https://qr6.ideal.nl/UUID

9.5. Het betaalproces

Image
De verschillende stappen in het betaalproces voor Dynamic Payments

Het betaalproces voor Dynamic Payments verloopt in verschillende stappen die in de afbeelding hiernaast worden weergegeven.

9.6. Hosted payment page

Wil je geen gebruik maken van de QR-code maar van een betaallink dan kan je gebruik maken van de volgende URL:
https://safe.pay.nl/dynamic/UUID

Deze hosted payment page beperkt zich niet alleen tot iDEAL maar geeft alle betaalopties weer die je bij de verkooplocatie hebt geselecteerd. Indien jouw exchange een paymentProfileIdsAllowed list heeft, worden enkel de betaalopties weergegeven uit deze lijst.

De hosted payment page maakt gebruik van de limiet filter.
Dit komt van pas bij bijvoorbeeld betaalmogelijkheden zoals iDEAL in3 waar het minimum limiet van een transactie € 100,- is.

Deze payment pagina wordt ook gebruikt bij sommige webshops zoals Shopify.

10. Restituties

Een restitutie (ook wel refund) is een terugbetaling van een (deel van een) transactie aan een eindgebruiker.

Binnen PAY. zijn er 2 type restituties beschikbaar

10.1. Op basis van transactie

Als je een bestaande transactie wilt terugboeken dan kan dit middels de API Refund::transaction.

Authenticatie

Basic Authentication

Authenticatie van de API Refund::transaction vindt plaats middels HTTP Basic Authentication.

Request

Request code: Refund transactie

curl --request POST \
  --url https://rest-api.pay.nl/v3/Refund/transaction/json\
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'transactionId=1198491141Xc70580'

In dit request voorbeeld refunden we het volledige bedrag van transactionId '1198491141Xc70580'.

Parameters

Paramater Type Omschrijving
transactionId string VERPLICHT Transactie code zoals verstrekt bij het starten van de transactie
amount integer OPTIONEEL Het bedrag dat gerefund moet worden in centen, dus €3,50 is 350
description string OPTIONEEL Omschrijving van de order (maximaal 32 tekens alphanummeriek en spaties)
processDate string OPTIONEEL De datum waarop de refund verwerkt moet worden. Volgens format dd-mm-yyyy (bijvoorbeeld: 25-09-2016). Dit werkt enkel voor IBAN refunds
products array OPTIONEEL Array van items die moeten worden terugbetaald (key: product ID, waarde: hoeveelheid)
fVatPercentage float OPTIONEEL Het BTW percentage dat op de refund van toepassing is. Dit is enkel toepasbaar op het bedrag, niet op producten in combinatie met de betaaloptie Riverty of Focum.
exchangeUrl string OPTIONEEL Custom exchange URL die de standaard exchange URL overschrijft
currency string OPTIONEEL De valuta waarmee de refund wordt gestart. Als de refund geen bedrag bevat, wordt het volledige bedrag terugbetaald in EUR.

Response: Transaction refunded

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "request": {
    "result": "1",
    "errorId": "",
    "errorMessage": ""
  },
  "refundedTransactions": {
    "orderId": "1098491152Xc70580",
    "amount": "995",
    "amountRefunded": "995",
    "voucherNumber": "6064 3642 1234 5678 123",
    "bankaccountNumber": "NL**RABO1234**789",
    "refundId": "RF-1234-5678-9100"
    },
      "failedTransactions": {
        "orderId": "",
        "amount": "",
        "refundAmount": "",
        "voucherNumber": "",
        "bankaccountNumber": "",
        "reason": ""
      }, 
  "amountRefunded": "995",
  "description": "refunded €9,95 succesfully"
}

Response

In dit response voorbeeld ziet u het resultaat van de volledige refund op transactie '1098491152Xc70580'.

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result boolean 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
errorMessage string Als er een foutmelding is opgetreden dan vind je hier de melding
refundedTransactions array De transacties die succesvol zijn terugbetaald
orderId string Het order-id van de gerestitueerde transactie
amount int Het originele bedrag van de refund
amountRefunded int Het bedrag dat gerefund is
voucherNumber string Het kaartnummer indien dit een refund is op een cadeaukaart
bankaccountNumber string Het IBAN rekeningnummer waarop de refund is verwerkt. Deze wordt gevuld als het een IBAN refund betrof.
refundId string Het ID van de refund, deze begint met 'RF-'. Deze zal worden gevuld als het een IBAN refund betrof.
failedTransactions array De transacties waarvoor geen refund verwerkt konden worden
orderId string Het order-id van de transactie
amount int Het originele bedrag van de refund
refundAmount int Het bedrag dat getracht werd terug te betalen
voucherNumber string Het kaartnummer indien dit een refund is op een cadeaukaart
bankaccountNumber string Het IBAN rekeningnummer waarop de refund is verwerkt. Deze wordt gevuld als het een IBAN refund betrof.
reason string De reden waardoor de transactie refund mislukt
amountRefunded int Het totale resitutiebedrag
description string Om omschrijving van hetgeen dat gerefund is

10.2. Op basis van IBAN (payout)

Naast het refunden van een transactie kun je ook een refund uitvoeren op basis van een IBAN nummer middels de API Refund::add. We noemen dit ook wel een externe refund of payout.

Authenticatie

Basic Authentication

Authenticatie van de API Refund::add vindt plaats middels HTTP Basic Authentication.

Request

Request code: Restitutie op basis van IBAN nummer

curl --request POST \
  --url https://rest-api.pay.nl/v3/Refund/add/json\
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'serviceId=SL-3490-4320' \
  --data-urlencode 'amount=350' \
  --data-urlencode 'bankAccountHolder=T. Testname' \
  --data-urlencode 'bankAccountNumber=NL54RABO123456789' \
  --data-urlencode 'orderId=1198491141Xc70580'

In dit request voorbeeld voeren we een restitutie (payout) uit van 3,50 EUR naar IBAN NL54RABO123456789

Parameters

Paramater Type Omschrijving
serviceId string VERPLICHT Jouw verkooplocatie start met 'SL-' gevolgd door 8 cijfers. Je vindt een overzicht van jouw verkooplocatie(s) op https://admin.pay.nl/websites
amount string VERPLICHT Het bedrag dat gerefund moet worden in centen, dus €3,50 is 350
bankAccountHolder string VERPLICHT De naam rekeninghouder behorende bij het IBAN nummer waarnaar de restitutie uitgevoerd dient te worden
bankAccountNumber string VERPLICHT Het IBAN waarnaar de restitutie (payout) uitgevoerd dient te worden
bankAccountBic string OPTIONEEL Het BIC nummer behorende bij het IBAN nummer waarnaar de restitutie uitgevoerd dient te worden
description integer OPTIONEEL Omschrijving van de terugboeking (maximaal 32 tekens alphanummeriek en spaties)
extra1 integer OPTIONEEL rije variabele 'extra1' die kan worden getraceerd in de statistieken
extra2 integer OPTIONEEL rije variabele 'extra2' die kan worden getraceerd in de statistieken
extra3 integer OPTIONEEL rije variabele 'extra3' die kan worden getraceerd in de statistieken
orderId integer OPTIONEEL Het order-id van de gerestitueerde transactie
currency integer OPTIONEEL De valuta waarin de refund wordt moet worden terugbetaald
processDate integer OPTIONEEL De datum waarop de refund verwerkt moet worden. Volgens format dd-mm-yyyy (bijvoorbeeld: 25-09-2016). Dit werkt enkel voor IBAN refunds

10.3. Exchange calls

In het geval van een terugbetaling, wordt er een exchange call uitgevoerd waarbij PAY. de communicatie URL op jouw server aanroept. Deze exchange call bevat een aantal parameters zodat je de betreffende refund eventueel in jouw eigen systeem kan updaten. Het gehele exchange proces wordt hier uitgebreid beschreven.

Parameters

Bij het aanroepen van de exchange / communicatie URL stuurt PAY. de standaard POST / GET parameters mee zoals hier vermeld aangevuld met de parameter refundId

Via het refund-ID kan je de details van een refund-opdracht ophalen via de API Refund::info

Momenten van aanroep

Voor een refund gelden de onderstaande momenten van aanroep:

Action Moment van aanroep
refund:add Deze notificatie ontvang je tijdens het aanroepen van de refund:API of indien er uit de Admin van PAY. een refund wordt aangemaakt. Zo blijft jouw systeem op de hoogte van refunds die vanaf externe platforms worden uitgevoerd.
refund:delete Na het verwijderen van een aangemaakte IBAN refund. Tot het moment dat een IBAN refund nog niet verwerkt is, kan deze nog worden verwijderd.
refund:received Vlak nadat een betaling is teruggeboekt. Bij achteraf betalen, cadeaukaarten en creditcard worden deze direct verwerkt. IBAN refunds worden in een batch geplaatst en worden 's ochtends rond 10:00 uur door de bank verwerkt.
refund:send Vlak nadat de refundbatch door de batch is verwerkt. Alleen van toepassing op IBAN refunds.
refund:declined Een aangemaakte refund is afgewezen voordat deze is verstuurd naar de bank, dit kan zijn op basis van foutieve data, een check via de sanctiewet etc.
refund:storno Een aangemaakte refund kon niet worden verwerkt. Een voorbeeld is een refund naar een IBAN nummer dat is opgeheven / geblokkeerd. Een bevestiging van de refund:storno wordt tevens gemaild naar medewerkers die operationele notificaties ontvangen.

11. Incasso

Binnen Europa is SEPA incasso een veel gebruikte betaalmethode. Incasso wordt vaak gebruikt voor doorlopende betalingen, maar kan ook eenmalig worden uitgevoerd. Door de mogelijkheid betalingen te laten plaatsvinden met een vooraf afgesproken frequentie, is incasso ook erg geschikt voor abonnementen en contributies.

11.1. Soorten incasso's

Naast de standaard eenmalige incasso biedt PAY. tevens herhaalde incasso's en flexibele incasso's aan waarmee je recurring betalingen kan uitvoeren.

  • Eenmalige incasso
    Bij deze vorm wordt één keer een bedrag van de rekening van de klant geïncasseerd.

  • Herhaalde incasso
    Bij deze vorm wordt er periodiek een vast bedrag van de rekening van de klant geïncasseerd. Dit kan bijvoorbeeld één keer per maand of kwartaal zijn. Deze vorm van incasseren is daarom uitermate geschikt voor abonnementen.

  • Flexibele incasso
    De flexibele mandaten zijn de meeste uitgebreide incassovorm. Je maakt hierbij eerst een mandaat aan dat je vervolgens kan gebruiken voor herhaalde incasso's. Je bent hierbij niet gebonden aan een vaste periode, een vast bedrag of omschrijving. Deze incassovorm is daarom uitermate geschikt als je variabele bedragen bij jouw klanten wil incasseren.

11.2. Mandaten en referenties

Eenmalige incasso

Image

Herhaalde incasso

Image
Meerdere referenties met vast bedrag / periode

Flexibele incasso

Image
Meerdere referenties met variabel bedrag / datums

Een incasso-opdracht bestaat uit een mandaat en een referentie. Binnen het platform van PAY. begint een mandaat altijd met IO- gevolgd door 12 cijfers. Een referentie begint met IL- gevolgd door 12 cijfers.

Het mandaat wordt naar de bank gestuurd om de incasso uit te kunnen voeren. Het mandaat van een eenmalige incasso is één keer geldig en levert één incasso (referentie) op. Bij herhaalde of flexibele incasso is er één mandaat waarmee meerdere incasso's (referenties) kunnen worden uitgevoerd.

Eenmalige incasso

Image

Herhaalde incasso

Meerdere referenties met vast bedrag / periode
Image

Flexibele incasso

Meerdere referenties met variabel bedrag / datums
Image

11.3. Limieten

Het gebruik van incasso is aan een aantal limieten gebonden:

  • Aantal opdrachten
    Je kan niet meer dan één incasso-opdracht per uniek IBAN-nummer per dag aanmaken.

  • Geldigheidsduur mandaat
    Een mandaat is geldig tot 36 maanden na de laaste incasso-opdracht.

  • Hoogte van het bedrag
    Er gelden limieten voor het te incasseren bedrag per incasso-opdracht. Deze limiet is o.a. afhankelijk van jouw branche, in het verleden behaalde resultaten en jouw relatie met PAY.

  • Maximum totaalbedrag per dag
    Er geldt een maximum bedrag per dag voor alle incasso's die je door PAY. laat verwerken. Deze limiet is o.a. afhankelijk van jouw branche, in het verleden behaalde resultaten en jouw relatie met PAY.

11.4. Incasso activeren

Vanaf het Professional pakket heb je de mogelijkheid om gebruik te maken van de betaaloptie incasso. Je dient deze echter eerst te activeren en in te stellen bij een verkooplocatie. In de documentatie voor merchant vind je een stap voor stap beschrijving.

11.5. Eenmalige incasso

Middels een eenmalige incasso wordt een bedrag eenmalig van de rekening van de klant / eindgebruiker afgeschreven. Je kan een eenmalige incasso via de API DirectDebit::debitAdd of een SDK aanmaken.

Authenticatie

Basic Authentication

Authenticatie van de API DirectDebit::debitAdd vindt plaats middels HTTP Basic Authentication.

Request

Request code: Eenmalige incasso aanmaken

curl --request POST \
  --url https://rest-api.pay.nl/v3/DirectDebit/debitAdd/json \
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'serviceId=SL-1234-5678'
  --data-urlencode 'amount=995'
  --data-urlencode 'bankaccountHolder=K. Jansen'
  --data-urlencode 'bankaccountNumber=NL01RABO123456789'

In dit request voorbeeld starten we een eenmalige incasso van € 9,95 voor IBAN-nummer NL01RABO123456789 van rekeninghouder K. Jansen.

Parameters

Paramater Type Omschrijving
serviceId string VERPLICHT Jouw verkooplocatie start met 'SL-' gevolgd door 8 cijfers. Je vindt een overzicht van jouw verkooplocatie(s) op https://admin.pay.nl/websites
amount integer VERPLICHT Bedrag in centen, dus € 3,50 is 350
bankaccountHolder string VERPLICHT Naam van de klant
bankaccountNumber string VERPLICHT IBAN nummer van de klant
processDate string OPTIONEEL De datum waarop de incasso moet worden verwerkt (dd-mm-yyyy)
description string OPTIONEEL Omschrijving van de incasso-opdracht
currency string OPTIONEEL Valuta volgens ISO 4217 (drielettercode). Indien leeg dan wordt EUR gebruikt. Je vindt een overzicht op https://admin.pay.nl/data/currencies
exchangeUrl string OPTIONEEL De exchange URL die bij deze incasso moet worden gebruikt
ipAddress string OPTIONEEL IP-adres van van de klant
email string OPTIONEEL E-mailadres van de klant
promotorId integer OPTIONEEL Het id van de promotor (webmaster)
tool string OPTIONEEL Variabele 'tool' die kan worden getraceerd in de statistieken
info string OPTIONEEL Variabele 'info' die kan worden getraceerd in de statistieken
object string OPTIONEEL Variabele 'object' die kan worden getraceerd in de statistieken
extra1 string OPTIONEEL Variabele 'extra1' die kan worden getraceerd in de statistieken
extra2 string OPTIONEEL Variabele 'extra2' die kan worden getraceerd in de statistieken
extra3 string OPTIONEEL Variabele 'extra3' die kan worden getraceerd in de statistieken

Response

Response: Eenmalige incasso aanmaken

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "request": {
    "result": "1",
    "errorId": "",
    "errorMessage": ""
  },
  "result": "IO-0000-3186-9140"
}

In dit response ziet u het resultaat van de aangemaakte eenmalige incasso-opdracht.

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result string 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
errorMessage string Als er een foutmelding is opgetreden dan vind je hier de omschrijving
result string Het mandaat ID van de betreffende incasso, startend met 'IO-'. Hiermee kan je de details / status van de incasso ophalen

Als de eenmalige incasso succesvol is aangemaakt, vind je deze terug in het Admin Panel overzicht met geplande eenmalige incasso's. Je kan een geplande incasso nog wijzigen of verwijderen. Zodra de incasso verwerkt is, wordt deze verplaatst naar de pagina uitgevoerde incasso's.

11.6. Herhaalde incasso

Wil je periodiek een vast bedrag incasseren van jouw klanten dan is de optie ''herhaalde incasso's'' de oplossing. Deze incassovorm staat ook wel bekend als recurring of automatische incasso. Herhaalde incasso's zijn zeer eenvoudig in het gebruik: je hoeft ze slechts één keer per klant in te stellen.

Authenticatie

Basic Authentication

Authenticatie van de API DirectDebit::recurringAdd vindt plaats middels HTTP Basic Authentication.

Request

Request code: Herhaalde incasso aanmaken

curl --request POST \
  --url https://rest-api.pay.nl/v3/DirectDebit/recurringAdd/json \
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'serviceId=SL-1234-5678'
  --data-urlencode 'amount=995'
  --data-urlencode 'bankaccountHolder=K. Jansen'
  --data-urlencode 'bankaccountNumber=NL01RABO123456789'
  --data-urlencode 'intervalValue=1'
  --data-urlencode 'intervalPeriod=2'

In dit request voorbeeld starten we een herhaalde incasso van € 9,95 voor IBAN-nummer NL01RABO123456789 van rekeninghouder K. Jansen. Deze incasso zal iedere maand (intervalPeriod) worden uitgevoerd.

Parameters

Paramater Type Omschrijving
serviceId string VERPLICHT Jouw verkooplocatie start met 'SL-' gevolgd door 8 cijfers. Je vindt een overzicht van jouw verkooplocatie(s) op https://admin.pay.nl/websites
amount integer VERPLICHT Bedrag in centen, dus € 3,50 is 350
bankaccountHolder string VERPLICHT Naam van de klant
bankaccountNumber string VERPLICHT IBAN nummer van de klant
intervalValue string VERPLICHT Bepaalt samen met de variabele intervalPeriode de herhalingstermijn
intervalPeriod string VERPLICHT 1: week, 2: maand, 3:kwartaal, 4: half jaar, 5: jaar, 6: dag
intervalQuantity integer OPTIONEEL Het aantal herhalingen waarna de incasso-opdracht moet worden gestopt
bankaccountBic string OPTIONEEL BIC code van de klant
processDate string OPTIONEEL De datum waarop de incasso moet worden verwerkt (dd-mm-yyyy)
description string OPTIONEEL Omschrijving van de incasso-opdracht
currency string OPTIONEEL Valuta volgens ISO 4217 (drielettercode). Indien leeg wordt EUR gebruikt. Je vindt een overzicht op https://admin.pay.nl/data/currencies
exchangeUrl string OPTIONEEL De exchange URL die bij deze incasso moet worden gebruikt
ipAddress string OPTIONEEL IP-adres van van de klant
email string OPTIONEEL E-mailadres van de klant
promotorId integer OPTIONEEL Het id van de promotor (webmaster)
tool string OPTIONEEL Variabele 'tool' die kan worden getraceerd in de statistieken
info string OPTIONEEL Variabele 'info' die kan worden getraceerd in de statistieken
object string OPTIONEEL Variabele 'object' die kan worden getraceerd in de statistieken
extra1 string OPTIONEEL Variabele 'extra1' die kan worden getraceerd in de statistieken
extra2 string OPTIONEEL Variabele 'extra2' die kan worden getraceerd in de statistieken
extra3 string OPTIONEEL Variabele 'extra3' die kan worden getraceerd in de statistieken

Herhaling instellen

Via de parameters IntervalValue en intervalPeriod kan je de tijd aangeven tussen de uitgevoerde incasso's. Dit wordt toegelicht aan de hand van de gegevens in de onderstaande tabel.


IntervalValue intervalPeriod Incassering
1 1 Iedere week
2 1 Iedere 2 weken
2 2 Iedere 2 maanden
1 3 Ieder kwartaal
1 4 Ieder half jaar
1 5 Ieder jaar
3 6 Elke 3 dagen

De variabele processDate bepaalt de startdatum. Stel dat je kiest voor een maandelijkse incasso met een initiële processDate van 10-01-2018, dan zal de volgende herhaalde incasso automatisch worden uitgevoerd op 10-02-2018. Als je geen processDate meegeeft dan zal de incasso zo snel mogelijk worden verwerkt (vaak de volgende werkdag).

Via de variabele intervalQuantity kan je eventueel aangeven na hoeveel herhalingen de incasso-opdracht moet stoppen.

Response

Response: Herhaalde incasso aanmaken

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "request": {
    "result": "1",
    "errorId": "",
    "errorMessage": ""
  },
  "result": "IO-0000-4567-8910"
}

In dit response zie je het resultaat van de aangemaakte herhaalde incasso-opdracht.

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result string 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
errorMessage string Als er een foutmelding is opgetreden dan vind je hier de omschrijving
result string Het mandaat ID van de betreffende incasso, startend met 'IO-'. Hiermee kan je de status van de bijbehorende incasso's ('IL'-code) bepalen.

Een overzicht van alle herhaalde incasso mandaten vind je terug op de pagina herhaalde incasso's. Zodra de incasso verwerkt is, vind je deze (referentie) terug bij de uitgevoerde incasso's.

11.7. Flexibele incasso

De flexibele incasso is de meest uitgebreide incassovorm die wordt aangeboden door PAY. De merchant maakt gebruik van één mandaat per eindgebruiker en kan hier incasso-opdrachten mee uitvoeren (referenties) die niet gebonden zijn aan een bepaalde periode, een bepaald bedrag of een bepaalde omschrijving.

Stap 1: Aanmaken mandaat

Om de flexibele incasso te kunnen gebruiken, dient er voor elke eindgebruiker eerste eenmalig een mandaat aan te worden gemaakt. Dit wordt toegelicht in de onderstaande stappen.

Authenticatie

Basic Authentication

Authenticatie van de API DirectDebit::mandateAdd vindt plaats middels HTTP Basic Authentication.

Request

Request code: Mandaat aanmaken

curl --request POST \
  --url https://rest-api.pay.nl/v3/DirectDebit/mandateAdd/json \
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'serviceId=SL-1234-5678'
  --data-urlencode 'amount=995'
  --data-urlencode 'bankaccountHolder=K. Jansen'
  --data-urlencode 'bankaccountNumber=NL01RABO123456789'

In dit request voorbeeld maken we een mandaat voor IBAN-nummer NL01RABO123456789 van rekeninghouder K. Jansen. De eerste incasso-opdracht die voor het mandaat zorgt heeft een waarde van € 9,95.

Parameters

Paramater Type Omschrijving
serviceId string VERPLICHT Jouw verkooplocatie start met 'SL-' gevolgd door 8 cijfers. Je vindt een overzicht van jouw verkooplocatie(s) op https://admin.pay.nl/websites
amount integer VERPLICHT Bedrag in centen, dus € 3,50 is 350
bankaccountHolder string VERPLICHT Naam van de klant
bankaccountNumber string VERPLICHT IBAN nummer van de klant
bankaccountBic string OPTIONEEL BIC code van de klant
processDate string OPTIONEEL De datum waarop de incasso moet worden verwerkt (dd-mm-yyyy)
description string OPTIONEEL Omschrijving van de incasso-opdracht
currency string OPTIONEEL Valuta volgens ISO 4217 (drielettercode). Indien leeg wordt EUR gebruikt. Je vindt een overzicht op https://admin.pay.nl/data/currencies
exchangeUrl string OPTIONEEL De exchange URL die bij deze incasso moet worden gebruikt
ipAddress string OPTIONEEL IP-adres van van de klant
email string OPTIONEEL E-mailadres van de klant
promotorId integer OPTIONEEL Het id van de promotor (webmaster)
tool string OPTIONEEL Variabele 'tool' die kan worden getraceerd in de statistieken
info string OPTIONEEL Variabele 'info' die kan worden getraceerd in de statistieken
object string OPTIONEEL Variabele 'object' die kan worden getraceerd in de statistieken
extra1 string OPTIONEEL Variabele 'extra1' die kan worden getraceerd in de statistieken
extra2 string OPTIONEEL Variabele 'extra2' die kan worden getraceerd in de statistieken
extra3 string OPTIONEEL Variabele 'extra3' die kan worden getraceerd in de statistieken

Response

Response: Mandaat aanmaken

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "request": {
    "result": "1",
    "errorId": "",
    "errorMessage": ""
  },
  "result": "IO-0000-9876-5432"
}

In dit response voorbeeld zie je het resultaat van het aangemaakte mandaat.

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result string 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
errorMessage string Als er een foutmelding is opgetreden dan vind je hier de omschrijving
result string Het mandaat ID van de betreffende incasso, startend met 'IO-'. Hiermee kan je de status van de bijbehorende incasso's ('IL'-code) bepalen.

Je vindt een overzicht van de mandaten in het Admin Panel.

Stap 2: Flexibele incasso aanmaken

Als de eerst incasso niet gestorneerd wordt, dient deze als mandaat voor de vervolgopdrachten. Als er een mandaat beschikbaar is voor een klant dan kan je heel eenvoudig een flexibele incasso aanmaken via de volgende API: DirectDebit::mandateDebit

Je gebruikt hiervoor de variabele mandateId dat je als resultaat hebt ontvangen van de API DirectDebit::mandateAdd

Authenticatie

Basic Authentication

Authenticatie van de API DirectDebit::mandateDebit vindt plaats middels HTTP Basic Authentication.

Request

Request code: Flexibele incasso aanmaken

curl --request POST \
  --url https://rest-api.pay.nl/v3/DirectDebit/mandateDebit/json \
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'mandateId=IO-0000-9876-5432'
  --data-urlencode 'amount=1495'

In dit request voorbeeld maken we een flexibele incasso aan van € 14,95 m.b.v het verkregen mandaat 'IO-0000-9876-5432'.

Parameters

Paramater Type Omschrijving
mandateId string VERPLICHT
amount integer OPTIONEEL Het bedrag van de incasso. Indien niet meegegeven, wordt het bedrag van de vorige incasso-opdracht gebruikt
description string OPTIONEEL Omschrijving van de incasso-opdracht
processDate string OPTIONEEL De datum waarop de incasso moet worden verwerkt (dd-mm-yyyy)
last boolean OPTIONEEL Geeft aan dat het de laatste flexibele incasso opdracht, daarna wordt het mandaat ongeldig.

Response

Response: Flexibele incasso aanmaken

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "request": {
    "result": "1",
    "errorId": "",
    "errorMessage": ""
  },
  "result": "IL-0000-1234-5678"
}

In dit response voorbeeld zie je het resultaat van de aangemaakte flexibele incasso.

Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result string 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
errorMessage string Als er een foutmelding is opgetreden dan vind je hier de omschrijving

11.8. Incasso informatie ophalen

Om de details en actuele status van een eenmalige, recurring of flexibele incasso op te halen, kan je gebruik maken van de volgende API: DirectDebit::info

Authenticatie

Basic Authentication

Authenticatie van de API DirectDebit::info vindt plaats middels HTTP Basic Authentication.

Request

Request code: Incasso informatie ophalen

curl --request POST \
  --url https://rest-api.pay.nl/v3/DirectDebit/info/json \
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'mandateId=IO-0000-9876-5432'

In dit request voorbeeld vragen we de informatie op van incasso's die bij mandaat: 'IO-0000-9876-5432' behoren.

Parameters

Paramater Type Omschrijving
mandateId string VERPLICHT Het mandaat ID, startend met 'IO-', waarvoor je de bijbehorende incasso's (referenties) wil opvragen
referenceId integer OPTIONEEL Het referentie ID, startend met 'IL-'. Elke incasso-opdracht heeft een uniek referentie ID.

Wanneer je enkel de variabele mandateId meegeeft dan zul je de details van incasso's (referenties) die bij het mandaat behoren, ontvangen. In het geval van een eenmalige incasso is dit natuurlijk slechts 1 referentie.

Als je de details van één enkele incasso-opdracht (referentie) wil ontvangen dan dien je tevens de optionele variabele referenceId mee te geven.

Response

Response: Incasso informatie ophalen

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "request": {
    "result": "1",
    "errorId": "",
    "errorMessage": ""
  },
  "result": {
    "mandate": {
      "mandateId": "IO-0000-9876-5432",
      "type": "single",
      "bankaccountNumber": "NL30RABO0123456789",
      "bankaccounOwner": "K. Janssen",
      "bankaccountBic": "RABONL2U",
      "amount": "995",
      "description": "Demo incasso",
      "intervalValue": "0",
      "intervalPeriod": "0",
      "intervalQuantity": "1",
      "state": "single",
      "ipAddress": "1.2.3.4",
      "email": "",
      "promotorId": "0",
      "tool": "",
      "info": "",
      "extra1": "",
      "extra2": "",
      "extra3": ""
    },
    "directDebit": [
      {
        "referenceId": "IL-0000-1234-5678",
        "bankaccountNumber": "NL30RABO0123456789",
        "bankaccountHolder": "K. Janssen",
        "bankaccountBic": "RABONL2U",
        "paymentSessionId": "823404322",
        "amount": "995",
        "description": "Demo incasso",
        "sendDate": "2018-01-01",
        "receiveDate": "2018-01-05",
        "statusCode": "100",
        "statusName": "Geincasseerd",
        "declineCode": "0",
        "declineName": "",
        "declineDate": ""
      }
    ]
  }
}

In dit response voorbeeld zie je het resultaat van de incasso's (referenties) die behoren bij mandaat 'IO-0000-9876-5432'. In dit geval betreft het een eenmalige incasso (IL-0000-1234-5678) waarvan we de details ontvangen.

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result boolean 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
errorMessage string Als er een foutmelding is opgetreden dan vind jehier de omschrijving
result array Array met een mandaat en bijbehorende referentie(s)
mandate array Array met informatie over het mandaat
mandateId string Het mandaat ID waarvoor de bijbehorende referenties zijn opgevraagd
bankaccountNumber string IBAN nummer van de klant
bankaccountOwner string Naam van de klant
bankaccountBic string BIC code van de klant
amount integer Bedrag in centen, dus € 3,50 is 350
description string Omschrijving van de incasso-opdracht
intervalValue integer Bepaalt samen met de variabele intervalPeriode de herhalingstermijn
intervalPeriod integer 1: week, 2: maand, 3:kwartaal, 4: half jaar, 5: jaar, 6: dag
intervalQuantity integer Het aantal herhalingen waarna de incasso-opdracht moet worden gestopt
state string Mogelijke waarden: first, active, last, single
ipAddress string IP-adres van van de klant
email string E-mailadres van de klant
promotorId string Het id van de promotor (webmaster)
tool string Variabele 'tool' die kan worden getraceerd in de statistieken
info string Variabele 'info' die kan worden getraceerd in de statistieken
object string Variabele 'object' die kan worden getraceerd in de statistieken
extra1 string Variabele 'extra1' die kan worden getraceerd in de statistieken
extra2 string Variabele 'extra2' die kan worden getraceerd in de statistieken
extra3 string Variabele 'extra3' die kan worden getraceerd in de statistieken
directDebit array Array met 1 of meerdere referenties die bij het opgevraagde mandaat behoren
referenceId string Unieke ID van de incasso-opdracht (referentie)
bankaccountNumber string IBAN nummer van de klant
bankaccountOwner string Naam van de klant
bankaccountBic string BIC code van de klant
paymentSessionId string Uniek betaalsessie ID
amount integer Bedrag in centen, dus €3,50 is 350
description string Omschrijving van de incasso-opdracht
sendDate string Datum waarop de incasso-opdracht is verstuurd
receiveDate string De datum waarop het de tegoeden zijn gecollecteerd
statusCode string Zie statussen voor de betreffende codes
statusName string Zie statussen voor de betreffende namen
declineCode string Zie storneringsredenen voor de betreffende codes
declineName string Zie storneringsredenen voor de betreffende namen
declineDate string Indien gestorneerd vind je hier de datum terug

Als er meerdere incasso-opdrachten (referenties) bij een mandaat behoren dan ontvang je deze via de array directDebit. Een incasso-opdracht is geslaagd als de variabele statusCode de waarde 100 heeft.

11.9. Exchange calls

Een communicatie- of exchange URL is een URL waar een script van u staat om meldingen van onze servers te ontvangen. Bij alle typen betalingen geven onze servers meldingen aan jou door om de status van de betaling door te geven, bijvoorbeeld om aan te geven dat een incassobetaling succesvol is geïncasseerd. Deze melding leveren wij dan af door het script op jouw exchange URL aan te roepen waarbij er een aantal parameters mee worden gegeven waarmee je de incasso kan achterhalen en eventueel kan updaten in jouw systeem.

Het gehele exchange proces voor een normale online betaling wordt hier uitgebreid beschreven. Voor een exchange call van een incasso-opdracht gelden slechts enkele wijzigingen die we hieronder toelichten.

Exchange URL instellen via een API

Bij het aanmaken van een incasso kan je jouw communicatie / exchange URL instellen via de variabele exchangeUrl Deze variabele is beschikbaar in de volgende API's:

Parameters

Bij het aanroepen van de exchange / communicatie URL stuurt PAY. de standaard POST / GET parameters mee zoals hier vermeld aangevuld met de parameters mandateId en referenceId

Via het mandatveId (en optioneel de referenceI) kan je de details van een incasso-opdracht ophalen via de API DirectDebit::info

Momenten van aanroep

Voor de betaaloptie incasso gelden de onderstaande momenten van aanroep:

Action Moment van aanroep
incassoadd Vlak nadat PAY. de incasso heeft opgepakt en heeft verwerkt tot een bankopdracht.
incassosend Vlak nadat de incasso-opdracht verstuurd is naar de bank.
incassopending
incassocollected Vlak nadat het geïncasseerde bedrag binnen is gekomen op de rekening van PAY. en vanaf dit moment is het ook beschikbaar in jouw boeksaldo.
incassostorno Vlak nadat het geïncasseerde bedrag is gestorneerd van onze rekening. Dit kan optreden tot en met 56 kalenderdagen na het ontvangen van de 'incassocollected'.
incassopremoi Vlak nadat er een MOI (melding onterechte incasso) is ontvangen waarbij een eindgebruiker via zijn/haar bank de incasso heeft terug laten draaien.

Functies als verplichte beantwoording, logging, retry scheme en beveiligen zijn overeenkomstig de standaard exchange calls.

11.10. Statussen

Bij het opvragen van de incasso status ontvang je één van de volgende statuscodes:

Statussen

Code Status Omschrijving
Veelvoorkomende statussen
94 ImageVerwerkt De incasso is door PAY. in een batch geplaatst en deze is aangeboden bij de bank
100 ImageGeïncasseerd Het bedrag is succesvol geïncasseerd
106 ImageTerugboeking Het bedrag is niet geïncasseerd, zie Storneringsredenen voor de specificatie
Overige statussen
91 ImageToegevoegd De incasso-opdracht is door PAY. opgepakt en staat op het punt om te worden verwerkt
526 ImageIn batch De incasso-opdracht is in een batch geplaatst
97 ImageVoortijdig afgewezen De incasso-opdracht is door het systeem van PAY. afgewezen
103 ImageVerwijderd De incasso-opdracht is verwijderd
127 ImageGeweigerd door bank De incasso-opdracht is geweigerd door bank

Storneringsredenen

In het geval van een terugboeking (statuscode 106) is via de API DirectDebit::info een variabele result['directDebit']['declineCode'] beschikbaar die de storneringsreden weergeeft. Deze decline code kan de volgende waarden bevatten:


Code Status   Mogelijke oorzaken
Veelvoorkomende statussen
109 Administratieve reden   Er is onvoldoende saldo op de rekening van de debiteur
Het IBAN nummer of de naam van de debiteur ontbreekt
De transactie voldoet niet aan wettelijk gestelde eisen
Er zijn "overige redenen"
121 Niet akkoord met incasso   De debiteur is het niet eens met de afschrijving. Hij maakt gebruik van het stornorecht (tot 8 weken na afschrijving)
De debiteur heeft de incasso geweigerd, voor de verwerkingsdatum van de incasso.
274 Rekeningnummer geblokkeerd   Het IBAN nummer waarvan je wilt incasseren, is niet voor incasso geschikt
277 Selectieve incassoblokkade   Het IBAN waarvan je wilt incasseren is geblokkeerd voor (deze) incasso. Dit kan door de debiteur of door de bank van de debiteur ingesteld zijn.
Het IBAN waarvan je wilt incasseren, is niet voor incasso geschikt. Het is bijvoorbeeld een spaarrekening
Overige statussen
112 Rekeningnummer vervallen   Het IBAN waarvan je wilt incasseren, is opgeheven
De debiteur is overleden.
115 Rekeningnummer onbekend   Het IBAN waarvan je wilt incasseren is niet juist.
118 Onjuiste machtiging   De debiteur heeft een lager maximum bedrag ingesteld dan het incassobedrag
Er is geen juiste registratie van de machtiging of de debiteur heeft de machtiging ingetrokken
De incasso is afgekeurd omdat er geen uniek machtigingskenmerk is gebruikt. Sommige banken controleren het kenmerk en verwachten dat deze uniek is.
124 Incasso dubbel uitgevoerd   Deze incasso is al eerder ingestuurd
271 Naam / nummer stemmen niet overeen   De naam van de debiteur zoals deze is ingestuurd komt niet overeen met de feitelijk naam van de rekeninghouder.
280 Rekeningnummer WKA   Het IBAN nummer betreft een rekeningnummer WKA waarvan niet geincasseerd mag worden.
286 Reden niet gespecificeerd   De incasso kon niet worden verwerkt maar er is geen specifieke reden vanuit de bank van de debiteur ontvangen
331 Melding onterechte incasso   De debiteur herkent de incassoopracht niet en heeft de procedure Melding Onterecht Incasso gestart. (tot 13 maanden na afschrijving)

11.11. Foutafhandeling

Indien er een fout is opgetreden bij het toevoegen van een incasso-opdracht via de API is een variabele request['errorId'] beschikbaar die een error code weergeeft. Deze error code kan de volgende waarden bevatten:


Errorcode Errormessage
100 General error
101 Invalid amount
102 Process date is too early
103 Not a valid interval
104 Interval value has been reached for this order
105 Interval value must be higher than 0
201 You can not start a directdebit for your own bankaccount
202 Invalid service, or the service does not have directdebit enabled
203 This order exceeds the maximum order amount
204 Bankaccount is on blacklist
205 The maximum amount of orders per day has already been reached for this bankaccount
206 This order will exceed the total amount that can be debited per day
207 The date for the last directdebit is too early
403 Access denied
404 Invalid value for parameter
405 Input not valid
500 Internal error please contact PAY. about this error

12. Pinnen (In-store payments)

Image
De verschillende stappen voor pinbetalingen

Naast online betalingen voor jouw webshop is het ook mogelijk om pinbetalingen (in-store payments) voor een fysiek verkooppunt te ontvangen. PAY. biedt twee soorten terminals. De Yomani pinterminal is een automaat die je aan kan sluiten op een vaste internetaansluiting.

In dit hoofdstuk lees je hoe je een pintransactie start en verwerkt met behulp van een API.

Het pinproces

Het proces m.b.t pinbetalingen verloopt in verschillende stappen die in de afbeelding hiernaast wordt weergegeven.

12.1. Beschikbaarheid van terminaltransacties en retourpinnen

Request code: Alle Terminals ophalen

curl --request POST \
  --url https://rest-api.pay.nl/v4/Instore/getAllTerminals/json \
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \

Om te controleren of je terminal geconfigureerd is voor het ontvangen van betalingen en het uitvoeren van retourpinnen, kun je de API Instore::getAllTerminals gebruiken.

Authenticatie

Basic Authentication

Authenticatie van de API Instore::getAllTerminals vindt plaats middels HTTP Basic Authentication

Request

In dit request voorbeeld, halen we alle terminals op om te checken of ze betalingen en retourpinnen kunnen verwerken, door de API Instore::getAllTerminals te gebruiken.

Response: Alle Terminals ophalen

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
"request": {
"result": "1",
"errorId": "",
"errorMessage": ""
},
"terminals": {
"id": "TH-4321-7890",
"name": "Your Terminal",
"ecrProtocol": "WEB",
"state": "active",
"payment": "1",
"refund": "1"
},
}

In deze response zie je dat terminal "TH-4321-7890" betalingen en retourpinnen heeft geactiveerd.

200 application/json; charset=utf-8
Parameter Type Omschrijving
request array Array met informatie over het resultaat van de request
result string 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
errorMessage string Als er een foutmelding is opgetreden dan vind je hier de omschrijving
terminals array Deze array bevat info over je huidige terminal(s)
id string De identifier van de terminal
name string De naam van je terminal
ecrProtocol string Het type of ecrProtocol dat je terminal(s) gebruikt.
state string De statusvan je terminal(s), dit kan actief of inactief
payment string De beschikbaarheid van de terminal(s) om betalingen te ontvangen. 1: beschikbaar, 0: niet beschikbaar
refund string De beschikbaarheid van retourpinnen op de terminal(s). 1: beschikbaar, 0: niet beschikbaar

12.2. Pintransactie starten

Om een pintransactie te starten, kan je gebruikmaken van de API Transaction::start Als paymentOptionId dien je 1927 (PIN) mee te geven. Vanzelfsprekend dient deze betaaloptie (PIN) geactiveerd te zijn in jouw verkooplocatie. Vervolgens geef je via de variabele paymentOptionSubId aan op welke terminal de pinbetaling afgerekend dient te worden.

Authenticatie

Basic Authentication

Authenticatie van de API Transaction::start vindt plaats middels HTTP Basic Authentication.

Request

Request code: Pintransactie starten

curl --request POST \
	--url https://rest-api.pay.nl/v16/Transaction/start/json \
	--header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
	--header 'cache-control: no-cache' \
	--header 'content-type: application/x-www-form-urlencoded' \
	--data-urlencode 'serviceId=SL-3490-4320' \
	--data-urlencode 'amount=100' \
	--data-urlencode 'ipAddress=1.2.3.4' \
	--data-urlencode 'finishUrl=https://www.domain.com/return' \
	--data-urlencode 'paymentOptionId=1927' \
	--data-urlencode 'paymentOptionSubId=TH-1234-5678' \
	--data-urlencode 'transaction[description]=My first instore payment'

In dit request voorbeeld starten we een pintransactie van € 1,- voor verkooplocatie SL-3490-4320 op pinterminal TH-1234-5678.

Parameters

Paramater Type Omschrijving
serviceId string VERPLICHT Jouw verkooplocatie start met 'SL-' gevolgd door 8 cijfers. Je vindt een overzicht van jouw verkooplocatie(s) op https://admin.pay.nl/websites
amount integer VERPLICHT Bedrag in centen, dus €3,50 is 350
ipAddress string VERPLICHT IP-adres van gebruiker
finishUrl string VERPLICHT URL waar de bezoeker naar wordt doorgestuurd als de betaling is voltooid. Voor pinbetalingen wordt deze URL niet uitgevoerd.
paymentOptionId integer VERPLICHT Interne ID van de betaaloptie waarvoor je een transactie wil starten. Voor een pintransactie voer je hier 1927 in.
paymentOptionSubId string VERPLICHT Voer hier de terminal in waarop de pintransactie moet worden afgerekend. Het terminal ID start met 'TH' en kan worden opgehaald via de Instore::getAllTerminals
testmode boolean OPTIONEEL Transactie uitvoeren in test modus. 0: Geen test modus ,1: Gebruik test modus
transaction Image array OPTIONEEL bekijk array
currency string OPTIONEEL Valuta volgens ISO 4217 (drielettercode). Indien leeg wordt EUR gebruikt. Je vindt een overzicht op https://admin.pay.nl/data/currencies
orderExchangeUrl string OPTIONEEL De URL voor het afleveren van de statussen, ook wel webhook of IPN genoemd.
description string OPTIONEEL Omschrijving van de order (maximaal 32 tekens)
expireDate string OPTIONEEL Verloopdatum van de transactie in het formaat: dd-mm-YY HH:ii:ss (31-12-2017 22:33:44). Maximale verloopdatum is +4 weken.
statsData Image array OPTIONEEL bekijk array
promotorId integer OPTIONEEL Het ID van de promotor (webmaster)
info string OPTIONEEL Variabele 'info' die kan worden getraceerd in de statistieken
tool string OPTIONEEL Variabele 'tool' die kan worden getraceerd in de statistieken
extra1 string OPTIONEEL Vrije variabele 'extra1' die kan worden getraceerd in de statistieken. (advies: ID van de order)
extra2 string OPTIONEEL Vrije variabele 'extra2' die kan worden getraceerd in de statistieken. (advies: klant referentie)
extra3 string OPTIONEEL Vrije variabele 'extra3' die kan worden getraceerd in de statistieken
transferData string OPTIONEEL Een array van vrije waarden
enduser Image array OPTIONEEL bekijk array
language string OPTIONEEL Taal van de eindgebruiker, NL voor Nederlands, EN voor Engels
initials string OPTIONEEL Voornaam / initialen van de eindgebruiker
lastName string OPTIONEEL Achternaam van de eindgebruiker
gender string OPTIONEEL M: man, F: vrouw
dob string OPTIONEEL Geboortedatum in het formaat dd-mm-yyyy
phoneNumber string OPTIONEEL Telefoonnummer van de eindgebruiker
emailAddress string OPTIONEEL Emailadres van de eindgebruiker
address array OPTIONEEL
streetName string OPTIONEEL Straatnaam van de eindgebruiker
streetNumber string OPTIONEEL Huisnummer van de eindgebruiker
streetNumberExtension string OPTIONEEL Toevoeging huisnummer
zipCode string OPTIONEEL Postcode van de eindgebruiker
city string OPTIONEEL Woonplaats van de eindgebruiker
countryCode string OPTIONEEL Landcode volgens ISO 3166 (tweelettercode). Je vindt een overzicht op https://admin.pay.nl/data/countries
invoiceAddress array OPTIONEEL
initials string OPTIONEEL Voornaam / initialen van de persoon die de factuur ontvangt
lastName string OPTIONEEL Achternaam van de persoon die de factuur ontvangt
gender string OPTIONEEL Geslacht van de persoon die de factuur ontvangt. M: man, F: vrouw
streetName string OPTIONEEL Straatnaam van de persoon die de factuur ontvangt
streetNumber string OPTIONEEL Huisnummer van de persoon die de factuur ontvangt
streetNumberExtension string OPTIONEEL Toevoeging huisnummer van de persoon die de factuur ontvangt
zipCode string OPTIONEEL Postcode van de persoon die de factuur ontvangt
city string OPTIONEEL Woonplaats van de persoon die de factuur ontvangt
countryCode string OPTIONEEL Landcode volgens ISO 3166 (tweelettercode) van de persoon die de factuur ontvangt. Je vindt een overzicht op https://admin.pay.nl/data/countries
saleData Image array OPTIONEEL bekijk array
invoiceDate string OPTIONEEL Datum van de factuur (YYYY-MM-DD)
deliveryDate string OPTIONEEL Verwachte leverdatum (YYYY-MM-DD)
orderData array OPTIONEEL
Image array OPTIONEEL Array met bestelde producten
productId string OPTIONEEL Het interne product id binnen uw systeem
productType string OPTIONEEL Type van de orderregel met de volgende mogelijke waarden: ARTICLE, SHIPPING, HANDLING, DISCOUNT
description string OPTIONEEL Omschrijving van het bestelde product
price integer OPTIONEEL Productprijs in centen, dus € 3,50 is 350
quantity integer OPTIONEEL Aantal bestelde producten met het betreffende product ID
vatCode string OPTIONEEL BTW code, mogelijke waarden: H: high, N: zero, L: low
vatPercentage string OPTIONEEL BTW percentage, bv: 21.00 of 6.00

Vanwege het grote aantal parameters worden de arrays beperkt weergegeven. Klik op de button 'bekijk array' om de volledige array te bekijken.

Response

Response: Pintransactie starten

	HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8


	{
	"request": {
	"result": "1",
	"errorId": "",
	"errorMessage": ""
	},
	"endUser": {
	"blacklist": "0"
	},
	"transaction": {
	"transactionId": "798491152Xc70580",
	"paymentURL": "https://safe.pay.nl/pin/7cfe195addffce335eb3092e7a0b07ac/NL",
	"popupAllowed": "0",
	"paymentReference": "7000 0079 8491 1152"
	},
	"terminal": {
	"hash": "7cfe195addffce335ebce66d7633092e7a0b07bb",
	"statusUrl": "https://pin.pay.nl:9004/api/status?hash=7cfe195addffce335eb3092e7a0b07ac&timeout=5"
	"cancelUrl": "https://instore.pay.nl:9004/api/cancel?hash=7cfe195addffce335eb3092e7a0b07ac&timeout=5"
	}
	}

In dit response zie je het resultaat van de gestarte pintransactie: '798491152Xc70580'.

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result string 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
errorMessage string Als er een foutmelding is opgetreden dan vind je hier de omschrijving
endUser array Array met informatie over de eindgebruiker
blacklist integer 0: eindgebruiker staat niet op de blacklist, 1: eindgebruiker staat op de blacklist
transaction array Array met informatie over de transactie
transactionId string Uniek ID van de pintransactie
paymentURL string URL om de voortgang van een pintransactie te controleren
popupAllowed boolean Geeft aan of een betaalscherm in een popup mag worden geladen. 0: niet toegestaan, 1: toegestaan
paymentReference string Betaalkenmerk van een transactie
terminal array Array met informatie over de pinterminal
hash string Unieke key van de transactie die gebruikt kan worden om de status van de pinbetaling te verifiëren of om een pinbon te genereren.
statusUrl string API URL die gebruikt kan worden om de status van de transactie op te halen
cancelUrl string API URL die gebruikt kan worden om de transactie af te breken

Pinterminal

Image
Bij een correcte pintransactie zal de pinterminal om de betaalkaart van de klant vragen

Als de pintransactie correct is aangemaakt dan zal de pinterminal vervolgens om de betaalkaart van de klant vragen zoals in de afbeelding hiernaast.

12.3. Retourpinnen

Om een bedrag terug te betalen (retourpinnen), kan je gebruikmaken van de API Transaction::start Als paymentOptionId dien je 2351 (Retourpinnen) mee te geven. Vervolgens geef je via de variabele paymentOptionSubId aan op welke terminal de pinbetaling afgerekend dient te worden.

Authenticatie

Basic Authentication

Authenticatie van de API Transaction::start vindt plaats middels HTTP Basic Authentication.

Request

Request code: Pintransactie starten

curl --request POST \
	--url https://rest-api.pay.nl/v15/Transaction/start/json \
	--header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
	--header 'cache-control: no-cache' \
	--header 'content-type: application/x-www-form-urlencoded' \
	--data-urlencode 'serviceId=SL-3490-4320' \
	--data-urlencode 'amount=100' \
	--data-urlencode 'ipAddress=1.2.3.4' \
	--data-urlencode 'finishUrl=https://www.domain.com/return' \
	--data-urlencode 'paymentOptionId=2351' \
	--data-urlencode 'paymentOptionSubId=TH-1234-5678' \
	--data-urlencode 'transaction[description]=My first instore payment'

In dit request voorbeeld boeken we middels een pintransactie € 1,- retour via verkooplocatie SL-3490-4320 op pinterminal TH-1234-5678.

Parameters

Paramater Type Omschrijving
serviceId string VERPLICHT Jouw verkooplocatie start met 'SL-' gevolgd door 8 cijfers. Je vindt een overzicht van jouw verkooplocatie(s) op https://admin.pay.nl/websites
amount integer VERPLICHT Bedrag in centen, dus €3,50 is 350
ipAddress string VERPLICHT IP-adres van gebruiker
finishUrl string VERPLICHT URL waar de bezoeker naar wordt doorgestuurd als de betaling is voltooid. Voor pinbetalingen wordt deze URL niet uitgevoerd.
paymentOptionId integer VERPLICHT Interne ID van de betaaloptie waarvoor je een transactie wil starten. Voor een pintransactie voer je hier 1927 in.
paymentOptionSubId integer VERPLICHT Voer hier de terminal in waarop de pintransactie moet worden afgerekend. Het terminal ID start met 'TH' en kan worden opgehaald via de Instore::getAllTerminals
testmode boolean OPTIONEEL Transactie uitvoeren in test modus. 0: Geen test modus ,1: Gebruik test modus
transaction Image array OPTIONEEL bekijk array
currency string OPTIONEEL Valuta volgens ISO 4217 (drielettercode). Indien leeg wordt EUR gebruikt. Je vindt een overzicht op https://admin.pay.nl/data/currencies
orderExchangeUrl string OPTIONEEL De URL voor het afleveren van de statussen, ook wel webhook of IPN genoemd.
description string OPTIONEEL Omschrijving van de order (maximaal 32 tekens)
expireDate string OPTIONEEL Verloopdatum van de transactie in het formaat: dd-mm-YY HH:ii:ss (31-12-2017 22:33:44). Maximale verloopdatum is +4 weken.
statsData Image array OPTIONEEL bekijk array
promotorId integer OPTIONEEL Het ID van de promotor (webmaster)
info string OPTIONEEL Variabele 'info' die kan worden getraceerd in de statistieken
tool string OPTIONEEL Variabele 'tool' die kan worden getraceerd in de statistieken
extra1 string OPTIONEEL Vrije variabele 'extra1' die kan worden getraceerd in de statistieken. (advies: ID van de order)
extra2 string OPTIONEEL Vrije variabele 'extra2' die kan worden getraceerd in de statistieken. (advies: klant referentie)
extra3 string OPTIONEEL Vrije variabele 'extra3' die kan worden getraceerd in de statistieken
transferData string OPTIONEEL Een array van vrije waarden
enduser Image array OPTIONEEL bekijk array
language string OPTIONEEL Taal van de eindgebruiker, NL voor Nederlands, EN voor Engels
initials string OPTIONEEL Voornaam / initialen van de eindgebruiker
lastName string OPTIONEEL Achternaam van de eindgebruiker
gender string OPTIONEEL M: man, F: vrouw
dob string OPTIONEEL Geboortedatum in het formaat dd-mm-yyyy
phoneNumber string OPTIONEEL Telefoonnummer van de eindgebruiker
emailAddress string OPTIONEEL Emailadres van de eindgebruiker
address array OPTIONEEL
streetName string OPTIONEEL Straatnaam van de eindgebruiker
streetNumber string OPTIONEEL Huisnummer van de eindgebruiker
streetNumberExtension string OPTIONEEL Toevoeging huisnummer
zipCode string OPTIONEEL Postcode van de eindgebruiker
city string OPTIONEEL Woonplaats van de eindgebruiker
countryCode string OPTIONEEL Landcode volgens ISO 3166 (tweelettercode). Je vindt een overzicht op https://admin.pay.nl/data/countries
invoiceAddress array OPTIONEEL
initials string OPTIONEEL Voornaam / initialen van de persoon die de factuur ontvangt
lastName string OPTIONEEL Achternaam van de persoon die de factuur ontvangt
gender string OPTIONEEL Geslacht van de persoon die de factuur ontvangt. M: man, F: vrouw
streetName string OPTIONEEL Straatnaam van de persoon die de factuur ontvangt
streetNumber string OPTIONEEL Huisnummer van de persoon die de factuur ontvangt
streetNumberExtension string OPTIONEEL Toevoeging huisnummer van de persoon die de factuur ontvangt
zipCode string OPTIONEEL Postcode van de persoon die de factuur ontvangt
city string OPTIONEEL Woonplaats van de persoon die de factuur ontvangt
countryCode string OPTIONEEL Landcode volgens ISO 3166 (tweelettercode) van de persoon die de factuur ontvangt. Je vindt een overzicht op https://admin.pay.nl/data/countries
saleData Image array OPTIONEEL bekijk array
invoiceDate string OPTIONEEL Datum van de factuur (YYYY-MM-DD)
deliveryDate string OPTIONEEL Verwachte leverdatum (YYYY-MM-DD)
orderData array OPTIONEEL
Image array OPTIONEEL Array met bestelde producten
productId string OPTIONEEL Het interne product id binnen uw systeem
productType string OPTIONEEL Type van de orderregel met de volgende mogelijke waarden: ARTICLE, SHIPPING, HANDLING, DISCOUNT
description string OPTIONEEL Omschrijving van het bestelde product
price integer OPTIONEEL Productprijs in centen, dus € 3,50 is 350
quantity integer OPTIONEEL Aantal bestelde producten met het betreffende product ID
vatCode string OPTIONEEL BTW code, mogelijke waarden: H: high, N: zero, L: low
vatPercentage string OPTIONEEL BTW percentage, bv: 21.00 of 6.00

Vanwege het grote aantal parameters worden de arrays beperkt weergegeven. Klik op de button 'bekijk array' om de volledige array te bekijken.

Response

Response: Pintransactie starten

	HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8


	{
	"request": {
	"result": "1",
	"errorId": "",
	"errorMessage": ""
	},
	"endUser": {
	"blacklist": "0"
	},
	"transaction": {
	"transactionId": "798491152Xc70580",
	"paymentURL": "https://safe.pay.nl/pin/7cfe195addffce335eb3092e7a0b07ac/NL",

	"popupAllowed": "0",
	"paymentReference": "7000 0079 8491 1152"
	},
	"terminal": {
	"hash": "7cfe195addffce335ebce66d7633092e7a0b07bb",
	"statusUrl": "https://pin.pay.nl:9004/api/status?hash=7cfe195addffce335eb3092e7a0b07ac&timeout=5"

	"cancelUrl": "https://instore.pay.nl:9004/api/cancel?hash=7cfe195addffce335eb3092e7a0b07ac&timeout=5"

	}
	}

In dit response zie je het resultaat van de gestarte pintransactie: '798491152Xc70580'.

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result string 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
errorMessage string Als er een foutmelding is opgetreden dan vind je hier de omschrijving
endUser array Array met informatie over de eindgebruiker
blacklist integer 0: eindgebruiker staat niet op de blacklist, 1: eindgebruiker staat op de blacklist
transaction array Array met informatie over de transactie
transactionId string Uniek ID van de pintransactie
paymentURL string URL om de voortgang van een pintransactie te controleren
popupAllowed boolean Geeft aan of een betaalscherm in een popup mag worden geladen. 0: niet toegestaan, 1: toegestaan
paymentReference string Betaalkenmerk van een transactie
terminal array Array met informatie over de pinterminal
hash string Unieke key van de transactie die gebruikt kan worden om de status van de pinbetaling te verifiëren of om een pinbon te genereren.
statusUrl string API URL die gebruikt kan worden om de status van de transactie op te halen
cancelUrl string API URL die gebruikt kan worden om de transactie af te breken

12.4. Pintransactie controleren

Request pintransactie status

# Opvragen status pintransactie.
https://pin.pay.nl:9004/status?hash=7cfe195addffce335eb3092e7a0b07ac&timeout=5

De klant heeft 45 seconden om een pintransactie af te ronden. Om te bepalen of een pinbetaling is geslaagd en de pinterminal weer beschikbaar is voor een nieuwe transactie kan je de status pollen. Wij raden je aan om de statusURL die je ontvangt bij het starten van een betaling niet te proxy-en maar direct aan te roepen. De status call wacht met antwoorden tot de pinterminal een eindstatus heeft (betaald, verlopen of afgewezen) of de TimeOut is verstreken. Indien de terminal na de POLL timeout nog geen eindstatus heeft, ontvang je een PENDING status. Je wacht 1 seconde en roept opnieuw de status URL aan. Dit herhaal je tot de terminal de eindstatus heeft.

Response pintransactie status: pending

{
    "status": "start",
    "txid": "TT-9549-5050-7700",
    "terminal": "50125205",
    "ssai": "0054cfc07110aa50ea909727381649de569f0fb770696e34dd0d31bb"
}

Response pintransactie status: cancel (geannuleerd door gebruiker)

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "status": "final",
    "txid": "TT-8679-5065-7700",
    "signature": "0",
    "terminal": "50125205",
    "ssai": "004bc3d8801046d67af69706782510fadbf0f90470696e34927c3d77",
    "error": "0",
    "amount": "1",
    "incidentcode": "2629",
    "incidentcodetext": "USER_CANCELLATION",
    "cancelled": "1",
    "approved": "0"
}

Response pintransactie status: cancel (timeout)

{
    "status": "final",
    "txid": "TT-9549-5050-7700",
    "signature": "0",
    "terminal": "50125205",
    "ssai": "0054cfc07110aa50ea909727381649de569f0fb770696e34dd0d31bb",
    "error": "0",
    "amount": "1",
    "incidentcode": "1803",
    "incidentcodetext": "TIMEOUT_EXPIRATION",
    "cancelled": "1",
    "approved": "0"
}

Response pintransactie status: betaald

{
    "status": "final",
    "txid": "TT-4149-5097-7700",
    "signature": "0",
    "terminal": "50125205",
    "ssai": "00b109736810adbce2749778f04fa4e3acd2149d70696e3459349676",
    "cardbrandlabelname": "Maestro",
    "cardbrandidentifier": "1009",
    "approvalID": "J9LHSH",
    "ticket": "UE9JOiA1MDEyNTIwNQ0gTUVSQ0hBTlQgVGlja2V0DSAtLS0tLS0tLS0tLS0tLS0t=...",
    "error": "0",
    "amount": "1",
    "incidentcode": "0000",
    "incidentcodetext": "SUCCESS",
    "cancelled": "0",
    "approved": "1"
}

Request

Je kan de status opvragen via de URL die is meegegeven middels de parameter statusUrl. Deze parameter heb je ontvangen in de json response nadat een pintransactie succesvol is gestart.

Response

In dit voorbeeld zien we de response van de aanroep van de URL https://pin.pay.nl:9004/status?hash=7cfe195addffce335eb3092e7a0b07ac&timeout=5 tijdens de verschillende statussen: pending, cancel en betaald

200 application/json; charset=utf-8
Naam Type Omschrijving
status string Status van de terminal. Start: terminal wacht op actie van de klant, final: transactie is voltooid (betaald of geannuleerd), de terminal is weer beschikbaar
txid string Unieke referentie van een pintransactie
signature string 0: pinbon hoeft niet ondertekend te worden 1: pinbon dient ondertekend te worden door de klant
terminal string Geeft weer op welke terminal de transactie is gestart
ssai string Unieke referentie van de pintransactie
cardbrandlabelname string Naam van het gebruikte cardscheme (bv Maestro, VISA)
cardbrandidentifier string Identifier van het gebruikte cardscheme
approvalID string Autorisatiecode van de pintransactie
ticket string Base64 gecodeerde pinbon, gebruik base64 decodering om de afbeelding weer te geven
error string 0: Er is geen fout opgetreden - 1 : Er is een fout opgetreden tijdens het pinproces
amount string Bedrag in centen van de pintransactie
incidentcode string Deze identifier komt via de pinterminal. Als de "status" : "final" is en "cancelled": "1" dan kan je deze identifier weergegeven in een melding
incidentcodetext string Deze tekst komt via de pinterminal. Als de "status" : "final" is en "cancelled": "1" dan kan je deze tekst weergeven in een melding.
cancelled string 0: transactie is geannuleerd, 1: transactie geannuleerd
approved string Indien "approved" : "1" dan kan je de printbon genereren m.b.v Base64 decode. Je kan ook jouw eigen pinbon maken met de volgende velden:
cardbrandlabelname
cardbrandidentifier
approvalID
txid
terminal
Image
Melding van een succesvolle transactie op de pinterminal

Pinterminal

Als de pintransactie succesvol is betaald dan zal de pinterminal een melding weergeven zoals op de afbeelding hiernaast. Afbeelding: Melding van een succesvolle transactie op de pinterminal

Image
Scherm bij gebruik van paymentURL

Voortgang

Optioneel kan je de voortgang van de pintransactie weergeven door gebruik te maken van de paymentURL die je ontvangt als json response na het starten van de pintransactie. Het scherm dat de verstreken tijd weergeeft, ziet er als volgt uit: Afbeelding: Scherm bij gebruik van paymentURL

12.5. Pinbon weergeven

Niet elke pinterminal heeft de optie om een pinbon te printen. Je bent verplicht om de klant een pinbon te kunnen overhandigen. Dit mag ook per e-mail of SMS. Er zijn twee manieren om een pinbon te genereren.

1. Pinbon genereren via ticket parameter

De eenvoudigste manier om een pinbon te genereren is door gebruik te maken van de parameter ticket die je in de json response ontvangt na een succesvolle betaling. Deze parameter bevat een waarde met de Base64 geëncodeerde pinbon. Gebruik base64-decodering om de pinbon afbeelding weer te geven.

2. Pinbon genereren via API

Daarnaast is er de mogelijkheid om via de API Instore::getTransactionTicket een pinbon te genereren die je zelf kan verzenden.

Authenticatie

Authenticatie van de API Instore::getTransactionTicket is niet nodig.

Request

Request code: Pinbon weergeven

curl --request POST \
  --url https://rest-api.pay.nl/v2/Instore/getTransactionTicket/json \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'hash=7cfe195addffce335ebce66d7633092e7a0b07bb'

In dit request voorbeeld genereren we een pinbon met hash '7cfe195addffce335ebce66d7633092e7a0b07bb'. De hash heb je verkregen tijdens het starten van de pinbetaling.

Parameters

Paramater Type Omschrijving
hash string VERPLICHT Hash zoals verstrekt bij het starten van de pintransactie

Response

Response: Pinbon weergeven

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "request": {
    "result": "1",
    "errorId": "",
    "errorMessage": ""
  },
  "receipt": "UE9JOiA1MDIwMjk3MQpDTElFTlQgVElDS0VUCi0tLS0tLS0tLS0tLSo=...",
  "signature": "0",
  "approvalId": "L5KKSY",
  "cardBrandId": "1009",
  "cardBrandName": "MAESTRO",
  "paymentProfileId": "1630"
}

In dit response zie je het resultaat voor het genereren van een pinbon met hash '7cfe195addffce335ebce66d7633092e7a0b07bb'. De pinbon wordt geretourneerd via de variabele receipt in base64 codering, gebruik base64 decodering om de afbeelding van de pinbon weer te geven.

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result string 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
errorMessage string Als er een foutmelding is opgetreden dan vind je hier de omschrijving
receipt string Base64 geëncodeerde pinbon, gebruik base64 decodering om de afbeelding weer te geven
approvalId string Identifier voor de transactie
cardBrandId string ID van het gebruikte cardscheme
cardBrandName string Naam van het gebruikte cardscheme (bv Maestro, VISA)
paymentProfileId integer Betaaloptie ID dat bij de pintransactie is gebruikt. Je vindt een overzicht op https://admin.pay.nl/data/payment_profiles
Image
Voorbeeld van een pinbon

Pinbon

De pinbon die je genereert ziet er als volgt uit: Afbeelding: Voorbeeld van een pinbon

12.6. Statussen

Bij het controleren van de pintransactie status ontvang je één van de volgende statussen:

Statussen

Code Status Omschrijving
100 ImageAPPROVED De transactie is succesvol betaald.
20 -80 ImageHOST_CANCELLATION De terminal maakt na een betaling zelfstandig verbinding met de bank van de kaarthouder. De host wordt beheerd door de acquirer en staat niet in verbinding met het netwerk van PAY.
20 -80 ImageDEVICE_CANCELLATION Er is een fout opgetreden in de terminal waardoor de transactie is afgebroken. De klant heeft niet betaald.
20 -80 ImageUSER_CANCELLATION De gebruiker heeft de transactie geannuleerd op de terminal.
20 -80 ImageMERCHANT_CANCELLATION De transactie is op verzoek van de merchant geannuleerd.
20 -80 ImageTIMEOUT_EXPIRATION De klant heeft te lang gewacht met de betaling. De terminal wacht maximaal 45 seconden na het starten van de betaling.

12.7. Foutafhandeling

De onderstaande fouten kunnen optreden bij de /in-store API verzoeken:

Errorcode Errormessage
Transactions
9001 Transaction not found
9002 Transaction already paid
9003 9004 No merchant data was found for this transaction
Terminal transactions
9101 Terminal transaction not found
9103 No available terminals found
9104 Terminal not found
9105 Terminal not allowed (No merchant connection)
9106 Terminal transaction cannot be started
9107 Terminal transaction not yet final
9108 Terminal transaction not paid
9110 Unkown error starting the transaction
9111 Terminal transaction already confirmed
9112 An invalid email address has been submitted
Hardware / config issues
9201 The license period has not yet started
9202 The license period has ended
9203 Terminal not configured
9204 Terminal configuration missing
9205 Terminal not available
9206 Terminal in use
9207 Unsupported service version
9301 Unknown error calling WebService

12.8. Pinterminals ophalen

Om de beschikbare pinterminals voor een merchant op te halen, gebruik je de API Instore::getAllTerminals of een SDK.

Authenticatie

Basic Authentication

Authenticatie van de API Instore::getAllTerminals vindt plaats middels HTTP Basic Authentication.

Authenticatie vindt plaats middels de SDK function \Paynl\Config::setApiToken('<your-api-token>');

Request

Request code: Pinterminals ophalen

curl --request POST \
  --url https://rest-api.pay.nl/v2/Instore/getAllTerminals/json \
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \

In dit request voorbeeld halen we alle pinterminals op voor een merchant. De pinterminals worden opgehaald op basis van de API token die wordt meegestuurd ter authenticatie.

Parameters

De API Instore::getAllTerminals vereist geen parameters

Response

Response: Pinterminals ophalen

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "request": {
    "result": "1",
    "errorId": "",
    "errorMessage": ""
  },
  "terminals": [
    {
      "id": "TH-1234-5678",
      "name": "Demo terminal 1",
      "ecrProtocol": "WEB"
    },
    {
      "id": "TH-4567-8910",
      "name": "Demo terminal 2",
      "ecrProtocol": "WEB"
    }
  ]
}

In dit response ziet u de 2 pinterminals die gekoppeld zijn aan de merchant.

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result string 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
errorMessage string Als er een foutmelding is opgetreden dan vind je hier de omschrijving
terminals array Array met beschikbare pinterminals
Image array
id string Uniek ID van de pinterminal startend met 'TH-'. Dit ID heb je nodig om een pintransactie te starten
name string Naam van de pinterminal, deze kan naar keuze worden ingesteld via https://admin.pay.nl/instore/terminals
ecrProtocol string Manier van aansturen van de terminal. Alleen terminals die voor deze waarde 'WEB' teruggeven, kunnen middels de API aangestuurd worden

13. Cadeaukaarten (vouchers)

Via de Voucher API is het mogelijk om het saldo van een cadeaukaart te controleren en om vervolgens een bedrag van de kaart te boeken.

13.1. Controleren saldo

Om het saldo van een cadeaukaart te controleren, kan je gebruik maken van de API Voucher::info.

Authenticatie

Basic Authentication

Authenticatie van de API Voucher::info vindt plaats middels HTTP Basic Authentication.

Request code: Controleren saldo cadeaukaart

curl --request POST \
  --url https://rest-api.pay.nl/v1/Voucher/info/json \
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'cardNumber=6064123456789101112' \
  --data-urlencode 'pincode=123456'

Request

In dit request voorbeeld controleren we het saldo voor kaartnummer 6064123456789101112

Parameters

Paramater Type Omschrijving
cardNumber string VERPLICHT Het 19-cijferige kaartnummer van de cadeaukaart
pincode string OPTIONEEL De 6-cijferige pincode behorend bij de cadeaukaart

Response

Response: Controleren saldo cadeaukaart

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8


{
  "request": {
    "result": "1",
    "errorId": "",
    "errorMessage": ""
  },
  "card": {
    "type": "VVV Cadeaubon",
    "withPin": "1",
    "paymentOptionId": "1714",
    "paymentProfileName": "VVV Cadeaukaart",
    "profileIconUrl":"https://static.pay.nl/payment_profiles/100x100/1714.png",

    "balance": "5000",
    "services": [
     {
      "service": "SL-1234-5678"
     }
    ]
   }
}

In dit response zie je het saldo voor kaartnummer 6064123456789101112 in centen.

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result string 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
errorMessage string Als er een foutmelding is opgetreden dan vind je hier de omschrijving
card array Array met informatie over de cadeaukaart
type string Type cadeaukaart
withPin string 1: Cadeaukaart dient te worden verzilverd met pincode 0: Cadeaukaart kan zonder pincode verzilverd worden
paymentOptionId string Betaaloptie ID van de cadeaukaart
paymentProfileName string Naam van de cadeaukaart
profileIconUrl string URL van een 100x100 image van de cadeaukaart
balance string Saldo op de cadeaukaart in centen
services array Array met services waarvoor de cadeaukaart is geactiveerd
Image array
service string Service ID waarvoor deze cadeaukaart is geactiveerd. Een service ID start altijd met SL-

13.2. Belasten

Om een bedrag van de cadeaukaart te halen, kan je gebruik maken van de API Voucher::transaction.

Authenticatie

Basic Authentication

Authenticatie van de API Voucher::transaction vindt plaats middels HTTP Basic Authentication.

Request code: Belasten cadeaukaart

curl --request POST \
  --url https://rest-api.pay.nl/v1/Voucher/transaction/json \
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'cardNumber=6064123456789101112' \
  --data-urlencode 'pin=123456'
  --data-urlencode 'serviceId=SL-1234=5678'
  --data-urlencode 'amount=995' \
  --data-urlencode 'finishUrl=https://www.domain.com/return'

Request

In dit request voorbeeld belasten we kaartnummer 6064123456789101112 met € 9,95.

Parameters

Paramater Type Omschrijving
cardNumber string VERPLICHT Het 19-cijferige kaartnummer van de cadeaukaart
pin string VERPLICHT De 6-cijferige pincode behorend bij de cadeaukaart
serviceId string VERPLICHT Jouw verkooplocatie start met 'SL-' gevolgd door 8 cijfers. Je vindt een overzicht van jouw verkooplocatie(s) op https://admin.pay.nl/websites
amount integer VERPLICHT Het bedrag in centen dat van de cadeaukaart gehaald dient te worden
finishUrl integer VERPLICHT URL waar de bezoeker naar wordt doorgestuurd als de betaling is voltooid
description string OPTIONEEL Omschrijving van de order (maximaal 32 tekens)
currency string OPTIONEEL Valuta volgens ISO 4217 (drielettercode). Indien leeg wordt EUR gebruikt. Je vindt een overzicht op https://admin.pay.nl/data/currencies
statsData array OPTIONEEL
promotorId integer OPTIONEEL Het id van de promotor (webmaster)
info string OPTIONEEL Variabele 'info' die kan worden getraceerd in de statistieken
tool string OPTIONEEL Variabele 'tool' die kan worden getraceerd in de statistieken
extra1 string OPTIONEEL Vrije variabele 'extra1' die kan worden getraceerd in de statistieken. (advies: ID van de order)
extra2 string OPTIONEEL Vrije variabele 'extra2' die kan worden getraceerd in de statistieken. (advies: klant referentie)
extra3 string OPTIONEEL Vrije variabele 'extra3' die kan worden getraceerd in de statistieken

Response

Response: Belasten cadeaukaart

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "request": {
    "result": "1",
    "errorId": "",
    "errorMessage": ""
  },
  "transaction": {
    "transactionId": "EX-1234-4567-8910",
    "orderId": "105537291X770f36",
    "entranceCode": "1234abcd5678efgh",
    "cardName": "VVV Cadeaukaart"
}

In dit response zie je het resultaat voor het belasten van € 9,95 op kaartnummer 6064123456789101112.

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result string 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
errorMessage string Als er een foutmelding is opgetreden dan vind je hier de omschrijving
transaction array Array met informatie over de transactie
transactionId string Het unieke ID van de transactie startend met EX-
orderId string Unieke ID van de order
entranceCode string Unieke code gerelateerd aan de order
cardName string Cadeaukaart die werd gebruikt bij de transactie

14. Barcode payment

Een betaling via AliPay en WeChat wordt gestart middels het scannen van een QR- of barcode op een mobiele device.

14.1. Transactie proces

Image
Het proces m.b.t het starten en controleren van een QR- of barcode betaling

Het proces m.b.t het starten en controleren van een QR- of barcode betaling wordt hiernaast weergegeven.

14.2. Transactie starten

Voor het starten van een QR- of barcodebetaling binnen het PAY. platform gebruik je de API Transaction::QRpayment.

Authenticatie

Basic Authentication

Authenticatie van de API Transaction::QRpayment vindt plaats middels HTTP Basic Authentication.

Request

Request code: QR / barcode betaling starten

curl --request POST \
  --url https://rest-api.pay.nl/v13/Transaction/QRpayment/json \
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'scanData=102314355006117801' \
  --data-urlencode 'serviceId=SL-3490-4320' \
  --data-urlencode 'amount=100' \
  --data-urlencode 'description=My first payment'

In dit request voorbeeld starten we een QR betaling van € 1,- voor verkooplocatie SL-1234-5678 met de betaalmethode WeChat. De scanData begint in dit geval met '10' en bevat 18 cijfers.

Parameters

Paramater Type Omschrijving
scanData string VERPLICHT Gescande data van een QR- of barcode.
WeChat: scanData bevat 18 cijfers en begint met 10, 11, 12,13, 14 of 15
AliPay: scanData bevat tussen de 16 en 24 cijfers en begint met 25, 26, 27, 28, 29 of 30
serviceId string VERPLICHT Jouw verkooplocatie start met 'SL-' gevolgd door 8 cijfers. Je vindt een overzicht van jouw verkooplocatie(s) op https://admin.pay.nl/programs/programs
amount integer VERPLICHT Bedrag in centen, dus € 3,50 is 350
description string VERPLICHT Omschrijving van de order (maximaal 32 tekens)
currency string OPTIONEEL Valuta volgens ISO 4217 (drielettercode). Indien leeg wordt EUR gebruikt. Je vindt een overzicht op https://admin.pay.nl/data/currencies
statsData array OPTIONEEL
promotorId integer OPTIONEEL Het ID van de promotor (webmaster)
info string OPTIONEEL Variabele 'info' die kan worden getraceerd in de statistieken
tool string OPTIONEEL Variabele 'tool' die kan worden getraceerd in de statistieken
extra1 string OPTIONEEL Vrije variabele 'extra1' die kan worden getraceerd in de statistieken. (advies: ID van de order)
extra2 string OPTIONEEL Vrije variabele 'extra2' die kan worden getraceerd in de statistieken. (advies: klant referentie)
extra3 string OPTIONEEL Vrije variabele 'extra3' die kan worden getraceerd in de statistieken

Response

Response: Starten QR- of barcode betaling

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "request": {
    "result": "1",
    "errorId": "",
    "errorMessage": ""
  },
  "transaction": {
    "transactionId": "EX-1234-4567-8910",
    "orderId": "105537291X770f36",
    "entranceCode": "1234abcd5678efgh",
    "state": "100",
    "stateName": "SUCCES"
}

In dit response zie je het resultaat van het starten van een QR- of barcode betaling van van € 1,- voor verkooplocatie SL-1234-5678

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result string 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
errorMessage string Als er een foutmelding is opgetreden dan vind je hier de omschrijving
Transaction array Array met informatie over het resultaat van de transactie
transactionId string Het unieke ID van de gestarte transactie
orderId string
entranceCode string
state integer Code van de status. 100 = SUCCES
stateName string Naam van de status: SUCCES, CANCEL, DENIED of PENDING

15. IDIN

IDIN is een dienst die is ontwikkeld door banken, Een klant kan via IDIN een online identificatie uitvoeren. Bij het starten van een iDIN identificatie verzoek, geeft de merchant aan welke informatie hij wenst te ontvangen van de consument. De consument zal op de pagina waar bij de verificatie uitvoert, zien om welke informatie de merchant vraagt. Zodra de consument toestemming geeft, wordt de aangegeven informatie aan de merchant doorgegeven.

iDIN kan direct worden gebruikt, omdat de meeste Nederlandse banken het online identificatiemiddel al ondersteunen. iDIN werkt volgens hetzelfde principe als iDEAL: Bij het online identificeren, selecteert jouw klant iDIN als identificatiemethode en de bank waar hij een betaalrekening heeft. Vervolgens kan via de bekende betaalroute worden ingelogd door middel van een (e-)identifier of de bankieren app. De persoonlijke gegevens die jij van jouw klant wil ontvangen, wordt na deze login getoond in de iDIN-omgeving. Na akkoord voor het delen van deze informatie wordt het identificatieproces afgerond. Eenmalig inloggen via iDIN vereenvoudigt ook het inlogproces: toegangscodes en wachtwoorden zijn overbodig.

15.1. IDIN activatie

Wil je gebruik maken van IDIN stuur dan een e-mail met de onderstaande gegevens

Merchant-idM-....-....
Service-idSL-....-....

De M-code is gemakkelijk te vinden in het Admin Panel. Klik op het tabblad ''Merchant''. Vervolgens druk je op ''Bedrijfsgegevens''. De M-code vind je op de eerste regel in het overzicht. Het service-id vind je in de eerste kolom van het tabblad Verkooplocaties https://admin.pay.nl/programs/programs

15.2. getIssuers

Via de API IDIN::getIssuers kan een lijst opgehaald worden met banken die IDIN ondersteunen.

Authenticatie

Basic Authentication

Authenticatie van de API IDIN::getIssuers vindt plaats middels HTTP Basic Authentication

Request code: IDIN issuers ophalen

curl --request POST \
  --url https://rest-api.pay.nl/v1/IDIN/getIssuers/json \
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded'

Response

Response: IDIN issuers ophalen

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "request": {
    "result": "1",
    "errorId": "",
    "errorMessage": ""
  },
  "issuers": {
    "RABONL2U": {
      "issuerId": "RABONL2U",
      "issuerName": "Rabobank",
      "countryName": "Nederland",
      "countryCode": "NL"
    },
    "ABNANL2A": {
      "issuerId": "ABNANL2A",
      "issuerName": "ABN AMRO",
      "countryName": "Nederland",
      "countryCode": "NL"
    },
    "INGBNL2A": {
      "issuerId": "INGBNL2A",
      "issuerName": "ING",
      "countryName": "Nederland",
      "countryCode": "NL"
    },
    "SNSBNL2A": {
      "issuerId": "SNSBNL2A",
      "issuerName": "SNS",
      "countryName": "Nederland",
      "countryCode": "NL"
    },	
    "TRIONL2U": {
      "issuerId": "RABONL2U",
      "issuerName": "Triodos Bank",
      "countryName": "Nederland",
      "countryCode": "NL"
    },	
    "BUNQNL2A": {
      "issuerId": "BUNQNL2A",
      "issuerName": "bunq",
      "countryName": "Nederland",
      "countryCode": "NL"
    }		
  }
}

In dit response voorbeeld worden de IDIN issuers opgehaald

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result string 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
errorMessage string Als er een foutmelding is opgetreden dan vind je hier de omschrijving
issuers array Array met informatie over de issuers
Image array
issuerId string Identifier voor een issuer / bank (eg. RABONL2U)
issuerName string Naam van de issuer / bank (e.g. Rabobank).
countryName string Naam van het land waar de bank actief is (e.g Nederland)
countryCode string Aforting van de naam van het land waar de bank actief is (e.g NL)

15.3. Authenticeren

Het opvragen van de data van de consument gaat via de API IDIN:authenticate Bij de aanroep moet worden aangegeven welke informatie van de consument wordt gevraagd. Dit kan de merchant doen middels de "data" parameter. Door bij de gewenste opties de waarde "1" mee te geven, wordt de data van de consument opgevraagd.

Authenticatie

Basic Authentication

Authenticatie van de API IDIN::authenticate vindt plaats middels HTTP Basic Authentication

Request code: IDIN Authenticatie

curl --request POST \
  --url https://rest-api.pay.nl/v1/IDIN/authenticate/json \
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'serviceid=SL-1234-5678' \
  --data-urlencode 'reference=REF0003' \
  --data-urlencode 'issuerId=RABONL2U' \
  --data-urlencode 'data[name]=1' \
  --data-urlencode 'data[address]=1' \
  --data-urlencode 'data[isEighteen]=1 \
  --data-urlencode 'data[dateOfBirth]=1 \
  --data-urlencode 'data[gender]=1' \
  --data-urlencode 'data[email]=1' \
  --data-urlencode 'data[phone]=1' \
  --data-urlencode 'returnUrl=https://www.domain.com/return'

Request

In dit request voorbeeld maken we een IDIN authenticatie verzoek aan.

Parameters

Parameter Type Omschrijving
serviceId string VERPLICHT Jouw verkooplocatie start met 'SL-' gevolgd door 8 cijfers. Je vindt een overzicht van jouw verkooplocatie(s) op https://admin.pay.nl/websites
reference string VERPLICHT Referentie meegegeven door de merchant.
issuerId string VERPLICHT Identifier voor een issuer / bank (eg. RABONL2U).
data array VERPLICHT Array waarin wordt gespecificeerd welke data moet worden opgehaald. Mogelijke waarden: 0: niet ophalen, 1: wel ophalen.
name string VERPLICHT Naam van de consument, waaronder initialen, voor- en achternaam. Mogelijke waarden: 0 / 1.
address string VERPLICHT Adres van de consument (straatnaam, postcode, plaats, land) Mogelijke waarden: 0 / 1.
isEighteen string VERPLICHT Geeft aan of de consument 18 jaar of ouder is. Mogelijke waarden: 0 / 1.
dateOfBirth string VERPLICHT Geboortedatum van de consument. Mogelijke waarden: 0 / 1.
gender string VERPLICHT Sekse van de consument (male, female, not specified, unknown). Mogelijke waarden: 0 / 1.
email string VERPLICHT Emailadres van de consument (indien bekend). Mogelijke waarden: 0 / 1.
phone string VERPLICHT Telefoonnummer van de consument (indien bekend). Mogelijke waarden: 0 / 1.
returnUrl string VERPLICHT URL waarop de consument na zijn authenticatie moet terugkeren.
language string OPTIONEEL Taal voor het scherm van de bank. Mogelijke waarden: nl / en
exchangeUrl string OPTIONEEL URL waarop het resultaat van de authenticatie wordt gepost. (POST, form-data)

Response

Response: IDIN Authenticatie

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "request": {
    "result": "1",
    "errorId": "",
    "errorMessage": ""
  },
  "paymentDetails": {
    "trxid": "DA-1234-5678-1234",
    "ec": "7041b0c0b8ecfdbf40b04ef8d1b4896",
    "issuerUrl": "https://issuer.url"
  }
}

In dit response voorbeeld wordt het transactie ID van de authenticatie weergegeven en de URL waarnaar de eindgebruiker geredirect dient te worden om de authenticatie af te ronden.

200 application/json; charset=utf-8
Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
result string 0: request niet geslaagd, 1: request geslaagd
errorId string Als er een foutmelding is opgetreden dan vind je hier de foutcode
errorMessage string Als er een foutmelding is opgetreden dan vind je hier de omschrijving
paymentDetails array Array met informatie over de authenticatie
trxid string ID van de transactie die na het starten van het authenticatie verzoek wordt ontvangen, bijv. DA-1234-5678-1234
ec string Unieke referentie voor deze transactie
issuerUrl string URL waarnaar de eindgebruiker gestuurd dient te worden om de authenticatie af te ronden

15.4. Status

Na het afronden van de authenticatie wordt de data van de consument middels een exchange verzoek naar de merchant doorgestuurd. De merchant heeft de mogelijkheid om de data later nogmaals op te vragen via de API IDIN::status

Authenticatie

Basic Authentication

Authenticatie van de API IDIN::status vindt plaats middels HTTP Basic Authentication

Request code: status IDIN Authenticatie ophalen

curl --request POST \
  --url https://rest-api.pay.nl/v1/IDIN/status/json \
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'trxid=DA-1234-5678-1234'

Request

In dit request voorbeeld halen we de status op voor de authenticatie van transactie ID 'DA-1234-5678-1234'.

Parameters

Parameter Type Omschrijving
trxid string VERPLICHT Het transaction ID verkregen bij het aanmaken van de authenticatie, bv DA-1234-5678-1234

Response

Response: status IDIN Authenticatie ophalen

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "request": {
    "result": "1",
    "errorId": "",
    "errorMessage": ""
  },
  "data": {
    "reference": "REF0003",
    "id": "12345",
    "name": {
      "prefLastName": "Vries-Jansen",
      "prefLastNamePrefix": "de",
      "legalLastName": "Vries",
      "legalLastNamePrefix": "de",
      "partnerLastName": "Jansen",
      "partnerLastNamePrefix": "",
      "initials": "M",
      "firstName": "Mark"
    },
    "address": {
      "street": "Teststreet",
      "houseNo": "10",
      "houseNoSuf": "A",
      "addressExtra": "",
      "postalCode": "1234AB",
      "city": "Amsterdam",
      "country": "NL",
      "intAddressLine": ""
    },
    "dateOfBirth": {
      "dateOfBirth": "1975-07-25"
    },
    "isEighteen": {
      "is18OrOlder": "TRUE"
    },
    "gender": {
      "gender": "male"
    },
    "phone": {
      "phone": "+31612345678"
    },
    "email": {
      "email": "mail@domain.com"
    }
  }
}

In dit response zie je het resultaat van het ophalen van de status voor de authenticatie met transactie ID 'DA-1234-5678-1234'.

200 application/json; charset=utf-8
Name Type Description
request array Array with information about the result of the request
result string 0: request failed, 1: request successful
errorId string If an error message has occurred, you will find the error code here
errorMessage string If an error message has occurred, you will find the description here
data array Array met authenticatie data
reference string Referentie meegegeven door de merchant.
id string
name array Array met de naam van de consument
prefLastName string (eg. "Vries-Jansen")
prefLastNamePrefix string (eg. "de")
legalLastName string (eg. "Vries")
legalLastNamePrefix string (eg. "de")
partnerLastName string (eg. "Jansen")
partnerLastNamePrefix string (eg. "de")
initials string (eg. "VJ")
firstName string (eg. "Vincent")
address array Array met adresgegevens
street string (eg. "Pascalstreet")
houseNo string (eg. "19")
houseNoSuf string (eg. "A")
addressExtra string (eg. "")
postalCode string (eg. "0000AA")
city string (eg. "Aachen")
country string (eg. "DE")
intAddressLine string (eg. "")
dateOfBirth array Array met geboortedatum
dateOfBirth string (eg. "1975-07-25")
isEighteen array Array met leeftijdsinformatie
is18OrOlder string (eg. "TRUE" / "FALSE")
gender array Array met informatie over het geslacht
gender string (eg. "male"/"female"/"unknown"/"not specified")
phone array Array met informatie over het telefoonummer
phone string (eg. "+31203051900")
email array Array met informatie over het emailadres
email string (eg. "info@domain.com")

15.5. Exchange calls

Na het afronden van de authenticatie wordt de data van de consument middels een POST verzoek doorgestuurd naar uw exchange URL

Parameters

Paramater Omschrijving
request Array with information about the result of the request
result 0: request failed, 1: request successful
errorId If an error message has occurred, you will find the error code here
errorMessage If an error message has occurred, you will find the description here
data Array met authenticatie data
state Indicates indicates whether the authentication has been successful. TRUE / FALSE.
statusMessage String indicating the status of the authentication.
reference Referentie meegegeven door de merchant.
trxid ID of the transaction which has been created while starting the request. E.g DA-3751-0025-4000
name Array met de naam van de consument
prefLastName (eg. "Vries-Jansen")
prefLastNamePrefix (eg. "de")
legalLastName (eg. "Vries")
legalLastNamePrefix (eg. "de")
partnerLastName (eg. "Jansen")
partnerLastNamePrefix (eg. "de")
initials (eg. "VJ")
firstName (eg. "Vincent")
address Array met adresgegevens
street (eg. "Pascalstreet")
houseNo (eg. "19")
houseNoSuf (eg. "A")
postalCode (eg. "0000AA")
city (eg. "Aachen")
country (eg. "DE")
intAddressLine (eg. "")
isEighteen (eg. "TRUE" / "FALSE")
dateOfBirth (eg. "1975-07-25")
gender (eg. "male"/"female"/"unknown"/"not specified")
phone (eg. "+31203051900")
email (eg. "info@domain.com")

16. Exchange (notificaties)

Een exchange call is een signaal van PAY. naar jouw webshop om aan te geven dat een order een nieuwe status heeft gekregen. De webshop kan vervolgens de betreffende order updaten zodat de status overeenkomt met de status in het PAY. Admin Panel. Het signaal dat PAY. aan jouw webshop geeft, is feitelijk een script (URL) dat wij aanroepen op jouw server. Als PAY. het juiste antwoord van dit script terugkrijgt, weten wij dat de nieuwe orderstatus correct door jouw systeem is verwerkt. Het script dat wordt aangeroepen door PAY. noemen wij de communicatie- of exchange URL.


16.1. Parameters

Bij het aanroepen van de exchange / communicatie URL stuurt PAY. een aantal POST / GET parameters mee.

Voorbeeld exchange call

https://www.domain.com/exchange/?action=pending&order_id=819034534X2b5a00&payment_session_id=819034534&ip_address=1.2.3.4amount=9.99&extra1=order%20123&extra2=klant%20123&extra3=factuur%20123&info=facebook_campaign

De feitelijke aanroep kan meer parameters bevatten afhankelijk van de betaaloptie.

Parameters

Parameter Omschrijving
action Die actie die heeft plaatsgevonden, klik hier voor meer info over het moment van aanroep
order_id Het order ID. Hiermee verifieer je de actuele status van de order
payment_session_id Het betaalsessie ID van de order
ip_address IP-adres van de gebruiker
amount Het bedrag van de transactie
extra1 Vrije variabele 'extra1' die kan worden getraceerd in de statistieken. Deze variable kan worden meegegeven bij het starten van de transactie
extra2 Vrije variabele 'extra2' die kan worden getraceerd in de statistieken. Deze variable kan worden meegegeven bij het starten van de transactie
extra3 Vrije variabele 'extra3' die kan worden getraceerd in de statistieken. Deze variable kan worden meegegeven bij het starten van de transactie
info Vrije variabele 'info' die kan worden getraceerd in de statistieken. Deze variable kan worden meegegeven bij het starten van de transactie

Let op: bij de exchange URL ontvang je de parameters in snakecase: order_id. Bij de return URL is dit camelcase: orderId

16.2. Verplichte beantwoording

Om te controleren of een verzoek goed is aangekomen, verwachten wij een antwoord in TXT formaat van jouw server. Dit antwoord moet bestaan uit TRUE. Indien je geen TRUE teruggeeft dan beschouwt PAY. de aanroep als niet geslaagd en treedt, indien ingesteld, het retry scheme in werking.

16.3. Verwerken exchange call

Voorbeeld code: Exchange verzoek verwerken

<?php 
# Setup API Url
$strUrl = "https://rest-api.pay.nl/v13/Transaction/info/array_serialize?"; 

# Add arguments
$arrArguments = array();
$arrArguments['transactionId'] = filter_var($_GET['order_id']);

# Prepare complete API URL
$strUrl = $strUrl . http_build_query($arrArguments);
$objCurl = curl_init($strUrl);
curl_setopt($objCurl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($objCurl, CURLOPT_USERAGENT, "Pay.nl Api Example");
curl_setopt($objCurl, CURLOPT_TIMEOUT, 5);
curl_setopt($objCurl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($objCurl, "token:<your-api-token>");
$strReturnData = curl_exec($objCurl);
curl_close($objCurl);

# Process result
$strMessage = '';
$arrResult = unserialize($strReturnData);
if(isset($arrResult['paymentDetails']['stateName'])) {

    if($arrResult['paymentDetails']['stateName'] == 'PAID') {
        # Execute code to process the order       

        $strMessage = 'Order processed';
    }
    elseif($arrResult['paymentDetails']['stateName'] == 'CANCEL') {
        # Payment canceled, restock items

        $strMessage = 'Order canceled';
    }
}

echo 'TRUE|'.$strMessage;

Het is van belang dat je de transactie verwerkt via de exchange URL en niet via de return URL. Niet elke klant komt namelijk op de return URL omdat men in sommige gevallen na de betaling het betaalscherm direct wegklikt. De return URL is daarom enkel bedoeld om de klant te laten weten of een betaling is geslaagd.

De exchange URL wordt in tegenstelling tot de return URL altijd aangeroepen. Dit is daarom ook de plek om een order in jouw backoffice te verwerken. Onder het verwerken van een order verstaan we bijvoorbeeld het updaten van een status in jouw database, het versturen van facturen / e-mails etc.

Status verifieren

Verifieer altijd de status van een transactie m.b.v de parameter order_id zoals in het PHP code voorbeeld. Ga dus niet uit van de parameter action om de status te bepalen, deze zou immers handmatig aangepast kunnen zijn in de URL.


16.4. Logging

Image
Exchange verzoeken via transactie details

De resultaten van een exchange calls kan je op twee plaatsen terug vinden, namelijk: (1) via de transactiedetails en (2) de 'Payment state log'. Geslaagde exchange calls worden voorzien van het volgende icoon Image Mislukte verzoeken worden weergegeven via het icoon Image

Image
Exchange verzoeken via Payment state log

Transactiedetails

Om de exchange verzoeken van één transactie te bekijken, voer je de onderstaande stappen uit:

  • In het Admin Panel kies je in het menu de optie Transacties » Totaaloverzicht
  • Zoek de transactie op waarvan je de exchange verzoeken wil bekijken.
  • Klik op de 'EX-code' of het vergrootglas-icoon van de transactie. Er wordt een popup geopend waar je alle details van de betreffende transactie vindt.
  • Onderaan de popup, bij 'Communicatie informatie', zie je de resultaten van de exchange verzoeken die voor deze transactie zijn uitgevoerd.

Payment state log

Het ''Payment state log'' is een overzicht van alle exchange verzoeken tussen PAY. en jouw server. Je vindt dit overzicht via het Admin Panel menu: Rapportages » Payment state log.

Via de link in de kolom ''Opties'' verkrijg je alle details van de transactie, inclusief de aangeroepen URL en het volledige antwoord dat wij van jouw server hebben ontvangen.

Foutoplossingen

In het ''Payment state log'' vind je o.a de HTTP Code terug. Indien deze niet de waarde 200 heeft dan is er een fout opgetreden. Via de online checklist kun je achterhalen hoe je de meest voorkomende problemen kan oplossen.

Trage exchange calls (timeout)

De standaard timeout tijd van de exchange is 5000 ms (5 seconden). In zeer uitzonderlijke gevallen kunnen wij deze tijd voor jou verhogen. Indien jouw exchange traag is, zal de gebruiker na de betaling moeten wachten totdat de exchange reageert of totdat de timeout tijd is verstreken. Indien er een langere timeout dan 5 seconden wordt gekozen, is de kans groot dat jouw klant de pagina ververst of helemaal afsluit.

16.5. Beveiliging

Het is aan te raden jouw exchange URL te beveiligen zodat kwaadwilligen geen verzoeken naar dit script kunnen doen. Je bent er dan tevens van verzekerd dat elk verzoek echt van PAY. afkomstig is.

Hiervoor heeft PAY. een lijst met IP-adressen van de PAY. servers beschikbaar. Als een verzoek van één van die IP-adressen afkomstig is, dan weet je zeker dat het verzoek van ons afkomstig is.

Eventueel kan je deze controle ook automatiseren met behulp van één van onze API's: API_Validate_v1::isPayServerIp of API_Validate_v1::getPayServerIps


16.6. Momenten van aanroep

Voorbeeld: Exchange verzoek

# Aanroep communicatie URL vanuit PAY.
https://www.domain.com/exchange/?action=new_ppt&order_id=819034534X2b5a00&...

Afhankelijk van de betreffende betaalmethode zijn er verschillen in de aanroep van de communicatie URL. Zo kunnen de momenten waarop de communicatie URL wordt aangeroepen verschillen en kunnen ook de waarden van de parameter Dynamic Payments Exchange action verschillen. Hieronder zie je een overzicht van de verschillen per betaalmethode.

Algemeen

De onderstaande momenten van aanroep gelden voor alle betaalopties met uitzondering van incasso en telefonie.

Action Moment van aanroep
new_ppt Vlak nadat een betaling succesvol is voltooid.
pending OPTIONEEL Vlak na het starten van de betaling. Van toepassing als 'status communicatie' bij de communicatie URL in het dienstenscherm aangevinkt is.
cancel OPTIONEEL Vlak nadat een betaling is beëindigd of verlopen. Van toepassing als 'status communicatie' bij de communicatie URL in het dienstenscherm aangevinkt is.
verify Vlak nadat we een transactie als 'verdacht' hebben gekenmerkt. Feitelijk houdt dit in dat PAY. de transactie nog niet goed- of afkeurt en dat de status middels een extra controle moet worden bepaald.
capture OPTIONEEL Vlak nadat de autorisatie is omgezet naar een capture. Alleen van toepassing wanneer autocapture (default) is uitgeschakeld.
getOrder OPTIONEEL Wordt gebruikt bij Dynamic Payments om de ordergegevens op te halen. Zie voor meer informatie: Dynamic Payments Exchange.
transaction:fraudnotice OPTIONEEL Je ontvangt deze action om aan te geven dat er een fraudemelding is binnengekomen voor de betreffende creditcard transactie.

Creditcard

Voor creditcard gelden de momenten van aanroep zoals in de bovenstaande tabel weergegeven. Er zijn echter nog enkele extra aanroepen van toepassing voor deze betaaltopie:

Action Moment van aanroep
chargeback:chargeback Vlak nadat een creditcard transactie als 'chargeback' is gekenmerkt. Dit betreft een verzoek van een kaarthouder aan zijn bank om bij klacht of betwisting een eerder verrichte transactie te onderzoeken.
chargeback:revert OPTIONEEL Je ontvangt deze action om aan te geven dat er een chargeback is teruggedraaid.

Klarna en Riverty

Voor Klarna en Riverty gelden de momenten van aanroep zoals in de algemene tabel weergegeven. Er zijn echter nog enkele extra aanroepen van toepassing voor deze betaalopies:

Action Moment van aanroep
capture OPTIONEEL Vlak nadat de autorisatie is omgezet naar een capture. Alleen van toepassing wanneer autocapture (default) is uitgeschakeld.

Incasso

Voor de betaaloptie incasso gelden de onderstaande momenten van aanroep:

Action Moment van aanroep
incassoadd Vlak nadat PAY. de incasso heeft opgepakt en heeft verwerkt tot een bankopdracht.
incassosend Vlak nadat de incasso-opdracht verstuurd is naar de bank.
incassopending
incassocollected Vlak nadat het geïncasseerde bedrag binnen is gekomen op de rekening van PAY. Vanaf dit moment is het ook beschikbaar in jouw boeksaldo.
incassostorno Vlak nadat het geïncasseerde bedrag is gestorneerd van onze rekening. Dit kan optreden tot en met 56 kalenderdagen na het ontvangen van de 'incassocollected'.

Telefonie

Voor de betaaloptie telefonie gelden de onderstaande momenten van aanroep:

Action Moment van aanroep
add Vlak na het starten van de betaling.
delete Vlak nadat de betaling is afgebroken / beëindigd.

Refunds

Voor terugbetalingen gelden de onderstaande momenten van aanroep:

Action Moment van aanroep
refund:add Deze notificatie ontvang je tijdens het aanroepen van de refund:API of indien er uit de Admin van PAY. een refund wordt aangemaakt. Zo blijft jouw systeem op de hoogte van refunds die vanaf externe platforms worden uitgevoerd.
refund:received Vlak nadat een betaling is teruggeboekt. Bij achteraf betalen, cadeaukaarten en creditcard worden deze direct verwerkt. IBAN refunds worden in een batch geplaatst en worden 's ochtends rond 10:00 uur door de bank verwerkt.
refund:send Vlak nadat de refundbatch door de batch is verwerkt. Alleen van toepassing op IBAN refunds.
refund:storno Een aangemaakte refund kon niet worden verwerkt. Een voorbeeld is een refund naar een IBAN nummer dat is opgeheven / geblokkeerd.

16.7. Het exchangeproces

Image
De verschillende stappen in het exchangeproces

Het exchangeproces verloopt in verschillende stappen die in de afbeelding hiernaast worden weergegeven.

Uitleg van het exchange proces

  1. Issuer informeert PAY.

    PAY. ontvangt het signaal van een issuer dat er een nieuwe status is voor een specifieke transactie. Op basis van deze transactie bepaalt PAY. de dienst van de webshop en de bijbehorende communicatie / exchange URL.

  2. Aanroep exchange URL

    PAY. roept de communicatie / exchange URL van de webshop aan om de nieuwe status van de transactie door te geven.

  3. Antwoord exchange URL

    De webshop verwerkt de status van de transactie in haar eigen systeem. Als alles correct verwerkt is dan retourneer je als antwoord TRUE.

  4. Retry scheme

    Als de exchange URL niet voldoet aan de verplichte beantwoording dan treedt het retry scheme in werking en wordt de exchange URL wederom aangeroepen tot PAY. het gewenste antwoord TRUE ontvangt.

16.8. Instellen

Om verbinding met jouw server te kunnen maken, moet PAY. vanzelfsprekend weten welke URL er aangeroepen dient te worden. Deze communicatie URL kan je als volgt instellen:

  • Bij de betreffende verkooplocatie via het Admin Panel
  • Bij het starten van een transactie
Image
Het wijzigen van de verkooplocatie waar je een exchange URL voor in wil stellen.

Bij een verkooplocatie via het Admin Panel

Om de exchange URL via het Admin Panel in te stellen, volg je de volgende stappen:

  • Kies in het Admin Panel het tabblad Verkooplocaties en klik op de link 'wijzigen' van de verkooplocatie waar je een exchange URL voor in wil stellen.
  • Bij het veld 'Exchange instellen' selecteer je: 'Ja, een custom communicatie URL gebruiken'.
  • Voer vervolgens jouw exchange / communicatie URL in en selecteer in welk formaat je de parameters wenst te onvangen:
    • TXT(POST) - standaard setting
    • TXT(GET)
    • XML(POST)
    • JSON(POST)
  • Stel een retry scheme in via het veld 'Aanroep herhalen' en sla de wijzigingen op.

Bij het starten van een transactie

Request code: Exchange URL instellen

curl --request POST \
  --url https://rest-api.pay.nl/v13/Transaction/start/json \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'token=<your-api-token>' \
  --data-urlencode 'serviceId=SL-3490-4320' \
  --data-urlencode 'amount=100' \
  --data-urlencode 'ipAddress=1.2.3.4' \
  --data-urlencode 'finishUrl=https://www.domain.com/return' \
  --data-urlencode 'paymentOptionId=739' \
  --data-urlencode 'transaction[description]=My first payment' \
  --data-urlencode 'transaction[orderExchangeUrl]=https://www.domain.com/exchange' \

De exchange URL kan je instellen bij het starten van een transactie via de optionele variabele transaction['orderExchangeUrl'] van de API Transaction::start

Het instellen van een retry scheme is niet mogelijk via een API. Dit dien je dus per verkooplocatie in te stellen via het Admin Panel.

Request

In dit request voorbeeld starten we een transactie met exchange URL 'https://www.domain.com/exchange'.

17. Return URL

Nadat de klant de betaling heeft afgerond, wordt deze doorgestuurd naar de return URL (ook wel finish URL). Op de return URL kan je bijvoorbeeld de klant bedanken voor een bestelling of terugsturen naar de check-out pagina wanneer een betaling is mislukt.

17.1. Instellen

Request code: Return URL instellen

curl --request POST \
  --url https://rest-api.pay.nl/v13/Transaction/start/json \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'token=<your-api-token>' \
  --data-urlencode 'serviceId=SL-3490-4320' \
  --data-urlencode 'amount=100' \
  --data-urlencode 'ipAddress=1.2.3.4' \
  --data-urlencode 'finishUrl=https://www.domain.com/return' \
  --data-urlencode 'paymentOptionId=739' \
  --data-urlencode 'transaction[description]=My first payment' \

De return URL kan je instellen bij het starten van een transactie via de verplichte variabele finishUrl van de API Transaction::start

Request

In dit request voorbeeld starten we een transactie met return URL 'https://www.domain.com/return'.

17.2. Parameters

Bij het aanroepen van de return URL stuurt PAY. een aantal GET parameters mee.

Voorbeeld return URL call

https://www.domain.com/return/?orderId=819034534X2b5a00&orderStatusId=100&paymentSessionId=819034534

Parameters

Paramater Omschrijving
orderId Het order ID. Hiermee verifieer je de actuele status van de order
orderStatusId De statuscode van de order
paymentSessionId Het betaalsessie ID van de order

Let op: Bij de return URL ontvang je de parameters in camelcase: orderId. Bij de exchange URL is dit snakecase: order_id

17.3. Verwerken return URL call

Voorbeeld code: Exchange verzoek verwerken

<?php 
# Setup API Url
$strUrl = "https://rest-api.pay.nl/v13/Transaction/info/array_serialize?"; 

# Add arguments
$arrArguments = array();
$arrArguments['transactionId'] = filter_var($_GET['orderId']);

# Prepare complete API URL
$strUrl = $strUrl . http_build_query($arrArguments);
$objCurl = curl_init($strUrl);
curl_setopt($objCurl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($objCurl, CURLOPT_USERAGENT, "Pay.nl Api Example");
curl_setopt($objCurl, CURLOPT_TIMEOUT, 5);
curl_setopt($objCurl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($objCurl, "token:<your-api-token>");
$strReturnData = curl_exec($objCurl);
curl_close($objCurl);

# Process result
$strMessage = '';
$arrResult = unserialize($strReturnData);
if(isset($arrResult['paymentDetails']['state'])) {

    if($arrResult['paymentDetails']['state'] == '100') {
        # Payment succesful       

        $strMessage = 'Thank you for the order';
    }
    elseif($arrResult['paymentDetails']['state']  0) {
        # Payment canceled, optionally send customer back to the checkoutpage

        $strMessage = 'Your order has been canceled';
    }
    elseif($arrResult['paymentDetails']['state'] >= 0) {
        # Payment pending

        $strMessage = 'Your payment is being processed';
    }
}

echo $strMessage;

Het is van belang dat je de return URL enkel gebruikt voor het weergeven van een status c.q terugsturen naar een winkelmandje. Een aanzienlijk percentage van de bezoekers klikt na de betaling het betaalscherm direct weg en bereikt dus nooit jouw return URL.

De return URL is daarom ook niet geschikt om een order te verwerken. Hiervoor dien je de exchange URL te gebruiken omdat je er dan van verzekerd bent dat deze altijd door ons platform wordt aangeroepen.

Openstaande status

Bij betaalmethoden als iDEAL en Bancontact is de eindstatus van de betaling vaak al bekend wanneer de klant op de return URL terecht komt. Dit hoeft echter niet altijd het geval te zijn (bijvoorbeeld bij bankoverboekingen of in het geval van een vertraging bij de issuer). De status is dan pending

Voor de openstaande creditcardstatus verify is speciale aandacht vereist. PAY. beoordeelt elke creditcardtransactie op 10 punten. Bij een negatieve score wordt de transactie als verdacht gekenmerkt. Hiermee wordt de status omgezet naar verify. Feitelijk houdt dat in dat PAY. de betaling nog niet goed- of afkeurt en dat de status middels een extra controle moet worden bepaald.

Als de de betaling nog steeds Imagewachtende is en er nog geen eindstatus bekend is dan raden wij jou aan een melding in de trant van: "Jouw betaling wordt op dit moment verwerkt, zodra de betaling is verwerkt ontvang je een bevestiging per e-mail" op jouw return URL te laten zien. Je voorkomt hiermee dat de klant denkt dat de betaling is mislukt en dat hij het bestelproces opnieuw moet doorlopen.

18. Authenticatie-methoden

# Omschrijving
0 (Kaart)gegevens invoer
1 QR 2 APP Betaling
2 Browser 2 QR
3 Mobile 2 APP
4 QR or Barcode betaling
5 UNIFIED QR
6 Apple Pay Button
7 MOTO
8 SCA - 3DS1.0
9 SCA - 3DS2 (Frictionless)
10 SCA - 3DS2 (Challenged)
11 Getokeniseerd
12 Google Pay button
13 SCA Exemption (TRA)
14 SCA - Exemption
15 3DS Authenication failover
16 Pincode bevestigd
17 NFC zonder pincode
18 Mobiele betaling
19 SCA - Corporate Exemption
20 Card on File by cardholder Initiation
21 Payment Based Checkout
22 Merchant Approved Transaction
23 Kaartlezen + Pin

Login