Creating an Invoice

Method for issuing an invoice.

URL

Method: POST

• Production: https://api.pay.kvell.group/v1/invoices
• Stage: https://api.pay.stage.kvell.group/v1/invoices

Request parameters

Name	Type	Required	Description
invoice_number	string	Yes	Unique invoice number
amount	integer	Yes	Order amount in kopecks
delivery_type	string	No	Invoice delivery method. Defaults to link
delivery_value	json	No	Data for invoice delivery
∟phone	string	No	Phone number for invoice delivery
∟email	string	No	Email for invoice delivery
description	string	Yes	Invoice description
expired_at	string	No	Invoice expiration date
fiscal_data	json	No	Fiscal data
extra_data	json	No	Additional data
split_data	array	No	Payment splitting

Invoice delivery methods

Name	Description
sms	Via SMS
email	Via email
sms-email	Via SMS and email simultaneously
link	Via a link
whatsapp	Via WhatsApp

Request example

{
  "invoice_number": "ae1eea1e-58fc-497e-aa74-c9acc4535733",
  "amount": 10000,
  "delivery_type": "email",
  "delivery_value": {
    "email": "invoice@test.com",
    "phone": "123456789"
  },
  "fiscal_data": {},
  "extra_data": {},
  "description": "Test invoice 1",
  "expired_at": "2023-10-05 10:00",
  "split_data": [
    {
     "service_id": "343-23",
     "amount": 1000,  // In kopecks
     "description": "",
     "metadata": {}
    }
  ]
}

Request headers

Name	Data type	Required	Description
X-Api-Key	string	Yes	Unique shop identifier
X-Signature	string	Yes	Signature

The X-Signature signature is formed by concatenating X-Api-Key, invoice_number, amount, and secret_key. It is generated as the sha256 hash of the resulting string:

sha256({X-Api-Key}{invoice_number}{amount}{secret_key})

where secret_key is the secret key found in the merchant's shop settings;

Response

Response example

201: OK422: Unprocessable Entity

{
  "id": 48,
  "invoice_guid": "fab90932-6b26-453c-b46e-8572342b5286",
  "api_key": "3a8c82d6-d2c6-4165-9a6b-ab3f14d965ae",
  "status": "new",
  "amount": 10000,
  "created_at": "2022-10-04T07:33:10.915751+00:00",
  "expired_at": "2022-10-05T10:10:00+00:00",
  "invoice_number": "ae1eea1e-58fc-497e-aa74-c9acc4535733",
  "delivery_type": "email",
  "delivery_value": {
    "email": "invoice@test.com",
    "phone": "123456789"
  },
  "fiscal_data": {},
  "extra_data": {},
  "split_data": [],
  "description": "Test invoice 1",
  "url": "https://pay.kvell.group/checkout/invoice/fab90932-6b26-453c-b46e-8572342b5286"
}

{
  "errors": [
    {
      "code": 20098,
      "message": "field required"
    }
  ]
}

Response parameters

Name	Data type	Description
id	string	Payment ID in the system
invoice_guid	string	Invoice GUID
api_key	string	Unique shop identifier
status	string	Transaction status
amount	integer	Amount in kopecks
created_at	string	Invoice creation time
expired_at	string	Invoice expiration date
invoice_number	string	Unique transaction (invoice) number
delivery_type	string	Invoice delivery method
delivery_value	json	Data for invoice delivery
∟phone	string	Phone number for invoice delivery
∟email	string	Email for invoice delivery
fiscal_data	json	Fiscal data
extra_data	json	Additional data
split_data	array	Transaction split data
description	string	Invoice description
url	string	Link to the invoice

List of statuses

Name	Description
new	New invoice
processing	Invoice is being processed
canceled	Invoice rejected
completed	Invoice completed
expired	Invoice expired