Visitor credit top-up

Connect a credit top-up request from the widget to checkout on your website.

Credit top-up request

When Offer additional credits is enabled in channel settings, the Add credits button sends an internal message from the iframe to the loader. The loader validates the origin, iframe source, and channel, then dispatches the safe senler-widget:credit-purchase-requested event on window:

const expectedChannelId = "xxx";

window.addEventListener("senler-widget:credit-purchase-requested", (event) => {
  if (event.detail.channel_id !== expectedChannelId) return;

  openCreditPayment({
    channelId: event.detail.channel_id,
    leadId: event.detail.lead_id,
  });
});

event.detail contains the validated channel_id and lead_id. The event only reports the user's intent: it neither processes payment nor changes the credit balance. The website must still verify that channel_id belongs to its integration and then open its own payment form.

Grant credits after payment

After payment is confirmed, the website backend must grant the purchased credits to the lead with a separate server-to-server request:

POST /api/projects/{projectId}/leads/{leadId}/credits
Authorization: Bearer senler_sk_...
Content-Type: application/json

{
  "credits": 50000,
  "type": "purchase",
  "reason": "Payment for order shop-order-123",
  "idempotency_key": "widget-credit-purchase:shop-order-123"
}

Put your integration's projectId in the request path and take leadId from the event. Before opening payment, verify that event.detail.channel_id matches this integration's channel. The project API key must belong to the same project and have the can_manage_leads permission. Keep the key on the backend only: never put it in loader configuration, page JavaScript, or browser network requests.

The credits field accepts an integer number of minimal credit units: one credit displayed to the user equals 10,000 units, so 50,000 grants 5 credits. The price and order contents remain website data and are not sent in this request.

Always reuse one stable idempotency_key for the same paid line item. After a network error, the request can be safely retried with the same body and key; using a new key for the same item grants the credits again. The grant changes only the selected lead's extra balance and does not top up the project's credit balance.

After the grant, the widget receives an update through its existing realtime connection, removes the block, and refreshes the balance. No additional browser request or polling is required.