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.
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/createInvoiceInput 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:
|
| payMethod | xs:string | Passed along with invoiceType=sberbank. Possible values:
|
| 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:
|
| payMethod | xs:string | Passed along with invoiceType=sberbank. Possible values:
|
| 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 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.
- 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%7DData 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" />