Developer Center

Collect Payments by Direct Debit

Once a customer has been enrolled by signing a SEPA mandate, SlimPay allows merchants to collect one-off payments or set up recurring payment plans without needing to display the Checkout to the consumer. Signed payment authorisations can be used to process direct debits with a server-to-server call to the SlimPay API!

This step-by-step guide walks you through the process of collecting server-to-server direct debit payments.

Creating one-off direct debit payments

To directly collect a one-off SDD payment, we make an API call using the create-payins relation, which can be found at the entry point. The table below lists all of the parameters that you need to create a direct debit payment. 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
creditor » reference		Alphanumeric	35
mandate » reference or subscriber » reference		Alphanumeric	35
payment reference If null, SlimPay will generate a unique reference.		Alphanumeric without special characters	35
amount		Decimal	19
currency EUR		An ISO 4217 currency code	3
scheme SEPA.DIRECT_DEBIT.CORE SEPA.DIRECT_DEBIT.B2B		Alphanumeric	35
label		Alphanumeric	140
executionDate As soon as possible if null.		A date, formatted to ISO 8601 standard E.g. 2021-11-03T00:00:00.000+0100	28

Below is an example of the create-payins API call using our PHP HTTP Client:

$rel = new Hal\CustomRel('https://api.slimpay.net/alps#create-payins');
$follow = new Http\Follow($rel, 'POST', null, new Http\JsonBody(
[
    'creditor' => [
        'reference' => 'yourCreditorReference'
    ],
    'mandate' => [
        'reference' => 'theMandateReference'
    ],
    'reference' => null,
    'amount' => 29.99,
    'currency' => 'EUR',
    'scheme' => 'SEPA.DIRECT_DEBIT.CORE',
    'label' => 'January subscription fee',
    'executionDate' => null
]
));
$payment = $hapiClient->sendFollow($follow);

In the example above, the mandate reference was used to create a direct debit payment. If a merchant provided the subscriber reference instead, SlimPay would use the most recently active SEPA mandate associated with this subscriber.

When trying to create the payment, it can be synchronously rejected by our API if a parameter is missing or not formatted correctly.

Otherwise, the server responds with a 201 Created HTTP status. The payment is created and returned in the response.

Below is an example of a created direct debit payment:

{
    "amount": "25.00",
    "confirmed": false,
    "currency": "EUR",
    "dateCreated": "2021-11-03T00:00:00.000+0100",
    "direction": "IN",
    "executionDate": "2021-11-03T00:00:00.000+0100",
    "executionStatus": "toprocess",
    "id": "edbc7803-7ed7-11e8-bf72-000000000000",
    "label": "The label",
    "processor": "slimpay",
    "reference": "Payment 123",
    "scheme": "SEPA.DIRECT_DEBIT.CORE",
    "state": "accepted",
    "_links": {
        ...
    }
}

From the response example above, the following three properties are important to note:

• id: the payment ID generated by SlimPay. You’ll need to store this in order to retrieve the payment later
• executionDate: the date on which the amount is expected to be settled by the clearing house. This can be set by you, or it will be generated by SlimPay for the earliest possible date
• executionStatus: the payment starts as toprocess, marking the beginning of its life cycle described below

Creating recurrent direct debit payment plans

To create a payment plan of recurring direct debits, we make an API call using the create-recurrent-direct-debits relation, which can be found at the entry point. The table below lists all of the parameters that you need to create a payment plan. 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
creditor » reference		Alphanumeric	35
mandate » reference or subscriber » reference		Alphanumeric	35
payment reference If null, SlimPay will generate a unique reference.		Alphanumeric without special characters	35
amount		Decimal	19
currency EUR		An ISO 4217 currency code	3
label		Alphanumeric	140
frequency The frequency of the direct debit transactions. daily weekly monthly bimonthly trimonthly semiyearly yearly biyearly		Alphanumeric	16
maxSddNumber The maximum number of direct debits that should be created with this payment plan. If not provided, the payment plan will have no limit until cancelled.		Integer	3
dateFrom The date of the first direct debit creation.		A date, formatted to ISO 8601 standard E.g. 2021-11-03T00:00:00.000+0100	28

