The Ubiqpay API employs HTTP status codes to communicate the outcome of API requests, and this section provides an overview of these codes and their implications within our framework.
Codes
- 200: When an API request generates a code in the 2XX range, it indicates the request was successfully processed.
- 4XX: API requests resulting in codes in the 4XX range indicate issues with the data you provided, such as missing required parameters/headers or incorrect Access Token.
- 5XX: Codes in the 5XX range denote processing errors on our API end.
If there is an error concerning a field within the merchant's request body, an extra property named errors will be returned. An example of the response can be found below:
// HTTP 400: BAD_REQUEST
{
"status_code": "bad.request",
"message": "Bad request",
"errors": [
"merchant_reference cannot be null or empty"
]
}
The response will appear as follows if the merchant's request is valid and an error occurs on the Ubiqpay API's end:
// HTTP 500: INTERNAL_SERVER_ERROR
{
"status_code": "internal.server.error",
"message": "Internal Server Error",
"data": {
"id": "1234",
"amount": 31000,
"currency": "KES",
"narration": "Order summary",
"country_code": "KE",
"merchant_reference": "merchant-ref-1234",
"transaction_id": "41ff0598-cce1-11ed-b870-0242ac120004",
"payment_method": "MOBILE_MONEY",
"payment_status": "FAILED",
"payment_option_id": 7,
"created_at": "2023-02-21T14:16:46.77872",
"updated_at": "2023-02-21T14:16:46.812058"
}
}
Below is a list of common status codes:
| Status Code | Message | Comment |
|---|---|---|
| success | Request processed successfully | |
| bad.request | Bad request | Check your request object properties |
| invalid.payment.option | Payment option not found or not enabled | Check if the payment option exists in your account |
| resource.not.found | Resource not found | Transaction or Payment option not found |
| internal.server.error | Please try again as the request could not be completed. | This is an internal error. It will be automatically reported and investigated. |
| invalid.card.details | Invalid card details | Check card properties |
| decryption.card.failed | Decryption of card details failed | Check your encryption method |
| invalid.currency | The selected currency does not match the currency required by the chosen Payment Option. | |
| invalid.phone.number | Invalid phone number | |
| payment.already.exists | Payment already exists with the same merchant reference | Merchant reference must be unique |
| invalid.payment.method | The selected payment method does not match the payment method required by the chosen Payment Option. | Check the selected payment option |
| invalid.country.code | The selected country code does not match the country code required by the chosen Payment Option. | Check the country code |
| invalid.min.amount | The amount should be equal to or greater than the minimum amount required by the chosen Payment Option. | |
| invalid.max.amount | The amount should be less than or equal to the maximum amount required by the chosen Payment Option. | |
| invalid.fees | No fees have been set up for this payout option on your account | Contact UBIQPAY support team |
| invalid.payout.option | Payout option not found or not enabled | Check if the payment option exists in your account |
| payout.already.exists | Payout already exists with the same merchant reference | This is a duplicated transaction |
| insufficient.balance.account | Insufficient balance account | |
| provider.similar.trx.error | A similar transaction was done recently | |
| receiver.not.registered | The customer's mobile phone number is not registered with the targeted service. | This error code is used with Meeza payment option in Egypt. |
| invalid.eg.national_id.length | Invalid National ID length. Must be 14 digits | Egyptian national ID |
Similar Transaction Error
{
"status_code": "provider.similar.trx.error",
"message": "A similar transaction was done recently, please wait 5min before retrying",
"data": {
...
}
}
Description
This error code indicates that a similar transaction was attempted too soon after a previous transaction. It occurs when transactions are made with the same phone number and the same amount within a 5-minute window. One of our payment providers, implements this restriction to enhance security measures and prevent potential fraudulent activities.
Affected Countries
Depending on the provider used, this error could be occured to transactions in the following countries:
- Burkina Faso (BF)
- Benin (BJ)
- Gabon (GA)
- Guinea (GN) (Orange Money only)
- Kenya (KE)
- Mali (ML)
- Nigeria (NG)
- Senegal (SN)
- Tanzania (TZ)
- Uganda (UG)
How to Avoid This Error
To prevent this error and ensure smooth transactions for your customers, please consider the following guidelines:
- Transaction Timing: Advise your customers to wait at least 5 minutes before attempting another transaction with the same phone number and the same amount. This interval allows our system to process each transaction distinctly, reducing the risk of triggering fraud detection mechanisms.
- Transaction Variation: If possible, suggest that your customers vary the transaction amounts if they need to make multiple transactions in a short period. Even a small variation in the amount can prevent the system from flagging the transaction as a duplicate.
- Customer Communication: Inform your customers about this specific restriction. Awareness can help reduce the number of transactions that are blocked due to this error, enhancing the overall customer experience.
- Monitoring and Feedback: Encourage customers to monitor their transactions and provide feedback on any issues encountered. This feedback is invaluable for us to continuously improve our systems and services.
Resolution Steps
If you or your customers encounter this error, please follow these steps:
- Ensure that the required time has elapsed (at least 5 minutes) before retrying the transaction.
- Verify that the transaction amounts are not identical to those of previous transactions within the last 5 minutes.
- If the issue persists, please contact our support team with details of the transaction for further assistance.
Note to Merchants
We understand the importance of ensuring seamless transactions for your customers, especially in preventing errors related to similar transactions being made within a short timeframe. To further support this, we offer an additional feature that can be activated upon request.
Feature Overview:
Upon activation, this feature automatically detects when a customer attempts to make a new payment with the same amount to the same phone number within the 5-minute window. To prevent the "provider.similar.trx.error," our system will intelligently round the transaction amount slightly. This adjustment is minimal but effective in avoiding the error due to duplicate transactions.
How to Activate:
This feature can be enabled for your account upon request. If you are interested in activating this automated amount adjustment feature, please contact our support team. We will provide you with all necessary details regarding the activation process and any implications for your transaction processing.
Recommendation:
While this feature offers an additional layer of flexibility, we still recommend merchants to encourage their customers to vary their transaction amounts manually or wait the necessary 5-minute interval between transactions. This practice ensures a broader understanding and control over transaction habits, which can be beneficial for both security and customer experience.
Activating this feature should be considered as a complementary measure rather than a primary solution to avoid similar transaction errors.