Checkout API

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 and/or document(s) signatures can be obtained in a single transaction.

This step-by-step guide will show you how to use our Checkout API solution. This involves creating the Checkout via order creation transaction, Sign the order with Otp or Checkbox, then, informing you as the merchant when the transaction is completed, and finally getting the mandate and/or document(s)

The Checkout API 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:

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.

All the data you provide must conform to the constraints outlined in our comprehensive #create-order in API reference.

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 and/or document) resources. Below is an example of the create-orders API call body for signing a mandate and a document (we can also sign a mandate only or a document only) :


{
    "started": 1,
    "paymentScheme": "SEPA.DIRECT_DEBIT.CORE",
    "userApprovalMode": "api",
    "otpChannelType": "sms",
    "creditor": {
        "reference": "{{creditor-reference}}"
    },
    "subscriber": {
        "reference": "{{creditor-reference}}"
    },
    "items": [
        {
            "type": "signMandate",
            "signatureApproval": {
                "paymentProcessor": "slimpay",
                "method": {
                    "type": "otp"
                }
            },
            "mandate": {
                "signatory": {
                    "honorificPrefix": "Mr",
                    "familyName": "Doe",
                    "givenName": "John",
                    "telephone":"{{tel}}",
                    "email": "{{email}}",
                    "billingAddress": {
                        "street1": "27 rue des fleurs",
                        "street2": "Bat 2",
                        "postalCode": "75008",
                        "city": "Paris",
                        "country": "FR"
                    },
                    "bankAccount": {
                        "iban": "{{iban}}"
                    }
                }
            }
        },
        {
            "type": "document",
            "document": {
                "signatory": {
                    "honorificPrefix": "Mr",
                    "familyName": "Doe",
                    "givenName": "John",
                    "telephone":"{{tel}}",
                    "email": "{{email}}",
                    "billingAddress": {
                        "street1": "27 rue des fleurs",
                        "street2": "Bat 2",
                        "postalCode": "75008",
                        "city": "Paris",
                        "country": "FR"
                    }
                },
                "binaryContent": {
                    "content": "JVBERi0xLjQKJeLjz9MKNCAwIG9iago8PC9NSzw8L0JDWzEgMSAxXS9CR1sxIDEgMV0+Pi9GIDQvVHlwZS9Bbm5vdC9TdWJ0eXBlL1dpZGdldC9SZWN0WzIwMCA2MzIgMTQ0IDc4MF0vRlQvU2lnL0RSPDw+Pi9UKFNpZ25hdHVyZURlYnRvcikvQVA8PC9OIDIgMCBSPj4vUCAxIDAgUj4+CmVuZG9iago1IDAgb2JqCjw8L0xlbmd0aCA4Mi9GaWx0ZXIvRmxhdGVEZWNvZGU+PnN0cmVhbQp4nCvkcgrhMjZTsDAwUwhJ4TJQ0DW0ADH03QwVDI0UQtK4NHwT81ISSxRSUhVKUotLNEOygKoMUBRrBGem5yWWlBalWikgybuGcAVyAQBzAxfgCmVuZHN0cmVhbQplbmRvYmoKMSAwIG9iago8PC9QYXJlbnQgNiAwIFIvQ29udGVudHMgNSAwIFIvVHlwZS9QYWdlL1Jlc291cmNlczw8L1Byb2NTZXQgWy9QREYgL1RleHQgL0ltYWdlQiAvSW1hZ2VDIC9JbWFnZUldL0ZvbnQ8PC9GMSAzIDAgUj4+Pj4vTWVkaWFCb3hbMCAwIDU5NSA4NDJdL0Fubm90c1s0IDAgUl0+PgplbmRvYmoKMyAwIG9iago8PC9CYXNlRm9udC9IZWx2ZXRpY2EvVHlwZS9Gb250L0VuY29kaW5nL1dpbkFuc2lFbmNvZGluZy9TdWJ0eXBlL1R5cGUxPj4KZW5kb2JqCjIgMCBvYmoKPDwvVHlwZS9YT2JqZWN0L1Jlc291cmNlczw8L1Byb2NTZXQgWy9QREYgL1RleHQgL0ltYWdlQiAvSW1hZ2VDIC9JbWFnZUldPj4vU3VidHlwZS9Gb3JtL0JCb3hbMCAwIDcyIDQ4XS9NYXRyaXggWzEgMCAwIDEgMCAwXS9MZW5ndGggMjYvRm9ybVR5cGUgMS9GaWx0ZXIvRmxhdGVEZWNvZGU+PnN0cmVhbQp4nDPQM1UwAGJzQyBhYg4kilIVghUANCwEqgplbmRzdHJlYW0KZW5kb2JqCjYgMCBvYmoKPDwvVHlwZS9QYWdlcy9Db3VudCAxL0tpZHNbMSAwIFJdPj4KZW5kb2JqCjcgMCBvYmoKPDwvRmllbGRzWzQgMCBSXS9EQSgvSGVsdiAwIFRmIDAgZyApL0RSPDw+Pj4+CmVuZG9iago4IDAgb2JqCjw8L1R5cGUvQ2F0YWxvZy9BY3JvRm9ybSA3IDAgUi9QYWdlcyA2IDAgUj4+CmVuZG9iago5IDAgb2JqCjw8L1Byb2R1Y2VyKGlUZXh0riA1LjQuMSCpMjAwMC0yMDEyIDFUM1hUIEJWQkEgXChBR1BMLXZlcnNpb25cKSkvTW9kRGF0ZShEOjIwMTUwNzIzMTEzMjAxKzAyJzAwJykvQ3JlYXRpb25EYXRlKEQ6MjAxNTA3MjMxMTMyMDErMDInMDAnKT4+CmVuZG9iagp4cmVmCjAgMTAKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMzE4IDAwMDAwIG4gCjAwMDAwMDA1NzcgMDAwMDAgbiAKMDAwMDAwMDQ4OSAwMDAwMCBuIAowMDAwMDAwMDE1IDAwMDAwIG4gCjAwMDAwMDAxNzAgMDAwMDAgbiAKMDAwMDAwMDgwMiAwMDAwMCBuIAowMDAwMDAwODUzIDAwMDAwIG4gCjAwMDAwMDA5MTQgMDAwMDAgbiAKMDAwMDAwMDk3NCAwMDAwMCBuIAp0cmFpbGVyCjw8L1Jvb3QgOCAwIFIvSUQgWzw0NjJjYWU2OGMzYWMyNTI4ZWI2NjI0YWYxOWM2N2ZiZj48OTUwZGIzYTllNDZhMGUwNTIwOTZhMmJhZDc1OTk4OWY+XS9JbmZvIDkgMCBSL1NpemUgMTA+PgolaVRleHQtNS40LjEKc3RhcnR4cmVmCjExMjcKJSVFT0YK"
                },
                "label": "label-7631859"
            }
        }
    ]
}

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


