Telgoo5 APIs

AddDataTopup

This XML API is used to add an Add On Voice as well as Data to subscriber's account. List of available Add On is returned via GetDenomination API which are seperated on the basis of carrier. This API is not charging any payment and hence we recommend using Payment API to charge the subscriber for the Add on.

End Point	https://www.vcareapi.com/vcareOssApi/AddDataTopup/
Field (Short Description)	Value/Tag Name	Format	Field Example	Type	Notes	Validation rules
VENDOR ID		string	Vcarecorporation	Required	A unique Vendor ID is associated with the MVNO/OSS partner. This is used for authorization purpose and can be obtained by contacting your account manager.
USER NAME		string	Vcarecorporation	Required	A unique User name is associated with the MVNO/OSS partner. This is used for authorization purpose and can be obtained by contacting your account manager.
PASSWORD		string	Vcarecorporation	Required	This is a random string which is generated by Vcare and is tied to the MVNO/OSS user name. This is specifically used for authentication purpose and can be obtained by contacting your account manager.
PIN		string	123456789	Required	This is generated by Vcare to provide an additional layer of security in the Interim API. This is used for authentication purpose and can be obtained by contacting your account manager.
REFERENCE NUMBER		string	123456789	Required	Auto generated unique reference number is required to be passed with each transaction.
CUSTOMERID		Numeric	123456	Conditional	Auto generated customer account number. This is returned in GetCustomerInfo	Customer ID and MDN are conditional; user can use either one of them.
MDN		Numeric	1234567890	Conditional	Telephone Number of the subscriber. This is returned in GetCustomerInfo	Customer ID and MDN are conditional; user can use either one of them.
COMPANYID		Numeric	28	Optional	This can be obtained using GetCompany API	Numeric
PLANID		Numeric	1315	Conditional	This is returned in GetDenomination API which are separated on the basis of carrier. This is the id of the topup which you would like to apply to the subscriber.	Priority Second. Plan ID and Plan code are conditional user can provide either of them.
PLAN CODE		string	125	Conditional	Unique carrier code assigned to every plan while creating. User can get it through Line inquiry API.	Priority first. Plan ID and Plan code are conditional user can provide either of them.
CHANGETYPE		string	IMMEDIATE	Optional	IMMEDIATE = This will change the plan instantly. ONEXPIRY = This will change the plan when the existing service plan expires. When you pass CHANGETYPE as ONEXPIRY the plan will be stacked on the account. If you pass multiple request for the plan ONEXPIRY than they will also be stacked and will be activated on the current plan expiry.	IMMEDIATE or ONEXPIRY, Default Value IMMEDIATE Change Type is optional and if left blank then change type will be considered as Immediate.
BALANCE TYPE		string	TOPUP	Optional	TOPUP,DATA,UPGRADE,ILD	Default value TOPUP
OTHER PAYMENT OPTION		string	Ebay	Optional	It is other payment option.	Ebay Amazon Website
AMOUNT		Numeric	30	Conditional	This is the amount that will be charged. It should be match with plan amount.
SOURCE		string	API	Optional	Source of the order/application	Expected Value:API, TABLET, IVR, WEBSITE
AGENTID		string	John Doe	Required	This is the Telgoo5 user id.For the Agent/Employee who is sending the API request.
AGENTPASSWORD		string	John Doe	Conditional	This is the password for the Agent Id mentioned above. This is configuration level field. If you have set the permissions for the Agent Id for the requirement of the password in API transactions then you will need to pass the Agent Password in all the XML API transaction, else if you have set the permissions to password not required then you don’t need to pass the Agent Password in the XML API.

Sample Request XML

<?xml version="1.0" encoding="utf-8"?>
<VCAREOSSAPI xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<CREDENTIALS>
	<VENDORID></VENDORID>
	<USERNAME></USERNAME>
	<PASSWORD></PASSWORD>
	<PIN></PIN>
	<REFERENCENUMBER></REFERENCENUMBER>
