Перейти к основному содержимому

Электронные кошельки

Сервис позволяет работать с электронными кошельками для самозанятых и любых партнеров, которым требуется эта функциональность.

На сегодняшний день реализована возможность:

Общие правила работы​

Правила работы с сервисом​

  1. Сервис предоставляет backend для работы с кошельками.
  2. Открытие, закрытие, изменение баланса кошельков происходит в режиме онлайн.
  3. Подтверждение операций по email, номеру телефона происходит на frontend Банка 131.
  4. Запросы от партнера к Банку 131 организованы через REST API.
  5. Уведомления о статусах действий с кошельком приходят в формате вебхуков.
  6. Для каждого партнера разрешен определенный набор используемых методов.
  7. Блокировка, списание или заморозка денежных средств на кошельке может происходить при получении запроса от государственных органов: МВД, ФССП, ФСН и др.

Правила работы с электронными кошельками​

  1. В одном проекте (X-PARTNER-PROJECT) физлицо НЕ может открыть несколько кошельков, даже если у них разный уровень идентификации и разные контактные данные (email, номер телефона).
  2. Кошельки открываются без срока действия и действуют до тех пор, пока проект (X-PARTNER-PROJECT) является активным.
  3. Нельзя закрыть кошелек с положительным балансом на счету.
  4. Кошельки с полной и упрощенной идентификацией открываются только граждан РФ.
  5. При открытии или закрытии кошелька с полной или упрощенной идентификацией отправляется уведомление в ФНС.
  6. Лимиты кошелька определяются согласно федеральному закону «О национальной платежной системе». Для кошельков также могут выставляться более строгие лимиты, чем регламентировано законодательством.

Формат работы с API​

Формат работы с API (формирование адреса для отправки запросов и данных аутентификации) подробно описан на нашем сайте.

Создание анонимного электронного кошелька​

Метод POST предназначен для создания анонимного электронного кошелька.

Адрес для отправки запроса​

/wallet/create/anonymous

Параметры запроса​

НазваниеОбязательностьТип данныхОписание
phone_number+stringНомер мобильного телефона без знака "+", 11 цифр
email+stringВалидный адрес электронной почты

Пример запроса​

curl -X POST \
https://demo.bank131.ru/wallet/create/anonymous \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-d '{
"phone_number": "79991234545",
"email": "ivanoff@yandex.ru"
}'

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

НазваниеОбязательностьТип данныхОписание
status+stringСтатус запроса. Возможные варианты: ok, error
data+ (при успешном запросе)objectОбъект с данными ответа
  request_id+stringИдентификатор запроса
  description+stringОписание статуса запроса, при успехе всегда отправляется ответ Запрос добавлен в очередь
error+ (при неуспешном запросе)objectОбъект с данными ошибки
  code+stringКод ошибки
  description+stringОписание ошибки

Коды ошибок​

КодОписание
partner_project_not_foundНе найден проект с указанным в заголовке идентификатором
wallet_account_number_not_foundУ партнера не настроена маска для генерации счетов
validation_errorОшибка валидации полей

Пример успешного ответа​

{
  "status": "ok",
  "data": {
    "request_id": "03706d18-c433-4e89-a1ed-db058fc5626c",
    "description": "Запрос добавлен в очередь"
  }
}

Пример неуспешного ответа​

{
  "status": "error",
  "error": {
    "code": "partner_project_not_found",
    "description": "Не найден проект с указанным в заголовке идентификатором"
  }
}

Создание электронного кошелька с упрощенной идентификацией​

Метод POST предназначен для создания электронного кошелька с упрощенной идентификацией (УПРИД).

Адрес для отправки запроса​

/wallet/create/simplified

Параметры запроса​

