NAV Navbar
shell

Introduction

Welcome to the Spotii API!

Merchants can use our API to access Spotii API endpoints for checking-out, capturing and refunding Spotii orders.

In addition, Spotii has plugins for the following eCommerce platforms:

Authentication

To authorize, use this code to obtain a temporary bearer token:

curl -v -H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-X POST -d '{
      "public_key": "<your-public-key>",
      "private_key": "<your-private-key>"
    }' https://auth.sandbox.spotii.me/api/v1.0/merchant/authentication/

Make sure to replace <your-public-key> and <your-private-key> with your API keys. The information can be found from your merchant dashboard > settings > integrations.

The above command returns JSON structured like this:

{
  "token": "<temporary-bearer-token>"
}

Spotii uses OAuth 2.0 Bearer Token Usage to allow access to the APIs.

Spotii expects the bearer token authentication to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer <temporary-bearer-token>

Checkout

⚬ Workflow

⚬ Create a Checkout

curl -v -H 'Accept: application/json; indent=4' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <temporary-bearer-token>' \
-X POST -d '{
    "reference": "198776653",
    "display_reference": "198776653",
    "description": "Order #198776653",
    "total": "300.00",
    "currency": "USD",
    "confirm_callback_url": "https://mywebsite.com/?success",
    "reject_callback_url": "https://mywebsite.com/?failed",
    "order": {
        "tax_amount": null,
        "shipping_amount": null,
        "discount": null,
        "customer": {
          "first_name": "George",
          "last_name": "Clooney",
          "email": "g.clooney@example.com",
          "phone": "+971559993322"
        },
        "billing_address": {
            "title": "Mr",
            "first_name": "George",
            "last_name": "Clooney",
            "line1": "My House 12",
            "line2": "",
            "line3": "",
            "line4": "Dubai",
            "state": "",
            "postcode": "4400",
            "country": "AE",
            "phone": "+971559993322"
        },
        "shipping_address": {
            "title": "Mr",
            "first_name": "George",
            "last_name": "Clooney",
            "line1": "My House 12",
            "line2": "",
            "line3": "",
            "line4": "Dubai",
            "state": "",
            "postcode": "4400",
            "country": "AE",
            "phone": "+971559993322"
        },
        "lines": [
          {
            "sku": "sku-1",
            "reference": "reference-1",
            "title": "Livingston All-Purpose Tight",
            "upc": "upc-1",
            "quantity": 1,
            "price": "300.00",
            "currency": "USD",
            "image_url": "http://mywebsite.com/products/mh07-gray_main_2.jpg"
          }
        ]
    }
}' https://api.sandbox.spotii.me/api/v1.0/checkouts/

The above command returns JSON structured like this:

{
    "reference": "198776653",
    "display_reference": "198776653",
    "description": "Order #198776653",
    "total": "300.00",
    "currency": "USD",
    "confirm_callback_url": "https://mywebsite.com/?success",
    "reject_callback_url": "https://mywebsite.com/?failed",
    "order": {
        "tax_amount": null,
        "shipping_amount": null,
        "discount": null,
        "customer": {
            "first_name": "George",
            "last_name": "Clooney",
            "email": "g.clooney@example.com",
            "phone": "+971559993322"
        },
        "billing_address": {
            "title": "Mr",
            "first_name": "George",
            "last_name": "Clooney",
            "line1": "My House 12",
            "line2": "",
            "line3": "",
            "line4": "Dubai",
            "state": "",
            "postcode": "4400",
            "country": "AE",
            "phone": "+971559993322"
        },
        "shipping_address": {
            "title": "Mr",
            "first_name": "George",
            "last_name": "Clooney",
            "line1": "My House 12",
            "line2": "",
            "line3": "",
            "line4": "Dubai",
            "state": "",
            "postcode": "4400",
            "country": "AE",
            "phone": "+971559993322"
        },
        "lines": [
            {
                "line_id": "b05508f7-825f-413a-8fa6-ce6fff24315d",
                "sku": "sku-1",
                "reference": "reference-1",
                "notes": null,
                "title": "Livingston All-Purpose Tight",
                "upc": "upc-1",
                "quantity": 1,
                "price": "300.00",
                "currency": "USD",
                "image_url": "http://mywebsite.com/products/mh07-gray_main_2.jpg"
            }
        ]
    },
    "checkout_url": "https://sandbox.spotii.me/checkout/?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1ODE5MzQ5NDAsImNoZWNrb3V0X2lkIjoiYmM2ODg5ZDctZDc5Mi00MDAyLWE4OGQtOTgwZjJjNzg0Mjk1In0.K-U4pRnfaNZ4aCKR-OFy9zVrIywhBaNlCOTAZEmzaLE"
}

