POST /sbp/customersРегистрирует покупателя под вашим идентификатором. Повторный вызов с тем же customerId второго клиента не создаёт: он обновит email и телефон и вернёт того же клиента. Нужно право sbp.create.
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
customerId | string | да | Ваш идентификатор клиента, до 128 символов |
email | string | да | Email клиента |
phone | string | да | Российский мобильный номер, оформленный на самого клиента по его текущему паспорту: банк сверяет номер с паспортом, и с этого номера клиент будет платить |
Телефон принимаем в любом виде: +7 999 123-45-67, 89991234567. Номер не российский или не мобильный — ответ 400 SBP_CUSTOMER_INVALID. Новый телефон начнёт действовать со следующего заказа.
curl -X POST 'https://b2b.lumowallet.io/sbp/customers' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"customerId": "cust-8841",
"email": "[email protected]",
"phone": "+79991234567"
}'{
"customerId": "cust-8841",
"email": "[email protected]",
"phone": "+79991234567",
"kycStatus": "none",
"kycReason": null,
"kycTerminal": false,
"canBuy": false,
"verifiedAt": null,
"createdAt": "2026-10-24T10:12:40.512Z"
}POST /sbp/customers/{customerId}/kycВозвращает verificationUrl. Откройте её клиенту в браузере или в WebView с доступом к камере, лучше с телефона. Понадобятся внутренний паспорт РФ и селфи.
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
callbackUrl | string | нет | Куда вернуть клиента после проверки, только https |
curl -X POST 'https://b2b.lumowallet.io/sbp/customers/cust-8841/kyc' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{ "callbackUrl": "https://example.com/kyc-done" }'{
"customerId": "cust-8841",
"kycStatus": "verifying",
"kycReason": null,
"kycTerminal": false,
"canBuy": false,
"verificationUrl": "https://verify.didit.me/session/…",
"…": "…"
}Не храните ссылку, запрашивайте её каждый раз, когда клиент возвращается к проверке. Пока проверка не закончена, мы отдаём ту же сессию, и клиент продолжит с того места, где остановился.
verificationUrl: null означает, что открывать нечего: клиент уже верифицирован, его данные проверяет банк или он получил окончательный отказ. Смотрите на kycStatus.
GET /sbp/customers/{customerId}Тело то же, что при регистрации. Статус меняется сам, о каждом изменении приходит вебхук sbp.customer.kyc_updated.
kycStatus | Что происходит |
|---|---|
none | Проверку не начинали, или сессия истекла (kycReason: didit_session_expired) |
verifying | Клиент проходит проверку паспорта |
submitting | Паспорт проверен, передаём данные банку |
provider_pending | Банк проверяет данные. Обычно это секунды, изредка дольше |
verified | Можно покупать, canBuy: true |
rejected | Отказ, причина в kycReason |
Показывайте кнопку покупки только при canBuy: true. Котировка неверифицированному клиенту вернёт 412 SBP_CUSTOMER_NOT_VERIFIED.
kycTerminal подсказывает, что делать при rejected:
false— можно повторить: снова вызовитеPOST /sbp/customers/{customerId}/kyc. Послеdidit_declined,passport_patronymic_missingиpassport_unreadableпридёт новая ссылка, число попыток ограничено, обычно три за неделю. После отказа банка (aura_…) паспорт и селфи заново не нужны: вызов просит банк перепроверить клиента, новый статус приходит сразу в ответе.true— повтор не поможет. Решение принимает поддержка.
kycReason | Окончательный | Что произошло |
|---|---|---|
didit_declined | нет | Проверка паспорта не пройдена: плохое фото, селфи не совпало и т. п. |
passport_not_russian_passport | да | Документ не является внутренним паспортом РФ |
passport_name_not_cyrillic | да | В паспорте не распознано ФИО кириллицей |
passport_patronymic_missing | нет | Отчество не распознано, паспорт в банк не отправлен. Клиенту нужно пройти проверку заново, сфотографировав паспорт целиком и чётко |
passport_unreadable | нет | Данные с разворота не совпали с машиночитаемой строкой внизу страницы или её не удалось прочитать, паспорт в банк не отправлен. Клиенту нужно пройти проверку заново: разворот целиком, ровно, без бликов на нижних строках |
passport_already_used | да | Паспорт уже привязан к другому покупателю |
passport_invalid | да | Банк счёл паспорт недействительным |
aura_… | по kycTerminal | Отказ банка, причина после префикса |
Причины с префиксом aura_ приходят от банка как есть. Список может расширяться, поэтому опирайтесь на kycTerminal, а не на конкретное значение.
Частый исправимый отказ — PhoneNumberFailed в kycReason: банк не связал телефон с паспортом. Так бывает, если номер оформлен на другого человека или на старый паспорт клиента. Передайте номер, оформленный на клиента, через POST /sbp/customers (или пусть клиент обновит паспорт у своего оператора) и снова вызовите POST /sbp/customers/{customerId}/kyc.