НазваниеОбязательностьТип данныхОписание
residence_type+stringТип резидента. Всегда: FL_RESIDENT
first_name+stringИмя
last_name+stringФамилия
patronymic-stringОтчество
birthday+stringДата рождения. Формат: ДД.ММ.ГГГГ. Получатель должен быть старше 18-ти лет
birthplace+stringМесто рождения
citizenship+stringГражданство. Формат: ISO 3166-1 alpha-2
inn+stringИНН клиента, 12 цифр
phone_number+stringНомер мобильного телефона без знака "+", 11 цифр
email+stringВалидный адрес электронной почты
documents+arrayПараметры документа
  type+stringТип документа. Всегда: PASSPORT_RF (паспорт РФ)
  series+stringСерия документа, 4 цифры
  number+stringНомер документа, 6 цифр
  issuer+stringКем выдан
  issuer_date+stringДата выдачи в формате ДД.ММ.ГГГГ
  issuer_code+stringКод подразделения

Пример запроса​

curl -X POST \
https://demo.bank131.ru/wallet/create/simplified \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-d '{
"residence_type": "FL_RESIDENT",
"last_name": "Дмитриев",
"first_name": "Иван",
"patronymic": "Герасимович",
"birthday": "01.01.1970",
"birthplace": "г. Новгород",
"citizenship": "RU",
"inn": "065553161159",
"phone_number": "79000000000",
"email": "name@email.com",
"documents": [
{
  "type": "PASSPORT_RF",
  "series": "0234",
  "number": "567890",
  "issuer": "ОТДЕЛОМ УФМС РОССИИ",
  "issuer_date": "01.01.2010",
  "issuer_code": "123-000"
}
]
}'

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

НазваниеОбязательностьТип данныхОписание
status+stringСтатус запроса. Возможные варианты: ok, error
data+ (при успешном запросе)objectОбъект с данными ответа
  request_id+stringИдентификатор запроса
  description+stringОписание статуса запроса, при успехе всегда отправляется ответ Запрос добавлен в очередь
error+ (при неуспешном запросе)objectОбъект с данными ошибки
  code+stringКод ошибки
  description+stringОписание ошибки

Коды ошибок​

КодОписание
partner_project_not_foundНе найден проект с указанным в заголовке идентификатором
wallet_account_number_not_foundУ партнера не настроена маска для генерации счетов
validation_errorОшибка валидации полей

Пример успешного ответа​

{
  "status": "ok",
  "data": {
    "request_id": "03706d18-c433-4e89-a1ed-db058fc5626c",
    "description": "Запрос добавлен в очередь"
  }
}

Пример неуспешного ответа​

{
  "status": "error",
  "error": {
    "code": "partner_project_not_found",
    "description": "Не найден проект с указанным в заголовке идентификатором"
  }
}

Повышение уровня анонимного кошелька до УПРИД​

Метод POST предназначен для повышения анонимного кошелька до уровня УПРИД кошелька.

Адрес для отправки запроса​

/wallet/{wallet_id}/identification/up_to_simplified

Параметры запроса​

При вызове метода укажите идентификатор кошелька (в примере ниже это цифры 1234).

НазваниеОбязательностьТип данныхОписание
inn+stringИНН клиента, 12 цифр
personal_info+objectИнформация о клиенте
  first_name+stringИмя
  last_name+stringФамилия
  middle_name-stringОтчество
  birthday+stringДата рождения. Формат: ДД.ММ.ГГГГ. Получатель должен быть старше 18-ти лет
  birthplace+stringМесто рождения
  citizenship+stringГражданство. Формат: ISO 3166-1 alpha-2
passport+objectДанные паспорта
  series+stringСерия документа, 4 цифры
  number+stringНомер документа, 6 цифр
  issuer+stringКем выдан
  issuer_date+stringДата выдачи в формате ДД.ММ.ГГГГ
  issuer_code+stringКод подразделения

Пример запроса​

curl -X POST \
https://demo.bank131.ru/wallet/1234/identification/up_to_simplified \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-d '{
"personal_info": {
  "first_name": "Иванов",
  "last_name": "Николай",
  "middle_name": "Петрович",
  "citizenship": "RU",
  "birthplace": "г. Пенза",
  "birthday": "06.06.1990"
},
"inn": "123456789123",
"passport": {
  "series": "0430",
  "number": "123223",
  "issuer_date": "",
  "issuer_code": "043-123",
  "issuer": "УВД35 г. Москвы"
}
}'

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

