Valuetopup API Specification (v2)

This is the gateway of the Valuetopup system that allows other hosts to connect to it and perform transactions. This API is based on REST principles and uses JSON as the format for data interchange.

Each call to the API is authenticated via UserId and Password. Authentication to the API is performed by HTTP Basic Authentication. Prepay Nation will provide a user id and password. Consumers send credentials in userId:password base64-encoded format in the Authorization header.

For example, let’s assume User Id = testuser and Password = test1234. Base64 format of “testuser:test1234” is dGVzdHVzZXI6dGVzdDEyMzQ= This must be in the header of each request – Authorization: Basic dGVzdHVzZXI6dGVzdDEyMzQ==

If the Valuetopup API and a response with the HTTP status code of 200, response will be provided in the following format:

{
    "responseCode": "string",
    "responseMessage": "string",
    "payLoad": object
}

Following is the field description:

IMPORTANT: Check for successful transaction you must check for 2 condition:

1. The HTTP status code : 200 OK and
2. responseCode in the body of the response is "000". If the status code is 200 and responseCode is not "000" then you must follow the API documentation for subsequent actions. If the HTTP status code is other than 200 then consider the transaction as failed.

Successful Transaction Example:

As we can see in the below response, we got HTTP status code: 200 OK Success from the server and also responseCode = "000". So we can say the transaction has been success.

***Http Status Code: 200 OK Success***
Response Body
{
    "responseCode": "000",
    "responseMessage": null,
    "payLoad": object
}

Failed Transaction Example:

As we can see in the below response, we got HTTP status code: 200 OK Success from the server but we got the responseCode = "501" Invalid Subscriber.So this is a Failed Transaction as subscriber number is not valid.

***Http Status Code: 200 OK Success***
Response Body
{
    "responseCode": "501",
    "responseMessage": "The Subscriber number is not valid",
    "payLoad": null
}

To facilitate integration to the API and for testing, two distinct environments are provided:

• Sandbox API: https://sandbox.valuetopup.com/api/v2

• Production API: https://www.valuetopup.com/api/v2

Sandbox environment can be used to access all API methods and perform transactions to test scenarios based on Integration test scenario sheet.

Production environment – actual transactions are performed, and it will charge to your account.

An exceptional scenario might occur in which the recharge transaction does not return a response within the timeout duration set by your system. This might cause your system to throw a timeout error and think that there was not response from Prepay Nation API. The timeout error does not mean that the original transaction has failed in the Prepay Nation system. It means that your system could not wait any longer than the set timeout duration for the response from Prepay nation API. If the original transaction is successful then your account will be charged.

To know the correct and final status of the original transaction we recommend that you implement the Check Status of transaction by customer unique correlation ID API method. This method will return you the final status of the original transaction.

Please follow the steps below: Send the corelationId value with every RTR or PIN transaction. This is the unique id from your system which will help us to identify the original transaction. In case of a request timeout error, call ""Transaction API -> Check Status of transaction by customer unique correlation ID"" method and pass the correlation id from step #1. You should call the Check Status of transaction by customer unique correlation ID method multiple times until you get a definite response of a success or a failure. Please refer to the documentation of ""Transaction API -> Check Status of transaction by customer unique correlation ID"" method.

Scenarios to generate Timeout mitigation:

1.) To generate Timeout error for 120 seconds, follow the below steps: a.) Initiate Top-up: Start the process to top up the mobile number ending with "666666". b.) Wait for 120 seconds: Allow the system 175 seconds to process the transaction. c.) Check Transaction Status: Use the "Transaction API → Check Status of transaction by customer unique correlation ID" to check the status of the transaction. This API likely requires a unique correlation ID associated with the transaction to identify and retrieve its status. d.) Get Final Result: After the 120 seconds timeout, use the unique correlation ID to query the status of the transaction via the "Transaction API". This should give you the final result of the top-up transaction.

2.) To generate Timeout error for 90 seconds, follow the below steps: a.) Initiate Top-up: Start the process to top up the mobile number ending with "555555". b.) Wait for 90 Seconds: Allow the system 90 seconds to process the transaction. c.) Check Transaction Status: Use the "Transaction API → Check Status of transaction by customer unique correlation ID" to check the status of the transaction. This API requires a unique correlation ID associated with the transaction to identify and retrieve its status. d.) Get Final Result: After the 90-second timeout, use the unique correlation ID to query the status of the transaction via the "Transaction API → Check Status of transaction by customer unique correlation ID". This should give you the final result of the top-up transaction.

Scenarios to generate other errors:

3.) Out of Stock sku Error: Mobile Number should end with "510" to generate "Out of Stock" Error Request:

POST https://{HostName}/api/v1/transaction/topup HTTP/1.1
Authorization: Basic c3VwcmVldGFwaTp0ZXN0MTIzNA==
Content-Type: application/json

