🔓Authentication

Overview

In order to interact with Smarty Pay, some of your requests must be authenticated. We use API keys (and secrets) to authenticate requests.

You can view and manage your API keys in the Backoffice UI.

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

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

Signing requests

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):

  1. Timestamp of the request in seconds.

  2. HTTP method.

  3. URI.

  4. JSON data (if present for POST request).

Example payload:

1624309597463POST/integration/invoices{
    "amount": "11 btBUSD",
    "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 invoice 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 invoice:
const amount = '60 btBUSD';
const invoiceLiveTime = 1000 * 60 * 60; // 1 hour
const now = Date.now();
const nowInSec = Math.round(now / 1000).toString();
const expiresAt = new Date(now + invoiceLiveTime).toISOString();

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

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

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

const respData = await resp.json();
const invoiceId = respData.invoice.id;

// params to open invoice
const params = new URLSearchParams();
params.set('invoice-id', invoiceId);

// additional params:
// params.set('name', 'Item Name to Buy');
// params.set('success-url', 'https://...');
// params.set('fail-url', 'https://...');

// final url be like "https://checkout.smartypay.io/invoice?invoice-id=XXXXXXX"
const urlToRedirect = 'https://checkout.smartypay.io/invoice?' + params.toString();

Create subscription 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 subscription address:
// This data is for example, use your data
planId = 'FlhFQYGcSH2-EtR03avJvw'; // your plan id
asset = 'btBUSD';
customerId = '667317'; // your company 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/integration/subscriptions' + body;
const signature = sha256.hmac(apiBackendSecret, messageToSign);

// create subscription request
const resp = await fetch('http://api.smartypay.io/integration/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 respData = await resp.json();
const contractAddress = respData.contractAddress;

Last updated