createInvoice method — [Archive] Payment solution protocol for merchants

createInvoice method

This is an old version of the API. Switch to the YooMoney API.

Description

This request allows you to initiate debiting money from the user’s account in external payment systems (SberPay, or direct carrier billing). A request for payment is sent in an SMS message to the user’s phone. The user confirms payment by sending a reply or entering a code on the store’s website.

The payment methods that are available depend on the value of the invoiceType parameter.

To process requests for payment using SMS messages, you must use the HTTP protocol.

Request

Address for calling the operation

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

Request parameters

Parameter	Type	Description
clientOrderId	ClientTransactionNumber	Unique transaction ID. Provides protection from repeating operations by mistake. Recommended values: linearly increasing decimal integers.
shopId	xs:string	The merchant ID issued when activating YooMoney.
shopArticleId	xs:string	Product ID issued by YooMoney. Used if the store has multiple payment forms for various products.
sum	CurrencyAmount	Payment amount. The default currency is the ruble.
customerNumber	xs:normalizedString, maximum 64 characters, required	The user ID used by the merchant. Sent in the payment form. The same user ID can be used repeatedly in payments.
description	xs:string	Order description. May be shown to the user in the external payment system.
offer_accepted	xs:boolean	Indicates whether the user agrees to the YooMoney terms and conditions. If any value other than `true` is passed, the request is declined.
smsPhoneNumber	xs:string	The user phone number linked to the account in the external payment system, in international format (`79000000000`). For example, to SberBank mobile banking.
showcase_url	xs:string	URL of the store’s website. Required only for payments via SberPay.
invoiceType	xs:string	ID of the external payment system: `sberbank` — payment via SberPay; `mobileBalance` — Debit via direct carrier billing
payMethod	xs:string, required if `invoiceType=sberbank`	Passed along with `invoiceType=sberbank`. Payment confirmation scenario. Possible values: `offline`: user confirms the payment via text message or push notification from SberBank's mobile app; `online`: user confirms the payment in SberBank's mobile app (only for payments via mobile devices).
extendedRecipientName	xs:string, up to 16 characters	Sent with `invoiceType=sberbank`. Store’s name displayed to users during payment confirmation.
ym_merchant_receipt	string	Details for creating a receipt in the JSON format. The parameter is transmitted and presents as mandatory if you set up interaction with your online sales register via YooMoney and transmits the details for creating the receipt in the payment form.

Parameter names for this request are not case-sensitive.

Request example

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

Example of a request for payments via SberPay with confirmation via text message or push notification

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

Example of a request for payments via SberPay via SberBank’s mobile app

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

Parameters for the receipt

These parameters are required if you set up interaction with your online sales register via YooMoney. See Description of payment process with receipt data transmission

Data for the receipt is transmitted mandatory in the ym_merchant_receipt parameter, in the JSON format (as in the payment form).

Example of the request with data for the receipt

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

Data for the receipt that are transmitted in this request under ym_merchant_receipt parameter:

JSON
{
  "customerContact": "+79123456543",
  "taxSystem": 1,
  "items": [
    {
      "quantity": 1.154,
      "price": {
        "amount": 300.23
      },
      "tax": 3,
      "text": "Product A"
    },
    {
      "quantity": 2,
      "price": {
        "amount": 200.00
        },
        "tax": 3,
        "text": "Product B"
    }
  ]
}

Response

The response to the createInvoice request is an XML document containing a single element: createInvoiceResponse.

Output parameters that are shared for all types of financial transaction requests. The result of the operation is passed in the status field.

If the request has invoiceType=sberbank and payMethod=online, the response passes an additional parameter: externalPaymentUrl. This parameter contains a deep link to SberBank’s mobile app. The store needs to redirect the user via the received link on its own.

Response example: request being processed

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

Example of a response for payments via SberPay in SberBank's mobile app

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"
/>

Response example for successful processing

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

Response example with error

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