Make a top-up

With the /topups endpoint, developers can make an airtime recharge to any mobile number within the operators covered by Reloadly

Top-up

POST https://topups.reloadly.com/topups

Headers

Name	Type	Description
Authorization*	string	Your access token is required as a bearer token in the request's header

Request Body

Name	Type	Description
operatorId*	integer	Indicates the operator's ID
amount*	integer	Indicates the amount of airtime or data that is to be recharged
useLocalAmount	boolean	Indicates if the recharge is to be made in the operator's local currency. Default is false.
customIdentifier	string	Indicates the transaction reference of the recharge. Note: Each transaction reference is to be unique. Once a reference has been used for a top-up transaction, it cannot be reused.
recipientEmail	string	This is the recipient's email address. It is required when the operator is Nauta Cuba. It supports only two email domains: 1. @nauta.com.cu 2. @nauta.co.cu
recipientPhone*	object	Indicates an object containing the receiver's country code and mobile number
senderPhone	object	Indicates an object containing the sender's country code and mobile number
countryCode*	string	Indicates the ISO code of the receiver's or sender's country
number*	string	Indicates the mobile number of the top-up receiver or sender

200 This response is gotten when a request is made and details of a successful airtime recharge are retrieved

JSON

{
    "transactionId": 26523,
    "status": "SUCCESSFUL",
    "operatorTransactionId": null,
    "customIdentifier": "This is example identifier",
    "recipientPhone": "447951631337",
    "recipientEmail": null,
    "senderPhone": "11231231231",
    "countryCode": "GB",
    "operatorId": 535,
    "operatorName": "EE PIN England",
    "discount": 63.37,
    "discountCurrencyCode": "NGN",
    "requestedAmount": 3168.4,
    "requestedAmountCurrencyCode": "NGN",
    "deliveredAmount": 5,
    "deliveredAmountCurrencyCode": "GBP",
    "transactionDate": "2022-01-26 03:19:16",
    "pinDetail": {
        "serial": "558111",
        "info1": "DIAL *611",
        "info2": "DIAL *611",
        "info3": "Dial *233* and PIN #",
        "value": null,
        "code": "773709733097662",
        "ivr": "1-888-888-8888",
        "validity": "30 days"
    },
    "balanceInfo": {
        "oldBalance": 60387.41,
        "newBalance": 57282.38,
        "cost": 3105.03,
        "currencyCode": "NGN",
        "currencyName": "Nigerian Naira",
        "updatedAt": "2022-01-26 08:19:16"
    }
}

400 This response is gotten when a request is made with an incorrect body parameter

JSON

{
  "timeStamp":"2021-05-31 18:38:03",
  "message":"Recipient phone number is not valid",
  "path":"/topups",
  "errorCode":"INVALID_RECIPIENT_PHONE",
  "infoLink":null,
  "details":[
    
  ]
}

401 This response is gotten when an incorrect or expired access token is used to make a request

JSON

{
  "timeStamp":"2021-05-31 17:48:18",
  "message":"Full authentication is required to access this resource",
  "path":"/topup",
  "errorCode":"INVALID_TOKEN",
  "infoLink":null,
  "details":[
    
  ]
}

Request samples

cURL

curl --location --request POST 'https://topups.reloadly.com/topups' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE' \
--header 'Accept: application/com.reloadly.topups-v1+json' \
--header 'Content-Type: application/json' \
--data-raw '{
	"operatorId":"341",
	"amount":"10",
	"useLocalAmount": false,
	"customIdentifier": "This is example identifier 092",
	"recipientPhone": {
		"countryCode": "NG",
		"number": "08147658721"
	},
	"senderPhone": {
		"countryCode": "CA",
		"number": "1231231231"
	}
}'

C#

using System;
using System.Threading.Tasks;
using System.Net.Http;
using System.Text;
using Newtonsoft.Json;

namespace WebAPIClient {
  class Program {

    static async Task Main(string[] args) {
      await ApiCall();
    }

    private static async Task ApiCall() {

      var json = JsonConvert.SerializeObject(new {
          operatorId = "341",
          amount = "10",
          useLocalAmount = false,
          customIdentifier = "This is a sample",
          recipientPhone = new {
            countryCode = "NG", 
            number = "08147658721"
          }
      });

      var message = new HttpRequestMessage(HttpMethod.Post, "https://topups.reloadly.com/topups"){
        Content = new StringContent(json, Encoding.UTF8, "application/json")
      };

      message.Headers.TryAddWithoutValidation("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
      message.Headers.TryAddWithoutValidation("Accept", "application/com.reloadly.topups-v1+json");

      using
      var httpClient = new HttpClient();
      var response = await httpClient.SendAsync(message);
      var responseBody = await response.Content.ReadAsStringAsync();
      var result = JsonConvert.DeserializeObject < dynamic > (responseBody);

      Console.WriteLine(result);
    }

  }
}

Golang

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://topups.reloadly.com/topups"
  method := "POST"

