Authentication

All API requests require HMAC-SHA256 authentication via HTTP headers. Get your credentials in the merchant dashboard → Stores.

Required Headers

Signature Example

payload = "1700000000" + "POST" + "/api/v1/payment/create" + '{"amount":"100"}'
signature = HMAC-SHA256(payload, api_secret)

Create Payment

{
  "success": true,
  "data": {
    "payment_id": "a1b2c3d4-...",
    "amount": "100.14",
    "currency": "USDT_TRC20",
    "pay_address": "TXyz...abc",
    "status": "pending",
    "expires_at": "2025-01-15T12:30:00Z",
    "payment_url": "https://soko.ai/pay/a1b2c3d4-..."
  }
}

{
  "success": true,
  "data": {
    "payment_id": null,
    "status": "selecting",
    "amount": 100,
    "currencies": ["USDT_TRC20", "BTC", "ETH"],
    "payment_url": "https://soko.ai/pay/select?token=..."
  }
}

Payment Status

{
  "success": true,
  "data": {
    "payment_id": "a1b2c3d4-...",
    "order_id": "ORDER-123",
    "status": "completed",
    "amount_requested": 100.14,
    "amount_with_cents": 100.14,
    "amount_received": 100.14,
    "currency": "USDT_TRC20",
    "pay_address": "TXyz...abc",
    "tx_hash": "abc123...",
    "confirmations": 21,
    "confirmed_at": "2025-01-15T12:25:00Z",
    "expires_at": "2025-01-15T12:30:00Z",
    "created_at": "2025-01-15T12:00:00Z"
  }
}

List Payments

Merchant Balance

{
  "success": true,
  "data": {
    "USDT_TRC20": {
      "available": 1250.50,
      "pending": 100.00,
      "total_received": 5000.00,
      "total_withdrawn": 3750.00,
      "total_commission": 75.00
    },
    "BTC": {
      "available": 0.05000000,
      "pending": 0.00100000,
      "total_received": 0.10000000,
      "total_withdrawn": 0.04900000,
      "total_commission": 0.00150000
    },
    "ETH": {
      "available": 1.25000000,
      "pending": 0.10000000,
      "total_received": 2.00000000,
      "total_withdrawn": 0.65000000,
      "total_commission": 0.03000000
    }
  }
}

Exchange Rates Public

{
  "success": true,
  "data": {
    "rates": {
      "btc": { "usd": 97500, "eur": 91200, "rub": 8775000 },
      "eth": { "usd": 3200, "eur": 2990, "rub": 288000 },
      "usdt": { "usd": 1.0001, "eur": 0.935, "rub": 90.5 }
    },
    "converted": 55.24
  }
}

Webhooks

When a payment status changes, we send a POST request to your webhook URL with the payment details.

Webhook Headers

Webhook Body

{
  "event": "payment.completed",
  "payment_id": "a1b2c3d4-...",
  "order_id": "ORDER-123",
  "amount": 100.14,
  "amount_received": 100.14,
  "currency": "USDT_TRC20",
  "tx_hash": "abc123...",
  "confirmed_at": "2025-01-15T12:25:00Z",
  "status": "completed",
  "metadata": { "user_id": 42 }
}

Events

Signature Verification (PHP)

$timestamp = $_SERVER['HTTP_X_TIMESTAMP'];
$signature = $_SERVER['HTTP_X_SIGNATURE'];
$body = file_get_contents('php://input');

$expected = hash_hmac('sha256', $timestamp . $body, $webhookSecret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    die('Invalid signature');
}

$payload = json_decode($body, true);
// Process payment...

JavaScript Widget

Embed a payment widget on your website. No backend integration required — just HTML + JS.

Quick Start

<script src="https://soko.ai/widget.js"></script>
<script>
CryptoMerchant.init({ apiKey: 'YOUR_STORE_API_KEY' });

document.getElementById('pay-btn').addEventListener('click', function() {
    CryptoMerchant.pay({
        amount: 100.00,
        order_id: 'ORDER-123',

        // Or use fiat conversion:
        // fiat_amount: 5000,
        // fiat_currency: 'RUB',

        onSuccess: function(payment) {
            alert('Payment confirmed! TX: ' + payment.tx_hash);
        },
        onClose: function() {
            console.log('Widget closed');
        },
        onError: function(err) {
            console.error('Payment error:', err);
        }
    });
});
</script>

