Merchant API

Швидкий старт

1. Зареєструйтесь на /register/ — збережіть api_key і api_secret.
2. Створіть платіж: POST /api/v1/payments/create з заголовком Authorization: Bearer <api_key>.
3. Перенаправте покупця на checkout_url з відповіді або вбудуйте widget.
4. Налаштуйте webhook у кабінеті — події з HMAC-SHA256 у X-Signature.

Автентифікація

Merchant API (server-to-server)

Authorization: Bearer pk_live_xxxxxxxx

API-ключі видаються при реєстрації (POST /api/v1/auth/register) або через адмін-панель.

Кабінет (браузер)

POST /api/v1/auth/login
Content-Type: application/json

{"email": "merchant@example.com", "password": "your-password"}

Відповідь містить access_token (JWT). Merchant-ендпоінти приймають або API key, або JWT.

Створення платежу

POST /api/v1/payments/create — вкажіть рівно одне з amount_usdt або amount_fiat.

{
  "amount_usdt": 100,
  "currency": "UAH",
  "buyer_wallet": "TYourTronAddress...",
  "network": "TRC20",
  "merchant_order_id": "ORDER-42",
  "callback_url": "https://shop.example/webhook"
}

Підтримувані мережі: TRC20, BEP20, ERC20. Валюти fiat: UAH, USD, EUR.

Статус платежу

Webhooks

Платформа надсилає POST на callback_url при зміні статусу. Підпис — HMAC-SHA256 у заголовку X-Signature.

Секрет = api_secret мерчанта. Підпис обчислюється від timestamp + "." + raw_body.

Події: payment.completed, payment.cancelled, payment.disputed.

Приклад перевірки (Python)

import hmac, hashlib

def verify(secret: str, timestamp: str, body: bytes, signature: str) -> bool:
    payload = f"{timestamp}.{body.decode()}"
    expected = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Ідемпотентність

Передайте заголовок Idempotency-Key: <unique> на POST /api/v1/payments/create, щоб безпечно повторювати запит при мережевих збоях.

Комісії

Покупець платить премію +9% до ринкового курсу USDT:

• 7% — винагорода P2P-провайдера
• 2% — комісія платформи

Точну суму fiat покупець бачить на екрані checkout перед оплатою.

Валюти та мережі

Приклади коду

cURL — створити платіж

curl -X POST "$BASE_URL/api/v1/payments/create" \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-42-v1" \
  -d '{
    "amount_usdt": 50,
    "currency": "UAH",
    "buyer_wallet": "TYourTronAddress...",
    "network": "TRC20",
    "merchant_order_id": "ORDER-42"
  }'

Python

import requests

BASE = "https://graypay.pro"
headers = {"Authorization": "Bearer pk_live_...", "Content-Type": "application/json"}

r = requests.post(f"{BASE}/api/v1/payments/create", headers=headers, json={
    "amount_usdt": 50,
    "currency": "UAH",
    "buyer_wallet": "TYourTronAddress...",
    "network": "TRC20",
    "merchant_order_id": "ORDER-42",
})
r.raise_for_status()
payment = r.json()
print(payment["payment_id"], payment["checkout_url"])

Node.js

const BASE = "https://graypay.pro";

const res = await fetch(`${BASE}/api/v1/payments/create`, {
  method: "POST",
  headers: {
    Authorization: "Bearer pk_live_...",
    "Content-Type": "application/json",
    "Idempotency-Key": "order-42-v1",
  },
  body: JSON.stringify({
    amount_usdt: 50,
    currency: "UAH",
    buyer_wallet: "TYourTronAddress...",
    network: "TRC20",
    merchant_order_id: "ORDER-42",
  }),
});
if (!res.ok) throw new Error(await res.text());
const payment = await res.json();
console.log(payment.payment_id, payment.checkout_url);

Помилки

{"detail": "Human-readable message", "code": "error_code"}

HTTP: 400 — валідація, 401 — автентифікація, 403 — заборона, 429 — rate limit, 503 — немає P2P-провайдерів.