Метод createInvoice — [Архив] Протокол приема платежей через ЮKassa

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

Набор доступных способов оплаты определяется значением параметра

invoiceType

Для выполнения запросов на оплату по смс необходимо подключение по HTTP-протоколу.

Формат запроса

Адрес для вызова операции

https://shop.yookassa.ru/webservice/mws/api/createInvoice

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

Параметр	Тип	Описание
clientOrderId	ClientTransactionNumber	Уникальный идентификатор операции. Обеспечивает защиту от ошибочных повторов операций. Рекомендуемые значения: целое, положительное, линейно нарастающее десятичное число.
shopId	xs:string	Идентификатор магазина, выдается при подключении к ЮKassa.
shopArticleId	xs:string	Идентификатор товара, выдается в ЮKassa. Применяется, если магазин использует несколько платежных форм для разных товаров.
sum	CurrencyAmount	Сумма платежа. Валюта по умолчанию — рубли.
customerNumber	xs:normalizedString, до 64 символов, обязательный	Идентификатор пользователя на стороне магазина. Присылается в платежной форме. Возможна повторная оплата по одному и тому же идентификатору пользователя.
description	xs:string	Описание заказа. Может быть показано пользователю на стороне ВПС.
offer_accepted	xs:boolean	Признак согласия пользователя с офертой ЮMoney. Если передано значение, отличное от true , запрос будет отклонен.
smsPhoneNumber	xs:string	Номер телефона плательщика в международном формате ( 79000000000 ), привязанный к счету в ВПС. Например, к Мобильному банку СберБанка.
showcase_url	xs:string	Адрес сайта магазина. Обязателен только для платежей через СберБанк.
invoiceType	xs:string	Идентификатор внешней платежной системы: sberbank — оплата через СберБанк (СберБанк Онлайн, SberPay); webmoney — списание из кошелька в системе WebMoney. mobileBalance — списание с баланса мобильного телефона
payMethod	xs:string, обязательный, если invoiceType=sberbank	Передается вместе с invoiceType=sberbank . Способ подтверждения платежа. Возможные значения, если используется SberPay: offline — пользователь подтверждает оплату по смс или по пуш-уведомлению мобильного приложения СберБанка; online — пользователь подтверждает оплату в мобильном приложении СберБанка (только для оплаты с мобильных устройств). Возможные значения, если используется СберБанк Онлайн: offline — пользователь подтверждает оплату по смс в мобильном банке; online — пользователь подтверждает оплату на веб-странице СберБанка Онлайн.
extendedRecipientName	xs:string, до 16 символов	Передается вместе с invoiceType=sberbank . Название магазина, которое будет отображаться пользователю при подтверждении платежа.
ym_merchant_receipt	string	Данные для формирования чека в формате JSON. Параметр передается и является обязательным, если вы настроили взаимодействие со своей онлайн-кассой через ЮKassa и передаете в платежной форме данные для формирования чека.

Имена параметров этого запроса не чувствительны к регистру.

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

POST /webservice/mws/api/createInvoice HTTP/1.1
Host: someshop.ru
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Content-Length: length
offer_accepted=true&clientOrderId=1436792567640&description=some_descr&smsPhoneNumber=89052185656&invoiceType=sberbank&payMethod=offline&sum=10.00&showcase_url=https%3A%2F%2Fexample.com&shopId=900700

Пример запроса при оплате через SberPay с подтверждением по смс или пуш-уведомлению

POST /webservice/mws/api/createInvoice HTTP/1.1
Host: someshop.ru
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Content-Length: length
offer_accepted=true&clientOrderId=1000000000000&description=some_descr&smsPhoneNumber=89000000000&invoiceType=sberbank&payMethod=offline&sum=10.00&showcase_url=https%3A%2F%2Fexample.com&shopId=100000

Пример запроса при оплате через SberPay в мобильном приложении СберБанка

POST /webservice/mws/api/createInvoice HTTP/1.1
Host: someshop.ru
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Content-Length: length
offer_accepted=true&clientOrderId=1000000000000&description=some_descr&invoiceType=sberbank&payMethod=online&sum=10.00&showcase_url=https%3A%2F%2Fexample.com&shopId=100000

