SDK-Alliance (PHP)

---

• About
• Installation
• Setting up
  • 1. The autoloader
  • 2. Your API token
• Examples
  • 1. Adding a merchant
  • 2. Getting a list of your merchants
  • 3. Getting a single merchant
  • 4. Uploading a document
  • 5. Getting the list of available categories
  • 6. Adding a service (website)
  • 7. Getting available payment methods
  • 8. Enable a payment method
  • 9. Disable a payment method
  • 10. Get statistics of your submerchants
  • 11. Creating an invoice for a merchant
  • 12. Creating a clearing for a merchant

---

About

A PAY. alliance account is required for this SDK.

As an alliance, you're able to manage sub-merchants and most of their tasks using this SDK.

This SDK also extends the standard PAY. SDK, so all functions from the original SDK are also available.

Installation

This SDK uses composer. To install the PAY. PHP SDK-alliance into your project, simply

$ composer require paynl/sdk-alliance

Setting up

To communicate with PAY. using this SDK, you'll need to authenticate. PAY. uses a token to authenticate you. You can find your token in the PAY. admin. On the bottom of the API Tokens page.

Step 1 The autoloader

Composer generates an autoloader for your application. To be able to access the classes of the SDK, all you have to do is include the composer autoloader. The autoloader is located here: vendor/autoload.php

require_once('path_to/vendor/autoload.php');

Step 2 Your APItoken

To let the SDK know what your API-Token is, you'll have to register the TokenCode (AT-code belonging to the token) and APItoken as follows:

\Paynl\Config::setTokenCode('AT-####-####');
\Paynl\Config::setApiToken('****************************************');

Now you're ready to use the SDK.

Examples

The full list of functions can be found in the samples folder.

1. Adding a merchant

Before we can do anything, we need to add a merchant to work with. For a full example of the merchantData, please refer to the sample

$merchant = \Paynl\Alliance\Merchant::add((array)$merchantData);

/* 
 *  Save the merchantId to your database.
 *  You'll need this id in the next call
 */
$merchantId = $merchant->getMerchantId();

2. Getting a list of your merchants

You can get a list of all your sub-merchants. See the example here

Just call:

/* 
 * Possible states are: new, accepted, deleted.
 * You can omit this value to get all merchants
 */
$result = Paynl\Alliance\Merchant::getList(array('state' => 'new')); 
$merchants = $result->getMerchants();

foreach ($merchants as $merchant) {
    echo $merchant->getMerchantId() . ' ' . $merchant->getMerchantName() . "<br />";
}

3. Getting a single merchant

You can of course also get the details of a single merchant. See also this example.

$merchant = Paynl\Alliance\Merchant::get(array('merchantId' => 'M-1820-9300'));

# Documents that still need to be uploaded (for the next example)
$documents = $merchant->getMissingDocuments();

var_dump($documents);

4. Uploading a document

Before we can accept your sub-merchants, you need to supply the required documents To check the missing documents, see the code from example 3. You can also check the example

$result = Paynl\Alliance\Document::upload(array(
      'documentId' => 'D-####-####',
      'path' => '/path/to/the/file',
      'filename' => 'bankStatement.pdf' # Optional, when you leave this blank, the filename from the path will be used
	));

if ($result->success()) {
}

It is also possible to send multiple files. The files will be merged into one file on our server. Both files must be of the same type (pdf or image)

$result = Paynl\Alliance\Document::upload(array(
      'documentId' => 'D-####-####',
      'path' => array('/path/to/the/file', 'path/to/the/second/file'),
      'filename' => 'bankStatement.pdf' # Optional, when you leave this blank, the filename from the path will be used
	));

if ($result->success()) {
}

5. Getting the list of available categories

You must select the correct category for the services you add for the merchant. The available paymentmethods differ for each category (for example, a wine giftcard is only valid for category wines) To get the list of categories, just call example

$categories = Paynl\Alliance\Service::getCategories();
$data = $categories->getData();

var_dump($data);

6. Adding a service (website)

In order for a merchant to use our services, The merchant needs to have a service (website) registered. A merchant can have multiple services, normally one for each website. Before we can add the website, we have to find out in which category the website should be placed. Some paymentmethods are only available for certain categories, so it is important to select the right one. To get a list of the available categories, see step 5. You can also check this extended example

