Skip to main content

Account

Check Balance

This operation return customer balance.

Authorizations:
basic

Responses

Request samples 

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

Response samples

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

Catalog

Retrive list of products

This operation return all products with their sku Id.

Authorizations:
basic
query Parameters
productid
integer <int32>

Responses

Request samples 

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

Response samples

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

Get description of Skus

Get description of Skus

Authorizations:
basic
query Parameters
skuId
integer <int32>

Sku Id

productId
integer <int32>

Product Id

Responses

Request samples 

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

Response samples

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

Mobile Number Lookup

Retrieve list of products by using mobile number.

Authorizations:
basic
path Parameters
mobile
required
integer <int64>

Mobile Number with country code

Responses

Request samples 

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

Response samples

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

Current Promotions

Date Time Display As Per Destination Country Time Zone

Authorizations:
basic

Responses

Request samples 

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

Response samples

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

Upcoming promotions

Date Time Display As Per Destination Country Time Zone

Authorizations:
basic

Responses

Request samples 

curl -X GET "https://sandbox.valuetopup.com/api/v1/catalog/promotion/upcoming" \
  -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 denomination

Authorizations:
basic
path Parameters
skuId
required
integer <int32>

Sku Id

Responses

Request samples 

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

Response samples

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

Get image of product

Get image of Skus

Authorizations:
basic
query Parameters
skuId
integer <int32>

Sku Id - it is optional

productId
integer <int32>

Product Id - it is optional

Responses

Request samples 

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

Response samples

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

Fetch List of error codes

Authorizations:
basic

Responses

Request samples 

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

Response samples

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

Fetch List of carriers

Authorizations:
basic
query Parameters
countryCode
string
Default: ""
currencyCode
string
Default: ""

Responses

Request samples 

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

Response samples

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

Fetch List of Countries

Authorizations:
basic

Responses

Request samples 

curl -X GET "https://sandbox.valuetopup.com/api/v1/catalog/countries" \
  -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 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/v1/esim/status/{Iccid}" \
  -H "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
  -H "Accept: application/json"

Response samples

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

Transaction

Mobile Topup

This operation is used to perform Topup on Mobile number.

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 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/v1/transaction/billpay/fetch-account-detail" \
  -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 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 customer unique correlation ID

This operation is used to check status of Transaction Status. This is very useful API method to check status of orignal 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.

Special consideration is needed for the Response Code. If the Response Code is “000”, the transaction has been successfully processed. If the Response code is “852”, that means the transaction is under execution. In both cases the transaction cannot be assumed to be complete.

Prepaynation 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/v1/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/v1/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/v1/transaction/sim/portin/status/{id}" \
  -H "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
  -H "Accept: application/json"

Response samples

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