This endpoint creates a merchant checkout. Upon a successful request, a checkout_url link will be provided for the merchant's customer to process payment at Spotii's payment portal. If payment is successful, the customer will be redirected to the provided confirm_callback_url link. Else if payment is rejected, the customer will be redirected to the provided reject_callback_url link.

HTTP Request

POST https://api.sandbox.spotii.me/api/v1.0/checkouts/

Query Parameters

Parameter Type Description Required
reference String Unique Reference ID
display_reference String Display of unique reference ID
description String Order description
total Decimal Total amount of the order, including tax, shipping and discount.
currency Currency ISO 4217 order currency. Currently supports "USD" for sandbox and "AED" or "SAR" for production.
confirm_callback_url String Merchant URL for confirmed order
reject_callback_url String Merchant URL for rejected order
order Order Order information.

Order

{
  "tax_amount": null,
  "shipping_amount": null,
  "discount": null,
  "customer": {},
  "billing_address": {},
  "shipping_address": {},
  "lines": []
}
Parameter Type Description Required Nullable
tax_amount Decimal Tax amount.
shipping_amount Decimal Shipping amount.
discount Decimal Discount amount.
customer Customer Object Customer information.
billing_address Billing Object Billing address.
shipping_address Shipping Object Shipping address.
lines Lines ArrayOf(Object) A list of line objects.

Customer

{
  "first_name": "George",
  "last_name": "Clooney",
  "email": "g.clooney@example.com",
  "phone": "+971559993322"
}
Parameter Type Description Required
first_name String First name.
last_name String Last name.
email String A valid email address.
phone String Phone number.

Billing

{
  "title": "Mr",
  "first_name": "George",
  "last_name": "Clooney",
  "line1": "My House 12",
  "line2": "",
  "line3": "",
  "line4": "Dubai",
  "state": "",
  "postcode": "4400",
  "country": "AE",
  "phone": "+971559993322"
}
Parameter Type Description Required
title String Title.
first_name String First name.
last_name String Last name.
line1 String Street address.
line2 String Apartment, suite, floor, etc.
line3 String Optional
line4 String City
state String State or Region or Province.
postcode String Postal Code.
country Country ISO 3166 alpha-2 country code.
phone String Phone number.

Shipping

{
  "title": "Mr",
  "first_name": "George",
  "last_name": "Clooney",
  "line1": "My House 12",
  "line2": "",
  "line3": "",
  "line4": "Dubai",
  "state": "",
  "postcode": "4400",
  "country": "AE",
  "phone": "+971559993322"
}
Parameter Type Description Required
title String Title.
first_name String First name.
last_name String Last name.
line1 String Street address.
line2 String Apartment, suite, floor, etc.
line3 String Optional
line4 String City
state String State or Region or Province.
postcode String Postal Code.
country Country ISO 3166 alpha-2 country code.
phone String Phone number.

Lines

{
  "sku": "sku-1",
  "reference": "reference-1",
  "title": "Livingston All-Purpose Tight",
  "upc": "upc-1",
  "quantity": 1,
  "price": "300.00",
  "currency": "USD",
  "image_url": "http://mywebsite.com/products/mh07-gray_main_2.jpg"
}
Parameter Type Description Required
sku String Line SKU.
reference String Reference ID
title String Line title.
upc String Line UPC.
quantity Integer Line quantity.
price String Line price, excluding tax, shipping and discount.
currency Currency ISO 4217 order currency. Currently supports "USD" for sandbox and "AED" or "SAR" for production.
image_url String Line image url.

Order

⚬ Get

An order object will not exist unless the payment is authorized.

Request

curl -v -H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <temporary-bearer-token>' \
-X GET https://api.sandbox.spotii.me/api/v1.0/orders/<reference>/
{
        "order_id": "9d7f31ac-d030-41e4-adf1-8769cae32520",
        "reference": "TDU4YSXB3RY89OG",
        "display_reference": "TDU4YSXB3RY89OG",
        "description": "Order #TDU4YSXB3RY89OG Description:",
        "total": "200.9900",
        "currency": "AED",
        "tax_amount": null,
        "shipping_amount": null,
        "discount": null,
        "customer": {
            "first_name": null,
            "last_name": null,
            "email": "",
            "phone": null
        },
        "billing_address": null,
        "shipping_address": null,
        "lines": [],
        "created_at": "2020-12-13T07:45:25.168325Z",
        "updated_at": "2020-12-13T07:45:29.548974Z",
        "order_number": "9QG738WMHKRW",
        "status": "OPENED",
        "total_refund": "0",
        "capture_expiration": "2020-12-18T07:45:25.168325+00:00",
        "employee_name": "Spotii Merchant"
    }

