API Integration Overview

The Elaypay API is designed for server-to-server communication using HMAC-SHA256 signature authentication. Use it when your backend systems need to interact with Elaypay programmatically -- for example, initiating transfers or querying wallet balances.

Aspect	Detail
Auth method	HMAC-SHA256 Signature
Use case	Server-to-server, backend systems
Credential	API key + secret (long-lived)
Transport	HTTPS
Session	Stateless (per-request signature)

How It Works

Every API request must include four custom headers that together prove the caller possesses a valid API key and knows the corresponding secret. The server verifies these headers before processing the request.

Required Headers

Name	Type	Required	Description
X-Api-Key	string	required	Your API key identifier. Format: sk_live_xxx (production) or sk_test_xxx (sandbox).
X-Signature	string	required	Base64-encoded HMAC-SHA256 signature computed over the canonical message (method, path, timestamp, nonce, body hash).
X-Timestamp	string	required	Unix epoch seconds (UTC) at the time of the request. Must be within 60 seconds of server time.
X-Nonce	string	required	A unique request identifier. UUID v4 recommended. Each nonce can only be used once within the timestamp window.

Quick Example

Here is what an authenticated API request looks like in practice:

curl -X POST "https://api.elaypay.app/api/v1/transfer/command/create" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sk_live_abc123def456" \
  -H "X-Signature: K7gNU3sdo+OL0wNhqoVWhr3g6s1xYv72ol/pe/Unols=" \
  -H "X-Timestamp: 1709337600" \
  -H "X-Nonce: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"sourceWalletId":"w_123","targetWalletId":"w_456","amount":"100.00","currency":"USD"}'

The signature in X-Signature is not a static token -- it is recomputed for every request based on the request method, path, body, timestamp, and nonce. This means that even if a request is intercepted, it cannot be replayed or tampered with.

Authentication Flow at a Glance

┌──────────────┐                              ┌──────────────┐
│  Your Server  │                              │   Elaypay   │
└──────┬───────┘                              └──────┬───────┘
       │                                             │
       │  1. Build canonical message                 │
       │     (method + path + timestamp +            │
       │      nonce + SHA256(body))                  │
       │                                             │
       │  2. Sign with HMAC-SHA256(secret)           │
       │                                             │
       │  3. Send request with 4 auth headers        │
       │ ──────────────────────────────────────────> │
       │                                             │
       │        4. Server validates:                 │
       │           - Key exists & active             │
       │           - Timestamp within 60s            │
       │           - Nonce is unique                 │
       │           - Signature matches               │
       │           - IP allowed (if configured)      │
       │           - Scope permitted                 │
       │                                             │
       │  <── 5. Response (success or error) ─────── │
       └─────────────────────────────────────────────┘

Next Steps

• HMAC Authentication -- Step-by-step guide to computing the signature, with complete code examples in bash and Node.js.
• API Reference & Error Codes -- Error codes, API key management, and technical specifications.
• Error Handling -- Response envelope format and the full error code catalog.
• Pagination -- How to paginate through large result sets.