TRANSACTION_SUCCESSFUL
Purchase completed successfully.
What to do: Confirm data.status is successful and reconcile the matching order once.
Core concepts
Response codes
Use metadata.code to identify the exact API result, then read the transaction status when handling a purchase.
HTTP statusDescribes the HTTP response. A 2xx status alone does not prove fulfillment.
metadata.codeIdentifies the API result: processing, validation, failure or retrieval.
Transaction outcomeRead data.status for purchases or data.transaction.status for lookup.
Always inspect metadata.code
The top-level status is a request-level boolean. message is readable text,
not a stable value for branching. New integrations should read data.status for purchase
outcomes; data.transaction_status is deprecated.
A successful transaction lookup returns TRANSACTION_DETAILS_RETRIEVED even when the
purchase it describes is processing or failed. Always inspect data.transaction.status
in that response.
Transaction outcomes
ERR_TRANSACTION_PROCESSING
The purchase is still pending.
What to do: Save the reference and keep the order pending. Query it again; do not refund or submit another purchase while the result is unresolved.
ERR_TRANSACTION_FAILED
The purchase has a failed outcome.
What to do: Read data.status and the returned refund information. If the response confirms a refund, reconcile it once. Investigate any unresolved debit with support.
Authentication and account access
ERR_UNAUTHENTICATED
Credentials are absent or not accepted.
What to do: Check the Authorization: Bearer header, secret key and environment. Never send your secret key to support.
ERR_ACCOUNT_INACTIVE
The authenticated account cannot perform the operation.
What to do: Check the account status and contact support to resolve the restriction before trying again.
ERR_INSUFFICIENT_BALANCE
The wallet cannot cover the purchase.
What to do: Check the intended wallet and available funds. Resolve the balance issue before making another purchase attempt.
ERR_DAILY_LIMIT_EXCEEDED
A daily transaction limit has been reached.
What to do: Do not loop retries. Review account limits and contact support about an increase.
Request and product validation
ERR_MISSING_OR_INVALID_FIELDS
Required request values are missing or invalid.
What to do: Compare the request with the endpoint field table and correct values, types and lengths.
ERR_INVALID_REFERENCE_FORMAT
The reference is not in the accepted format.
What to do: Use letters and digits only. Check the endpoint length limit before submitting.
ERR_REFERENCE_ALREADY_EXISTS
A transaction already uses the submitted reference.
What to do: Choose a new reference for a new purchase every time, never as a blind retry of an uncertain order.
ERR_INVALID_AIRTIME_AMOUNT
The airtime amount is not accepted.
What to do: Check that it is positive and within the current product limits and send the documented JSON type.
ERR_INVALID_MOBILE_NUMBER
The phone number is not accepted.
What to do: Correct its format and confirm the recipient with the customer. Documentation placeholders are not real purchase inputs.
ERR_INVALID_PRODUCT_CODE_OR_INACTIVE
The product code is unknown or no longer active.
What to do: Fetch current products and choose an active product before submitting the corrected request.
ERR_INVALID_CABLE_TV_ACCOUNT
The smart card cannot be validated or the account is inactive.
What to do: Confirm the smart card and selected provider with the customer, then validate again.
ERR_INVALID_CABLE_TV_PROVIDER
The selected cable provider is invalid or unsupported.
What to do: Select a supported product code from the cable TV products endpoint and repeat validation.
ERR_INVALID_ELECTRICITY_ACCOUNT
The meter or electricity account cannot be validated.
What to do: Confirm the meter number, provider and meter type with the customer before validating again.
Lookup and resource errors
ERR_RESOURCE_NOT_FOUND
The requested resource is unavailable at that path.
What to do: Check the endpoint, resource identifier and environment.
ERR_TRANSACTIONS_NOT_FOUND
No matching transaction was found in the authenticated account.
What to do: For reference lookup, use the original purchase reference. Verify the account and environment. For history, there may be no matching records.
ERR_PHONE_NUMBER_NOT_FOUND
The phone report lookup has no matching record.
What to do: Handle an empty result. No report is not proof that a number is safe or unsafe.
Gateway and server errors
ERR_PRODUCT_GATEWAY_UNAVAILABLE
The provider gateway is unavailable.
What to do: For a submitted purchase, reconcile its reference before retrying. Delay read-only retries and avoid repeatedly submitting purchases.
ERR_INTERNAL_SERVER_ERROR
The server could not complete normal processing.
What to do: Keep the trace ID and reference. Query an uncertain purchase and contact support if it remains unresolved; do not infer a refund from HTTP 500.
Successful retrieval and validation
USER_DETAILS_RETRIEVED
The authenticated account details were returned.
What to do: Read data.account and check account_status before further operations.
WALLET_DETAILS_RETRIEVED
The account wallets were returned.
What to do: Select by wallet type, including primary_ngn, and check its status, balance and limits.
TRANSACTIONS_RETRIEVED
Transaction history was returned.
What to do: Read each transaction status separately; retrieving history does not mean every purchase succeeded.
TRANSACTION_DETAILS_RETRIEVED
The requested transaction record was returned.
What to do: The lookup succeeded. Read data.transaction.status to determine the purchase outcome.
PRODUCTS_RETRIEVED
The product list was returned.
What to do: Use its current identifiers, availability and pricing when preparing a purchase.
CABLE_TV_ACCOUNT_VERIFIED
The smart card validation succeeded.
What to do: Confirm the customer details and retain the verify_token for the matching purchase. This is not a completed subscription.
ELECTRICITY_METER_VERIFIED
The meter validation succeeded.
What to do: Confirm the customer and meter details; use the returned verify_token for that purchase. This does not mean electricity was purchased.
PHONE_REPORT_STATS_FETCHED
Phone report statistics were returned.
What to do: Use the statistics as contextual information rather than a guarantee about the recipient.
Missing codes, timeouts and unknown results
A network failure or proxy error may have no JSON body or metadata. Catch parsing errors and retain the HTTP status for diagnostics. If a code is missing, unfamiliar or contradicts the transaction status, leave a submitted purchase unresolved and query its saved reference. Do not invent a successful or failed outcome.
Log the endpoint, environment, reference, HTTP status and metadata.trace_id, with
secrets and customer details redacted. Follow transaction
verification and troubleshooting for recovery
steps.
Questions? Let’s work through them.
Having an issue or need help with your integration? Join the Strongmb Slack community to ask questions and get assistance from our team and other developers.
Keep API keys and customer details private when sharing examples.
Experiencing a service issue? Check Strongmb’s service status for incident updates.
Did this page help you?
Up to 100 characters. Please leave out personal details, account information and API keys.