API Skeerel (2.0.0)

The Skeerel API is designed to let you create an intuitive interface between your e-commerce website and our REST API

Base url: https://api.skeerel.com/v2

General information

Libraries and sample applications

In order to ease the integration of Skeerel on your website, we have developped some libraries. Below is a recap of all the (official) resources available for you.

Language Library Sample application
Java Library Sample application
PHP Library Sample application

Generate a state token

On the page where you show the Skeerel button to your user, you have to generate and set a session token in order to avoid some XSRF attacks.

<?php 
// Example with the Skeerel PHP library
\Skeerel\Skeerel::generateSessionStateParameter();

Show the button (easy way)

In order to connect or pay, a user must clic on the Skeerel button.

It's quite simple to insert the button on your page. Just paste this code where you want the button to appear

Snippet

<script type="text/javascript" src="https://cdn.skeerel.com/assets/v2/javascript/api.min.js"
    id="skeerel-api-script"
    data-website-id="YOUR_WEBSITE_ID"
    data-state="mlfpo5ir4nvw"
    data-redirect-url="https://site.com/skeerel/finalize.php"
    data-need-shipping-address=""
    data-need-billing-address=""
    data-delivery-methods-url="https://site.com/skeerel/delivery_methods.php?user=__USER__&zip_code=__ZIP_CODE__&city=__CITY__&country=__COUNTRY__"
    data-checkout=""
    data-amount="1000"
    data-currency="eur"></script>

Parameters

Parameter Required Description
id true Identifier of the button
data-website-id true the identifier of the website
data-state true the session state parameter
data-redirect-url true the url where the user will be redirected once he has complete
data-text-button false set custom text for the button
data-profile-id false skeerel's profile ID that has to be used for the session
data-need-shipping-address false in case you need a shipping address
data-need-billing-address false in case you need a billing address
data-delivery-methods-url false If you need to ship something to the user
data-checkout false if the session is for the user to pay
data-payment-test-mode false if the payment must be done in test mode
data-amount false amount is in the smallest common currency unit. For instance 1000 for 10,00€, 10.00USD or ¥1000
data-currency false the currency of the transaction (only eur)
data-custom false custom data sent back at the end of the session

Show the button (custom way)

By using the custom JavaScript integration, you have more control on the code. Here are the main advantages:

  • Script can be inserted anywhere (not where you want the button to appear)
  • Possibility to design your own button
  • Sometimes, prices are generated dynamically, so you can start the process on user click
  • You can also cancel the action and start a new process, by creating a new object.

Snippet

<html>
  <head>...</head>
  <body>
    ...
    <div id="skeerel-button-holder"></div>
    ...

    <script type="text/javascript" src="https://cdn.skeerel.com/assets/v2/javascript/api.min.js"></script>
    <script type="text/javascript">
      //****************************************//
      //********* SKEEREL CHECKOUT *************//
      //****************************************//
      // In case you want the default button (as shown with easy method)
      // You can also create your own button and not use this function
      SkeerelCheckout.insertDefaultButton(document.getElementById("skeerel-button-holder"), "skeerel-pay-button");

      document.getElementById("skeerel-pay-button").onclick = function() {
        var skeerelCheckout = new SkeerelCheckout(
                "YOUR_WEBSITE_ID", // Website id
                "mlfpo5ir4nvw", // state parameter
                "https://site.com/skeerel/finalize.php", // redirect url
                true, // need shipping address?
                "https://site.com/skeerel/delivery_methods.php?user=__USER__&zip_code=__ZIP_CODE__&city=__CITY__&country=__COUNTRY__", // delivery methods url
                1000, // amount to pay
                "eur", // currency
                null, // profile id
                null, // custom data
                true // is test mode?
        );

        // Create and show the iframe
        skeerelCheckout.start();

        // at some point if you want to cancel the process
        skeerelCheckout.cancel();
      };


      //****************************************//
      //********* SKEEREL CONNECT *************//
      //****************************************//
      SkeerelAuth.insertDefaultButton(document.getElementById("skeerel-button-holder"), "skeerel-connect-button");

      document.getElementById("skeerel-connect-button").onclick = function() {
        var skeerelAuth = new SkeerelAuth(
                "YOUR_WEBSITE_ID", // Website id
                "mlfpo5ir4nvw", // state parameter
                "https://site.com/skeerel/finalize.php", // redirect url
                null, // profile id
                null, // custom data
        );

        // Create and show the iframe
        skeerelAuth.start();

        // at some point if you want to cancel the process
        skeerelAuth.cancel();
      };
    </script>
  </body>