Response

Excluding values at checkout POST

Parameter Type Description
status String Either OPENED or COMPLETED *
total_refund String The amount of Refunds done on the order
employee_name String Reference ID
capture_expiration String Capture expiry time stamp

⚬ Capture

curl -v -H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <temporary-bearer-token>' \
-X POST https://api.sandbox.spotii.me/api/v1.0/orders/<reference>/capture/

This endpoint captures an order that has been approved by Spotii's payment portal.

Request

Response

Parameter Type Description
status String Transaction status: SUCCESS or FAILURE
order_id String unique order uuid
amount String The amount captured (returned on SUCCESS)
currency Currency ISO 4217 order currency (returned on SUCCESS)
type String Transaction type "CAPTURE" (returned on SUCCESS)

Exceptions

Code Description
404 Transaction does not exist

⚬ Refund

curl -v -H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <temporary-bearer-token>' \
-X POST -d '{
      "total": "100.00",
      "currency": "USD"
    }' https://api.sandbox.spotii.me/api/v1.0/orders/<reference>/refund/

This endpoint refunds an order. This can be done at any time there is no window.

Request

POST https://api.sandbox.spotii.me/api/v1.0/orders/<reference>/refund/

Query Parameters

Parameter Type Description Required
total Decimal Total amount of the order, including tax, shipping and discount.
currency Currency ISO 4217 order currency.

Response

Parameter Type Description
status String Transaction status: SUCCESS or FAILURE
order_id String unique order uuid
amount String The amount captured
currency Currency ISO 4217 order currency
type String Transaction type "REFUND"
transaction_id String unique uuid for the transaction

Exceptions

Code Description
406 Transaction is already refunded or Transaction is still open
404 Transaction does not exist

⚬ Void

curl -v -H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <temporary-bearer-token>' \
-X POST https://api.sandbox.spotii.me/api/v1.0/orders/<reference>/void/

This endpoint voids an OPENED order. This can be done at any time as long as the order is in the OPENED status.

Request

POST https://api.sandbox.spotii.me/api/v1.0/orders/<reference>/void/

Query Parameters

Response

Parameter Type Description
detail String Transaction result: 'Order successfully voided'

Exceptions

Code Description
404 Order missing
406 Order cannot be voided

Errors

Spotii uses conventional HTTP response codes to indicate the success or failure of an API request.

Error Code Meaning
200 OK -- Success.
400 Bad Request -- The request was invalid, please double check the required parameter(s).
401 Unauthorized -- No valid Bearer Token provided.
402 Request Failed -- The parameters were valid but the request failed.
404 Not Found -- The requested resource could not be found.
406 Not Acceptable -- Cannot produce a response matching the list of acceptable values.
500 Internal Server Error -- We had a problem with our server. Try again later.

Loading Spotii Checkout in iframe

Implementation Steps

Spotii reccomends to load all Spotii checkouts in an iframe to improve User Experience and reduce bounce rates.

  1. Import Spotii iframe Script File into your codebase
  2. Guide for Checkout with Spotii:
    • create a Spotii checkout using the /checkouts
    • call loadSpotiiCheckout(checkoutUrl) for the magic to begin

Implementing Spotii Widget

To add Spotii widget on the cart/product page, please add the following code snippet:

<!-- Start of Spotii Cart Widget -->
<script>
  window.spotiiConfig = {
    targetXPath: ['.cart-subtotal__price'],
    renderToPath: ['.cart-subtotal'],
    currency: {{ cart.currency.iso_code | json }},
  };
</script>
<script>
  (function(w,d,s) {
    var widgetLink=d.getElementsByTagName('html')[0].getAttribute('lang')== 'ar'?'https://widget.spotii.me/v1/javascript/price-widget-ar':'https://widget.spotii.me/v1/javascript/price-widget';  var f=d.getElementsByTagName(s)[0];var a=d.createElement('script');a.async=true;a.src= widgetLink;f.parentNode.insertBefore(a,f);
  }(window, document, 'script'));
