Valuetopup API Specification (v2)

Download OpenAPI specification:Download

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

200

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

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": [{"countryCode": "",
"countryName": "",
"region": "",
"internationalCountryCode": "",
"areaCodes": "",
"numberLength": ""
}
]
}

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

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": [{"operatorId": 0,
"operatorName": "",
"imageUrl": ""
}
]
}

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

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": [{"productId": 0,
"category": "",
"productName": "",
"countryCode": "",
"operatorId": 0,
"operatorName": "",
"imageUrl": "",
"requireFetchBundle": true,
"description": ""
}
]
}

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 to Localization and Multilingual Response Support 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

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": [{"skuId": 0,
"skuName": "",
"min": {"faceValue": 0.1,
"faceValueCurrency": "",
"deliveredAmount": 0.1,
"deliveryCurrencyCode": "",
"faceValueInWalletCurrency": 0.1
},
"max": {"faceValue": 0.1,
"faceValueCurrency": "",
"deliveredAmount": 0.1,
"deliveryCurrencyCode": "",
"faceValueInWalletCurrency": 0.1
},
"exchangeRate": 0.1,
"loanAmountInFaceValueCurrency": 0.1,
"loanAmountInDeliveryCurrency": 0.1,
"loanAmountInWalletCurrency": 0.1,
"productId": 0,
"productName": "",
"category": "",
"isSalesTaxCharged": true,
"salesTax": 0.1,
"countryCode": "",
"benefitType": "",
"validity": "",
"productDescription": "",
"localPhoneNumberLength": 0,
"internationalCountryCode": ["string"
],
"allowDecimal": true,
"fee": 0.1,
"operatorId": 0,
"operatorName": "",
"imageUrl": "",
"additionalInformation": "",
"region": "",
"deliveryAmountType": "",
"subCategory": "",
"requireFetchBundle": true
}
]
}

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

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": {"skuId": 0,
"productName": "",
"currencyCode": "",
"exchangeRate": 0.1
}
}

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

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": [{"errorCode": "",
"errorDescription": ""
}
]
}

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

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": [{"skuId": 0,
"skuName": "",
"min": {"faceValue": 0.1,
"faceValueCurrency": "",
"deliveredAmount": 0.1,
"deliveryCurrencyCode": "",
"faceValueInWalletCurrency": 0.1
},
"max": {"faceValue": 0.1,
"faceValueCurrency": "",
"deliveredAmount": 0.1,
"deliveryCurrencyCode": "",
"faceValueInWalletCurrency": 0.1
},
"exchangeRate": 0.1,
"loanAmountInFaceValueCurrency": 0.1,
"loanAmountInDeliveryCurrency": 0.1,
"loanAmountInWalletCurrency": 0.1,
"productId": 0,
"productName": "",
"category": "",
"isSalesTaxCharged": true,
"salesTax": 0.1,
"countryCode": "",
"benefitType": "",
"validity": "",
"productDescription": "",
"localPhoneNumberLength": 0,
"internationalCountryCode": ["string"
],
"allowDecimal": true,
"fee": 0.1,
"operatorId": 0,
"operatorName": "",
"imageUrl": "",
"additionalInformation": "",
"region": "",
"deliveryAmountType": "",
"subCategory": "",
"requireFetchBundle": true
}
]
}

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 to the 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

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": [{"skuId": 0,
"skuName": "",
"min": {"faceValue": 0.1,
"faceValueCurrency": "",
"deliveredAmount": 0.1,
"deliveryCurrencyCode": "",
"faceValueInWalletCurrency": 0.1
},
"max": {"faceValue": 0.1,
"faceValueCurrency": "",
"deliveredAmount": 0.1,
"deliveryCurrencyCode": "",
"faceValueInWalletCurrency": 0.1
},
"exchangeRate": 0.1,
"loanAmountInFaceValueCurrency": 0.1,
"loanAmountInDeliveryCurrency": 0.1,
"loanAmountInWalletCurrency": 0.1,
"productId": 0,
"productName": "",
"category": "",
"isSalesTaxCharged": true,
"salesTax": 0.1,
"countryCode": "",
"benefitType": "",
"validity": "",
"productDescription": "",
"localPhoneNumberLength": 0,
"internationalCountryCode": ["string"
],
"allowDecimal": true,
"fee": 0.1,
"operatorId": 0,
"operatorName": "",
"imageUrl": "",
"additionalInformation": "",
"region": "",
"deliveryAmountType": "",
"subCategory": "",
"requireFetchBundle": true
}
],
"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

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": {"transactionId": 0,
"transactionDate": "",
"invoiceAmount": 0.1,
"faceValue": 0.1,
"discount": 0.1,
"fee": 0.1,
"product": {"skuId": 0,
"productName": "",
"faceValue": 0.1,
"instructions": "",
"productDescription": ""
},
"topupDetail": {"localCurrencyAmount": 0.1,
"salesTaxAmount": 0.1,
"localCurrencyAmountExcludingTax": 0.1,
"destinationCurrency": "",
"operatorTransactionId": ""
},
"pins": [{"pinNumber": "",
"controlNumber": "",
"deliveredAmount": 0.1,
"deliveredCurrencyCode": "",
"expirationDate": ""
}
],
"giftCardDetail": {"cardNumber": "",
"pin": "",
"expirationDate": "",
"certificateLink": ""
},
"simInfo": {"simNumber": "",
"language": "",
"zipCode": "",
"mobileNumber": ""
},
"billPaymentDetail": {"accountNumber": "",
"token": "",
"unit": "",
"receivedNarration": ""
},
"esimDetail": {"iccid": "",
"activationCode": "",
"smdpAddress": "",
"confirmationCode": "",
"qrCodeString": "",
"qrCodeLink": ""
}
}
}

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

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": [{"name": "",
"description": "",
"initialQuantity": 0,
"remainingQuantity": 0,
"assignmentDateTime": "",
"startTime": "",
"endTime": "",
"assignmentReference": "",
"unit": "",
"activationCode": "",
"smdpAddress": ""
}
]
}

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 to the 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

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": [{"productId": 0,
"productName": "",
"countryCode": "",
"operatorId": 0,
"operatorName": "",
"imageUrl": "",
"skus": [{"skuId": 0,
"skuName": "",
"min": {"faceValue": 0.1,
"faceValueCurrency": "",
"deliveredAmount": 0.1,
"deliveryCurrencyCode": "",
"faceValueInWalletCurrency": 0.1
},
"max": {"faceValue": 0.1,
"faceValueCurrency": "",
"deliveredAmount": 0.1,
"deliveryCurrencyCode": "",
"faceValueInWalletCurrency": 0.1
},
"exchangeRate": 0.1,
"loanAmountInFaceValueCurrency": 0.1,
"loanAmountInDeliveryCurrency": 0.1,
"loanAmountInWalletCurrency": 0.1,
"productId": 0,
"productName": "",
"category": "",
"isSalesTaxCharged": true,
"salesTax": 0.1,
"countryCode": "",
"benefitType": "",
"validity": "",
"productDescription": "",
"localPhoneNumberLength": 0,
"internationalCountryCode": ["string"
],
"allowDecimal": true,
"fee": 0.1,
"operatorId": 0,
"operatorName": "",
"imageUrl": "",
"additionalInformation": "",
"region": "",
"deliveryAmountType": "",
"subCategory": "",
"requireFetchBundle": true
}
]
}
]
}

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

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": {"accountNumber": "",
"customerName": "",
"balanceDue": 0.1,
"currencyCode": "",
"dueDate": ""
}
}

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

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": [{"promotionId": 0,
"promotionName": "",
"countryTimeZone": "",
"startDate": "",
"endDate": "",
"description": "",
"restriction": "",
"promotionalBalanceExpiration": "",
"promotionMinMax": [{"currencyCode": "",
"minAmount": 0.1,
"maxAmount": 0.1
}
],
"product": {"productId": 0,
"productName": "",
"countryCode": "",
"operatorName": ""
},
"operator": {"operatorId": 0,
"operatorName": "",
"countryCode": "",
"countryName": ""
}
}
]
}

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

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": [{"promotionId": 0,
"promotionName": "",
"countryTimeZone": "",
"startDate": "",
"endDate": "",
"description": "",
"restriction": "",
"promotionalBalanceExpiration": "",
"promotionMinMax": [{"currencyCode": "",
"minAmount": 0.1,
"maxAmount": 0.1
}
],
"product": {"productId": 0,
"productName": "",
"countryCode": "",
"operatorName": ""
},
"operator": {"operatorId": 0,
"operatorName": "",
"countryCode": "",
"countryName": ""
}
}
]
}

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. Important Note: ⚠️ For fixed-denomination SKUs, if `transactionCurrencyCode` is not provided or is the same as your wallet currency code, then the `amount` is not validated against the product's allowed fixed denominations. Sending an amount that does not match a valid fixed denomination will not be rejected by the API under these conditions. Always pass `transactionCurrencyCode` when ordering a fixed-denomination product, or verify `amount` against the denomination / FaceValueCurrency values returned by `/catalog/skus` before submitting the request.
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": [{"name": "",
"value": ""
}
]
}

