API docs by Redocly

TalkBank BaaS (1.0.0)

Download OpenAPI specification:

Введение

Данный API предназначен для автоматизации бизнес-процессов между TalkBank и партнерскими проектами.
В рамках АPI есть возможность:

  • создания новых пользователей;
  • прохождения идентификации клиентом;
  • выпуска пластиковых и виртуальных карт;
  • получения реквизитов карты клиента;
  • получения списка операций по картам;
  • приема платежей (эквайринг);
  • выплаты на карты физ. лиц;
  • холдирования, осуществления рекуррентных платежей;
  • p2p переводов.

Термины

  • barcode — 13 цифр, расположенных под штрих-кодом карты TalkBank;
  • Card Ref Id — уникальный номер корреспонденции (направления p2p-перевода) при выполнении p2p перевода;
  • Ref Number — уникальный номер операции;
  • KYC — операция установления личности клиента, которая выполняется перед проведением финансовой операции;
  • client_id — уникальный идентификатор клиента на стороне партнера. Если партнер не пользуется функционалом для создания клиента, данный параметр будет выдан;
  • зарегистрированная карта — карта, выпущенная TalkBank;
  • авторизованная карта — карта, выпущенная сторонним банком, имеющая уникальный идентификатор в системе партнера;
  • незарегистрированная карта — неавторизованная карта, выпущенная сторонним банком.

Подключение к API

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

Общение с сервисом осуществляется посредством HTTP запросов. POST, PUT параметры передаются в виде JSON в теле сообщения в кодировке UTF-8. Каждый запрос целиком подписывается с помощью HMAC-SHA-256.

Данные для авторизации передаются с помощью HTTP заголовка Authorization в формате TB1-HMAC-SHA256 uuid:hmac-sha256-hash.

Обязательные заголовки запроса. Используются в подписи запроса.

Имя Описание Пример
Date Текущее время запроса, RFC 7231 Tue, 19 Feb 2019 08:43:02 GMT
TB-Content-SHA256 SHA256 хеш от тела запроса, если запрос не содержит тела (например GET) - то от пустой строки e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Генерация подписи, псевдокод

StringToSign = HmacSha256Hex(
  Uppercase(RequestMethod) + "\n"
  RequestPath + "\n"
  RequestQuery + "\n"
  SignedRequestHeaders + "\n"
  SHA256Hex(RequestPayload)
, SecretToken)

При тестировании API необходимо обращаться к тестовому стенду по URL: https://baas.staging.talkbank.dev/.

Продакшен-окружение находится по URL: https://baas.talkbank.io/. Доступ к стенду осуществляется через аккаунт партнера. Для получения доступов необходимо обратиться к менеджеру TalkBank.

СЦЕНАРИИ ВЗАИМОДЕЙСТВИЯ

Создание клиента и выпуск карты

  1. Создайте клиента с набором данных KYC2 с помощью метода "Добавление клиента и запуск идентификации".
  • передайте данные по KYC1 для выпуска карты с упрощенными лимитами (расходный лимит - 40 тыс. руб. в месяц, максимальный баланс - 15 тыс. руб);
  • передайте данные по KYC2 для выпуска карты с упрощенными лимитами (расходный лимит - 200 тыс. руб., максимальный баланс - 60 тыс. руб.), при этом параметры ИНН и СНИЛС необязательны;
  • передайте данные по KYC3 для выпуска карты с расширенными лимитами (расходный лимит - 600 тыс. руб., баланс не ограничен).
  1. Получите статус идентификации клиента методом "Получение статуса клиента" или оформив подписку на событие order.
  2. Когда клиент успешно создан, вызовите метод активации карты:
  1. Дождитесь изменения статуса активации карты (5-15 мин). Получите статус по методу "Получение статуса активации карты" или оформите подписку на событие activation.
  2. Запросите реквизиты карты:

Авторизация карты клиента

Авторизация может проводиться с использованием платежной формы TalkBank или без нее. Это зависит от наличия у партнера сертификата PCI DSS. Наличие сертификата предполагает получение и хранение карточных данных клиента на стороне партнера, поэтому:

Наличие сертификата Как происходит авторизация
есть сертификат PCI DSS авторизация без формы
нет сертификата PCI DSS авторизация с формой
  1. Создайте платеж методом "Авторизация карты без формы" или "Авторизация карты с формой".
  2. В ответ вы получите ссылку на форму, на которую нужно переадресовать клиента.
  3. Клиент вводит данные карты (если авторизация с формой) и подтверждает операцию кодом 3dsec.
  4. При регистрации с карты будет списана авторизационная сумма 1 рубль, а затем автоматически возвращена.
  5. Для получения идентификатора карты в системе необходимо вызвать метод "Получение статуса платежа" или оформив подписку на событие order.
    Идентификатор карты будет указан в поле "card token", который необходимо сохранить для использования в дальнейших операциях. Финальный статус авторизационного платежа - cancelled.

Холдирование средств

Холдирование может проводиться с использованием платежной формы TalkBank или без нее. Это зависит от наличия у партнера сертификата PCI DSS. Наличие сертификата предполагает получение и хранение карточных данных клиента на стороне партнера, поэтому:

Наличие сертификата Как происходит холдирование
есть сертификат PCI DSS холдирование без формы
нет сертификата PCI DSS холдирование с формой
  1. Создайте запрос методом "Холдирование без формы" или "Холдирование с формой".
  • если карта ранее была авторизована, передайте в запросе "card_token". В этом случае форма будет предзаполнена;
  • если карта ранее не была авторизована, после успешного списания вам вернется "card_token". Он может понадобиться для досписания с клиента.
  1. В ответ вы получите ссылку, на которую нужно переадресовать клиента.
  2. Клиент вводит данные карты (если холдирование с формой) и подтверждает операцию кодом 3dsec.
  3. Статус операции можно получить методом "Получение статуса платежа" или оформив подписку на событие order. Обработка операции занимает 1-2 минуты.
  4. При успешной операции на карте клиента захолдируется сумма, указанная в поле "amount".

Для подтверждения списания захолдированной суммы используется метод "Подтверждение списания".
Для отмены списания захолдированной суммы используется метод "Отмена списания".
Для возврата уже списанной суммы используется метод "Оформление возврата операции".

Прием средств от клиентов

Прием средств может проводиться с использованием платежной формы TalkBank или без нее. Это зависит от наличия у партнера сертификата PCI DSS. Наличие сертификата предполагает получение и хранение карточных данных клиента на стороне партнера, поэтому:

Наличие сертификата Как происходит прием средств
есть сертификат PCI DSS прием средств без формы
нет сертификата PCI DSS прием средств с формой
  1. Создайте платеж методом "Списание с незарегистрированной карты на счет партнера" или "Списание с незарегистрированной карты на счет партнера с формой".
  2. В ответ вы получите ссылку, на которую нужно переадресовать клиента.
  3. Клиент вводит данные карты (если прием средств с формой) и подтверждает операцию кодом 3dsec.
  4. Статус операции можно получить методом "Получение статуса платежа" или оформив подписку на событие order. Обработка операции занимает 1-2 минуты.
  5. При успешной операции на счет партнера поступит сумма, указанная в поле "amount", за вычетом комиссии TalkBank.

Также прием платежей можно осуществлять по QR коду:

  1. Создайте платеж методом "Прием средств от клиента по СБП".
  2. В ответ получите ссылку на QR код, переадресуйте на нее клиента для подтверждения операции.
  3. Статус операции можно получить методом "Получение статуса платежа" или оформив подписку на событие order. Обработка операции занимает 1-2 минуты.
  4. При успешной операции на счет партнера поступит сумма, указанная в поле "amount", за вычетом комиссии TalkBank.

Выплаты клиентам

Выплаты могут проводиться с использованием платежной формы TalkBank или без нее. Это зависит от наличия у партнера сертификата PCI DSS. Наличие сертификата предполагает получение и хранение карточных данных клиента на стороне партнера, поэтому:

Наличие сертификата Как происходит списание на карту клиента
есть сертификат PCI DSS списание на карту клиента без формы
нет сертификата PCI DSS списание на карту клиента с формой
  1. Создайте платеж методом "Списание со счета партнера на незарегистрированную карту" или "Списание со счета партнера на незарегистрированную карту с формой".
  2. Статус операции можно получить методом "Получение статуса платежа" или оформив подписку на событие order. Обработка операции занимает 1-2 минуты.
  3. При успешной операции на счет партнера поступит сумма, указанная в поле "amount", за вычетом комиссии TalkBank.

Выплаты клиентам можно также переводить по реквизитам счета:

  1. Создайте платеж методом "Выплата по реквизитам".
  2. Статус операции можно получить методом "Получение статуса перевода по реквизитам" или оформив подписку на событие transfer. Обработка операции занимает 1-2 минуты.
  3. При успешной операции на счет партнера поступит сумма, указанная в поле "amount", за вычетом комиссии TalkBank.

СБП

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

  1. Проверьте доступность платежа клиенту методом "Проверка возможности совершения платежа клиенту" или "Проверка возможности совершения платежа по номеру телефона".
  2. Создайте платеж методом "Платеж клиенту" или "Платеж по номеру телефона".
  3. Статус операции можно получить методом "Получение статуса платежа" или оформив подписку на событие order. Обработка операции занимает 1-2 минуты.
  4. При успешной операции на счет партнера поступит сумма, указанная в поле "amount", за вычетом комиссии TalkBank.

Прием платежей по СБП может также осуществляться по QR коду:

  1. Создайте платеж методом "Прием средств от клиента по СБП".
  2. В ответ получите ссылку на QR код, переадресуйте на нее клиента для подтверждения операции.
  3. Статус операции можно получить методом "Получение статуса платежа" или оформив подписку на событие order. Обработка операции занимает 1-2 минуты.
  4. При успешной операции на счет партнера поступит сумма, указанная в поле "amount", за вычетом комиссии TalkBank.

Рекуррентные платежи

  1. Авторизуйте карту методом "Авторизация карты без формы" или "Авторизация карты с формой" или выполните одну из операций списания.
  2. При успешной операции сохраните "card_token".
  3. Настройте логику списаний и создайте платеж методом Списание с авторизованной карты без 3dsecure или "Списание средств с карты TalkBank на счет партнера".
  4. Статус операции можно получить методом "Получение статуса платежа" или оформив подписку на событие order. Обработка операции занимает 1-2 минуты.
  5. При успешной операции на счет партнера поступит сумма, указанная в поле "amount", за вычетом комиссии TalkBank.

Безопасная сделка

Безопасная сделка обеспечивает расчеты между продавцом и покупателем. Покупатель бронирует товар или услугу, а продавец получает деньги, только когда покупатель подтвердил, что товар или услуга получены в установленном количестве и объеме.

  1. Определите подходящий способ приема оплаты с покупателя:
  2. Клиент подтверждает качество услуги или товара.
  3. Статус операции можно получить методом "Получение статуса платежа" или оформив подписку на событие order. Обработка операции занимает 1-2 минуты.
  4. При успешной операции на счет партнера поступит сумма, указанная в поле "amount", за вычетом комиссии TalkBank.
  5. Создайте платеж в пользу продавца одним из методов: на карту, по СБП или по реквизитам счета для оплаты услуг продавца.
  6. Получите статус выплаты:

Выплаты самозанятым

  1. Создайте клиента с помощью метода "Добавление клиента и запуск идентификации".
  2. Проведите проверку статуса самозанятого методом "Получение статуса самозанятого".

  • если статус — registered, перейдите к п. 4;

  • если статус — unbound, направьте запрос на передачу прав TalkBank методом "Привязки самозанятого к TalkBank";

  • если статус — unregistered, самозанятый должен воспользоваться чат-ботом https://t.me/KassaSMZ_bot для постановки на учет. Подпишитесь на событие selfemployments. После того, как пользователь успешно зарегистрируется в качестве самозанятого, вы получите оповещение со статусом registered.

  1. Зарегистрируйте доход с помощью метода Регистрация дохода самозанятого. При успешной регистрации вы получите оповещение с ссылкой на чек.
  2. Создайте платеж на карту по реквизитам счета или по СБП. Если партнер планирует оплачивать налоги за самозанятого, то сумма выплаты = сумма чека - сумма налога:
  1. Получите статус выплаты:

Работа с бенефициарами

Функционал предназначен для работы с юридическими лицами (клиентами партнера), что позволяет вести раздельный учет по средствам заказчика на едином счету партнера.

  1. Создайте бенефициара с помощью метода "Создание бенефициара".
  2. В ответ получите уникальный идентификатор бенефициара, который используется в дальнейшей работе. Идентификатор бенефициара необходимо передавать при каждом запросе выплаты для корректного учета баланса.
  3. Для редактирования или блокировки бенефициара используйте метод "Редактирование бенефициара".
  4. Для записи комиссии, которая будет списываться в пользу партнера, используйте метод "Создание комиссии бенефициара".

  • Комиссия рассчитывается за каждую проведенную выплату.

  • Дата начала действия комиссии - это дата, с которой комиссия вступает в силу.

  • Чтобы изменить комиссию по бенефициару, необходимо создать новую комиссию с датой вступления изменений.
    Например:

    • Партнер создал комиссию, которая действует с 01.10.2023 в размере 3%;

    • Партнер создает 2-ю комиссию с датой начала действия от 01.11.2023 в размере 2%;

    • С 01.11.2023 с бенефициара начнет взиматься новая комиссия - 2%.

  • Типы комиссий:

    • % от суммы операции (3%);

    • % от суммы операции + фиксированная сумма (3% + 2 руб. за операцию);

    • % от суммы операции не менее фиксированной суммы (3%, но не менее 30 руб. за операцию).

  1. Для редактирования комиссии используйте метод "Редактирование комиссии бенефициара".

  2. Для удаления комиссии используйте метод "Удаление комиссии бенефициара".

  3. Для получения списка созданных комиссий по бенефициару используйте метод "Список комиссий бенефициара".

Для получения информации о бенефициаре, его актуальном остатке средств и начисленной комиссии используется метод "Корректировка баланса бенефициара".

Создание клиента

Добавление клиента и запуск идентификации

Метод позволяет создать клиента и запустить процесс идентификации (KYC). В дальнейшем этот функционал используется для выпуска карт, работы с самозанятыми и т.д. Для использования метода достаточно внести уникальный идентификатор клиента (client_id).
Для повторного запуска KYC с новыми данными используется метод Редактирование данных клиента.