</CREDENTIALS>
<VCAREOSS>
	<ADDDATATOPUP>
		<CUSTOMERID></CUSTOMERID>
		<MDN></MDN>
		<COMPANYID></COMPANYID>
		<PLANID></PLANID>
		<PLANCODE></PLANCODE>
		<CHANGETYPE></CHANGETYPE>
		<BALANCETYPE></BALANCETYPE>
		<OTHER_PAYMENT_OPTION></OTHER_PAYMENT_OPTION>
		<AMOUNT></AMOUNT>
		<AGENTID></AGENTID>
		<AGENTPASSWORD></AGENTPASSWORD>
		<SOURCE></SOURCE>
	</ADDDATATOPUP>
</VCAREOSS>
</VCAREOSSAPI>

List of status code and description.
Status Code	Description
00	SUCCESS
01	Error Received from Carrier.
13	Password is invalid.
16	Vendor not found. Wrong credentials.
25	Customer ID is invalid.
126	Invalid MDN.
128	Plan Code is required.
129	Plan Code is incorrect.
168	Invalid Amount.
174	You are not eligible for upgrade topup.
226	Customer ID is required.
301	Balance Type is invalid.
356	Agent ID cannot be blank.
367	MDN should be 10 digits.
374	Change Type should not be blank.
377	Change Type is not valid.
457	Invalid Source.
487	MDN mismatch.
488	Company ID mismatch.
751	Custom message.
805	Plan ID OR plan code is required.
810	Other Payment option is not allowed
811	Provided Other payment option is not available
812	Other payment options are not configured.

Sample Response

<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <credentials>
        <vendorId>Vcarecorporation</vendorId>
        <referenceNumber>11111</referenceNumber>
    </credentials>
    <Adddatatopup>
        <statusCode>00</statusCode>
        <description>SUCCESS</description>
        <errorDescription>SUCCESS</errorDescription>
        <Adddatatopup>
</VcareOssApi>

SUCCESS

Sample Fail Response: 1

<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
<AddDataTopup>
	<statusCode>01</statusCode>
	<description>FAIL</description>
	<errorDescription>Error Received from Carrier.</errorDescription>
</AddDataTopup>
</VcareOssApi>

Error Received from Carrier.

Sample Fail Response: 2

<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
<AddDataTopup>
	<statusCode>13</statusCode>
	<description>FAIL</description>
	<errorDescription>Password is invalid.</errorDescription>
</AddDataTopup>
</VcareOssApi>

Password is invalid.

Sample Fail Response: 3

<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
<AddDataTopup>
	<statusCode>16</statusCode>
	<description>FAIL</description>
	<errorDescription>Vendor not found. Wrong credentials.</errorDescription>
</AddDataTopup>
</VcareOssApi>

Vendor not found. Wrong credentials.

Sample Fail Response: 4

<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
<AddDataTopup>
	<statusCode>25</statusCode>
	<description>FAIL</description>
	<errorDescription>Customer ID is invalid.</errorDescription>
</AddDataTopup>
</VcareOssApi>

Customer ID is invalid.

Sample Fail Response: 5

<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
<AddDataTopup>
	<statusCode>126</statusCode>
	<description>FAIL</description>
	<errorDescription>Invalid MDN.</errorDescription>
</AddDataTopup>
</VcareOssApi>

Invalid MDN.

Sample Fail Response: 6

<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
<AddDataTopup>
	<statusCode>128</statusCode>
	<description>FAIL</description>
	<errorDescription>Plan Code is required.</errorDescription>
</AddDataTopup>
</VcareOssApi>

Plan Code is required.

Sample Fail Response: 7

<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
<AddDataTopup>
	<statusCode>129</statusCode>
	<description>FAIL</description>
	<errorDescription>Plan Code is incorrect.</errorDescription>
</AddDataTopup>
</VcareOssApi>

Plan Code is incorrect.

Sample Fail Response: 8

<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
<AddDataTopup>
	<statusCode>168</statusCode>
	<description>FAIL</description>
	<errorDescription>Invalid Amount.</errorDescription>
</AddDataTopup>
</VcareOssApi>

Invalid Amount.

Sample Fail Response: 9

