Partner API ApiPay

Server-to-server документация для партнёров-интеграторов (CRM, платформы, агрегаторы)

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

Все запросы к Partner API — заголовок X-Partner-Key: <ключ>.

Ключ выдаётся командой ApiPay при одобрении заявки. В БД хранится только хеш (sha256) — восстановить невозможно. Сохраните при получении.

Поток онбординга мерчанта

Главный кейс Partner API — партнёр онбордит мерчанта в ApiPay без ручной регистрации. Авторизация основана на Kaspi-SMS: мерчант сообщает партнёру код из SMS.

1. POST /api/partner/organizations — создать организацию мерчанта
2. POST /api/partner/organizations/{id}/kaspi-auth/init — начать авторизацию кассира
3. POST /api/partner/organizations/{id}/kaspi-auth/send-phone — Kaspi шлёт SMS кассиру
4. POST /api/partner/organizations/{id}/kaspi-auth/verify-otp — подтвердить код из SMS
5. POST /api/partner/organizations/{id}/api-key — получить X-API-Key + webhook

Эндпоинты

{
  "name": "CRM key",
  "webhook_url": "https://your-crm.example.com/webhooks/kaspi",
  "webhook_secret": "optional_custom_secret"
}

{
  "success": true,
  "key": "<plaintext, показывается ОДИН РАЗ>",
  "key_id": 200,
  "webhook_url": "https://your-crm.example.com/webhooks/kaspi",
  "webhook_secret": "<plaintext>",
  "is_org_default": true,
  "regenerated": false
}

Формат карточки организации

{
  "id": 50,
  "name": "ТОО Example",
  "idn": "123456789012",
  "status": "pending|verified|suspended",
  "sandbox_mode": false,
  "has_catalog": false,
  "kaspi_connected": true,
  "session_mode": "self",
  "external_id": "crm-client-42",
  "payment_status": "none|active|expired",
  "payment_expires_at": "2026-06-16T00:00:00+00:00",
  "has_active_payment": false,
  "created_at": "2026-05-16T10:00:00+00:00"
}

Примеры кода

Полный поток онбординга (JavaScript)

// 1. Создать организацию мерчанта
const orgRes = await fetch('https://bpapi.bazarbay.site/api/partner/organizations', {
  method: 'POST',
  headers: {
    'X-Partner-Key': 'pk_your_partner_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ external_id: 'crm-client-42' }),
})
const { organization } = await orgRes.json()
const orgId = organization.id

// 2. Инициировать авторизацию кассира
await fetch(`https://bpapi.bazarbay.site/api/partner/organizations/${orgId}/kaspi-auth/init`, {
  method: 'POST',
  headers: { 'X-Partner-Key': 'pk_your_partner_key_here' },
})

// 3. Передать номер кассира — Kaspi пришлёт SMS
await fetch(`https://bpapi.bazarbay.site/api/partner/organizations/${orgId}/kaspi-auth/send-phone`, {
  method: 'POST',
  headers: {
    'X-Partner-Key': 'pk_your_partner_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ cashier_phone: '77001234567' }),
})

// 4. Подтвердить OTP из SMS
const verifyRes = await fetch(`https://bpapi.bazarbay.site/api/partner/organizations/${orgId}/kaspi-auth/verify-otp`, {
  method: 'POST',
  headers: {
    'X-Partner-Key': 'pk_your_partner_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ otp: '1234' }),
})
// { "success": true, "mode": "self", "organization": { "status": "verified", ... } }

// 5. Получить X-API-Key для мерчанта (один раз!)
const keyRes = await fetch(`https://bpapi.bazarbay.site/api/partner/organizations/${orgId}/api-key`, {
  method: 'POST',
  headers: {
    'X-Partner-Key': 'pk_your_partner_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'CRM key',
    webhook_url: 'https://your-crm.example.com/webhooks/kaspi',
  }),
})
const { key, webhook_secret } = await keyRes.json()
// key — сохраните в вашем хранилище, больше не показывается

Создание счёта от имени мерчанта

// После онбординга используйте X-API-Key мерчанта
const invoiceRes = await fetch('https://bpapi.bazarbay.site/api/v1/invoices', {
  method: 'POST',
  headers: {
    'X-API-Key': 'merchant_api_key_obtained_during_onboarding',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 15000,
    phone_number: '87001234567',
    description: 'Оплата заказа #123',
    external_order_id: 'order_123',
  }),
})
const { id, status } = await invoiceRes.json()

Список организаций (cURL)

curl -X GET 'https://bpapi.bazarbay.site/api/partner/organizations?per_page=25&page=1' \
  -H 'X-Partner-Key: pk_your_partner_key_here'

Rate Limits

Коды ошибок

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

{
  "success": false,
  "error": "error_code"
}
// или для ошибок валидации:
{
  "success": false,
  "errors": {
    "field_name": ["описание ошибки"]
  }
}