> Источник: https://apipay.kz/guides/kyc-klienta-cherez-partner-api · Обновлено: 2026-08-15 · apipay.kz
> ApiPay — независимый сервис приёма платежей поверх вашего Kaspi Pay.

# Как партнёру провести клиента через анкету о бизнесе?

**TL;DR.** Анкету заполняет **сам клиент** — партнёр выдаёт ему одноразовую ссылку
(`POST .../kyc/invite`) и получает решение модератора вебхуком `kyc.status_changed`. Аккаунт в
ApiPay клиенту для этого не нужен. Пока анкета не одобрена, у клиента действует суточный
потолок счетов; в песочнице его нет.

## Коротко

| Вопрос | Ответ |
|---|---|
| Кто заполняет анкету | Только сам клиент — по вашей ссылке, без регистрации |
| Может ли партнёр подать за клиента | Нет — принимающей ручки не существует |
| Как выдать ссылку | `POST /api/partner/organizations/{id}/kyc/invite` |
| Сколько живёт ссылка | 14 дней; открывать можно сколько угодно раз |
| Как узнать решение | Вебхук `kyc.status_changed` на ваш `webhook_url` |
| Текущее состояние | `GET /api/partner/organizations/{id}/kyc` |
| До одобрения | Действует суточный потолок счетов у клиента |

## Почему анкету нельзя подать за клиента

В анкете есть подтверждение о неторговле запрещённым — азартные игры, крипта и форекс,
оружие, взрослый контент и подобное. Это юридическое заверение, и давать его должен тот, у
кого факты, — поэтому анкету заполняет и подтверждает сам клиент.

⛔ **Не проектируйте у себя форму-прокси**, которая собирает ответы клиента и отправляет их
нашим API от его имени: принимающей ручки не существует. Ваша роль — довести клиента до
формы, а не заполнить её.

## Шаг 1. Прочитать состояние

```bash
curl "https://api.apipay.kz/api/partner/organizations/829/kyc" -H "X-Partner-Key: $KEY"
```

```json
{ "success": true,
  "kyc": { "status": "needs_changes", "required_action": "fix_and_resubmit",
           "can_submit": true, "comment": "Скриншот витрины нечитаемый",
           "submitted_at": "2026-08-14T12:00:00+05:00", "submitted_via": "invite" } }
```

⚠️ **Ветвитесь по `required_action`, а не по `status`.** Это производное поле именно затем,
чтобы маппинг наших статусов не оказался зашит в вашей CRM: ветвление по нему переживает
пополнение набора статусов.

| `required_action` | Что делать вам |
|---|---|
| `submit_profile` | Выдать клиенту ссылку на анкету |
| `wait_review` | Ничего: анкета у модератора |
| `fix_and_resubmit` | Передать клиенту `comment` дословно и ссылку на исправление |
| `none` | Ничего: одобрено |
| `contact_support` | Обратиться в поддержку — это терминальный отказ |

`comment` приходит только при `fix_and_resubmit`. Передавайте его клиенту **дословно**:
это конкретное указание модератора, а пересказ превращает его в догадку.

### Все клиенты сразу

Опрашивать каждую организацию по отдельности не нужно:

- `GET /api/partner/health` → `organizations.kyc` — сколько клиентов в каком состоянии;
- `GET /api/partner/organizations?kyc_status=required,needs_changes` — кто именно; это и есть
  «кому нужна анкета», одним запросом;
- карточка каждой организации несёт `kyc_status`.

## Шаг 2. Выдать ссылку

```bash
curl -X POST "https://api.apipay.kz/api/partner/organizations/829/kyc/invite" \
  -H "X-Partner-Key: $KEY"
```

```json
{ "success": true, "invite_url": "https://apipay.kz/invite/2f6c…",
  "expires_at": "2026-08-29T12:00:00+05:00" }
```

Что важно знать про ссылку:

- **показывается один раз** — у нас хранится только её хеш, повторно получить ту же не выйдет;
- **передавайте её клиенту как есть** — адрес ссылки может измениться, собирать его у себя
  из токена не нужно;
- **новая выдача отзывает предыдущую** — если клиент потерял ссылку, просто выдайте новую, но
  старая перестанет работать;
- **открывать можно сколько угодно раз** до истечения срока: если анкету вернут на доработку,
  клиент исправит её по той же ссылке;
- **открывается без входа** — передавайте её клиенту лично (личный чат, письмо), а не в общий
  канал: у того, кто получил ссылку, есть доступ к анкете этой организации до истечения срока;
- живёт **14 дней**.

Отказы: `409 kyc_already_submitted` (анкета уже у модератора, одобрена или по ней вынесен отказ),
`409 test_organization` (тестовая организация — на ней анкета не заводится).

## Шаг 3. Что увидит клиент

Клиент открывает ссылку и заполняет три коротких шага — что продаёт и примерный средний чек,
где продаёт (ссылка на витрину и 1–3 скриншота), подтверждение о неторговле запрещённым.
Регистрация и вход не нужны, на странице видно только название его организации.