Response samples

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": {"transactionId": 0,
"transactionDate": "",
"invoiceAmount": 0.1,
"faceValue": 0.1,
"discount": 0.1,
"fee": 0.1,
"product": {"skuId": 0,
"productName": "",
"faceValue": 0.1,
"instructions": "",
"productDescription": ""
},
"topupDetail": {"localCurrencyAmount": 0.1,
"salesTaxAmount": 0.1,
"localCurrencyAmountExcludingTax": 0.1,
"destinationCurrency": "",
"operatorTransactionId": ""
},
"pins": [{"pinNumber": "",
"controlNumber": "",
"deliveredAmount": 0.1,
"deliveredCurrencyCode": "",
"expirationDate": ""
}
],
"giftCardDetail": {"cardNumber": "",
"pin": "",
"expirationDate": "",
"certificateLink": ""
},
"simInfo": {"simNumber": "",
"language": "",
"zipCode": "",
"mobileNumber": ""
},
"billPaymentDetail": {"accountNumber": "",
"token": "",
"unit": "",
"receivedNarration": ""
},
"esimDetail": {"iccid": "",
"activationCode": "",
"smdpAddress": "",
"confirmationCode": "",
"qrCodeString": "",
"qrCodeLink": ""
}
}
}

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": [{"name": "",
"value": ""
}
]
}

