How to Set Up Automatic Balance Top-Ups in an SMM Panel via API

What to Prepare Before Setting Up Auto Top-Ups

Auto top-ups connect the SMM panel balance to a payment service or internal billing. The service checks the remaining balance, creates a payment when the specified threshold is reached, and credits funds only after payment confirmation. To make this work, you need the panel's API documentation, access to the payment API, separate keys for the test and production environments, and a log of all operations.

Before development, check whether the panel API can return the balance, accept a credit request, show top-up history, and accept an external operation identifier. If the panel does not support crediting via API, automation can only create a request or send a notification to the operator. The downside of this option is that the money will still have to be deposited manually.

Separate the Balance Check from the Payment Decision

It is better to run the balance check as a separate scheduled task. It retrieves the balance, compares it with the threshold, and passes the result to the top-up handler. Do not create a payment directly at the moment of the API response without checking current incomplete operations: parallel tasks may see the same low balance and create multiple payments.

Before a new payment, the handler must check whether there is an operation with the status "created," "awaiting payment," or "being confirmed." If such a record exists, a new attempt is not started until reconciliation is complete. The downside of sequential processing is that with a slow response from the external API, the top-up may start later than with several parallel requests.

Choose the Threshold and Top-Up Amount Logic

The balance threshold is chosen with a margin for active orders, the supplier queue, and payment delays. For a channel with uneven activity, relying only on average spend is risky: after a stream, ad launch, or bulk order, charges can spike sharply. A critical level is set separately, at which a notification arrives but a payment is not necessarily created automatically.

The top-up amount can be fixed or calculated from spend over a selected period. A fixed amount is easier to control and reconcile. Its downside is that during a quiet period, extra funds may sit in the balance, while during a sharp increase in orders, one top-up may not be enough. A calculated amount is more flexible but requires cleaning the statistics of anomalous charges and refunds.

Set Financial Limits Separately from the Threshold

The threshold only answers the question of when the system is allowed to start the top-up process. Limits answer a different question: how much funds it is permitted to charge. Set the maximum amount for a single operation, an overall limit for the period, and the allowable balance after crediting. These rules are checked before creating a payment, not after it is paid.

Auto top-ups must not charge funds without a limit per operation and period. If the calculated amount exceeds the permitted amount, it is better to move the operation to manual review and send a notification. The downside of strict limits is that with rapid growth in expenses, the balance may run out before the responsible employee confirms an increase in the limit.

Create Separate Keys and Secure Access

For the auto top-up script, use separate API keys with minimal permissions: reading the balance, creating a payment, checking the status, and crediting a confirmed operation. Such a key does not need access to users, service settings, orders, or withdrawals. If the service supports IP address restrictions, allow requests only from the integration server.

Keys are stored in environment variables or a secure secrets vault. Do not pass them into browser code, logs, public repositories, or error messages. Each key must have an owner and a clear replacement procedure. The downside of frequent key rotation is that top-ups will stop if the new secret is not updated in all production processes.

Create a Payment with a Unique Identifier

Each top-up is assigned an internal identifier before calling the payment API. It is saved in the log and passed as an idempotency key or external operation number. On a network timeout, the same request can be repeated with the same identifier: the payment service should return the already created operation rather than charge the money again.

Below is a generic request example. Replace the field names and URLs with the values from the specific provider's documentation. The PAYMENT_ID variable stores a pre-created unique ID, and CALLBACK_URL points to the webhook handler.

curl -X POST "$PAYMENT_API_URL/payments" \
-H "Authorization: Bearer $PAYMENT_API_KEY" \
-H "Idempotency-Key: $PAYMENT_ID" \
-H "Content-Type: application/json" \
-d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID","callback_url":"$CALLBACK_URL"}'

Do not determine payment uniqueness only by amount and creation time. Two identical top-ups may be legitimate, but a repeated request after a failure is not. The downside of an external ID in your own database is that it must be stored reliably and not reused after an operation is canceled.

Check the Balance and Save the Operation State

