getNumber, getStatus, setStatus 3/6/8: where the activation cycle loses money
The bot took a number, saw no SMS after 30 seconds, sent setStatus 8 and moved on to the next one. The server rejected the cancellation, but nobody read the response. Later a code arrived for that first number. The order was paid for, and the code was never used. Below is the API activation cycle step by step, plus the branches where an integration ends up paying for codes it doesn't need.
The cycle, step by step
- getNumber. The bot requests a number for a service and country, the order amount is reserved on your balance, and the response contains an activation id. Save the id to persistent storage before the bot enters the number in the service. If the process crashes, you can't cancel the order or pick up the code without the id.
- getStatus. The bot polls the status and waits for the code. The catalog sets how long to wait: each service has its own window, currently one hour.
- setStatus 3. You need another code on the same number: the first one didn't work, or the service asks you to confirm again. After 3, the bot goes back to polling getStatus.
- setStatus 6. The code has been used, and the order is complete.
- setStatus 8. Cancellation. It's accepted only while the code hasn't arrived, and no earlier than one minute after purchase.
If the bot does nothing and no code arrives, the reserve returns to your balance on its own when the window expires. That gives you the main rule of the integration: cancelling an activation with setStatus 8 gets you a refund only before the code arrives. Once the SMS is received, the service counts as delivered, and the order is not refunded. All refunds go to your internal balance, not to a wallet.
Where money gets lost
Cancelling in the first minute. This is the scenario from the opening. Read the response to every setStatus 8. If the cancellation failed because of the one-minute rule, keep polling getStatus and retry the cancellation once a minute has passed since purchase.
Polling racing the cancellation. getStatus returned "waiting", the bot sent 8, and the code arrived between the two requests. The cancellation won't go through now. Make one more getStatus call and use the code. The order is paid for either way.
Cancelling after the code because registration failed. The service rejected the account, so the developer sends 8 and expects the money back. The code was delivered, which means the service was provided, and receiving an SMS doesn't guarantee a successful sign-up on a third-party service. Close these orders with status 6 and count them separately from cancellations in your reports.
Abandoned number. The bot moves on to the next number without cancelling, often because of a single timeout shared across all services. If the timeout is shorter than the service's window, the code may arrive after the bot has stopped waiting, and you've paid for nothing. Take the timeout from the specific service's window, and close any number you no longer need with an explicit status 8.
A new number instead of status 3. The first code didn't work, so the bot buys a different number. A new getNumber is a separate order with its own reserve, and registration on the service has to start over. Request a repeat code with status 3 on the same number, and check that getStatus returned a new code, not the previous one.
Success left open. The code was entered, but 6 was never sent. The order stays open until the window runs out, and the log can no longer tell you which numbers are done and which are still waiting for a code. Send 6 as soon as the service accepts the code.
Migrating from another service. If the bot switched to us by changing the base URL, its status branches were written for the previous platform's rules. Check for the one-minute delay before cancelling, and set timeouts based on the windows in our catalog.
Polling, keys, and softId
The API limit is 600 requests per minute per key. That's ten per second across all your open orders combined. A tight getStatus loop hits it fast. The most dangerous case is when your code reads a rate-limit rejection as "no code yet" and cancels or abandons the number. Poll each order with a pause of a few seconds, and handle the rate-limit response in its own branch: wait, then retry.
Purchases made with an API key are charged to your balance. Issue a separate named key for each bot or environment. The last-used date in the dashboard shows which keys are unnecessary, so you can revoke them.
For software owners in the partner program: make sure softId is sent with every getNumber. Without it, the purchase won't be linked to your software_id, and you won't get the 5% from the user's activation. If an order is refunded, the commission on it is deducted.
What to check today
Open the "API Reference" in your dashboard and compare how you handle each status against it, starting with the response to 8 and timeouts based on each service's window. Then pick a period in the "Transactions" feed and match refunds against the bot's log. Every order that was cancelled or expired without a code should come back to your balance. If the log shows a cancellation but the feed shows only a payment for that order, find the number in "Order History" and check when the bot sent 8: in the first minute, or after the code had already arrived.