NAV

1. Introductie Alliance Partnership

De ideale oplossing voor SaaS-oplossingen en platformen

Met het Alliance Partnership geef je jouw klanten direct toegang tot een breed scala aan betaaloplossingen en PAY. features onder één overeenkomst. Als Alliance Partner hoef je slechts eenmalig een technische integratie te maken met ons platform. Gefactureerde abonnements-, platform-, marketing- en transactiekosten kunnen worden verrekenend met het boeksaldo van de ondernemer. En PAY? Wij zorgen voor gestroomlijnde betalingen en innovatieve (betaal)oplossingen.

2. Aan de slag

Welke partijen kunnen een Alliance Partnership aangaan met PAY?

Het Alliance Pakket is uitermate geschikt voor Saas-oplossingen en platformen waar derde partijen bij betrokken zijn. Enkele voorbeelden:

  • Donatiewebsites (die betalingen ontvangen voor meerdere goede doelen).
  • Facturatieplatformen en debiteurenmanagementsystemen.
  • Productvergelijkingssites (of apps) en marketplaces die betalingen ontvangen voor vele aanbieders.
  • Franchiseketens (de franchisefee kan bijvoorbeeld direct worden verrekend met de geboekte omzet)
  • Etenbestelwebsites met meerdere restaurants.
  • Ticketingplatformen met verschillende eventorganisatoren, zoals theaters, musea, festivals, poppodia.
  • Reserveringssystemen in de breedste zin van het woord voor bijvoorbeeld vakantieparken, sportscholen

3. Het onboarden van Submerchants

Om op je platform betalingen voor Submerchants te kunnen verwerken, moet deze eerst een account hebben in PAY. In onderstaande documentatie leggen we uit hoe je een Submerchant-account aan kunt maken via de API. Ook is het mogelijk om via het Submerchant beheerscherm in PAY. een submerchant manueel aan te maken door het invoeren van een formulier.

Als de aanmelding op een correcte manier wordt aangeleverd, kan er in de meeste gevallen direct begonnen worden met verwerken van transacties. PAY. heeft een wettelijke verplichting om klanten te screenen om zo witwassen en financiering terrorisme te voorkomen. Om dit te kunnen doen, worden er een aantal documenten en gegevens gevraagd. Als deze documenten zijn aangeleverd en door het onboardingsteam zijn gecontroleerd, wordt de Submerchant in zijn geheel gecontroleerd op een aantal factoren. Zodra deze checks gedaan zijn, kunnen de ontvangen tegoeden door PAY. worden uitbetaald.

3.1. Submerchants toevoegen

Request code: Add Submerchant

  
    curl --request POST \
    --url https://rest-api.pay.nl/v16/Alliance/addMerchant/json \
    --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data-urlencode 'merchant[name]=Test Alliance Submerchant' \
    --data-urlencode 'merchant[coc]=123456178' \
    --data-urlencode 'merchant[vat]=NL12345678B01' \
    --data-urlencode 'merchant[street]=Kopersteden' \
    --data-urlencode 'merchant[houseNumber]=10' \
    --data-urlencode 'merchant[houseNumberAddition][email protected]' \
    --data-urlencode 'merchant[postalCode]=7547TK' \
    --data-urlencode 'merchant[city]=Enschede' \
    --data-urlencode 'merchant[contactEmail][email protected]' \
    --data-urlencode 'merchant[contactPhone]=+31888866622' \
    --data-urlencode 'accounts[0][email][email protected]' \
    --data-urlencode 'accounts[0][firstname]=John' \
    --data-urlencode 'accounts[0][lastname]=Doe' \
    --data-urlencode 'accounts[0][dateOfBirth]=21-12-2001' \
    --data-urlencode 'accounts[0][placeOfBirth]=Spijkenisse' \
    --data-urlencode 'accounts[0][gender]=M' \
    --data-urlencode 'accounts[0][authorizedToSign]=1' \
    --data-urlencode 'accounts[0][ubo]=0' \
    --data-urlencode 'accounts[0][uboPercentage]=0' \
    --data-urlencode 'accounts[0][useCompanyAuth]=1' \
    --data-urlencode 'accounts[0][hasAccess]=1' \
    --data-urlencode 'accounts[0][language]=4' \
    --data-urlencode 'accounts[1][email][email protected]' \
    --data-urlencode 'accounts[1][firstname]=Dagobert' \
    --data-urlencode 'accounts[1][lastname]=Duck' \
    --data-urlencode 'accounts[1][dateOfBirth]=13-12-1937' \
    --data-urlencode 'accounts[1][placeOfBirth]=Spijkenisse' \
    --data-urlencode 'accounts[1][gender]=M' \
    --data-urlencode 'accounts[1][authorizedToSign]=0' \
    --data-urlencode 'accounts[1][ubo]=1' \
    --data-urlencode 'accounts[1][uboPercentage]=95' \
    --data-urlencode 'accounts[1][useCompanyAuth]=0' \
    --data-urlencode 'accounts[1][hasAccess]=0' \
    --data-urlencode 'accounts[1][language]=1' \
    --data-urlencode 'bankAccount[bankAccountOwner]=CompanyAccount' \
    --data-urlencode 'bankAccount[bankAccountNumber]=NL01PAYL0001234567' \
    --data-urlencode 'bankAccount[bankAccountBic]=NLPAYNL2A' \
    --data-urlencode 'settings[package]=03-07-2017' \
    --data-urlencode 'settings[sendEmail]=1' \
    --data-urlencode 'settings[settleBalance]=1' \
    --data-urlencode 'settings[clearingInterval]=week' \
    --data-urlencode 'settings[referralProfileId]=CP-####-####' \

  