  payload := strings.NewReader(`{
	"operatorId":"341",
	"amount":"10",
	"useLocalAmount": false,
	"customIdentifier": "This is example identifier 092",
	"recipientPhone": {
		"countryCode": "NG",
		"number": "08147658721"
	},
	"senderPhone": {
		"countryCode": "CA",
		"number": "1231231231"
	}
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  req.Header.Add("Accept", "application/com.reloadly.topups-v1+json")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

Java

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n\t\"operatorId\":\"685\",\n\t\"amount\":\"10\",\n\t\"customIdentifier\": \"This is example identifier 092\",\n\t\"recipientPhone\": {\n\t\t\"countryCode\": \"NG\",\n\t\t\"number\": \"08147658721\"\n\t},\n\t\"senderPhone\": {\n\t\t\"countryCode\": \"CA\",\n\t\t\"number\": \"1231231231\"\n\t}\n}");
Request request = new Request.Builder()
  .url("https://topups.reloadly.com/topups")
  .method("POST", body)
  .addHeader("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  .addHeader("Accept", "application/com.reloadly.topups-v1+json")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

Node JS

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://topups.reloadly.com/topups',
  'headers': {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept': 'application/com.reloadly.topups-v1+json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "operatorId": "341",
    "amount": "10",
    "useLocalAmount": false,
    "customIdentifier": "This is example identifier 092",
    "recipientPhone": {
      "countryCode": "NG",
      "number": "08147658721"
    },
    "senderPhone": {
      "countryCode": "CA",
      "number": "1231231231"
    }
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://topups.reloadly.com/topups',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
	"operatorId":"341",
	"amount":"10",
	"useLocalAmount": false,
	"customIdentifier": "This is example identifier 092",
	"recipientPhone": {
		"countryCode": "NG",
		"number": "08147658721"
	},
	"senderPhone": {
		"countryCode": "CA",
		"number": "1231231231"
	}
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept: application/com.reloadly.topups-v1+json',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Python

import requests
import json

url = "https://topups.reloadly.com/topups"

payload = json.dumps({
  "operatorId": "341",
  "amount": "10",
  "useLocalAmount": False,
  "customIdentifier": "This is example identifier 092",
  "recipientPhone": {
    "countryCode": "NG",
    "number": "08147658721"
  },
  "senderPhone": {
    "countryCode": "CA",
    "number": "1231231231"
  }
})
headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
  'Accept': 'application/com.reloadly.topups-v1+json',
  'Content-Type': 'application/json'
}

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

print(response.text)

Request samples for Nauta Cuba top-ups

cURL

curl --location --request POST 'https://topups.reloadly.com/topups' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE' \
--header 'Accept: application/com.reloadly.topups-v1+json' \
--header 'Content-Type: application/json' \
--data-raw '{
	"operatorId":"685",
	"amount":"10",
	"customIdentifier": "This is example identifier 092",
	"recipientEmail": "[e-mail]",
	"senderPhone": {
		"countryCode": "CA",
		"number": "1231231231"
	}
}'

C#

using System;
using System.Threading.Tasks;
using System.Net.Http;
using System.Text;
using Newtonsoft.Json;

namespace WebAPIClient {
  class Program {

    static async Task Main(string[] args) {
      await ApiCall();
    }

    private static async Task ApiCall() {

      var json = JsonConvert.SerializeObject(new {
        operatorId = "685",
          amount = "10",
          customIdentifier = "This is a sample",
          recipientEmail = "[e-mail]"
          senderPhone = new {
            countryCode = "CA", 
            number = "1231231231"
          }
      });

      var message = new HttpRequestMessage(HttpMethod.Post, "https://topups.reloadly.com/topups"){
        Content = new StringContent(json, Encoding.UTF8, "application/json")
      };

      message.Headers.TryAddWithoutValidation("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
      message.Headers.TryAddWithoutValidation("Accept", "application/com.reloadly.topups-v1+json");

      using
      var httpClient = new HttpClient();
      var response = await httpClient.SendAsync(message);
      var responseBody = await response.Content.ReadAsStringAsync();
      var result = JsonConvert.DeserializeObject < dynamic > (responseBody);

      Console.WriteLine(result);
    }

  }
}

Golang

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://topups.reloadly.com/topups"
  method := "POST"

  payload := strings.NewReader(`{
	"operatorId":"685",
	"amount":"10",
	"customIdentifier": "This is example identifier 092",
	"recipientEmail": "[e-mail]",
	"senderPhone": {
		"countryCode": "CA",
		"number": "1231231231"
	}
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  req.Header.Add("Accept", "application/com.reloadly.topups-v1+json")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

Java

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n\t\"operatorId\":\"685\",\n\t\"amount\":\"10\",\n\t\"customIdentifier\": \"This is example identifier 092\",\n\t\"recipientEmail\": \"[e-mail]\",\n\t\"senderPhone\": {\n\t\t\"countryCode\": \"CA\",\n\t\t\"number\": \"1231231231\"\n\t}\n}");
Request request = new Request.Builder()
  .url("https://topups.reloadly.com/topups")
  .method("POST", body)
  .addHeader("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  .addHeader("Accept", "application/com.reloadly.topups-v1+json")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

Node JS

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://topups.reloadly.com/topups',
  'headers': {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept': 'application/com.reloadly.topups-v1+json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "operatorId": "685",
    "amount": "10",
    "customIdentifier": "This is example identifier 092",
    "recipientEmail": "[e-mail]",
    "senderPhone": {
      "countryCode": "CA",
      "number": "1231231231"
    }
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://topups.reloadly.com/topups',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
	"operatorId":"685",
	"amount":"10",
	"customIdentifier": "This is example identifier 092",
	"recipientEmail": "[e-mail]",
	"senderPhone": {
		"countryCode": "CA",
		"number": "1231231231"
	}
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept: application/com.reloadly.topups-v1+json',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Python

import requests
import json

url = "https://topups.reloadly.com/topups"

payload = json.dumps({
  "operatorId": "685",
  "amount": "10",
  "customIdentifier": "This is example identifier 092",
  "recipientEmail": "[e-mail]",
  "senderPhone": {
    "countryCode": "CA",
    "number": "1231231231"
  }
})
headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
  'Accept': 'application/com.reloadly.topups-v1+json',
  'Content-Type': 'application/json'
}

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

print(response.text)

Response parameters

Parameter	Type	Description
transactionId	integer	Indicates the unique ID of a top-up
status	string	Indicates the status of a top-up. Note: SUCCESSFUL: This applies when the top up is successfully made. PROCESSING: This applies while the top up is still being verified from the operator's end. REFUNDED: This applies once the top up is not processed successfully from the airtime operator's end. In this instance, any funds debited from a user's wallet while attempting to make the top-up are automatically refunded.
operator TransactionId	string	Indicates the transaction ID assigned by the operator of the receiving mobile number
customIdentifier	string	This is the top-up's reference that is to be assigned by the sender
recipientPhone	string	This indicates the top-up receiver's mobile number
recipientEmail	string	This indicates the top-up receiver's email (only applicable to Nauta Cuba top-ups)
senderPhone	string	This indicates the sender's mobile number
countryCode	string	Indicates the ISO code of the country where the operator is registered
operatorId	integer	The ID of the receiving mobile number's operator
operatorName	string	The name of the receiving mobile number's operator
discount	integer	Indicates if there was a discount on the top-up made and at what rate
discountCurrency Code	string	Indicates the currency code of the receiving mobile number
requestedAmount	integer	Indicates the top-up amount sent by the originating account
requestedAmount CurrencyCode	string	Indicates the currency code of the originating account
deliveredAmount	integer	Indicates the top-up amount received by the receiving mobile number
deliveredAmount CurrencyCode	string	Indicates the currency in which the top-up was delivered
transactionDate	string	Indicates the date and time the top-up was made
pinDetail	object	This contains information on how to process the PIN on the physical SIM. Note that this is only for operators that support PIN Top-up
serial	string	Indicates the serial code of the PIN top-up
info	string	Indicates information on how to utilize the top-up
value	string	Indicates additional information on the PIN
code	string	Indicates the code that is to be used to activate the top-up
ivr	string	Indicates the number to call for an interactive voice response
validity	string	Indicates the validity of the PIN
balanceInfo	object	Contains information of the top-up sender's account balance
oldBalance	integer	Indicates the balance of the sender's account before the top-up was made
newBalance	integer	Indicates the balance of the sender's account after the top-up was made
cost	integer	Indicates the amount deducted from your account for the top-up.
currencyCode	string	Indicates the currency code of the sender's account
currencyName	string	Indicates the currency denomination of the sender's account
updatedAt	string	Indicates the time the account's balance was updated to reflect the last top-up made

Flowchart for an airtime top-up