Skip to main content
API docs by Redocly

ValueTopup API (v2)

Download OpenAPI specification:Download

E-mail: [email protected]

Valuetopup API Specification v2

Account

Check Balance

This method provides a real-time balance. For prepaid terms with Prepay Nation, the balance is returned with a negative sign to indicate available funds. For credit terms, the balance indicates the amount owed.

The transaction will only proceed if your wallet contains sufficient funds. We strongly advise utilizing this API method to monitor your wallet.

Authorizations:
basic

Responses

Request samples 

curl -X GET "https://sandbox.valuetopup.com/api/v2/account/balance" \
  -H "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
  -H "Accept: application/json"

Response samples

Content type
application/json
{
  • "responseCode": "",
  • "responseMessage": "",
  • "payLoad": 0.1
}

Catalog

Get a list of Countries

This method can be utilized to retrieve a list of all available countries.

Authorizations:
basic

Responses

Request samples 

curl -X GET "https://sandbox.valuetopup.com/api/v2/catalog/countries" \
  -H "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
  -H "Accept: application/json"

Response samples

Content type
application/json
{
  • "responseCode": "",
  • "responseMessage": "",
  • "payLoad": [
    ]
}

Get Operators List

Return the operators list

Authorizations:
basic
query Parameters
operatorId
integer <int32>

Operator Id

countryCode
string

Country Code

Responses

Request samples 

curl -X GET "https://sandbox.valuetopup.com/api/v2/catalog/operators" \
  -H "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
  -H "Accept: application/json"

Response samples

Content type
application/json
{
  • "responseCode": "",
  • "responseMessage": "",
  • "payLoad": [
    ]
}

Get a list of Products

Get a list of products available to the agent. You can use OperatorId to get a list of products from /getproducts API. Available Category Id Values: Pin = 1, Rtr = 2, Bill Pay = 4, Sim = 5, Gift Card = 6, eSim = 7.

Authorizations:
basic
query Parameters
operatorId
integer <int32>

Operator Id

categoryId
integer <int32>

Category Id

countryCode
string

Country Code

Responses

Request samples 

curl -X GET "https://sandbox.valuetopup.com/api/v2/catalog/getproducts" \
  -H "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
  -H "Accept: application/json"

Response samples

Content type
application/json
{
  • "responseCode": "",
  • "responseMessage": "",
  • "payLoad": [
    ]
}

Get list of SKUs

This operation retrieves all products except Gift Card along with their SKU IDs.

Authorizations:
basic
query Parameters
productId
integer <int32>
skuId
integer <int32>
header Parameters
Accept-Language
string

Language code for localized responses (for eg 'ar').

Refer Localization and Multilingual Response Support section for more details.

Responses

Request samples 

curl -X GET "https://sandbox.valuetopup.com/api/v2/catalog/skus" \
  -H "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
  -H "Accept: application/json"

Response samples

Content type
application/json
{
  • "responseCode": "",
  • "responseMessage": "",
  • "payLoad": [
    ]
}

Get list of Gift Card SKUs

This operation retrieves all Gift Card products along with their SKU IDs.

Note: If neither cursor nor a pageSize is provided, the default response will display only 100 Gift Card SKUs.

Authorizations:
basic
query Parameters
cursor
integer <int32>

The cursor is used to retrieve the next set of SKUs. For example, cursor=10, will retrieve SKUs starting from skuId : 10 based on the specified page size.

pageSize
integer <int32>

The number of items to retrieve starting with the cursor. The page size must be at least 1 and not more than 100.

productId
integer <int32>

Product Id - The ProductId can be obtained by the “/catalog/getproducts/” API.

skuId
integer <int32>

SKU ID of denomination

countryCode
string

ISO Country Code e.g. IN for India

header Parameters
Accept-Language
string

Language code for localized responses (for eg 'ar').

Refer Localization and Multilingual Response Support section for more details.

Responses

Request samples 

curl -X GET "https://sandbox.valuetopup.com/api/v2/catalog/skus/giftcards" \
  -H "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
  -H "Accept: application/json"

Response samples

Content type
application/json
{
  • "responseCode": "",
  • "responseMessage": "",
  • "payLoad": [
    ],
  • "next": 0,
  • "next_cursor": 0
}

Get Exchange Rate

Return the most current exchange of a SKU

Authorizations:
basic
path Parameters
skuId
required
integer <int32>

SKU ID

Responses

Request samples 

curl -X GET "https://sandbox.valuetopup.com/api/v2/catalog/sku/exchangeRate/{skuId}" \
  -H "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
  -H "Accept: application/json"

Response samples

Content type
application/json
{
  • "responseCode": "",
  • "responseMessage": "",
  • "payLoad": {
    }
}

Get a list of Error Codes