Типы KYC:

  • KYC1 - создание клиента без идентификации (расходный лимит - 40 тыс. руб. в месяц, максимальный баланс - 15 тыс. руб.). Обязательные параметры – номер телефона.

  • KYC2 - упрощенная идентификация клиента (расходный лимит: 200 тыс. руб. в месяц, максимальный баланс - 60 тыс. руб.). Обязательные параметры – ФИО, секретное слово, телефон, серия и номер паспорта, дата рождения, дата выдачи документа, пол, ИНН.

  • KYC3 - полная идентификация клиента (расходный лимит: 600 тыс. руб. расходов в месяц, баланс не ограничен). Обязательные параметры – KYC2 + место и страна рождения, адрес прописки, код подразделения, кто выдал документ. Для прохождения KYC3 также требуется заполненная анкета от клиента и копии паспорта.


    1. Партнер вызывает метод и передает необходимые данные:

    При работе с самозанятыми:

    • в случае постановки исполнителя на учет, необходимо передавать набор данных по KYC1.
    • в случае передачи прав от исполнителя к TalkBank для проведения операций от его имени, необходимо передать набор данных по KYC1 + ИНН. Проверка статуса самозанятого осуществляется по ИНН.

    При выпуске карт:

    • с упрощенными лимитами требуется передать набор данных по KYC2, при этом параметры ИНН и СНИЛС необязательны.
    • с расширенными лимитами требуется передать набор данных по KYC3.
    1. Статус операции можно получить методом "Получение статуса клиента" или оформив подписку на событие identification. Обработка операции занимает 10-15 минут.
Request Body schema: application/json
client_id
required
string

Уникальный идентификатор клиента. Может состоять из: латинских букв, цифр и символов -._ Не более 40 символов

object (object_person_request)

Responses

Request samples

Content type
application/json
{
  • "client_id": "123124",
  • "person": {
    }
}

Response samples

Content type
application/json
{
  • "client_id": "12345"
}

Получение статуса клиента

Метод позволяет получить статус идентификации клиента.

Возможные статусы:

Статус Описание
Identification in process Идентификация в процессе
Identification complete Идентификация завершена
Identification Error Ошибка идентификации
path Parameters
client_id
string
Example: client1

Идентификатор клиента

Responses

Response samples

Content type
application/json
{
  • "client_id": "123154",
  • "is_identified": false,
  • "status": "Identification in process",
  • "status_code": "error",
  • "message": "passport: doc_status = 302: сведениями по заданным реквизитам не располагаем",
  • "additional": {
    }
}

Редактирование данных клиента

Метод позволяет отредактировать данные созданного ранее клиента и перезапустить процесс идентификации с новыми данными. Функционал может быть использован, если клиент не прошел проверку или передал некорректные / недействительные данные.
При редактировании клиента необходимо учесть, что номер телефона пользователя должен быть уникальным.

path Parameters
client_id
string
Example: client1

Идентификатор клиента

Request Body schema: application/json
required
object (object_person_request)

Responses

Request samples

Content type
application/json
{
  • "person": {
    }
}

Response samples

Content type
application/json
{
  • "client_id": "12345"
}

Работа с картами TalkBank

Выпуск виртуальной карты

Метод позволяет выпустить виртуальную карту для пользователя и автоматически запустить активацию этой карты. Получить реквизиты карты можно методом "Получение реквизитов карты".

  1. Партнер вызывает метод и передает необходимые данные, в ответ получает данные карты клиента.
  2. Статус операции можно получить методом "Получение статуса активации карты" или оформив подписку на событие activation. Обработка операции занимает не более 5 минут. Максимальное количество карт для пользователя - 5 виртуальных и 5 пластиковых.
path Parameters
client_id
string
Example: client1

Идентификатор клиента

Responses

Response samples

Content type
application/json
{
  • "client_id": "12345",
  • "barcode": "9950000000119",
  • "number": "5469********1649",
  • "expiration": "10/24"
}

Активация карты

Метод запускает активацию пластиковой или виртуальной карты клиента. Альтернативой метода для виртуальных карт может быть метод "Выпуск виртуальной карты".
1. Партнер вызывает метод и передает необходимые данные, в ответ получает данные карты клиента.
2. Статус операции можно получить методом "Получение статуса активации карты" или оформив подписку на событие activation. Обработка операции занимает не более 5 минут.
Максимальное количество карт для пользователя - 5 виртуальных и 5 пластиковых.

path Parameters
client_id
string
Example: client1

Идентификатор клиента

barcode
string
Example: 9950000000119

Баркод карты

Responses

Response samples

Content type
application/json
{
  • "client_id": "12345",
  • "barcode": "9950000000119",
  • "number": "5469********1649",
  • "expiration": "10/24"
}

Реактивация виртуальной карты

Метод перезапускает активацию виртуальной карты на пользователя и используется в случае, если предыдущая активация завершилась ошибкой "Заявка в обработке - запущены проверки по СМЭВ. Пожалуйста, повторите попытку активации позже".
1. Партнер вызывает метод и передает необходимые данные, в ответ получает данные карты клиента.
2. Статус операции можно получить методом "Получение статуса активации карты" или оформив подписку на событие activation. Обработка операции занимает не более 5 минут.

path Parameters
client_id
string
Example: client1

Идентификатор клиента

barcode
string
Example: 9950000000119

Баркод карты

Responses

Response samples

Content type
application/json
{
  • "client_id": "12345",
  • "barcode": "9950000000119",
  • "number": "5469********1649",
  • "expiration": "10/24"
}

Получение статуса активации карты

Метод позволяет получить статус заявки на активацию карты.

Возможные значения поля status:

Статус Описание Тип
Pending В ожидании string
Activated Активирована string
Error Ошибка string
path Parameters
client_id
string
Example: client1

Идентификатор клиента

barcode
string
Example: 9950000000119

Баркод карты

Responses

Response samples

Content type
application/json
{
  • "barcode": "9950000000119",
  • "status": "activated"
}

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

Метод возвращает реквизиты карты по баркоду.
Используется при отсутствии сертификата PCI DSS, т.к. не предполагает хранение карточных данных клиента на стороне партнера.

Возможные статусы карты

Статус Описание
ValidCard Карта активна
BlockedManual Карта заблокирована
NotActivated Карта не активирована
BlockedBank Заблокировано банком
BlockedAntifrod Заблокировано банком из-за подозрительных операций
Invalid Карта недействительна
Expired Истек срок действия карты
BlockedFinancial Заблокировано банком - банкротство, задолженность по карте
path Parameters
client_id
string
Example: client1

Идентификатор клиента

barcode
string
Example: 9950000000119

Баркод карты

Responses

Response samples

Content type
application/json
{
  • "card_number": "5469********1649",
  • "expiration": "10/24",
  • "status": "ValidCard",
  • "currency": "RUB",
  • "recipient": "Иванов Иван Иванович",
  • "checking_account": "40914810010550207764",
  • "bank_recipient": "ТКБ БАНК ПАО",
  • "legal_address": "109147, г. Москва, ул. Воронцовская, д.27/35, к/с: № 30101810800000000388 в ГУ Банка России по ЦФО",
  • "bik": "044525212",
  • "inn": 77123456789
}

Получение полного номера карты

Метод возвращает полный номер карты (PAN) без маскировки по баркоду для пополнения по номеру карты. Используется при наличие сертификата PCI DSS, т.к. предполагает получение и хранение карточных данных клиента на стороне партнера.

Возможные статусы карты

Статус Описание
ValidCard Карта активна
BlockedManual Карта заблокирована
NotActivated Карта не активирована
BlockedBank Заблокировано банком
BlockedAntifrod Заблокировано банком из-за подозрительных операций
Invalid Карта недействительна
Expired Истек срок действия карты
BlockedFinancial Заблокировано банком - банкротство, задолженность по карте
path Parameters
client_id
string
Example: client1

Идентификатор клиента

barcode
string
Example: 9950000000119

Баркод карты

Responses

Response samples

Content type
application/json
{
  • "card_number": "4314 0901 1111 1111",
  • "expiration": "10/24",
  • "status": "ValidCard",
  • "currency": "RUB",
  • "recipient": "Иванов Иван Иванович",
  • "checking_account": "40914810010550207764",
  • "bank_recipient": "ТКБ БАНК ПАО",
  • "legal_address": "109147, г. Москва, ул. Воронцовская, д.27/35, к/с: № 30101810800000000388 в ГУ Банка России по ЦФО",
  • "bik": "044525212",
  • "inn": 77123456789
}

Получение баркода по номеру карты

Метод возвращает идентификатор карты (barcode).

Возможные статусы карты:

Статус Описание
Activated Карта активирована
Pending Карта не активирована
Request Body schema: application/json
required
number
string

Номер карты

Responses

Request samples

Content type
application/json
{
  • "number": "1111222233334444"
}

Response samples

Content type
application/json
{
  • "barcode": "2000000000001",
  • "status": "Activated"
}

Заказ и доставка карты по указанному адресу

Метод позволяет организовать доставку пластиковых карт пользователю или выезд представителя банка для проведения полной идентификации.

  1. Партнер вызывает метод и передает необходимые данные, в ответ получает идентификатор и статус доставки Имеется два типа доставки и оплаты:
    Тип Описание
    courier Доставка осуществляется курьерской службой
    post Доставка осуществляется Почтой России
  2. Отслеживать изменение статуса доставки можно с помощью метода "Получение статуса доставки" или оформив подписку на событие delivery.
path Parameters
client_id
string
Example: client1

Идентификатор клиента

Request Body schema: application/json
required
type
string

Тип доставки

phone
string

Контактный телефон

city
string

Населенный пункт (город, деревня)

address
string

Адрес доставки (улица, дом, квартира/офис)

street
string

Улица

house
string

Дом

flat
string

Квартира

cards_count
integer

Количество заказанных карт

Responses

Request samples

Content type
application/json
{
  • "type": "post",
  • "phone": "+79260000000",
  • "city": "Москва",
  • "address": "Кремлевская пл., д. 1",
  • "street": "Кремлевская пл.",
  • "house": "1",
  • "flat": "1",
  • "cards_count": 1
}

Response samples

Content type
application/json
{
  • "client_id": "12345",
  • "delivery_id": 13611,
  • "delivery_status_code": 1,
  • "delivery_status_description": "new"
}

Получение статуса доставки

Метод позволяет запросить статус доставки или выезда представителя банка для проведения полной идентификации.

Возможные статусы доставки:

Код Описание кода
0 Доставка добавлена в систему
1 Доставка ожидает оплаты
2 Доставка ожидает оформления
3 Ошибка доставки (на стороне курьерской службы)
4 В пути
5 Отправлено
6 Добавлен трекинг-номер (для почты)
7 Доставка прибыла в пункт назначения (для почты)
8 Ошибка доставки (получатель не вышел на связь/перенос доставки)
9 Доставка завершена успешно
10 Отмена (с указанием причины)
path Parameters
client_id
string
Example: 12345

Идентификатор клиента

delivery_id
integer
Example: 123

Идентификатор доставки

Responses

Response samples

Content type
application/json
{
  • "client_id": "12345",
  • "delivery_id": 13611,
  • "delivery_status_code": 0,
  • "delivery_status_description": "new"
}

Перевод юридического лица физическому лицу

Метод позволяет совершить перевод юридического лица физическому лицу.

path Parameters
client_id
string
Example: client1

Идентификатор клиента

Request Body schema: application/json
required
transferID
string

Идентификатор операции

amount
integer

Сумма (в копейках)

barcode
string

Баркод карты

purpose
string

Комментарий

Responses

Request samples

Content type
application/json
{
  • "transferID": "b118731d-ba4f-44cf-bd85-8c547a13b748",
  • "amount": 100,
  • "barcode": "9950000000119",
  • "purpose": "Оплата по договору 12345 от 01.01.2024"
}

Response samples

Content type
application/json
{
  • "transferID": "b118731d-ba4f-44cf-bd85-8c547a13b748"
}

Получение баланса на карте

Метод возвращает актуальный баланс (в рублях) по карте клиента на текущий момент.

path Parameters
client_id
string
Example: client1

Идентификатор клиента

barcode
string
Example: 9950000000119

Баркод карты

Responses

Response samples

Content type
application/json
{
  • "barcode": "2000007536975",
  • "balance": 100,
  • "currency": "RUB"
}

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

Метод возвращает доступные лимиты, установленные по карте клиента, для разных разных типов операций. Значение лимитов возвращается в копейках.

Обновление лимита происходит 1-го числа каждого месяца.

Возможные типы лимитов:

Идентификатор лимита Название лимита Описание лимита Период
1 cash_day Снятие наличных День
19 cash_month Снятие наличных Месяц
29 internet_month Покупки (онлайн) Месяц
7 pos_day Покупки (оффлайн) День
27 pos_month Покупки (оффлайн) Месяц
56 cash_month Пополнения Месяц
79 p2pDb_month Переводы с карты Месяц
33 aggregate_month Общий расходный лимит (покупки+наличные+переводы) Месяц
- p2pcash_month Общий лимит на наличные и переводы (выдается он в случае если есть p2pDb_month и cash_month) Месяц
path Parameters
client_id
string
Example: client1

Идентификатор клиента

barcode
string
Example: 9950000000119

Баркод карты

Responses

Response samples

Content type
application/json
{
  • "cash_day": {
    },
  • "pos_day": {
    },
  • "cash_month": {
    },
  • "pos_month": {
    },
  • "internet_month": {
    },
  • "aggregate_month": {
    },
  • "p2pcr_month": {
    },
  • "p2pdb_day": {
    },
  • "p2pDb_month": {
    },
  • "p2pCash_month": {
    }
}

Изменение лимитов по карте

Метод позволяет изменить лимиты по карте клиента (в копейках). Например, партнер хочет сократить возможность перевода по карте до 15 тыс. в месяц.
Каждый лимит имеет свой идентификатор. Если не передается идентификатор, то передается изменение лимита p2pcash_month при условии соблюдения критериев, которые указаны в таблице для данного лимита. Важно! Нельзя установить лимиты больше, чем они возможны по УПРИДу.

При успешной установке лимита возвращается ответ с кодом 200 и пустым телом.

Возможные типы лимитов:

Идентификатор лимита Название лимита Описание лимита Период
1 cash_day Снятие наличных День
19 cash_month Снятие наличных Месяц
29 internet_month Покупки (онлайн) Месяц
7 pos_day Покупки (оффлайн) День
27 pos_month Покупки (оффлайн) Месяц
56 cash_month Пополнения Месяц
79 p2pDb_month Переводы с карты Месяц
33 aggregate_month Общий расходный лимит (покупки+наличные+переводы) Месяц
- p2pcash_month Общий лимит на наличные и переводы (выдается в случае если есть p2pDb_month и cash_month) Месяц
path Parameters
client_id
string
Example: client1

Идентификатор клиента

barcode
string
Example: 9950000000119

Баркод карты

Request Body schema: application/json
required
name
string

Идентификатор лимита

amount
integer

Сумма в копейках

Responses

Request samples

Content type
application/json
{
  • "name": "1",
  • "amount": 1000
}

Response samples

Content type
application/json
[ ]

Блокировка карты

Метод позволяет установить временную блокировку по карте клиента. Может использоваться в случае утери карты.

  1. Партнер вызывает метод и передает необходимые данные. Блокировка устанавливается в течение 1 минуты.
  2. Статус операции можно получить методом "Получение статуса блокировки". В поле "is_locked” будет установлено значение "1".

Если нужно разблокировать карту, используется метод "Снятие блокировки с карты".

