​

Usage in Endpoints

​

Validate Requests

• “Get authToken” to Miniapp backend
• “Complete Order Payment” Webhook to Miniapp backend

​

Signing Requests

“Create Order Payment” to Boxo Platform “Get Order Payment Status” to Boxo Platform

​

Settings Options

​

Algorithms

Choose from three types of algorithms for signing requests and validating them:

• RSA2
• HMAC
• ECDSA

​

Hash Function Used in Signature

Select the hash function used for the signature:

• MD5
• SHA-1
• SHA-224
• SHA-256
• SHA-384
• SHA-512

​

Api Client ID

“Api client ID” is an identifier for a Miniapp’s API

​

Key Format for RSA or ECDSA

For RSA2 and ECDSA, choose between:

• PEM
• DER

​

Boxo public key

“Boxo public key” is used for validating request data on a Hostapp’s side.

​

Hostapp public key

“Hostapp public key” is used for validating request data from a Hostapp. This key belongs to the private key on a Hostapp’s side.

​

HMAC Secret

“HMAC Secret” is used in HMAC algorithm only.

​

Headers Map

“Headers map” is a JSON field used to set up custom headers in case a Hostapp wants to utilize their own request signaturing. These fields should be mapped:

• signature
• timestamp
• nonce
• identity
• client_id
• merchant_id

​

Default

{
  "nonce": "X-Nonce",
  "identity": "X-Identity",
  "client_id": "X-Client-Id",
  "signature": "X-Signature",
  "timestamp": "X-Timestamp",
  "merchant_id": "X-Merchant-Id"
}

​

Signature Payload Template

“Signature payload template” is a string template field used to set up a custom payload format in case a Hostapp wants to utilize their own request signaturing. These fields should be mapped in the template:

• {timestamp}
• {nonce}
• {identity}
• {client_id}
• {merchant_id}
• {request_method} - Example: “POST”, "GET"
• {url}
• {payload} - this is “Request data/body”

​

Signature Template

“Signature template” is a string template field used to set up a custom signature header format in case a Hostapp wants to utilize their own request signaturing. These fields should be mapped in the template:

• {signature}

​

Timespec

“Timespec” is a field used while generating the current timestamp, defining time precision. Example: seconds, milliseconds

​

Identity

“Identity” is an optional static string that can be used in the signature payload and passed with headers to verify data integrity. Don’t forget to add it in “Headers map” and to “Signature payload template” as if used.

​

Nonce

“Nonce” is an optional random string that can be used in the signature payload and passed with headers to verify data integrity. Length is set in “Nonce length”. Enabled via “Use nonce”. Don’t forget to add it in “Headers map” and to “Signature payload template” as if used.

​

Encoding

“Request data encoding for payload” is a field that encodes Request data to “base64” or leaves it as plain text before formatting payload.

“Signature payload encoding” is a field that encodes the payload to “base64” or leaves it as plain text before signing it.

“Signature encoding” is a field that encodes the signature from bytes to “base64” or “hex” after signing payload.

​

Request Data/Body

“Use request data with spaces”

Example: If false {"a": "b"} will become {"a":"b"} in payload, if true {"a":"b"} will become {"a": "b"} in payload

“Sort request data keys”

Example: If true {"b": "1", "a": "2"} will become {"a": "2", "b": "1"} in payload

​

Merchant ID

Merchant ID is an optional identifier unique to a Partnership. It is used to identify a miniapp in a Hostapp’s system. Don’t forget to add it in “Headers map” and to “Signature payload template” as if used. Merchant ID can be also specified in a Partnership settings.

​

Miniapp to provide

Please provide the following information to Boxo, after setup Boxo will provide you with a public key to verify the signature:

​

Miniapp’s settings

• Algorithm (choice) - RSA2, HMAC, ECDSA
• Hash function (choice) - MD5, SHA-1, SHA-224, SHA-256, SHA-384, SHA-512
• Key Format (choice) optional - PEM, DER (For RSA2 and ECDSA only)
• Miniapp public key (string) - Public Key (string) PKCS1 - Private key for a Miniapp to verify the signature
• HMAC Secret (string) optional - Secret for a HMAC algorithm only
• Headers map (JSON) optional - JSON field used to set up custom headers in case a Miniapp wants to utilize their own request signaturing
• Signature payload template (string) optional - String template field used to set up a custom payload format in case a Miniapp wants to utilize their own request signaturing
• Signature template (string) optional - String template field used to set up a custom signature header format in case a Miniapp wants to utilize their own request signaturing
• Timespec (string) - Field used while generating the current timestamp, defining time precision. Example: seconds, milliseconds
• Identity (string) optional - Any identifier for a Miniapp’s identification
• Nonce length (integer) optional - Length of a Nonce string
• Use nonce (boolean) optional - Use Nonce string
• Request data encoding for payload (choice) - base64, plain text
• Signature payload encoding (choice) - base64, plain text
• Signature encoding (choice) - base64, hex
• Use request data with spaces (boolean) optional - Use spaces in request data
• Sort request data keys (boolean) optional - Sort request data keys
• Public Key (string) PKCS1 - Private key for a Boxo Platform to verify the signature
• Client ID (string) - Client ID for a Miniapp’s identification
• Merchant ID (string) optional - Merchant ID for a Miniapp’s identification