Response samples

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": {"transactionId": 0,
"transactionDate": "",
"invoiceAmount": 0.1,
"faceValue": 0.1,
"discount": 0.1,
"fee": 0.1,
"product": {"skuId": 0,
"productName": "",
"faceValue": 0.1,
"instructions": "",
"productDescription": ""
},
"topupDetail": {"localCurrencyAmount": 0.1,
"salesTaxAmount": 0.1,
"localCurrencyAmountExcludingTax": 0.1,
"destinationCurrency": "",
"operatorTransactionId": ""
},
"pins": [{"pinNumber": "",
"controlNumber": "",
"deliveredAmount": 0.1,
"deliveredCurrencyCode": "",
"expirationDate": ""
}
],
"giftCardDetail": {"cardNumber": "",
"pin": "",
"expirationDate": "",
"certificateLink": ""
},
"simInfo": {"simNumber": "",
"language": "",
"zipCode": "",
"mobileNumber": ""
},
"billPaymentDetail": {"accountNumber": "",
"token": "",
"unit": "",
"receivedNarration": ""
},
"esimDetail": {"iccid": "",
"activationCode": "",
"smdpAddress": "",
"confirmationCode": "",
"qrCodeString": "",
"qrCodeLink": ""
}
}
}

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> 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. Important Note: ⚠️ For fixed-denomination SKUs, if `transactionCurrencyCode` is not provided or is the same as your wallet currency code, then the `amount` is not validated against the product's allowed fixed denominations. Sending an amount that does not match a valid fixed denomination will not be rejected by the API under these conditions. Always pass `transactionCurrencyCode` when ordering a fixed-denomination product, or verify `amount` against the denomination / FaceValueCurrency values returned by `/catalog/skus` before submitting the request.
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 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,
"accountNumber": "",
"mobileNumber": "",
"checkDigits": "",
"correlationId": "",
"senderMobile": "",
"senderName": "",
"transactionCurrencyCode": "",
"additionalInfos": [{"name": "",
"value": ""
}
]
}