path Parameters
client_id
string
Example: client1

Идентификатор клиента

barcode
string
Example: 9950000000119

Баркод карты

Request Body schema: application/json
reason
string

Причина блокировки, необязательно

Responses

Request samples

Content type
application/json
{
  • "reason": "Временная блокировка"
}

Response samples

Content type
application/json
{
  • "barcode": "9950000000119"
}

Получение статуса блокировки карты

Метод позволяет получить актуальный статус блокировки карты клиента на текущий момент.

Возможные статусы:

Статус Описание
"is_locked":0 Карта разблокирована
"is_locked":1 Карта заблокирована

Responses

Response samples

Content type
application/json
{
  • "barcode": "9950000000100",
  • "is_locked": 0
}

Снятие блокировки с карты

Метод позволяет разблокировать карту клиента, если карта была заблокирована партнером или на стороне TalkBank.

  1. Партнер вызывает метод и передает необходимые данные. Блокировка снимается в течение 1 минуты.
  2. Статус операции можно получить методом "Получение статуса блокировки". В поле "is_locked” будет установлено значение "0".
path Parameters
client_id
string
Example: client1

Идентификатор клиента

barcode
string
Example: 9950000000119

Баркод карты

Responses

Response samples

Content type
application/json
{
  • "barcode": "9950000000119"
}

Восстановление CVV

Метод направляет на номер телефона СМС, в котором указаны последние 6 цифр номера карты и CVV.

Примерный формат SMS

Ваш номер карты: **22 0014, CVV-код: 777 ТКББАНК ПАО

path Parameters
client_id
string
Example: client1

Идентификатор клиента

barcode
string
Example: 9950000000119

Баркод карты

Responses

Response samples

Content type
application/json
{
  • "barcode": "2000007536975",
  • "phone": "7 930 *** ** 25"
}

Получение транзакций по карте

Метод позволяет партнеру получить историю транзакций по карте клиента.
Расходные операции будут отражаться со знаком "-".

path Parameters
client_id
string
Example: client1

Идентификатор клиента

barcode
string
Example: 9950000000119

Баркод карты

query Parameters
from_date
string
Default: "-1 month"
Example: from_date=2020-12-31

Начиная с даты

to_date
string
Default: "now"
Example: to_date=2020-12-31

Вплоть до даты

page
integer
Default: 1
Example: page=2

Номер страницы

limit
integer
Default: 1000
Example: limit=100

Лимит записей, максимум 1000

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Создание ссылки на перевод card2card

  1. Партнер вызывает метод и передает необходимые данные.
  • Для перевода между своими картами необходимо указать параметры "from_ean" и "to_ean".
  • Для перевода на карту стороннего банка необходимо указать параметр "from_ean", поле "to_ean" оставить пустым.
  • Для пополнения карты внутри банка TalkBank необходимо указать параметры "from_ean" и "to_ean".
  • Для пополнения карты TalkBank с карты стороннего банка необходимо указать параметр "to_ean", а поле "from_ean" оставить пустым.
    При указании параметров отправителя и получателя вместе в ответ получает ссылку на банковскую форму. Время жизни ссылки - 15 минут.
  1. Партнер переадресовывает клиента на полученную форму, где клиент дополняет данные карты и подтверждает операцию кодом 3dsec.
  2. Статус операции можно получить методом "Получение статуса перевода card2card" или оформив подписку на событие order. Обработка операции занимает 1-2 минуты.
path Parameters
client_id
string
Example: client1

Идентификатор клиента

Request Body schema: application/json
from_ref_id
string

RefId карты списания

from_ean
string

Barcode карты списания

to_ref_id
string

RefId карты пополнения

to_ean
string

Barcode карты пополнения

amount
integer

4-значный пинкод карты

redirect_url
string

Страница, на которую попадает пользователь после ввода 3dsec

Responses

Request samples

Content type
application/json
{
  • "from_ref_id": "12",
  • "from_ean": "20000002232",
  • "to_ref_id": "21",
  • "to_ean": "20000001232",
  • "amount": 1234,
  • "redirect_url": "http://url"
}

Response samples

Content type
application/json
{}

Получение статуса перевода card2card

Метод позволяет получить статус перевода card2card. Партнер вызывает метод и передает необходимые данные. Параметр "payment_id" - идентификатор операции, приходит в ответе метода "Создание ссылки на перевод card2card".

Возможные статусы:

Статус Описание
new Платеж не был совершен
in process Операция в обработке
success Операция успешная
error Ошибка операции
path Parameters
client_id
string
Example: client1

Идентификатор клиента

payment_id
string
Example: eykn54re

Идентификатор ссылки на пополнение

Responses

Response samples

Content type
application/json
{
  • "payment_id": "eykn54re",
  • "payment_status": "in process",
  • "payment_status_description": "В обработке",
  • "is_complete": false
}

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

Метод позволяет получить список карт, активированных на клиента.

path Parameters
client_id
string
Example: client1

Идентификатор клиента

Responses

Response samples

Content type
application/json
[
  • "2000007536968"
]

История операций по счету партнера

Метод позволяет запросить транзакции по счету партнера за период.
Расходные операции будут отражаться со знаком "-".

query Parameters
from_date
string
Default: "-1 month"
Example: from_date=2020-12-31

Начиная с даты

to_date
string
Default: "now"
Example: to_date=2020-12-31

Вплоть до даты

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Информационные методы по счету партнера

Получение баланса

Метод возвращает актуальный баланс (в копейках) по счету партнера на текущий момент.

Responses

Response samples

Content type
application/json
{
  • "balance": 12345,
  • "currency": "RUB"
}

Получение статуса платежа

Метод используется для запроса статуса любой операции.
Альтернативой метода служит подписка на событие order, которая оповестит вас о смене статуса операции.

Возможные статусы:

Статус Описание
new Создана заявка на проведение операции
pending Операция в обработке
hold Операция холдирования
success Операция успешная
error Ошибка операции
expired Срок действия ордера истек
cancelled Операция отменена

Возможные коды атрибута state_code и описание атрибута state_description:

Код Описание
0 Ошибок нет
10 Недостаточно средств
11 Карта не найдена
12 Недействительная карта
13 Транзакция недоступна для держателя карты
14 Срок действия карты истек
15 Карта утеряна
16 Превышены лимиты карты
17 Отказ эмитента или платежной системы
18 Операции по карте ограничены
19 Карта изъята
20 Недействительный номер карты
21 Не найден БИН
22 Операции пополнения недоступны по карте
23 Неверный ввод CVV / CVV2
24 Карта украдена
path Parameters
order_slug
string
Example: external_sandbox_8eKEQ8Bw

Уникальный идентификатор операции со стороны партнера

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "order_id": "2076607",
  • "order_slug": "client_wof_32425_8e4Q0WyK",
  • "is_completed": true,
  • "type": "charge_unregistered",
  • "amount": 100,
  • "currency": "RUB",
  • "card_number": "5469********5183",
  • "is_authorization": false,
  • "description": "Успех",
  • "state_code": 0,
  • "state_description": "Нет ошибки",
  • "talkbank_commission": 100,
  • "beneficiary_partner_commission": 50
}

Список операций по счету партнера

Метод позволяет запросить список операций партнера за период.

Тип операции Описание
bank_refill Пополнение счета по реквизитам
transfer Перевод со счета по реквизитам
charge_auth Авторизационный платеж
charge_hold Операции холдирования
charge_registered Списание с зарегистрированной карты
charge_unregistered Списание с незарегистрированной карты
withdrawal Списание с карты TalkBank
refill_registered Пополнение зарегистрированной карты
refill_unregistered Пополнение незарегистрированной карты
refill Пополнение карты TalkBank
query Parameters
from_date
string
Default: "-1 month"
Example: from_date=2020-12-31

Начиная с даты

to_date
string
Default: "now"
Example: to_date=2020-12-31

Вплоть до даты

page
integer
Default: 1
Example: page=2

Номер страницы

on_page
integer
Default: 50
Example: on_page=4

Количество операций на страницу

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 1,
  • "page": 1,
  • "pages": 1
}

Операция по счету партнера

Метод получения одной операции.

Тип операции Описание
bank_refill Пополнение счета по реквизитам
transfer Перевод со счета по реквизитам
charge_auth Авторизационный платеж
charge_hold Операции холдирования
charge_registered Списание с зарегистрированной карты
charge_unregistered Списание с незарегистрированной карты
withdrawal Списание с карты TalkBank
refill_registered Пополнение зарегистрированной карты
refill_unregistered Пополнение незарегистрированной карты
refill Пополнение карты TalkBank
path Parameters
type
string
Example: bank_refill

Тип операции

id
string
Example: 55b0eacb-8936-4b44-bc09-9482e674edb8

Идентификатор операции

Responses

Response samples

Content type
application/json
Example
{
  • "type": "object_operation_bank_refill",
  • "id": "55b0eacb-8936-4b44-bc09-9482e674edb8",
  • "datetime": "2020-12-31T23:59:59+00:00",
  • "is_refill": true,
  • "amount": 100,
  • "sender_inn": "1234567890",
  • "sender_name": "ООО «Рога и копыта»",
  • "description": "Назначение платежа"
}

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

Метод позволяет партнеру получить историю транзакций по карте клиента.
Расходные операции будут отражаться со знаком "-".

query Parameters
from_date
string
Default: "-1 month"
Example: from_date=2020-12-31

Начиная с даты

to_date
string
Default: "now"
Example: to_date=2020-12-31

Вплоть до даты

page
integer
Default: 1
Example: page=2

Номер страницы

limit
integer
Default: 1000
Example: limit=100

Лимит записей, максимум 1000

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Получение платежной квитанции

Метод может быть использован для получения ссылки на платежную квитанцию по операциям.

Тип операции Описание
charge_auth Авторизационный платеж
charge_hold Операции холдирования
charge_registered Списание с зарегистрированной карты
charge_unregistered Списание с незарегистрированной карты
withdrawal Списание с карты TalkBank
refill_registered Пополнение зарегистрированной карты
refill_unregistered Пополнение незарегистрированной карты
refill Пополнение карты TalkBank
path Parameters
order_slug
string
Example: external_sandbox_e3bqG7MJ

Уникальный идентификатор операции со стороны партнера

query Parameters
no-bc
boolean
Example: no-bc=false

Формирование квитанции без поля с комиссией банка

Responses

Response samples

Авторизация клиентов

Авторизация карты без формы

Метод позволяет сохранять данные карты стороннего банка в системе. Используется при наличии сертификата PCI DSS, т.к. предполагает хранение данных держателя карты в системе партнера. В случае отсутствия сертификата PCI DSS для авторизации следует использовать метод "Авторизация карты с формой".

Процесс авторизации:

  1. Клиент оставляет данные карты в сервисе партнера.
  2. Партнер вызывает метод, в ответ получает ссылку, на которую переадресовывает клиента. В ответ получает ссылку на страницу для подтверждения операции кодом 3ds. Время жизни ссылки - 15 минут.
  3. Партнер переадресовывает клиента на полученную форму, где клиент подтверждает операцию.
  4. При регистрации с карты будет списана авторизационная сумма - 1 рубль, а затем автоматически возвращена.
    У клиента есть только одна попытка ввести данные при переходе по ссылке. При ошибке авторизации, необходимо вызвать метод еще раз и передать клиенту новую ссылку.
  5. Для получения идентификатора карты в системе необходимо вызвать метод "Получение статуса платежа". Идентификатор карты будет указан в поле "сard_token".
    Идентификатор необходимо сохранить для использования в дальнейших операциях.
    Финальный статус авторизационного платежа - cancelled.
path Parameters
client_id
string
Example: client1

Идентификатор клиента

Request Body schema: application/json
required
object (object_card_request)
redirect_url
string

Ссылка на страницу, на которую попадет пользователь после ввода 3dsec

Responses

Request samples

Content type
application/json
{
  • "card_info": {
    },
  • "redirect_url": "https://example.com"
}

Response samples

Content type
application/json
{}

Авторизация карты с формой

Метод позволяет сохранять данные карты стороннего банка в системе. Возможен при отсутствии сертификата PCI DSS, т.к. не предполагает хранение карточных данных в системе партнера.

Процесс авторизации:

  1. Партнер вызывает метод, в ответ получает ссылку, на которую переадресовывает клиента. Время жизни ссылки - 15 минут.
  2. Клиент по ссылке вводит реквизиты карты и подтверждает операцию. У клиента есть только одна попытка ввести данные при переходе по ссылке.
  3. При регистрации с карты будет списана авторизационная сумма - 1 рубль, а затем автоматически возвращена.
  4. Для получения идентификатора карты в системе необходимо вызвать метод "Получение статуса платежа".
    В поле "сard_token" будет указан идентификатор карты, который необходимо сохранить для использования в дальнейших операциях. Финальный статус авторизационного платежа - cancelled.
path Parameters
client_id
string
Example: client1

Идентификатор клиента

Request Body schema: application/json
required
redirect_url
string

Ссылка на страницу, на которую попадет пользователь после ввода 3dsec

order_slug
string

Уникальный идентификатор операции со стороны партнера (не более 40 символов)

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Прием средств от клиентов

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

Метод позволяет списывать средства с карт карт других банков РФ на счет партнера. Используется при наличии сертификата PCI DSS, т.к. предполагает хранение карточных данных в системе партнера. При отсутствии сертификата PCI DSS используется метод "Списание с незарегистрированной карты на счет партнера с формой".

  1. Партнер собирает данные карты клиента в своем сервисе.
  2. Партнер передает эти данные в методе, в ответ получает ссылку для подтверждения клиентом операции вводом кода 3dsec. Время жизни ссылки - 15 минут.
  3. Партнер переадресовывает клиента на полученную форму, где клиент подтверждает операцию.
  4. Статус операции можно получить методом "Получение статуса платежа" или оформив подписку на событие order. Обработка операции занимает 1-2 минуты.
  5. При успешной операции на счет партнера поступит сумма, указанная в поле "amount", за вычетом комиссии TalkBank.
path Parameters
client_id
string
Example: client1

Идентификатор клиента

Request Body schema: application/json
required
object (object_card_request)
amount
required
integer

Сумма списания в копейках

redirect_url
required
string

Ссылка на страницу, на которую попадет пользователь после ввода 3dsec

order_slug
required
string

Уникальный идентификатор операции со стороны партнера

Responses

Request samples

Content type
application/json
{
  • "card_info": {
    },
  • "amount": 100,
  • "redirect_url": "https://example.com",
  • "order_slug": "example_unique_identifier"
}

Response samples

Content type
application/json
{}

Списание с незарегистрированной карты на счет партнера с формой

Метод позволяет списывать средства на счет партнера с карт других банков РФ. Используется при отсутствии сертификата PCI DSS, т.к. не предполагает хранение карточных данных в системе партнера.

  1. Партнер вызывает метод, в ответ получает ссылку на банковскую форму. Время жизни ссылки - 15 минут.
  2. Партнер переадресовывает клиента на полученную форму, где клиент вводит реквизиты своей карты и подтверждает операцию кодом 3dsec.
  3. Статус операции можно получить методом "Получение статуса платежа" или оформив подписку на событие order. Обработка операции занимает 1-2 минуты.
  4. При успешной операции на счет партнера поступит сумма, указанная в поле "amount", за вычетом комиссии TalkBank.
