Alliance Partners - 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

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

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]=test@email.com'
--data-urlencode 'merchant[postalCode]=7547TK'
--data-urlencode 'merchant[city]=Enschede'
--data-urlencode 'merchant[contactEmail]=info@alliancepartner.nl'
--data-urlencode 'merchant[contactPhone]=+31888866622'
--data-urlencode 'accounts[0][email]=director@classic-carparts.nl'
--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]=ubo@classic-carparts.nl'
--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-####-####'

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

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

Parameters

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.

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": "director@classic-carparts.nl"
  },
  {
   "accountId": "A-####-####",
   "email": "finance@classic-carparts.nl"
  }
 ]
}

2. Enkele merchant ophalen

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

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-###-####'

Parameters

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

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-####-####)

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": "info@classic-carparts.nl",
          "description": "24/7 helpdesk"
        },
        {
          "type": "phone",
          "value": "+31888866622",
          "description": "Customer service"
        }
      ]
    }
  ],
  "contract": {
    "packageType": "ALLIANCEPLUS",
    "invoiceAllowed": "1",
    "payoutInterval": "week",
    "createdDate": "2021-01-15",
    "acceptedDate": "",
    "deletedDate": ""
  }
}

3. Document uploaden

Authenticatie

Basic Authentication

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

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.

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='

Response

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

Parameters

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

Response: Document upload

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


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

4. Bankrekening toevoegen aan Submerchant

Authenticatie

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

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.

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'

Response

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

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

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

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