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

{
    "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"
    }
}

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

{
  "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 --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"
	}
}'

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);
    }

  }
}

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

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();

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

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

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 --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": "anyone@nauta.com.cu",
	"senderPhone": {
		"countryCode": "CA",
		"number": "1231231231"
	}
}'

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 = "peter@nauta.com.cu"
          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);
    }

  }
}

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": "peter@nauta.com.cu",
	"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))
}

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\": \"peter@nauta.com.cu\",\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();

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": "peter@nauta.com.cu",
    "senderPhone": {
      "countryCode": "CA",
      "number": "1231231231"
    }
  })

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

<?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": "peter@nauta.com.cu",
	"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;

import requests
import json

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

payload = json.dumps({
  "operatorId": "685",
  "amount": "10",
  "customIdentifier": "This is example identifier 092",
  "recipientEmail": "peter@nauta.com.cu",
  "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

PreviousGet promotion by operator ID NextMake an asynchronous top-up

Last updated 3 years ago

Was this helpful?