path Parameters
client_id
string
Example: client1

Идентификатор клиента

Request Body schema: application/json
required
amount
required
integer

Сумма списания в копейках

redirect_url
required
string

Ссылка на страницу, на которую попадет пользователь после ввода 3dsec

order_slug
required
string

Уникальный идентификатор операции со стороны партнера

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Списание с авторизованной карты без 3dsecure

Метод позволяет списывать автоплатежи (рекуррентные платежи), например, досписание оплаты за услугу, подписку на сервис и т.д. с карты клиента. Используется при условии, что карта ранее была авторизована одним из методов "Авторизация клиентов".

  1. Партнер настраивает логику списания (периодичность, размер) в своем сервисе.
  2. Партнер вызывает метод в соответствии с настроенной логикой и передает необходимые данные.
  3. Статус операции можно получить методом "Получение статуса платежа" или оформив подписку на событие order. Обработка операции занимает 1-2 минуты.
  4. При успешной операции на счет партнера поступит сумма, указанная в поле "amount", за вычетом комиссии TalkBank.
path Parameters
client_id
string
Example: client1

Уникальный идентификатор клиента на стороне партнера

Request Body schema: application/json
required
amount
integer

Сумма частичной отмены холдирования (обычно не указывается)

card_token
string

Уникальный идентификатор карты в формате UUID

order_slug
required
string

Уникальный идентификатор операции со стороны партнера

Responses

Request samples

Content type
application/json
{
  • "amount": 100,
  • "card_token": "7daf4b05-2860-4e57-b1db-bccd40840bc5",
  • "order_slug": "example_unique_identifier"
}

Response samples

Content type
application/json
{
  • "order_slug": "example_unique_identifier"
}

Списание средств с карты TalkBank на счет партнера

Метод позволяет списывать автоплатежи (рекуррентные платежи), например, досписание оплаты за услугу, подписку на сервис и т.д. с карты TalkBank, выпущенной партнером. Процесс выпуска карты описан в сценарии "Создание клиента и выпуск карты".

  1. Партнер настраивает логику списания (периодичность, размер) в своем сервисе.
  2. Партнер вызывает метод в соответствии с настроенной логикой и передает необходимые данные.
  3. Статус операции можно получить методом "Получение статуса платежа" или оформив подписку на событие order. Обработка операции занимает 1-2 минуты.
  4. При успешной операции на счет партнера поступит сумма, указанная в поле "amount", за вычетом комиссии TalkBank.
path Parameters
client_id
string
Example: client1

Идентификатор клиента

barcode
string
Example: 9950000000119

Баркод карты

Request Body schema: application/json
required
amount
integer

Сумма пополнения в копейках

order_slug
required
string

Уникальный идентификатор операции со стороны партнера

Responses

Request samples

Content type
application/json
{
  • "amount": 100,
  • "order_slug": "example_unique_identifier"
}

Response samples

Content type
application/json
{
  • "order_id": 3,
  • "order_slug": "example_unique_identifier"
}

Оформление возврата операции

Метод позволяет оформить возврат для операций списания с карты клиента.
После успешного возврата операция перейдет в статус cancelled.

Request Body schema: application/json
required
amount
integer

Сумма для возврата. Если не указана, то будет возвращена вся сумма операции

order_slug
required
string

Уникальный идентификатор операции со стороны партнера

Responses

Request samples

Content type
application/json
{
  • "amount": 100,
  • "order_slug": "external_sandbox_e3bqG7MJ"
}

Response samples

Content type
application/json
{
  • "status": "pending",
  • "order_slug": "external_sandbox_8eKE9orn"
}

Отмена операции

Метод позволяет отменить операцию списания с карты клиента.
После успешного возврата операция перейдет в статус cancelled.

Request Body schema: application/json
required
order_slug
string

Уникальный идентификатор операции со стороны партнера

Responses

Request samples

Content type
application/json
{
  • "order_slug": "external_sandbox_e3bqG7MJ"
}

Response samples

Content type
application/json
{
  • "status": "cancelled",
  • "order_slug": "external_sandbox_8eKE9orn"
}

Холдирование средств

Холдирование без формы

Метод холдирует указанную сумму на карте клиента. Используется при наличии сертификата PCI DSS, т.к. предполагает хранение карточных данных в системе партнера. При отсутствии сертификата PCI DSS используется метод "Холдирование с формой".

  1. Партнер собирает данные карты клиента в своем сервисе.
  2. Партнер передает эти данные в методе, в ответ получает ссылку для подтверждения клиентом операции вводом кода 3dsec. Время жизни ссылки - 15 минут.
  3. Партнер переадресовывает клиента на полученную форму, где клиент подтверждает операцию.
  4. Статус операции можно получить методом "Получение статуса платежа" или оформив подписку на событие order. Обработка операции занимает 1-2 минуты.
  5. При успешной операции на карте клиента захолдируется сумма, указанная в поле "amount", за вычетом комиссии TalkBank.

Для подтверждения списания захолдированной суммы используется метод "Подтверждение списания".
Для отмены списания захолдированной суммы используется метод "Отмена списания".
Для возврата уже списанной суммы используется метод "Оформление возврата операции".

Request Body schema: application/json
required
object (object_card_request)
amount
integer

Сумма списания в копейках

redirect_url
string

Ссылка на страницу, на которую попадет пользователь после ввода 3dsec

card_token
string

Уникальный идентификатор карты в формате UUID

order_slug
string

Уникальный идентификатор операции со стороны партнера

Responses

Request samples

Content type
application/json
{
  • "card_info": {
    },
  • "amount": 100,
  • "redirect_url": "https://example.com",
  • "card_token": "assaffgqw12334",
  • "order_slug": "example_unique_identifier"
}

Response samples

Content type
application/json
{}

Холдирование с формой

Метод холдирует указанную сумму на карте клиента. Используется при отсутствии сертификата PCI DSS, т.к. не предполагает хранение карточных данных в системе партнера.

  1. Партнер вызывает метод, передает необходимые данные, в ответ получает ссылку на банковскую форму. Время жизни ссылки - 15 минут.
    Если карта клиента была ранее авторизована, необходимо указать параметр "card_token". В этом случае форма будет предзаполнена.
  2. Партнер переадресовывает клиента на полученную форму, где клиент вводит реквизиты своей карты и подтверждает операцию. Есть только одна попытка ввести данные при переходе по ссылке.
  3. Статус операции можно получить методом "Получение статуса платежа" или оформив подписку на событие order. Обработка операции занимает 1-2 минуты.
  4. При успешной операции на карте клиента захолдируется сумма, указанная в поле "amount".

Для подтверждения списания захолдированной суммы используется метод "Подтверждение списания".
Для отмены списания захолдированной суммы используется метод "Отмена списания".
Для возврата уже списанной суммы используется метод "Оформление возврата операции".

path Parameters
client_id
string
Example: client1

Идентификатор клиента

Request Body schema: application/json
required
amount
integer

Сумма списания в копейках

redirect_url
string

Ссылка на страницу, на которую попадет пользователь после ввода 3dsec

order_slug
string

Уникальный идентификатор операции со стороны партнера

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Подтверждение списания

Метод используется для подтверждения списания захолдированной суммы.

  1. Партнер вызывает метод и передает необходимые данные.
    Можно подтвердить холд на сумму меньшую, чем была указана ранее. В этом случае оставшаяся часть автоматически расхолдируется.
  2. Статус операции можно получить методом "Получение статуса платежа" или оформив подписку на событие order. Обработка операции занимает 1-2 минуты.
  3. При успешной операции на счет партнера поступит сумма, указанная в поле "amount", за вычетом комиссии TalkBank.
    Для возврата уже списанной суммы используется метод "Оформление возврата операции".
path Parameters
order_slug
string
Example: client_wof_32425_8e4Q0WyK

Уникальный идентификатор операции (не более 40 символов)

Request Body schema: application/json
required
amount
integer

Сумма списания в копейках. Может быть меньше суммы холдирования

Responses

Request samples

Content type
application/json
{
  • "amount": 100
}

Response samples

Content type
application/json
{
  • "amount": 100,
  • "order_slug": "example_unique_identifier"
}

Отмена списания

Метод используется для отмены списания захолдированной суммы.

  1. Партнер вызывает метод и передает необходимые данные.
    Можно отменить холд на сумму частично. Оставшаяся часть останется захолдирована.
  2. Статус операции можно получить методом "Получение статуса платежа" или оформив подписку на событие order. Обработка операции занимает 1-2 минуты.
  3. При успешной операции на карту клиента поступит раннее захолдированная сумма.
path Parameters
order_slug
string
Example: client_wof_32425_8e4Q0WyK

Уникальный идентификатор операции (не более 40 символов)

Request Body schema: application/json
required
amount
integer

Сумма частичной отмены холдирования (обычно не указывается)

Responses

Request samples

Content type
application/json
{
  • "amount": 100
}

Response samples

Content type
application/json
{
  • "amount": 100,
  • "order_slug": "example_unique_identifier"
}

Рекуррентные платежи

Списание с авторизованной карты без 3dsecure

Метод позволяет списывать автоплатежи (рекуррентные платежи), например, досписание оплаты за услугу, подписку на сервис и т.д. с карты клиента. Используется при условии, что карта ранее была авторизована одним из методов "Авторизация клиентов".

  1. Партнер настраивает логику списания (периодичность, размер) в своем сервисе.
  2. Партнер вызывает метод в соответствии с настроенной логикой и передает необходимые данные.
  3. Статус операции можно получить методом "Получение статуса платежа" или оформив подписку на событие order. Обработка операции занимает 1-2 минуты.
  4. При успешной операции на счет партнера поступит сумма, указанная в поле "amount", за вычетом комиссии TalkBank.
path Parameters
client_id
string
Example: client1

Уникальный идентификатор клиента на стороне партнера

Request Body schema: application/json
required
amount
integer

Сумма частичной отмены холдирования (обычно не указывается)

card_token
string

Уникальный идентификатор карты в формате UUID

order_slug
required
string

Уникальный идентификатор операции со стороны партнера

Responses

Request samples

Content type
application/json
{
  • "amount": 100,
  • "card_token": "7daf4b05-2860-4e57-b1db-bccd40840bc5",
  • "order_slug": "example_unique_identifier"
}

Response samples

Content type
application/json
{
  • "order_slug": "example_unique_identifier"
}

Списание средств с карты TalkBank на счет партнера

Метод позволяет списывать автоплатежи (рекуррентные платежи), например, досписание оплаты за услугу, подписку на сервис и т.д. с карты TalkBank, выпущенной партнером. Процесс выпуска карты описан в сценарии "Создание клиента и выпуск карты".

  1. Партнер настраивает логику списания (периодичность, размер) в своем сервисе.
  2. Партнер вызывает метод в соответствии с настроенной логикой и передает необходимые данные.
  3. Статус операции можно получить методом "Получение статуса платежа" или оформив подписку на событие order. Обработка операции занимает 1-2 минуты.
  4. При успешной операции на счет партнера поступит сумма, указанная в поле "amount", за вычетом комиссии TalkBank.
path Parameters
client_id
string
Example: client1

Идентификатор клиента

barcode
string
Example: 9950000000119

Баркод карты

Request Body schema: application/json
required
amount
integer

Сумма пополнения в копейках

order_slug
required
string

Уникальный идентификатор операции со стороны партнера

Responses

Request samples

Content type
application/json
{
  • "amount": 100,
  • "order_slug": "example_unique_identifier"
}

Response samples

Content type
application/json
{
  • "order_id": 3,
  • "order_slug": "example_unique_identifier"
}

Выплаты на карту со счета партнера

Получение токена карты

Метод позволяет сохранить карту в системе TalkBank и получить ее токен без проведения операции.
Этот токен в дальнейшем используется в методе "Списание со счета партнера на зарегистрированную карту".

path Parameters
client_id
string
Example: client1

Идентификатор клиента

Request Body schema: application/json
card_number
required
string

Действительный номер карты

Responses

Request samples

Content type
application/json
{
  • "card_number": "4314090014803658"
}

Response samples

Content type
application/json
{
  • "card_token": "7daf4b05-2860-4e57-b1db-bccd40840bc5"
}

Списание со счета партнера на незарегистрированную карту

Метод позволяет перевести денежные средства клиенту на карту стороннего банка. Используется при наличии сертификата PCI DSS, т.к. предполагает хранение карточных данных на стороне партнера. При отсутствии сертификата PCI DSS используется метод "Списание со счета на незарегистрированную карту с формой".

  1. Партнер собирает данные карты клиента в своем сервисе.
  2. Партнер передает эти данные в методе.
    Комиссия за транзакцию будет списана со счета партнера. Если необходимо переложить комиссию на клиента, то нужно указать это в поле "percents_on_user".
  3. Статус операции можно получить методом "Получение статуса платежа" или оформив подписку на событие order. Обработка операции занимает 1-2 минуты.
  4. При успешной операции на счет партнера поступит сумма, указанная в поле "amount", за вычетом комиссии TalkBank.
Request Body schema: application/json
required
amount
required
integer

Сумма списания (в копейках)

card_number
required
string

Номер карты

order_slug
string

Уникальный идентификатор операции со стороны партнера

percents_on_user
boolean
Default: false

Переложить комиссии на клиента

receipt_ids
Array of strings

Идентификаторы чеков самозанятого

beneficiary_id
string

Идентификатор бенефициара

currency_control_code
string

Код валютного контроля

currency_control_level
string

Уровень валютного контроля

currency_control_file_ids
Array of strings

Идентификаторы документов для валютного контроля

Responses

Request samples

Content type
application/json
{
  • "amount": 100,
  • "card_number": "4444111133335555",
  • "order_slug": "external_sandbox_e3bqG7MJ",
  • "percents_on_user": true,
  • "receipt_ids": [
    ],
  • "beneficiary_id": "01864b01-aaec-4717-9ce4-7b59db42af8f",
  • "currency_control_code": "VO21200",
  • "currency_control_level": "LEVEL_600",
  • "currency_control_file_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "new",
  • "order_id": "2076607",
  • "order_slug": "client_wof_32425_8e4Q0WyK",
  • "is_completed": false,
  • "type": "refill_unregistered",
  • "amount": 100,
  • "currency": "RUB",
  • "card_number": "4444********5555",
  • "is_authorization": false,
  • "description": "unknown",
  • "state_code": 0,
  • "state_description": "Нет ошибки",
  • "talkbank_commission": 2500,
  • "beneficiary_partner_commission": 5000
}

Списание со счета партнера на незарегистрированную карту с формой

