ApiPay API v2 Documentation — ApiPay.kz

Полная документация ApiPay REST API v2 — Интернет-эквайринг через Kaspi Pay (Phone Payments)

REST API для приёма платежей по номеру телефона через Kaspi Pay. Без договора с банком, без комиссий. Поддержка каталога, подписок, возвратов и webhooks.

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

1. Войдите в личный кабинет apipay.kz/login через WhatsApp
2. Получите API ключ в Настройки → Подключение
3. Создавайте счета: POST /api/v1/invoices
4. Для работы с реальными платежами — напишите в WhatsApp поддержки, мы подключим ваш Kaspi Business с правами Кассира
5. Настройте webhook в личном кабинете для получения уведомлений об оплате

Базовая конфигурация

Обзор эндпоинтов (23 шт.)

Health Check

GET /status

Проверка доступности API. Не требует аутентификации.

Ответ (200 OK)

{
  "status": "ok",
  "timestamp": "2026-02-12T10:00:00+05:00"
}

Счета (Invoices)

POST /invoices

Создать счёт на оплату. Два режима: без корзины (передать amount) или с корзиной (передать cart_items, сумма рассчитывается автоматически).

Запрос (без корзины)

{
  "amount": 10000,
  "phone_number": "87001234567",
  "description": "Оплата заказа #123",
  "external_order_id": "order_123"
}

Запрос (с корзиной — для организаций с каталогом)

{
  "phone_number": "87001234567",
  "description": "Оплата заказа #123",
  "cart_items": [
    { "catalog_item_id": 1, "count": 2, "price": 4500.00 },
    { "catalog_item_id": 5, "count": 1, "discount": 500 }
  ],
  "discount_percentage": 10
}

Параметры

Поля cart_items

Ответ (201 Created)

{
  "id": 124,
  "amount": "4550.00",
  "status": "pending",
  "subtotal": "5000.00",
  "discount_sum": "450.00",
  "discount_percentage": "10",
  "created_at": "2026-02-12T10:35:00+05:00"
}

GET /invoices

Список счетов с фильтрацией, сортировкой и пагинацией.

Query параметры

Ответ (200 OK)

{
  "current_page": 1,
  "data": [
    {
      "id": 124,
      "user_id": 5,
      "organization_id": 3,
      "api_key_id": 2,
      "amount": "5000.00",
      "phone_number": "87001234567",
      "description": "Оплата заказа #123",
      "external_order_id": "order-123",
      "status": "paid",
      "paid_at": "2026-02-12T10:36:00+05:00",
      "created_at": "2026-02-12T10:35:00+05:00"
    }
  ],
  "total": 100
}

GET /invoices/{id}

Получить счёт по ID.

Ответ

{
  "id": 124,
  "amount": "5000.00",
  "phone_number": "87001234567",
  "description": "Payment for order #123",
  "external_order_id": "order-123",
  "status": "paid",
  "client_name": "Ivan I.",
  "client_comment": null,
  "is_sandbox": false,
  "total_refunded": "0.00",
  "is_fully_refunded": false,
  "kaspi_invoice_id": "13234689513",
  "items": [
    {
      "id": 1,
      "invoice_id": 124,
      "catalog_item_id": 42,
      "name": "Americano",
      "price": "800.00",
      "original_price": "900.00",
      "count": 2,
      "discount": null,
      "unit_id": 1
    },
    {
      "id": 2,
      "invoice_id": 124,
      "catalog_item_id": 43,
      "name": "Latte",
      "price": "1200.50",
      "original_price": null,
      "count": 1,
      "discount": "500.00",
      "unit_id": 1
    }
  ],
  "paid_at": "2026-02-12T10:36:00+05:00",
  "created_at": "2026-02-12T10:35:00+05:00"
}

Поля items

POST /invoices/{id}/cancel

Отменить счёт. Только для статуса pending. Может вернуть 202 Accepted — в этом случае счёт переходит в статус cancelling, используйте GET /invoices/{id} для проверки.

Ответ (200 OK / 202 Accepted)

{
  "message": "Invoice cancelled successfully",
  "invoice": {
    "id": 124,
    "status": "cancelled"
  }
}

POST /invoices/{id}/refund

Создать полный или частичный возврат. Без amount — полный возврат. Для счетов с товарами используйте return_items для возврата конкретных позиций.

Запрос

{
  "amount": 2000.00,
  "reason": "Запрос клиента",
  "return_items": [
    { "catalog_item_id": 1, "count": 1 }
  ]
}

