Eleven Pay · Разработчикам

Русский

Қазақша

Русский

Қазақша

Appearance

Быстрый старт ​

Кратчайшая корректная интеграция. Все шаги соответствуют реальному публичному контракту.

Пилотный режим

Eleven Pay доступен в режиме пилота/разработки. Реальная доступность приёма платежей зависит от онбординга вашей организации. Публичный адрес API не определён — используйте базовый адрес, который вам выдали (ELEVENPAY_BASE_URL).

1. Получите API-ключ ​

Создайте ключ в кабинете мерчанта app.eleven.kz → API-ключи. Полное значение ключа показывается один раз — сохраните его на сервере. Формат: ep_<env>_<keyid>_<secret>, где env — live или test. Возможности ключа:

  • путь «платёж»: payment.create и payment.read;
  • путь «счёт Cashier»: cashier.invoice.create и payment.read (ключ окружения live).

2. Настройте серверную аутентификацию и адрес ​

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

Ключ используется только на сервере в заголовке Authorization: Bearer …. Никогда не передавайте его в браузер или мобильное приложение. Подробнее — Аутентификация.

3a. Создайте счёт плательщику (Cashier) ​

Сгенерируйте один Idempotency-Key на одну логическую команду (сохраните его вместе с заказом). amount — строка с двумя знаками после точки и целое число тенге; customer_phone — 10–15 цифр без форматирования.

bash
curl -X POST "$ELEVENPAY_BASE_URL/v1/cashier/invoices" \
  -H "Authorization: Bearer $ELEVENPAY_API_KEY" \
  -H "Idempotency-Key: 3f1b9c1e-0d7a-4a52-9a53-order-1001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "1500.00",
    "currency": "KZT",
    "merchant_order_id": "order_demo_1001",
    "customer_phone": "77001234567"
  }'

Ответ 201 Created (или 200 OK при безопасном повторе): status: "pending", invoice_state: "queued", settled: false. Запрос только ставит счёт в очередь; отправка плательщику происходит в фоне — см. Счета Cashier и Статусы.

3b. Или создайте платёж с действием оплаты ​

bash
curl -X POST "$ELEVENPAY_BASE_URL/v1/payments" \
  -H "Authorization: Bearer $ELEVENPAY_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"
  }'

Ответ (201 Created, или 200 OK при безопасном повторе):

json
{
  "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
}

Сохраните reference — это идентификатор для сверки. Если action не null, покажите его клиенту: qr или redirect (Действия оплаты).

4. Настройте вебхук ​

В кабинете → Вебхуки укажите HTTPS-адрес вашего сервера. При настройке вы получите секретный ключ подписи (показывается один раз). Зарегистрируйте адрес до первого платежа. Eleven Pay отправит событие payment.succeeded, когда платёж завершится успешно.

5. Проверьте подпись и обработайте событие ​

Проверяйте подпись по точным сырым байтам тела запроса до разбора JSON, затем дедуплицируйте по X-ElevenPay-Event-Id, сверьте заказ, сумму и валюту и выполняйте выдачу идемпотентно. См. Проверка подписи и Обработчик вебхуков.

6. Сверяйтесь через GET ​

Вебхуки доставляются не менее одного раза — не полагайтесь на одну доставку как на единственную истину. При любой неопределённости запросите статус:

bash
curl "$ELEVENPAY_BASE_URL/v1/payments/ep1_7t4k2m8q9x3v6b1n5c0d2f4a8h" \
  -H "Authorization: Bearer $ELEVENPAY_API_KEY"

Для счёта: GET /v1/cashier/invoices/{reference}. Подробнее — Сверка.

Дальше ​