Метод позволяет перевести денежные средства клиенту на карту стороннего банка. Используется при отсутствии сертификата PCI DSS, т.к. не предполагает хранение карточных данных клиента на стороне партнера.

  1. Партнер вызывает метод, передает необходимые данные, в ответ получает ссылку на банковскую форму. Время жизни ссылки - 15 минут.
    Комиссия за транзакцию будет списана со счета партнера. Если необходимо переложить комиссию на клиента, то нужно указать это в поле "percents_on_user".
  2. Партнер переадресовывает клиента на полученную форму, где клиент вводит реквизиты своей карты и подтверждает операцию. Есть только одна попытка ввести данные при переходе по ссылке.
  3. Статус операции можно получить методом "Получение статуса платежа" или оформив подписку на событие order. Обработка операции занимает 1-2 минуты.
  4. При успешной операции на счет партнера поступит сумма, указанная в поле "amount", за вычетом комиссии TalkBank.
path Parameters
client_id
string
Example: client1

Идентификатор клиента

Request Body schema: application/json
amount
required
integer

Сумма списания (в копейках)

redirect_url
string

Ссылка на страницу, на которую попадет пользователь после ввода 3dsec

order_slug
string

Уникальный идентификатор операции со стороны партнера

percents_on_user
boolean
Default: false

Переложить комиссии на клиента

receipt_ids
Array of strings

Идентификаторы чеков самозанятого

beneficiary_id
string

Идентификатор бенефициара

Responses

Request samples

Content type
application/json
{
  • "amount": 100,
  • "redirect_url": "https://example.com",
  • "order_slug": "external_sandbox_e3bqG7MJ",
  • "percents_on_user": true,
  • "receipt_ids": [
    ],
  • "beneficiary_id": "01864b01-aaec-4717-9ce4-7b59db42af8f"
}

Response samples

Content type
application/json
{}

Списание со счета партнера на зарегистрированную карту

Метод позволяет перевести денежные средства клиенту на карту клиента. Используется при условии, что карта ранее была авторизована одним из методов "Авторизация клиентов".

  1. Партнер вызывает метод и передает необходимые данные.
    Комиссия за транзакцию будет списана со счета партнера. Если необходимо переложить комиссию на клиента, то нужно указать это в поле "percents_on_user".
  2. Статус операции можно получить методом "Получение статуса платежа" или оформив подписку на событие order. Обработка операции занимает 1-2 минуты.
  3. При успешной операции на счет партнера поступит сумма, указанная в поле "amount", за вычетом комиссии TalkBank.
path Parameters
client_id
string
Example: client1

Идентификатор клиента

Request Body schema: application/json
required
amount
required
integer

Сумма списания (в копейках)

card_token
required
string

Уникальный идентификатор карты в формате UUID

order_slug
string

Уникальный идентификатор операции со стороны партнера

percents_on_user
boolean
Default: false

Переложить комиссии на клиента

receipt_ids
Array of strings

Идентификаторы чеков самозанятого

beneficiary_id
string

Идентификатор бенефициара

Responses

Request samples

Content type
application/json
{
  • "amount": 100,
  • "card_token": "7daf4b05-2860-4e57-b1db-bccd40840bc5",
  • "order_slug": "external_sandbox_e3bqG7MJ",
  • "percents_on_user": true,
  • "receipt_ids": [
    ],
  • "beneficiary_id": "01864b01-aaec-4717-9ce4-7b59db42af8f"
}

Response samples

Content type
application/json
{
  • "status": "new",
  • "order_id": "2076607",
  • "order_slug": "client_wof_32425_8e4Q0WyK",
  • "is_completed": false,
  • "type": "refill_registered",
  • "amount": 100,
  • "currency": "RUB",
  • "card_number": "4444********5555",
  • "is_authorization": false,
  • "description": "unknown",
  • "state_code": 0,
  • "state_description": "Нет ошибки",
  • "talkbank_commission": 2500,
  • "beneficiary_partner_commission": 5000
}

Списание со счета партнера на карту TalkBank

Метод используется для пополнения карт TalkBank, выпущенных партнером. Процесс выпуска карты описан в сценарии "Создание клиента и выпуск карты".

  1. Партнер вызывает метод и передает необходимые данные.
    Комиссия за транзакцию будет списана со счета партнера. Если необходимо переложить комиссию на клиента, нужно указать это в поле "percents_on_user".
  2. Статус операции можно получить методом "Получение статуса платежа" или оформив подписку на событие order. Обработка операции занимает 1-2 минуты.
  3. При успешной операции на счет партнера поступит сумма, указанная в поле "amount", за вычетом комиссии TalkBank.
path Parameters
client_id
string
Example: client1

Идентификатор клиента

barcode
string
Example: 9950000000119

Баркод карты

Request Body schema: application/json
required
amount
required
integer

Сумма списания (в копейках)

percents_on_user
boolean
Default: false

Переложить комиссии на клиента

receipt_ids
Array of strings

Идентификаторы чеков самозанятого

beneficiary_id
string

Идентификатор бенефициара

Responses

Request samples

Content type
application/json
{
  • "amount": "100§",
  • "percents_on_user": true,
  • "receipt_ids": [
    ],
  • "beneficiary_id": "01864b01-aaec-4717-9ce4-7b59db42af8f"
}

Response samples

Content type
application/json
{
  • "order_id": "2076607",
  • "order_slug": "client_wof_32425_8e4Q0WyK"
}

Выплаты по реквизитам

Выплата по реквизитам

Метод позволяет перевести денежные средства клиенту по реквизитам счета.

  1. Партнер вызывает метод и передает необходимые данные.
  2. Статус операции можно получить методом "Получение статуса перевода по реквизитам" или оформив подписку на событие transfer. Платежи по реквизитам обрабатываются в рабочее время в будние дни. Обычно это занимает не более 3 часов.
  3. При успешной операции на счет партнера поступит сумма, указанная в поле "amount", за вычетом комиссии TalkBank.
Request Body schema: application/json
amount
required
integer

Сумма пополнения (в копейках)

account
required
string

Номер счета получателя

bik
required
string

БИК банка получателя

name
required
string

Наименование получателя

inn
string

ИНН получателя

description
string

Описание платежа

order_slug
string

Уникальный идентификатор операции со стороны партнера

receipt_ids
Array of strings

Идентификаторы чеков самозанятого

beneficiary_id
string

Идентификатор бенефициара

income_code
string

Код вида дохода

currency_control_file_id
string

Идентификатор документа для валютного контроля

Responses

Request samples

Content type
application/json
{
  • "amount": 100,
  • "account": "00000000000000000001",
  • "bik": "000000001",
  • "name": "ООО «Рога и копыта»",
  • "inn": "123123123121",
  • "description": "Оплата услуг по договору",
  • "order_slug": "external_sandbox_e3bqG7MJ",
  • "receipt_ids": [
    ],
  • "beneficiary_id": "01864b01-aaec-4717-9ce4-7b59db42af8f",
  • "income_code": "3",
  • "currency_control_file_id": "file_id_123456"
}

Response samples

Content type
application/json
{
  • "completed": false,
  • "status": "new",
  • "order_slug": "external_sandbox_8eKE9orn",
  • "talkbank_commission": 2500,
  • "beneficiary_partner_commission": 5000
}

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

Метод используется для запроса статуса выплаты по реквизитам счета.
Альтернативой метода служит подписка на событие transfer, которая оповестит вас о смене статуса операции.

Возможные статусы:

Статус Описание
new Создана заявка на проведение операции
pending Операция в обработке
success Операция успешная
error Ошибка операции
path Parameters
order_slug
string
Example: external_sandbox_e3bqG7MJ

Уникальный идентификатор операции со стороны партнера

Responses

Response samples

Content type
application/json
{
  • "completed": false,
  • "status": "new",
  • "order_slug": "external_sandbox_8eKE9orn",
  • "talkbank_commission": 2500,
  • "beneficiary_partner_commission": 5000
}

Оплата налоговых платежей

Метод позволяет оплатить налог в ФНС за клиента. Процесс оплаты налогов описан в сценарии "Работа с самозанятыми".

  1. Партнер вызывает метод и передает необходимые данные.
  2. Статус операции можно получить методом "Получение статуса перевода по реквизитам" или оформив подписку на событие transfer. Платежи по реквизитам обрабатываются в рабочее время в будние дни. Обычно это занимает не более 3 часов.
  3. При успешной операции на счет налоговой поступит сумма, указанная в поле "amount", за вычетом комиссии TalkBank.
Request Body schema: application/json
required
amount
required
integer

Сумма пополнения (в копейках)

account
required
string

Номер счета получателя

bik
string

БИК банка получателя

name
required
string

Наименование получателя

inn
required
string

ИНН получателя

kpp
required
string

КПП

kbk
required
string

КБК

okato
required
string

ОКТМО

payment_base
required
string

Код основания платежа

tax_pediod
required
string

Налоговый период

tax_doc_num
required
string

Номер налогового документа

tax_doc_date
required
string

Дата налогового документа

uin
required
string

Уникальный идентификатор начисления

payer_inn
required
string

ИНН плательщика

payer_name
required
string

ФИО плательщика

description
string

Описание платежа

order_slug
string

Уникальный идентификатор операции со стороны партнера

former_status
string
Default: "20"

Статус составителя документа

Responses

Request samples

Content type
application/json
{
  • "amount": 100,
  • "account": "00000000000000000001",
  • "bik": "000000001",
  • "name": "ООО «Рога и копыта»",
  • "inn": "123123123121",
  • "kpp": "987654321",
  • "kbk": "18210500000011000010",
  • "okato": "00000001",
  • "payment_base": "123123123121",
  • "tax_pediod": "МС.04.2021",
  • "tax_doc_num": "0",
  • "tax_doc_date": "0",
  • "uin": "12309990000011000123",
  • "payer_inn": "1234561234567",
  • "payer_name": "Иванов Иван Иванович",
  • "description": "Оплата услуг по договору",
  • "order_slug": "external_sandbox_e3bqG7MJ",
  • "former_status": "20"
}

Response samples

Content type
application/json
{
  • "completed": false,
  • "status": "new",
  • "order_slug": "external_sandbox_8eKE9orn",
  • "talkbank_commission": 2500,
  • "beneficiary_partner_commission": 5000
}

Получение платежного поручения

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

path Parameters
order_slug
string
Example: external_sandbox_e3bqG7MJ

Уникальный идентификатор операции со стороны партнера

Responses

Response samples

Получение pdf файла для KYC

Для переводов нерезидентам по номеру счета необходимо предоставлять соответсвующие документы для валютного контроля. Данный метод позволяет загрузить документы в нашу систему. При использовании этого метода вы получаете индентификатор документа в нашей системе file_id, который в дальнейшем необходимо передавать в поле "currency_control_file_id" метода "Выплата по реквизитам"

Ограничения

  • формат файла - pdf;
  • максимальный размер файла - 10 Мб.
Request Body schema: multipart/form-data
required
contents
string

Содержимое файла документа

Responses

Response samples

Content type
application/json
{
  • "file_id": "0182ab4f-1d9f-6617-a99a-5a9121344407"
}

СБП

Проверка возможности совершения платежа по номеру телефона

Метод позволяет проверить доступность платежа по номеру телефона в указанный банк.
Альтернативой методу служит метод "Проверка возможности совершения платежа клиенту".

  1. Партнер вызывает метод и передает необходимые данные.
    Для определения банка могут передаваться либо БИК, либо название банка. Если переданы оба параметра, то определение будет происходить по БИК.
  2. В ответ получает идентификатор проверки, по которому проверяется статус проверки в методе "Получить статус проверки возможности совершения платежа по номеру телефона".

Возможные ошибки

Код Сообщение Комментарий
4f1912d1-9c86-4883-bf95-73699eed28be Request with id 03705a0e-ed44-4ca1-b622-67d06261cea5 already exists Запрос на проверку c указанным request_id уже существует
Request Body schema: application/json
request_id
string

Идентификатор проверки

phone
required
string

Номер телефона

bic
string

БИК. Необязателен, если указано название банка

bank_name
string

Название банка. Необязателен, если указан БИК

fio
string

ФИО получателя

Responses

Request samples

Content type
application/json
{
  • "request_id": "e299475c-8518-4192-aec6-b08b98dfd29b",
  • "phone": "+79998887766",
  • "bic": "012345678",
  • "bank_name": "ООО “Банк”",
  • "fio": "Иванов Иван Иванович"
}

Response samples

Content type
application/json
Example
{
  • "request_id": "55b0eacb-8936-4b44-bc09-9482e674edb8",
  • "errors": null
}

Получить статус проверки возможности совершения платежа по номеру телефона

Метод позволяет получить статус проверки доступности платежа по номеру телефона в указанный банк.

  1. Партнер вызывает метод и передает необходимые данные.
  2. В ответ получает информацию о доступности перевести денежные средства по указанному номеру телефона.

Возможные ошибки доступности

Код Сообщение Комментарий
1f67b674-d8eb-4617-b221-9fe3e37a7ebe Bank not found by given params По указанным параметрам банк не найден
f2e8b8ff-1bdb-4412-b1f7-bc643bf534ba Amount exceed client balance or maximum available value for SBP payment Для выполнения проверки необходимо пополннить счет.
a8562ab9-8036-4ce8-99fe-56fef6486130 Given recipient name not match one found by SBP service Не совпадает ФИО получателя платежа, переданное в параметре fio, с ФИО в Банке Получателя. Необходимо уточнить ФИО получателя и отправить новый запрос sbp_check_availability с правильными ФИО. Либо отправить без параметра fio, если несовпадение ФИО не является решающим фактором для отправителя.
03f111a8-df55-4206-a9b1-18b805e00139 Operation with order slug a2250f30-4170-446e-800a-12715089ae28 not found Идентификатор проверки не найден
path Parameters
request_id
required
string
Example: a2250f30-4170-446e-800a-12715089ae28

Идентификатор проверки

Responses

Response samples

Content type
application/json
Example
{
  • "status": "in_process",
  • "request_id": "55b0eacb-8936-4b44-bc09-9482e674edb8",
  • "is_available": null,
  • "errors": null
}

Платеж по номеру телефона

Метод позволяет перевести денежные средства клиенту по номеру телефона. Рекомендуется предварительно проверить возможность совершения платежа клиенту по номеру телефона методом "Проверка возможности совершения платежа по номеру телефона".

  1. Партнер вызывает метод и передает необходимые данные.
  2. Статус операции можно получить методом "Получение статуса платежа" или оформив подписку на событие order. Обработка операции занимает 1-2 минуты.
  3. При успешной операции клиенту поступит сумма, указанная в поле "amount", за вычетом комиссии TalkBank.
Request Body schema: application/json
phone
required
string

Номер телефона

bic
string

БИК. Необязателен, если указано название банка

bank_name
string

Название банка. Необязателен, если указан БИК

amount
required
integer

Сумма в копейках

order_slug
string

Внешний идентификатор платежа

receipt_ids
Array of arrays

Идентификаторы чеков самозанятого

beneficiary_id
string

Идентификатор бенефициара

fio
string

ФИО получателя

description
string

Назначение платежа

Responses