Authorizations:
basic

Responses

Request samples 

curl -X GET "https://sandbox.valuetopup.com/api/v2/catalog/errors" \
  -H "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
  -H "Accept: application/json"

Response samples

Content type
application/json
{
  • "responseCode": "",
  • "responseMessage": "",
  • "payLoad": [
    ]
}

Get list of Bundles

This operation returns list of dynamic bundles

Authorizations:
basic
path Parameters
productId
required
integer <int32>
mobileNumber
required
string

Responses

Request samples 

curl -X GET "https://sandbox.valuetopup.com/api/v2/catalog/bundles/{productId}/{mobileNumber}" \
  -H "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
  -H "Accept: application/json"

Response samples

Content type
application/json
{
  • "responseCode": "",
  • "responseMessage": "",
  • "payLoad": [
    ]
}

eSIM

eSIM Transaction

This operation is used to buy eSIM products

Authorizations:
basic
Request Body schema: application/json
skuId
required
integer <int32>

SKU ID - The SKU ID can be obtained by the “/catalog/skus/” API. The category of the carrier should be ‘eSIM’

correlationId
string [ 1 .. 50 ] characters

Unique ID of Customer System

Responses

Request samples

Content type
application/json
{
  • "skuId": 0,
  • "correlationId": ""
}

Response samples

Content type
application/json
{
  • "responseCode": "",
  • "responseMessage": "",
  • "payLoad": {
    }
}

Get Remaining Data Balance of Bundle

This operation is used to check the current data balance of eSIM

Authorizations:
basic
path Parameters
Iccid
required
string

Iccid which you received from eSIM order response

Responses

Request samples 

curl -X GET "https://sandbox.valuetopup.com/api/v2/esim/status/{Iccid}" \
  -H "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
  -H "Accept: application/json"

Response samples

Content type
application/json
{
  • "responseCode": "",
  • "responseMessage": "",
  • "payLoad": [
    ]
}

Lookup

Mobile Number Lookup

Get operator and product information for a specific mobile number. Pass mobile number along with country code to validate MSISDN.

Sandbox environment - We only support phone number lookup for Jamaica, India, Pakistan, and Mexico. Please utilize any of the below phone numbers for testing purposes in the Sandbox environment.

Jamaica - 18761234567, 18762234567
India - 911234567890, 912345678901
Pakistan - 923123456789 , 923234578901
Mexico - 5212345678901, 522345678901.

Production environment - We provide support for all countries excluding the United States and Spain.

Note: Providing end users with the choice to make a final operator selection is crucial. Occasionally, the results obtained from a lookup request may not accurately reflect the most up-to-date information, particularly after a recent porting of the mobile number to a new operator. Introducing this extra step enhances accuracy and enhances the user experience as a whole.

Authorizations:
basic
path Parameters
mobile
required
integer <int64>

Mobile Number with country code

header Parameters
Accept-Language
string

Language code for localized responses (for eg 'ar').

Refer Localization and Multilingual Response Support section for more details.

Responses

Request samples 

curl -X GET "https://sandbox.valuetopup.com/api/v2/lookup/mobile/{mobile}" \
  -H "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
  -H "Accept: application/json"

Response samples

Content type
application/json
{
  • "responseCode": "",
  • "responseMessage": "",
  • "payLoad": [
    ]
}

Bill Payment

This operation is used to fetch bill detail

Authorizations:
basic
query Parameters
skuId
integer <int32>

Sku Id of Product

accountNumber
string

bill account number

Responses

Request samples 

curl -X GET "https://sandbox.valuetopup.com/api/v2/lookup/billpay/fetch-account-detail" \
  -H "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
  -H "Accept: application/json"

Response samples

Content type
application/json
{
  • "responseCode": "",
  • "responseMessage": "",
  • "payLoad": {
    }
}

Promotion

Get a List of current promotions

Retrieve a list of all currently active promotions.

Authorizations:
basic

Responses

Request samples 

curl -X GET "https://sandbox.valuetopup.com/api/v2/promotion/current" \
  -H "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
  -H "Accept: application/json"

Response samples

Content type
application/json
{
  • "responseCode": "",
  • "responseMessage": "",
  • "payLoad": [
    ]
}

Get a List of Upcoming promotions

Retrieve a list of all future promotions.

Authorizations:
basic

Responses

Request samples 

curl -X GET "https://sandbox.valuetopup.com/api/v2/promotion/upcoming" \
  -H "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
  -H "Accept: application/json"

Response samples

Content type
application/json
{
  • "responseCode": "",
  • "responseMessage": "",
  • "payLoad": [
    ]
}

Transaction

Mobile Topup