Скриншоты — jpg или png. Слишком большой файл отдаст `413`, неподходящий формат — `422
invalid_file_type`, а длинная склейка нескольких страниц в один узкий файл не принимается
(`422 image_rejected`) — её нужно приложить частями.

Полное описание анкеты глазами клиента — «[Анкета о бизнесе и лимит 1 платёж в
день](/guides/anketa-o-biznese-i-limit)». Эту статью удобно переслать клиенту вместе со
ссылкой.

## Шаг 4. Поймать решение вебхуком

Решение модератора приходит на ваш `webhook_url` — поллить статус каждой организации не нужно:

```json
{ "event": "kyc.status_changed", "scope": "partner", "partner_id": 7,
  "organization_id": 829, "external_id": "crm-client-42",
  "previous_status": "submitted", "kyc_status": "needs_changes",
  "comment": "Скриншот витрины нечитаемый",
  "source": "Partner Key", "is_sandbox": false, "timestamp": "2026-08-15T12:00:00+05:00" }
```

⚠️ **Событие описывает переход, а не текущее состояние.** Оба статуса зафиксированы в момент
решения, поэтому повторная доставка не «догоняет» более позднее состояние: если модератор
успел передумать, вы получите два события — про каждый переход своё. Опираться на текущее
состояние всегда можно через `GET .../kyc`.

⚠️ Событие приходит только по организациям, которыми вы управляете. Клиент, пришедший по вашей
реферальной ссылке, ведёт анкету сам и в своём кабинете.

Проверка подписи — та же, что у остальных наших событий:
«[Настройка вебхуков](/guides/nastroyka-webhookov-apipay)».

## Пока анкета не одобрена

Организация клиента работает, но с ограничением: **1 реальный счёт в сутки** (окно
Asia/Almaty). При попытке создать второй API вернёт `429 kyc_daily_limit_reached`, в теле
`meta{limit, reset_at, kyc_status}`, в заголовке `Retry-After` — секунды до сброса.

В лимит идут все реальные счета организации: выставленные из кабинета, созданные по
API-ключу, счета по QR и автосписания подписок. **В песочнице лимита нет** — отладку
интеграции клиент (и вы) продолжаете там без ограничений.

После одобрения лимит снимается автоматически. Отказ (`blocked`) закрывает приём платежей:
создание счёта возвращает `403 kyc_rejected`, статус терминальный.

## Частые ошибки

| Ответ | Что не так | Что делать |
|---|---|---|
| `409 kyc_already_submitted` | Анкета уже у модератора, одобрена или отклонена | Ничего: состояние — в `GET .../kyc`; при отказе решения ждать не нужно |
| `409 test_organization` | Организация тестовая | Анкета заводится только на боевой |
| `404 organization_not_found` | Организация заведена не вами (владелец — сам клиент) | Выдача по партнёрскому ключу работает только с организациями, которые создали вы; для остальных ссылку выдают из партнёрского кабинета |
| `404 invite_invalid` | Ссылка истекла, отозвана новой выдачей или не существует | Выдать новую |
| `429 kyc_daily_limit_reached` (у клиента) | Суточный потолок до одобрения | Довести клиента до анкеты; отладку продолжать в песочнице |
| `403 kyc_rejected` (у клиента) | Терминальный отказ | В поддержку |

## Частые вопросы

### Можно ли отправить анкету за клиента через API?

Нет. В анкете есть юридическое подтверждение о неторговле запрещённым, и давать его должен
сам клиент. Партнёр выдаёт ссылку — принимающей ручки для чужой анкеты не существует.

### Клиент потерял ссылку. Что делать?

Выдать новую тем же запросом. Ссылка показывается один раз (у нас хранится только её хеш), и
новая выдача отзывает предыдущую.

### Нужен ли клиенту аккаунт в ApiPay, чтобы заполнить анкету?

Нет. Страница анкеты открывается по ссылке без регистрации и входа; на ней видно только
название организации.

### Как узнать статус, не дожидаясь вебхука?

`GET /api/partner/organizations/{id}/kyc` всегда отдаёт текущее состояние — на него и
опирайтесь. Раскладку по всем клиентам сразу даёт `GET /api/partner/health`.

### Почему клиент создаёт только один счёт в сутки?

Это ограничение действует до одобрения анкеты и снимается автоматически после него. В песочнице ограничения нет.

Смотрите также: [Анкета о бизнесе и лимит 1 платёж в день](/guides/anketa-o-biznese-i-limit) ·
[Интеграция ApiPay с МоимСкладом](/guides/integraciya-apipay-s-moyskladom) ·
[Лимиты и квоты ApiPay](/guides/limity-i-kvoty-apipay) ·
[Настройка вебхуков](/guides/nastroyka-webhookov-apipay)

---

ApiPay — независимый сервис и не аффилирован с АО «Kaspi Bank». Kaspi и Kaspi Pay — товарные знаки их правообладателя.
База знаний: https://apipay.kz/guides