Invoice Webhook Guide

Authorization & Token configuration

To use this API you need to create API Client and get Access Token with invoice scope.

You must pass the token in the request headers

Header: "Authorization: Bearer token"

📘
You can find more information about API itself here

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).
`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

{
    "invoice": {
      "additional_data": "{\"UserID_TG\": 123456789012345}",
      "amount": 10000,
      "comment": "This text will be publicly visible",
      "expires_at": 1735689600,
      "invoice_date": 1735689600,
      "invoice_id": 12345,
      "is_test": false,
      "merchant_id": 12345,
      "paid_date": 0,
      "payer_user_id": 0,
      "payment_id": "UniquePaymentID12345",
      "resend_attempts": 0,
      "status": "paid",
      "url": "https://lzt.market/invoice/12345/",
      "url_callback": "https://yourweb.site/api/callback",
      "url_success": "https://yourweb.site/success",
      "user_id": 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
`x-attempt`	Contains the number of attempts to send the request (same as `resend_attempts` in the JSON body)

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:

{
  "additional_data": "{\"UserID_TG\": 123456789012345}",
  "amount": 10000,
  "comment": "This text will be publicly visible",
  "expires_at": 1735689600,
  "invoice_date": 1735689600,
  "invoice_id": 12345,
  "is_test": false,
  "merchant_id": 12345,
  "paid_date": 1735689600,
  "payer_user_id": 1,
  "payment_id": "UniquePaymentID12345",
  "resend_attempts": 0,
  "status": "paid",
  "url": "https://lzt.market/invoice/12345/",
  "url_callback": "https://yourweb.site/api/callback",
  "url_success": "https://yourweb.site/success",
  "user_id": 12345
}

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.