API

Overview

Smartex exposes a standard REST based interface, which enables application developers and webmasters an easy, yet powerful and safe integration with the Smartex infrastructure. Through our API, clients can create and manage invoices, issue refunds, manage bills, retrieve real-time rates information, view merchant ledger entries, and much more. Developers have the freedom to rollover their own code, or choose from one of Smartex client libraries, available for most popular programming languages such as Node.js, PHP, Perl, Python and more.

Concepts

Identities & Tokens

In the Smartex API an Identity is represented by the hash of its public key.

Smartex API is designed around Capability-based security principles, any API call must provide a Token granting access to the requested capability and each API call response will provide a new token to access the resource requested. You will need to manage these tokens on your own when not using one of our client libraries.

Facades

Facades correspond to various arrays of capabilities that can be granted. For example, the ability to create invoices or to view ledger entries. An Identity is registered against a specific facade level. Security best practices suggest that the facade granted should be limited to the minimum level for the required capabilities.

Facade Capabilities Description
public The implicit facade applied when no token is provided. Provides access to public methods for generating merchant applications, generating and claiming tokens, or checking exchange rates.
pos Limited to creating new invoices for the merchant's organization
merchant The broadest set of capabilities against a merchant organization. Allows to create, search, and view actions for Invoices and Bills; ledger download, as well as the creation of new merchant or pos tokens associated with the account.

Access

Getting Access

To access any non-public facade a token must be provided with the request. If a token requires authentication each request would require cryptographical signing. You can obtain a token either by generating it via the "My Account -> API Tokens" page, or directly from your application by sending a POST request to smartex.io/tokens with the following query parameters:

  • label (e.g. My Smartex Client)
  • id (e.g. Tf5tYNrKfAdiSjuzsZwRbne6QyWpgKtH6DZ)
  • facade (e.g. merchant)<"My Account -> API Tokens" pag

The response provided will include a token and a pairingCode. A pairing code can be shared with a merchant organization administrator to approve access. This can be done by visiting "My Account -> API Tokens" and entering the pairing code, or by visiting the url format: smartex.io/api-access-request?pairingCode=<pairingcode_goes_here>.

Alternatively, pairing codes can be generated at "My Account -> API Tokens", and can then be activated from your application. To activate a token from an API client, send a POST request to smartex.io/tokens with the following parameters:

  • label (e.g. My Smartex Client)
  • id (e.g. Tf5tYNrKfAdiSjuzsZwRbne6QyWpgKtH6DZ)
  • pairingCode (e.g. As retrieved from My Account -> API Tokens)

If a token does not require authentication it can be used directly to make API calls. Please note that pairing codes will expire after 24 hours if not claimed.

Requests

Signing Your Request

To produce the x-signature header you must concatenate the ECDSA signature of the request URL concatenated with the request body and sign it with your private key. For example when sending a request to:

https://smartex.io/invoices

with a request body of :

{"amount":10,"currency":"USD","token":"1234"}

The resulting string to sign will be :

https://smartex.io/invoices{"amount":10,"currency":"USD","token":"1234"}

The result must be passed as the value of the x-signature request header.

Sessions

You can use sessions in order to further increase security and reliability when interacting with the Smartex API. Sessions protect against replay attacks and ensure that API calls are executed in the order they are submitted.

To create a Session please issue a POST request to /sessions. The server will provide a sessionId in the response. The sessionId is used in each subsequent request along with a requestNumber. You can either pass these parameters via GET in the URL or as data body in a POST or PUTrequest.

The requestNumber should start from 1, and be incremented on each additional request. If the server detects an invalid requestNumber it will return an error. In case of errors in the communication the requestNumber will stay valid and the server will provide a cached response.

Sessions will timeout after 15 minutes of inactivity, after which, the client will get an error and will have to create a new session.

CORS

The Smartex REST API supports Cross-Origin Resource Sharing and allows requests sent directly from clients. Please remember to keep your private key secure. If your key is compromised immediately revoke it and generate a new one.