<button id="pay-btn">Pay with Crypto</button>

❤️ Donate Widget

Accept crypto donations on any website. No API signatures required — just your Store API key.

How It Works

Enable donations in your Store settings, then add the widget to your website. Visitors can donate using USDT, BTC, or ETH. Each donation creates a tracked payment — you see all donations in your Dashboard under ❤️ Donations.

Quick Start — Button

Adds a "Donate" button where the script is placed:

<script src="https://soko.ai/donate-widget.js"
        data-store-key="YOUR_STORE_API_KEY"></script>

Top Bar

Shows a fixed donation bar at the top of the page:

<script src="https://soko.ai/donate-widget.js"
        data-store-key="YOUR_STORE_API_KEY"
        data-mode="topbar"></script>

Inline

Renders the button inside a specific element:

<div id="crypto-donate"></div>
<script src="https://soko.ai/donate-widget.js"
        data-store-key="YOUR_STORE_API_KEY"
        data-mode="inline"
        data-target="crypto-donate"></script>

Customization Attributes

Direct Donation Page

You can also link directly to the donation page without a widget:

https://soko.ai/donate/YOUR_STORE_API_KEY

API: Create Donation

Error Handling

{
  "success": false,
  "error": "Description of what went wrong"
}

Code Examples

<?php
$apiKey = 'your_api_key';
$apiSecret = 'your_api_secret';

$body = json_encode([
    'amount' => '100.00',
    'order_id' => 'ORDER-' . time(),
]);

$timestamp = (string) time();
$method = 'POST';
$path = '/api/v1/payment/create';

$signature = hash_hmac('sha256', $timestamp . $method . $path . $body, $apiSecret);

$ch = curl_init('https://soko.ai' . $path);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-Api-Key: ' . $apiKey,
        'X-Timestamp: ' . $timestamp,
        'X-Signature: ' . $signature,
    ],
]);

$response = json_decode(curl_exec($ch), true);
echo $response['data']['payment_url'];

import hmac, hashlib, time, json, requests

API_KEY = 'your_api_key'
API_SECRET = 'your_api_secret'
BASE_URL = 'https://soko.ai'

body = json.dumps({
    'amount': '100.00',
    'order_id': f'ORDER-{int(time.time())}'
})

timestamp = str(int(time.time()))
method = 'POST'
path = '/api/v1/payment/create'

payload = f'{timestamp}{method}{path}{body}'
signature = hmac.new(API_SECRET.encode(), payload.encode(), hashlib.sha256).hexdigest()

r = requests.post(f'{BASE_URL}{path}', data=body, headers={
    'Content-Type': 'application/json',
    'X-Api-Key': API_KEY,
    'X-Timestamp': timestamp,
    'X-Signature': signature,
})

print(r.json()['data']['payment_url'])

const crypto = require('crypto');
const https = require('https');

const API_KEY = 'your_api_key';
const API_SECRET = 'your_api_secret';

const body = JSON.stringify({
    amount: '100.00',
    order_id: `ORDER-${Date.now()}`
});

const timestamp = Math.floor(Date.now() / 1000).toString();
const method = 'POST';
const path = '/api/v1/payment/create';

const signature = crypto
    .createHmac('sha256', API_SECRET)
    .update(timestamp + method + path + body)
    .digest('hex');

fetch('https://soko.ai' + path, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-Api-Key': API_KEY,
        'X-Timestamp': timestamp,
        'X-Signature': signature,
    },
    body
})
.then(r => r.json())
.then(data => console.log(data.data.payment_url));

# Generate signature first (bash):
TIMESTAMP=$(date +%s)
BODY='{"amount":"100.00","order_id":"ORDER-1"}'
PAYLOAD="${TIMESTAMP}POST/api/v1/payment/create${BODY}"
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "your_api_secret" | cut -d' ' -f2)

curl -X POST https://soko.ai/api/v1/payment/create \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your_api_key" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -d "$BODY"