Authentication

In order to interact with SMARTy Pay API all your requests must be authenticated.

SMARTy Pay offers two ways to authenticate your API requests:

The HMAC-based authentication option is more robust in terms of security, while Basic authentication may be simpler to integrate. Therefore, the choice of authentication method is up to you.

Any authentication method will require you to create an API Key and Secret.
You can view and manage your API keys in the Partner UI.

Please note that every staging and production API Keys/Secrets are not the same.

Basic authentication

To use basic authentication just pass your API Key & Secret inside the Authorization header.

Basic authentication example

# This code must be on your backend side
# Do not send your Secret into Client Browser!
curl https://partner-api.smartypay.io/v1/dictionary/blockchains \
    -u API_KEY:SECRET

HMAC-based Signing Requests

Authentication information is passed through several HTTP headers listed below.

Header	Description	Example
x-api-key	API Key	TVs1OAkZXCZ0Azk0Qd9rFMxIYKVlLSUg
x-api-sig	Request signature in hex	5ef1c...de684c2602980cf03292abf
x-api-ts	Timestamp of this request (in seconds)	1623659516033

SMARTy Pay uses HMAC-SHA256 algorithm to create a signature (or so-called message authentication code) using provided API Secret. To create a message/payload to sign the following information needs to be concatenated in a single string (without separators):

Timestamp of the request in seconds.
HTTP method.
URI.
JSON data (if present for POST request).

Example payload:

1624309597463POST/integration/payments{"amount":{"value":"10","currency":"bUSDT"},"expiresAt":"2021-06-22T23:19:38.146071+03:00"}

After applying HMAC-SHA256 to the payload and getting a signature as a byte array, it should be converted into a hex-encoded string.

For the payload above and given API Key/Secret, the signature should be:

ApiSecret = 'DiFy5adj2FbrD5SDWsvPrsM2uVOdAund2ksMCZ9lBrRyDr5WMFO6O0loLL8TD1gh'
Signature = '695e66179483e9f7df31676893fbc5421630c14b16f9c63f3ef484003e82cef5'

This signature, as well as API Key and timestamp, should be placed in the HTTP headers of the request according to the table in the previous section.

You can double-check your calculation using this online tool.

Code examples

Create a payment with signature

// This code must be on your backend side
// Do not send your Secret into Client Browser!

// you special data from smartypay:
const apiPublicKey = 'YBSs200ehQr4KPlyZUaunGaY049yCpsH';
const apiBackendSecret = 'DocmTHXBnPSdXrXKwdB3m4fTFlytV0nY5e3dMCh4LZLQHMxy6ifWDBaLeevMC4Jp';

// data for payment:
const amount = { value:'60', currency: 'btUSDTv2' };
const paymentTTL = 1000 * 60 * 60; // 1 hour
const now = Date.now();
const nowInSec = Math.round(now / 1000).toString();
const expiresAt = new Date(now + paymentTTL).toISOString();
const merchantId = 'RgFw2p65CQn3pE8uriL53d'

const body = JSON.stringify({
  amount,
  expiresAt,
  merchantId
});

const messageToSign = nowInSec + 'POST/v1/payments' + body;
const signature = sha256.hmac(apiBackendSecret, messageToSign);

// create payment request
const resp = await fetch('http://partner-api.smartypay.io/v1/payments', {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'x-api-key': apiPublicKey,
    'x-api-sig': signature,
    'x-api-ts': nowInSec,
  },
  body
});

const payment = await resp.json();

Create a subscription with a signature

// This code must be on your backend side
// Do not send your Secret into Client Browser!

// API Key & Secret
const apiPublicKey = 'YBSs200ehQr4KPlyZUaunGaY049yCpsH';
const apiBackendSecret = 'DocmTHXBnPSdXrXKwdB3m4fTFlytV0nY5e3dMCh4LZLQHMxy6ifWDBaLeevMC4Jp';

// This data is for example, use your own data
planId = 'FlhFQYGcSH2-EtR03avJvw'; // your plan id
asset = 'btUSDTv2';
customerId = '0x4f22d5679aEcb21551112692074877E43A2e771c'; // your customer id
startFrom = '2023-01-13T14:07:11Z';
payer = '0x60957B6C6C0A194422F6370A00806695FE941b83'; // payer address

const now = Date.now();
const nowInSec = Math.round(now / 1000).toString();

const body = JSON.stringify({
    planId,
    asset,
    customerId,
    startFrom,
    payer
});

const messageToSign = nowInSec + 'POST/v1/subscriptions' + body;
const signature = sha256.hmac(apiBackendSecret, messageToSign);

// create subscription request
const resp = await fetch('http://partner-api.smartypay.io/v1/subscriptions', {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'x-api-key': apiPublicKey,
        'x-api-sig': signature,
        'x-api-ts': nowInSec
    },
    body
});

const subscription = await resp.json();

SMARTy Docs