Параметры

Ответ (201 Created)

{
  "message": "Refund created and queued for processing",
  "refund": {
    "id": 456,
    "invoice_id": 124,
    "amount": "2000.00",
    "reason": "Запрос клиента",
    "status": "pending",
    "created_at": "2026-02-12T11:00:00+05:00"
  },
  "invoice": {
    "id": 124,
    "amount": "5000.00",
    "total_refunded": "0.00",
    "available_for_refund": 5000,
    "pending_refund_amount": 2000
  }
}

GET /invoices/{id}/refunds

Список возвратов по конкретному счёту с информацией о счёте.

Ответ (200 OK)

{
  "invoice": {
    "id": 124,
    "amount": "5000.00",
    "total_refunded": "2000.00",
    "available_for_refund": 3000,
    "is_fully_refunded": false
  },
  "refunds": [
    {
      "id": 456,
      "invoice_id": 124,
      "amount": "2000.00",
      "status": "completed",
      "reason": "Запрос клиента",
      "items": null,
      "created_at": "2026-02-12T11:00:00+05:00"
    }
  ],
  "total": 1
}

POST /invoices/status/check

Массовая проверка статусов нескольких счетов за один запрос. Полезно для синхронизации состояния в вашей системе.

Запрос

{
  "invoice_ids": [124, 125, 126]
}

Параметры

Ответ (200 OK)

{
  "message": "Status check jobs dispatched",
  "count": 3
}

Статусы счетов

Каталог (Catalog)

Управление каталогом товаров. Доступно только для организаций с включённым каталогом (has_catalog = true).

GET /catalog/units

Получить список доступных единиц измерения для товаров каталога.

Ответ (200 OK)

{
  "data": [
    { "id": 1, "name": "шт.", "name_kaz": "дн." },
    { "id": 2, "name": "кг", "name_kaz": "кг" },
    { "id": 3, "name": "литр", "name_kaz": "литр" },
    { "id": 4, "name": "метр", "name_kaz": "метр" },
    { "id": 5, "name": "грамм", "name_kaz": "грамм" },
    { "id": 37, "name": "м2", "name_kaz": "м2" },
    { "id": 38, "name": "сутки", "name_kaz": "тәулік" },
    { "id": 43, "name": "упак.", "name_kaz": "жиынтық" },
    { "id": 44, "name": "час", "name_kaz": "сағат" }
  ]
}

Описание полей

GET /catalog

Список товаров каталога с поиском и фильтрацией.

Query параметры

Ответ

