Error Codes & Server Responses

Introduction into Smobilpay Error Categories

Error Code Category	Description	When it can occur	How are they transmitted
API Errors	These are errors generated directly by the Smobilpay system when performing pre-checks (e.g.: authentication, internal limit checks) on any request received via S3P API.	This occurs when Smobilpay pre-validates the incoming response.	These responses are transmitted synchronously during any call with our API
Payment Errors	These are errors that are usually directly related with a payment transaction (bill payment, collection, cash-in/cash-out etc) that has been sent to a service provider.	Errors of this category usually come from the service provider who is processing the payment transaction. Smobipay simply aggregates and forwards the errors to integrators via the S3P API.	These error messages are transmitted ONLY in the transaction response objects listed below: `GET /v2/verifytx` `GET /v2/historystd` Callback support via Webhook

API Error Codes

Find below a list of error codes that could be returned by the Smobilpay S3P API during processing of requests in the HTTP response object.

HTTP Error Message Object

All errors are returned as a valid JSON object and contain the following information:

Field	Description
devMsg	Verbose, plain language description of the problem for the app developer with hints about how to fix it, if applicable.
usrMsg	High level error message that can be passed on to the actual user - if required.
respCode	Unique error response code identifying the issue. We recommend you use this code for internal error handling.
Link	Link to documentation for this error response code – if available

Example

JSON

GET /ping HTTP 1.1
status code: 400

{
  "devMsg" : "Access token invalid", 
  "usrMsg" : "Authentication error when connecting to service", 
  "respCode" : 4009, 
  "link" : "http://support.maviance.com/"
}

Common Error Codes

These error codes can occur on any endpoint, usually due to wrong or invalid parameter values being sent

Error Code	HTTP Code	Message / Meaning	Recommended Action
4000	400	Authorization HTTP header is provided, but invalid	Correct Authentication Implementation Refer to Authentication
4001	400	Authorization HTTP header is missing in request	Correct Authentication Implementation Refer to Authentication
4002	400	One or more HTTP header parameters are incorrect	Correct Authentication Implementation Refer to Authentication
4005	400	Nonce already used	Correct Authentication Implementation Ensure the nonce sent via your implementation is unique Refer to Authentication
4006	400	Signature does not pass server validation	Correct Authentication Implementation Refer to Authentication
4007	400	Signature method not supported	Correct Authentication Implementation Pick a support signature methode Refer to Authentication
4008	400	Timestamp is too old	Correct Authentication Implementation Timestamp provided must not be too far in the past Refer to Authentication
4009	400	Access token used in authorization is invalid	Ensure correct credentials are being used
40003	401	User token is not recognized	Ensure correct credentials are being used
4105	400	One or more mandatory parameters are missing	Correct error in request and retry
4106	400	One or more mandatory parameters are empty	Correct error in request and retry
60020	400	Access outside configured workhours	Retry during workhours. Contact support to adapt configuration if necessary
40001	400	HTTP Type not supported	Correct error in request and retry
40002	500	Internal service exception	Contact support for details
40004	401	User account does not have access to this API	Ensure correct credentials are being used
40005	401	Internal service authentication error	Contact support for details
40007	400	Internal service communication error	Contact support for details
40010	400	Missing mandatory fields in request	Correct error in request and retry
40014	400	Company is not yet enabled	Contact support for details to activate your collector company account
40015	400	User provide in credentials does not exist	Contact support for details
40302	400	One or more input parameters are invalid or contain invalid values	Check error message and correct accordingly
40602	400	Service unknown. You likely used an incorrect or no longer active service id	Correct error in request and retry. Please validate input against configuration details of service.
40603	400	Merchant unknown. You likely used an incorrect or no longer active merchant code	Correct error in request and retry. Please validate input against configuration details of service.
5000	500	Server Error	Contact support for details
5010	500	Server error	Contact support for details
50000	500	Server exception	Contact support for details

Endpoint Specific HTTP Resposne Errors

The error codes below are specific to the context of the endpoint called

GET /v2/verify

Error Code	HTTP Code	Message / Meaning	Recommended Action
40408	400	This service does not allow a precollection verification of the service number	Correct error in request and retry. Please validate input against configuration details of service.

GET /v2/historystd

Error Code	HTTP Code	Message / Meaning	Recommended Action
4107	400	Too many optional filter parameters were provided in the request.	Correct error in request and retry
4201	400	Invalid service id	Correct error in request and retry
40011	400	Error when requesting a search with more than 1 filter	Correct error in request and retry

GET /v2/subscription

Error Code	HTTP Code	Message / Meaning	Recommended Action
4107	400	Too many optional filter parameters were provided in the request.	Correct error in request and retry
4201	400	Invalid service id	Correct error in request and retry
40011	400	Error when requesting a search with more than 1 filter	Correct error in request and retry
40605	400	Service type of service does not match requested type. You have passed in a service that is not supported by the endpoint	Correct error in request and retry
40611	400	Service temporarily deactivated for maintenance work	Try again later
41004	400	Gateway to service provider temporarily unavailable.	Try again later

