Alliance Partner – Onboarding von Submerchants

Um Zahlungen für Submerchants über Ihre Plattform verarbeiten zu können, muss zunächst ein PAY.-Konto für den jeweiligen Submerchant vorhanden sein. In der nachfolgenden Dokumentation erläutern wir, wie Sie über die API ein Submerchant-Konto erstellen können. Alternativ können Sie einen Submerchant auch manuell über die Submerchant-Verwaltung in PAY. anlegen, indem Sie das entsprechende Formular ausfüllen.

Wenn die Anmeldung korrekt eingereicht wird, kann in den meisten Fällen unmittelbar mit der Verarbeitung von Transaktionen begonnen werden. PAY. ist gesetzlich verpflichtet, Kunden zu überprüfen, um Geldwäsche und Terrorismusfinanzierung zu verhindern. Zu diesem Zweck werden bestimmte Dokumente und Informationen angefordert. Sobald diese Dokumente eingereicht und vom Onboarding-Team geprüft wurden, wird der Submerchant anhand verschiedener Kriterien überprüft. Nach Abschluss dieser Prüfungen können die eingegangenen Guthaben von PAY. ausgezahlt werden.

3.1 Submerchants hinzufügen

Request

In diesem Request-Beispiel fügen wir einen Merchant über ein Alliance-Partner-Konto hinzu.

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

Parameter	Typ	Feld	Beschreibung
Merchant	array	PFLICHT	Unternehmensdaten eines Submerchants
name	string		Firmenname
coc	string		Handelsregisternummer des Unternehmens
vatNumber	string		Umsatzsteuer-Identifikationsnummer
street	string		Straßenname
houseNumber	string		Hausnummer
houseNumberAddition	string		Hausnummerzusatz
postalCode	string		Postleitzahl
city	string		Unternehmenssitz
countryCode	string		Land, in dem das Unternehmen ansässig ist
contactEmail	string	OPTIONAL	E-Mail-Adresse, über die Kunden den Händler kontaktieren können
contactPhone	string	OPTIONAL	Telefonnummer, über die Kunden den Händler kontaktieren können
Accounts	array	PFLICHT	Liste der Benutzerkonten, die mit dem Submerchant verknüpft werden sollen. Mindestens ein Benutzerkonto ist erforderlich.

Accounts

Parameter	Typ	Beschreibung
email	string	E-Mail-Adresse des Benutzers
firstname	string	Vorname des Benutzers
lastname	string	Nachname des Benutzers
gender	string	Geschlecht des Benutzers. Verfügbare Optionen: male, female
authorizedToSign	string	Zeichnungsberechtigung des Benutzers: 0: NEIN 1: JA, vollständig/einzelvertretungsberechtigt 2: JA, gemeinschaftlich zeichnungsberechtigt
ubo	integer	Gibt an, ob der Benutzer ein UBO ist: 0: NEIN 1: JA
uboPercentage	string	UBO-Anteil in Prozent als Ganzzahl (z. B. 25 für 25 %)
hasAccess	string	Zugriff auf das Merchant-Konto: 0: NEIN 1: JA
languageId	string	Bevorzugte Sprache des Benutzers. Verfügbare Optionen über `language::getAll`. Beispiele: 1:NL, 2:BE, 4:EN, 5:DE, 6:FR, 8:ES

Response

In diesem Response-Beispiel sehen Sie das Ergebnis des Aufrufs der API alliance::addMerchant.

Name	Typ	Beschreibung
success	boolean	0: Request fehlgeschlagen, 1: Request erfolgreich
error_field	string	Fehlercode
errorMessage	string	Fehlerbeschreibung
merchantId	string	Die eindeutige Kennung des neu angelegten Submerchant-Kontos
merchantToken	string	Token des Submerchants
accounts	array	Liste der neu angelegten Konten

