If anything is unclear, feel free to contact our support team: support@lava.top.

To get started with integrating your service on the platform, you need to create an API key and set up a webhook.

1. Go to Integrations section, choose API.

2. Click Create API Key.

3. The platform will generate the key automatically — copy it and save it securely on your device.

1. Create an API key and confirm that you’ve saved it.
2. Click the Add Webhook button.

3. Fill in the following fields:

• URL — the endpoint on your server where webhook data will be sent (this is the address that will receive and process requests).
• Event type:

1. payment.success — Successful payment
2. payment.failed — Failed payment
3. subscription.recurring.payment.success — Successful subscription renewal
4. subscription.recurring.payment.failed — Failed subscription renewal
5. subscription.cancelled — Subscription cancelled
6. refund.success — Successful refund
7. chargeback.initiated — Chargeback request received

4. Choose an authentication method:

• Basic - enter the login and password for your service that will receive webhook requests.

• Your service’s API key - enter the API key of your service that will receive the webhook requests. Maximum key length: 80 characters.

Click the three dots next to the desired key and select Add Webhook.

Products - work with digital products: fetch the product list and update their parameters (e.g., price).

IInvoices — for creating purchase invoices (including invoices for custom amounts), checking their status, and setting up the customer's return to the creator's page after payment.
The /api/v2/invoices and /api/v3/invoice methods are available.

Custom Price Invoices - allows creating a contract with a custom price for products published with the 'Price on request via API' flag. The amount and currency are set per request, without changing product settings.

Reports - access sales analytics data via the API.

Subscriptions - manage user subscriptions.

Donate - generate donation links.

1. provide your API key:

• Click Authorize in the top-right corner of the page:

• fill in ApiKeyAuth (apiKey), (use the API key you received in the Author’s personal account interface at lava.top: Integrations → API → Create API Key (we explained this in more detail here)):

2. click Try it out, enter the required data, and select Execute:

In the lava.top interface, when publishing a Digital Product, Consultation, or Course, enable the “Price on request via API” option. The pricing block will be hidden. The product will only be available via direct link and through the API.

Use the POST /api/v3/invoice method. Pass the offerId of the product published with the “Price on request” option enabled, as well as amount and currency in the request body.

1.curl --location 'https://gate.lava.top/api/v3/invoice' \
2.  --header 'Accept: application/json' \
3.  --header 'X-Api-Key: {api_key}' \
4.  --header 'Content-Type: application/json' \
5.  --data-raw '{
6.	"email": "client@example.com",
7.	"offerId": "836b9fc5-7ae9-4a27-9642-592bc44072b7",
8.	"currency": "EUR",
9.	"amount": 120
10.  }'

Specifying the provider

1.curl --location 'https://gate.lava.top/api/v3/invoice' \
2.  --header 'Accept: application/json' \
3.  --header 'X-Api-Key: {api_key}' \
4.  --header 'Content-Type: application/json' \
5.  --data-raw '{
6.	"email": "client@example.com",
7.	"offerId": "836b9fc5-7ae9-4a27-9642-592bc44072b7",
8.	"currency": "EUR",
9.	"amount": 120,
10.	"paymentProvider": "PAYPAL"
11.  }'

Use the POST /api/v3/invoice method. Add the optional successful_return_url, failure_return_url, and cancel_return_url fields to the request body. You can pass any subset — one field, two, or all three.

All three query

1.curl --location 'https://gate.lava.top/api/v3/invoice' \
2.  --header 'Accept: application/json' \
3.  --header 'X-Api-Key: {api_key}' \
4.  --header 'Content-Type: application/json' \
5.  --data-raw '{
6.    "email": "client@example.com",
7.    "offerId": "836b9fc5-7ae9-4a27-9642-592bc44072b7",
8.    "currency": "EUR",
9.    "successful_return_url": "https://school.example.com/thanks",
10.    "failure_return_url": "https://school.example.com/payment-error",
11.    "cancel_return_url": "https://school.example.com/checkout"
12.  }'

Successful payment page only

1.curl --location 'https://gate.lava.top/api/v3/invoice' \
2.  --header 'Accept: application/json' \
3.  --header 'X-Api-Key: {api_key}' \
4.  --header 'Content-Type: application/json' \
5.  --data-raw '{
6.    "email": "client@example.com",
7.    "offerId": "836b9fc5-7ae9-4a27-9642-592bc44072b7",
8.    "currency": "EUR",
9.    "paymentProvider": "PAYPAL",
10.    "successful_return_url": "https://school.example.com/thanks?utm_source=lava"
11.  }'