Request

In dit request voorbeeld voegen wij een merchant toe vanuit een Alliantie partner account.

Parameters

Parameter Type Veld Omschrijving
Merchant array VERPLICHT Bedrijfsgegevens toevoegen van een submerchant
array {
name string Bedrijfsnaam
coc string KvK nummer van het bedrijf
vatNumber string BTW nummer
street string Straatnaam van het bedrijf
houseNumber string Huisnummer van het bedrijf
houseNumberAddition string Toevoeging huisnummer
postalCode string Postcode van het bedrijf
city string Plaats waar het bedrijf is gevestigd
countryCode string Land waar het bedrijf is gevestigd }
contactEmail string OPTIONEEL Email adres voor klanten om contact op te nemen met de verkoper
contactPhone string OPTIONEEL Telefoonnummer voor klanten om contact op te nemen met de verkoper
Accounts array VERPLICHT Array van gebruikeraccounts die aan de submerchant gekoppeld dienen te worden. Voeg tenminste 1 gebruikersaccount toe.
array {
email string Email adres van de gebruiker
firstname string Voornaam van de gebruiker
lastname string Achternaam van de gebruiker
gender string Geslacht van de te registreren gebruiker.Beschikbare opties:
male
female
authorizedToSign string Geeft aan of de gebruiker bevoegd is om te tekenen. Beschikbare opties:
0: NEE
1: JA, volledig/zelfstandig tekenbevoegd
2: JA, gezamenlijk tekenbevoegd
ubo integer Geeft aan of de gebruiker een UBO is. Beschikbare opties:
0: NEE
1: JA
uboPercentage string Geeft het UBO percentage aan in alleen getallen (bijvoorbeeld 25 voor 25%)
hasAccess string Geeft aan of het gebruikersaccount toegang heeft tot het merchant account. Beschikbare opties:
0: NEE, gebruik deze optie wanneer je alleen een UBO wilt registreren (en niet per se toegang nodig heeft)
1: JA, gebruik heeft toegang tot het merchant account
languageId string Taal voorkeur voor de te registreren gebruiker. Hier geef je een ID mee. Beschikbare opties op te halen via language::getAll
Voorbeelden: 1:NL, 2:BE, 4:EN, 5:DE, 6:FR, 8:ES

Response: Alliance::addMerchant

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

{ "success": "1", "error_field": "", "error_message": "", "merchantId": "M-####-####", "merchantToken": "***********", "accounts": [ { "accountId": "A-####-####", "email": "[email protected]" }, { "accountId": "A-####-####", "email": "[email protected]" } ] }

Response

In dit response voorbeeld zie je het resultaat van aanroepen van de alliance::addMerchant API.

200 application/json; charset=utf-8
Naam Type Omschrijving
succes boolean 0: request niet geslaagd, 1: request geslaagd
error_field 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
merchantID string De unieke referentiecode naar het zojuist aangemaakte Submerchant-account
merchantToken string Alle acties binnen het submerchantaccount kunnen worden uitgevoerd worden met het API token van de Alliance. Echter kan het soms handig zijn om een Submerchantspecifiek token te gebruiken voor bepaalde zaken.
accounts array Een array met de zojuist aangemaakte accounts van de bestuurders, ubo's en medewerkers.
accountId string De accountcode van de aangemaakte gebruiker (A-####-####)
email string E-mailadres van de zojuist aangemaakte gebruiker.

3.2. Enkele merchant ophalen

Request code: Add Submerchant

  
    curl --request POST \
    --url https://rest-api.pay.nl/v16/Alliance/getMerchant/json \
    --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data-urlencode 'merchantId=M-###-####' \

Request

In dit voorbeeld halen we gegevens op van een enkele handelaar. Met deze oproep kunt u onder andere de volgende informatie ophalen:

  • Naam verkoper
  • Geactiveerde betaalmethoden (services)
  • Boek saldo (saldo)
  • Status van aan te leveren documenten
  • Gebruikers toegevoegd
  • Gekoppelde bankrekening
  • Bedrijfsgegevens (adres, KvK-nummer)
  • Openbare contactgegevens
  • Toegestaan om saldo te belasten
  • Wanneer het account is aangemaakt/geaccepteerd/verwijderd

Parameters

Parameter Type Veld Omschrijving
merchantId array VERPLICHT De ID van de handelaar die u wilt ophalen (M-code)

Response: Alliance::getMerchant

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

{ "request": { "result": "1", "errorId": "", "errorMessage": "" }, "merchantId": "M-####-####", "merchantName": "Classic Carparts BV", "services": [ {, "serviceId": "SL-####-####", "serviceName": "Classic Carparts Diner" { "serviceId": "SL-####-####", "serviceName": "Classic Carparts Burger Delivery" } ], "balance": "125343", "documents": [ { "id": "D-####-####", "type_id": "agreement", "type_name": "Overeenkomst", "status_id": "2", "status_name": "Wacht op goedkeuring", "expires": "" }, { "id": "D-####-####", "type_id": "coc_extract", "type_name": "KvK uittreksel", "status_id": "4", "status_name": "Afgekeurd", "expires": "" } ], "accounts": [ { "id": "AL-####-####", "account_id": "A-####-####", "name": "John Doe", "accepted": "1", "access": "1", "ubo": "0", "authorised_to_sign": "1", "signature_label": "Volledig/ Zelfst. Tekenbevoegd", "documents": [ { "id": "D-####-####", "type_id": "identification", "type_name": "Legitimatie", "status_id": "1", "status_name": "Aan te leveren", "expires": "" } ] }, "id": "AL-####-####", "account_id": "A-####-####", "name": "Dagobert Duck", "accepted": "0", "access": "0", "ubo": "1", "authorised_to_sign": "0", "signature_label": "Niet Tekenbevoegd", "documents": [ { "id": "D-####-####", "type_id": "identification", "type_name": "Legitimatie", "status_id": "1", "status_name": "Aan te leveren", "expires": "" } ] } ], "bankaccounts": [ { "id": "BA-####-####", "bankaccountHolder": "Classic Carparts Diner", "bankaccountNumber": "NL20PAYN000123456***", "bic": "PAYNLA2A", "countryCode": "" } ], "public_info": [ "merchantId": "M-####-####", "name": "Classic Carparts BV", "type": "", "type_name": "", "postalAddress": ""{ "street": "Kopersteden", "houseNumber": "10", "zipCode": "7547TK", "city": "Enschede", "countryCode": "NL", "countryName": "Nederland" }, "cocNumber": "012345678", "vatNumber": "NL012345678B01", "image": "", "contactdata": [ { "type": "email", "value": "[email protected]", "description": "24/7 helpdesk" }, { "type": "phone", "value": "+31888866622", "description": "Customer service" } ] }, "contract": { "packageType": "ALLIANCEPLUS", "invoiceAllowed": "1", "payoutInterval": "week", "createdDate": "2021-01-15", "acceptedDate": "", "deletedDate": "", } }

Request

In dit request voorbeeld halen wij een merchant op die onder een Alliantie partner valt.

Parameters

Parameter Type Veld Omschrijving
merchantId array VERPLICHT Het Merchant ID van de submerchant (M-####-####)

3.3. Document uploaden

Authenticatie

Basic Authentication

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

Request code: Uploading a document as base64 for a Submerchant

  
    curl --request POST \
    --url https://rest-api.pay.nl/v1/document/add/json \
    --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data-urlencode 'documentID=D-####-####' \
    --data-urlencode 'filename=id.pdf' \
    --data-urlencode 'documentFile=Sm9pbiBvdXIgdGVhbSEgV2UncmUgYWx3YXlzIGxvb2tpbmcgZm9yIGdvb2QgZGV2ZWxvcGVycyE=' \
  

Request

In dit request voorbeeld zie je de parameters die benodigd zijn voor het uploaden van 'D‑####‑####'.

Parameters

Parameter Type Veld Omschrijving
documentID array VERPLICHT Het ID van het te uploaden document voor de Submerchant. Openstaande documenten van een Specifieke Submerchant kunnen via de Alliance::getMerchant worden opgehaald.
filename string Optioneel De bestandsnaam van het te uploaden bestand.
documentFile string VERPLICHT De base64 string met de inhoud van het document.

Response: Document upload

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

{ "request": { "result": "1", "errorId": "", "errorMessage": "" }, }

Response

In dit response voorbeeld ziet u het resultaat van het uploaden van 'D-####-####'.

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

3.4. Bankrekening toevoegen aan Submerchant

Authenticatie

Basic Authentication

Authenticatie van de API alliance::addBankAccount vindt plaats middels HTTP Basic Authentication

Request code: adding a new bank account to a Submerchant account by doing a one time payment.

  
    curl --request POST \
    --url https://rest-api.pay.nl/v1/alliance/addBankAccount/json \
    --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data-urlencode 'merchantId=M-####-####' \
    --data-urlencode 'returnUrl=https://alliance-partner.com/bankaccount_added' \
    --data-urlencode 'paymentOptionId=10' \
    --data-urlencode 'bankId=4' \
  

Request

In dit request voorbeeld zie je de parameters die benodigd zijn voor het toevoegen van een (nieuwe) clearingrekening aan het Submerchantaccount 'M‑####‑####' door middel van een verificatiebetaling via iDEAL, Bancontact, SOFORT of GiroPay.

Parameters

Parameter Type Veld Omschrijving
merchantId array VERPLICHT Het ID van de Submerchant waaraan de bankrekening moet worden toegevoegd. Afhankelijk van de settings op het account, wordt het huidige rekeningnummer verwijderd of toegevoegd aan het account.
returnUrl string VERPLICHT De URL waarnaar moet worden doorverwezen na de betaling.
paymentOptionId string Optioneel De betaalmethode waarmee de verificatiebetaling gedaan wordt. Beschikbare betaalmethoden:
10 - iDEAL - NL - default betaaloptie, zonder meesturen van paymentOptionId wordt een iDEAL-betaling gestart.
436 - Bancontact - BE
559 - SOFORT - AT, BE, DE, IT, NL, ES, CH
694 - Giropay - DE
bankId string Optioneel In geval van een iDEAL-betaling, kan direct de bankkeuze meegestuurd worden, zodat deze direct in de bankieren-app kan worden afgerond. De beschikbare banken kunnen met de transaction::getBanks opgehaald worden.
returnUrl string Optioneel De URL waarnaar moet worden doorverwezen na de betaling.

Response: Alliance::addBankAccount

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

{ "request": { "result": "1", "errorId": "", "errorMessage": "" } "issuerUrl": "https://bankieren.ideal.ing.nl/ideal/betalen/inlog-annuleren/static/detect_mob?trxid=XXXXXXX&random=YYYYYYY" }

Response

In dit response voorbeeld ziet u het resultaat van het toevoegen van een rekeningnummer via iDEAL - ING voor M-####-####.

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
issuerURL string De link naar de betaalpagina waar de verificatiebetaling op plaatsvindt

3.5. Merchant (un)suspenden

Wanneer een klant heeft opgezegd, kun je dit aan ons doorgeven via de Alliance::suspend API of juist unsuspenden via Alliance::unsuspend.

Parameters

Parameter Type Veld Omschrijving
merchantId array VERPLICHT Het ID van de Submerchant die je wilt (un)suspenden.

Response

In dit response voorbeeld ziet u het resultaat van het (un)suspenden van een merchant

Naam Type Omschrijving
request array Array met informatie over het resultaat van de request
status string FALSE (0): request niet geslaagd, TRUE (1): request geslaagd
message string Als er een foutmelding is opgetreden dan vind je hier de omschrijving (bijvoorbeeld: access denied).

4. Verkooplocaties

4.1. Beschikbare categorieën ophalen

For a quick start, please refer to the sample in the php SDK or call the Service::getCategories

Full documentation coming soon

4.2. Verkooplocatie toevoegen

Request code: Add Service for a Submerchant

  
    curl --request POST \
  --url https://rest-api.pay.nl/v7/Alliance/addService/json \
  --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'merchantId=M-####-####' \
  --data-urlencode 'name=Cheers' \
  --data-urlencode 'description=The place where everybody knows your name' \
  --data-urlencode 'categoryId=CY-2010-5020' \
  --data-urlencode 'publication=https://classic-carparts-restaurant.nl' \
  --data-urlencode 'pluginVersionId=PV-####-####' \
  --data-urlencode 'publication=' \
  --data-urlencode 'contactPhone=0888866666' \
  --data-urlencode 'publication=' \
  --data-urlencode 'paymentOptions[0][id]=10' \
  --data-urlencode 'paymentOptions[1][id]=138' \
  --data-urlencode 'paymentOptions[1][settings][merchantId][email protected]' \
  --data-urlencode 'paymentOptions[1][settings][noShipping]=0' \
  --data-urlencode 'paymentOptions[1][settings][protectionEligibility]=1' \
  --data-urlencode 'paymentOptions[1][settings][showOrderLines]=1' \
  --data-urlencode 'paymentOptions[1][settings][currencyEnabled]=0' \
  --data-urlencode 'exchange[useExchange]=1' \
  --data-urlencode 'exchange[alwaysSendExchange]=1' \
  --data-urlencode 'exchange[requestMethod]=post' \
  --data-urlencode 'exchange[requestFormat]=json/xml/txt/jsonp' \
  --data-urlencode 'exchange[resultSeperator]=|' \
  --data-urlencode 'exchange[retry]=7' \
  --data-urlencode 'exchange[urls][0]=https://demo.pay.nl/exchange.php' \
  --data-urlencode 'exchange[urls][1]=https://demo.pay.nl/webhooks/paynl/exchange.php' \

4.3. Beschikbare betaalmethoden ophalen

For a quick start, please refer to the sample in the php SDK or call the service::getAvailablePaymentMethods

Full documentation coming soon

4.4. Betaalmethode activeren

For a quick start, please refer to the sample in the php SDK or call the service::enablePaymentOption

Full documentation coming soon

4.5. Betaalmethode uitschakelen

For a quick start, please refer to the sample in the php SDK or call the service::enablePaymentOption

Full documentation coming soon

5. Beheren van Submerchants geldstromen

5.1. Submerchants ophalen

Request code: Merchantlijst ophalen via API

curl --request POST \
    --url https://rest-api.pay.nl/v6/Alliance/getMerchants/json\
    --header 'authorization: Basic dG9rZW46PHlvdXItYXBpLXRva2VuPg==' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data-urlencode 'state=accepted' \

Request

In dit request voorbeeld halen wij (alle) onderliggende Submerchans op voor een Alliantie account door het aanroepen van het Alliance::getMerchants endpoint. Deze aanroep kan gestart worden met het token van de Alliance Partner. Hierdoor is het niet nodig een verplicht veld mee te geven en haalt de aanroep automatisch alle M-codes (submerchants) op die gekoppeld zijn aan het Alliantie account. Optioneel kan er gefilterd worden op

Parameters

Parameter Type Veld Omschrijving
state array OPTIONEEL De status van de merchants die je terug wilt hebben in de lijst. Mogelijke waardes:
new
accepted
deleted

Response: Alliance::addMerchant

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

[ { "merchantId": ""M-####-####"", "merchantName": "", "packageType": "", "invoiceAllowed": "M-####-####", "payoutInterval": "***********", "createdDate": "***********", "acceptedDate": "***********", "deletedDate": "***********", "services": [ { "serviceId": "A-####-####", "serviceName": "[email protected]" }, { "serviceId": "A-####-####", "serviceName": "[email protected]" } ]

5.2. Transactierapportages ophalen van jouw merchants

For a quick start, please refer to the sample in the php SDK or call the Statistics::Management

Full documentation coming soon

5.3. Clearings uitbetalen via jouw eigen systeem

For a quick start, call the Merchant::addClearing

Full documentation coming soon

5.4. Facturen verrekenen met boeksaldo submerchant

For a quick start, please refer to the sample in the php SDK or call the Alliance::addInvoice

Full documentation coming soon

Login