{
    "_links": {
        "self": {
            "href": "https://api.preprod.slimpay.com/orders/71d33ca6-393a-11ef-82e1-000000000000"
        },
        "profile": {
            "href": "https://api.preprod.slimpay.com/alps/v1/orders"
        },
        "https://api.slimpay.net/alps#get-creditor": {
            "href": "https://api.preprod.slimpay.com/creditors/rmadridfc"
        },
        "https://api.slimpay.net/alps#get-subscriber": {
            "href": "https://api.preprod.slimpay.com/subscribers/66ea683d-ec2f-11ee-80dc-000000000000"
        },
        "https://api.slimpay.net/alps#get-order-items": {
            "href": "https://api.preprod.slimpay.com/orders/71d33ca6-393a-11ef-82e1-000000000000/order-items"
        },
        "https://api.slimpay.net/alps#cancel-order": {
            "href": "https://api.preprod.slimpay.com/orders/71d33ca6-393a-11ef-82e1-000000000000/cancellation"
        },
        "https://api.slimpay.net/alps#send-otp": {
            "href": "https://api.preprod.slimpay.com/orders/71d33ca6-393a-11ef-82e1-000000000000/otp-sending"
        },
        "https://api.slimpay.net/alps#sign-order": {
            "href": "https://api.preprod.slimpay.com/orders/71d33ca6-393a-11ef-82e1-000000000000/signing"
        }
    },
    "id": "71d33ca6-393a-11ef-82e1-000000000000",
    "reference": "71d33ca6-393a-11ef-82e1-000000000000",
    "state": "open.running",
    "locale": "en",
    "started": true,
    "userApprovalMode": "api",
    "otpChannelType": "sms",
    "sendUserApproval": false,
    "registrationType": "signature",
    "dateCreated": "2024-07-03T12:47:45.000+0000",
    "dateStarted": "2024-07-03T12:47:45.000+0000",
    "paymentScheme": "SEPA.DIRECT_DEBIT.CORE",
    "checkoutActor": "end_user"
}

