Valuetopup API Specification (v1)

Download OpenAPI specification:Download

Valuetopup API Specification v1

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

200

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

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": [{"skuId": 0,
"productId": 0,
"productName": "",
"productDescription": "",
"benefitType": "",
"validity": "",
"faceValue": 0.1,
"minAmount": 0.1,
"maxAmount": 0.1,
"discount": 0.1,
"pricing": "",
"category": "",
"region": "",
"isSalesTaxCharged": true,
"salesTax": 0.1,
"exchangeRate": 0.1,
"currencyCode": "",
"countryCode": "",
"localPhoneNumberLength": 0,
"internationalCountryCode": ["string"
],
"allowDecimal": true,
"fee": 0.1,
"operatorName": "",
"deliveryCurrencyCode": "",
"supportedTransactionCurrencies": "",
"carrierName": "",
"additionalInformation": "",
"loanAmount": 0.1
}
]
}

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

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": [{"skuId": 0,
"productName": "",
"description": ""
}
]
}

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

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": {"productId": 0,
"productName": "",
"category": "",
"countryCode": "",
"operator": "",
"operatorId": 0,
"denominationType": "",
"skus": [{"skuId": 0,
"productId": 0,
"productName": "",
"productDescription": "",
"benefitType": "",
"validity": "",
"faceValue": 0.1,
"minAmount": 0.1,
"maxAmount": 0.1,
"discount": 0.1,
"pricing": "",
"category": "",
"region": "",
"isSalesTaxCharged": true,
"salesTax": 0.1,
"exchangeRate": 0.1,
"currencyCode": "",
"countryCode": "",
"localPhoneNumberLength": 0,
"internationalCountryCode": ["string"
],
"allowDecimal": true,
"fee": 0.1,
"operatorName": "",
"deliveryCurrencyCode": "",
"supportedTransactionCurrencies": "",
"carrierName": "",
"additionalInformation": "",
"loanAmount": 0.1
}
]
}
}

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

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

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

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

200

Content type

application/json

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

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

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": [{"productId": 0,
"productName": "",
"imageUrl": ""
}
]
}

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

200

Content type

application/json

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

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

200

Content type

application/json

{"responseCode": "",
"responseMessage": "",
"payLoad": [{"carrierId": 0,
"carrierName": "",
"category": "",
"countryCode": "",
"productId": 0,
"operator": "",
"denominationType": ""
}
]
}

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

200

Content type

application/json

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

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

Payments

Creates a Stripe Checkout session for payment.

Authorizations:

basic

Request Body schema: application/json

The checkout request details.

amount required	integer <int32>
description	string or null [ 0 .. 500 ] characters
	object or null

Responses

Request samples

Content type

application/json

{"amount": 0,
"description": "",
"metadata": {"property1": "string",
"property2": "string"
}
}

Response samples

200
400
401
429

Content type

application/json

{"sessionId": "",
"url": "",
"expiresAt": ""
}

Gets the payment response for a successful session. User must be authenticated and authorized to own the session.

Authorizations:

basic

query Parameters

sessionId

string

Responses

Request samples

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

Response samples

200

Content type

application/json

{"payLoad": null,
"responseCode": "",
"responseMessage": "",
"responseMessages": ["string"
],
"isSuccessful": true,
"stackTrace": "",
"logId": 0,
"apiResponseCode": ""
}

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": [{"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 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

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> 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": [{"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 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

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
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": [{"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/v1/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/v1/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": ""
}
}