НазваниеОбязательностьТип данныхОписание
status+stringСтатус запроса. Возможные варианты: ok, error
data+ (при успешном запросе)objectОбъект с данными ответа
  request_id+stringИдентификатор запроса
  description+stringОписание статуса запроса
error+ (при неуспешном запросе)objectОбъект с данными ошибки
  code+stringКод ошибки
  description+stringОписание ошибки

Коды ошибок​

КодОписание
partner_project_not_foundНе найден проект с указанным в заголовке идентификатором
internal_errorВнутренняя ошибка
validation_errorОшибка валидации полей
phone_number_not_foundНе найден номер телефона
unexpected_errorВнутренняя ошибка

Пример успешного ответа​

{
  "status": "ok",
  "data": {
    "description": "Задача на повышение уровня идентификации поставлена в очередь",
    "request_id": "03706d18-c433-4e89-a2ed-db058fc5626c"
  }
}

Пример неуспешного ответа​

{
  "status": "error",
  "error": {
    "code": "partner_project_not_found",
    "description": "Не найден проект с указанным в заголовке идентификатором"
  }
}

Получение баланса кошелька​

Метод GET предназначен для получения баланса кошелька.

Адрес для отправки запроса​

/wallet/{wallet_id}/balance

Параметры запроса​

При вызове метода укажите идентификатор кошелька (в примере ниже это цифры 1234).

Пример запроса​

curl -X GET \
https://demo.bank131.ru/wallet/1234/balance \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \

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

НазваниеОбязательностьТип данныхОписание
status+stringСтатус запроса. Возможные варианты: ok, error
data+ (при успешном запросе)objectОбъект с данными
  wallet_id+stringИдентификатор кошелька
  balance+numberБаланс в копейках
  currency+stringВалюта
error+ (при неуспешном запросе)objectОбъект с данными об ошибке
  code+stringКод ошибки
  description+stringОписание ошибки

Коды ошибок​

КодОписание
partner_project_not_foundНе найден проект с указанным в заголовке идентификатором
internal_errorВнутренняя ошибка
wallet_not_foundАктивный кошелёк не найден
wallet_closed_foundКошелёк является закрытым
unexpected_errorВнутренняя ошибка

Пример успешного ответа​

{
  "status": "ok",
  "data": {
    "wallet_id": "1234",
    "balance": 100321,
    "currency": "RUB"
  }
}

Пример неуспешного ответа​

{
  "status": "error",
    "error": {
     "code": "wallet_not_found",
     "description": "Активный кошелек не найден"
    }
}

Пополнение кошелька​

Метод POST предназначен для пополнения электронного кошелька.

Адрес для отправки запроса​

/api/v1/session/init/payment

Параметры запроса​

Параметры запроса зависят от способа пополнения кошелька:

Полный список параметров запроса можно посмотреть на нашем сайте.

Пополнение кошелька с банковской карты​

НазваниеОбязательностьТип данныхОписание
payment_details+objectПлатежные данные
  type+stringТип способа оплаты: card
  card+objectДанные банковской карты
    type+stringТип передачи данных карты: bank_card
    bank_card+objectКарта в открытом виде
      number+stringНомер карты
      expiration_month+stringМесяц
      expiration_year+stringГод
      security_code+stringСекретный код CVC
amount_details+objectСумма
  amount+intЗначение суммы в копейках. Чтобы передать 100 рублей, укажите 10000
  currency+stringКод валюты согласно ISO 4217: rub
participant_details+objectИнформация об участниках
  sender+objectДанные отправителя
    full_name+stringПолное имя
  recipient+objectДанные получателя
    full_name+stringПолное имя (имя совпадает с именем отправителя)
    wallet_id+stringИдентификатор кошелька
customer+objectДанные клиента вашей системе
  reference+stringИдентификатор пользователя (до 128 символов)
  contacts-arrayСписок контактов пользователя
payment_options-objectДополнительные параметры платежа
metadata-*Дополнительная информация

Пополнение кошелька через СБП​