{
  "data": [
    {
      "id": 1,
      "kaspi_item_id": 12345,
      "name": "Coffee Latte",
      "unit_id": 1,
      "selling_price": 1800,
      "image_url": "https://cdn.kaspi.kz/image.jpg",
      "barcode": "4870000123456",
      "status": "active",
      "synced_at": "2026-02-12T10:00:00+05:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "total": 50,
    "per_page": 50
  }
}

Описание полей товара

POST /catalog/upload-image

Загрузить изображение для товара. Формат: multipart/form-data. Макс 10 МБ (jpg, png, gif, webp). Изображения оптимизируются (512x512 PNG) и дедуплицируются по MD5.

Ответ

{
  "image_id": "abc12345-def6-7890-ghij-klmnopqrstuv"
}

Используйте image_id при создании или обновлении товара.

POST /catalog

Создать один или несколько товаров (batch, 1-50 штук).

Запрос

{
  "items": [
    {
      "name": "Coffee Latte",
      "selling_price": 1800,
      "unit_id": 1,
      "image_id": "abc12345-def6-7890-ghij-klmnopqrstuv"
    }
  ]
}

Параметры items

Ответ (202 Accepted)

{
  "data": [
    {
      "id": 101,
      "name": "Coffee Latte",
      "selling_price": 1800,
      "unit_id": 1,
      "barcode": null,
      "status": "pending"
    }
  ]
}

PATCH /catalog/{id}

Обновить товар каталога. Все поля опциональны — обновляются только переданные.

Запрос

{
  "name": "Updated Name",
  "selling_price": 2000,
  "unit_id": 1,
  "image_id": "abc12345-def6-7890-ghij-klmnopqrstuv",
  "is_image_deleted": false
}

Параметры

Ответ (200 OK)

{
  "message": "Catalog item update queued",
  "catalog_item_id": 1
}

DELETE /catalog/{id}

Удалить товар каталога.

Ответ

{
  "message": "Catalog item deletion queued",
  "catalog_item_id": 1
}

Подписки (Subscriptions)

Автоматическое создание повторяющихся счетов по расписанию. Поддержка grace period и retry при неоплате.

POST /subscriptions

Создать подписку. Два режима: без корзины (передать amount) или с корзиной (передать cart_items, сумма рассчитывается автоматически). Для организаций с каталогом cart_items обязателен.

Запрос (без корзины)

{
  "phone_number": "87001234567",
  "amount": 5000,
  "billing_period": "monthly",
  "billing_day": 15,
  "description": "Ежемесячная подписка",
  "subscriber_name": "Иван Иванов",
  "external_subscriber_id": "cust-123",
  "started_at": "2026-03-01",
  "max_retry_attempts": 3,
  "retry_interval_hours": 24,
  "grace_period_days": 7,
  "metadata": { "plan": "premium" }
}

Запрос (с корзиной — для организаций с каталогом)

{
  "phone_number": "87001234567",
  "billing_period": "monthly",
  "billing_day": 15,
  "description": "Ежемесячная подписка",
  "subscriber_name": "Иван Иванов",
  "cart_items": [
    { "catalog_item_id": 1, "count": 2 },
    { "catalog_item_id": 5, "count": 1 }
  ]
}

Параметры

Поля cart_items

Ответ (201 Created)

{
  "message": "Subscription created",
  "subscription": {
    "id": 1,
    "subscriber_name": "Иван Иванов",
    "phone_number": "87001234567",
    "amount": "5000.00",
    "cart_items": null,
    "billing_period": "monthly",
    "billing_period_label": "Ежемесячно",
    "billing_day": 15,
    "billing_day_label": "15-го числа",
    "description": "Ежемесячная подписка",
    "external_subscriber_id": "cust-123",
    "status": "active",
    "status_label": "Активна",
    "status_color": "green",
    "started_at": "2026-02-12T00:00:00+05:00",
    "next_billing_at": "2026-03-15T00:00:00+05:00",
    "next_billing_in_days": 31,
    "next_billing_label": "через 31 день",
    "paused_at": null,
    "cancelled_at": null,
    "failed_attempts": 0,
    "max_retry_attempts": 3,
    "retry_interval_hours": 24,
    "grace_period_days": 7,
    "in_grace_period": false,
    "is_sandbox": false,
    "metadata": { "plan": "premium" },
    "created_at": "2026-02-12T12:00:00+05:00",
    "updated_at": "2026-02-12T12:00:00+05:00"
  }
}

GET /subscriptions

Список подписок с фильтрацией и пагинацией.

Query параметры

Ответ (200 OK)

{
  "current_page": 1,
  "data": [
    {
      "id": 1,
      "subscriber_name": "Иван Иванов",
      "phone_number": "87001234567",
      "amount": "5000.00",
      "cart_items": null,
      "billing_period": "monthly",
      "billing_period_label": "Ежемесячно",
      "billing_day": 15,
      "billing_day_label": "15-го числа",
      "description": "Ежемесячная подписка",
      "external_subscriber_id": "cust-123",
      "status": "active",
      "status_label": "Активна",
      "status_color": "green",
      "started_at": "2026-02-01T00:00:00+05:00",
      "next_billing_at": "2026-03-15T00:00:00+05:00",
      "next_billing_in_days": 17,
      "next_billing_label": "через 17 дней",
      "paused_at": null,
      "cancelled_at": null,
      "failed_attempts": 0,
      "max_retry_attempts": 3,
      "retry_interval_hours": 24,
      "grace_period_days": 7,
      "in_grace_period": false,
      "is_sandbox": false,
      "metadata": null,
      "created_at": "2026-02-12T12:00:00+05:00",
      "updated_at": "2026-02-12T12:00:00+05:00"
    }
  ],
  "total": 10
}

GET /subscriptions/{id}

Получить подписку со статистикой и информацией о последнем платеже.

Ответ (200 OK)

{
  "subscription": {
    "id": 1,
    "subscriber_name": "Иван Иванов",
    "phone_number": "87001234567",
    "amount": "5000.00",
    "cart_items": null,
    "billing_period": "monthly",
    "billing_period_label": "Ежемесячно",
    "billing_day": 15,
    "billing_day_label": "15-го числа",
    "description": "Ежемесячная подписка",
    "status": "active",
    "status_label": "Активна",
    "status_color": "green",
    "external_subscriber_id": "cust-123",
    "started_at": "2026-02-01T00:00:00+05:00",
    "next_billing_at": "2026-03-15T00:00:00+05:00",
    "next_billing_in_days": 17,
    "next_billing_label": "через 17 дней",
    "paused_at": null,
    "cancelled_at": null,
    "max_retry_attempts": 3,
    "retry_interval_hours": 24,
    "grace_period_days": 7,
    "failed_attempts": 0,
    "in_grace_period": false,
    "is_sandbox": false,
    "metadata": { "plan": "premium" },
    "stats": {
      "total_payments": 5,
      "successful_payments": 4,
      "failed_payments": 1,
      "total_amount": "20000.00"
    },
    "last_payment": {
      "id": 200,
      "status": "paid",
      "amount": "5000.00",
      "paid_at": "2026-02-15T12:00:00+05:00"
    },
    "created_at": "2026-02-01T12:00:00+05:00",
    "updated_at": "2026-02-15T12:00:00+05:00"
  }
}

Описание полей

PUT /subscriptions/{id}

Обновить подписку. Все поля опциональны — обновляются только переданные. При передаче cart_items сумма пересчитывается автоматически.

Запрос

{
  "amount": 7000,
  "billing_day": 20,
  "description": "Обновлённая подписка",
  "subscriber_name": "Иван Иванов",
  "max_retry_attempts": 5,
  "retry_interval_hours": 12,
  "grace_period_days": 14,
  "metadata": { "plan": "enterprise" }
}

Параметры

Ответ (200 OK)

{
  "message": "Subscription updated",
  "subscription": {
    "id": 1,
    "subscriber_name": "Иван Иванов",
    "phone_number": "87001234567",
    "amount": "7000.00",
    "cart_items": null,
    "billing_period": "monthly",
    "billing_period_label": "Ежемесячно",
    "billing_day": 20,
    "billing_day_label": "20-го числа",
    "description": "Обновлённая подписка",
    "status": "active",
    "status_label": "Активна",
    "status_color": "green",
    "next_billing_at": "2026-03-20T00:00:00+05:00",
    "next_billing_in_days": 22,
    "paused_at": null,
    "cancelled_at": null,
    "failed_attempts": 0,
    "max_retry_attempts": 5,
    "retry_interval_hours": 12,
    "grace_period_days": 14,
    "in_grace_period": false,
    "is_sandbox": false,
    "metadata": { "plan": "enterprise" },
    "created_at": "2026-02-12T12:00:00+05:00",
    "updated_at": "2026-02-26T10:00:00+05:00"
  }
}

POST /subscriptions/{id}/pause

Поставить подписку на паузу. Только для статуса active.

Ответ (200 OK)

{
  "message": "Subscription paused",
  "subscription": {
    "id": 1,
    "subscriber_name": "Иван Иванов",
    "phone_number": "87001234567",
    "amount": "5000.00",
    "billing_period": "monthly",
    "billing_day": 15,
    "status": "paused",
    "status_label": "На паузе",
    "status_color": "orange",
    "next_billing_at": null,
    "paused_at": "2026-02-26T10:00:00+05:00",
    "cancelled_at": null,
    "updated_at": "2026-02-26T10:00:00+05:00"
  }
}

POST /subscriptions/{id}/resume

Возобновить подписку после паузы. Только для статуса paused.

Ответ (200 OK)

{
  "message": "Subscription resumed",
  "subscription": {
    "id": 1,
    "subscriber_name": "Иван Иванов",
    "phone_number": "87001234567",
    "amount": "5000.00",
    "billing_period": "monthly",
    "billing_day": 15,
    "status": "active",
    "status_label": "Активна",
    "status_color": "green",
    "next_billing_at": "2026-03-15T00:00:00+05:00",
    "paused_at": null,
    "cancelled_at": null,
    "updated_at": "2026-02-26T10:00:00+05:00"
  }
}

POST /subscriptions/{id}/cancel

Отменить подписку навсегда. Нельзя восстановить.

Ответ (200 OK)

{
  "message": "Subscription cancelled",
  "subscription": {
    "id": 1,
    "subscriber_name": "Иван Иванов",
    "phone_number": "87001234567",
    "amount": "5000.00",
    "billing_period": "monthly",
    "billing_day": 15,
    "status": "cancelled",
    "status_label": "Отменена",
    "status_color": "red",
    "next_billing_at": null,
    "paused_at": null,
    "cancelled_at": "2026-02-26T10:00:00+05:00",
    "updated_at": "2026-02-26T10:00:00+05:00"
  }
}

GET /subscriptions/{id}/invoices

Список счетов, созданных подпиской.

Query параметры

Ответ (200 OK)

{
  "data": [
    {
      "id": 1,
      "invoice_id": 200,
      "billing_period_start": "2026-02-01",
      "billing_period_end": "2026-02-28",
      "billing_period_label": "01.02.2026 — 28.02.2026",
      "amount": "5000.00",
      "attempt_number": 1,
      "status": "paid",
      "status_label": "Оплачен",
      "status_color": "green",
      "paid_at": "2026-02-15T12:00:00+05:00",
      "failure_reason": null,
      "invoice": {
        "id": 200,
        "kaspi_invoice_id": "13234689513",
        "status": "paid"
      },
      "created_at": "2026-02-15T00:00:00+05:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "total": 5,
    "per_page": 20
  }
}

Статусы подписок

Периоды списания

Grace Period (льготный период)

Если клиент не оплатил счёт и все retry-попытки исчерпаны:

1. Подписка переходит в grace period (in_grace_period: true)
2. Если оплата поступит в течение grace_period_days — подписка продолжает работать
3. Если нет — подписка переходит в статус expired

Возвраты (Refunds)

Полные и частичные возвраты по оплаченным счетам.

GET /refunds

Список всех возвратов с фильтрацией и пагинацией.

Query параметры

Ответ (200 OK)

{
  "current_page": 1,
  "data": [
    {
      "id": 456,
      "invoice_id": 124,
      "amount": "2000.00",
      "reason": "Запрос клиента",
      "status": "completed",
      "created_at": "2026-02-12T11:00:00+05:00"
    }
  ],
  "total": 3
}

Описание полей возврата

Статусы возвратов

Webhooks

События

invoice.status_changed

{
  "event": "invoice.status_changed",
  "invoice": {
    "id": 42,
    "external_order_id": "order_123",
    "amount": "15000.00",
    "subtotal": "16500.00",
    "discount_sum": "1500.00",
    "discount_percentage": "10",
    "status": "paid",
    "description": "Оплата заказа",
    "kaspi_invoice_id": "13234689513",
    "client_name": "Иван Иванов",
    "client_phone": "87071234567",
    "paid_at": "2026-02-12T14:35:00+05:00"
  },
  "source": "My API Key",
  "timestamp": "2026-02-12T14:35:01+05:00"
}

invoice.refunded

{
  "event": "invoice.refunded",
  "refund": {
    "id": 5,
    "amount": "2000.00",
    "status": "completed",
    "reason": "Возврат товара",
    "created_at": "2026-02-12T10:00:00+05:00"
  },
  "invoice": {
    "id": 42,
    "external_order_id": "order_123",
    "amount": "5000.00",
    "subtotal": "5500.00",
    "discount_sum": "500.00",
    "total_refunded": "2000.00",
    "available_for_refund": "3000.00",
    "is_fully_refunded": false,
    "status": "paid",
    "kaspi_invoice_id": "13234689513"
  },
  "source": "My API Key",
  "timestamp": "2026-02-12T10:00:01+05:00"
}

subscription.payment_succeeded

{
  "event": "subscription.payment_succeeded",
  "subscription": {
    "id": 10,
    "external_subscriber_id": "CLIENT-001",
    "phone_number": "87071234567",
    "subscriber_name": "Иван Иванов",
    "amount": "5000.00",
    "billing_period": "monthly",
    "status": "active",
    "next_billing_at": "2026-03-01T00:00:00+05:00",
    "failed_attempts": 0,
    "in_grace_period": false
  },
  "invoice_id": 200,
  "amount": "5000.00",
  "paid_at": "2026-02-01T12:00:00+05:00",
  "source": "My API Key",
  "timestamp": "2026-02-01T12:00:01+05:00"
}

subscription.payment_failed

{
  "event": "subscription.payment_failed",
  "subscription": {
    "id": 10,
    "phone_number": "87071234567",
    "amount": "5000.00",
    "billing_period": "monthly",
    "status": "active",
    "failed_attempts": 2,
    "in_grace_period": false
  },
  "invoice_id": 201,
  "amount": "5000.00",
  "reason": "Invoice expired",
  "attempt_number": 2,
  "source": "My API Key",
  "timestamp": "2026-02-02T12:00:01+05:00"
}

subscription.grace_period_started

{
  "event": "subscription.grace_period_started",
  "subscription": {
    "id": 10,
    "phone_number": "87071234567",
    "amount": "5000.00",
    "status": "active",
    "failed_attempts": 3,
    "in_grace_period": true
  },
  "grace_period_days": 3,
  "expires_at": "2026-02-05T12:00:00+05:00",
  "source": "My API Key",
  "timestamp": "2026-02-02T12:00:01+05:00"
}

subscription.expired

{
  "event": "subscription.expired",
  "subscription": {
    "id": 10,
    "phone_number": "87071234567",
    "amount": "5000.00",
    "status": "expired",
    "next_billing_at": null,
    "failed_attempts": 3,
    "in_grace_period": false
  },
  "source": "My API Key",
  "timestamp": "2026-02-05T12:00:01+05:00"
}

Поле source

Все webhook payload содержат поле source — имя API-ключа, создавшего ресурс (счёт или подписку). Может быть null.

Политика повторов

• Subscription webhooks — повторяются до 3 раз с интервалами 1, 5, 15 минут
• Invoice webhooks — не повторяются
• Ваш сервер должен ответить в течение 10 секунд
• HTTP 2xx = успешно, любой другой код = неудача

Верификация подписи

Заголовок: X-Webhook-Signature: sha256=<HMAC-SHA256>

Node.js

const crypto = require('crypto')

function verifyWebhook(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))
}

