Setting Up SlimCollect

Enrolling a customer for SlimCollect Pay

SlimPay’s Checkout solution offers merchants a new frictionless and intuitive payment experience for their customers. Called SlimCollect, clients can be enrolled through a seamless payment journey, where customers select their bank, their bank account, and confirm the payment in their banking environment, all in a single transaction. At the same time, our SlimCollect solution builds and stores a SEPA mandate that can be used to process future recurrent payments.

This step-by-step guide will show you how to enroll a customer for SlimCollect payments using our Checkout solution. This involves creating the Checkout transaction order, redirecting the customer to the SlimCollect Checkout and collecting the mandate information when the transaction is completed.

Please note

This guide does not cover the basics of API authentication or the format of requests and responses. Please review these sections if you are unfamiliar with these concepts.

All of the code examples in our guides are written in PHP and are based on our HAPI Client, developed by SlimPay to reduce the code complexity of interfacing with our API. Please refer to our HTTP client page for more details on using these libraries.

The SlimCollect payment flow is illustrated below:

Step 1: Create the Checkout transaction

Please note: SlimCollect features are available for UAT and live accounts only and must be activated by SlimPay.

To enroll a customer for SlimCollect payments, 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
the SlimCollect payment (PIS, or payment initiation service)

To create a SlimCollect single transaction, you can customize the create-orders relation. The basic parameters of the request body are as follows:

{
    "started": true,
    "creditor": {
        "reference": "yourCreditorReference"
    },
    "subscriber": {
        "reference": "theSubscriberReference",
        "givenName": "John",
        "familyName": "Doe",
        "email": "change.me@slimpay.com",
        "shippingAddress": {
            "street1": "27 rue des fleurs",
            "postalCode": "75008",
            "city": "Paris",
            "country": "FR",
            "fullCountry": "France"
        },
        "billingAddress": {
            "street1": "27 rue des fleurs",
            "postalCode": "75088",
            "city": "Paris",
            "country": "FR",
            "fullCountry": "France"
        }
    },
    "items": [
        {
            "type": "slimCollectPaySigned" // slimCollectPaySigned for a signed mandate, slimCollectPayUnSigned for unsigned mandate
        },
        {
            "type": "payment",
            "payin": {
                "amount": "10",
                "currency": "EUR",
                "label": "label-003",
                "reference": "payin-0000003",
                "scheme": "PIS.SEPA.CREDIT_TRANSFER",
                "market": "FR"
            }
        }
    ],
    "successUrl": "https://www.merchant.com/success",
    "failureUrl": "https://www.merchant.com/failure",
    "cancelUrl": "https://www.merchant.com/cancel",
    "userApprovalMode": "api"
}

The details of the specific payment order item can be found here.

It is mandatory to configure a returnURL 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

It is strongly recommended to set a transaction amount equal or superior to 1 euro to be able to work properly with the different banks.

Once all the parameters are defined, you can target the following URL:

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

{
    "id": "13086071-d05b-11ec-96db-000000000000",
    "reference": "13086071-d05b-11ec-96db-000000000000",
    "state": "open.running",
    "started": true,
    "userApprovalMode": "api",
    "sendUserApproval": false,
    "failureUrl": "https://www.merchant.com/failure",
    "successUrl": "https://www.merchant.com/success",
    "cancelUrl": "https://www.merchant.com/cancel",
    "pisUrl": "https://proxy-slimcollect.prod.slimpay.com/pis/43333fb1-5f5e-11ed-89ff-000000000000",
    "dateCreated": "2022-05-10T12:16:52.000+0000",
    "dateStarted": "2022-05-10T12:16:55.000+0000",
    "paymentScheme": "PIS.SEPA.CREDIT_TRANSFER",
    "pisTransactionUuid": "43333fb1-5f5e-11ed-89ff-000000000000",
    "checkoutActor": "end_user"
}

Step 2: Redirect the customer to the SlimCollect Checkout

From the order returned by the SlimPay server, you should extract the pisUrl, and redirect the customer to it. We also recommend you to store pisTransactionUuid that you will need later on to retrieve the payment status.

At this stage, the customer will be directed into the payment tunnel. These steps include:

Bank selection
Payment confirmation
Authentication by the selected bank
Bank account selection
Confirm the payment with the bank
and finally the customer will be redirected to the merchant URL (success/cancel/failure)

The pisUrl is valid for 30 days maximum if it is not used. It will expire also if the link is used (when the customer bank is triggerred).

Note: The pisUrl in pre-production will trigger a testing tool that will allow you to simulate the success, failure and cancel use cases.

Step 3: Confirm the payment has been received

By making a Get Order call, you can determine the status of the order. The most common order states include:

closed.completed: the customer has completed a successful order and the payment is received. The mandate is accessible
closed.aborted.aborted_byclient: the customer has abandoned the order
closed.aborted.aborted_byserver: the order was cancelled by the server

To understand fully the current status, the order state should be combined with the payment status (by making a Get Payment call, using the pisTransactionUuid as a parameter), that can be in the following state:

toprocess: the payment has been created
processing: the payment has been issued by the customer’s bank
processed: the payment is received by SlimPay for the merchant
notprocessed: the payment will not happen

A complete view of the state machine is illustrated below (slimCollectPayUnSigned):

*Note: Four banking days from the moment the payment status is set to "ExecutionStatus.processing". The change is made the following night, 2:10am UTC.

Step 4: Retrieve the mandate information by API

Once the order is successful and the payment is received, SlimCollect allows you to build a SEPA mandate with the payment information collected (IBAN, debtor's name, debtor's address). All this information can be retrieved thanks to a number of API calls when the order is in the closed.completed state:

Get Mandate: to retrieve the mandate information (RUM, also called reference)
Get Signatory: to retrieve the debtor name (givenName will contain all the information)
Get Signatory Billing address: to retrieve the debtor's address (extract from street1 and street2 and country to retrieve the full address)
Get Bank Account: to retrieve the debtor's IBAN and BIC

Step 5: Retrieve the mandate information by Dashboard

You can also access mandate information using the SlimPay Dashboard. Select the Authorizations tab, and filter mandates by 'Creation Channel' to narrow down your search. Selecting it will give you access to all the debtor information.

Enrolling a customer for SlimCollect Verify

In the case you do not need to have a first payment (freemium case), SlimCollect Verify is offering an alternative to SlimCollect Pay. It allows you to create a signed mandate through a seamless journey, where customers select their bank and their bank account being authenticate from their banking account. At the same time, our SlimCollect solution builds and stores a SEPA mandate that can be used to process future recurrent payments.

As the steps are similar to SlimCollect Pay, we will focus below on the differences.

Step 1: Create the Checkout transaction

To create a SlimCollect single transaction, you can customize the create-orders relation. The basic parameters of the request body are as follows:

{
    "started": 1,
    "creditor": {
        "reference": "yourCreditorReference"
    },
    "subscriber": {
        "reference": "theSubscriberReference",
    },
    "items": [
        {
        "type": "signMandateAis",
         "mandate": {
            "signatory": {
                "billingAddress": {
                 "street1": "27 rue des fleurs",
                 "city": "France",
                 "postalCode": "75008",
                 "country": "FR"
              },
              "honorificPrefix": "Mr",
              "familyName": "John",
              "givenName": "Doe",
              "email": "change.me@slimpay.com",
             },
             "standard": "SEPA",
             "market":"FR"
           }
         }
    ],
    "successUrl": "https://www.merchant.com/success",
    "failureUrl": "https://www.merchant.com/failure",
    "cancelUrl": "https://www.merchant.com/cancel",
    "userApprovalMode": "api"
    "locale": "EN"
    }

Once all the parameters are defined, you can target the following URL:

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

{
        "id": "b3f86394-3752-11ee-a649-000000000000",
        "reference": "b3f86394-3752-11ee-a649-000000000000",
        "state": "open.running",
        "locale": "en",
        "started": true,
        "userApprovalMode": "api",
        "sendUserApproval": false,
        "registrationType": "signatureAis",
        "failureUrl": "https://www.merchant.com/failure",
        "successUrl": "https://www.merchant.com/success",
        "cancelUrl": "https://www.merchant.com/cancel",
        "aisUrl": "https://proxy-slimcollect.preprod.slimpay.com/ais/b4247d14-3752-11ee-b245-000000000000",
        "dateCreated": "2022-08-10T07:51:24.000+0000",
        "dateStarted": "2022-08-10T07:51:25.000+0000",
        "aisTransactionUuid": "b4247d14-3752-11ee-b245-000000000000",
        "paymentScheme": "SEPA.DIRECT_DEBIT.CORE",
        "checkoutActor": "end_user"
}

Step 2: Redirect the customer to the SlimCollect Checkout

From the order returned by the SlimPay server, you should extract the aisUrl, and redirect the customer to it.

At this stage, the customer will be directed into the payment tunnel. These steps include:

Bank selection
Authentication by the selected bank
Bank account selection
and finally the customer will be redirected to the merchant URL (success/cancel/failure)

The aisUrl is valid for 30 days maximum if it is not used.

The mandate is available as soon as the enduser is reaching the success page. You can retrieve the information through API or using the Dashboard

Note: The aisUrl in pre-production will trigger a testing tool that will allow you to simulate the success, failure and cancel use cases.