Response samples

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": {"transactionId": 0,
"transactionDate": "",
"invoiceAmount": 0.1,
"faceValue": 0.1,
"discount": 0.1,
"fee": 0.1,
"product": {"skuId": 0,
"productName": "",
"faceValue": 0.1,
"instructions": "",
"productDescription": ""
},
"topupDetail": {"localCurrencyAmount": 0.1,
"salesTaxAmount": 0.1,
"localCurrencyAmountExcludingTax": 0.1,
"destinationCurrency": "",
"operatorTransactionId": ""
},
"pins": [{"pinNumber": "",
"controlNumber": "",
"deliveredAmount": 0.1,
"deliveredCurrencyCode": "",
"expirationDate": ""
}
],
"giftCardDetail": {"cardNumber": "",
"pin": "",
"expirationDate": "",
"certificateLink": ""
},
"simInfo": {"simNumber": "",
"language": "",
"zipCode": "",
"mobileNumber": ""
},
"billPaymentDetail": {"accountNumber": "",
"token": "",
"unit": "",
"receivedNarration": ""
},
"esimDetail": {"iccid": "",
"activationCode": "",
"smdpAddress": "",
"confirmationCode": "",
"qrCodeString": "",
"qrCodeLink": ""
}
}
}

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 Transaction 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

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": {"transactionId": 0,
"transactionDate": "",
"invoiceAmount": 0.1,
"faceValue": 0.1,
"discount": 0.1,
"fee": 0.1,
"product": {"skuId": 0,
"productName": "",
"faceValue": 0.1,
"instructions": "",
"productDescription": ""
},
"topupDetail": {"localCurrencyAmount": 0.1,
"salesTaxAmount": 0.1,
"localCurrencyAmountExcludingTax": 0.1,
"destinationCurrency": "",
"operatorTransactionId": ""
},
"pins": [{"pinNumber": "",
"controlNumber": "",
"deliveredAmount": 0.1,
"deliveredCurrencyCode": "",
"expirationDate": ""
}
],
"giftCardDetail": {"cardNumber": "",
"pin": "",
"expirationDate": "",
"certificateLink": ""
},
"simInfo": {"simNumber": "",
"language": "",
"zipCode": "",
"mobileNumber": ""
},
"billPaymentDetail": {"accountNumber": "",
"token": "",
"unit": "",
"receivedNarration": ""
},
"esimDetail": {"iccid": "",
"activationCode": "",
"smdpAddress": "",
"confirmationCode": "",
"qrCodeString": "",
"qrCodeLink": ""
}
}
}

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 - 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. Important Note: ⚠️ For fixed-denomination SKUs, if `transactionCurrencyCode` is not provided or is the same as your wallet currency code, then the `amount` is not validated against the product's allowed fixed denominations. Sending an amount that does not match a valid fixed denomination will not be rejected by the API under these conditions. Always pass `transactionCurrencyCode` when ordering a fixed-denomination product, or verify `amount` against the denomination / FaceValueCurrency values returned by `/catalog/skus/giftcards` before submitting the request.
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. 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,
"correlationId": "",
"firstName": "",
"lastName": "",
"recipient": "",
"transactionCurrencyCode": "",
"additionalInfos": [{"name": "",
"value": ""
}
]
}

Response samples

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": {"transactionId": 0,
"transactionDate": "",
"invoiceAmount": 0.1,
"faceValue": 0.1,
"discount": 0.1,
"fee": 0.1,
"product": {"skuId": 0,
"productName": "",
"faceValue": 0.1,
"instructions": "",
"productDescription": ""
},
"topupDetail": {"localCurrencyAmount": 0.1,
"salesTaxAmount": 0.1,
"localCurrencyAmountExcludingTax": 0.1,
"destinationCurrency": "",
"operatorTransactionId": ""
},
"pins": [{"pinNumber": "",
"controlNumber": "",
"deliveredAmount": 0.1,
"deliveredCurrencyCode": "",
"expirationDate": ""
}
],
"giftCardDetail": {"cardNumber": "",
"pin": "",
"expirationDate": "",
"certificateLink": ""
},
"simInfo": {"simNumber": "",
"language": "",
"zipCode": "",
"mobileNumber": ""
},
"billPaymentDetail": {"accountNumber": "",
"token": "",
"unit": "",
"receivedNarration": ""
},
"esimDetail": {"iccid": "",
"activationCode": "",
"smdpAddress": "",
"confirmationCode": "",
"qrCodeString": "",
"qrCodeLink": ""
}
}
}

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

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": {"cardNumber": "",
"pin": "",
"expirationDate": "",
"certificateLink": ""
}
}

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": [{"name": "",
"value": ""
}
]
}