PHP

function verifyWebhook($payload, $signature, $secret) {
    $expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);
    return hash_equals($expected, $signature);
}

Python

import hmac, hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Примеры кода

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

JavaScript/Node.js

const response = await fetch('https://bpapi.bazarbay.site/api/v1/invoices', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 10000,
    phone_number: '87001234567',
    description: 'Payment for order #123'
  })
})
const data = await response.json()
console.log('Invoice created:', data.id)

Python

import requests

response = requests.post(
    'https://bpapi.bazarbay.site/api/v1/invoices',
    headers={'X-API-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json'},
    json={'amount': 10000, 'phone_number': '87001234567'}
)
data = response.json()
print(f"Invoice created: {data['id']}")

PHP

$ch = curl_init('https://bpapi.bazarbay.site/api/v1/invoices');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode(['amount' => 10000, 'phone_number' => '87001234567']),
    CURLOPT_RETURNTRANSFER => true
]);
$response = json_decode(curl_exec($ch), true);
echo "Invoice created: " . $response['id'];

cURL

curl -X POST https://bpapi.bazarbay.site/api/v1/invoices \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 10000, "phone_number": "87001234567"}'

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

JavaScript/Node.js

const response = await fetch('https://bpapi.bazarbay.site/api/v1/invoices', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phone_number: '87001234567',
    description: 'Cart order',
    cart_items: [
      { catalog_item_id: 1, count: 2 },
      { catalog_item_id: 5, count: 3 }
    ]
  })
})

