Skip to main content

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 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": [
    ]
}

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
}

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 SkuId can be obtained by the “/catalog/skus/” API. The category of the carrier should be ‘eSIM’

correlationId
required
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 phone number with a valid country code from these countries for testing purposes in the Sandbox environment.

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 SkuId, obtained from the Product API, along with the amount, mobile, and correlationId. It's crucial for the agent to include a correlationId, 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
required
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

This field is optional. 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. 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
required
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 SkuId 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 pf Postpaid Mobile Bill

mobileNumber
string or null

Mobile Number

checkDigits
string or null

Check digits

correlationId
required
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 is used to check status of Transaction Status. 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 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. 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
correlationId
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/{correlationId}" \
  -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/{correlationId}) 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
required
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

This field is optional. 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": {
    }
}

Sim Activation

This operation is used to activate sim.

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

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

simNumber
required
string non-empty

Sim Number

zipCode
required
integer <int32>

Zip Code

language
string or null

Language

email
string or null

Email

correlationId
required
string [ 1 .. 50 ] characters

Unique Id of Customer System

numberOfPlanMonths
integer <int32>

This field is used to buy Lyca Bundle for multiple Months.

areaCode
string or null

Area Code

imei
string or null

IMEI

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,
  • "simNumber": "",
  • "zipCode": 0,
  • "language": "",
  • "email": "",
  • "correlationId": "",
  • "numberOfPlanMonths": 0,
  • "areaCode": "",
  • "imei": "",
  • "additionalInfos": [
    ]
}

Response samples

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

Sim Port in

This operation is used to port in Sim.

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

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

simNumber
required
string non-empty

Sim Number

zipCode
required
integer <int32>

Zip Code

language
string or null

Language

email
string or null

Email

correlationId
required
string [ 1 .. 50 ] characters

Unique Id of Customer System

numberOfPlanMonths
integer <int32>

Number of Plan Months

areaCode
string or null <= 3 characters

Area Code

imei
string or null

IMEI

operatorCode
string or null

Operator Code

mobileNumber
string or null

Mobile Number which need to be port

accountNumber
string or null

Account Number of existsing carrier

passwordPin
string or null

Password

firstName
string or null

First Name

lastName
string or null

Last Name

address
string or null

Address

city
string or null

City

state
string or null

State

accountHolderZip
string or null

Account Holder Zip

equipmentType
string or null

Equipement Type

streetNumber
string or null

Street Number

streetName
string or null

Street Name

contactNumber
string or null

Contact Number

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,
  • "simNumber": "",
  • "zipCode": 0,
  • "language": "",
  • "email": "",
  • "correlationId": "",
  • "numberOfPlanMonths": 0,
  • "areaCode": "",
  • "imei": "",
  • "operatorCode": "",
  • "mobileNumber": "",
  • "accountNumber": "",
  • "passwordPin": "",
  • "firstName": "",
  • "lastName": "",
  • "address": "",
  • "city": "",
  • "state": "",
  • "accountHolderZip": "",
  • "equipmentType": "",
  • "streetNumber": "",
  • "streetName": "",
  • "contactNumber": "",
  • "additionalInfos": [
    ]
}

Response samples

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

Check Port in Status

This operation is used to check port in status

Authorizations:
basic
path Parameters
id
required
integer <int64>

Transaction Id which you received from Port In response

Responses

Request samples 

curl -X GET "https://sandbox.valuetopup.com/api/v2/transaction/sim/portin/status/{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 SkuId 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

This field is optional. 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. 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": {
    }
}