Документация Merchant API

Обзор

Merchant API позволяет:

• Создавать заявки на входящие платежи и получать реквизиты для оплаты
• Создавать заявки на исходящие выплаты
• Получать callback при смене статуса операции
• Управлять API-ключами и IP whitelist
• Подавать апелляции по спорным pay-in транзакциям

Базовый URL

Все эндпоинты payments API:

https://api.avapay.net/api/v1/payments/

Ключи, валюты и платёжные системы доступны в личном кабинете мерчанта (раздел API Keys).

Аутентификация

Каждый запрос к API должен содержать заголовок:

Authorization: Token <ваш_api_token>

Подпись запросов

Для всех POST-запросов с телом (pay-in, pay-out, whitelist) обязателен заголовок Signature.

Алгоритм

1. Сериализуйте JSON-тело запроса с сортировкой ключей, без пробелов
2. Добавьте к строке ваш private_key (как текст)
3. Вычислите SHA-256 hex-дайджест

Signature = SHA256( JSON_sorted(body) + private_key )

Пример (Python)

import hashlib
import json

PRIVATE_KEY = "00000000-0000-4000-8000-000000000001"  # пример, не боевой ключ

request_data = {
    "amount": "2000.00",
    "currency": "KZT",
    "payment_system": "C2CKZT",
    "merchant_order_id": "order-demo-10001",
    "callback_url": "https://merchant.example.com/callbacks/avapay",
    "ftd": False,
    "client": {
        "client_id": "user-demo-42",
        "email": "client@example.com",
        "phone": "+77000000000",
        "name": "Demo Client"
    }
}

sorted_json = json.dumps(request_data, sort_keys=True, separators=(",", ":"))
signature = hashlib.sha256((sorted_json + PRIVATE_KEY).encode()).hexdigest()

headers = {
    "Authorization": "Token 0000000000000000000000000000000000000000",
    "Content-Type": "application/json",
    "Signature": signature,
}

Callback-уведомления

При смене статуса pay-in / pay-out AvaPay отправляет POST на callback_url, указанный при создании заявки.

Тело callback (пример)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "order_id": "order-demo-10001",
  "amount": 2000.0,
  "currency": "KZT",
  "payment_system": "C2CKZT",
  "status": "Success",
  "recalculated": false,
  "timestamp": 1718123456
}

Заголовок

Signature: <sha256 подпись тела callback + private_key>

Алгоритм тот же, что для исходящих запросов. Всегда проверяйте подпись на своей стороне.

API Keys — создание

POST /api/v1/payments/keys/

Создаёт новую активную пару ключей. Предыдущие активные ключи деактивируются.

Тело запроса: пустое {}

Ответ 201

{
  "id": "9e3e624c-175c-496a-a7e7-e408ed671163",
  "token": "0000000000000000000000000000000000000000",
  "private_key": "00000000-0000-4000-8000-000000000001",
  "created_at": "2026-06-01T12:00:00Z",
  "whitelist_on": false,
  "whitelist_ips": []
}

API Keys — IP whitelist

POST /api/v1/payments/keys/{id}/whitelist/

{
  "whitelist_on": true,
  "whitelist": ["203.0.113.10", "203.0.113.11"]
}

Рекомендуется включать whitelist в production.

Pay-in — H2H

POST /api/v1/payments/in/h2h/

Создание заявки с немедленной выдачей реквизитов в поле payment_details.

Тело запроса

{
  "amount": "3000.00",
  "currency": "KZT",
  "payment_system": "C2CKZT",
  "merchant_order_id": "order-demo-10002",
  "callback_url": "https://merchant.example.com/callbacks/avapay",
  "success_url": "https://merchant.example.com/payment/success",
  "failed_url": "https://merchant.example.com/payment/failed",
  "ftd": false,
  "client": {
    "client_id": "user-demo-42",
    "email": "client@example.com",
    "phone": "+77000000000",
    "name": "Demo Client"
  }
}

Объект client

Ответ 201 (успех)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "currency": "KZT",
  "amount": "3000.00",
  "payment_system": "C2CKZT",
  "status": "New",
  "merchant_order_id": "order-demo-10002",
  "callback_url": "https://merchant.example.com/callbacks/avapay",
  "payment_details": {
    "card_number": "4000000000000001",
    "owner": "Иванов И. И.",
    "bank": "Example Bank"
  },
  "expires_at": 1718127056,
  "recalculated": false,
  "usd_amount": 5.77
}

Формат payment_details зависит от payment_system:

• Sber, C2C, C2CKZT — card_number, owner, bank
• SBP, SberPay — phone, owner, bank
• SberDep — deposit_number, bic, owner

Pay-in — Invoice (редирект)

POST /api/v1/payments/in/invoice/

Те же поля, что у H2H. В ответе дополнительно возвращается redirect_url — ссылка на платёжную страницу.

Начальный статус: In Progress

Статусы pay-in

Поле expires_at — Unix timestamp, до которого действительны реквизиты.

Дополнительные действия pay-in

Получить заявку

GET /api/v1/payments/in/h2h/{id}/

Отметить «деньги отправлены»

POST /api/v1/payments/in/h2h/{id}/sent/

Отмена заявки

POST /api/v1/payments/in/h2h/{id}/cancel/

Апелляция

POST /api/v1/payments/in/h2h/{id}/arbitrage/

Формат: multipart/form-data, поле file — PNG, JPEG или PDF (до 5 MB).

Используйте, если клиент утверждает, что оплатил, а статус не перешёл в Success.

Pay-out — H2H

POST /api/v1/payments/out/h2h/

{
  "amount": "5000.00",
  "currency": "RUB",
  "payment_system": "Sber",
  "merchant_order_id": "payout-demo-20001",
  "callback_url": "https://merchant.example.com/callbacks/avapay-payout",
  "ftd": false,
  "client": {
    "client_id": "user-demo-42",
    "email": "client@example.com",
    "phone": "+79000000000",
    "name": "Demo Client"
  },
  "details": {
    "card_number": "4000000000000002"
  }
}

Поле details обязательно. Набор полей зависит от payment_system — см. required_fields в справочнике.

Справочник валют

GET /api/v1/payments/currencies/

Возвращает валюты, доступные вашему мерчанту.

[
  { "symbol": "KZT" },
  { "symbol": "RUB" }
]

Справочник платёжных систем

GET /api/v1/payments/payment-systems/

[
  {
    "name": "C2CKZT",
    "currency": "KZT",
    "required_fields": {
      "card_number": {
        "regex": "^\\d{16}$",
        "pattern": "16 digits"
      }
    }
  }
]

Типичные ошибки

Безопасность

• Храните private_key только на backend
• Используйте HTTPS для callback URL
• Включите IP whitelist в production
• Проверяйте подпись каждого callback
• Не логируйте полные реквизиты карт в открытом виде
• Ротируйте ключи при компрометации: создайте новую пару в кабинете

Чеклист запуска

1. Получите доступ в личный кабинет AvaPay
2. Создайте API Keys, сохраните token и private_key
3. Реализуйте подпись исходящих POST-запросов
4. Реализуйте приём и проверку callback
5. Проверьте доступные payment_system и лимиты для вашего аккаунта
6. Проведите тестовые заявки на минимальных суммах
7. Включите IP whitelist перед production

Техническая поддержка: обращайтесь к вашему менеджеру AvaPay.