Rechage Transaction

POSThttps://xyz.com/v1/service/recharge/initiate

Authentication

Basic Authentication

• Username: Client Id
• Password: Secret Key

Example Authorization Header:

Authorization: Basic eGV0dGxlXzgzMjg2NjU5YmRmNzBkZWEzMDUwMzcwNzE1MTYwMzA0MDo3YzE1ZDQyYTZhYjEyOTYzYWI4NzJhMzFkOTk4MDk1ZDMwNTAzNzA3MTUxNjMyMDg5

Request Body

{
  "phone": "1234567890",
  "amount": "299",
  "operatorId": "6",
  "clientRefId": "363636342454" 
}

Parameters

Parameter	Type	Required	Description
phone	String	Yes	Customer's phone number that will be recharged
amount	String	Yes	Recharge amount
operatorId	String	Yes	ID of the mobile operator
clientRefId	String	Yes	Unique reference ID generated by client for transaction tracking

Request Examples

Request Examples

Curl

curl --location 'https://xyz.com/v1/service/recharge/initiate' --header 'Content-Type: application/json' --header 'Authorization: Basic eGV0dGxlXzgzMjg2NjU5YmRmNzBkZWEzMDUwMzcwNzE1MTYwMzA0MDo3YzE1ZDQyYTZhYjEyOTYzYWI4NzJhMzFkOTk4MDk1ZDMwNTAzNzA3MTUxNjMyMDg5' --data '{
"phone" :"1234567890",
"amount" :"299",
"operatorId" :"6",
"clientRefId" :"363636342454"
}'

Nodejs

const axios = require('axios');
let data = JSON.stringify({
  "phone": "1234567890",
  "amount": "299",
  "operatorId": "6",
  "clientRefId": "363636342454"
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://xyz.com/v1/service/recharge/initiate',
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': 'Basic eGV0dGxlXzgzMjg2NjU5YmRmNzBkZWEzMDUwMzcwNzE1MTYwMzA0MDo3YzE1ZDQyYTZhYjEyOTYzYWI4NzJhMzFkOTk4MDk1ZDMwNTAzNzA3MTUxNjMyMDg5'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

C#

var options = new RestClientOptions("https://xyz.com")
{
  MaxTimeout = -1,
};
var client = new RestClient(options);
var request = new RestRequest("/v1/service/recharge/initiate", Method.Post);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "Basic eGV0dGxlXzgzMjg2NjU5YmRmNzBkZWEzMDUwMzcwNzE1MTYwMzA0MDo3YzE1ZDQyYTZhYjEyOTYzYWI4NzJhMzFkOTk4MDk1ZDMwNTAzNzA3MTUxNjMyMDg5");
var body = @"{
" + "
" +
@"""phone"" :""1234567890"",
" + "
" +
@"""amount"" :""299"",
" + "
" +
@"""operatorId"" :""6"",
" + "
" +
@"""clientRefId"" :""363636342454""
" + "
" +
@"}";
request.AddStringBody(body, DataFormat.Json);
RestResponse response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);

Java

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{
"phone" :"1234567890",
"amount" :"299",
"operatorId" :"6",
"clientRefId" :"363636342454"
}");
Request request = new Request.Builder()
  .url("https://xyz.com/v1/service/recharge/initiate")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Basic eGV0dGxlXzgzMjg2NjU5YmRmNzBkZWEzMDUwMzcwNzE1MTYwMzA0MDo3YzE1ZDQyYTZhYjEyOTYzYWI4NzJhMzFkOTk4MDk1ZDMwNTAzNzA3MTUxNjMyMDg5")
  .build();
Response response = client.newCall(request).execute();

Python

import requests
import json

url = "https://xyz.com/v1/service/recharge/initiate"