{
    "skuId": 1451,
    "correlationId": "dinesh666677",
    "mobile": "93989876510",
    "amount": 9,
    "transactionCurrencyCode": "USD"
}

Response:

{
    "responseCode": "510",
    "responseMessage": "The Sku is out of stock",
    "payLoad": null
}

4.) Invalid Denomination Error: mobile number start with "1876" and end with "888" having skuid=193 and amount < 4

Request:

POST https://{HostName}/api/v1/transaction/topup HTTP/1.1
Authorization: Basic c3VwcmVldGFwaTp0ZXN0MTIzNA==
Content-Type: application/json

{
    "skuId": 193,
    "correlationId": "dinesh666677",
    "mobile": "18763351888",
    "amount": 4,
    "transactionCurrencyCode": "USD"
}

Response:

{
    "responseCode": "001",
    "responseMessage": "The charge amount for Denomination Digicel Jamaica should be between 5.00 USD and 100.00 USD",
    "payLoad": null
}

5.) Account Not Activated Error: Mobile Number ending with "500" Request:

POST https://{HostName}/api/v1/transaction/topup HTTP/1.1
Authorization: Basic c3VwcmVldGFwaTp0ZXN0MTIzNA==
Content-Type: application/json                
{
    "skuId": 1451,
    "correlationId": "dinesh666677",
    "mobile": "93989876500",
    "amount": 9,
    "transactionCurrencyCode": "USD"
}

Response:

 {
    "responseCode": "500",
    "responseMessage": "The Account was not activated. a) Possible reasons are: Subscriber number is not found. b) Subscriber account is suspended c) Carrier's experienced internal error. Please try again",
    "payLoad": null
 }

The API endpoints are prefixed with a version number to ensure seamless integration and to guarantee that future major changes to the API won't disrupt existing integrations. Within a major version, no breaking changes will be introduced, thus ensuring stability and compatibility. Further details regarding this distinction are elaborated in the subsequent subsection.

Non-Breaking Changes

Also referred to as backward-compatible alterations, these changes enable your integration to function seamlessly without necessitating additional adjustments on your end. They do not mandate a new version number and are implemented without prior notification.

Changes falling under this category are primarily "additive" in nature, as exemplified below:

• Introduction of new API endpoints
• Inclusion of optional fields in the request body and/or header
• Addition of fields to the response body and/or header
• Data modifications, including:
  • Addition of new Countries / Operators / Products / Services
  • Alteration of text and/or numeric field values, such as:
    • Country / Operator / Product / Service Names
    • Wholesale / Retail Prices and/or Rates
    • Status and Error Descriptions

💡 Before deploying, it is crucial to ensure that your integration is capable of accommodating non-breaking API changes to minimize potential disruptions to your service.

Breaking Changes

Conversely, breaking changes requires adjustments to how your integration functions. These adjustments usually happen when there are significant updates to the API, aimed at improving features or the platform. However, with the endpoints of the API prefixed with a corresponding version number, your existing integration is protected from any disruption due to the complete isolation of implementation differences between versions.

Examples of changes falling under this category include:

• Removal and/or renaming of API endpoints
• Addition of required fields to request body and/or header
• Removal and/or renaming of fields from request body and/or header
• Removal and/or renaming of fields from response body and/or header

💡 Upon the availability of a new API version, it is advisable to conduct testing in a sandbox environment to ensure seamless compatibility with your implementation before transitioning to the production environment.

Some operators require customers to pay their outstanding loan amount during a bundle purchase. This scenario follows a specific transaction flow, referred to as a two-step process.

Step 1: Fetch Bundle API

Begin by calling the /catalog/bundles/ API. This API returns:

• Bundles applicable to the customer's number
• Loan information, if the customer has any outstanding dues

This ensures that the system can determine whether a loan payment is required before proceeding with the bundle purchase.

Step 2: Perform Bundle Purchase

If the response from Step 1 indicates that a loan payment is necessary, the bundle purchase must be executed in two steps:

• The amount must include both the Face Value and Loan Amount
• Pass this information along with the correct skuId, mobile number and transaction Currency to the /transaction/topup/ API

Reference Document

We’ve prepared a detailed document outlining:

• Step-by-step instructions
• Sequence diagram for the two-step flow

👉 Click here to open this document

The following APIs now support localization:

1. Catalog SKUs: /api/v2/catalog/skus
2. Catalog GiftCards: /api/v2/catalog/skus/giftcards
3. Mobile Number Lookup: /api/v2/lookup/mobile/{mobile}

The fields below are returned in a localized format based on the requested language:

• SkuName
• ProductName
• BenefitType
• ProductDescription
• OperatorName
• AdditionalInformation

By default, API responses are provided in English. However, the system now supports additional languages such as Arabic.

To receive the response in another supported language (e.g., Arabic), the client must include the "Accept-Language" in header with the appropriate language code.

For Arabic, use 'ar'