Requirements for values:

• https scheme only
• Absolute URL
• Up to 512 characters per field

After payment, the customer first returns to a lava.top page and is then redirected to your address.

The intermediate page shows a loading indicator and does not repeat the payment status — the customer has already seen it in the payment form and will see it on your page.

We add two parameters to your address:

• invoiceId — The invoice ID
• status — success / failed / cancelled

• Applies only to invoices created via the API. Does not apply to direct sales on lava.top
• For subscriptions, applies only to the first payment. Renewals run without a browser session
• If the automatic redirect fails, the customer stays on our page and sees a link to continue manually

Get the package PyPI, typically via pip:

1.pip install lava-top-sdk

Make sure that, however you install lava-top-sdk, you install its dependencies as well.

Available on npm

1.npm install --save lava-top-sdk

Get the artifact from Maven

1.<dependency>
2.	<groupId>top.lava</groupId>
3.	<artifactId>lava-top-kotlin-sdk</artifactId>
4.	<version>1.0.0</version>
5.</dependency>

If the webhook is not delivered, the system will automatically try to resend it to the specified URL. The first attempt will be in one second, the second in five seconds, and the third in 15 seconds. The system will then make ten attempts with an interval of one minute. After that, if unsuccessful, the system will make five more attempts with an interval of one hour.

Up to 20 attempts will be made in total.

You can find the webhook history in your account card. To access it, go to Integrations → API → Webhook history (button in the upper right corner of the page).

This section logs all events linked to your configured webhooks. Events are categorized by type, status, and the API Key + webhook pair.

In the payment details, you can view the full request body sent at the time of the event, along with the delivery attempt history (in case of a failed subscription charge, the webhook is sent only after the final attempt (i.e., if there were three charge attempts, the webhook will be triggered only after the third one)). To see these details, simply click on the corresponding webhook entry.

Advanced filters are available to help you quickly find the webhook you need — you can search by Buyer's email, Invoice ID, Product name, or Product ID.

Each event is associated with a payment type and a contract status.

Payment Types:

• one-time payment (purchasing a digital product, course, consultation, or the first payment in a subscription);
• recurring payment (subscription renewal or cancellation).

Contract Statuses:

• success (payment was successful);
• failed (payment was not completed, e.g. insufficient funds);
• cancelled (the subscription was cancelled).

Based on this, you may encounter the following Event types:

• payment.success — successful purchase of a product (not a donation) or the first subscription payment;
• payment.failed — failed product purchase (not a donation) or failed first subscription payment;
• subscription.recurring.payment.success — successful renewal of a subscription (second, third, and later payments);
• subscription.recurring.payment.failed — failed subscription renewal;
• subscription.cancelled — cancellation of a previously active subscription;
• refund.success — a full or partial refund on a sale has been completed;
• chargeback.initiated — the customer has opened a dispute through their bank.

To receive events, create a webhook and select the events you need in the "Event type" field. There are no restrictions on combinations: a single webhook can receive one event or all seven. See "Setting up the integration" for how the options map to event types:

Refunds and chargebacks happen after a sale is completed and affect both your balance and the customer's access to content. These events let you revoke access in your system automatically and reconcile your records without manual exports.

Both events arrive in a common envelope. The event body is in the data field; its contents depend on the event type.

1.{
2.  "event_id": "7ea82675-4ded-4133-95a7-a6efbaf165cc",
3.  "event_type": "refund.success",
4.  "created_at": "2024-02-05T09:38:27.33277Z",
5.  "data": { }
6.}

Payload eventrefund.success

1.{
2.  "event_id": "7ea82675-4ded-4133-95a7-a6efbaf165cc",
3.  "event_type": "refund.success",
4.  "created_at": "2024-02-05T09:38:27.33277Z",
5.  "data": {
6.    "refund_id": "7ea82675-4ded-4133-95a7-a6efbaf165cc",
7.    "refund_type": "full",
8.    "initiator": "creator",
9.    "amount": 400.00,
10.    "currency": "EUR",
11.    "product": {
12.      "product_name": "Test product",
13.      "product_id": "d31384b8-e412-4be5-a2ec-297ae6666c8f",
14.      "product_type": "DIGITAL_PRODUCT",
15.      "tier_id": "836b9fc5-7ae9-4a27-9642-592bc44072b7"
16.    },
17.    "customer_email": "test@lava.top",
18.    "balance_impact": {
19.      "debited_amount": 368.00,
20.      "currency": "EUR"
21.    },
22.    "subscription_cancelled": false
23.  }
24.}