<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
<AddDataTopup>
	<statusCode>174</statusCode>
	<description>FAIL</description>
	<errorDescription>You are not eligible for upgrade topup.</errorDescription>
</AddDataTopup>
</VcareOssApi>

You are not eligible for upgrade topup.

Sample Fail Response: 10

<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
<AddDataTopup>
	<statusCode>226</statusCode>
	<description>FAIL</description>
	<errorDescription>Customer ID is required.</errorDescription>
</AddDataTopup>
</VcareOssApi>

Customer ID is required.

Sample Fail Response: 11

<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
<AddDataTopup>
	<statusCode>301</statusCode>
	<description>FAIL</description>
	<errorDescription>Balance Type is invalid.</errorDescription>
</AddDataTopup>
</VcareOssApi>

Balance Type is invalid.

Sample Fail Response: 12

<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
<AddDataTopup>
	<statusCode>356</statusCode>
	<description>FAIL</description>
	<errorDescription>Agent ID cannot be blank.</errorDescription>
</AddDataTopup>
</VcareOssApi>

Agent ID cannot be blank.

Sample Fail Response: 13

<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
<AddDataTopup>
	<statusCode>367</statusCode>
	<description>FAIL</description>
	<errorDescription>MDN should be 10 digits.</errorDescription>
</AddDataTopup>
</VcareOssApi>

MDN should be 10 digits.

Sample Fail Response: 14

<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
<AddDataTopup>
	<statusCode>374</statusCode>
	<description>FAIL</description>
	<errorDescription>Change Type  should not be blank.</errorDescription>
</AddDataTopup>
</VcareOssApi>

Change Type should not be blank.

Sample Fail Response: 15

<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
<AddDataTopup>
	<statusCode>377</statusCode>
	<description>FAIL</description>
	<errorDescription>Change Type is not valid.</errorDescription>
</AddDataTopup>
</VcareOssApi>

Change Type is not valid.

Sample Fail Response: 16

<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
<AddDataTopup>
	<statusCode>457</statusCode>
	<description>FAIL</description>
	<errorDescription>Invalid Source.</errorDescription>
</AddDataTopup>
</VcareOssApi>

Invalid Source.

Sample Fail Response: 17

<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
<AddDataTopup>
	<statusCode>487</statusCode>
	<description>FAIL</description>
	<errorDescription>MDN mismatch.</errorDescription>
</AddDataTopup>
</VcareOssApi>

MDN mismatch.

Sample Fail Response: 18

<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
<AddDataTopup>
	<statusCode>488</statusCode>
	<description>FAIL</description>
	<errorDescription>Company ID mismatch.</errorDescription>
</AddDataTopup>
</VcareOssApi>

Company ID mismatch.

Sample Fail Response: 19

<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
<AddDataTopup>
	<statusCode>751</statusCode>
	<description>FAIL</description>
	<errorDescription>Custom message.</errorDescription>
</AddDataTopup>
</VcareOssApi>

Custom message.

Sample Fail Response: 20

<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
<AddDataTopup>
	<statusCode>805</statusCode>
	<description>FAIL</description>
	<errorDescription>Plan ID OR plan code is required.</errorDescription>
</AddDataTopup>
</VcareOssApi>

Plan ID OR plan code is required.

Sample Fail Response: 21

<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
<AddDataTopup>
	<statusCode>810</statusCode>
	<description>FAIL</description>
	<errorDescription>Other Payment option is not allowed</errorDescription>
</AddDataTopup>
</VcareOssApi>

Other Payment option is not allowed

Sample Fail Response: 22

<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
<AddDataTopup>
	<statusCode>811</statusCode>
	<description>FAIL</description>
	<errorDescription>Provided Other payment option is not available</errorDescription>
</AddDataTopup>
</VcareOssApi>

Provided Other payment option is not available

Sample Fail Response: 23

<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
<AddDataTopup>
	<statusCode>812</statusCode>
	<description>FAIL</description>
	<errorDescription>Other payment options are not configured.</errorDescription>
</AddDataTopup>
</VcareOssApi>

Other payment options are not configured.