Возвраты | Pay.Aibot.kz

Полный или частичный возврат уже оплаченной операции

Возврат отправляет деньги обратно на карту клиента Kaspi. Поддерживаются полные и частичные возвраты, в том числе несколько частичных по одной операции.

Когда возможен возврат

•Платёж в статусе Processed (успешно оплачен)
•С момента оплаты прошло не более 90 дней
•Сумма возврата ≤ сумме платежа минус ранее возвращённого
•На счёте Kaspi достаточно средств

После 90 дней Kaspi не принимает возвраты по операции — придётся возвращать деньги вне Pay Bot.

Создание возврата

bash

Скачать

curl -X POST https://payapi.aibot.kz/v2/refunds \
  -H "X-API-Key: kp_live_xxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "operation_id": 14837690870,
    "amount": 5000,
    "reason": "Клиент отказался от заказа"
  }'

python

Скачать

import requests, uuid

resp = requests.post(
    "https://payapi.aibot.kz/v2/refunds",
    headers={
        "X-API-Key": "kp_live_xxx",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "operation_id": 14837690870,
        "amount": 5000,
        "reason": "Клиент отказался от заказа",
    },
)
refund = resp.json()

javascript

Скачать

const res = await fetch("https://payapi.aibot.kz/v2/refunds", {
  method: "POST",
  headers: {
    "X-API-Key": "kp_live_xxx",
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    operation_id: 14837690870,
    amount: 5000,
    reason: "Клиент отказался от заказа",
  }),
});
const refund = await res.json();

php

Скачать

$ch = curl_init("https://payapi.aibot.kz/v2/refunds");
curl_setopt_array($ch, [
    CURLOPT_POST =&gt; true,
    CURLOPT_HTTPHEADER =&gt; [
        "X-API-Key: kp_live_xxx",
        "Idempotency-Key: " . uniqid('', true),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS =&gt; json_encode([
        "operation_id" =&gt; 14837690870,
        "amount" =&gt; 5000,
        "reason" =&gt; "Клиент отказался от заказа",
    ]),
    CURLOPT_RETURNTRANSFER =&gt; true,
]);
$refund = json_decode(curl_exec($ch), true);

Параметры

Поле	Тип	Обязательно	Описание
`operation_id`	int	да	ID операции, которую возвращаете
`amount`	int	да	Сумма в тенге, ≤ оставшейся к возврату
`reason`	string	нет	Причина, для своей админки

Ответ

json

Скачать

{
  "refund_id": "ref_a1b2c3d4",
  "operation_id": 14837690870,
  "amount": 5000,
  "status": "Pending",
  "reason": "Клиент отказался от заказа",
  "created_at": "2026-05-11T15:00:00Z"
}

Статус сразу после создания — Pending. Kaspi обрабатывает возврат от секунд до пары часов. По завершению Pay Bot шлёт webhook payment.refunded.

Частичные возвраты

Можно сделать несколько возвратов по одной операции, пока сумма не достигнет общей оплаченной:

bash

Скачать

# Оплачено: 30000
# Возврат #1: 10000 — клиент вернул один товар
curl -X POST .../v2/refunds -d '{"operation_id": 1, "amount": 10000}'

# Возврат #2: 5000 — позже вернул ещё один
curl -X POST .../v2/refunds -d '{"operation_id": 1, "amount": 5000}'

# Доступно к возврату: 30000 - 10000 - 5000 = 15000

Идемпотентность

Idempotency-Key обязателен. Без него — 400 idempotency_key_required. Используйте уникальный ключ на каждую попытку возврата, например refund_{order_id}_{attempt}.

При повторе с тем же ключом в течение 24 часов вернётся оригинальный ответ с заголовком X-Idempotent-Replay: true — без второго списания.

Подробнее: Идемпотентность.

Webhook payment.refunded

После успешного возврата:

json

Скачать

{
  "id": "wh_evt_xyz789",
  "event": "payment.refunded",
  "created_at": "2026-05-11T15:05:00Z",
  "data": {
    "operation_id": 14837690870,
    "refund_id": "ref_a1b2c3d4",
    "amount": 5000,
    "refunded_total": 5000,
    "original_amount": 30000,
    "remaining_refundable": 25000
  }
}

Подпишитесь на payment.refunded в дашборде, чтобы обновлять заказы у себя.

Получение списка возвратов

bash

Скачать

curl "https://payapi.aibot.kz/v2/payments?type=refund&amp;cursor=&amp;limit=25" \
  -H "X-API-Key: kp_live_xxx"

Возвращает только операции-возвраты в обратном хронологическом порядке. См. Пагинацию.

Типичные ошибки

Код	Значение	Что делать
`400 amount_too_large`	Сумма больше доступной к возврату	Уменьшите `amount`
`400 operation_not_refundable`	Прошло 90 дней или статус не `Processed`	Возвращайте деньги вне Pay Bot
`404 operation_not_found`	Нет такой операции	Проверьте `operation_id`
`502 kaspi_unavailable`	Kaspi не отвечает	Повторите с тем же `Idempotency-Key`

Что дальше

•QR и счета через API — создание операции, которую потом возвращаете
•Webhooks — обработка payment.refunded
•Идемпотентность — почему критична для возвратов