НазваниеОбязательностьТип данныхОписание
payment_details+objectПлатежные данные
  type+stringТип способа оплаты: faster_payment_system
  faster_payment_system+objectДанные банковской карты
    phone+stringТелефон получателя
    bank_id+stringИдентификатор банка получателя в СБП. Чтобы получить идентификатор, используйте метод fps/banks
    description+stringНазначение выплаты
amount_details+objectСумма
  amount+intЗначение суммы в копейках. Чтобы передать 100 рублей, укажите 10000
  currency+stringКод валюты согласно ISO 4217: rub
participant_details+objectИнформация об участниках
  sender+objectДанные отправителя
    full_name+stringПолное имя
  recipient+objectДанные получателя
    full_name+stringПолное имя (имя совпадает с именем отправителя)
    wallet_id+stringИдентификатор кошелька
customer+objectДанные клиента вашей системе
  reference+stringИдентификатор пользователя (до 128 символов)
  contacts-arrayСписок контактов пользователя
payment_options-objectДополнительные параметры платежа
metadata-*Дополнительная информация

Пример запроса для пополнения кошелька с банковской карты​

curl -X POST \
https://demo.bank131.ru/api/v1/session/init/payment \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_details": {
    "type": "card",
    "card": {
      "type": "bank_card",
      "bank_card": {
        "number": "4242424242424242",
        "expiration_month": "12",
        "expiration_year": "29",
        "security_code": "123"
      }
    }
  },
  "amount_details": {
    "amount": 1000,
    "currency": "rub"
  },
  "customer": {
    "reference": "ew_online",
    "contacts": [
      {
        "email": "email@131.ru"
      }
    ]
  },
  "participant_details": {
    "sender": {
      "full_name": "Full Name Test"
    },
    "recipient": {
      "full_name": "Full Name Test",
      "wallet_id": "98364988927770625"
    }
  },
  "payment_options": {
    "return_url": "https://www.131.ru",
    "recurrent": false
  },
  "metadata": {
    "key": "value"
  }
}

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

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-objectПлатежная сессия
error-objectОшибка

Пример успешного ответа​

{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2025-01-27T02:03:00.000000Z",
    "updated_at": "2025-01-27T02:03:00.000000Z",
    "acquiring_payments": [
      {
        "id": "pm_203",
        "status": "in_progress",
        "created_at": "2025-01-27T02:03:00.000000Z",
        "payment_details": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "4242",
            "country_iso3": "GBR"
          }
        },
        "amount_details": {
          "amount": 1000,
          "currency": "rub"
        },
        "customer": {
          "reference": "ew_online",
          "contacts": [
            {
              "email": "email@131.ru"
            }
          ]
        },
        "participant_details": {
          "sender": {
            "full_name": "Full Name Test"
          },
          "recipient": {
            "full_name": "Full Name Test",
            "wallet_id": "1234"
          }
        },
        "payment_options": {
          "return_url": "https://www.131.ru",
          "recurrent": false
        },
        "metadata": {
          "key": "value"
        }
      }
    ]
  }
}

Пример неуспешного ответа​

{
  "status": "error",
    "error": {
      "code": "error code",
      "description": "error description"
    }
}

Списание с кошелька​

Метод POST предназначен для списания средств с электронного кошелька.

Адрес для отправки запроса​

/api/v1/session/init/payout

Параметры запроса​

Параметры запроса зависят от способа вывода средств:

Полный список параметров запроса можно посмотреть на нашем сайте.

Вывод средств с кошелька на банковский счет​

НазваниеОбязательностьТипОписание
payment_method/payout_details+objectПлатежные данные
  type+stringТип способа получения выплаты: bank_account
  bank_account+objectБанковский счет получателя
    system_type+stringСистема банковских платежей: ru
    ru+objectСчет получателя в российском банке
      bik+stringБИК банка получателя
      account+stringБанковский счет получателя
      full_name+stringФИО физического лица
      description+stringНазначение выплаты
amount_details+objectСумма
  amount+intЗначение суммы в копейках. Чтобы передать 100 рублей, укажите 10000
  currency+stringКод валюты согласно ISO 4217: rub