Создание подписки

cURL

curl -X POST https://bpapi.bazarbay.site/api/v1/subscriptions \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "87001234567",
    "amount": 5000,
    "billing_period": "monthly",
    "description": "Monthly subscription"
  }'

JavaScript/Node.js

const response = await fetch('https://bpapi.bazarbay.site/api/v1/subscriptions', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phone_number: '87001234567',
    amount: 5000,
    billing_period: 'monthly',
    description: 'Monthly subscription'
  })
})
const data = await response.json()
console.log('Subscription:', data.subscription.id)

Загрузка изображения + создание товара

cURL

# Шаг 1: Загрузить изображение
IMAGE_ID=$(curl -s -X POST https://bpapi.bazarbay.site/api/v1/catalog/upload-image \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "image=@product.jpg" | jq -r '.image_id')

# Шаг 2: Создать товар с изображением
curl -X POST https://bpapi.bazarbay.site/api/v1/catalog \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"items\": [{
      \"name\": \"Coffee Latte\",
      \"selling_price\": 1800,
      \"unit_id\": 1,
      \"image_id\": \"$IMAGE_ID\"
    }]
  }"

Возврат

cURL

# Полный возврат
curl -X POST https://bpapi.bazarbay.site/api/v1/invoices/42/refund \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Customer request"}'

# Частичный возврат
curl -X POST https://bpapi.bazarbay.site/api/v1/invoices/42/refund \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000, "reason": "Partial return"}'

Коды ошибок

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

{
  "message": "Описание ошибки",
  "errors": {
    "field_name": ["детали ошибки"]
  }
}