API Reference

URL signing

Protecting your sensitive data

A signed URL helps limit access from unauthorized third parties by providing limited permissions and time to make a request. If your widget URL contains sensitive information, we strongly recommend using the signature parameter. it must be appended at the end of the URL.

How to sign URLs

When using the SDK, you'll need to

  • Generate a key pair using the Elliptic Curve algorithm (EC).
  • Configure the newly generated public key in the BlockATM console.
  • Send your widget URL to your backend.
  • Sign the URL with the private key generated in the first step.
  • Return the signature and update the URL params with it.
  • Show the widget.

🚧

Attention

Please securely and safely store your private key and refrain from disclosing it to anyone, including BlockATM staff. BlockATM will verify your requests using your public key, so there is no need for them to know your private key.

How to generate signatures

Generate an ECDSA signature using the SHA-256 hash function.Use your private key as the key, and use the original query string as the message.

All query parameter values (not the entire query string) need to be URL encoded before generating the signature in order for it to be valid.

const crypto = require('crypto');

const originalUrl = 'https://cashier.blockatm.net/?apiKey=your_api_key&custNo=C001&lang=zh-HK&amount=1000&currency=USDT';

const privateKey = `-----BEGIN PRIVATE KEY-----
your private key
-----END PRIVATE KEY-----`;

const urlObject = new URL(originalUrl);
const queryParams = urlObject.searchParams.toString();

const sign = crypto.createSign('sha256');
sign.update(queryParams);

const signature = sign.sign(privateKey, 'base64');

const urlWithSignature = `${originalUrl}&signature=${encodeURIComponent(signature)}`;
console.log(urlWithSignature);

📘

You can leverage an open-source demo from GitHub to help you with the implementation.