GET /v2/bill

Error Code	HTTP Code	Message / Meaning	Recommended Action
4201	400	Invalid service id	Correct error in request and retry
4210	400	Wrong service type for endpoint	Correct error in request and retry
40011	400	Error when requesting a search with more than 1 filter	Correct error in request and retry
40013	400	Endpoint is called with empty search parameters	Contact support for details
40301	400	Item no longer available for payment	Time between search and payment was to great. Restart payment process from beginning
40605	400	Service type of service does not match requested type. You have passed in a service that is not supported by the endpoint	Correct error in request and retry
40611	400	Service temporarily deactivated for maintenance work	Try again later
41004	400	Gateway to service provider temporarily unavailable.	Try again later

POST /v2/collectstd

Error Code	HTTP Code	Message / Meaning	Recommended Action
4202	400	Invalid email address	Correct error in request and retry
4204	400	Invalid phone number	Correct error in request and retry
40201	400	Insufficient account balance	Topup your account with Smobilpay
40202	400	Collection limit exceeded	Contact support to discuss raising your limit
40301	400	Item no longer available for payment	Time between search and payment was to great. Restart payment process from beginning
40303	400	Error during collection process	Check error message and correct accordingly
40305	400	Destination blocked	The destination chose has been blocked by the system due to suspected fraud. Contact support for details
40609	400	This payment item id is no longer valid or has already been used for another payment	Re-retrieve the payment item id from the appropriate endpoint and restart the process
40611	400	Service temporarily deactivated for maintenance work	Try again later
41004	400	Gateway to service provider temporarily unavailable.	Try again later

POST /v2/quotestd

Error Code	HTTP Code	Message / Meaning	Recommended Action
4203	400	Invalid merchant code	Correct error in request and retry
4207	400	Invalid payment item id. Improper format	Correct error in request and retry
40304	400	Error with pricing calculation for the selected payment item	Contact support for details
40402	400	No pricing has been setup for the service you are trying to execute a payment for	Contact support for details
40404	400	The amount provided is not valid for this entity. You are injecting a custom price for a fixed price package.	Correct error in request and retry. Please validate input against configuration details of service.
40405	400	Amount is too small for collections	Correct amount and retry
40406	400	The amount provided is not valid for this entity. Partial payments are not allowed	Correct error in request and retry. Please validate input against configuration details of service.
40407	400	The amount provided is not valid for this entity. Overpayments are not allowed	Correct error in request and retry. Please validate input against configuration details of service.
40409	400	Payment amount outside of allowed range or proper denomination for this service	Correct error in request and retry. Please validate input against configuration details of service.
40606	400	The Payment Item Id provide is synactically incorrect	Re-retrieve the payment item id from the appropriate endpoint and restart the process
40610	400	Quote could not be created	Re-request a new quote
40611	400	Service temporarily deactivated for maintenance work	Try again later
44001	400	AML Block Service amount exceeds maximum allowed AML amount limit for a single transaction	Correct amount in request and retry

Payment Errors

Payment errors are errors that are usually directly related with a payment transaction (bill payment, collection, cash-in/cash-out etc) providing details as to why a transaction was accepted but ulitmately failed to be exeucted. You will only find these error codes in the errorCode property of the response object

Find below a list of error codes in the transaction object returned by

/verifytx endpoint
/historystd endpoint
Callback support via Webhook

Note: These error codes below will not be returned as an HTTP response error code!

Sample Responses for different error endpoints

GET /v2/verifytx

JSON

GET /verifytx HTTP 1.1
status code: 200

{
	"ptn": "99999164577717700069821234567890",
	"merchant": "CMMTNMOMO",
	"serviceid": "90003",
	"timestamp": "2022-02-25T08:19:37+00:00",
	"receiptNumber": "9999931234567890",
	"veriCode": "5411da",
	"clearingDate": null,
	"trid": "1234567800",
	"priceLocalCur": 35000.00,
	"priceSystemCur": 35000.00,
	"localCur": "XAF",
	"systemCur": "XAF",
	"pin": null,
	"status": "ERRORED",
	"payItemId": "S-113-948-CMMTNMOMO-90003-200544-1",
	"payItemDescr": null,
	"errorCode": 702102
}

GET /v2/historystd

JSON

GET /historystd HTTP 1.1
status code: 200

{
	"ptn": "99999164577717700069821234567890",
	"merchant": "CMMTNMOMO",
	"serviceid": "90003",
	"timestamp": "2022-02-25T08:19:37+00:00",
	"receiptNumber": "9999931234567890",
	"veriCode": "5411da",
	"clearingDate": null,
	"trid": "1234567800",
	"priceLocalCur": 35000.00,
	"priceSystemCur": 35000.00,
	"localCur": "XAF",
	"systemCur": "XAF",
	"pin": null,
	"status": "ERRORED",
	"payItemId": "S-113-948-CMMTNMOMO-90003-200544-1",
	"payItemDescr": null,
	"errorCode": 702102
}

Callback Response Body

JSON

POST /{exampleEndpoint} HTTP/1.1

