Creating an Invoice¶

Creates payment invoice.

For scenarios using this method, please see “QIWI Form Payment using the API” and “Payment Token“

Request¶

PUT /payin/v1/sites/{siteId}/bills/{billId}

Path Parameters¶

Parameter	Required	Type	Description
siteId	Yes	string	Merchant site identifier
billId	Yes	string	Unique invoice identifier in the Merchant’s system

Headers¶

Header	Required	Type	Description
Authorization	Yes	string	API access key. `Bearer [access-token]`
Content-type	Yes	string	Request content. `application/json`
Accept	No	string	Response content. `application/json`

Body Parameters¶

Parameter	Required	Type	Description
amount	Yes	object	Amount of the operation
expirationDateTime	Yes	string	Invoice expiration date. If invoice is not paid until this date, subsequent invoice payment will not be possible
comment	No	string(256)	Service description for the customer
billPaymentMethodsType	No	array of strings	Payment methods shown on the QIWI Payment Form for a customer. `CARD` — bank card. `SBP` — Faster Payment System.
flags	No	array of strings	Additional API commands. `SALE` — use one-step authorization scenario. `BIND_PAYMENT_TOKEN` — issue a payment token.
customer	No	object	Customer information
receiverData	No	object	Payment recipient information
customFields	No	object	Additional information for the operation

Request Example¶

Creating an Invoice

PUT /partner/payin/v1/sites/site-01/bills/893794793973 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: b2b-api.qiwi.com

{
   "amount": {
     "currency": "RUB",
     "value": 100.00
   },
   "billPaymentMethodsType": [
      "SBP"
   ],
   "comment": "Text comment",
   "expirationDateTime": "2022-04-13T14:30:00+03:00",
   "customer": {},
   "customFields": {
     "cf1": "Some data"
   }
}

Response¶

Successful Response Parameters¶

Parameter	Required	Type	Description
billId	Yes	string	Invoice unique identifier — the same as in the original request
invoiceUid	Yes	string(60)	Invoice identifier on the QIWI side
amount	Yes	object	Operation amount
status	Yes	object	Invoice status. `CREATED` only: the invoice is issued and waiting to be paid
comment	Yes	string	Service description for the customer
creationDateTime	Yes	string	Invoice creation date
expirationDateTime	Yes	string	Invoice expiration date
payUrl	Yes	string	Payment Form URL
customer	No	object	Customer information: `account`, `email`, `phone`
customFields	No	object	Additional information for the operation: `contractdId`, `invoice_callback_url`, `themeCode` и др.

Error Parameters¶

Parameter	Required	Type	Description
serviceName	Yes	string	Name of the service that produced the error
errorCode	Yes	string	Error code
description	Yes	string	Error description for the merchant
userMessage	Yes	string	Error description for the customer
dateTime	Yes	string	Error date and time
traceId	Yes	string	Error Log unique ID

Response Examples¶

Successful responseResponse when the invoice already exists and expiredResponse with error 4xx

{
    "billId": "893794793973",
    "invoiceUid": "d875277b-6f0f-445d-8a83-f62c7c07be77",
    "amount": {
        "value": "100.00",
        "currency": "RUB"
    },
    "status": {
        "value": "CREATED",
        "changedDateTime": "2022-04-05T11:27:41"
    },
    "comment": "Text comment",
    "customFields": {
        "cf1": "Some data"
    },
    "creationDateTime": "2022-03-05T11:27:41",
    "expirationDateTime": "2022-04-13T14:30:00",
    "payUrl": "https://payment.qiwi.com/form/?invoice_uid=d875277b-6f0f-445d-8a83-f62c7c07be77"
}

{
"billId": "12345",
"invoiceUid": "3b39ad6d-f111-401d-8108-ed11af920a65",
"amount": {
    "currency": "RUB",
    "value": "1.00"
},
"expirationDateTime": "2023-03-21T13:02:00+03:00",
"status": {
    "value": "EXPIRED",
    "changedDateTime": "2023-03-21T13:02:00+03:00"
},
"comment": "Text comment",
"flags": [
    "TEST"
],
"payUrl": "https://payment.qiwi.com/form?invoiceUid=3b39ad6d-f211-401d-8008-ed11af920a65"
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2022-03-05T11:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}