Name	Typ	Beschreibung
accountId	string	Kontocode des Benutzers (A-####-####)
email	string	E-Mail-Adresse des Benutzers

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. Einzelnen Merchant abrufen

Request

In diesem Beispiel rufen wir die Daten eines einzelnen Merchants ab. Mit diesem Aufruf können unter anderem folgende Informationen abgerufen werden:

Name des Händlers
Aktivierte Zahlungsmethoden (Services)
Kontoguthaben
Status der einzureichenden Dokumente
Hinzugefügte Benutzer
Verknüpftes Bankkonto
Unternehmensdaten (Adresse, Handelsregisternummer)
Öffentliche Kontaktdaten
Berechtigung zur Belastung des Guthabens
Erstellungs-, Aktivierungs- oder Löschdatum des Kontos

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)

Parameter

Parameter	Typ	Feld	Beschreibung
merchantId	array	PFLICHT	Die Merchant-ID des Submerchants (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. Dokument hochladen

Authentifizierung

Basic Authentication

Die Authentifizierung der API document::add erfolgt mittels HTTP Basic Authentication.

Request

In diesem Beispiel werden die Parameter gezeigt, die für das Hochladen des Dokuments „D-####-####“ erforderlich sind.

Parameter	Typ	Feld	Beschreibung
documentID	array	PFLICHT	Die ID des hochzuladenden Dokuments für den Submerchant
filename	string	OPTIONAL	Dateiname der hochzuladenden Datei
documentFile	string	PFLICHT	Base64-String mit dem Inhalt des Dokuments

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 diesem Response-Beispiel sehen Sie das Ergebnis des Uploads des Dokuments „D-####-####“.

Parameters

Name	Typ	Beschreibung
request	array	Informationen über das Ergebnis des Requests
result	string	0: fehlgeschlagen, 1: erfolgreich
errorId	string	Fehlercode
errorMessage	string	Fehlerbeschreibung

Response: Document upload

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


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

4. Bankkonto zu einem Submerchant hinzufügen

Authentifizierung

Basic Authentication

Die Authentifizierung der API alliance::addBankAccount erfolgt mittels HTTP Basic Authentication.

Request

In diesem Beispiel werden die Parameter gezeigt, die erforderlich sind, um dem Submerchant-Konto mittels einer Verifizierungszahlung über iDEAL, Bancontact ein neues Auszahlungskonto hinzuzufügen.

Parameters

Parameter	Typ	Feld	Beschreibung
merchantId	array	PFLICHT	Die ID des Submerchants, dem das Bankkonto hinzugefügt werden soll
returnUrl	string	PFLICHT	URL, zu der nach der Zahlung weitergeleitet wird
paymentOptionId	string	OPTIONAL	Zahlungsmethode für die Verifizierungszahlung
bankId	string	OPTIONAL	Bankauswahl bei iDEAL
returnUrl	string	OPTIONAL	URL für die Weiterleitung nach erfolgreicher Zahlung

Verfügbare Zahlungsmethoden

10 – iDEAL – NL
436 – Bancontact – BE

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 diesem Response-Beispiel sehen Sie das Ergebnis der Verknüpfung eines Bankkontos über iDEAL - ING mit dem Submerchant-Konto M-####-####

Name	Typ	Beschreibung
request	array	Informationen über das Ergebnis des Requests
result	string	0: fehlgeschlagen, 1: erfolgreich
errorId	string	Fehlercode
errorMessage	string	Fehlerbeschreibung
issuerUrl	string	Link zur Zahlungsseite der Verifizierungszahlung

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 sperren oder entsperren

Wenn ein Kunde gekündigt hat, können Sie dies über die API Alliance::suspend melden oder den Merchant über Alliance::unsuspend wieder aktivieren.

Parameter

Parameter	Typ	Feld	Beschreibung
merchantId	array	PFLICHT	Die ID des Submerchants, der gesperrt oder entsperrt werden soll

Response

Name	Typ	Beschreibung
request	array	Informationen über das Ergebnis des Requests
status	string	FALSE (0): fehlgeschlagen, TRUE (1): erfolgreich
message	string	Fehlermeldung, z. B. „access denied“