Developer Center

Enrolling a customer for direct debits

SlimPay’s Checkout solution offers merchants a frictionless and intuitive payment experience for their customers. Clients can be enrolled through a seamless payment journey, where SEPA mandate signatures can be obtained and payments can be collected in a single transaction.

This step-by-step guide will show you how to enroll a customer for direct debit payments by signing a SEPA mandate using our Checkout solution. This involves creating the Checkout transaction, displaying the Checkout to the customer and informing you as the merchant when the transaction is completed.

The direct debit payment flow is illustrated below:

Step 1: Create the Checkout transaction

To enroll a customer for SEPA direct debits, you will need to have at a minimum:

• your creditor reference
• the reference of your subscriber
• the customer's first name, last name and billing address

You also need to know the payment scheme you intend to use for this customer. If you’re not sure what that is, you probably need to use SEPA Direct Debit CORE.

The table below lists all of the parameters that you need to enroll a customer for direct debits. Be sure to include all the properties that are mandatory, as well as any optional ones you wish.
All of the data you provide must conform to the constraints outlined in our comprehensive API reference.

Parameter	Mandatory	Format	Max length
locale One of de, en, es, fr, it, nl, pl, pt or null if you want to let SlimPay try to deduce it from the user's browser configuration.		An ISO 639-1 standard country code (E.g. fr for France)	2
paymentScheme SEPA.DIRECT_DEBIT.CORE SEPA.DIRECT_DEBIT.B2B		Alphanumeric	35
creditor » reference		Alphanumeric	35
subscriber » reference		Alphanumeric	35
mandate » reference If null, SlimPay will generate a unique reference.		Alphanumeric	35
mandate » signatory » honorificPrefix Mr, Miss or Mrs		Alphabetic	4
mandate » signatory » givenName Forbidden characters: digits from 0 to 9 the at sign @ the slash / the backslash \		Alphabetic	32
mandate » signatory » familyName Forbidden characters: see list above.		Alphabetic	70
mandate » signatory » companyName The company's legal name.		Alphanumeric	70
mandate » signatory » organizationName The unique identifier of the company.		Alphanumeric	24
mandate » signatory » email		Alphanumeric	70
mandate » signatory » telephone If provided, it will be prefilled but still editable by the user.		An E.164 standard telephone number, must include a + symbol (E.g. +33612345678)	16
mandate » signatory » billingAddress » street1		Alphanumeric	70
mandate » signatory » billingAddress » street2		Alphanumeric	70
mandate » signatory » billingAddress » city		Alphanumeric	35
mandate » signatory » billingAddress » postalCode		Alphanumeric	15
mandate » signatory » billingAddress » country		An ISO 3166-2 standard country code (E.g. FR for France)	2
mandate » signatory » bankAccount » iban If provided, it will be prefilled but still editable by the user.		Alphanumeric	34

With these parameters, you create the Checkout transaction through the create-orders relation available at the API entry point, using the orders and order items (of type signMandate) resources. Below is an example of the create-orders API call using our PHP HTTP Client:

$rel = new Hal\CustomRel('https://api.slimpay.net/alps#create-orders');
$follow = new Http\Follow($rel, 'POST', null, new Http\JsonBody(
[
    'started' => true,
    'locale' => 'fr',
    'paymentScheme' => 'SEPA.DIRECT_DEBIT.CORE',
    'creditor' => [
        'reference' => 'yourCreditorReference'
    ],
    'subscriber' => [
        'reference' => 'theSubscriberReference'
    ],
    'items' => [
        [
            'type' => 'signMandate',
            'action' => 'sign',
            'mandate' => [
                'reference' => null,
                'signatory' => [
                    'honorificPrefix' => 'Mr',
                    'givenName' => 'John',
                    'familyName' => 'Doe',
                    'email' => 'change.me@slimpay.com',
                    'telephone' => '+33612345678',
                    'companyName' => null,
                    'organizationName' => null,
                    'billingAddress' => [
                        'street1' => '27 rue des fleurs',
                        'street2' => 'Bat 2',
                        'city' => 'Paris',
                        'postalCode' => '75008',
                        'country' => 'FR'
                    ]
                ]
            ]
        ]
    ]
]
));
$order = $hapiClient->sendFollow($follow);
$orderReference = $order->getState()['reference'];