$result = Paynl\Alliance\Service::add(array(
    'merchantId' => 'M-####-####',
    'name' => 'The name of my sales location tells us what my Sales location is about', 
    'description' => 'This description describes what people are paying for',
    'categoryId' => 'CY-####-####', # Use Paynl\Alliance\Service::getCategories() to get the list of available categories
    'url' => 'https://www.pay.nl',
    'extraUrls' => array(
        'https://phpsdk.webshop.pay.nl',
        'https://sdkalliance.webshop.pay.nl'
    ),
    'alwaysSendExchange' => true # Set to false if you only want a notification on successfull payment (not recommended)
));

7. Getting available payment methods

To get a list of the available payment methods, see the following example

$paymentOptions = Paynl\Alliance\Service::getAvailablePaymentMethods(array('serviceId' => 'SL-####-####'));
$data = $paymentOptions->getData();

var_dump($data);

To get a list of the enabled payment methods, use the Paymentmethods::getList() from the Merchant SDK

\Paynl\Config::setServiceId('SL-####-####'); 
$paymentMethods = \Paynl\Paymentmethods::getList();
var_dump($paymentMethods);

8. Enable a payment method

To enable a payment method, see the following example Some payment method have settings. The Paynl\Alliance\Service::getAvailablePaymentMethods result has a settings array inside the result for payment methods that have settings.

$success = Paynl\Alliance\Service::enablePaymentMethod(array(
    'serviceId' => 'SL-####-####',
    'paymentMethodId' => 739,
    'settings' => array( # Optional for payment methods that have settings.
        'merchantId' => 1234,
        'merchantPassword' => 'p4ssw0rd',
        'portefeuilleId' => '1'
    )
));

if($success) {
    # Enabled
}

9. Disable a payment method

To disble a payment method, see the following example

$success = Paynl\Alliance\Service::disablePaymentMethod(array(
    'serviceId' => 'SL-####-####',
    'paymentMethodId' => 739    
));

if($success) {
   # Disabled
}

10. Get statistics of your submerchants

You can get the statistics of your submerchants. For example to calculate the amount for the invoice in the next step. See the following example

You can use the predefined periods:

\Paynl\Alliance\Statistics::PERIOD_THIS_WEEK
\Paynl\Alliance\Statistics::PERIOD_LAST_WEEK
\Paynl\Alliance\Statistics::PERIOD_THIS_MONTH
\Paynl\Alliance\Statistics::PERIOD_LAST_MONTH

For example:

$result = Paynl\Alliance\Statistics::getStats(array(
    'period' => \Paynl\Alliance\Statistics::PERIOD_LAST_WEEK
));
var_dump($result->getData());

Or if you want to use your own start and end date:

$result = Paynl\Alliance\Statistics::getStats(array(
    'startDate' => new DateTime('2015-03-01'),
    'endDate' => new DateTime('2015-03-10')
));
var_dump($result->getData());

11. Creating an invoice for a merchant

You can add an invoice for a merchant. In order to be able to add an invoice to a merchant, you'll have to set the settleBalance option to true, when adding a merchant in step 1 See the following example

\Paynl\Config::setServiceId('SL-####-####');

$result = Paynl\Alliance\Invoice::add(array(

    # Required
    'merchantId' => 'M-####-####', # The id of the merchant
    'serviceId' => 'SL-####-####', # The serviceid (of the Alliance) to book the payment on
    'invoiceId' => 'INV012345',# Your reference number to the invoice
    'amount' => 25.75, # The total amount of the invoice
    'description' => 'Test invoice', # The description of the invoice

    # Optional
    'invoiceUrl' => 'https://url.to.the/invoice.pdf', # The url to the invoice
    'makeYesterday' => true # If the invoice needs to be added in today's clearing, set this to true
    'extra1' => 'free variable 1',
    'extra2' => 'free variable 2',
    'extra3' => 'free variable 3',
    "merchantServiceId": "SL-####-####", # The ServiceId of the submerchant that needs to be invoiced  
));

$referenceId = $result->referenceId();

12. Creating a clearing for a merchant

You can add a clearing for a merchant. The addClearing function should be called after 5:00 am CET, as the daily totals of the clearings are calculated at 4:00 am CET each day. See the following example

$result = \Paynl\Alliance\Merchant::addClearing(array(

    # Required
    'amount' => '123', # The amount to clear, in cents.

    # Optional
    'merchantId' => 'M-1234-5678', # The id of the merchant
    'contentCategoryId' => 'CT-1234-5678' # The content category Id
));

$referenceId = $result->referenceId();