createInvoice method

Attention. This is an old version of the API. Switch to the Yandex.Checkout API.

Description

This request allows you to initiate debiting money from the user's account in external payment systems (Sberbank Online or Webmoney). 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.

Note.

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

Address for calling the createInvoice operation

https://server:port/webservice/mws/api/createInvoice

Input 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 Yandex.Checkout.
shopArticleId	xs:string	Product ID issued by Yandex.Checkout. 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 Yandex.Money 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 Sberbank Online.
invoiceType	xs:string	ID of the external payment system: sberbank — Sberbank Mobile Banking or Sberbank Online. webmoney — Debit from a WebMoney purse.
payMethod	xs:string	Passed along with invoiceType=sberbank. Possible values: offline — Sberbank Mobile Banking, user confirms payment via SMS online — Sberbank Online, user confirms payment in webpage
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 Yandex.Checkout and transmits the details for creating the receipt in the payment form.


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 Yandex.Checkout.
shopArticleId	xs:string	Product ID issued by Yandex.Checkout. 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 Yandex.Money 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 Sberbank Online.
invoiceType	xs:string	ID of the external payment system: sberbank — Sberbank Mobile Banking or Sberbank Online. webmoney — Debit from a WebMoney purse.
payMethod	xs:string	Passed along with invoiceType=sberbank. Possible values: offline — Sberbank Mobile Banking, user confirms payment via SMS online — Sberbank Online, user confirms payment in webpage
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 Yandex.Checkout and transmits the details for creating the receipt in the payment form.

Note.

Parameter names for this request are not case-sensitive.

Parameters for the receipt

These parameters are required if you set up interaction with your online sales register via Yandex.Checkout. 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).

Response format

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.

Note. If the request has invoiceType=sberbank and payMethod=online, the response passes an additional parameter: externalPaymentUrl. This parameter contains a link to the payment confirmation page in Sberbank Online. The merchant must redirect the user to this page.

Examples

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&sum=10.00&showcase_url=https%3A%2F%2Fexample.com&shopId=900700

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:

{"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 example: request being processed

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

Response example for successful processing

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

Response example with error

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