The order returned by the SlimPay server should look something like this:

{
    "id": "1b1df0d4-0193-11ec-a6ce-000000000000",
    "reference": "1b1df0d4-0193-11ec-a6ce-000000000000",
    "state": "open.running",
    "locale": "fr",
    "started": true,
    "sendUserApproval": false,
    "dateCreated": "2021-08-20T08:46:26.839+0000",
    "dateStarted": "2021-08-20T08:46:26.839+0000",
    "paymentScheme": "SEPA.DIRECT_DEBIT.CORE",
    "checkoutActor": "end_user"
}

Take note of the order reference (1b1df0d4-0193-11ec-a6ce-000000000000) in both code examples above (a property which can optionally be chosen by the merchant during the create-orders API call). This reference needs to be stored in a variable because it will be used later to retrieve the order. Where this reference gets stored depends on how your application keeps track of its users (cookies, database, etc)... this is entirely up to you!

If your transaction flow doesn't rely on keeping a live session of your user’s payment journey, we can activate, as a last resort, an option which will add the order reference to the URL the user returns to when they are finished with the Checkout. This option does come with certain risks, so be careful about how you use it. To activate this option, please submit a request to our Customer Success team.

Step 2: Display the Checkout to the user

At this stage, the customer is directed to the SlimPay Checkout where they will provide and confirm their bank account details and approve their use for recurring direct debits:

$url = $order->getLink('https://api.slimpay.net/alps#user-approval')->getHref();
header('Location: ' . $url);
exit;

An alternative to redirecting the customer to a URL is to embed an iframe into your own application or website, or use an iframe popin to display the Checkout to the user. SlimPay’s HAPI Client can take care of the implementation of this, all you need to do is decode the HTML using base 64.

$rel = new Hal\CustomRel('https://api.slimpay.net/alps#extended-user-approval');
$follow = new Http\Follow($rel, 'GET', [
    'mode' => 'iframepopin' // Or iframeembedded
]);
$htmlCode = $hapiClient->sendFollow($follow, $order)->getState()['content'];
echo base64_decode($htmlCode);

The iframe popin will adapt to the size of the window, while an embedded iframe will take the size (width and height) of the parent container with a minimum of 320 pixels in height.

A further option is to send a link directing the customer to the SlimPay Checkout in a fully-customisable email. This link is valid for a period of 60 days, during which time a customer can click on the link up to five times to complete the Checkout process. Each time the customer clicks on the link, the Checkout session is active for 30 minutes.

At this stage, it is now up to the customer to complete or cancel the Checkout process.

Step 3: Be informed about the Checkout status

When a customer completes or cancels a Checkout transaction, a POST request is sent to your notification URL (if you provided one when configuring your app).

To retrieve the order in the notification URL, we need to decode the message body as a JSON object:

$body = file_get_contents('php://input');
$order = \HapiClient\Hal\Resource::fromJson($body);

Immediately after this synchronous notification ends, the customer can click on the continue button of the Checkout, which redirects them to the return URL (if you provided one when configuring your app).

To retrieve the order in the return URL, we must follow the get-orders relation using the order reference that was stored at the end of the first step:

$rel = new Hal\CustomRel('https://api.slimpay.net/alps#get-orders');
$follow = new Http\Follow($rel, 'GET', [
    'creditorReference' => 'yourCreditorReference',
    'reference' => 'theOrderReference'
]);
$order = $hapiClient->sendFollow($follow);

An alternative to configuring a returnURL is to configure a number of dynamic URLs for handling specific use cases. These include:

• a failureUrl, which is a web page a customer is redirected to following an order failure during Checkout
• a successUrl, which is a web page a customer is redirected to following a successful order during Checkout
• a cancelUrl, which is a web page a customer is redirected to following a cancelled order during Checkout

Further documentation on URL management can be found on the SlimPay Help Center.

Once we’ve retrieved the customer’s order (whether it was cancelled or completed), let’s check its state to trigger the appropriate action:

if (strpos($order->getState()['state'], 'closed.aborted') === 0) {
    // The user did not complete the Checkout
    
    // ... trigger some action(s) depending on your need
    
    header('Location: failure-page.php');
    exit;
} elseif (strpos($order->getState()['state'], 'closed.completed') === 0) {
    // The user completed the Checkout successfully
    
    // The mandate reference (needed to create payments)
    $rel = new Hal\CustomRel('https://api.slimpay.net/alps#get-mandate');
    $follow = new Http\Follow($rel);
    $mandate = $hapiClient->sendFollow($follow, $order);
    $mandateReference = $mandate->getState()['reference'];
    
    // The mandate PDF file
    $rel = new Hal\CustomRel('https://api.slimpay.net/alps#get-binary-content');
    $follow = new Http\Follow($rel);
    $binaryContent = $hapiClient->sendFollow($follow, $mandate);
    $pdfContent = base64_decode($binaryContent->getState()['content']);
    file_put_contents("mandate-$mandateReference.pdf", $pdfContent);
    
    // The subscriber reference that you provided
    $rel = new Hal\CustomRel('https://api.slimpay.net/alps#get-subscriber');
    $follow = new Http\Follow($rel);
    $subscriber = $hapiClient->sendFollow($follow, $order);
    $subscriberReference = $subscriber->getState()['reference'];
    
    // ... trigger some action(s) depending on your need
    
    header('Location: success-page.php');
    exit;
} else {
    throw new Exception('Checkout is still open. State expected to be "closed".');
}

The example code above includes some suggestions for follow-up requests based on a successful transaction (like retrieving the signed mandate and its contents).

It’s important to store the mandate reference as it will be needed to create payments or to update the mandate with a new IBAN.

The most common order states include:

• closed.complete: the customer has completed a successful order
• closed.aborted.aborted_byclient: the customer has abandoned the order
• closed.aborted.aborted_byserver: the order was cancelled by the server

Sign By Link

SlimPay has a feature that allows merchants to email a link to their customers, where they can sign a SEPA mandate to authorize direct debit payments. By following this link, customers will be directed to the Checkout in order to provide and confirm their bank account details according to the process described above.

To make use of this feature via API, simply include the sendUserApproval property in the order resource, setting its value to true.

$rel = new Hal\CustomRel('https://api.slimpay.net/alps#create-orders');
$follow = new Http\Follow($rel, 'POST', null, new Http\JsonBody(
[
    'started' => true,
    'locale' => 'fr',
    'paymentScheme' => 'SEPA.DIRECT_DEBIT.CORE',
    'sendUserApproval' => true,
    'creditor' => [
        'reference' => 'yourCreditorReference'
    ],
    'subscriber' => [
        'reference' => 'theSubscriberReference'
    ],
    'items' => [
        [
        // Your already existing order item of type signMandate
        // As defined in the Setting Up Direct Debits guide
        ]
    ]
]

Remember to include the customer’s email address in the signatory object where the Checkout link will be sent.

Signing a SEPA mandate by link can also be accomplished using the Dashboard. Further documentation regarding signing by link via the Dashboard can be found on our Help Center. This documentation also describes how to sign mandates by delegation (for example, on the customer’s behalf following telephone orders).

Signing a SEPA mandate by link can also be accomplished using our File API. Dozens, hundreds or even thousands of new customers can be enrolled for direct debit payments in a single operation, by depositing a file into our SFTP server. Further documentation regarding signing by link via file can be found here.

Retrieving and managing SEPA mandates

Once a mandate has been signed and created, SlimPay allows merchants to retrieve the mandate in order to manage it (update the IBAN, revoke the mandate etc). To do this by API, you can follow the get-order relation available at the entry point, providing your creditor reference and the order reference as parameters. Then simply follow the get-mandate relation that is returned by the server.

Alternatively, you can follow the search-subscribers relation available at the entry point, providing your creditor reference and the subscriber reference as parameters. Then you can follow the get-mandate relation associated with the subscriber.

Lastly, you can retrieve the mandate directly by following the get-mandates relation available at the entry point, providing your creditor reference and the mandate reference as parameters.

Mandates can also be retrieved and managed using the SlimPay Dashboard. Further documentation on managing mandates via the Dashboard can be found on our Help Center.

Mandate templates

SlimPay offers merchants a range of customisation options using mandate templates. Specific documentation regarding mandate templates can be found on our Help Center.

Testing your integration

In order to test your implementation in our preprod environment, SlimPay has a range of test data available, such as test IBANs and card numbers. Specific documentation regarding this test data can be found on the SlimPay Dev Center and Help Center.