Создание платежа

POST /v1/payments создаёт один платёж со статусом pending. Ни один провайдер при этом не вызывается. Запрос идемпотентен — повтор с тем же Idempotency-Key и тем же телом возвращает исходный платёж.

Запрос

Метод и путь: POST {ELEVENPAY_BASE_URL}/v1/payments (базовый адрес вам выдают при подключении — см. Окружения)

Заголовки:

Заголовок	Обязателен	Значение
Authorization	да	Bearer <API_KEY> (возможность payment.create)
Idempotency-Key	да	Ключ одной логической команды создания (см. Идемпотентность)
Content-Type	да	application/json

Тело: дополнительные поля запрещены (лишнее поле → ошибка валидации).

Поле	Тип	Правила
amount	строка	Ровно два знака после точки, например "1500.00". Строка, не число.
currency	строка	"KZT" (по умолчанию KZT).
merchant_order_id	строка	Ваш идентификатор заказа: [A-Za-z0-9_.:-], длина 1–100.

amount — это строка

Отправляйте amount как JSON‑строку ("1500.00"). JSON‑число будет отклонено. Так исключается потеря точности денежной суммы через двоичный float.

Пример: curl

export ELEVEN_PAY_API_KEY="ep_test_<keyid>_<secret>"
export ELEVENPAY_BASE_URL="<базовый адрес, выданный при подключении>"

curl -X POST "$ELEVENPAY_BASE_URL/v1/payments" \
  -H "Authorization: Bearer $ELEVEN_PAY_API_KEY" \
  -H "Idempotency-Key: order_demo_1001_attempt_1" \
  -H "Content-Type: application/json" \
  -d '{"amount":"1500.00","currency":"KZT","merchant_order_id":"order_demo_1001"}'

(Обработка переменных окружения и истории команд зависит от вашей среды — не встраивайте реальный секрет прямо в постоянные примеры.)

Пример: Node.js (сервер)

// Только на сервере. Ключ читается из окружения и никогда не попадает в браузер.
const res = await fetch(`${process.env.ELEVENPAY_BASE_URL}/v1/payments`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ELEVEN_PAY_API_KEY}`,
    "Idempotency-Key": "order_demo_1001_attempt_1",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: "1500.00",
    currency: "KZT",
    merchant_order_id: "order_demo_1001",
  }),
});
if (!res.ok) {
  // Разберите тело ошибки безопасно; при сетевой ошибке повторите с ТЕМ ЖЕ Idempotency-Key.
  throw new Error(`create failed: ${res.status}`);
}
const payment = await res.json();

Пример: Python (стандартная библиотека)

import json
import os
import urllib.request

body = json.dumps(
    {"amount": "1500.00", "currency": "KZT", "merchant_order_id": "order_demo_1001"}
).encode("utf-8")
req = urllib.request.Request(
    os.environ["ELEVENPAY_BASE_URL"] + "/v1/payments",
    data=body,
    method="POST",
    headers={
        "Authorization": f"Bearer {os.environ['ELEVEN_PAY_API_KEY']}",
        "Idempotency-Key": "order_demo_1001_attempt_1",
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(req, timeout=15) as resp:
    payment = json.loads(resp.read())

Ответ

• 201 Created — платёж создан.
• 200 OK — безопасный повтор (тот же Idempotency-Key + то же тело): возвращён исходный платёж.
• Заголовок ответа Idempotency-Replayed: true|false показывает, был ли это повтор.

{
  "reference": "ep1_7t4k2m8q9x3v6b1n5c0d2f4a8h",
  "merchant_order_id": "order_demo_1001",
  "external_account_number": "4821937",
  "status": "pending",
  "amount": "1500.00",
  "currency": "KZT",
  "environment": "test",
  "created_at": "2024-09-05T11:59:30Z",
  "action": null
}

Поля описаны в Объект платежа. Действие оплаты (action) — в Действия оплаты.

Если ответ потерян

Если запрос ушёл, а ответ не получен (таймаут/обрыв), повторите тот же запрос с тем же Idempotency-Key и тем же телом. Eleven Pay вернёт исходный платёж, а не создаст второй. Никогда не генерируйте новый ключ только потому, что не увидели ответ. См. Идемпотентность.

Ошибки

HTTP	code	Причина
400	idempotency_key_required	Нет заголовка Idempotency-Key.
400	idempotency_key_invalid	Ключ содержит недопустимые символы или длину.
401	invalid_api_key	Неверный/неизвестный/отозванный ключ.
403	forbidden	У ключа нет возможности payment.create.
409	idempotency_conflict	Тот же ключ использован для другого логического запроса.
422	payment_amount_invalid	Сумма недопустима.
422	(детали валидации)	Некорректная форма запроса (см. Ошибки).

Полная таблица — на странице Ошибки.