payload = json.dumps({
  "phone": "1234567890",
  "amount": "299",
  "operatorId": "6",
  "clientRefId": "363636342454"
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Basic eGV0dGxlXzgzMjg2NjU5YmRmNzBkZWEzMDUwMzcwNzE1MTYwMzA0MDo3YzE1ZDQyYTZhYjEyOTYzYWI4NzJhMzFkOTk4MDk1ZDMwNTAzNzA3MTUxNjMyMDg5'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Response Examples

Success

{
        "code": "0x0200",
        "message": "status fetch successfully",
        "status": "SUCCESS",
        "data": {
            "clientRefId": "363636342469",
            "stan_no": "BR000C3NF5GA",
            "status": "processed"
        }
    }

Failed

{
        "code": "0x0200",
        "message": "status fetch successfully",
        "status": "SUCCESS",
        "data": {
            "clientRefId": "363636342468",
            "stan_no": " ",
            "status": "failed"
        }
    }

RequestFailed

{
    "code": "0x0202",
    "status": "FAILURE",
    "message": "Insufficient funds."
}

Pending

{
        "code": "0x0200",
        "message": "status fetch successfully",
        "status": "SUCCESS",
        "data": {
            "clientRefId": "363636342467",
            "stan_no": null,
            "status": "processing"
       }
    }

Response Codes

The API uses the following response codes to indicate the status of requests:

Code	Description	Meaning
0x0200	SUCCESS	The request was processed successfully.
0x0201	UNAUTHORIZED	Authentication failed or insufficient permissions.
0x0202	FAILED	The request processing failed for a reason other than those specifically identified.
0x0203	MISSING_PARAMETER	The request is missing one or more required parameters.
0x0206	PENDING	The request has been received and is being processed, but processing has not yet completed.
0x0205	SOMETHING_WENT_WRONG	A server error occurred during processing of the request.

Response Format

All API responses follow a standard JSON format:

{
  "code": "STATUS_CODE",
  "message": "Human-readable message",
  "status": "STATUS_TEXT",
  "data": {
    // Optional response data
  }
}

Response Scenarios

Successful Transaction

When a transaction has been processed successfully, the API returns:

{
  "code": "0x0200",
  "message": "status fetch successfully",
  "status": "SUCCESS",
  "data": {
    "clientRefId": "363636342469",
    "stan_no": "BR000C3NF5GA",
    "status": "processed"
  }
}

Key indicators of success:

• code is 0x0200 (SUCCESS_CODE)
• status is "SUCCESS"
• data.status is "processed"
• stan_no contains a valid transaction reference number

Failed Transaction

When a transaction has failed but the status check was successful:

{
  "code": "0x0200",
  "message": "status fetch successfully",
  "status": "SUCCESS",
  "data": {
    "clientRefId": "363636342468",
    "stan_no": " ",
    "status": "failed"
  }
}

Key indicators of transaction failure:

• code is still 0x0200 because the status check itself succeeded
• status is "SUCCESS" (referring to the status check, not the transaction)
• data.status is "failed"
• stan_no is empty or blank

Invalid Request

When the request itself is invalid (e.g., incorrect reference ID):

{
  "code": "0x0202",
  "status": "FAILURE",
  "message": "Invalid clientRefId."
}

Key indicators of invalid request:

• code is 0x0202 (FAILED_CODE)
• status is "FAILURE"
• No data object is returned
• message describes the specific error

Processing Transaction

When a transaction is still being processed:

{
  "code": "0x0200",
  "message": "status fetch successfully",
  "status": "SUCCESS",
  "data": {
    "clientRefId": "363636342467",
    "stan_no": null,
    "status": "processing"
  }
}

Key indicators of processing:

• code is 0x0200 because the status check succeeded
• status is "SUCCESS" (referring to the status check)
• data.status is "processing"
• stan_no is typically null

Integrating with Frontend

function checkTransactionStatus(clientRefId) {
  // Make API call to check status
  
  // Handle response based on code and status
  if (response.code === "0x0200") {
    if (response.data.status === "processed") {
      showSuccess("Transaction completed successfully!");
      logTransaction(response.data.stan_no);
    } else if (response.data.status === "processing") {
      showPending("Transaction is processing...");
      // Poll again after 5 seconds
      setTimeout(() => checkTransactionStatus(clientRefId), 5000);
    } else if (response.data.status === "failed") {
      showError("Transaction failed. Please try again.");
    }
  } else {
    // Handle other error codes
    showError(`Error: ${response.message}`);
  }
}