The SMSpay shop API follows loosely the (now old) Paypal Website Payments Standard. Most of the fields used to create an order are the same. All API responses are in JSON.

1. Authentication

Before creating an order or checking a status the merchant must log in. Also every time the API returns a 401, the merchant must reauthenticate. SMSpay currently implements a simple token based authentication over https (JSON Web Token). Upon successful login, the server will return an authorization token. That token must be sent on every following request as the “Authorization” header.

URL for login: https://api.smspay.io/v1/login (POST) Login fields:

  • user (the provided merchant username)
  • password (the provided merchant password)

The server will return a 401 error on login failure or a 200 if the login is successful. The successful message also includes the user’s scope, merchant’s id (to use in the following requests) and the authorization token.

Authorization header example: “Authorization”: “Bearer VyIjoiYWRtaW4iLCJzY29wZSI6WyJhZG1pbiJdLCJpYXQiOjE”

2. Creating new order

The data sent to create an order is composed of two basic parts: Global order data and order item details. All amounts are integer numbers and should be provided in the smallest unit for the currency selected. See ISO 4217 for details. Currently the order fields are not check for consistency. It is assumed that the order is sent correctly.

URL for order creation: https://api.smspay.io/v1/payments (POST) Order fields:

  • phone (required, the customers phone, numbers only with country code)
  • invoice (required, the merchants order number, any string)
  • currency (required, the currency for the order amounts, a 3 letter ISO 4217 code)
  • merchant (required, the merchant’s SMSpay id - provided on login)
  • description (a string with an order description)
  • shipping (global shipping amount for the order)

Order item fields (where X is the sequential number of the item starting at 1):

  • item_number_X (required, the merchants number for this item)
  • item_name_X (required, the merchant’s name for this item
  • amount_X (required, the items amount - “price”)
  • quantity_X (required, the quantity for this item)
  • shipping_X (optional, the shipping amount for this item, send 0 if not used)

Notification fields:

  • success_url (shop url for successful payment notification)
  • failure_url (shop url for payment failure notification)
  • update_url (not implemented yet, shop url of notifying other events such as payment delays and customer registrations - can be removed in the future).

Upon successful order creation the server will return a 200 message with the order info, including the SMSpay reference (id) and status (usually NEW) for that order. If any order parameter fails to validate a 400 error will be returned. If the authentication isn’t valid or has expired a 401 is returned.

SMSpay will calculate the total amount and use that value to capture the payment. The total amount will be presented to the customer and on the API return message.

3. Success/Failure callback

The merchant store should provide a series of url for callback upon certain events. The most important events are the successful payment (or order completion) and payment failure.

The merchant can also be notified of other events such as failure to capture the payment or the triggering of the customer registration process. These could be useful for tracking customer actions after placing the order.

4. Checking order status

The status and details for any order can be checked by calling the SMSpay API providing the order reference.

Url for order status/details: https://api.smspay.io/v1/payments/[reference] (GET) The only required field is the order’s reference (number, part of the path).

The server will return the full details of the order, including order items and transactions (payment gateway events).

Appendix A. Possible order status

  • NEW (order was created)
  • PENDING (waiting customer confirmation/registration)
  • PROCESSING (processing payment)
  • COMPLETE (payment complete)
  • CANCELLED (cancelled by the customer or SMSpay)