participant_details+objectИнформация об участниках
  sender+objectДанные отправителя
    full_name+stringПолное имя
    wallet_id+stringИдентификатор кошелька
  recipient+objectДанные получателя
    full_name+stringПолное имя
metadata-*Дополнительная информация

Вывод средств с кошелька на банковскую карту​

НазваниеОбязательностьТипОписание
payment_method/payout_details+objectПлатежные данные
  type+stringТип способа получения выплаты: card
  card+objectБанковская карта получателя
    type+stringТип передачи данных карты: bank_card
    bank_card+objectКарта в открытом виде
      number+stringНомер карты
      expiration_month+stringМесяц
      expiration_year+stringГод
      security_code+stringСекретный код CVC
amount_details+objectСумма
  amount+intЗначение суммы в копейках. Чтобы передать 100 рублей, укажите 10000
  currency+stringКод валюты согласно ISO 4217: rub
participant_details+objectИнформация об участниках
  sender+objectДанные отправителя
    full_name+stringПолное имя
    wallet_id+stringИдентификатор кошелька
  recipient+objectДанные получателя
    full_name+stringПолное имя
metadata-*Дополнительная информация

Вывод средств с кошелька через СБП​

НазваниеОбязательностьТип данныхОписание
payment_method/payout_details+objectПлатежные данные
  type+stringЗначение: bank_account
  bank_account+objectБанковский счет
    system_type+stringСистема банковских платежей. Всегда: faster_payment_system
    faster_payment_system+objectДанные СБП
    phone+stringТелефон получателя
      bank_id+stringИдентификатор банка получателя в СБП
      description+stringНазначение выплаты (не более 140 символов). Как сформировать
amount_details+objectСумма
  amount+intСумма в копейках. Значение должно быть больше нуля. Чтобы передать 100 рублей, укажите 10000
  currency+stringКод валюты согласно ISO 4217. Регистр не важен. Всегда: rub
participant_details+objectИнформация об участниках
  sender+objectДанные отправителя
    full_name+stringПолное имя
    wallet_id+stringИдентификатор кошелька
  recipient+objectДанные получателя
    full_name+stringПолное имя получателя
metadata-*Дополнительная информация

Пример запроса вывода из средств из кошелька на карту​

curl -X POST \
https://demo.bank131.ru/api/v1/session/init/payout \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_method": {
    "type": "card",
    "card": {
      "type": "bank_card",
      "bank_card": {
        "number": "4242424242424242",
        "expiration_month": "12",
        "expiration_year": "29",
        "security_code": "123"
      }
    }
  },
  "amount_details": {
    "amount": 2000,
    "currency": "rub"
  },
  "participant_details": {
    "sender": {
      "full_name": "Full Name",
      "wallet_id": "1234"
  },
    "recipient": {
      "full_name": "Full Name"
    }
  },
  "metadata": {
    "key": "value"
  }
}

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

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-objectПлатежная сессия
error-objectОшибка

Пример успешного ответа​

{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2025-01-27T02:03:00.000000Z",
    "updated_at": "2025-01-27T02:03:00.000000Z",
    "payments": [
      {
        "id": "po_2018",
        "status": "in_progress",
        "created_at": "2025-01-27T02:03:00.000000Z",
        "payment_method": {
            "type": "card",
            "card": {
              "brand": "visa",
              "last4": "4242",
              "country_iso3": "GBR"
              }
        },
        "amount_details": {
          "amount": 2000,
          "currency": "rub"
        },
        "participant_details": {
          "sender": {
            "full_name": "Full Name",
            "wallet_id": "1234"
        },
          "recipient": {
            "full_name": "Full Name"
          }
        },
        "metadata": {
          "key": "value"
        }
      }
    ]
  }
}

Пример неуспешного ответа​

{
  "status": "error",
    "error": {
      "code": "error code",
      "description": "error description"
    }
}

Закрытие кошелька​

Метод POST предназначен для закрытия кошелька по требованию клиента.

Адрес для отправки запроса​

/wallet/{wallet_id}/close

Параметры запроса​

При вызове метода укажите идентификатор кошелька (в примере ниже это цифры 1234).

