Список банков по номеру телефона

Метод получения списка СБП-банков, в которые ранее осуществлялись переводы по указанному номеру телефона. Список формируется на основе истории переводов (исторические данные) на стороне банка.

Список носит справочный характер

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

URL

ProductionStage

GET https://api.pay.kvell.group/v1/orders/payout/sbp/banks/{phone}

GET https://api.pay.stage.kvell.group/v1/orders/payout/sbp/banks/{phone}

Запрос

Path-параметры

Параметр	Тип	Обязательно	Описание
`phone`	string	Да	Номер телефона получателя: 11 цифр, код страны `7`, без `+`, пробелов и разделителей. Пример: `79991234567`.

Заголовки

Название	Тип	Обязательно	Описание
`X-Api-Key`	string	Да	Идентификатор магазина.
`X-Signature`	string	Да	Подпись запроса.

Формирование подписи

Объедините X-Api-Key, phone и secret_key без разделителей, вычислите SHA-256 от полученной строки в кодировке UTF-8 и передайте hex-результат в нижнем регистре в заголовке X-Signature.

SHA256(X-Api-Key + phone + secret_key)

secret_key находится в настройках магазина.

Пример

curl --request GET \
  --url 'https://api.pay.stage.kvell.group/v1/orders/payout/sbp/banks/79991234567' \
  --header 'X-Api-Key: 00000000-0000-4000-8000-000000000000' \
  --header 'X-Signature: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'

Ответ

Выберите HTTP-код, чтобы посмотреть пример, параметры ответа и рекомендуемые действия.

2004004034044225XX

Пример ответа 200 (OK)

[
  {
    "bank_id": "100100000014",
    "bank_bic": "012345678",
    "name": "RSB+ (Банк русский Стандарт)"
  },
  {
    "bank_id": "100000000202",
    "bank_bic": "012345678",
    "name": "Норвик Банк"
  },
  {
    "bank_id": "100000000201",
    "bank_bic": null,
    "name": "Банк Кремлевский"
  }
]

Если по номеру телефона нет исторических данных, метод возвращает пустой массив:

Пример пустого списка

[]

Параметры ответа

Параметр	Тип	Описание
`bank_id`	string	Идентификатор банка в СБП.
`bank_bic`	string \| null	БИК банка. Возвращается `null`, если БИК отсутствует в справочнике.
`name`	string	Наименование банка.

Пример ответа 400 (Bad Request)

{
  "errors": [
    {
      "code": 20002,
      "message": "Неверная подпись"
    }
  ]
}

Параметры ответа

Параметр	Тип	Описание
`errors`	array	Список ошибок. Коды и рекомендации приведены в разделе «Ошибки HTTP-ответов».
`errors[].code`	integer	Код ошибки. В примере — `20002`.
`errors[].message`	string	Описание причины отклонения запроса.

Что делать дальше

Проверьте номер телефона в URL, порядок значений в подписи и секретный ключ магазина.
Сформируйте правильный X-Signature и повторите запрос.

Пример ответа 403 (Forbidden)

{
  "errors": [
    {
      "code": 20037,
      "message": "Доступ запрещен"
    }
  ]
}

Параметры ответа

Параметр	Тип	Описание
`errors`	array	Список ошибок. Коды и рекомендации приведены в разделе «Ошибки HTTP-ответов».
`errors[].code`	integer	Код ошибки. В примере — `20037`.
`errors[].message`	string	Описание причины запрета доступа.

Пример ответа 404 (Not Found)

{
  "errors": [
    {
      "code": 20006,
      "message": "Магазин не найден"
    }
  ]
}

Параметры ответа

Параметр	Тип	Описание
`errors`	array	Список ошибок. Коды и рекомендации приведены в разделе «Ошибки HTTP-ответов».
`errors[].code`	integer	Код ошибки. В примере — `20006`.
`errors[].message`	string	Описание ресурса, который не найден.

Что означает ответ

Магазин для переданного X-Api-Key не найден. Ответ не означает отсутствие банков по номеру телефона.

Что делать дальше

Проверьте X-Api-Key и контур запроса.
Повторите запрос только после исправления ключа или URL контура.

Пример ответа 422 (Unprocessable Entity)

{
  "errors": [
    {
      "code": 20098,
      "message": "phone: Неверный формат номера телефона"
    }
  ]
}

Параметры ответа

Параметр	Тип	Описание
`errors`	array	Список ошибок валидации. Коды и рекомендации приведены в разделе «Ошибки HTTP-ответов».
`errors[].code`	integer	Код ошибки. Для ошибки поля — `20098`.
`errors[].message`	string	Поле и причина ошибки валидации.

Пример ответа 5XX (Internal Server Error)

{
  "errors": [
    {
      "code": 20000,
      "message": "Неизвестная ошибка"
    }
  ]
}

Параметры ответа

Параметр	Тип	Описание
`errors`	array	Список ошибок. Коды и рекомендации приведены в разделе «Ошибки HTTP-ответов».
`errors[].code`	integer	Код технической ошибки.
`errors[].message`	string	Описание технической ошибки.

Что делать дальше

Безопасно повторите тот же GET-запрос с теми же phone, X-Api-Key и X-Signature.
При повторяющейся ошибке обратитесь в поддержку KVELL и передайте URL, время запроса, HTTP-код, code и message.