NAV Navbar
shell

Introduction

Welcome to the Spotii API!

Merchants can use our API to access Spotii API endpoints, which can checkout, capture and refund.

Spotii offers integration with 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
reference String Merchant's unique reference ID
display_reference String Display of merchant's 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" 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
tax_amount Decimal Tax amount.
shipping_amount Decimal Shipping amount.
discount Decimal Discount amount.
customer Customer Customer information.
billing_address Billing Billing address.
shipping_address Shipping Shipping address.
lines Line A list of line objects.

▫️ Customer

{
  "first_name": "George",
  "last_name": "Clooney",
  "email": "g.clooney@example.com",
  "phone": "+971559993322"
}
Parameter Type Description
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
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
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.

▫️ Line

{
  "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
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" for production.
image_url String Line image url.

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.

HTTP Request

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

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.

HTTP Request

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

Query Parameters

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

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.
500 Internal Server Error -- We had a problem with our server. Try again later.

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