</script>
<!-- End of Spotii Cart Widget -->

To configure the widget please note the following:

<div class='price-item price-item--sale'>500 AED </div>

When configuring the widget, the selectors will be used like this

targetXPath: ['.price-item.price-item--sale'] 

Click here to view the widget in works!

Platforms

Magento 2

This extension allows you to use Spotii as a payment gateway in your Magento 2 store.

1. Installation steps

  1. composer require spotii/spotiipay
  2. php bin/magento setup:upgrade
  3. php bin/magento setup:di:compile
  4. php bin/magento setup:static-content:deploy
  5. php bin/magento cache:clean

Manual Setup

  1. Sign up for Spotii account at https://dashboard.sandbox.spotii.me/merchant/signup/
  2. In your Magento 2 [ROOT]/app/code/ create folder called Spotii/Spotiipay.
  3. Download and extract files from this repository to the folder.
  4. Open the command line interface.
  5. Enable Spotii by running command below: php bin/magento module:enable Spotii_Spotiipay
  6. Magento setup upgrade: php bin/magento setup:upgrade
  7. Magento Dependencies Injection Compile: php bin/magento setup:di:compile
  8. Magento Static Content deployment: php bin/magento setup:static-content:deploy
  9. Login to Magento Admin and navigate to System/Cache Management
  10. Flush the cache storage by selecting Flush Cache Storage

2a. Admin Configuration

  1. Login to your Magento Admin
  2. Navigate to Store > Configuration > Sales > Payment Methonds > Spotii > Payment Settings
  3. Click Register for Spotii or I’ve already setup Spotii, I want to edit my settings

2b. Payment Setup

  1. Set the Payment Mode to Live for LIVE and set it as Sandbox for SANDBOX.
  2. Set the Merchant ID, Public Key and Private Key. The information can be found from your merchant dashboard.
  3. Set Payment Action as Authorize only for doing payment authorization only and Authorize and Capture for doing authorization as well as payment capture.
  4. Set the Merchant Country as per the origin.
  5. Enable the log tracker to trace the Spotii checkout process.
  6. Save the configuration and clear the cache.

3a. Product Widget Setup

  1. Navigate to Stores/Configuration/Sales/Payment Methods/Spotii/Widget Settings/Product Page in your Magento admin.
  2. Provide the following information below to display the Spotii widget at the product page.
    • Price Block Selector : XPath of the price element.
    • Product page:render to element path : Location where to render the widget.
    • Show in all countries : Yes/No.
    • Alignment : Position of the widget.
    • Theme : Widget theme.
    • Width type : Text width of the widget.
    • Image url : If you want to have different logo, paste the url here.
    • Hide classes : Classes to be hidden when spotii widget is in place.
  3. Save the configuration
  4. Clear the cache.

3b. Cart Widget Setup

  1. Navigate to Stores/Configuration/Sales/Payment Methods/Spotii/Widget Settings/Cart Page in your Magento admin.
  2. Provide the following information below to display the Spotii widget at the product page.
    • Price Block Selector : XPath of the price element.
    • Cart page:render to element path : Location where to render the widget.
    • Show in all countries : Yes/No.
    • Alignment : Position of the widget.
    • Theme : Widget theme.
    • Width type : Text width of the widget.
    • Image url : If you want to have different logo, paste the url here.
    • Hide classes : Classes to be hidden when spotii widget is in place.
  3. Save the configuration
  4. Clear the cache.

WooCommerce

This extension allows you to use Spotii as a payment gateway in your WooCommerce store.

Ensure you have signed up as a merchant on Spotii

1. Installation steps

  1. Get folder ‘spotii-gateway’ from plugin zip
  2. Copy this folder inside /Wordpress [ROOT]/wp-content/plugins/
  3. Ensure folder structure as /wp-content/plugins/spotii-gateway/spotii-gateway.php

2a. Admin Configuration

  1. Login to your Wordpress Admin portal
  2. Navigate to Plugins > Installed Plugins
  3. Look for “Spotii Payment Gateway” in the plugins list and click “Install”
  4. On installation complete, click on “Activate”

2b. Payment Setup

  1. Navigate to WooCommerce > Settings > Payments
  2. Check radio button “Enable” and click on “Set up” on Spotii Gateway
    • Enable Spotii gateway
    • Enable test mode – disable this when going live
    • Put your test (staging) private and public keys in Test fields
    • Put your live (staging) keys in Live fields
    • Save changes