Пример запроса​

curl -X POST \
https://demo.bank131.ru/wallet/1234/close \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-d ''

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

НазваниеОбязательностьТип данныхОписание
status+stringСтатус запроса. Возможные варианты: ok, error
data+ (при успешном запросе)objectОбъект с данными
  request_id+stringИдентификатор запроса
  description+numberОписание статуса запроса
error+ (при неуспешном запросе)objectОбъект с данными об ошибке
  code+stringКод ошибки
  description+stringОписание ошибки

Коды ошибок​

КодОписание
partner_project_not_foundНе найден проект с указанным в заголовке идентификатором
wallet_not_foundАктивный кошелёк не найден
wallet_not_nullable_balance_errorБаланс кошелька должен быть нулевым
wallet_block_errorОшибка при блокировке кошелька в bookkeeper
unexpected_errorВнутренняя ошибка

Пример успешного ответа​

{
  "status": "ok",
  "data": {
    "description": "Кошелек поставлен на закрытие",
    "request_id": "03706d18-c433-4e89-a2ed-db058fc5626c"
  }
}

Пример неуспешного ответа​

{
  "status": "error",
    "error": {
      "code": "wallet_not_nullable_balance_error",
      "description": "Баланс кошелька должен быть нулевым. Текущий баланс - 3000"
    }
}

Вебхуки​

В заголовках вебхуков приходят параметры:

  • Content-Type: application/json - string, тип контента
  • X-PARTNER-SIGN: signature - string, подпись

Вебхук operation_with_wallet​

Данный вебхук приходит при совершении клиентом следующих операций:

  • Создание кошелька.

  • Повышение уровня кошелька.

  • Закрытие кошелька.

    Параметры вебхука​

НазваниеОбязательностьТип данныхОписание
type+stringТип вебхука: operation_with_wallet
data+objectОбъект с данными
  operation_type+stringТип операции:
- wallet_create- кошелёк создан,
- wallet_close - кошелёк закрыт,
- up_to_uprid_level - уровень кошелька повышен
  wallet_id+ (не приходит при wallet_close)stringИдентификатор кошелька
  description+stringОписание операции
  request_id+stringИдентификатор запроса

Примеры вебхука​

{
  "type": "operation_with_wallet",
  "data": {
    "operation_type": "wallet_create",
    "wallet_id": "1234",
    "description": "Кошелек создан",
    "request_id": "c8d16809-51a9-4aa3-8b10-ef75d1f0b866"
  }
}
{
  "type": "operation_with_wallet",
  "data": {
    "operation_type": "wallet_close",
    "description": "Кошелек успешно закрыт",
    "request_id": "c8d16809-51a9-4aa3-8b10-ef75d1f0b866"
  }
}
{
  "type": "operation_with_wallet",
  "data": {
    "operation_type": "up_to_uprid_level",
    "wallet_id": "1234",
    "description": "Уровень кошелька повышен и изменен на SIMPLIFIED",
    "request_id": "c8d16809-51a9-4aa3-8b10-ef75d1f0b866"
  }
}

Вебхук action​

Данный вебхук приходит при отправке клиенту сообщения по СМС или email при завершении операции создания кошелька.

НазваниеОбязательностьТип данныхОписание
type+stringТип вебхука: action
data+objectОбъект с данными
  operation_type+stringТип операции:
- sms_create - СМС создано,
- sms_send - СМС отправлено,
- e-mail_send - письмо отправлено
  description+stringОписание операции
  request_id+stringИдентификатор запроса
  uuid+stringУникальный идентификатор СМС или email-сообщения

Примеры вебхука​