Request samples

Content type
application/json
{
  • "phone": "+79998887766",
  • "bic": "012345678",
  • "bank_name": "ООО “Банк”",
  • "amount": 120050,
  • "order_slug": "order_2209hx",
  • "receipt_ids": "200l55dvce",
  • "beneficiary_id": "017fe4c7-ac57-d5d6-62e1-ff74d0a09e61",
  • "fio": "Иванов Иван Иванович",
  • "description": "Назначение платежа"
}

Response samples

Content type
application/json
{
  • "order_slug": "order_20220707_b509s734f89e8145"
}

Проверка возможности совершения платежа клиенту

Метод позволяет проверить доступность совершения платежа клиенту по указанным реквизитам банка.
Альтернативой методу служит метод "Проверка возможности совершения платежа по номеру телефона".

  1. Партнер вызывает метод и передает необходимые данные.
    Для определения банка могут передаваться либо БИК, либо название банка. Если переданы оба параметра, то определение будет происходить по БИК.
  2. В ответ получает информацию о доступности перевести денежные средства клиенту по указанным реквизитам банка.

Возможные ошибки доступности

Код Сообщение
1f67b674-d8eb-4617-b221-9fe3e37a7ebe Bank not found by given params
f2e8b8ff-1bdb-4412-b1f7-bc643bf534ba Amount exceed client balance or maximum available value for SBP payment
a0ce0ac3-8450-4742-a525-1a9bffba9aa4 Given phone not registered for SBP payment or not exists
a8562ab9-8036-4ce8-99fe-56fef6486130 Given recipient name not match one found by SBP service
path Parameters
client_id
string
Example: client123

Идентификатор клиента

Request Body schema: application/json
required
bic
string

БИК. Необязателен, если указано название банка

bank_name
string

Название банка. Необязателен, если указан БИК

Responses

Request samples

Content type
application/json
{
  • "bic": "012345678",
  • "bank_name": "ООО “Банк”"
}

Response samples

Content type
application/json
{
  • "is_available": "false",
  • "errors": [
    ]
}

Платеж клиенту

Метод позволяет перевести денежные средства клиенту. Рекомендуется предварительно проверить возможность совершения платежа клиенту по указанным реквизитам банка методом "Проверка возможности совершения платежа клиенту".

  1. Партнер вызывает метод и передает необходимые данные.
  2. Статус операции можно получить методом "Получение статуса платежа" или оформив подписку на событие order. Обработка операции занимает 1-2 минуты.
  3. При успешной операции на клиенту поступит сумма, указанная в поле "amount", за вычетом комиссии TalkBank.
path Parameters
client_id
string
Example: client123

Идентификатор клиента

Request Body schema: application/json
bic
string

БИК. Необязателен, если указано название банка

bank_name
string

Название банка. Необязателен, если указан БИК

amount
required
integer

Сумма в копейках

order_slug
string

Внешний идентификатор платежа

receipt_ids
Array of arrays

Идентификаторы чеков самозанятого

beneficiary_id
string

Идентификатор бенефициара

description
string

Назначение платежа

Responses

Request samples

Content type
application/json
{
  • "bic": "012345678",
  • "bank_name": "ООО “Банк”",
  • "amount": 120050,
  • "order_slug": "order_2209hx",
  • "receipt_ids": "200l55dvce",
  • "beneficiary_id": "017fe4c7-ac57-d5d6-62e1-ff74d0a09e61",
  • "description": "Назначение платежа"
}

Response samples

Content type
application/json
{
  • "order_slug": "order_20220707_b509s734f89e8145"
}

Генерация платежной ссылки

Метод позволяет сгенерировать платежную ссылку для оплаты клиентом. Предварительно необходимо пройти листинг в ТСП, направив на почту accounts@talkbank.io перечень документов, указанный в памятке, включая заполненный опросный лист.

При переходе по платёжной ссылке с десктопа клиенту будет показан QR-код для оплаты. В случае перехода с мобильного устройства клиенту будет предложен выбор приложения банка для оплаты через СБП.

Request Body schema: application/json
is_static
required
bool

Параметр статичности QR кода. При генерации платежной ссылки на отдельные продукты ставится false

amount
required
integer

Сумма в копейках

qr_ttl_min
integer

Время жизни QR-кода в минутах

request_id
required
string

Уникальный идентификатор в формате UUID

Responses

Request samples

Content type
application/json
{
  • "is_static": true,
  • "amount": 120050,
  • "qr_ttl_min": 25,
  • "request_id": "4f96616f-1dc5-4104-a91b-c28617cba6c0"
}

Response samples

Content type
application/json
{}

Работа с самозанятыми

Определение ИНН по паспортным данным

Метод позволяет получить ИНН клиента по паспортным данным.

query Parameters
firstName
string
Example: firstName=Иван

Имя

lastName
string
Example: lastName=Иванов

Фамилия

patronymicName
string
Example: patronymicName=Иванович

Отчество

birthDay
string
Example: birthDay=2000-12-12

Дата рождения

passportSeries
string
Example: passportSeries=1234

Серия паспорта

passportNumber
string
Example: passportNumber=123456

Номер паспорта

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Получение статуса самозанятого

Метод позволяет получить статус клиента в качестве самозанятого. Используется в сценарии "Работа с самозанятыми". Партнер вызывает метод, передает необходимые данные, в ответ получает статус клиента.

Возможные статусы

Статус Описание
registered пользователь стоит на учете в ФНС в качестве самозанятого, передал банку права на проведение операций в ФНС от его лица
unregistered пользователь не стоит на учете в ФНС в качестве самозанятого
unbound пользователь стоит на учете в ФНС в качестве самозанятого, но не передал банку права на проведение операций в ФНС от его лица
path Parameters
client_id
string
Example: client1

Идентификатор клиента

Responses

Response samples

Content type
application/json
{
  • "client_id": "client123",
  • "status": "registered",
  • "description": "Success",
  • "details": {
    }
}

Привязка самозанятого к TalkBank

Метод используется при статусе клиента unbound и направляет запрос в ФНС для передачи прав на проведение операций в ФНС от лица самозанятого партнеру. Используется в сценарии "Работа с самозанятыми".

  1. Партнер вызывает метод и передает необходимые данные.
  2. Партнер переадресовывает клиента в приложение "Мой налог", где клиент должен подтвердить запрос конкретного банка.
  3. После подтверждения привязки клиентом, статус клиента становится registered.
path Parameters
client_id
string
Example: client123

Идентификатор клиента

Responses

Response samples

Content type
application/json
{
  • "client_id": "client123",
  • "status": "success"
}

Регистрация дохода самозанятого (асинхронный метод)

Метод позволяет зарегистрировать доход за самозанятого (выбить чек) в ФНС. Используется в сценарии "Работа с самозанятыми".
Партнер вызывает метод и передает необходимые данные, в ответ получает ссылку на чек.
Если нужно отменить чек, можно использовать метод "Отмена чека".

path Parameters
client_id
string
Example: client1

Идентификатор клиента

Request Body schema: application/json
required
RequestTime
string

Дата формирования

OperationTime
string

Дата расчета

Array of objects

Список услуг

TotalAmount
integer

Итоговая сумма чека

IncomeType
string

Источник/Тип дохода

CustomerInn
string

ИНН покупателя

CustomerOrganization
string

Наименование организации - покупателя

Array of objects

Координаты продажи

OperationUniqueId
string

Уникальный идентификатор операции

Responses

Request samples

Content type
application/json
{
  • "RequestTime": "2020-10-26T06:38:23+00:00",
  • "OperationTime": "2020-10-26T06:35:40+00:00",
  • "Services": [
    ],
  • "TotalAmount": 323.55,
  • "IncomeType": "FROM_LEGAL_ENTITY",
  • "CustomerInn": "7734387717",
  • "CustomerOrganization": "ООО «Рога и копыта»",
  • "GeoInfo": [
    ],
  • "OperationUniqueId": "operation_001"
}

Response samples

Content type
application/json
{
  • "client_id": "client123",
  • "id": 12345,
  • "RequestId": "11gp3hd94ed0j9ymsg5g6a82vf",
  • "Status": "SENT"
}

Отмена чека

Метод позволяет отменить чек за самозанятого. Используется в сценарии "Работа с самозанятыми".
Партнер вызывает метод и передает необходимые данные, в ответ получает статус отмены чека.

path Parameters
client_id
string
Example: client123

Идентификатор клиента

Request Body schema: application/json
required
ReceiptId
string

Идентификатор чека

Reason
string

Причина отмены

Responses

Request samples

Content type
application/json
{
  • "ReceiptId": "2005tq4hfz",
  • "Reason": "REGISTRATION_MISTAKE"
}

Response samples

Content type
application/json
{
  • "client_id": "client123",
  • "status": "error",
  • "description": [
    ]
}

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

Метод позволяет получить все чеки по конкретному самозанятому за указанный период. Используется в сценарии "Работа с самозанятыми".

path Parameters
client_id
string
Example: client1

Идентификатор клиента

query Parameters
dateFrom
string
Example: dateFrom=2021-02-25

Дата начала периода

dateTo
string
Example: dateTo=2021-02-25

Дата окончания периода

Responses

Response samples

Content type
application/json
{
  • "client_id": "client123",
  • "status": "success",
  • "data": {
    }
}

Получение информации по доходу самозанятого за период

Метод возвращает доходы конкретного самозанятого за указанный период.

path Parameters
client_id
string
Example: client123

Идентификатор клиента

query Parameters
taxPeriod
string
Example: taxPeriod=202110

Год и месяц налогового периода

Responses

Response samples

Content type
application/json
{
  • "client_id": "client123",
  • "status": "success",
  • "data": {
    }
}

Получение списка налоговых начислений, долгов и пени самозанятого

Метод возвращает налоговые начисления, долги и пени конкретного самозанятого. Используется в сценарии "Работа с самозанятыми".

path Parameters
client_id
string
Example: client1

Идентификатор клиента

Responses

Response samples

Content type
application/json
{
  • "client_id": "client123",
  • "status": "success",
  • "data": {
    }
}

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

Метод возвращает реквизиты и квитанции для оплаты начислений. Можно использовать для дальнейшей уплаты налогов. Используется в сценарии "Работа с самозанятыми".
Партнер вызывает метод и передает необходимые данные, в ответ получает реквизиты и квитанции для начислений, сформированные в формате PDF.

path Parameters
client_id
string
Example: client1

Идентификатор клиента

Responses

Response samples

Content type
application/json
{
  • "client_id": "client123",
  • "status": "success",
  • "data": {
    }
}

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

Метод возвращает список всех запросов на привязку, которые направлялись самозанятому.

path Parameters
client_id
string
Example: client123

Идентификатор клиента

Responses

Response samples

Content type
application/json
{
  • "client_id": "client123",
  • "status": "success",
  • "data": {
    }
}

Подтверждение/отклонение запроса на привязку cамозанятого к платформе

Метод возвращает информацию, какой запрос на привязку принял/отклонил самозанятый.

path Parameters
client_id
string
Example: client123

Идентификатор клиента

Request Body schema: application/json
required
requestId
string

Идентификатор запроса партнера на привязку самозанятого

accept
boolean

Привязка самозанятого к платформе

Responses

Request samples

Content type
application/json
{
  • "requestId": "640243",
  • "accept": true
}

Response samples

Content type
application/json
{
  • "client_id": "client123",
  • "status": "error",
  • "description": [
    ]
}

Получение списка разрешений

Метод возвращает список разрешений, которые предоставил самозанятый для проведения операций в ФНС от лица самозанятого. Например, для регистрации/отмены дохода, оплаты налоговых начислений и т.д. Используется в сценарии "Работа с самозанятыми".

Список разрешений

Код Описание
INCOME_REGISTRATION Отражение дохода от моего имени
PAYMENT_INFORMATION Получение информации по моим налоговым начислениям
TAX_PAYMENT Оплата налоговых начислений от моего имени
INCOME_LIST Получение информации по моим доходам
INCOME_SUMMARY Получение сводной информации о доходе
CANCEL_INCOME Корректировка сведений о моих доходах, поданных Партнером
CANCEL_ANY_INCOME Корректировка сведений о моих доходах без ограничений
TAXPAYER_UPDATE Корректировка сведений моего профиля
PERMISSIONS_MGMT Управление Партнерами
path Parameters
client_id
string
Example: client123

Идентификатор клиента

Responses

Response samples

Content type
application/json
{
  • "client_id": "client123",
  • "status": "success",
  • "data": {
    }
}

Получение справки о доходах самозанятого

Метод возвращает справку о доходах конкретного самозанятого за указанный период в формате PDF.

path Parameters
client_id
string
Example: client123

Идентификатор клиента

query Parameters
requestYear
string
Example: requestYear=2021

Год, за который запрашивается справка

Responses

Response samples

Content type
application/json
{
  • "client_id": "client123",
  • "status": "success",
  • "data": {
    }
}

Получение справки о постановке на учет (снятии с учета) физического лица в качестве самозанятого

Метод возвращает справку о постановке/снятия с учета конкретного самозанятого за указанный период в формате PDF.

path Parameters
client_id
string
Example: client123

Идентификатор клиента

query Parameters
requestYear
string
Example: requestYear=2021

Год, за который запрашивается справка

Responses

Response samples

Content type
application/json
{
  • "client_id": "client123",
  • "status": "success",
  • "data": {
    }
}

Получение сводной информацию по лицевому счету

Метод возвращает информацию по лицевому счету конкретного самозанятого за указанный период.

path Parameters
client_id
string
Example: client123

Идентификатор клиента

Responses

Response samples

Content type
application/json
{
  • "client_id": "client123",
  • "status": "success",
  • "data": {
    }
}

Получение статуса самозанятого на дату

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

path Parameters
client_id
string
Example: client1

Идентификатор клиента

yyyy-mm-dd
string
Example: 2023-11-12

Дата

Responses

Response samples

Content type
application/json
{
  • "client_id": "client123",
  • "status": "registered",
  • "description": "Success",
  • "details": {
    }
}

Работа с бенефициарами

Создание бенефициара

Метод позволяет создать бенефициара.
Партнер вызывает метод и передает необходимые данные в ответ получает идентификатор бенефициара. Для редактирования бенефициара с новыми данными используется метод "Редактирование бенефициара".
Используется в сценарии "Работа с бенефициарами".

Request Body schema: application/json
required
name
string

Название

inn
string

ИНН

is_blocked
boolean

Флаг блокировки

Responses

Request samples

Content type
application/json
{
  • "name": "ООО \"Рога и копыта\"",
  • "inn": "1234567890",
  • "is_blocked": false
}

Response samples

Content type
application/json
{
  • "id": "12345",
  • "inn": "1234567890",
  • "name": "ООО \"Рога и копыта\"",
  • "is_blocked": false,
  • "created_at": "2021-10-12T10:24:54+00:00"
}

Список бенефициаров

Метод возвращает список всех созданных ранее бенефициаров. Используется в сценарии "Работа с бенефициарами".

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Редактирование бенефициара

