Создание черновика платежного поручения (отправка на свой счет в Сбербанке)

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

/fintech/api/v1/payments/from-invoice

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

Для создания черновика платежного поручения необходимо отправить POST-запрос /fintech/api/v1/payments/from-invoice с токеном доступа (access_token) пользователя в параметре Authorization заголовка и реквизитами счета в теле запросе.

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

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

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

Request

/fintech/api/v1/payments/from-invoice

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

Наименование	Тип	Формат	Regexp	Обязательность	Описание
HEADER
Authorization	string	string	^[a-zA-Z0-9]{38}$	required	Access token пользователя, полученный через SSO.
BODY
Invoice {
amount	number	float	^[0-9]{1,16}\.[0-9]{2}$	required	Сумма платежа,
date	string	ISO 8601 YYYY-MM-DD	^[0-9]{4}-[0-9]{2}-[0-9]{2}$	required	Дата составления документа,
deliveryKind	string	string	^(электронно\|срочно\|0)$	optional	Вид платежа. Если не заполнено или 0, то будет присвоено значение "электронно",
expirationDate	string	ISO 8601 YYYY-MM-DD	^[0-9]{4}-[0-9]{2}-[0-9]{2}$	optional	Дата истечения заказа (платеж должен быть подтвержден клиентом),
externalId	string	UUID	^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$	required	Идентификатор документа, присвоенный партнером,
linkedDocs	array[LinkedDoc]	array[object]		optional	Связанные документы,
operationCode	string	string	^01$	optional	Код операции,
orderNumber	string	string		optional	Номер заказа,
payeeAccount	string	string	^[0-9]{20}$	required	Счет получателя платежа,
payeeOrgIdHash	string	string	^[0-9a-f]{64}$	optional	Идентификатор получателя платежа,
paymentNumber	string	string	^[0-9]{1,6}$	optional	Номер платежного поручения. Если Клиент не ведет в своей учетной системе нумерацию платежных поручений, созданных на основании выставленных счетов, то атрибут можно не передавать, он будет присвоен автоматически,
priority	string	string	^[4-5]{1}$	optional	Очередность платежа,
purpose	string	string	^.{0,240}$	required	Назначение платежа. Рекомендации по заполнению,
urgencyCode	string	string	^(INTERTAL\|INTERNAL_NOTIF\|OFFHOURS\|BESP\|NORMAL)$	optional	Код срочности. INTERNAL - срочный INTERNAL_NOTIF - срочный платеж с уведомлением OFFHOURS - неотложный BESP - банковские электронные срочные платежи NORMAL - срочность не указана,
vat	Vat	object		required	Данные НДС
}
LinkedDoc {
docExtId	string	UUID	^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$	optional	Идентификатор документа (заявления на страхование экспортного контракта) во внешней системе (UUID), к которому необходимо привязать платежное поручение,
type	string	string	^(ExportContractInsure)$	optional	Тип связанного документа (доступное значение для заполнения - exportContractInsure), с которым необходимо связать платежное поручение
}
Vat {
amount	number	float	^[0-9]{1,16}\.[0-9]{2}$	optional	Сумма НДС,
rate	string	string	^[0-9]{0,2}$	optional	Ставка НДС,
type	string	string	^(INCLUDED\|NO_VAT\|MANUAL)$	required	Способ расчета НДС. INCLUDED - НДС включен в сумму платежа NO_VAT - не облагается НДС MANUAL - ручной ввод НДС
}

POST /fintech/api/v1/payments/from-invoice HTTP/1.1
Content-Type: application/json
Authorization: Bearer xbgDF3brf456ghi789jkl012mNKFtEpqr678
 
{
    "amount": 100.00,
    "date": "2023-11-14",
    "deliveryKind": "электронно",
    "expirationDate": "2023-11-30",
    "externalId": "534bb614-5d3b-4f29-a667-c8dd51be9e7e",
    "operationCode": "01",
    "orderNumber": "123",
    "payeeAccount": "40702810006000001792",
    "paymentNumber": "1",
    "priority": "5",
    "purpose": "Оплата заказа №123. НДС 20%",
    "urgencyCode": "NORMAL",
    "vat": {
        "type": "INCLUDED",
        "amount": 20.00,
        "rate": "20"
    }
}

Responses

201 (Created)

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

Наименование	Тип	Обязательность	Описание
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 201 Created
Content-Type: application/json;charset=UTF-8
 
{
    "number": "1",
    "date": "2023-11-14",
    "digestSignatures": [],
    "bankStatus": "CREATED",
    "bankComment": null,
    "externalId": "534bb614-5d3b-4f29-a667-c8dd51be9e7e",
    "amount": "100.00",
    "operationCode": "01",
    "deliveryKind": "электронно",
    "priority": "5",
    "urgencyCode": "NORMAL",
    "voCode": null,
    "purpose": "Оплата заказа №123. НДС 20%",
    "departmentalInfo": null,
    "payerName": "ИП_Автотест_Клиент_ЕКС_20231027092336",
    "payerInn": "213504669246",
    "payerKpp": "346801713",
    "payerAccount": "40802810706000000087",
    "payerBankBic": "048073601",
    "payerBankCorrAccount": "30101810300000000601",
    "payeeName": "ТЕСТ9036",
    "payeeInn": "7379190522",
    "payeeKpp": "683801910",
    "payeeAccount": "40702810006000001792",
    "payeeBankBic": "048073601",
    "payeeBankCorrAccount": "30101810300000000601",
    "crucialFieldsHash": "0c78790070b8487a4d73151bdab59899",
    "vat": {
        "type": "INCLUDED",
        "rate": "20",
        "amount": "20.00"
    },
    "incomeTypeCode": null
}

400 (Bad request)

Cause	Message	Description
DESERIALIZATION_FAULT	Неверный формат запроса	Данные в request указаны в неправильном формате. Атрибуты request, в которых найдены ошибки, указаны в responce в массиве fields с описанием проблемы. Описание типа, формата и regexp атрибутов находится в request запроса. Скорректируйте заполнение атрибутов и повторите запрос.
WORKFLOW_FAULT	Не найдена организация получателя по payeeOrgIdHash: <значение payeeOrgIdHash>	Проверьте корректность поля payeeOrgIdHash. Также можно в повторном запросе не указывать данное поле - оно не обязательное.
	Невозможно идентифицировать организацию плательщика	Проверьте корректность указанных реквизитов плательщика.
	Документ с таким externalId уже существует в системе	Используется externalId, который уже есть в системе (дубль). Сгенерируйте новый externalId и повторите запрос.
	Отсутствует доступный открытый рублевый расчетный счет у организации плательщика	Плательщику требуется открыть рублевый расчетный счет в Сбербанке.
	Неизвестный счет получателя: <счет получателя платежа>	Проверьте корректность указанного счета в атрибуте payeeAccount. Счет должен принадлежать вашей организации.
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": "145ac7ed-9c20-4a75-8135-8a978d403836",
    "message": "Объект Invoice не соответствует модели",
    "checks": [
        {
            "level": "ERROR",
            "message": "должно соответствовать \"^(электронно|срочно|0)$\"",
            "fields": [
                "deliveryKind"
            ]
        }
    ],
    "fieldNames": [
        "deliveryKind"
    ]
}

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_INVOICE`. Необходимо добавить эту операцию в scope. Пользователю потребуется пройти авторизацию заново. Вы получите новые токены access_token и refresh_token. Сделайте повторный запрос с новым access_token.
		Вы использовали access_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": "Операция не может быть выполнена: доступ к ресурсу запрещен"
}

429 (Too Many Requests)

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

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

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

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": "Внутренняя ошибка сервера"
}