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

Подключение партнёра к ECPAY Systems для создания заявок и получения статусов. Ниже приведены точные точки входа, обязательные заголовки, поля, а также живые коды валют и банков из вашей базы.

Авторизация

X-Authorization передаётся в заголовке каждого API-запроса. Значение должно совпадать с секретом, который сохранён в настройках API.

Обязательные заголовки

X-Authorization: YOUR_API_SECRET
Content-Type: application/json

Кроме заголовка, в теле каждого запроса передаётся поле apikey — публичный идентификатор обменника. Пара apikey + secret однозначно идентифицирует пользователя в системе.

🔑 Получить API-ключ

API-ключ и секрет для работы с API ecpay видны в вашем личном кабинете в разделе «🔌 API доступ» — если API-доступ активирован администратором для вашего аккаунта.

Откройте свой профиль: /settings.php (или /security.php).
Найдите блок «🔌 API доступ». Если статус «● Активен» — вам доступны API-ключ и секрет.
Нажмите «👁 Показать», чтобы раскрыть полное значение, или «📋 Копировать», чтобы сразу скопировать в буфер обмена.
В этом же блоке готовые curl-примеры с уже подставленными вашими ключами для эндпоинтов «Курсы», «Создание заявки» и «Проверка статуса».
Если статус «○ Выключен» — попросите владельца включить API-доступ в настройках вашего аккаунта (users.php → API).

💡 Что куда подставлять при вызовах:

apikey (в теле JSON) — это публичный API key из блока «🔌 API доступ».
X-Authorization (заголовок) — это API secret из того же блока.

🧪 Тестовая среда

Тестовый режим позволяет проверить интеграцию без списания баланса. URL и контракт API остаются теми же.

Баланс не списывается при создании заявок.
В ответе на создание заявки приходит поле is_test: true.

Включение и отключение тестового режима — только через администрацию.

💰 Получить баланс

Получение баланса по ключу.

Метод	Эндпоинт	Описание
POST / GET	/api/balance.php	Баланс и сводка по заявкам.

Примеры

curl -X POST 'https://ecpay.systems/api/balance.php' \
  -H 'X-Authorization: YOUR_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"apikey":"YOUR_API_KEY"}'

Ответ

{
  "ok": true,
  "exchanger": {
    "id": 12,
    "email": "partner@example.com",
    "name": "Partner Name"
  },
  "balance": {
    "usdt": 12345.67,
    "reserved_usdt": 250.00,
    "available_usdt": 12095.67
  },
  "today": {
    "completed_count": 3,
    "completed_usdt": 480.00,
    "open_count": 2,
    "open_usdt": 250.00
  },
  "ts": 1745000000
}

Поля ответа

Поле	Тип	Описание
`exchanger.id / email / name`	any	Владелец API-ключа = владелец возвращаемого баланса. Используйте, чтобы убедиться в каком именно аккаунте находится баланс.
`balance.usdt`	number	Полный баланс USDT в ecpay для этого аккаунта.
`balance.reserved_usdt`	number	Зарезервировано под активные заявки (статусы new / accepted / in_progress / processing / active / paywait).
`balance.available_usdt`	number	Доступно для новых заявок: `usdt − reserved_usdt`.
`today.completed_count` / `completed_usdt`	int / number	Сколько заявок и на какую сумму закрыто сегодня.
`today.open_count` / `open_usdt`	int / number	Сколько активных заявок прямо сейчас и какой их объём.

💱 Получить курсы

Возвращает список всех валют и банков с актуальными курсами для вашего аккаунта. Это те же курсы, по которым создаются заявки в UI.

Метод	Эндпоинт	Описание
POST / GET	/api/exchange_rates.php	Список валют с банками и курсами.

Примеры

curl -X POST 'https://ecpay.systems/api/exchange_rates.php' \
  -H 'X-Authorization: YOUR_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"apikey":"YOUR_API_KEY"}'

Ответ

{
  "ok": true,
  "exchanger": {
    "id": 12,
    "email": "partner@example.com",
    "name": "Partner Name"
  },
  "currencies": [
    {
      "id": 3, "code": "TRY", "name": "Турецкая лира",
      "banks": [
        {
          "id": 17, "name": "Vakıfbank", "identifier": "vakifbank",
          "rate": 40.6116,
          "rate_mode": "manual",
          "rate_updated_at": "2026-04-30 12:34:56",
          "min_amount": 100, "max_amount": 50000,
          "payout_time_minutes": 30,
          "is_active": 1
        }
      ]
    }
  ],
  "ts": 1745000000
}

Поля ответа

Поле	Тип	Описание
`currencies[].code`	string	Код валюты для использования в `currency_code` при создании заявки.
`banks[].identifier`	string	Идентификатор банка для поля `bank_code` при создании заявки.
`banks[].rate`	number	Актуальный курс. Используйте для расчёта `amount_from`.
`banks[].min_amount` / `max_amount`	number	Лимиты банка (если выставлены).
`banks[].payout_time_minutes`	int	Целевое время выплаты в минутах.
`banks[].rate_updated_at`	datetime	Когда курс был обновлён.
`banks[].is_active`	0/1	Активен ли банк прямо сейчас.

Создание заявки

Метод	Эндпоинт	Описание
POST	/api/exchange_request_create.php	Создаёт новую заявку в системе.

Заявка через API создаётся по той же логике, что и через сайт: курс берётся автоматически из БД для пары currency_code + bank_code, сумма списания amount_from рассчитывается сервером по этому курсу, баланс аккаунта владельца ключа списывается атомарно. Достаточно передать amount_to и направление — серверу всё остальное известно.

Поля запроса

