Authentication

A merchant’s SlimPay account is identified by a creditor reference, which is allocated by SlimPay. To access a merchant’s (creditor’s) account, you need to have an app. This presents a number of scenarios:

One app, one creditor

This is the most common use case, where a merchant has a single SlimPay account, accessed by a single application.

Multiple apps, one creditor

Similar to UC1, except that the single merchant has multiple apps (each with a different return or notification URL). For instance, one merchant collecting payments from multiple sources/websites.

One app, multiple creditors

This use case occurs when a single application has access to multiple SlimPay accounts. This is often the case with our partners.

OAuth 2.0

Every request you make to the SlimPay API is secured by OAuth 2.0 protocol. OAuth is an industry-standard for client authentication, providing access to protected resources on secure URLs.

You will need to provide an access token in the HTTP Authorization header on every call you make to the API. A merchant can obtain an access token through HTTP Basic authentication. This can be done in four easy steps:

  1. Have your app name and app secret at hand (both of these can be found on the App Management tab of your Dashboard)
  2. Concatenate these with a colon : as a separator (appname:appsecret)
  3. Encode the result of step 2 using base 64
  4. Send a POST request to <server>/oauth/token like this:
POST https://api.preprod.slimpay.com/oauth/token HTTP/1.1
Accept: application/json
Authorization: Basic ValueFrom3
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=api

Be sure to include all the headers (Accept, Authorization and Content-Type) as well as the URL encoded message body (which tells the server what kind of access you want).

The response from the SlimPay server should look like this:

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZSI6WyJhcGkiXSwiZXhwIjoxNDg2Mzk0ODM2LCJqdGkiOiIxMzhkNjA4My01ZTEzLTQwMjItYjQyOS01ZmY0YjM5MzgyZGIiLCJjbGllbnRfaWQiOiJkZW1vY3JlZGl0b3IwMSJ9.3X1jVsL5CCSASwwAWHV599Xyo1TKKn4jpHMzSzE6TWE",
    "token_type": "bearer",
    "expires_in": 985,
    "scope": "api",
    "jti": "899a8019-328d-41bb-876a-980f1c768453"
}

Now that you’ve obtained a valid access_token, this must be used for all requests you send to the server via the Authorization header: 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZSI6WyJhcGkiXSwiZXhwIjoxNDg2Mzk0ODM2LCJqdGkiOiIxMzhkNjA4My01ZTEzLTQwMjItYjQyOS01ZmY0YjM5MzgyZGIiLCJjbGllbnRfaWQiOiJkZW1vY3JlZGl0b3IwMSJ9.3X1jVsL5CCSASwwAWHV599Xyo1TKKn4jpHMzSzE6TWE

Notice that the Authorization is now set to Bearer rather than Basic.

Token lifetime

An access token has a maximum length of 500 characters and it is valid for about 16 minutes (985 seconds in the above example). This means:

  1. Your access token can be stored and used for as many requests as you want to make during this time
  2. If you redo the Basic authentication process outlined above while your access token is still valid, you will still get the same token. Only the expires_in value will be reset

With this in mind, the best way to handle multiple HTTP requests is to keep using the same token until our server responds with a 401 Unauthorised error code (because the token expired). At that point, ask for a new token and rerun your most recent request (but only once; if you get another 401 Unauthorised error, something is wrong with your access credentials).

Generate a new app secret

At some point, you may wish to change your app secret. This can be done from the “App Management” panel in our Dashboard.

You can also change your app secret using our API by authenticating as a user, not an app:

  1. Prepare your creditor reference and your dashboard login and password provided by SlimPay
  2. Concatenate the three with a hash # then a colon : as separators (creditor#login:password)
  3. Encode the result of step 2 using base 64
  4. Send a POST request to <server>/oauth/token like this:
POST https://api.preprod.slimpay.com/oauth/token HTTP/1.1
Accept: application/json
Authorization: Basic ValueFrom3
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=api_admin

Be sure to include all the headers (Accept, Authorization and Content-Type) as well as the URL encoded message body (which in this case tells the server you want admin access to the API).

The response from the SlimPay server should look like this:

{
  "access_token" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZSI6WyJhcGlfYWRtaW4iXSwiZXhwIjoxNDg4NTU5MTA0LCJqdGkiOiJmMzBhYzdiNC05MzE4LTQ0YWQtOWIxMS00NDNhNzhmNDA3YmYiLCJjbGllbnRfaWQiOiJkZW1vY3JlZGl0b3Ijcm9kb2xwaGUucm9jY2FAc2xpbXBheS5jb20ifQ.xiXChXDAi5y7PZAi9DVSGEZ3mmjcaGzUzI_TW6AhL2k",
  "token_type" : "bearer",
  "expires_in" : 998,
  "scope" : "api_admin",
  "jti" : "f30ac7b4-9318-44ad-9b11-443a78f407bf"
}

With this access token, you’ll have access to other links at the entry point that will allow you to fetch your apps and generate a new app secret.