API ЮKassa
Помощь
Подключить ЮKassa
Метод createInvoice
Описание
Запрос позволяет инициировать списание денег со счета пользователя во внешних платежных системах (SberPay, Баланс мобильного телефона). Счет на оплату выставляется в смс на телефон пользователя. Пользователь подтверждает оплату ответным сообщением или вводом кода на сайте магазина.
Набор доступных способов оплаты определяется значением параметра invoiceType.
Формат запроса
Адрес для вызова операции
https://shop.yookassa.ru/webservice/mws/api/createInvoice
Параметры запроса
ПараметрТипОписание
clientOrderIdClientTransactionNumberУникальный идентификатор операции. Обеспечивает защиту от ошибочных повторов операций. Рекомендуемые значения: целое, положительное, линейно нарастающее десятичное число.
shopIdxs:stringИдентификатор магазина, выдается при подключении к ЮKassa.
shopArticleIdxs:stringИдентификатор товара, выдается в ЮKassa. Применяется, если магазин использует несколько платежных форм для разных товаров.
sumCurrencyAmountСумма платежа. Валюта по умолчанию — рубли.
customerNumberxs:normalizedString,
до 64 символов, обязательный
Идентификатор пользователя на стороне магазина. Присылается в платежной форме.
Возможна повторная оплата по одному и тому же идентификатору пользователя.
descriptionxs:stringОписание заказа. Может быть показано пользователю на стороне ВПС.
offer_acceptedxs:booleanПризнак согласия пользователя с офертой ЮMoney. Если передано значение, отличное от true, запрос будет отклонен.
smsPhoneNumberxs:stringНомер телефона плательщика в международном формате (79000000000), привязанный к счету в ВПС. Например, к мобильному банку СберБанка.
showcase_urlxs:stringАдрес сайта магазина. Обязателен только для платежей через SberPay.
invoiceTypexs:string
Идентификатор внешней платежной системы:
  • sberbank — оплата через SberPay;
  • mobileBalance — списание с баланса мобильного телефона
payMethodxs:string,
обязательный, если invoiceType=sberbank
Передается вместе с invoiceType=sberbank.
Способ подтверждения платежа.
Возможные значения:
  • offline — пользователь подтверждает оплату по смс или по пуш-уведомлению мобильного приложения СберБанка;
  • online — пользователь подтверждает оплату в мобильном приложении СберБанка (только для оплаты с мобильных устройств).
extendedRecipientNamexs:string,
до 16 символов
Передается вместе с invoiceType=sberbank.
Название магазина, которое будет отображаться пользователю при подтверждении платежа.
ym_merchant_receiptstring
Данные для формирования чека в формате 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.
Пример ответа: запрос в обработке
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"
/>
Что почитать еще
Правила обработки запросовКоды ошибокТипы данныхУведомление об успешном платеже