Response samples

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": {"transactionId": 0,
"transactionDate": "",
"invoiceAmount": 0.1,
"faceValue": 0.1,
"discount": 0.1,
"fee": 0.1,
"product": {"skuId": 0,
"productName": "",
"faceValue": 0.1,
"instructions": "",
"productDescription": ""
},
"topupDetail": {"localCurrencyAmount": 0.1,
"salesTaxAmount": 0.1,
"localCurrencyAmountExcludingTax": 0.1,
"destinationCurrency": "",
"operatorTransactionId": ""
},
"pins": [{"pinNumber": "",
"controlNumber": "",
"deliveredAmount": 0.1,
"deliveredCurrencyCode": "",
"expirationDate": ""
}
],
"giftCardDetail": {"cardNumber": "",
"pin": "",
"expirationDate": "",
"certificateLink": ""
},
"simInfo": {"simNumber": "",
"language": "",
"zipCode": "",
"mobileNumber": ""
},
"billPaymentDetail": {"accountNumber": "",
"token": "",
"unit": "",
"receivedNarration": ""
},
"esimDetail": {"iccid": "",
"activationCode": "",
"smdpAddress": "",
"confirmationCode": "",
"qrCodeString": "",
"qrCodeLink": ""
}
}
}

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": [{"name": "",
"value": ""
}
]
}

Response samples

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": {"transactionId": 0,
"transactionDate": "",
"invoiceAmount": 0.1,
"faceValue": 0.1,
"discount": 0.1,
"fee": 0.1,
"product": {"skuId": 0,
"productName": "",
"faceValue": 0.1,
"instructions": "",
"productDescription": ""
},
"topupDetail": {"localCurrencyAmount": 0.1,
"salesTaxAmount": 0.1,
"localCurrencyAmountExcludingTax": 0.1,
"destinationCurrency": "",
"operatorTransactionId": ""
},
"pins": [{"pinNumber": "",
"controlNumber": "",
"deliveredAmount": 0.1,
"deliveredCurrencyCode": "",
"expirationDate": ""
}
],
"giftCardDetail": {"cardNumber": "",
"pin": "",
"expirationDate": "",
"certificateLink": ""
},
"simInfo": {"simNumber": "",
"language": "",
"zipCode": "",
"mobileNumber": ""
},
"billPaymentDetail": {"accountNumber": "",
"token": "",
"unit": "",
"receivedNarration": ""
},
"esimDetail": {"iccid": "",
"activationCode": "",
"smdpAddress": "",
"confirmationCode": "",
"qrCodeString": "",
"qrCodeLink": ""
}
}
}

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

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": {"status": "",
"portInDate": "",
"mobile": "",
"rejectCode": "",
"rejectReason": ""
}
}

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. Important Note: ⚠️ For fixed-denomination SKUs, if `transactionCurrencyCode` is not provided or is the same as your wallet currency code, then the `amount` is not validated against the product's allowed fixed denominations. Sending an amount that does not match a valid fixed denomination will not be rejected by the API under these conditions. Always pass `transactionCurrencyCode` when ordering a fixed-denomination product, or verify `amount` against the denomination / FaceValueCurrency values returned by `/catalog/skus` or `/catalog/skus/giftcards` before submitting the request.
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 or /catalog/skus/giftcards 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

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": {"invoiceAmount": 0.1,
"faceValue": 0.1,
"faceValueCurrency": "",
"faceValueInWallet": 0.1,
"localCurrencyAmount": 0.1,
"salesTaxAmount": 0.1,
"localCurrencyAmountExcludingTax": 0.1,
"destinationCurrency": "",
"product": {"skuId": 0,
"productName": "",
"productDescription": ""
}
}
}