Метод позволяет отредактировать данные созданного ранее бенефициара. Используется в сценарии "Работа с бенефициарами".

path Parameters
beneficiary_id
string
Example: 017c7408-9fac-5822-d0f8-954c5f17a999

Идентификатор бенефициара

Request Body schema: application/json
required
name
string

Название

inn
string

ИНН

is_blocked
boolean

Флаг блокировки

Responses

Request samples

Content type
application/json
{
  • "name": "ООО \"Рога и копыта\"",
  • "inn": "1234567890",
  • "is_blocked": false
}

Response samples

Content type
application/json
{
  • "id": "12345",
  • "inn": "1234567890",
  • "name": "ООО \"Рога и копыта\"",
  • "is_blocked": false,
  • "created_at": "2021-10-12T10:24:54+00:00"
}

Получение данных о бенефициаре

Метод возвращает данные о созданном ранее бенефициара. Используется в сценарии "Работа с бенефициарами".

path Parameters
beneficiary_id
string
Example: 017c7408-9fac-5822-d0f8-954c5f17a999

Идентификатор бенефициара

Responses

Response samples

Content type
application/json
{
  • "id": "12345",
  • "inn": "1234567890",
  • "name": "ООО \"Рога и копыта\"",
  • "is_blocked": false,
  • "created_at": "2021-10-12T10:24:54+00:00",
  • "balance": 0,
  • "partner_commission_amount": 0,
  • "current_commission": null
}

Создание комиссии бенефициара

Метод позволяет записать комиссию бенефициара, которая будет списываться в пользу партнера при каждой операции. Изменить комиссию можно методом "Редактирование комиссии бенефициара". Удалить комиссию можно методом "Удаление комиссии бенефициара". Используется в сценарии "Работа с бенефициарами".

Поле operation может принимать одно из следующих значений:

  • order_to_external_card - для выплат на карту стороннего банка по номеру карты;
  • order_to_our_card - для выплат на карту TalkBank по barcode;
  • transfer - для переводов по реквизитам;
  • order_sbp - для выплат СБП.
path Parameters
beneficiary_id
string
Example: 017c7408-9fac-5822-d0f8-954c5f17a999

Идентификатор бенефициара

Request Body schema: application/json
required
will_start_at
string

Дата начала действия комиссии

operation
string

Тип операции

percentage
number

Процент комиссии

fixed_part
integer

Фиксированная часть комиссии, в копейках

minimum
integer

Минимальная комиссия, в копейках

Responses

Request samples

Content type
application/json
{
  • "will_start_at": "2021-10-12 13:24:54 Europe/Moscow",
  • "operation": "order_to_external_card",
  • "percentage": 2.5,
  • "fixed_part": 100,
  • "minimum": 3000
}

Response samples

Content type
application/json
{
  • "id": "017c7408-9fac-5822-d0f8-954c5f17a999",
  • "will_start_at": "2021-10-12 13:24:54 Europe/Moscow",
  • "operation": "order_to_external_card",
  • "percentage": 2.5,
  • "fixed_part": 100,
  • "minimum": 3000,
  • "created_at": "2021-10-12T10:24:54+00:00"
}

Список комиссий бенефициара

Метод возвращает список всех ранее установленных комиссий бенефициара. Используется в сценарии "Работа с бенефициарами".

Поле operation может принимать одно из следующих значений

  • order_to_external_card - для выплат на карту стороннего банка по номеру карты
  • order_to_our_card - для выплат на карту TalkBank по barcode
  • transfer - для переводов по реквизитам
  • order_sbp - для выплат СБП
path Parameters
beneficiary_id
string
Example: 017c7408-9fac-5822-d0f8-954c5f17a999

Идентификатор бенефициара

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Редактирование комиссии бенефициара

Метод позволяет изменить комиссию бенефициара, которая будет списываться в пользу партнера при каждой операции. Используется в сценарии "Работа с бенефициарами".

path Parameters
beneficiary_id
string
Example: 017c7408-9fac-5822-d0f8-954c5f17a999

Идентификатор бенефициара

commission_id
string
Example: 017c7408-9fac-5822-d0f8-954c5f17a966

Идентификатор комиссии бенефициара

Request Body schema: application/json
required
will_start_at
string

Дата начала действия комиссии

percentage
number

Процент комиссии

fixed_part
integer

Фиксированная часть комиссии, в копейках

minimum
integer

Минимальная комиссия, в копейках

Responses

Request samples

Content type
application/json
{
  • "will_start_at": "2021-10-12 13:24:54 Europe/Moscow",
  • "percentage": 2.5,
  • "fixed_part": 100,
  • "minimum": 3000
}

Response samples

Content type
application/json
{
  • "id": "017c7408-9fac-5822-d0f8-954c5f17a999",
  • "will_start_at": "2021-10-12 13:24:54 Europe/Moscow",
  • "percentage": 2.5,
  • "fixed_part": 100,
  • "minimum": 3000,
  • "created_at": "2021-10-12T10:24:54+00:00"
}

Удаление комиссии бенефициара

Метод позволяет удалить установленную ранее комиссию бенефициара. Используется в сценарии "Работа с бенефициарами".

path Parameters
beneficiary_id
string
Example: 017c7408-9fac-5822-d0f8-954c5f17a999

Идентификатор бенефициара

commission_id
string
Example: 017c7408-9fac-5822-d0f8-954c5f17a966

Идентификатор комиссии бенефициара

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Корректировка баланса бенефициара

Метод позволяет корректировать баланс бенефициара.

path Parameters
beneficiary_id
string
Example: 017c7408-9fac-5822-d0f8-954c5f17a999

Идентификатор бенефициара

Request Body schema: application/json
required
amount
integer

Сумма корректировки (коп)

Responses

Request samples

Content type
application/json
{
  • "amount": -200
}

Response samples

Content type
application/json
{
  • "id": "017c7408-9fac-5822-d0f8-954c5f17a999",
  • "inn": "1234567890",
  • "name": "ООО \"Рога и копыта\"",
  • "is_blocked": false,
  • "created_at": "2021-10-12T10:24:54+00:00",
  • "balance": 0
}

Подписки на события

Оформление подписки

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

Партнер вызывает метод и передает необходимые данные. В методе передается URL и массив с информацией о выбранных событиях.
Если на указанный URL событие не получилось доставить с первого раза (система партнера вернула ошибку), то TalkBank повторяет попытки доставки еще несколько раз:

  • во второй раз: через 1 секунду;
  • в третий раз: через 1 минуту;
  • в четвертый раз: через 1 час;
  • в пятый раз: через 2,5 суток.

Удалить подписку на событие можно методом "Удаление подписки на событие".

Нотификация о расходах (notifications)

Уведомление приходит при расходах с карты конкретного клиента.

Изменение статуса доставки (delivery)

Уведомление приходит при изменении статуса доставки. Альтернативой подписки может быть метод "Получение статуса доставки".

Изменение статуса идентификации (identification)

Уведомление приходит при изменении статуса идентификации. Альтернативой подписки может быть метод "Получение статуса клиента".

Изменение статуса активации (activation)

Уведомление приходит при изменении статуса активации карты. Альтернативой подписки может быть метод "Получение статуса активации карты".

Изменение статуса банковского ордера (order)

Уведомление приходит при изменении статуса платежа. Альтернативой подписки может быть метод "Получение статуса платежа".

Изменение статуса трансфера (transfer)

Уведомление приходит при изменении статуса платежа по реквизитам счета. Альтернативой подписки может быть метод "Получение статуса перевода по реквизитам".

Изменение статуса регистрации самозанятого (selfemployments)

Уведомление приходит при изменении статуса самозанятого.

Нотификация о регистрации дохода самозанятого (income)

Уведомление приходит при регистрации дохода самозанятого.

Нотификация о поступлении по реквизитам на счет - пополнение/возврат (bank_refill)

Уведомление приходит при поступлении денежных средств на счет. Если денежные средства пришли по причине возврата по выплате, то в описании указывается, что это - возврат средств, номер платежного поручения и причина возврата.
Если денежные средства пришли по причине пополнения счета, то в уведомлении приходит информация о заказчике и сумма.

Нотификация об уплате налога (tax)

Уведомление приходит при оплате налога за самозанятого. Указывается статус оплаты и сумма.

Регистрация СМЗ (register)

Уведомление приходит при регистрации самозанятого.

Request Body schema: application/json
required
url
string

Адрес, куда будут уходить события

events
Array of strings

Множество типов событий. Пустой массив или отсутствующее значение параметра - означает все типы

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "enabled": [],
  • "available": [
    ]
}

Получение списка подписок

Метод возвращает список событий и URL, на которые оформлена подписка.

Нотификация о расходах

{
  "type": "payment.notification",
  "data": {
    "partner": "04b92d9f-a944-365c-9919-64539ee33b04",
    "partner_id": 134,
    "client_id": "27d0b46d-b120-4e72-92c5-3de0b588fccc",
    "date": "14_октября_2020",
    "amount": 50000,
    "card_number": "6678",
    "merchant": "3DI_QWB",
    "place": "643 Москва",
    "transaction_type": "Расход",
    "mcc": 6051,
    "category": "Финансы",
    "child_category": "Прочие_финансовые_операции",
    "balance": 147000,
    "is_cancel": false,
    "currency": "RUB",
    "currency_code": "₽",
    "currency_amount": 50000,
    "ean": 2000005459764,
    "ref_number": "028812975349",
    "merchant_name": "3DI QWB",
    "merchant_id": "26798502",
    "terminal_id": "26798502",
    "card_amount": 50000,
    "datetime": "2020-10-14T15:06:45+03:00"},
    "timestamp": "2020-10-14T15:06:47+03:00"
}

Расшифровка полей нотификации

Поле ответа Описание поля
amount Сумма в валюте списания
date Дата операции
card_number Номер карты (маскированный)
city Город (если есть)
country Страна (если есть)
address Адрес (если есть)
type Тип операции (Расход, Перевод, Снятие, Пополнение, Возврат)
online Онлайн покупка (POS терминал)
merchant_name Имя мерчанта
merchant_id ID мерчанта
terminal_id ID терминала
barcode Баркод карты
currency Валюта списания (в формате ISO)
mcc mcc код
is_error Наличие ошибки, boolean
error_description Описание ошибки
balance Баланс карты (опционально)
card_amount Сумма в валюте карты (RUB)
ref_number RefNumber (не гарантируется уникальность)
resp_code resp_code, расшифровка ниже

Варианты resp_code

resp_code Описание
0 Операция одобрена
4 Неверные данные карты
5 Перевод не прошел
31 Истек срок действия карты
41 Карта потеряна
43 Карта украдена
51 Недостаточно средств
55 Неправильный PIN-код
57 Ограничение действий по счету
61 Количество попыток исчерпано
68 Время ожидания истекло
75 Превышены попытки ввода неправильного PIN-кода
71 Недостаточно лимитов
81 Ошибка при ввода CVV и/или срока действия карты
91 Сервис недоступен
92 Некорректные реквизиты для оплаты
93 Сервис заблокирован
96 Карта заблокирована по причине неправильного ввода PIN-кода
97 Операции по карте недоступны

Изменение статуса доставки

    {
       "type": "delivery",
       "data" {
         "client_id": "47",
         "delivery_id": 2323,
         "delivery_status_code": 1,
         "delivery_status_description": "ожидание оплаты"
       }
    }
Поле ответа Описание поля
client_id Код клиента
delivery_id Код доставки
delivery_status_code Статус доставки (статусы описаны в методе получения статуса доставки)
delivery_status_description Описание статуса доставки

Изменение статуса идентификации

Ответ при статусе success

   {
       "type": "identification.success",
       "data" {
         "client_id": "47"
       }
   }

Ответ при статусе error


   {
     "type": "identification.error",
     "data": {
       "client_id": "47",
       "message": "passport: doc_status = 302: сведениями по заданным реквизитам не располагаем",
       "additional": {
         "passport": {
           "status": "NotValid",
           "description": "DOC_STATUS = 302: Сведениями по заданным реквизитам не располагаем"
         },
         "inn": {
           "status": "Processing",
           "description": "В обработке"
         },
         "snils": {
           "status": "NotProcessed",
           "description": "Не указан СНИЛС, проверка не производилась"
         }
       }
     }
   }

Изменение статуса активации

Ответ при статусе success

   {
       "type" : "activation.success",
       "data" : {
           "partner" : "bbbb7320-7255-3c4c-ad16-9446dfe62cc1",
           "partner_id" : 81,
           "client_id" : "79172758",
           "barcode" : "2000007141360"
       },
       "timestamp" : "2020-10-07T17:13:04+03:00"
   }

Ответ при статусе error


   {
       "type" : "activation.error",
       "data" : {
           "partner" : "bbbb7320-7255-3c4c-ad16-9446dfe62cc1",
           "partner_id" : 81,
           "client_id" : "79182670",
           "barcode" : ""
       },
       "timestamp" : "2020-10-07T11:46:50+03:00"
   }

Изменение статуса банковского ордера

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


    {
      "type": "order",
      "data" {
        "order_id": 1,
        "order_slug": "payment.xxxx",
        "status": "success",
        "is_completed": true,
        "amount": 3000,
        "card_number": "4314********8781",
        "state_code": 10,
        "state_description": "Недостаточно средств"
      }
    }

Изменение статуса трансфера

При изменении трансфера получаем ту же структуру, что и при запросе аналогичных методов.


  {
    "type": "transfer",
    "data": {
      "completed": true,
      "status": "success",
      "order_slug": "transfer_xxxx",
      "talkbank_commission": 2500,
      "beneficiary_partner_commission": null
    }
  }

Изменение статуса регистрации самозанятого

    {
        "type": "selfemployed_status.unbind",
        "data": {
          "client_id": "04527b0c-3c1a-459d-8134-2b4e1359ea95",
          "event": "unbind",
          "status": "completed"
        },
        "timestamp": "2021-07-23T01:35:28+03:00"
    }

Структура

Поле Описание Примечание
type тип события состоит из selfemployed_status. , где - тип операции
data данные по событию включает в себя поля
- client_id
- event
- status
- details
Возможные значения поля event
- register
- unregister
- bind
- unbind
Возможные значения поля status
- completed
- failed
Поле details присутствует при событии register в статусе failed и может содержать поля
- rejection_code
- rejection_description
timestamp дата/время события

Пример сообщения при успешной регистрации самозанятого

     {
        "type": "selfemployed_status.register",
        "data": {
          "client_id": "21fc5216-a6cf-4098-92ce-94a7d7fe3367",
          "event": "register",
          "status": "completed"
        },
        "timestamp": "2021-07-23T17:54:07+03:00"
    }