Field	Type	Required	Описание
`apikey`	string	yes	Публичный API-ключ обменника. Связан с балансом, лимитами и доступными валютами.
`currency_code`	string	yes	Код валюты назначения, например `KZT`, `TRY`, `UAH`. Список — в секции «Коды валют» ниже.
`bank_code`	string	yes*	Идентификатор банка из «Кодов банков». Альтернативно `bank_id` (int).
`amount_to`	number	yes	Сумма к выплате клиенту в валюте назначения (например `10000` KZT).
`amount_from`	number	no	Не передавайте — будет рассчитано сервером по актуальному курсу банка. Если передадите, значение проигнорируется и пересчитается.
`from_currency`	string	no	По умолчанию `USDT`.
`requisites`	object	yes**	Объект с реквизитами получателя. Какие поля обязательны — зависит от банка (см. секцию «📝 Реквизиты по банкам»).
`external_request_id`	string	no	Ваш ID заявки. Используется для идемпотентности: повторный запрос с тем же ID вернёт ту же заявку.
`external_token`	string	no	Дополнительный токен заявки.
`callback_url`	string	no	URL для webhook-уведомлений о смене статуса. См. секцию «Callback / Webhook».
`client_name` / `client_contact`	string	no	Имя и контакт клиента (для привязки заявки на стороне партнёра).

* Достаточно одного из bank_code или bank_id. ** Поля requisites зависят от выбранного банка — см. список ниже.

Примеры

curl -X POST 'https://ecpay.systems/api/exchange_request_create.php' \
  -H 'X-Authorization: YOUR_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
  "apikey": "YOUR_API_KEY",
  "currency_code": "KZT",
  "bank_code": "kaspi",
  "amount_to": 100000,
  "external_request_id": "ORD-1001",
  "callback_url": "https://partner.example/callback",
  "requisites": {
    "card": "4400 4302 1234 5678",
    "account_holder": "ИВАНОВ ИВАН"
  }
}'

Успешный ответ (HTTP 200)

{
  "ok": true,
  "created": true,
  "request_id": 123,
  "external_request_id": "ORD-1001",
  "external_token": "...",
  "status": "new",
  "internal_status": "new",
  "is_test": false,

  "min_amount_usdt": 100,
  "amount_to_usdt": 218.34,
  "below_min_fee_applied": false,
  "below_min_fee_percent": 0,
  "below_min_fee_amount": 0
}

amount_from и rate рассчитываются сервером по актуальному курсу банка. Списание баланса = amount_from.
min_amount_usdt — минимум USDT для этого банка. Если amount_to_usdt ≥ него — заявка обычная.

Поведение при сумме ниже минимума

Сервер сравнивает amount_to / rate (= USDT) с банковским min_amount_usdt. Дальше — таблица:

Условие	Поведение	Ответ API
`usdt ≥ min_amount_usdt`	Обычная заявка, без комиссии	HTTP 200, `below_min_fee_applied: false`
`usdt < below_min_floor_usdt` (абсолютный пол)	Отказ — даже с комиссией нельзя	HTTP 422, `{"ok":false,"message":"Сумма ниже абсолютного порога банка: ..."}`
`usdt < min_amount_usdt` и `allow_below_min_request = 0`	Отказ — банк не разрешает below-min	HTTP 422, `{"ok":false,"message":"Сумма ниже минимума банка: ... allow_below_min_request=0"}`
`usdt < min_amount_usdt` и `allow_below_min_request = 1` и `below_min_fee_percent > 0`	Применяется доп.комиссия → `amount_from` увеличивается на %	HTTP 200, `below_min_fee_applied: true`, `below_min_fee_percent: 2.0`, `below_min_fee_amount: 1.234`

Параметры банка (min_amount_usdt, allow_below_min_request, below_min_floor_usdt, below_min_fee_percent) можно проверить заранее через /api/exchange_rates.php — там в каждом банке возвращается min_amount/max_amount.

Ошибочные ответы (HTTP 422)

Сообщение	Когда
`amount_to must be greater than 0`	сумма не передана или ≤ 0
`Валюту не удалось сопоставить: KZT`	код валюты неизвестен
`Банк не найден для currency_id=N`	код банка не привязан к валюте
`Для выбранного банка не задан курс.`	в БД нет `rate_value`
`Сумма ниже абсолютного порога банка: ...`	см. таблицу выше
`Сумма ниже минимума банка: ...`	см. таблицу выше (когда allow_below_min_request=0)
`Обменник не найден.`	API-ключ не привязан к user.role=exchanger
`Недостаточно баланса USDT (...)`	на счёте обменника меньше чем `amount_from`

📝 Реквизиты по банкам

Объект requisites при создании заявки содержит набор полей, обязательность и валидация которых зависят от выбранного банка. Ниже — точная схема для каждого активного банка из вашей системы.

Если поле обязательное и не передано — сервер вернёт {"ok": false, "error": "field name required"}. Опциональные поля можно опустить.

Типы валидации

Тип	Что принимается
`card`	Номер карты — 12–19 цифр (пробелы и дефисы можно, очищаются).
`iban` / `alnum`	Буквы и цифры (без специальных символов).
`email`	Стандартный email (filter_var FILTER_VALIDATE_EMAIL).
`phone`	6–25 символов: цифры, `+`, `-`, пробелы, скобки.
`letters`	Только буквы, пробел и дефис (для ФИО).
`digits`	Только цифры.
`none`	Произвольная строка.

Конкретные банки и валюты

Список ниже формируется автоматически из вашей админки: добавите новую валюту или банк через интерфейс — они сразу появятся здесь со своими полями, валидацией и готовым примером запроса.