Below is an example of the create-recurrent-direct-debits API call using our PHP HTTP Client:

$rel = new Hal\CustomRel('https://api.slimpay.net/alps#create-recurrent-direct-debits');
$follow = new Http\Follow($rel, 'POST', null, new Http\JsonBody(
[
    'creditor' => [
        'reference' => 'yourCreditorReference'
    ],
    'subscriber' => [
        'reference' => 'theSubscriberReference'
    ],
    'amount' => 100,
    'currency' => 'EUR',
    'frequency' => 'monthly',
    'maxSddNumber' => '12',
    'dateFrom' => '2021-07-12T22:00:00.000+0000',
    'label' => 'Direct debit payment plan'
]
));
$payment_plan = $hapiClient->sendFollow($follow);

The example above is for a payment plan of 12 monthly instalments of €100 each. The payment plan will be created for the most recently active SEPA mandate associated with the subscriber.

Collecting direct debits by file

Direct debit payments can also be processed by batch file, meaning you can inject a remittance file to process dozens, hundreds or even thousands of payment orders in a single operation. Documentation regarding direct debits by batch file can be found here (see the ''Direct Debit'' and ''Debit Schedule Creation'' tabs in the Operation order line section).

Collecting direct debits by Dashboard

Direct debit payments can also be processed using SlimPay’s Dashboard interface. For documentation on this process, please refer to our Help Center.

Modifying recurring direct debit plans

Once a direct debit payment plan has been created, merchants can modify or cancel it by API, by file or via the Dashboard.

The patch-recurrent-direct-debit relation allows merchants to alter the recurring direct debit amount as well as the label associated with the plan, while the cancel-recurrent-direct-debit relation will discontinue the payment plan.

Recurring direct debit plans can also be modified by file. Specific documentation can be found here (see the ''Debit Schedule Modification'' and ''Debit Schedule Cancellation'' tabs in the Operation order line section).

Alternatively, changes or cancellations to recurring direct debit plans can be made via the Dashboard. For specific documentation, refer to our Help Center.

Determining whether a direct debit payment was successful

SlimPay allows merchants to track the status of direct debit payments to confirm whether they have been successfully processed.

To retrieve all direct debit payments for a specific customer, you can use the search-payments relation available at the API entry point, providing your creditor reference, the payment scheme (SEPA.DIRECT_DEBIT.CORE) and the subscriber reference as parameters. All SDD payments created for that specific debtor will be returned in a collection by the SlimPay server.

To retrieve the status of a specific payment, you can use the search-payment-by-id relation available at the API entry point, providing the ID of the direct debit.

In the event that a direct debit has failed, SlimPay has a range of mechanisms in place for retrieving and recovering payment issues. Further documentation on handling R-transactions can be found here.

The direct debit payment refund timeline

Direct debits are subject to a potential refund request up to 8 weeks after settlement, where a debtor can dispute a transaction without justification. A debtor can dispute an SDD transaction up to 13 months after settlement providing justification. Conversely, a credit transfer payment to refund an SDD can be processed at any time. Documentation on how to process direct debit refunds can be found here.

Direct Debit Payment Life Cycle

Execution Status	Description
toprocess	The payment seems valid and should be sent to the clearing house.
processing	A few days before the execution date, our system tries to process it.
notprocessed	A few days before the execution date, our system is not able to process it as it is not valid anymore (e.g. the mandate has been revoked between the payment creation and the time we try to process it).
toreplay	The processing of the payment was not a success and another attempt will be done after our operations team figure out what's wrong with the payment. Depending on their analysis, it may move to notprocessed or processing again. You can basically treat this status as toprocess.
processed	The processing of the payment was a success and it's on its way through the clearing house. At this point, you can expect the settlement to happen on execution date unless the payment moves to rejected.
rejected	The payment was never settled or it was settled and then the money was sent back to the debtor. See our guide on how to handle payment issues for more details.