Пример сообщения при неуспешной регистрации самозанятого

    {
        "type": "selfemployed_status.register",
        "data": {
          "client_id": "82ab57c9-47b2-44d6-b7c6-758a2cc0a9a3",
          "event": "register",
          "status": "failed" 
          "details": {
             "rejection_code": "NOT_IDENTIFYED",
             "rejection_description": "По Вашим паспортным данным не найден ИНН. Если Вы знаете свой ИНН, попробуйте зарегистрироваться, с использованием ИНН и пароля от  ЛК физического лица. Если у Вас нет ИНН, Вам необходимо обратиться в любой налоговый орган, обслуживающий физических лиц, для получения ИНН."
          }
        }
        "timestamp": "2021-05-20T12:24:01+03:00"
    }

Список всех причин для отказа в регистрации самозанятого от ФНС (rejection_code)

Код Описание Текст по умолчанию
REGISTERED ФЛ состоит на учете в налоговом органе в качестве НП НПД «Физическое лицо уже поставлено на учет в налоговом органе в качестве налогоплательщика налога на профессиональный доход. Повторная постановка на учет не требуется»
INCOME_OVERFLOW Пользователь был зарегистрирован, превысил лимит дохода в текущем календарном году (2 400 000 руб.), снялся с учета и пытается встать на учет повторно «Доход за текущий календарный год достиг допустимого порога в %s миллиона рублей. Вы не можете встать на учёт»
DEBTS_FOUND у ФЛ имеется задолженность. «За Вами числится задолженность. Чтобы стать налогоплательщиком налога на профессиональный доход необходимо ее погасить»
REGISTRATION_RESTRICTED в системе НПД имеется информация от Партнеров или налоговых органов, что у ФЛ есть ограничения на постановку на учет в качестве плательщика НПД. «Постановка на учет в налоговом органе в качестве налогоплательщика налога на профессиональный доход невозможна, так как имеются ограничения на постановку»;
NOT_IDENTIFIED ФЛ не идентифицировано «По Вашим паспортным данным ИНН не найден. Если Вы знаете свой ИНН, попробуйте зарегистрироваться с использованием логина (ИНН) и пароля доступа к личному кабинету налогоплательщика. Если у Вас нет ИНН, Вам необходимо обратиться в любой налоговый орган, к функциям которого относится взаимодействие с физическими лицами, для получения ИНН»;
NOT_FULLY_IDENTIFIED ФЛ идентифицировано неоднозначно «По Вашим данным выявлены несоответствия, налоговому органу необходимо провести уточняющие мероприятия. Пожалуйста, повторите попытку регистрации через 6 дней. Если через 6 дней зарегистрироваться не получится, обратитесь, пожалуйста, в службу технической поддержки»
TAXPAYER_DIED у лица заполнена дата смерти «По Вашим данным выявлены несоответствия, налоговому органу необходимо провести уточняющие мероприятия. Пожалуйста, повторите попытку регистрации через 6 дней. Если через 6 дней зарегистрироваться не получится, обратитесь, пожалуйста, в службу технической поддержки»
NO_RESIDENCY у лица нет действующей постановки «Ошибка при постановке на учет: Отсутствуют данные о постановке на учет в налоговом органе по месту жительства. Для постановки на учет по месту жительства обратитесь, пожалуйста, в любой налоговый орган, к функциям которого относится взаимодействие с физическими лицами, после чего необходимо повторить попытку регистрации»
INVALID_CITIZENSHIP гражданство ФЛ не соответствует допустимому значению. «Выявлено несоответствие документов (данных), представленных физическим лицом, сведениям, имеющимся у налогового органа. По данным налогового органа физическое лицо не является гражданином Российской Федерации или других государств – членов Евразийского экономического союза»
RESTRICTED_OCCUPATION ФЛ состоит на учете в качестве арбитражного управляющего, медиатора, оценщика, нотариуса, адвоката, лица, являющегося участником договора простого товарищества «Отказ в постановке на учет в качестве налогоплательщика налога на профессиональный доход – выявлено, что документы (данные) представлены физическим лицом в нарушение требований, установленных пунктом 2 статьи 4 Федерального закона, а именно: физическое лицо состоит на учете в налоговом органе в качестве арбитражного управляющего, медиатора, оценщика, нотариуса, адвоката, участника договора простого товарищества, в ЕГРН есть такие сведения»;
IE_RESTRICTED_TAX_MODE ФЛ состоит на учете в налоговом органе в качестве ИП с применением специальных налоговых режимов (ПСН, ЕНВД, СРП, УСН, ЕСХН) «Отказ в постановке на учет в качестве налогоплательщика налога на профессиональный доход – выявлено, что документы (данные) представлены физическим лицом в нарушение требований, установленных пунктом 2 статьи 4 Федерального закона от 27.11.2018 № 422-ФЗ, а именно: физическое лицо состоит на учете в налоговом органе в качестве индивидуального предпринимателя, применяющего специальный режим налогообложения (УСН/ПСН/ЕНВД/СРП/ЕСХН).
UNKNOWN любая другая/неизвестная ошибка «При постановке на учет возникли технические проблемы. Пожалуйста, повторите попытку постановки на учет позже или обратитесь, в службу технической поддержки».

Нотификации о регистрации доходов самозанятого

Ответ при статусе sent

    {
      "type": "income.income_register",
      "data": {
        "client_id": "540860935007",
        "event": "income_register",
        "id": 700154,
        "status": "sent",
        "receipt_id": "201h7x4z2r",
        "link": "https://lknpd.nalog.ru/api/v1/receipt/637401428296/201h7x4z2r/print"
      },
      "timestamp": "2022-01-14T08:04:03 00:00"
    }

Ответ при статусе failed

    {
      "type": "income.income_register",
      "data": {
        "client_id": "540860935007",
        "event": "income_register",
        "id": 700155,
        "status": "failed",
        "errors": {
          "DUPLICATE": "Внесение полного дубликата чека невозможно"
        }
      },
      "timestamp": "2022-01-14T09:49:15 00:00"
    }

Расшифровка полей

Параметры Описание поля
client_id Идентификатор клиента
id Идентификатор чека в БД
receipt_id Идентификатор чека в ФНС
data Объект
status Статус запроса: sent или failed
errors В случае, если status = ‘error’, то поле description будет содержать описание ошибки (ошибок)
event Событие
receipt_id Идентификатор чека в ФНС
link Ссылка на чек
timestamp Время печати чека

Нотификации о поступлении по реквизитам на счет (пополнение/возврат)

Нотификация по возврату


  {
    "type": "bank_refill",
    "data": {
      "id": "56882730-4fee-4c07-859d-8e55bbc2cb8a",
      "amount": 1234585,
      "sender_name": "ПАО СБЕРБАНК",
      "sender_inn": "7707083893",
      "description": "Возврат по ПП No 12345 от 12/03/2022. По указанным реквизитам зачисление невозможно",
      "refund_transfer": {
        "completed": true,
        "status": "success",
        "order_slug": "order_id_123",
        "talkbank_commission": 123,
        "beneficiary_partner_commission": 123
      }
    },
    "timestamp": "2022-03-23T01:23:45+03:00"
  }

Нотификация по пополнению


  {
     "type": "bank_refill",
     "data": {
       "id": "56882730-4fee-4c07-859d-8e55bbc2cb8b",
       "amount": 12345685,
       "sender_name": "ООО \"Новая эра\"",
       "sender_inn": "7712345678",
       "description": "Без налога (НДС)",
       "refund_transfer": null
     },
   "timestamp": "2022-03-24T01:23:45+03:00"
 }

Нотификации об уплате налога

    {
        "type": "tax",
        "data": {
          "case_name": "payment_low_rate",
          "return_amount": 14512,
          "tax_amount": 71575,
          "date": "2022-06-12T10:20:05+03:00",
          "client_id": "fa712bd5-4809-4cf6-ba91-60f03bcabea8",
          "notify_type": "tax"
        },
        "timestamp": "2022-06-12T01:23:45+03:00"
      }

Возможные статусы по исполнителю (поле case_name тела запроса)

Статус Описание
payment_low_rate 1.1 Платим налог в ФНС/Остаток на карту
payment_with_fines 1.2 Платим задолженность и пени в ФНС/Остаток на карту
return_no_permission 2. Нет прав на выплату/Платим остаток баланса на карту
return_deregister 3. Исполнитель снялся с учета/ Платим остаток баланса на карту
no_return_low_balance 4.1 Переплата в прошлом месяце/Недостаточно средств для уплаты налога/Баланс исполнителя отрицательный
return_low_balance 4.2 Переплата в прошлом месяце/Недостаточно средств для уплаты налога/Платим остаток на карту
no_payment_no_tax 4.3 Переплата в прошлом месяце/Обязательств перед ФНС нет/Ничего не платим
return_extra_fines 5. В предыдущем месяце не было выплаты дохода исполнителю/незакрытый остаток/Остаток на карту
return_already_payed 6. Обязательства перед ФНС погашены исполнителем/Остаток на карту
return_has_extra_taxes 7.1 Платим остаток на карту/Сторонние доходы
return_self_payment 7.2 Платим остаток на карту/ Ранее выплата удержаний осуществлялась на карту для самостоятельного погашения обязательств перед ФНС
return_doubles 7.3 Платим остаток на карту/Задублированный чек
return_canceled 8. Исполнитель отменил чеки/Остаток баланса на карту

Общий список кодов отказов

Код Описание
REGISTERED По данным налогового органа физическое лицо является действующим налогоплательщиком налога на профессиональную деятельность. Повторная постановка на учет не требуется
INCOME_OVERFLOW Доход за текущий календарный год достиг допустимого порога в 2.4 миллиона рублей. Вы не можете встать на учёт.
REGISTRATION_RESTRICTED В платформе имеется информация от партнеров или налоговых органов, что НП НПД не разрешено вставать на учет как плательщику НПД
NOT_IDENTIFIED По Вашим паспортным данным не найден ИНН. Если Вы знаете свой ИНН, попробуйте зарегистрироваться, с использованием ИНН и пароля от ЛК физического лица. Если у Вас нет ИНН, Вам необходимо обратиться в любой налоговый орган, обслуживающий физических лиц, для получения ИНН.
NOT_FULLY_IDENTIFIED По Вашим данным выявлены несоответствия, налоговому органу необходимо провести уточняющие мероприятия. Пожалуйста, повторите попытку регистрации через 6 дней. Если через 6 дней зарегистрироваться не получится, обратитесь, пожалуйста, в службу технической поддержки.
TAXPAYER_DIED По Вашим данным выявлены несоответствия, налоговому органу необходимо провести уточняющие мероприятия. Пожалуйста, повторите попытку регистрации через 6 дней. Если через 6 дней зарегистрироваться не получится, обратитесь, пожалуйста, в службу технической поддержки.
NO_RESIDENCY Отсутствуют данные о постановке на учет в налоговом органе по месту жительства. Для постановки на учет по месту жительства обратитесь, пожалуйста, в любой налоговый орган, к функциям которого относится взаимодействие с физическими лицами, после чего необходимо повторить попытку регистрации.
INVALID_CITIZENSHIP Выявлено несоответствие документов (данных), представленных физическим лицом, сведениям, имеющимся у налогового органа, по данным налогового органа физическое лицо не является гражданином Российской Федерации или государств – членов Евразийского экономического союза
RESTRICTED_OCCUPATION Отказ в постановке на учет в качестве налогоплательщика налога на профессиональный доход – выявлено, что документы (данные) представлены физическим лицом в нарушение требований, установленных пунктом 2 статьи 4 Федерального закона …, а именно: физическое лицо состоит на учете в налоговом органе в качестве арбитражного управляющего/медиатора/оценщика/нотариуса/адвоката/участника договора простого товарищества – в ЕГРН есть такие сведения?
IE_RESTRICTED_TAX_MODE Отказ в постановке на учет в качестве налогоплательщика налога на профессиональный доход – выявлено, что документы (данные) представлены физическим лицом в нарушение требований, установленных пунктом 2 статьи 4 Федерального закона …, а именно: физическое лицо состоит на учете в налоговом органе в качестве индивидуального предпринимателя, применяющего специальный режим налогообложения (УСН/ПСН/ЕНВД/СРП/ЕСХН)

Responses

Response samples

Content type
application/json
{
  • "enabled": [],
  • "available": [
    ]
}

Удаление подписки на событие

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

path Parameters
subscription_id
integer
Example: 1234

Идентификатор подписки

Responses

Response samples

Content type
application/json
{
  • "enabled": [],
  • "available": [
    ]
}

Трансграничные переводы

Перевод с российской на иностранную карту

Метод позволяет осуществить перевод с российской карты на иностранную.

  1. Партнер вызывает метод и передает необходимые данные.
  2. Статус операции можно получить методом "Получение статуса перевода card2card" или оформив подписку на событие order. Обработка операции занимает 1-2 минуты.
Request Body schema: application/json
required
order_id
string

Уникальный идентификатор операции

documents
Array of strings

Массив уникальных идентификаторов документов отправителя

pan
string

Номер карты получателя

accepted_currency
string

Валюта внесения

object
amount
integer

Сумма

withdraw_currency
string

Валюта зачисления

description
string

Описание платежа

Responses

Request samples

Content type
application/json
{
  • "order_id": "514ba43c-6978-41e7-9204-861024316390",
  • "documents": [
    ],
  • "pan": "4276740013641221",
  • "accepted_currency": "RUB",
  • "beneficiary": {
    },
  • "amount": 100,
  • "withdraw_currency": "EUR",
  • "description": "Перевод личных средств"
}

Response samples

Content type
application/json
{
  • "order_id": "514ba43c-6978-41e7-9204-861024316390",
  • "status": "new"
}

Перевод с российской карты с выдачей наличных средств за рубежом

Метод используется для перевода на иностранные карты с возможностью получить наличные. Узнать список стран, в которых можно получить наличные, можно по методу "Получение списка стран для получения средств".
1. Партнер вызывает метод и передает необходимые данные.
2. Статус операции можно получить методом "Получение статуса перевода card2card" или оформив подписку на событие order. Обработка операции занимает 1-2 минуты.

Request Body schema: application/json
required
order_id
string

Уникальный идентификатор операции

documents
Array of strings

Массив уникальных идентификаторов документов отправителя

to_country_code
string

Код страны получения

accepted_currency
string

Валюта внесения

object
amount
integer

Сумма

withdraw_currency
string

Валюта зачисления

description
string

Описание платежа

amount_type
string

Тип суммы

Responses

Request samples

Content type
application/json
{
  • "order_id": "514ba43c-6978-41e7-9204-861024316390",
  • "documents": [
    ],
  • "to_country_code": "PRT",
  • "accepted_currency": "RUB",
  • "beneficiary": {
    },
  • "amount": 100,
  • "withdraw_currency": "EUR",
  • "description": "Перевод личных средств",
  • "amount_type": "withdraw"
}

Response samples

Content type
application/json
{
  • "order_id": "514ba43c-6978-41e7-9204-861024316390",
  • "status": "new"
}

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

Используется для метода "Перевод с российской карты с выдачей наличных средств за рубежом". Возвращает список стран, в которых можно получить наличные.
Список стран: Великобритания, Греция, Израиль, Италия, Кипр, Сербия.

Responses

Response samples

Content type
application/json
[
  • {
    }
]