</html>

Parameters (Skeerel Authentication)

Position Parameter Required Type Description
0 website_id true string the identifier of the website
1 state true string the session state parameter
2 redirect_url true string the url where the user will be redirected once he has complete
3 profile_id false string skeerel's profile ID that has to be used for the session
4 custom false string custom data sent back at the end of the session

Parameters (Skeerel Checkout)

Position Parameter Required Type Description
0 website_id true string the identifier of the website
1 state true string the session state parameter
2 redirect_url true string the url where the user will be redirected once he has complete
3 need_shipping_address true boolean in case you need a shipping address
4 delivery_methods_url true string If you need to ship something to the user
5 amount true integer amount is in the smallest common currency unit. For instance 1000 for 10,00€, 10.00USD or ¥1000
6 currency true string the currency of the transaction (only eur)
7 profile_id false string skeerel's profile ID that has to be used for the session
8 custom false string custom data sent back at the end of the session
9 test_mode false boolean if the payment must be done in test mode

About redirect url

When the authentication or checkout process is complete, the user is redirected to the redirect_url page you set up with JavaScript.

Just before redirecting the user, the URL is slightly modified to insert some parameters:

  • token: the token needed to validate the payment
  • state: the state parameter you will compare the one you generated to and saved in the user's session.

These parameters are inserted as query parameters, like this:
https://site.com/skeerel/finalize.php?token=TOKEN&state=STATE

If you already had some custom query parameters in the url you gave us, it will still work, as we will modify the url like this:
https://site.com/skeerel/finalize.php?customVar=customValue&token=TOKEN&state=STATE

Dealing with delivery methods

Description

When a user pays with Skeerel, it's likely that you will have to ship its order. In that case, just set the url that Skeerel should call to get your delivery methods in your data-delivery-methods-url parameter. For instance:

https://site.com/path/to/delivery/methods
https://site.com/path/to/delivery/methods?uid=__USER___
https://site.com/path/to/delivery/methods?uid=__USER__&zip_code=__ZIP_CODE&city=__CITY__&country=__COUNTRY__
https://site.com/path/to/delivery/methods?some_var=some_value&zip_code=__ZIP_CODE&city=__CITY__&country=__COUNTRY__

You can personalize your url as you like, for instance a custom variable weight for the package weight.

Note that __USER__ (user identifier), __ZIP_CODE__, __CITY__, __COUNTRY__ (two letters country code) are generics values that will be replaced automatically before calling your page.

In case of a guest checkout, __USER__ value will be set to empty string.

Expected format

You can get more information on the format of the expected json on the Delivery methods model.

Please, note that with the official libraries, there are objects that let you create your delivery methods in an easy way.

Authentication

In order to authenticate a request, you have to send your website_id and your website_secret with each request as query parameters, alongside with other eventual parameters.

website_id

the identifier of the website as a UUID. for Instance website_id=769ae9d7-42b6-4f09-88a2-8d75b10f7c9a

Security Scheme Type API Key
Query parameter name: website_id

website_secret

the secret key of the website. for Instance website_secret=epmrA0Rhj6YPs0lnUF2stT...

Security Scheme Type API Key
Query parameter name: website_secret

Payment

Get details on completion

When a user logs in or pays with Skeerel, the browser will redirect him automatically to your data-redirect-url parameter. From here, you have to call this webservice with the provided token to get information about the authentication or the payment.

Authorizations:
query Parameters
access_token
required
string
Example: access_token=eyJhbGciOiJIUzI1NiIsInR5cCI...

the token returned by the redirect_url

Responses

200

success

Response Schema: application/json
status
required
string

the status of the request

data
required
object
default

failure

get /me

API base endpoint

https://api.skeerel.com/v2/me

Request samples

