Invoice Webhook Guide

Creating an Invoice

Use this endpoint to create a new invoice.

Endpoint: POST /invoice

Required scopes: invoice

Parameters

Parameter	Type	Description
currency	string	Currency for the invoice.
amount	number	Invoice amount.
payment_id	string	Your unique payment identifier (must be unique within the merchant/invoices).
comment	string	Invoice description. (Will be publicly visible)
url_success	string	URL to redirect after successful payment.
url_callback	string	Webhook URL for payment notifications. (Optional)
merchant_id	integer	Your merchant ID. (You must create a merchant here)
lifetime	number	Invoice validity period in seconds. (Optional)
additional_data	string	Custom data for your reference. (Optional)

Example Response

JSON

{
    "invoice": {
        "invoice_id": 12345,
        "user_id": 12345,
        "merchant_id": 12345,
        "invoice_date": 1735689600,
        "expires_at": 1735689600,
        "amount": 12345,
        "status": "not_paid",
        "paid_date": 0,
        "payer_user_id": 0,
        "payment_id": "UniquePaymentID12345",
        "additional_data": "{\"UserID_TG\": 123456789012345}",
        "comment": "После оплаты вы получите ничего",
        "url_success": "https://yourweb.site/thanks",
        "url_callback": "https://yourweb.site/api/callback",
        "resend_attempts": 0,
        "is_test": 0,
        "url": "https://lzt.market/invoice/12345/"
    },
    "system_info": {
        "visitor_id": 12345,
        "time": 1735689600
    }
}

Webhook Callback

When an invoice is paid, a POST request will be sent to the url_callback specified during invoice creation.

Webhook Headers

Header	Description
x-secret-key	Contains your merchant token which must be verified

Webhook Payment Statuses

Status	Description
paid	Invoice is paid.
not_paid	Invoice is not paid.

Webhook Payload

The webhook will send a POST request with the following data:

JSON

{
  "invoice_id": 12345,
  "user_id": 12345,
  "merchant_id": 12345,
  "invoice_date": 1735689600,
  "expires_at": 1735689600,
  "amount": 100,
  "status": "paid",
  "paid_date": 1735689600,
  "payer_user_id": 111333,
  "payment_id": "UniquePaymentID12345",
  "additional_data": "{\"UserID_TG\": 123456789012345}",
  "comment": "This text will be publicly visible",
  "url_success": "https://yourweb.site/thanks",
  "url_callback": "https://yourweb.site/api/callback",
  "is_test": 1,
  "payer_username": "Username"
}

Verifying Webhooks

You must verify that the x-secret-key header matches with your merchant token to ensure the webhook was sent by our server.