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

Обновлено 29 ноября 2024

Компаниям

Холдингам

Платформам

/fintech/api/v1/payments/{externalId}/state

Ресурс позволяет вам получить статус ранее сформированного черновика платежного поручения. В случае, если у Клиента отключена/истек срок соглашения услуги на формирование платежных поручений, вы все равно сможете получить статус готовых документов.

Для получения статуса необходимо отправить GET-запрос /fintech/api/v1/payments/{externalId}/state с токеном доступа (access_token) пользователя в параметре Authorization заголовка и идентификатор документа (externalId) в querry-параметре запроса.

В параметре scope ссылки авторизации пользователя для получения доступа к этому запросу должен быть указан один из сервисов:

• PAY_DOC_RU
• PAY_DOC_RU_INVOICE
• PAY_DOC_RU_INVOICE_ANY
• PAY_DOC_RU_INVOICE_BUDGET

Для обращения к ресурсу необходимо отправлять запрос на:

• Тестовый контур https://iftfintech.testsbi.sberbank.ru:9443
• Промышленный контур https://fintech.sberbank.ru:9443

Request

/fintech/api/v1/payments/{externalId}/state

• Модель
• Пример

Наименование	Тип	Формат	Regexp	Обязательность	Описание
HEADER
Authorization	string	string	^[a-zA-Z0-9]{38}$	required	Access token пользователя, полученный через SSO.
Accept	string	string	^(application/json|application/jose)	optional	Указывает на формат данных, который вы готовы принять от Банка. - Если ответ не требуется в зашифрованном виде, то может быть не указан или передан со значением application/json. - Если необходимо получить ответ на запрос токена в зашифрованном виде, то необходимо передать параметр со значением application/jose.
PATH PARAMETERS
externalId	string	UUID	^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$	required	Идентификатор документа, присвоенный вами при создании документа