{
  "type": "action",
  "data": {
    "operation_type": "sms_create",
    "description": "Создано отложенное сообщение для подтверждения номера телефона",
    "request_id": "c8d16809-51a9-4aa3-8b10-ef75d1f0b866",
    "uuid": "1215be96-47ab-46f8-9391-ae369e1ad7a3"
  }
}
{
  "type": "action",
  "data": {
    "operation_type": "sms_send",
    "description": "Отправлено отложенное сообщение для подтверждения номера телефона",
    "request_id": "c8d16809-51a9-4aa3-8b10-ef75d1f0b866",
    "uuid": "1215be96-47ab-46f8-9391-ae369e1ad7a3"
  }
}
{
  "type": "action",
  "data": {
    "operation_type": "e-mail_send",
    "description": "Отправлено подтверждение email адреса",
    "request_id": "c8d16809-51a9-4aa3-8b10-ef75d1f0b866",
    "uuid": "1215be96-47ab-46f8-9391-ae369e1ad7a3"
  }
}

Вебхук notification​

Банк может заблокировать или закрыть кошелек в следующих случаях:

  • данные владельца недействительны,
  • персональные данные устарели,
  • по решению Банка,
  • по решению суда,
  • по заявлению клиента,
  • по истечении срока действия.

Разблокировка происходит по решению Банка.

Параметры вебхука​

НазваниеОбязательностьТип данныхОписание
type+stringТип вебхука: notification
data+objectОбъект с данными
  wallet_id+stringИдентификатор кошелька
  operation_type+stringТип операции:
- wallet_is_blocked- кошелёк заблокирован,
- wallet_is_unblocked - кошелёк разблокирован,
- wallet_is_closed - кошелёк закрыт,
- wrong_personal_data - недействительные данные
  operation_time+ISO TIMEДата и время закрытия кошелька в формате YYYY-MM-DDT02:03:00.000000Z
  reason+stringПричина закрытия/блокировки/разблокировки кошелька

Примеры вебхука​

{
  "type": "notification",
  "data": {
    "wallet_id": "1234",
    "operation_type": "wrong_personal_data",
    "operation_time": "2025-04-03T02:00:59.104425+03:00",
    "reason": "Недействительные данные"
  }
}
{
"type": "notification",
"data": {
  "wallet_id": "1234",
  "operation_type": "wallet_is_blocked",
  "operation_time": "2025-04-03T02:00:59.104425+03:00",
  "reason": "По решению суда"
}
}
{
"type": "notification",
"data": {
  "wallet_id": "1234",
  "operation_type": "wallet_is_unblocked",
  "operation_time": "2025-04-03T02:00:59.104425+03:00",
  "reason": "Актуализированы ПДн"
}
}
{
"type": "notification",
"data": {
  "wallet_id": "1234",
  "operation_type": "wallet_is_closed",
  "operation_time": "2025-04-03T02:00:59.104425+03:00",
  "reason": "По решению банка"
}
}

Вебхук action_required​

Данный вебхук приходит при необходимости редиректа на страницу виджета.

Параметры вебхука​

НазваниеОбязательностьТипОписание
type+stringТип вебхука: action_required
session+objectПлатежная сессия

Пример вебхука​

{
    "type": "action_required",
    "session": {
        "id": "ps_3595815",
        "status": "in_progress",
        "created_at": "2025-05-22T13:47:29.029948Z",
        "updated_at": "2025-05-22T13:47:29.111328Z",
        "payments": [
            {
                "id": "po_953492",
                "status": "pending",
                "created_at": "2025-05-22T13:47:29.128937Z",
                "payment_method": {
                    "type": "bank_account",
                    "bank_account": {
                        "system_type": "ru",
                        "ru": {
                            "bik": "049205131",
                            "account": "40702810900000000011",
                            "full_name": "ООО ДваПиЭр",
                            "description": "Выплата",
                            "is_fast": false,
                            "kpp": "156605101",
                            "inn": "3316004790"
                        }
                    }
                },
                "amount_details": {
                    "amount": 1000,
                    "currency": "rub"
                },
                "amounts": {},
                "metadata": {
                    "key": "value"
                },
                "payment_metadata": {},
                "participant_details": {
                    "sender": {
                        "full_name": "Full Name Test",
                        "wallet_id": "1234"
                    },
                    "recipient": {
                        "full_name": "Full Name Test"
                    }
                },
                "customer_interaction": {
                    "type": "redirect",
                    "redirect": {
                        "url": "https://stage-verify.131.ru/ru/verify/transaction/70cf5df9-a4e5-491a-8fdd-5e0b02d26370/cG1fNTA0/41752947790cd418b9419454011ea6a2ec1ad94cbc84c52977dc86dffbfcd922",
                        "base_url": "https://stage-verify.131.ru/ru/verify/transaction/70cf5df9-a4e5-491a-8fdd-5e0b02d26370/cG1fNTA0/41752947790cd418b9419454011ea6a2ec1ad94cbc84c52977dc86dffbfcd922",
                        "method": "GET",
                        "qs": {},
                        "params": {}
                    }
                }
            }
        ]
    }
}

