To process payments for submerchants on your platform, they must first have an account with PAY. In the documentation below, we explain how to create a submerchant account via the API. It's also possible to manually create a submerchant via the submerchant management screen in PAY. by filling in a form.
If the registration is submitted correctly, processing transactions can, in most cases, begin immediately. PAY. has a legal obligation to screen customers in order to prevent money laundering and terrorism financing. To do this, a number of documents and details are requested. Once these documents have been submitted and checked by the onboarding team, the submerchant is checked as a whole against a number of factors. Once these checks are complete, the credits received can be paid out by PAY.
3.1. Adding submerchants
Request
In this request example, we add a merchant from an Alliance 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 | Field | Description |
|---|---|---|---|
| Merchant | array | OBLIGED | Add business details of a submerchant |
 |
array | { | |
| name | string | Company name | |
| coc | string | Chamber of Commerce number of the company | |
| vatNumber | string | VAT number | |
| street | string | Street name of the company | |
| houseNumber | string | House number of the company | |
| houseNumberAddition | string | House number suffix | |
| postal Code | string | Company postcode | |
| City | string | Place where the company is located | |
| countryCode | string | Country where the company is established | |
| contactEmail | string | OPTIONAL | Email address for customers to contact the seller |
| contactPhone | string | OPTIONAL | Phone number for customers to contact the seller |
| Accounts | array | OBLIGED | Array of user accounts to be linked to the submerchant. Add at least 1 user account. |
|
array | { | |
| string | User's email address | ||
| first name | string | User's first name | |
| last name | string | User's last name | |
| gender | string | Gender of the user to be registered. Available options: male female |
|
| authorizedToSign | string | Indicates whether the user is authorized to sign. Available options: 0 : NO 1 : YES, fully/independently authorized to sign 2 : YES, jointly authorized to sign |
|
| ubo | integrity | Indicates whether the user is a UBO. Available options: 0 : NO 1 : YES |
|
| uboPercentage | string | Indicates the UBO percentage in numbers only (for example, 25 for 25%) | |
| hasAccess | string | Indicates whether the user account has access to the merchant account. Available options: 0 : NO, use this option when you only want to register a UBO (and do not necessarily need access) 1 : YES, the user has access to the merchant account |
|
| languageId | string | Language preference for the user to be registered. Here you provide an ID. Available options can be retrieved via language::getAll Examples: 1 :NL, 2 :BE, 4 :EN, 5 :DE, 6 :FR, 8 :ES |
|
Response
In this response example, you see the result of calling the alliance::addMerchant API.
Parameters
| Name | Type | Description |
|---|---|---|
| success | boolean | 0: request failed, 1: request successful |
| error_field | 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. |
| merchantID | string | The unique reference code to the newly created Submerchant account |
| merchantToken | string | All actions within the submerchant account can be performed using the Alliance's API token. However, it can sometimes be useful to use a submerchant-specific token for certain matters. |
| accounts | array | An array with the newly created accounts of the directors, UBOs, and employees. |
| accountId | string | The account code of the created user (A-####-####) |
| string | Email address of the newly created user. |
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. Retrieving a single merchant
Request
In this example, we retrieve data for a single merchant. With this call, you can retrieve, among other things, the following information:
- Merchant name
- Activated payment methods (services)
- Account balance (balance)
- Status of documents to be submitted
- Users added
- Linked bank account
- Company details (address, KVK number)
- Public contact details
- Permitted to debit the balance
- When the account was created/accepted/deleted
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 | Field | Description |
|---|---|---|---|
| merchantId | array | OBLIGED | The ID of the merchant you wish to retrieve (M-code) |
Request
In this request example, we retrieve a merchant that falls under an Alliance partner.
Parameters
| Parameter | Type | Field | Description |
|---|---|---|---|
| merchantId | array | OBLIGED | The Merchant ID of the 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. Uploading a document
Authentication
Basic Authentication
Authentication for the API document::add takes place via HTTP Basic Authentication
Request
In this request example, you see the parameters needed to upload 'D‑####‑####'.
Parameters
| Parameter | Type | Field | Description |
|---|---|---|---|
| documentID | array | OBLIGED | The ID of the document to be uploaded for the Submerchant. Outstanding documents for a Specific Submerchant can be retrieved via Alliance::getMerchant . |
| filename | string | Optional | The filename of the file to be uploaded. |
| documentFile | string | OBLIGED | The base64 string containing the content of the 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 this response example, you see the result of uploading 'D-####-####'.
Parameters
| 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. |
Response: Document upload
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"request": {
"result": "1",
"errorId": "",
"errorMessage": ""
},
}
4. Adding a bank account to a submerchant
Authentication
Basic Authentication
Authentication for the API alliance::addBankAccount takes place via HTTP Basic Authentication
Request
In this request example, you see the parameters needed to add a (new) clearing account to the submerchant account 'M‑####‑####' by means of a verification payment via iDEAL, Bancontact, SOFORT, or GiroPay.
Parameters
| Parameter | Type | Field | Description |
|---|---|---|---|
| merchantId | array | OBLIGED | The ID of the Submerchant to which the bank account is to be added. Depending on the account settings, the current account number is either removed or added to the account. |
| returnUrl | string | OBLIGED | The URL to be redirected to after payment. |
| paymentOptionId | string | Optional | The payment method used for the verification payment. Available payment methods: 10 - iDEAL - NL - default payment option, an iDEAL payment is initiated without sending paymentOptionId. 436 - Bancontact - BE 559 - SOFORT - AT, BE, DE, IT, NL, ES, CH 694 - Giropay - DE |
| bankId | string | Optional | In the case of an iDEAL payment, the bank selection can be sent immediately so that it can be completed directly in the banking app. The available banks can be retrieved using transaction::getBanks . |
| returnUrl | string | Optional | The URL to be redirected to after payment. |
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 this response example, you see the result of adding an account number via iDEAL - ING for M-####-####.
| 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. |
| issuerURL | string | The link to the payment page where the verification payment takes place |
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. (Un)suspending a merchant
When a customer has cancelled, you can notify us via the Alliance::suspend API, or unsuspend via Alliance::unsuspend.
Parameters
| Parameter | Type | Field | Description |
|---|---|---|---|
| merchantId | array | OBLIGED | The ID of the Submerchant you want to (un)suspend. |
Response
In this response example, you see the result of (un)suspending a merchant
| Name | Type | Description |
|---|---|---|
| request | array | Array with information about the result of the request |
| status | string | FALSE (0): request failed, TRUE (1): request succeeded |
| message | string | If an error message occurred, you will find the description here (for example: access denied). |