GET /fintech/api/v1/payments/6a54593d-464b-4c8e-a7e2-742a05e5c241/state HTTP/1.1
Authorization: Bearer xbgDF3brf456ghi789jkl012mNKFtEpqr678
Accept: */*

Responses

200 (ОК)

• Модель
• Пример

Наименование	Тип	Обязательность	Описание
Payment {
amount	number	required	Сумма платежа,
bankComment	string	optional	Банковский комментарий к статусу документа,
bankStatus	string	optional	Статус документа,
crucialFieldsHash	string	optional	Hash от ключевых полей документа,
date	string	required	Дата составления документа,
deliveryKind	string	optional	Вид платежа,
departmentalInfo	DepartmentalInfo	optional	Реквизиты налогового, таможенного или иного бюджетного платежа,
digestSignatures	array[Signature]	optional	Электронные подписи по дайджесту документа,
externalId	string	required	Идентификатор документа, присвоенный партнером,
incomeTypeCode	string	optional	Код вида дохода получателей выплаты по 229-ФЗ,
number	string	optional	Номер документа,
operationCode	string	required	Код операции,
payeeAccount	string	optional	Счет получателя платежа,
payeeBankBic	string	required	БИК получателя платежа,
payeeBankCorrAccount	string	optional	Корсчет банка получателя платежа,
payeeInn	string	optional	ИНН получателя платежа,
payeeKpp	string	optional	КПП получателя платежа,
payeeName	string	required	Полное наименование получателя платежа,
payerAccount	string	required	Счет плательщика,
payerBankBic	string	required	БИК банка плательщика,
payerBankCorrAccount	string	required	Корсчет банка плательщика,
payerInn	string	required	ИНН плательщика,
payerKpp	string	optional	КПП плательщика,
payerName	string	required	Полное наименование плательщика,
priority	string	required	Очередность платежа,
purpose	string	required	Назначение платежа,
urgencyCode	string	optional	Код срочности,
vat	vat	optional	Данные НДС,
voCode	string	optional	Код вида валютной операции
}
DepartmentalInfo {
uip	string	required	Уникальный идентификатор платежа,
drawerStatus101	string	required	Показатель статуса налогоплательщика (реквизит - 101),
kbk	string	required	Код бюджетной классификации (реквизит - 104),
oktmo	string	required	Код OKTMO (реквизит - 105),
reasonCode106	string	required	Показатель основания платежа (реквизит - 106),
taxPeriod107	string	required	Налоговый период / код таможенного органа (реквизит - 107),
docNumber108	string	required	Номер налогового документа (реквизит - 108),
docDate109	string	required	Дата налогового документа (реквизит - 109),
paymentKind110	string	optional	Тип налогового платежа (реквизит - 110)
}
Signature {
base64Encoded	string	required	Значение электронной подписи, закодированное в Base64,
certificateUuid	string	required	Уникальный идентификатор сертификата ключа проверки электронной подписи (UUID),
}
Vat {
amount	number	optional	Сумма НДС,
rate	string	optional	Ставка НДС,
type	string	required	Способ расчета НДС
}

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
 
{
    "number": "1",
    "date": "2023-11-15",
    "digestSignatures": [],
    "bankStatus": "CREATED",
    "bankComment": null,
    "externalId": "6a54593d-464b-4c8e-a7e2-742a05e5c241",
    "amount": "100.00",
    "operationCode": "01",
    "deliveryKind": "электронно",
    "priority": "5",
    "urgencyCode": "NORMAL",
    "voCode": null,
    "purpose": "Оплата заказа №123. НДС 20%",
    "departmentalInfo": null,
    "payerName": "ООО_Автотест_Клиент_ЕКС_20231027092414",
    "payerInn": "6376615662",
    "payerKpp": "702701625",
    "payerAccount": "40702810506000002149",
    "payerBankBic": "048073601",
    "payerBankCorrAccount": "30101810300000000601",
    "payeeName": "ТЕСТ9036",
    "payeeInn": "7379190522",
    "payeeKpp": "683801910",
    "payeeAccount": "40702810006000001792",
    "payeeBankBic": "048073601",
    "payeeBankCorrAccount": "30101810300000000601",
    "crucialFieldsHash": null,
    "vat": {
        "type": "INCLUDED",
        "rate": "20",
        "amount": "20.00"
    },
    "incomeTypeCode": null
}

400 (Bad request)

Cause	Message	Description
DESERIALIZATION_FAULT	Неверный формат запроса	Данные в request указаны в неправильном формате. Атрибуты request, в которых найдены ошибки, указаны в responce в массиве fields с описанием проблемы. Описание типа, формата и regexp атрибутов находится в request запроса. Скорректируйте заполнение атрибутов и повторите запрос.
VALIDATION_FAULT	Ошибка валидации	Данные не соответствуют требованиям валидации. Сведения о некорректных атрибутах request содержатся в массивах fieldNames и checks. Подробные требования к атрибутам описаны в request запроса, включая типы, форматы и регулярные выражения. Необходимо скорректировать заполнение атрибутов и повторить запрос.

• Модель
• Пример

Наименование	Тип	Обязательность	Описание
ResourceFault {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
checks	array[Check]	optional	Список проверок, приведших к ошибке,
fieldNames	array[string]	optional	Названия полей с некорректным значением (только для VALIDATION_FAULT)
}
Check {
level	string	optional	Уровень результата = ['ERROR', 'WARNING'],
message	string	optional	Сообщение,
fields	array[string]	optional	Названия полей (при наличии связи с моделью)
}

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
  
{
    "cause": "VALIDATION_FAULT",
    "referenceId": "0d6a80ba-7d35-4858-8443-9a77039ad9f1",
    "message": "Параметр \"externalId\" не соответствует регулярному выражению: [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}",
    "checks": [],
    "fieldNames": null
}

401 (Unauthorized Error)

Cause	Message	Description
UNAUTHORIZED	accessToken not found by value =хххххххх-хххх-хххх-хххх-хххххххххххх-х	Указан некорректный или просроченный access_token. Используйте refresh_token для обновления access_token и повторите запрос.

• Модель
• Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
 
{
    "cause": "UNAUTHORIZED",
    "referenceId": "014ec3a1-3e41-4805-9e22-d07947b012af",
    "message": "accessToken not found by value = 3513f959-bbd5-490a-9f9f-67fb7380fae5-2"
}

403 (Forbidden)

Cause	Message	Description
ACTION_ACCESS_EXCEPTION	Операция не может быть выполнена: доступ к ресурсу запрещен	Используемый в запросе access_token не имеет разрешения на доступ к нужному сервису Sber API. В ссылке авторизации СберБизнес ID, в параметре scope, не указана ни одна из операций по работе с платежными поручениями (PAY_DOC_RU, PAY_DOC_RU_INVOICE, PAY_DOC_RU_INVOICE_ANY или PAY_DOC_RU_INVOICE_BUDGET). Необходимо добавить одному или несколько операций в scope. Пользователю потребуется пройти авторизацию заново. Вы получите новые токены access_token и refresh_token. Сделайте повторный запрос с новым access_token.

• Модель
• Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
 
{
    "cause": "ACTION_ACCESS_EXCEPTION",
    "referenceId": "7535c2bb-7706-4b16-9882-d68aedbf2fef",
    "message": "Операция не может быть выполнена: доступ к ресурсу запрещен"
}

404 (Not found)

Cause	Message	Description
NOT_FOUND	Документ с указанным ID не найден

• Модель
• Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
  
{
    "cause": "NOT_FOUND",
    "referenceId": "1bd1b8b9-1bd3-4159-9909-d30536211114",
    "message": "Документ с указанным ID не найден"
}

429 (Too Many Requests)

Cause	Message	Description
TOO_MANY_REQUESTS	Превышен лимит запросов. Повторите операцию позже.	Количество запросов к данному методу за ограниченное время превысило допустимое значение. Пользователю необходимо повторить запрос позднее

• Модель
• Пример

Наименование	Тип	Обязательность	Описание
Notice{
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

json HTTP/1.1 429 Too Many Requests Content-Type: application/json;charset=UTF-8

{ "cause": " TOO_MANY_REQUESTS ", "referenceId": "5650c1e4-5039-4038-8cad-afab64003f61", "message": " Превышен лимит запросов. Повторите операцию позже" }

500 (Internal Server Error)

Cause	Message	Description
UNKNOWN_EXCEPTION	Внутренняя ошибка сервера	Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.

• Модель
• Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
 
{
  "cause": "UNKNOWN_EXCEPTION",
  "referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a65d",
  "message": "Внутренняя ошибка сервера"
}

503 (Service Temporarily Unavailable)

Cause	Message	Description
UNAVAILABLE_RESOURCE_EXCEPTION	Внутренняя ошибка сервера	Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.

• Модель
• Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 503 Service Temporarily Unavailable
Content-Type: application/json;charset=UTF-8
 
{
  "cause": "UNAVAILABLE_RESOURCE_EXCEPTION",
  "referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a67d",
  "message": "Внутренняя ошибка сервера"
}

Статусы платежных поручений

bankStatus (string)

Код состояние документа	Наименование статуса	Назначение кода состояния
Промежуточный/Продолжать опрашивать
ACCEPTED	Принят	Электронный документ принят на стороне Банка
ACCEPTED_BY_ABS	Принят АБС или Принят	Электронный документ был принят к обработке в АБС Банка
CARD2	Картотека 2 или Ожидает оплаты	АБС обнаружено, что на счете плательщика недостаточно средств для иcполнения документа
CREATED	Создан	Документ записан в БД, проверки не выполнялись
CHECKERROR	Ошибка контроля	ЭД сформирован, но при сохранении не прошел проверку корректности заполнения полей и сохранен с имеющимися в нем ошибками
DELAYED	Приостановлен	Обработка электронного документа была приостановлена
DELIVERED	Доставлен	Запрос доставлен в ДБО и взят в обработку
DELIVERED_RZK	Доставлен в СБК	Электронный документ отправлен в СБК и получен квиток о доставке
FRAUDALLOW	Одобрен ФРОД	Проверка во ФРОДЕ прошла успешно, переход на «Принят»
FRAUDREVIEW	На проверке у специалиста Банка	Со стороны ФРОД-анализа получен статус документа «На проверке у специалиста Банка»
FRAUDSENT	Отправлен во ФРОД	Документ отправлен на проверку в АС Fraud-мониторинг
FRAUDSMS	Требуется подтверждение sms-паролем	Со стороны ФРОД-анализа получен статус документа «Требуется подтверждение sms-паролем»
NOT_ACCEPTED_RZK	Не принят СБК	Электронный документ не прошел логические контроли СБК
PARTSIGNED	Частично подписан	ЭД подписан частью подписей, входящих в предусмотренный для данного документа комплект подписей
PROCESSING_RZK	Обрабатывается СБК	ЭД успешно прошел проверки ЭП и логические проверки СБК
REQUESTED_RECALL	Запрошен отзыв	Документ отозван
RZK_SIGN_ERROR	Ошибка ЭП СБК	Проверка подписи под ЭД на стороне СБК дала отрицательный результат
SENDING_TO_RZK	Отправляется в СБК	Электронный документ отправлен в СБК, но не получен квиток о доставке
SIGNED	Подписан	ЭД подписан предусмотренным для него комплектом подписей.
TO_PROCESSING_RZK	К отправке в СБК	ЭД подписан предусмотренным для него комплектом о доставке
Окончательный (Не успешный)/Прекратить опрос
DELETED	Удален	Электронный документа удален из числа действующих документов
INVALIDEDS	ЭП/АСП не верна Подпись неверна	Проверка ЭП под ЭД на стороне Банка дала отрицательный результат
RECALL	Отозван	Электронный документ был отозван Клиентом по запросу
REFUSEDBYBANK	Отвергнут банком или Отклонен банком	Электронный документ отвергнут банком
REFUSEDBYABS	Отказан АБС	Электронный документ не прошел проверки в АБС
REQUISITEERROR	Ошибка реквизитов	В ЭД указаны ошибочные реквизиты
REFUSED_BY_RZK	Отказан контролирующей организацией	Электронный документ не прошел проверки контролирующей организацией
FRAUDDENY	Отвергнут ФРОД	Документ отказан на основе проверки в АС Fraud-мониторинг, переходим в «Отвергнут банком»
Окончательный (Успешный)/Прекратить опрос
IMPLEMENTED	Исполнен	Электронный документ исполнен Банком