Copy
// Verify that the state parameter is the same
if (\Skeerel\Skeerel::verifyAndRemoveSessionStateParameter($_GET['state'])) {
    $skeerel = new \Skeerel\Skeerel('YOUR_WEBSITE_ID', 'YOUR_WEBSITE_SECRET');
    $data = $skeerel->getData($_GET['token']);
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "status": "ok",
  • "data":
    {
    }
}

Get full information for a given payment

Authorizations:
query Parameters
payment_id
required
string <uuid>
Example: payment_id=32b2fe1a-d987-487b-9fa1-e10964212e76

identifier of the payment

Responses

200

success

Response Schema: application/json
status
required
string

the status of the request

data
required
object (Payment)

Object describing a Payment object

default

failure

get /payment/get

API base endpoint

https://api.skeerel.com/v2/payment/get

Request samples

Copy
$skeerel = new \Skeerel\Skeerel('YOUR_WEBSITE_ID', 'YOUR_WEBSITE_SECRET');
$payment = $skeerel->getPayment("ce365eec-c287-43b6-ad38-25d8d9029fd1");

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "status": "ok",
  • "data":
    {
    }
}

List payments

Authorizations:
query Parameters
live
boolean
Default: true
Example: live=true

filter by live or test payments

first
integer
Default: 0
Example: first=11

first result to fetch

limit
integer
Default: 10
Example: limit=10

maximum payments to fetch

Responses

200

success

Response Schema: application/json
status
required
string

the status of the request

data
required
Array of objects (Payment)
default

failure

get /payment/list

API base endpoint

https://api.skeerel.com/v2/payment/list

Request samples

Copy
$skeerel = new \Skeerel\Skeerel('YOUR_WEBSITE_ID', 'YOUR_WEBSITE_SECRET');
$payment = $skeerel->listPayments(); // last ten payments
$payment = $skeerel->listPayments(true); // only live payments
$payment = $skeerel->listPayments(true, 15, 20); // list twenty payments starting from the fifteenth index

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "status": "ok",
  • "data":
    [
    ]
}

Refund payment

Authorizations:
query Parameters
payment_id
required
string <uuid>
Example: payment_id=32b2fe1a-d987-487b-9fa1-e10964212e76

identifier of the payment

amount
integer <int64>
Example: amount=5000

amount to refund in the currency's smallest unit. Ex 50€ => 5000

Responses

200

success

Response Schema: application/json
status
required
string

the status of the request

default

failure

get /payment/refund

API base endpoint

https://api.skeerel.com/v2/payment/refund

Request samples

Copy
$skeerel = new \Skeerel\Skeerel('YOUR_WEBSITE_ID', 'YOUR_WEBSITE_SECRET');
$skeerel->refundPayment("32b2fe1a-d987-487b-9fa1-e10964212e76"); // full refund
$skeerel->refundPayment("32b2fe1a-d987-487b-9fa1-e10964212e76", 100); // partial refund (amount is in the currency's smallest unit. Ex 50€ => 5000)

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "status": "ok"
}

Capture payment

Authorizations:
query Parameters
payment_id
required
string <uuid>
Example: payment_id=32b2fe1a-d987-487b-9fa1-e10964212e76

identifier of the payment

Responses

200

success

Response Schema: application/json
status
required
string

the status of the request

default

failure

get /payment/capture

API base endpoint

https://api.skeerel.com/v2/payment/capture

Request samples

Copy
$skeerel = new \Skeerel\Skeerel('YOUR_WEBSITE_ID', 'YOUR_WEBSITE_SECRET');
$skeerel->capturePayment("32b2fe1a-d987-487b-9fa1-e10964212e76"); // payment is legit, capture it

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "status": "ok"
}

Reject payment

Authorizations:
query Parameters
payment_id
required
string <uuid>
Example: payment_id=32b2fe1a-d987-487b-9fa1-e10964212e76

identifier of the payment

Responses

200

success

Response Schema: application/json
status
required
string

the status of the request

default

failure

get /payment/reject

API base endpoint

https://api.skeerel.com/v2/payment/reject

Request samples

Copy
$skeerel = new \Skeerel\Skeerel('YOUR_WEBSITE_ID', 'YOUR_WEBSITE_SECRET');
$skeerel