createInvoice method

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.

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 where data for the receipt are transmitted

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.
  • If the createInvoice request with payment via Sberbank Online (invoiceType=sberbank) continues getting the status=1 response after one hour, the payment is considered unsuccessful.

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

See also

Payment from an account in an SMS message

confirmInvoice method

Rules for processing requests

Error codes

Data types

Notification of successful payment