Authorisation

Authorisation

All Pay.io API requests must be authenticated with three headers:

Header	Description
X-API-Key	Your unique merchant API key from Merchant Console.
X-API-Nonce	Unique identifier (UUID) per request.
X-API-Signature	RSA-SHA256 signature generated using your private key.

---

Creating a Public and Private Key

Merchants must provide Pay.io with a public key during onboarding.

Requirements:

• At least 2048 bits

• PEM format

You can use the following code sample to generate the public key and private key.

from cryptography.hazmat.primitives.asymmetric import rsa
from cryptography.hazmat.primitives import serialization

# Generate 2048-bit private key
private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)

# Serialize keys to PEM
pem_private = private_key.private_bytes(
    encoding=serialization.Encoding.PEM,
    format=serialization.PrivateFormat.TraditionalOpenSSL,
    encryption_algorithm=serialization.NoEncryption()
)

pem_public = private_key.public_key().public_bytes(
    encoding=serialization.Encoding.PEM,
    format=serialization.PublicFormat.SubjectPublicKeyInfo
)

---

Creating a Merchant Signature

Every API request must be signed with your merchant's RSA private key. Pay.io verifies the signature using the public key you provided during onboarding. This is an asymmetric scheme — there is no shared secret.

Steps:

1

Generate a nonce - a secure random string of at least 16 characters. A UUID4 works well.

2

Normalize the body - strip all whitespace from the request body before signing. The server silently normalizes the body the same way, so signing pretty-printed JSON without stripping whitespace will fail signature verification.

3

Build the canonical string using the rule below (no delimiters): METHOD + PATH + NONCE + QUERY + BODY

4

Sign the canonical string with your merchant's private key using RSA-SHA256 (PKCS#1 v1.5).

5

Base64-encode the signature (standard Base64, not URL-safe).

6

Send the request with all three headers: X-API-Key, X-API-Nonce, and X-API-Signature.

Example in Python:

import uuid
import re
import base64
import json
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding


def generate_auth_headers(method, path, query_string, body, api_key, private_key_pem):
    # Load the merchant's RSA private key from PEM
    private_key = serialization.load_pem_private_key(
        private_key_pem.encode("utf-8") if isinstance(private_key_pem, str) else private_key_pem,
        password=None,
    )

    # Generate a unique nonce per request (UUID4, >= 16 chars)
    nonce = str(uuid.uuid4())

    # Strip all whitespace from the body to match server-side normalization
    normalized_body = re.sub(r"\s", "", body or "")

    # Build the canonical signing string: METHOD + PATH + NONCE + QUERY + BODY
    signing_data = f"{method.upper()}{path}{nonce}{query_string or ''}{normalized_body}"

    # Sign with RSA-SHA256 (PKCS#1 v1.5)
    signature = private_key.sign(
        signing_data.encode("utf-8"),
        padding.PKCS1v15(),
        hashes.SHA256(),
    )

    # Base64-encode the signature (standard, not URL-safe)
    signature_b64 = base64.b64encode(signature).decode("ascii")

    # Return the three required headers
    return {
        "X-API-Key": api_key,
        "X-API-Nonce": nonce,
        "X-API-Signature": signature_b64,
    }


# Example usage
headers = generate_auth_headers(
    method="POST",
    path="/v1/user/withdraw",
    query_string="",
    body=json.dumps({
        "amount": "100.50",
        "currency_id": "c872e749-...",
        "user_reference_id": "hub_player_2",
    }),
    api_key="YOUR_API_KEY",
    private_key_pem=open("merchant_private_key.pem", "rb").read(),
)

---

Example Authenticated Request

curl --location 'https://gateway.stage.pay.io/v1/user/withdraw' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'X-API-Nonce: 123e4567-e89b-12d3-a456-426614174000' \
--header 'X-API-Signature: BASE64_SIGNATURE' \
--data '{
"amount":"100.50",
"currency_id":"c872e749-fd56-533e-b01f-de87ae38e7f1",
"wallet_address":"0x123...",
"user_reference_id":"hub_player_2"
}'

---

Error Codes

missing signature — Status 401

{ "message": "missing signature" }

missing api key — Status 401

{ "message": "missing api key" }

invalid api key — Status 401

{ "message": "invalid api key" }

nonce too short — Status 400

{ "message": "nonce too short" }

nonce already used — Status 401

{ "message": "invalid request signature" }

invalid nonce — Status 400

{ "message": "invalid nonce" }

missing nonce — Status 401

{ "message": "missing nonce" }

timestamp expired — Status 401

{ "message": "timestamp expired" }

multiple nonces — Status 401

{ "message": "multiple nonces" }