Take note of the order id (71d33ca6-393a-11ef-82e1-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!

Step 2: Sign order

At this stage, a signing should be processed. Signing request body depends on the signing approval method (Otp, Checkbox).
The link used to sign the order is within the #create-order response links => #sign-order

Signing Request :

Signing by OTP

The Otp code is sent after the first call #create-order. If something went wrong then call #send-otp for Otp resend

Request body : 


{
  "credentials": {
    "otpCode" : "1234"
  }
}
Signing by Checkbox
For signing by Checkbox, OTP code is not needed. The body is empty.

Signing Response :

The response (for both OTP and Checkbox) looks something like this:


{
    "_links": {
        "self": {
            "href": "https://api.preprod.slimpay.com/orders/71d33ca6-393a-11ef-82e1-000000000000"
        },
        "profile": {
            "href": "https://api.preprod.slimpay.com/alps/v1/orders"
        },
        "https://api.slimpay.net/alps#get-creditor": {
            "href": "https://api.preprod.slimpay.com/creditors/rmadridfc"
        },
        "https://api.slimpay.net/alps#get-subscriber": {
            "href": "https://api.preprod.slimpay.com/subscribers/66ea683d-ec2f-11ee-80dc-000000000000"
        },
        "https://api.slimpay.net/alps#get-order-items": {
            "href": "https://api.preprod.slimpay.com/orders/71d33ca6-393a-11ef-82e1-000000000000/order-items"
        },
        "https://api.slimpay.net/alps#get-mandate": {
            "href": "https://api.preprod.slimpay.com/mandates/882b4c0d-393a-11ef-a3f2-000000000000"
        },
        "https://api.slimpay.net/alps#get-document": {
            "href": "https://api.preprod.slimpay.com/creditors/rmadridfc/documents/11kNHDH00TGmK0ourLpgraYY9ls99lXRNBv"
        }
    },
    "id": "71d33ca6-393a-11ef-82e1-000000000000",
    "reference": "71d33ca6-393a-11ef-82e1-000000000000",
    "state": "closed.completed",
    "locale": "en",
    "started": true,
    "userApprovalMode": "api",
    "otpChannelType": "sms",
    "sendUserApproval": false,
    "registrationType": "signature",
    "dateCreated": "2024-07-03T12:47:45.000+0000",
    "dateStarted": "2024-07-03T12:47:45.000+0000",
    "dateClosed": "2024-07-03T12:48:32.000+0000",
    "paymentScheme": "SEPA.DIRECT_DEBIT.CORE",
    "mandateReused": false,
    "checkoutActor": "end_user"
}

the #get-document type depends on the number of documents to sign. If it's just on document then it contains one object, if there are many documents to sign then it's an array : 


     "https://api.slimpay.net/alps#get-document": [
            {
                "href": "https://api.preprod.slimpay.com/creditors/{{creditor}}/documents/v3y5OvweFGolix1BSJo0KHRu6HqOAuBSAen"
            },
            {
                "href": "https://api.preprod.slimpay.com/creditors/{{creditor}}/documents/yWSDHP0zYcEKLVCluh2hjVrT4OW4XQ5enTC"
            }
        ]

Step 3: Be informed about the Checkout status


Please note: While the notification of the completed Checkout journey is synchronous, SlimPay employs an asynchronous signature process, offering merchants greater protection against failed signatures. As such, although you will receive a success sign-order response, it may take a few seconds before a signed mandate can be retrieved using the get-mandate or get-document relation.

get-mandate and get-document returns non-signed item if called before the real signing (The order is really signed only after receiving a notification).

Notification URLs:

  • 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.

Step 4: getting the mandate and/or document(s)

get mandate Response :

The response looks something like this:


{
    "_links": {
        "self": {
            "href": "https://api.preprod.slimpay.com/mandates/882b4c0d-393a-11ef-a3f2-000000000000"
        },
        "profile": {
            "href": "https://api.preprod.slimpay.com/alps/v1/mandates"
        },
        "https://api.slimpay.net/alps#get-creditor": {
            "href": "https://api.preprod.slimpay.com/creditors/rmadridfc"
        },
        "https://api.slimpay.net/alps#get-subscriber": {
            "href": "https://api.preprod.slimpay.com/subscribers/66ea683d-ec2f-11ee-80dc-000000000000"
        },
        "https://api.slimpay.net/alps#get-document": {
            "href": "https://api.preprod.slimpay.com/mandates/882b4c0d-393a-11ef-a3f2-000000000000/document"
        },
        "https://api.slimpay.net/alps#get-binary-content": {
            "href": "https://api.preprod.slimpay.com/mandates/882b4c0d-393a-11ef-a3f2-000000000000/document"
        },
        "https://api.slimpay.net/alps#revoke-mandate": {
            "href": "https://api.preprod.slimpay.com/mandates/882b4c0d-393a-11ef-a3f2-000000000000/revocation"
        },
        "https://api.slimpay.net/alps#get-signatory": {
            "href": "https://api.preprod.slimpay.com/mandates/882b4c0d-393a-11ef-a3f2-000000000000/signatory"
        },
        "https://api.slimpay.net/alps#get-bank-account": {
            "href": "https://api.preprod.slimpay.com/mandates/882b4c0d-393a-11ef-a3f2-000000000000/bank-account"
        },
        "https://api.slimpay.net/alps#update-bank-account": {
            "href": "https://api.preprod.slimpay.com/mandates/882b4c0d-393a-11ef-a3f2-000000000000/bank-accounts"
        },
        "https://api.slimpay.net/alps#show-bank-accounts-history": {
            "href": "https://api.preprod.slimpay.com/mandates/882b4c0d-393a-11ef-a3f2-000000000000/bank-accounts-history{?page,size}",
            "templated": true
        },
        "https://api.slimpay.net/alps#get-signature-approval": {
            "href": "https://api.preprod.slimpay.com/mandates/882b4c0d-393a-11ef-a3f2-000000000000/signature-approval"
        }
    },
    "id": "882b4c0d-393a-11ef-a3f2-000000000000",
    "reference": "SLMP100024802",
    "rum": "SLMP100024802",
    "state": "active",
    "standard": "SEPA",
    "initialScore": 0,
    "dateCreated": "2024-07-03T12:48:23.000+0000",
    "dateSigned": "2024-07-03T12:48:23.000+0000",
    "paymentScheme": "SEPA.DIRECT_DEBIT.CORE",
    "creationChannel": "SEPA"
}

To get the signed mandate call #get-binary-content

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.

Document templates

SlimPay offers merchants a range of customisation options using document templates. Specific documentation regarding document 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. Specific documentation regarding this test data can be found on the SlimPay Dev Center and Help Center.

Please note: Do no use real data (IBAN, phone number, address etc) during your preprod tests. However, any email addresses provided and used in our preprod environment must be valid, meaning you cannot use false or artificial email addresses in your tests.