This operation facilitates mobile number top-up. Agents can initiate this request by providing the SKU ID, obtained from the Product API, along with the amount, mobile, and corelationId. It's crucial for the agent to include a correlation ID, serving as a unique transaction identifier within their system, which can be utilized for reconciliation purposes.

Sandbox Environment: For testing purposes, any number can be passed. However, it's essential to ensure that the mobile number adheres to country-specific formatting guidelines. For example, in Jamaica, the country code is 1876, and the number length is 7 digits. Thus, any number in the format 1876XXXXXXX can be used.

Authorizations:
basic
Request Body schema: application/json

Topup request

skuId
required
integer <int32>

Sku Id - The SkuId can be obtained by the Products API. The category of the carrier should be ‘RTR’

amount
required
number <double>

Top-up Amount - It is by default in Customer Wallet Currency if "transactionCurrencyCode" is not defined. Otherwise, it is based on the "transactionCurrencyCode" field. For example, if the Customer wallet currency is GBP and "TransactionCurrencyCode" is not specified, then the system considers the amount in GBP. However, the customer can send the amount in the destination currency by defining the destination currency code in the "transactionCurrencyCode" field, for example, INR for India or NGN for Nigeria.

mobile
required
string non-empty

Mobile number of the subscriber. it should be as per carrier guideline.

correlationId
string [ 1 .. 50 ] characters

Unique ID of Customer System

senderMobile
string or null

Sender Mobile Number

boostPin
string or null [ 0 .. 6 ] characters

4 to 6 digits PIN of Boost Mobile number. This is required only when recharge is for Boost Mobile.

numberOfPlanMonths
integer <int32>

This field is used to buy Lyca Bundle for multiple Months. E.g. If user wants to buy 19 USD Lyca Bundle for 3 months then request should contain 3.

transactionCurrencyCode
string or null

It is used to send amount in destination currency. If customer want to send amount in destination country currency then pass ISO currency code of that country in this field. You should check FaceValueCurrency field of /catalog/skus api to check what currency you can pass in this field.
e.g. customer wants to send amount in NGN currency. Then he will pass "NGN"

Array of objects or null (AdditionalInfo)

Some product requires additional information to process transactions. you need to provide that information here in name value pair. You can get this information from Catalog

Responses

Request samples

Content type
application/json
{
  • "skuId": 0,
  • "amount": 0.1,
  • "mobile": "",
  • "correlationId": "",
  • "senderMobile": "",
  • "boostPin": "",
  • "numberOfPlanMonths": 0,
  • "transactionCurrencyCode": "",
  • "additionalInfos": [
    ]
}

Response samples

Content type
application/json
{
  • "responseCode": "",
  • "responseMessage": "",
  • "payLoad": {
    }
}

Pin Transaction

This operation is used to buy PIN products

Authorizations:
basic
Request Body schema: application/json

Pin Request Object

skuId
required
integer <int32>

Sku Id - The SkuId can be obtained by the Products API. The category of the carrier should be PIN

correlationId
string [ 1 .. 50 ] characters

Unique ID of Customer System

recipient
string or null

System will use this information to deliver PIN through SMS. Pass mobile number along with country code.Mobile number must belong to same country for which you are buying PIN.e.g.ATT PIN - 1XXXXXXXXXX

Array of objects or null (AdditionalInfo)

Some product requires additional information to process transactions. you need to provide that information here in name value pair. You can get this information from Catalog

Responses

Request samples

Content type
application/json
{
  • "skuId": 0,
  • "correlationId": "",
  • "recipient": "",
  • "additionalInfos": [
    ]
}

Response samples

Content type
application/json
{
  • "responseCode": "",
  • "responseMessage": "",
  • "payLoad": {
    }
}

Bill Payment

This operation is used to perform Bill Payment

Authorizations:
basic
Request Body schema: application/json
skuId
required
integer <int32>

SKU ID - The SKU ID can be obtained by the Products API. The category of the carrier should be billpay

amount
required
number <double>

Topup Amount

accountNumber
required
string non-empty

Account number on the Bill or Mobile number in case of Postpaid Mobile Bill

mobileNumber
string or null

Mobile Number

checkDigits
string or null

Check digits

correlationId
string [ 1 .. 50 ] characters

Unique Id of Customer

senderMobile
string or null

Sender Mobile

senderName
string or null

Sender Name

transactionCurrencyCode
string or null <= 3 characters

It tells us currency of "Amount". If it is null or empty then system considers customer wallet currency

Array of objects or null (AdditionalInfo)

Some product requires additional information to process transactions. you need to provide that information here in name value pair. You can get this information from Catalog

Responses

Request samples

Content type
application/json
{
  • "skuId": 0,
  • "amount": 0.1,
  • "accountNumber": "",
  • "mobileNumber": "",
  • "checkDigits": "",
  • "correlationId": "",
  • "senderMobile": "",
  • "senderName": "",
  • "transactionCurrencyCode": "",
  • "additionalInfos": [
    ]
}