Payload event chargeback.initiated

1.{
2.  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
3.  "event_type": "chargeback.initiated",
4.  "created_at": "2024-02-05T09:38:27.33277Z",
5.  "data": {
6.    "chargeback_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
7.    "dispute_date": "2024-02-05",
8.    "reason_category": "fraud",
9.    "reason_description": "Fraudulent transaction",
10.    "amount": 400.00,
11.    "currency": "EUR",
12.    "product": {
13.      "product_name": "Test product",
14.      "product_id": "d31384b8-e412-4be5-a2ec-297ae6666c8f",
15.      "product_type": "DIGITAL_PRODUCT",
16.      "tier_id": "836b9fc5-7ae9-4a27-9642-592bc44072b7"
17.    },
18.    "customer_email": "test@lava.top",
19.    "balance_impact": {
20.      "debited_amount": 400.00,
21.      "provider_fee": 40.00,
22.      "currency": "EUR"
23.    },
24.    "subscription_cancelled": false
25.  }
26.}

The status indicates whether the webhook was successfully received.

A webhook can have one of two statuses:

• DELIVERED — the webhook was successfully delivered.
• FAILED — the webhook delivery failed.

The status is determined based on the HTTP response code returned by your server when the event is sent.

Lava.top uses HTTP status codes to determine whether an API request was successfully processed or failed.

If a webhook delivery fails (i.e., a non-successful HTTP status code is returned), lava.top will retry the delivery up to 19 additional times, for a total of 20 attempts.

If webhooks were not delivered, the system will attempt to resend them to the specified URL. Repeated attempts are made according to the logic: first 1s, 5s, 15s, then 10 attempts with an interval of 1 min, then, if unsuccessful, another 5 attempts with an interval of 1 hour.

In total, 20 delivery attempts will be made.

Each attempt is logged in the webhook history with the corresponding HTTP status code. If a successful status code is received, no further retries will be made. In that case, you’ll see only one event logged (successful or failed payment).

In case of an unsuccessful response, up to 20 attempts may be made (retries stop after a successful delivery or after 19 retry attempts).

You can view all retry attempts in the "Sending attempt history" section of the webhook details.

Most common response codes:

• Code 401 / Code 403 — Invalid authentication data; access to the webhook handler is denied;
• Code 404 — The webhook contains an incorrect URL (the link to the author's server that receives and processes the webhook is invalid)
• Code 500 — An error occurred on the author's server that is responsible for handling the webhook.

You can manually resend any webhook by clicking the arrow icon next to it.

Click the icon and confirm the resend action.

Added the ability to create an invoice for a custom amount via API.

Implemented the POST /api/v3/invoice method with support for amount and currency parameters for products published with the “Price on request via API” option enabled.

Supported content types: Digital product, Consultation, Course.

Supported currencies: RUB, USD, EUR. Contract type: ONE_TIME.

Updated navigation for the "Integrations" section.

A standalone “Integrations” section has been added to the Creator Dashboard sidebar menu. API Key and Webhook management has been moved here from the Profile section. Navigation path: Integrations → API.

Subscription payments via Stripe are now supported.

Implemented /api/v2/invoices and /api/v2/invoices/{id} endpoints with updated contract typing:

• INVOICE - payment for products, consultations, or courses,
• SUBSCRIPTION_FIRST_INVOICE - first subscription charge,
• SUBSCRIPTION_RENEWAL - recurring subscription payment.

Donation payments via Stripe are now supported.

Improved GET /invoices request: now returns the parentInvoiceId field (ID of the parent transaction for subscriptions).

PayPal support added:

• Subscription payments,
• Donation sending.

Webhook improvements:

• Manual retry option,
• Webhook list retrieval,
• Event type now included in the webhook payload,
• Ability to search webhooks by Product ID in the Author Dashboard (Integrations → API → Webhook History).

UTM tags added.

Stripe payment support added for digital products.