Параметры для чека

Эти параметры нужны, если вы настроили взаимодействие со своей онлайн-кассой через ЮKassa. См. Описание процесса оплаты с отправкой данных для чека

Данные для чека передаются обязательно, в параметре

ym_merchant_receipt

, в формате JSON (так же, как в платежной форме).

Пример запроса с данными для чека

POST
/webservice/mws/api/createInvoice HTTP/1.1
Host: someshop.ru
Content-Type:
application/x-www-form-urlencoded; charset=UTF-8
Content-Length: length
offer_accepted=true&clientOrderId=1436792567640&description=some_descr&smsPhoneNumber=89123456543&invoiceType=sberbank&sum=500.23&showcase_url=https%3A%2F%2Fexample.com&shopId=900700&ym_merchant_receipt=%7B%22customerContact%22%3A%20%22%2B79123456543%22%2C%22taxSystem%22%3A%201%2C%22items%22%3A%20%5B%7B%22quantity%22%3A%201.154%2C%22price%22%3A%20%7B%22amount%22%3A%20300.23%7D%2C%22tax%22%3A%203%2C%22text%22%3A%20%22%D0%A2%D0%BE%D0%B2%D0%B0%D1%80%20%D0%90%22%7D%2C%7B%22quantity%22%3A%202%2C%22price%22%3A%20%7B%22amount%22%3A%20200.00%7D%2C%22tax%22%3A%203%2C%22text%22%3A%20%22%D0%A2%D0%BE%D0%B2%D0%B0%D1%80%20%D0%91%22%7D%5D%7D

Данные для чека, которые передаются в этом запросе, в параметре

ym_merchant_receipt

JSON
{
  "customerContact": "+79123456543",
  "taxSystem": 1,
  "items": [
    {
      "quantity": 1.154,
      "price": {
        "amount": 300.23
      },
      "tax": 3,
      "text": "Товар А"
    },
    {
      "quantity": 2,
      "price": {
        "amount": 200.00
        },
        "tax": 3,
        "text": "Товар Б"
    }
  ]
}

Формат ответа

В ответе на запрос

createInvoice

приходит XML-документ, состоящий из одного элемента:

createInvoiceResponse

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

status

Если в запросе приходит

invoiceType=sberbank

payMethod=online

, в ответе передается дополнительный параметр

externalPaymentUrl

. Для СберБанка Онлайн в нём передается ссылка на страницу подтверждения оплаты в СберБанке Онлайн, для SberPay — диплинк в мобильное приложение СберБанка. Магазину нужно самостоятельно перенаправить пользователя по полученной ссылке.

Пример ответа: запрос в обработке

XML
<createInvoiceResponse
  orderId="2000003201974"
  status="1"
  error="0"
  processedDT="2015-06-26T14:22:43.824Z"
/>

Пример ответа при оплате через SberPay в мобильном приложении СберБанка

XML
<createInvoiceResponse
  orderId="1000000000000"
  status="1"
  error="0"
  processedDT="2015-06-26T14:21:46.824Z"
  externalPaymentUrl="sberpay://invoicing/v2?bankInvoiceId=b297c4461e e34490b9a759ab2b3b3d17&redirect_uri=https://yoomoney.ru/g/1kjlqr06u0c20f67753ff0af71e07a/?ulp=https%3A%2F%2Fshop.com%2Fsuccess.html"
/>

Пример ответа при успехе обработки

XML
<createInvoiceResponse
  orderId="2000003201974"
  status="0"
  error="0"
  processedDT="2015-06-26T14:22:56.245Z"
/>

Пример ответа при ошибке

XML
<createInvoiceResponse
  status="3"
  error="158"
  processedDT="2015-06-26T14:51:31.033Z"
/>

Что почитать еще

Правила обработки запросов Коды ошибок Типы данных Уведомление об успешном платеже

Описание

Формат запроса

Формат ответа