Response samples

Content type
application/json
{
  • "responseCode": "",
  • "responseMessage": "",
  • "payLoad": {
    }
}

Check Status of transaction by correlation ID

This operation checks the final status of a transaction using its correlation ID. This is very useful API method to check status of original transaction in case if you don't get response of original transaction within the timeout set by your system. To know the correct and final status of the original transaction we recommend that you to implement this API method to check status. This method will return you final status of the original transaction.

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

If the response code is "852," it means the transaction is still in progress. Any other response code should be considered the final status of the transaction. This could either be successful ("000") or failed (any code other than "000").

Prepay nation Timeout = 2 minute

Authorizations:
basic
path Parameters
corelationId
required
string

Correlation ID which you send in actual topup API method.

Responses

Request samples 

curl -X GET "https://sandbox.valuetopup.com/api/v2/transaction/status/{corelationId}" \
  -H "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
  -H "Accept: application/json"

Response samples

Content type
application/json
{
  • "responseCode": "",
  • "responseMessage": "",
  • "payLoad": {
    }
}

Gift Card

This operation is used to buy Gift Card.

Important Note: Gift Card processing may take longer than usual. If you receive response code 852 with the message "Gift Card processing is in progress." it means the transaction is still being processed. In this case, you must check the transaction status using the Check Status API (/transaction/status/{corelationId}) to obtain the final result. Please refer to the "Check Status of transaction by correlation ID" endpoint documentation for more details.

Response code 852 indicates the transaction is in progress. Any other response code represents the final transaction status - either success (000) or failure (any code other than 000).

Authorizations:
basic
Request Body schema: application/json

Gift Card Object

skuId
required
integer <int32>

Sku Id - The SkuId can be obtained by the Products API. The category of the product should be Giftcard

amount
required
number <double>

Amount

correlationId
string [ 1 .. 50 ] characters

Unique ID of Customer System

firstName
string or null

First Name

lastName
string or null

Last Name

recipient
string or null

Mobile Number

transactionCurrencyCode
string or null

It is used to send amount in destination currency. If customer wanted to send amount in destination country currency than pass ISO currency code of that country in this field. e.g. customer wants to send amount in NGN currency. Then he will pass "NGN"

Array of objects or null (AdditionalInfo)

Some product requires additional information to process transactions. you need to provide that information here in name value pair. You can get this information from Catalog

Responses

Request samples

Content type
application/json
{
  • "skuId": 0,
  • "amount": 0.1,
  • "correlationId": "",
  • "firstName": "",
  • "lastName": "",
  • "recipient": "",
  • "transactionCurrencyCode": "",
  • "additionalInfos": [
    ]
}

Response samples

Content type
application/json
{
  • "responseCode": "",
  • "responseMessage": "",
  • "payLoad": {
    }
}

Fetch Gift Card information

Authorizations:
basic
path Parameters
id
required
integer <int64>

Transaction Id which you receive in Gift Card Operation

Responses

Request samples 

curl -X GET "https://sandbox.valuetopup.com/api/v2/transaction/giftcard/fetch/{id}" \
  -H "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
  -H "Accept: application/json"

Response samples

Content type
application/json
{
  • "responseCode": "",
  • "responseMessage": "",
  • "payLoad": {
    }
}

Estimated Cost

This operation is used to get the estimate cost of product

Authorizations:
basic
Request Body schema: application/json

Cost request

skuId
required
integer <int32>

SKU ID - The SKU ID can be obtained by the Products API.

amount
required
number <double>

Amount - It is by default in Customer Wallet Currency if "transactionCurrencyCode" is not defined. Otherwise, it is based on the "transactionCurrencyCode" field. For example, if the Customer wallet currency is GBP and "TransactionCurrencyCode" is not specified, then the system considers the amount in GBP. However, the customer can send the amount in the destination currency by defining the destination currency code in the "transactionCurrencyCode" field, for example, INR for India or NGN for Nigeria.

transactionCurrencyCode
string or null

It is used to send amount in destination currency. If you want to send the amount in the destination country's currency then pass ISO currency code of that country in this field. You should check FaceValueCurrency field of /catalog/skus API to check what currency you can pass in this field.
e.g. customer wants to send amount in NGN currency. Then he will pass "NGN". The 'TransactionCurrencyCode' must be in uppercase (e.g. USD, AFN, EUR, etc.)

Responses

Request samples

Content type
application/json
{
  • "skuId": 0,
  • "amount": 0.1,
  • "transactionCurrencyCode": ""
}

Response samples

Content type
application/json
{
  • "responseCode": "",
  • "responseMessage": "",
  • "payLoad": {
    }
}