Вебхук в случае ошибки​

В случае ошибки возвращается название типа вебхука и описание ошибки.

Параметры​

НазваниеОбязательностьТип данныхОписание
type+stringТип вебхука: operation_with_wallet
data+objectОбъект с данными
  operation_type+stringТип операции:
- wallet_create- кошелёк создан,
- wallet_close - кошелёк закрыт,
- up_to_uprid_level - уровень кошелька повышен
  request_id+stringИдентификатор запроса
error+objectОбъект с данными об ошибке
  code+stringКод ошибки
  description+stringОписание ошибки

Примеры вебхука​

{
  "type": "operation_with_wallet",
  "data": {
    "request_id": "c8d16809-51a9-4aa3-8b10-ef75d1f0b866",
    "operation_type": "wallet_create"
  },
  "error": {
    "code": "internal_error",
    "description": "Внутренняя ошибка"
  }
}
{
  "type": "operation_with_wallet",
  "data": {
    "request_id": "c8d16809-51a9-4aa3-8b10-ef75d1f0b866",
    "operation_type": "wallet_close"
  },
  "error": {
    "code": "wallet_not_closed",
    "description": "Кошелек не может быть закрыт. Подтверждение не получено"
  }
}
{
  "type": "operation_with_wallet",
  "data": {
    "request_id": "c8d16809-51a9-4aa3-8b10-ef75d1f0b866",
    "operation_type": "up_to_uprid_level"
  },
  "error": {
    "code": "wallet_update_identification_error",
    "description": "Невозможно обновить идентификацию кошелька. Подтверждение не получено. [Wallet_id] - 1234"
  }
}

Коды ошибок​

Код ошибкиОписание ошибки
phone_in_blacklistНомер телефона в чёрном списке
phone_already_existsКошелёк с таким номером телефона уже существует
email_in_blacklistАдрес email в чёрном списке
email_already_existsКошелёк с таким email уже существует
internal_errorВнутренняя ошибка
phone_not_confirmedПроверка для номера телефона не пройдена. Создание кошелька отменено
email_not_confirmedПроверка для email не пройдена. Создание кошелька отменено
inn_in_blacklistИНН в чёрном списке
invalid_passportПаспорт недействительный
beneficiary_verification_failedПроверка бенефициара завершилась ошибкой
wallet_update_identification_errorПроизошла ошибка после запроса в bookkepeer для получения информации о кошельке
wallet_update_identification_errorПроизошла ошибка после запроса в bookkepeer для блокировки кошелька
wallet_update_identification_errorНевозможно обновить идентификацию кошелька. Подтверждение не получено
wallet_update_identification_errorПроизошла ошибка после разблокировки кошелька в bookkeeper
wallet_update_identification_errorПроизошла ошибка после запроса в bookkepeer для разблокировки кошелька
wallet_update_identification_errorИНН в чёрном списке
wallet_update_identification_errorПроизошла ошибка после проверки бенефициара
wallet_update_identification_errorПроизошла ошибка при создании кошелька
wallet_update_identification_errorПроизошла ошибка после запроса в bookkepeer для перевода баланса
wallet_update_identification_errorПроизошла ошибка после закрытия анонимного кошелька
wallet_not_closedКошелек не может быть закрыт. Подтверждение не получено
wallet_close_errorКошелек не может быть закрыт и разблокирован. Ошибка в промежуточном программном обеспечении
wallet_close_errorНевозможно зафиксировать закрытие кошелька в промежуточном программном обеспечении
ИИ-помощник