API docs

Authentication

Send your account API key either in Authorization: Bearer YOUR_API_KEY or as the key request field. Choose one method; the key field works with common reseller panels. Keep keys in server-side environment variables and rotate them from Account.

All actions use POST https://smm.africa/api/v3. Supported bodies: application/json, application/x-www-form-urlencoded, and multipart/form-data with text fields only. Responses are JSON. The action field selects the operation.

curl --fail-with-body --silent --show-error --max-time 60 \
  -X POST https://smm.africa/api/v3 \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "action=balance"

All balances, charges, and order amounts in v3 are returned in USD for compatibility.

Errors & retries

Check the HTTP status and the JSON error field. Authentication errors use HTTP 400; API callers are not redirected to login. Log technical errors privately and show customers a neutral message.

{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY",
  "request_id": "request-123",
  "retryable": false
}

Add responses replay for 24 hours. After expiry, the same key can create another order: reconcile first. REQUEST_IN_PROGRESS permits the same request/key after Retry-After. IDEMPOTENCY_CONFLICT requires restoring the original payload. ACTION_OUTCOME_UNCONFIRMED requires support review: never change keys to bypass it. PRICE_LIMIT_EXCEEDED means no debit or order was committed. Log request_id (also X-Request-Id) for support.

Retry an order without charging twice

1. Create and persist a unique idempotency_key for each logical order before sending add. Replace the example key with your own unique value.
2. Allow up to 60 seconds for the server request. After 20 seconds, show a pending message to the customer while the backend request continues.
3. If no response arrives, retry the exact same payload with the same key after a delay. Do not generate a new key. A completed retry replays the response with X-Idempotent-Replay: true.
4. Once you receive an order ID, save it and use status to track that order. A queued response means accepted for fulfillment, not completed delivery.

Idempotency-Key and X-Idempotency-Key headers are also supported. Without a client key, an order can still be submitted, but retrying after a timeout cannot safely identify the original attempt.

Rate limits

Limits are action-specific and deployment-configurable. On HTTP 429, honor Retry-After (seconds). Without that header, use exponential backoff with jitter, for example 2, 4, 8, then 16 seconds plus a small random delay. Bound retries and surface persistent failures to your operator.

Cache the catalog fetched with POST /api/v3 and action=services. Refresh it periodically and verify current service IDs, rates, and min/max constraints before ordering.

Order lifecycle

Send action=status with order for one ID, or orders for 1–20 IDs. Bulk responses include http_status per item; back off per item using retry_after. As a starting client policy, poll every 30 seconds, then increase the interval for long-running orders; honor rate limits. Stagger requests across orders. Signed order webhooks are available when enabled for the deployment. Keep bulk polling for reconciliation. A stale response never authorizes repeating add.

queued → pending → processing

Active states: continue polling. Orders may skip intermediate states.

completed · partial · refunded · canceled

Terminal states: stop routine delivery polling. Partial means delivery was incomplete; inspect charge and remains. Refill and cancellation requests are subject to service and order eligibility.

unknown

An unrecognized state; do not treat it as success or place a replacement order automatically. Retry status with backoff and contact support if it persists.