Справочник API

Базовый URL

https://amypay.ru/api/v2

Все эндпоинты работают только по HTTPS. Запросы по HTTP автоматически перенаправляются на HTTPS. Версия v1 ещё принимается, но помечена как deprecated — рекомендуем сразу использовать v2.

Авторизация

Все эндпоинты (кроме /ping) требуют передачи API-ключа. Поддерживаются две схемы:

Bearer-токен кассы (основной способ)

Authorization: Bearer amypay_live_8f3d...9a2b

Ключ берётся в «Кассы → [название] → Реквизиты API». У каждой кассы свой ключ; действия в API привязаны к кассе, которой принадлежит ключ.

Персональный токен пользователя

X-Api-Token: amypay_user_token_...
merchant_id: 42  // передаётся в body или query

Позволяет одним токеном работать с несколькими кассами одного пользователя. Можно ограничить IP-адреса в настройках токена.

Формат ошибок

Все ответы — JSON. Успех:

{ "ok": true, ... }

Ошибка:

{
    "ok": false,
    "error": "unauthorized"
}

Или с детализацией по полям (HTTP 422):

{
    "ok": false,
    "errors": {
        "amount": ["Минимум 0.01"]
    }
}

Ограничение частоты запросов

Базовый лимит: 60 запросов в минуту на один API-ключ. При превышении возвращается 429 Too Many Requests с заголовком Retry-After, указывающим сколько секунд подождать. Если вам нужен увеличенный лимит — напишите на support@amypay.ru.

GET /ping

Проверка доступности. Авторизация не требуется.

curl https://amypay.ru/api/v2/ping

{
    "ok": true,
    "service": "Amypay",
    "version": "v2",
    "time": 1745251200
}

POST /orders — создать заказ

Параметры

Пример

curl -X POST https://amypay.ru/api/v2/orders \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "amount": 1490.00,
        "external_order_id": "ORDER-123",
        "description": "Подписка Pro",
        "payer_email": "user@example.com",
        "metadata": { "plan": "pro" }
    }'

Ответ 201 Created:

{
    "ok": true,
    "order": {
        "number": "AMY-20260421-000123",
        "amount": 1490.00,
        "currency": "RUB",
        "status": "pending",
        "external_order_id": "ORDER-123",
        "pay_url": "https://amypay.ru/pay?t=eyJhbGciOi...",
        "pay_token": "eyJhbGciOi...",
        "created_at": 1745251200
    }
}

GET /orders/{number} — получить заказ

curl https://amypay.ru/api/v2/orders/AMY-20260421-000123 \
    -H "Authorization: Bearer $API_KEY"

{
    "ok": true,
    "order": {
        "number": "AMY-20260421-000123",
        "external_order_id": "ORDER-123",
        "description": "Подписка Pro",
        "amount": "1490.00",
        "amount_rub": "1490.00",
        "currency": "RUB",
        "pay_currency": "RUB",
        "pay_amount": "1490.00",
        "pay_address": "79001234567",
        "amount_credited": "1475.10",
        "fee_merchant": "14.90",
        "fee_client": "0.00",
        "status": "paid",
        "payer_email": "user@example.com",
        "metadata": "{\"plan\":\"pro\"}",
        "created_at": 1745251200,
        "paid_at":    1745251500
    }
}

GET /orders — список заказов

Параметр page — номер страницы (1 по умолчанию). Размер страницы фиксирован (50 записей).

curl "https://amypay.ru/api/v2/orders?page=2" \
    -H "Authorization: Bearer $API_KEY"

{
    "ok": true,
    "items": [ { "number": "AMY-...", "status": "paid", ... }, ... ],
    "total": 317
}

GET /wallets — балансы пользователя

curl https://amypay.ru/api/v2/wallets \
    -H "Authorization: Bearer $API_KEY"

{
    "ok": true,
    "wallets": [
        { "currency": "RUB",  "balance": "12450.75", "balance_hold": "0.00" },
        { "currency": "USDT", "balance": "138.52",   "balance_hold": "0.00" },
        { "currency": "BTC",  "balance": "0.00452",  "balance_hold": "0.00" }
    ]
}

balance_hold — сумма, временно заморожена (например, под оформленную, но ещё не одобренную заявку на вывод).

Вебхуки

Вебхуки отправляются на notify_url кассы методом POST с телом application/x-www-form-urlencoded.

Поля

Подпись

sign = sha256( api_key + ":" + order_number + ":" + amount + ":" + secret_word_2 )

Пример проверки (PHP)

$expected = hash('sha256', implode(':', [
    $apiKey,
    $_POST['order_number'],
    $_POST['amount'],
    $secretWord2,
]));
if (!hash_equals($expected, $_POST['sign'] ?? '')) {
    http_response_code(400);
    exit('bad sign');
}
// безопасно обновляем заказ в БД, отвечаем 200 OK
echo 'OK';

Ретраи

Если ваш сервер вернул не 2xx или таймаут (>10 сек), Amypay повторит попытку по расписанию: 30 сек → 2 мин → 10 мин → 30 мин → 2 часа (всего 5 попыток). Перезапуск ретраев из админки — «Заказы → [номер] → Повторить вебхук».

Статусы заказа

OpenAPI спецификация

Машиночитаемое описание API в формате OpenAPI 3: /api/openapi.json. Можно открыть в Swagger Editor или использовать для генерации клиентов.