The balance request should be performed before deciding on a new top-up and after a successful credit. A generic request may look like this: curl -X GET "$PANEL_API_URL/balance" -H "Authorization: Bearer $PANEL_API_KEY". In the response, save not only the amount but also the check time so that decisions are not made based on outdated data.

For each operation, keep a record with the internal ID, the provider's payment ID, amount, currency, creation time, status, API responses, and error reason. A suitable state chain is: "created," "awaiting payment," "paid," "crediting," "credited," "canceled," "requires review."

Crediting to the panel is allowed only for a confirmed and not yet processed payment. Do not overwrite statuses without history: in a dispute, it should be clear which request was sent and why the operation was changed. The downside of a detailed log is that it may contain sensitive data, so access to it is restricted.

Receive the Webhook and Verify the Payment Status

The successful payment page and user redirect do not confirm receipt of funds. Confirmation is provided by a webhook from the payment service or a repeated status check via its API. When receiving a webhook, verify the signature, send time, payment ID, external ID, amount, and currency. Only after that should you move the operation to the confirmed payment state.

After verifying the webhook, it is useful to request the current payment status from the provider. For example: curl -X GET "$PAYMENT_API_URL/payments/$PROVIDER_PAYMENT_ID" -H "Authorization: Bearer $PAYMENT_API_KEY". Compare the status with the log data, then send a credit request to the SMM panel with the same internal ID.

A repeated webhook must not create a second credit. The handler finds the operation by external ID, sees the "credited" status, and returns a successful response without new actions. The downside of webhooks is that they may be delayed or fail to arrive if the handler was unavailable.

Handle Timeouts, Retries, and Stuck Payments

On a timeout after creating a payment, do not send a new request with a different ID. First find the operation by internal identifier or repeat the request with the same idempotency key. If the provider accepted the original request, it will return the existing payment. This protects against double charging when the connection drops.

If the webhook does not arrive within the specified time, a background task requests the payment status via API. Repeated checks are made with an increasing delay and a limited number of attempts to avoid overloading the API and the log. An operation that remains pending for a long time is moved to manual review rather than considered canceled without reconciliation.

Retries are acceptable for responses indicating a temporary network error or API unavailability. For a payment decline, incorrect amount, invalid webhook signature, or limit exceeded, it is not worth repeating the request automatically. The downside of retries is that they complicate the state logic and can create extra load during a mass provider outage.

Credit the Confirmed Payment to the SMM Panel

Before crediting, the handler checks once more: the amount does not exceed the limit, the currency matches, the operation was not canceled, and its status is not yet "credited." The request passes the amount and the external payment identifier. If the panel API supports an idempotency key, use the same internal operation ID.

Generic request form: curl -X POST "$PANEL_API_URL/balance/topups" -H "Authorization: Bearer $PANEL_API_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: $PAYMENT_ID" -d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID"}'

After the panel responds, request the balance again and save the result in the log. If the money was charged by the payment service but the panel API returned an error, do not create a new payment. The operation remains in the "requires review" status until a repeated credit attempt or manual reconciliation. The downside of such a cautious scheme is that the balance may temporarily not be topped up automatically.

Add Notifications, a Kill Switch, and a Startup Check

Notifications are needed for deviations: the balance dropped below the critical level, the payment was declined, the webhook was not received, the limit was exceeded, the API is unavailable, or the operation requires manual review. The message only needs to include the internal ID, status, and reason. Do not include API keys, webhook signatures, or payment details in it.

Leave a separate auto top-up kill switch without removing the integration. It is needed when changing providers, during maintenance, when an error is suspected, or when expenses change sharply. The downside of a kill switch is obvious: if it is not turned back on after maintenance, the balance may run out during active orders.

Checklist Before Enabling Auto Top-Ups

• The balance check does not create a payment while an incomplete operation exists.
• A unique internal ID and idempotency key are created for each payment.
• Limits are set for a single operation and the selected period.
• Webhooks are verified by signature, amount, currency, and identifier.
• If no webhook arrives, a repeated status reconciliation via API is started.
• A timeout does not lead to creating a second payment before the first is checked.
• Crediting to the panel is performed once and recorded in the log.
• The test mode has been checked for success, decline, duplicate webhook, and API unavailability.