Authentication

The Project API allows your backend server to create payment orders, check their status, and perform withdrawals programmatically. All requests are authenticated with a key/secret pair and an HMAC request signature.

Getting API Keys

1. Log in to CryptumPay Console
2. Open your project
3. Navigate to Integration & API
4. Click Get API Keys
5. Optionally add IP addresses to the whitelist — required if you plan to use withdrawal endpoints (see IP Whitelist below)

Keep your secret safe

The API secret is shown only once at generation. Store it securely (e.g. in environment variables). Never commit it to version control.

HTTPS Requirement

Your project domains must be configured with valid HTTPS. Requests originating from HTTP-only domains will be rejected with error 3002. This applies both to your site domain registered in the console and to the webhook endpoint URL.

Required Headers

Every request to the API must include the following headers:

Header	Description
x-api-key	Your API key
x-signature	HMAC signature of the request (see algorithm below)
x-timestamp	Current Unix timestamp in milliseconds (e.g. Date.now())
Content-Type	Must be application/json

Signing Algorithm

The server verifies every request by recomputing the signature from the request content. Requests older than 1 minute are automatically rejected regardless of signature validity.

Step-by-step (language-independent)

1. Serialize the body
   For POST requests: body = JSON.stringify(params)
   For GET requests: body = "{}"

2. Hash the body
   bodyHash = hex(SHA-256(body))

3. Normalize the path

   • Add / at the start if not present
   • Remove trailing / if present
     Example: orders/ → /orders

4. Build the prehash string

   prehash = bodyHash + "|" + METHOD + "|" + path + "|" + timestamp + "|" + apiKey

   Where METHOD is the HTTP method in uppercase (GET, POST, etc.)

5. Compute the signature
   signature = hex(HMAC-SHA256(prehash, secret))

6. Set the headers

   x-api-key: <apiKey>
   x-signature: <signature>
   x-timestamp: <timestamp>

Example: Node.js SDK

The easiest way — use the official SDK, which handles signing automatically:

npm install @cryptumpay/node-sdk

import { CryptumPayClient, CryptumPaySigner } from '@cryptumpay/node-sdk';

const client = new CryptumPayClient(
  new CryptumPaySigner(
    process.env.CRYPTUMPAY_API_KEY,
    process.env.CRYPTUMPAY_API_SECRET
  )
);

// All methods sign requests automatically
const response = await client.createOrder({ ... });

IP Whitelist

Withdrawal endpoints (POST /v1/withdraw and GET /v1/withdraw/:id) additionally verify the IP address of the request.

• If no IP whitelist is configured for the API key, withdrawal requests will be rejected with error 8002
• Configure the whitelist in the console when generating or editing an API key

Response Format

All API responses follow a consistent envelope:

{
  "data": { ... },
  "errorObject": null
}

On error, data is null and errorObject is populated:

{
  "data": null,
  "errorObject": {
    "httpCode": 401,
    "appCode": 7005,
    "message": "Invalid signature"
  }
}

Error Reference

Authentication & Middleware Errors

HTTP	appCode	Description	How to fix
401	7000	One or more required headers (x-api-key, x-signature, x-timestamp) are absent	Add all three headers to the request
401	7001	The API key was not found or is revoked	Check the value of x-api-key
401	7002	Internal authentication error	Contact support
401	7003	The request IP is not in the whitelist	Add the server's IP address in the console
401	7004	The timestamp is more than 1 minute away from the server time	Ensure the server clock is synchronized (NTP)
401	7005	The computed signature does not match	Verify the signing algorithm, especially body serialization and path normalization
403	8002	The API key has no IP whitelist configured; withdrawals are blocked	Add at least one IP address to the whitelist in the console

See Also

• API Endpoints — Available endpoints and request/response formats
• Webhooks & Redirects — Receiving payment notifications