Shopify

For integrating Spotii in Shopify, please get in touch with our Merchant Technical Services team via email: mts@spotii.me

Opencart

The Spotii Checkout Plugin serves as a payment gateway and has been developed for OpenCart version 3.0.2.0.

The link to the Github Repo can be found by Clicking Here

1. Installation steps

OpenCart install files and paths:

Installation of the Spotii Checkout Plugin requires 10 files to be placed in certain locations within your OpenCart code / project folder.

Please copy each file (all named spotii.*) to the corresponding location in the Opencart folder as mentioned below:

File inside the following folder in OC_Spotii_plugin_master.zip / folder

Desired location of this file in Opencart folder

Admin Controller : admin/controller/extension/payment/ 
Admin Language File : admin/language/en-gb/extension/payment/ 
Admin Model File : admin/model/extension/payment/ 
Admin View File : admin/view/template/extension/payment/ 
Image File : admin/view/image/payment/ 
Catalog Controller : catalog/controller/extension/payment/ 
Catalog Language File : catalog/language/en-gb/extension/payment/ 
Catalog Model : catalog/model/extension/payment/
Catalog View File – Spotii.twig and Spotii_error.twig : catalog/view/theme/default/template/extension/payment/

Once these files are in their respective paths, please open your Opencart Admin Panel and follow these steps to install the Spotii Checkout plugin on your Opencart instance:

  1. In the sidebar, select Extensions
  2. In the sub-list, select Extensions again
  3. In the drop-down menu under “Choose the Extension type”, please select Payments
  4. Scroll down to Spotii Payment Method and click on Install
  5. Once installed, click on Edit
  6. In the Edit Spotii Pay section under Spotii Payment Method (see screenshot below), please update the Public / Private keys and select the order status required to be shown when a Spotii payment is successfully processed.
  7. Under test mode, either select Sandbox for test environment or, Live for production environment
  8. The Total field sets a minimum cart amount that is required to enable Spotii checkout option on the cart / checkout page. Default value for this minimum cart amount is AED 200. You can always change this later, as per your business requirements and agreement with Spotii
  9. Order Status: you can select the Order Status that you want to be shown once an order is successfully processed through the Spotii Payment Gateway. You can create a custom status or use any of the default status options that are available (custom order status creation is factory feature of OpenCart).
  10. Please select Status as enabled. This is required for Spotii to be displayed as a payment option on the checkout page. A payment gateway can be installed but will not be available for commercial use unless set as enabled in this screen
  11. Sort order can be set as per merchant preference with relation to other payment gateways
  12. Please click on the Save button on the top right corner to save changes to your Spotii Checkout Plugin

2. Steps to setup Spotii widget on the product and cart page

  1. Add the “div" element just below the price block of code inside the file called “product.twig” (Reference path \catalog\view\theme\default\template\product\product.twig) md Buy Now, Pay Later   Add the “div" element just below the price block of code inside the file called “cart.twig”, (Reference path \catalog\view\theme\default\template\checkout\cart.twig) 
Buy Now, Pay Later

  Copy the file "common.js" from the Spotii plugin folder (\OC_Spotii_Plugin-master\Spotii_OC3.0.2.0_Plugin_V1.0.0) to the common.js file of corresponding location in the file folder (at reference path \catalog\view\javascript\common.js)

Salla

This section describes of how merchants can utilise Spotii as a payment gateway in Salla

Note, an approved Spotii Merchant account is a prerequiste for a merchant to use Spotii in Salla

  1. Login to your Salla account

    • Go to your Salla Admin panel and log in with your username and password.
  2. Navigate to the “Store Settings”

    • In your navigation bar in the admin section scroll down and choose store settings and click on it.
  3. From setting window go to “Payment Methods”

    • Go to your setting menu and look for the payments options tab and click on it.
  4. Select and enable Spotii

    • Scroll and look for spotii option and click to select and enable.
  5. Add the public and private keys that were provided through email and present in Spotii merchant account

    • In the pop up that will show copy and paste the public and private keys that were provided through email and present in Spotii merchant account.
  6. Save the changes and then you are able to go

    • Click save.

Wix

For integrating Spotii in Wix, please get in touch with our Merchant Technical Services team via email: mts@spotii.me

Ecwid

For integrating Spotii in Ecwid, please get in touch with our Merchant Technical Services team via email: mts@spotii.me

Production Checklist