Skip to content
English
Go to PAY.NL
  • There are no suggestions because the search field is empty.

Alliance Partners - Managing Submerchant Cash Flows

1. Retrieving submerchants

Request

In this request example, we retrieve (all) underlying submerchants for an Alliance account by calling the Alliance::getMerchants endpoint. This call can be made with the Alliance Partner's token. This means no required field needs to be passed, and the call automatically retrieves all M-codes (submerchants) linked to the Alliance account. Optionally, you can filter on

Request code: Retrieving the merchant list via the 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'

Parameters

Pameter Type Field Description
state array OPTIONAL The status of the merchants you want to remove from the list. Possible values:
new
accepted
deleted

Response

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


2. Retrieving transaction reports from your merchants

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

Full documentation coming soon

3. Paying out clearings via your own system

When you, as a merchant or partner, initiate a withdrawal via the Merchant::addClearing API, this can cause confusion on the clearing invoice if the withdrawn amount differs from the sum of the individual transactions. Below we explain how this works using an example.

3.1 Example situation

Suppose a merchant has the following available account balance:

Payment type Number Amount per type
iDeal 50 €5,000
Credit card 10 €2,000
Bancontact 5 €2,500
Bank transfer 5 €500
Total   €10,000

The partner initiates a clearing via the API with a withdrawal of €6,000.

What happens?

  • The available account balance is €10,000.
  • The partner only wants €6,000 to be paid out.
  • However: the transactions that make up the balance haven't yet been processed in a clearing.
  • To still show a correct breakdown of the clearing (and enable reconciliation), we do the following:

The solution on the clearing invoice

  1. We create an extra revenue line "Clearing opening balance" of €-4,000 to reduce the account balance to the desired amount.
  2. We create the clearing including this new revenue line to arrive at a correct clearing of the desired amount of €6,000 (€10,000 credit minus the €4,000)
  3. After creating it, we again create an extra revenue line called "Clearing closing balance" of €+4,000 to offset the "Clearing closing balance" line. This restores the account balance to the €4,000 that remained.

Example on the clearing invoice

Payment type Number Amount per type
iDeal 50 €5,000
Credit card 10 €2,000
Bancontact 5 €2,500
Bank transfer 5 €500
Pay.payment - Clearing opening balance 1 - €4,000
Total   €6,000

The Clearing closing balance then appears as a correction to offset the earlier "opening balance". In a subsequent clearing, the amount is then included again as a starting amount (in the example below, the available balance is €14,000 and a clearing of €12,000 will take place):

Payment type Number Amount per type
Pay.payment - Clearing final balance 1 €4,000
iDeal 45 €4,500
Credit card 12 €3,000
Bancontact 5 €1,500
Bank transfer 5 €1,000
Pay.payment - Clearing opening balance 1 - €2,000
Total   €6,000
3.2 Why is this important?
  • This means merchants can still correctly reconcile their transactions with the clearing in which the actual withdrawal took place.
  • After all, all transactions that contributed to the account balance have already been included in the clearing that this withdrawal relates to.
  • They aren't included again in the next clearing – that would otherwise lead to double counting.
3.3 Important to know as a partner
  • If you use a withdrawal amount in the API that's lower than the current account balance, we'll automatically correct the difference internally with an opening balance/closing balance pair.
  • These aren't paid out and are purely intended internally for correct reporting and reconciliation.


4. Offsetting invoices against submerchant account balance

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

Full documentation coming soon