Overview

This method allows you to make recharges for any of the HOT Recharge products. Please note that for the Data Bundles product, you need to provide a ProductCode , check below to see how to get ProductCode.

Recharge Request Model

For a successful recharge you need to provide the following information: AgentReference , ProductId , Target, Amount. Although not required you can also provide the following additional information: Customer SMS, RechargeOptions.

Field name	Type	Description
AgentReference	string	Reference provided by client that can be used to query the transaction later.
ProductId	int	Hot Recharge Product Id
Target	string	The target of a recharge, this can be a mobile number, meter or account number. Requirements of each product differ and are specified in product meta.
Amount	double	The value of the recharge.
CustomerSMS	string	Custom SMS to be use in the customer notification SMS.
RechargeOptions	List of Recharge Options	Recharge Option for recharge if required by the product.

🚧
Agent References
Retailers, Aggregators and multiple site users are advised to insert meaningful agent references to help with reporting and reconciliation. The example below demonstrates an easily identifiable format and reference sample.
Format Sample: DivisionID-ShopID-TillNumber-TellerID-SalesInvoice/ReceiptNumber-LineNumber
Sample Reference: HRE-CBD01-01-KUDA01-100001-01

Getting a ProductId

To get a ProductId for the product you want to recharge, navigate to the Available Products page by clicking this link Available Products. Copy the productId of the specific product you want, that is the value you enter in the ProductId field.

Getting a ProductCode

To get a ProductCode for the Data Bundles product, navigate to the Check Available Stock page by clicking this link Check Available Stock

Reserved Recharge

Overview

This allows for retailers to send a two stage recharge request where the initial request only reserves the recharge and the second stage will complete the recharge. This is useful in situations where the payment processor have additional steps to complete or recharge needs to be delayed for a period but letting the customer know that a transaction is pending on their behalf.

Reservation Recharge Options

Recharge Option	Type	Description
MakeReservation	bool	The field is used to mark that the recharge request is a reserved transaction.
SendReservationSMSToCustomer	bool	Optional field to indicate that a message to the customer to let them know that a transaction to recharge them has been reserved.

Response & Completion of Transaction

The response is for a reserved transaction is the same as a normal recharge request. Please take not of the Agent Reference used for the request as it will be required in the 2nd stage to complete or cancel the reservation. Complete Transaction

Custom SMS Template

The Hot recharge API allows for you to send a custom SMS to the customers that you recharge. The custom SMS field allows for you to use the below tags as placeholders in your message. The API will fill in the correct value in the message to the customer. Below is a list of the standard tags that can be used in any message but in the meta data of each product additional tags are available that are specific to each product.

TAG	Format	Description
%AMOUNT%	$XXX.XX	The value of the transaction
%INITIALBALANCE%	$XXX.XX	End users initial balance for before transaction
%BALANCE%	$XXX.XX	End users final balance for after transaction
%COMPANYNAME%	string	Company name set on the website www.hot.co.zw
%ACCESSNAME%	string	User's name defined on website for the sender

Examples

Requests

Below are samples of different types of custom Recharge Requests.

{
    "agentReference": "{{AgentReference}}",
    "productId": 100,
    "target": "0772929223",
    "amount": 10
}

{
    "agentReference": "{{AgentReference}}",
    "productId": 16,
    "target": "0772929223",
    "amount": 284,
    "RechargeOptions": [
    {
      "Name": "ProductCode",
      "ParameterType": "string",
      "Value": "DDB20"
    }
  ]
}

{
    "agentReference": "{{AgentReference}}",
    "productId": 24,
    "target": "{{MeterNumber}}",
    "amount": 100000,
    "RechargeOptions": [
    {
      "Name": "NotifyNumber",
      "ParameterType": "string",
      "Value": "0772929223"
    }
  ]
}

Example Requests with Custom SMS

{
    "agentReference": "{{AgentReference}}",
    "productId": 7,
    "target": "0772397464",
    "amount": 10,
    "CustomsSMS":"%COMPANYNAME% topped up your account with $%AMOUNT%. Your new balance is $%BALANCE%."
}

{
    "agentReference": "{{AgentReference}}",
    "productId": 24,
    "target": "{{MeterNumber}}",
    "amount": 100000,
    "CustomsSMS":"A ZETDC token was purchased for %ACOUNTNAME% (%METERNUMBER%) valued %AMOUNT% that resulted in %KWH% units."
    "RechargeOptions": [
    {
      "Name": "NotifyNumber",
      "ParameterType": "string",
      "Value": "0772929223"
    }
  ]
}

Example Request with Reserved Transaction

{
   "agentReference": "{{AgentReference}}",
    "productId": 100,
    "target": "0772929223",
    "amount": 10,
    "RechargeOptions": [
    {
      "Name": "MakeReservation",
      "ParameterType": "bool",
      "Value": "true"
    }
  ]
}

{
   "agentReference": "{{AgentReference}}",
    "productId": 100,
    "target": "0772929223",
    "amount": 10,
    "RechargeOptions": [
    {
      "Name": "MakeReservation",
      "ParameterType": "bool",
      "Value": "true"
    },
    {
      "Name":"SendReservationSMSToCustomer",
      "ParameterType": "bool",
      "Value": "true"
    }
  ]
}

Responses

{
    "successful": true,
    "rechargeId": 182255554,
    "amount": 10,
    "discount": 0,
    "balance": {
        "accountTypeId": 1,
        "name": "ZiG",
        "balance": 8985.73
    },
    "message": "Recharge to 0716047102 of $10.23 was successful. The initial balance was $32,451.22 final balance is $32,461.45",
    "rechargeData": {
        "InitialBalance": "32451.219236",
        "FinalBalance": "32461.449236"
    }
}

{
    "successful": true,
    "rechargeId": 182362390,
    "amount": 284,
    "discount": 0,
    "balance": {
        "accountTypeId": 1,
        "name": "ZiG",
        "balance": 8067.23
    },
    "message": "OK",
    "rechargeData": {}
}

{
    "successful": false,
    "rechargeId": 182362358,
    "amount": 10,
    "discount": 0,
    "balance": {
        "accountTypeId": 1,
        "name": "ZiG",
        "balance": 8351.23
    },
    "message": "Mobile Number not a prepaid subscriber",
    "rechargeData": {}
}

Errors

{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "errors": {
        "ProductId": [
            "ProductId is currently not supported. ProductID 0"
        ]
    }
}

{
    "errors": [
        {
            "name": "Product",
            "message": "\"Invalid Product Code\" DDB2"
        }
    ]
}

Overview

Recharge Request Model

🚧Agent References

Getting a ProductId

Getting a ProductCode

Reserved Recharge

Overview

Reservation Recharge Options

Response & Completion of Transaction

Custom SMS Template

Examples

Requests

Example Requests with Custom SMS

Example Request with Reserved Transaction

Responses

Errors

🚧
Agent References