​

Code examples

• Hash function - SHA-256
• Key Format - PEM
• Headers map - {"signature": "X-Signature", "timestamp": "X-Timestamp", "client_id": "X-Client-Id"}
• Signature payload template - {timestamp}{client_id}{request_method}{url}{payload}
• Signature template - {signature}
• Timespec - seconds
• Use nonce - false
• Request data encoding for payload - plain text
• Signature payload encoding - plain text
• Signature encoding - base64
• Use request data with spaces - false
• Sort request data keys - false

​

RSA2

def sign_request(
    url, request_method, request_data, client_id, timestamp, 
):
    import rsa

    payload = self._payload_template.format(
        request_method=request_method,
        url=url,
        client_id=client_id,
        timestamp=timestamp,
        payload=request_data,
    )

    signature = rsa.sign(
        payload.encode("utf-8"),
        rsa.PrivateKey.load_pkcs1(self._private_key),
        hash_method,
    )

    return base64.b64encode(signature).decode()

def verify_signature(
    signature, url, request_method, request_data, client_id, timestamp,
):
    import rsa
    from rsa.pkcs1 import VerificationError

    payload = self._payload_template.format(
        request_method=request_method,
        url=url,
        client_id=client_id,
        timestamp=timestamp,
        payload=request_data,
    )

    signature = base64.b64decode(signature)
    try:
        rsa.verify(
            payload.encode("utf-8"),
            signature,
            rsa.PublicKey.load_pkcs1_openssl_pem(self._public_key),
        )
        return True
    except VerificationError:
        return False

​

HMAC

def sign_request(
    url, request_method,  request_data, timestamp
):
    import hmac
    import hashlib

    keyEncoded = secret_key.encode()
    hash_method = hashlib.sha256

    payload = self._payload_template.format(
        request_method=request_method,
        url=url,
        client_id=self._client_id,
        timestamp=timestamp,
        payload=request_data,
    )
    h = hmac.new(keyEncoded, payload.encode(), hash_method)

    generated_signature = base64.b64encode(h.digest()).decode("utf-8")

    return generated_signature

def verify_signature(
    signature, url, request_method, request_data, client_id, secret_key, timestamp
):
    import hmac
    import hashlib
    import base64


    payload = self._payload_template.format(
        request_method=request_method,
        url=url,
        client_id=client_id,
        timestamp=timestamp,
        payload=request_data,
    )

    keyEncoded = self._secret_key.encode()
    hash_method = hashlib.sha256
    h = hmac.new(keyEncoded, payload.encode(), hash_method)

    generated_signature = base64.b64encode(h.digest()).decode("utf-8")

    return hmac.compare_digest(signature, generated_signature)

​

ECDSA

def sign_request(
    url, request_method, request_data, client_id, timestamp, 
):
    import hashlib
    from ecdsa import SigningKey
    from ecdsa.util import sigencode_der

    payload = self._payload_template.format(
        request_method=request_method,
        url=url,
        client_id=client_id,
        timestamp=timestamp,
        payload=request_data,
    )

    sign_key = SigningKey.from_pem(self._private_key)
    signature = sign_key.sign(
        payload.encode(),
        hashfunc=hashlib.sha256,
        sigencode=sigencode_der,
    )

    return base64.b64encode(signature).decode()

def verify_signature(
    signature, url, request_method, request_data, timestamp, client_id
):  
    import hashlib
    from ecdsa import VerifyingKey
    from ecdsa.util import sigdecode_der

    payload = self._payload_template.format(
        request_method=request_method,
        url=url,
        client_id=client_id,
        timestamp=timestamp,
        payload=request_data,
    )

    verifying_key = VerifyingKey.from_pem(self._public_key)
    return verifying_key.verify(
        base64.b64decode(signature),
        payload.encode(),
        hashfunc=hashlib.sha256,
        sigdecode=sigdecode_der,
    )