Developer documentation

Create an invoice from your server, send the customer to checkout_url, and fulfil the order when you receive a verified invoice.completed webhook.

1. Credentials

After approval, open Stores & API keys in your dashboard and create a store. You get an API key, an API secret and a webhook secret (shown once).

2. Authenticate requests

Send these headers: X-Api-Key, X-Timestamp (unix seconds, max 5 min skew), X-Nonce (random 16-64 chars, single use), X-Signature.

signature = hex( HMAC_SHA256( api_secret, timestamp + "\n" + nonce + "\n" + METHOD + "\n" + path + "\n" + sha256hex(body) ) )

path is the URL path only, e.g. /api/v1/invoices. For GET requests the body is empty. Add Idempotency-Key to make a retry return the same invoice.

3. Create an invoice

POST https://pay.smartalgofx.com/api/v1/invoices
{ "amount": "50.00", "currency": "USD", "description": "Order #1234",
  "order_id": "1234", "country": "BD", "customer_email": "buyer@example.com",
  "return_url": "https://yourshop.com/thanks", "metadata": {"cart": "abc"} }

Response: invoice_id, status, checkout_url. return_url host must be in your store's allowed hosts.

4. Other endpoints

GET /api/v1/invoices/{invoice_id}
GET /api/v1/methods?country=BD&currency=USD&amount=50

5. Webhooks

We POST JSON to your store's webhook URL. Verify before trusting:

X-Gateway-Timestamp: 1700000000
X-Gateway-Signature: hex( HMAC_SHA256( webhook_secret, timestamp + "." + raw_body ) )
X-Gateway-Event-Id: evt_...

Reject requests older than 5 minutes or with a bad signature. Respond with any 2xx to acknowledge; otherwise we retry (1m, 5m, 15m, 1h, 3h, 6h, 12h, 24h). Handle duplicates by event id. Events: invoice.completed, invoice.underpaid, invoice.manual_review, invoice.expired, invoice.failed, invoice.cancelled. Only invoice.completed means paid.

6. Invoice statuses

CREATED, WAITING_FOR_PAYMENT, PAYMENT_DETECTED, VERIFYING, CONFIRMED, COMPLETED, UNDERPAID, EXPIRED, MANUAL_REVIEW, FAILED, CANCELLED.

PHP example

$body = json_encode($payload); $ts = (string)time(); $nonce = bin2hex(random_bytes(12));
$sig = hash_hmac("sha256", "$ts\n$nonce\nPOST\n/api/v1/invoices\n" . hash("sha256", $body), $apiSecret);
// send with headers X-Api-Key, X-Timestamp, X-Nonce, X-Signature, Content-Type: application/json

WooCommerce

A ready-made WooCommerce gateway plugin is available - ask support.