X-Delivery: 72d3162e-cc78-11e3-81ab-4c9367dc0958
X-Ptn: 99999152778369900057856272351928
X-Signature: 13c3bda9ff43530abc8ae63755d9bb101e554c94
Content-Type: application/json
Content-Length: 89

{
  "timestamp":"2018-05-31 16:21:40",
  "trid":"13550",
  "errorCode": "702102",
  "status":"ERRORED"
}

Error Codes

Error Code	Description	Recommended Action
0	Transaction processing did not trigger an error - it’s either still being processed or was already successfully processed.	No error. Check the payment status.
2	Transaction is under investigation	Contact support for details
3	Transaction has been reversed	Contact support for details
40401	No free vouchers available	No free vouchers available
40701	Payment ran into timeout during execution and was errored	Re-request a new quote and retry
41002	Gateway balance insufficient	Try again later. Contact support if issue persists
41004	Gateway to service provider temporarily unavailable.	Try again later
60001	No open agent session	Contact support for details
60003	Company session is not open	Contact support for details
60010	Invalid drawer assignment	Contact support for details
702000	Transaction failed due to a general payment error	Contact support for details
702100	Transaction failed when initializing communications with the service provider	Contact support if this error persists during retry
702101	Destination does not match expected value range. For example: The MSISDN may not within the number range accepted by the Service Provider	Correct error in request and retry. Please validate input against configuration details of service.
702102	The transaction was rejected because the amount is below the acceptable threshold	Correct error in request and retry. Please validate input against configuration details of service.
702103	The transaction was rejected because the amount is above the acceptable threshold	Correct error in request and retry. Please validate input against configuration details of service.
702105	The transaction timeout at the level of Service Provider	Check the payment status. It has to be moved to a clear ERROR or SUCCESS and act accordingly.
702106	Transaction failed. The Service Provider could not be reached temporarily (during transaction initialization phase)	Try again later. Contact support if issue persists.
703000	Transaction failed due to a general business error.	Contact support for details
703020	The Service Provider could not be reached temporarily (after transaction initialization phase)	Try again later. Contact support if issue persists.
703100	Invalid input in request - one or more fields of the payment input request are invalid and were rejected	Correct error in request and retry. Please validate input against configuration details of service.
703102	Service Provider has rejected the transaction	Try again. Contact support for details if issue persists.
703103	Recipient account with Service Provider is blocked	Inform customer
703104	Sender account with Service Provider is blocked	Inform customer
703105	Service Provider does not know the recipient (account) of the transaction	Inform customer
703106	Service provider does not know the Sender/Initiator Account of the transaction	Inform customer
703107	Recipient Account does not have sufficient funds with the Service Provider to perform this transaction.	Inform customer
703108	Initiator (sender) Account does not have sufficient funds with the Service Provider to perform this transaction	Inform customer
703109	Service Provider rejected the transaction because the amount is below the threshold allowed	Correct error in request and retry. Please validate input against configuration details of service.
703110	Service Provider rejected the transaction because the amount is above the threshold allowed	Correct error in request and retry. Please validate input against configuration details of service.
703111	Sender/Initiator account has exceeded the limit (daily, weekly, monthly etc) with the Service Provider	Inform customer
703112	Recipient account has exceeded the limit (daily, weekly, monthly etc) with the Service Provider	Inform customer
703113	Payment Item (e.g. for bill payments) is no longer available for payment or has already been paid	Retrieve currently available payment item id based on service type
703114	The Service Provider has rejected the transaction amount. Invalid Amount in the transaction	Correct error in request and retry. Please validate input against configuration details of service.
703117	The Service Provider does not support the Account number in the transaction.	Inform customer
703201	Payment requires a customer confirmation to complete. Confirmation has not been given by customer.	Inform customer
703202	Customer has rejected the payment / denied the approval of the transaction. The transaction cannot complete without the customer confirmation.	Inform customer. Retry payment.
703203	Customer has provided Wrong/Invalid approval credentials which resulted in a rejection of the transaction by the Service Provider (e.g. wrong/invalid PIN, expired OTP, etc.). The transaction cannot complete without the customer confirmation.	Inform customer. Retry payment.
703401	Error indicating that the connector could not find the transaction in the Service Provider System when performing a status check.	Contact support for details
703501	Technical error during validation of payment with service provider	Contact support for details
703503	Service provider system is under maintenance	Try again. Contact support for details if issue persists.
704000	Technical error	Contact support for details
704003	Payment processing error	Contact support for details
704004	The time between searching for and paying for a payable item was too long and has expired.	Please retry from start
704005	Technical error during validation of payment with service provider	Contact support for details
704006	Unknown response provided by Service Provider	Contact support for details
705000	Unexpected technical error	Contact support for details
705010	Timeout during communication with service provider	Try again later. Contact support if issue persists.
705020	Timeout during communication with service provider	Try again later. Contact support if issue persists.
705030	Timeout during communication with service provider	Try again later. Contact support if issue persists.
90000	Internal server error	Try again later. Contact support if issue persists.