Airtime Ruby Quickstart

This quick start will guide you through integrating Reloadly’s Airtime API into your Ruby application. Prerequisites needed for this guide are:

• The reader should have a decent understanding of Ruby.
• A Reloadly account – if you don’t have one, you can sign up here
• Next, you need to have funds in your test wallet. When you sign up, a certain amount of funds are automatically added to your test wallet. You can fund your live wallet by following the steps in the Wallet section
• Sign in to retrieve your client_id and client_secret keys for test mode. You can get both keys by toggling from live to test mode on the sidebar and navigating to Developers > API settings

Get an access token

Reloadly issues access tokens (also called bearer tokens) that are used to authorize API requests. Using your test client_id and client_secret, make a request to Reloadly’s authorization URL to obtain the appropriate access token. You can get a test access token by making a request in your Ruby application like this

require 'json'
require 'uri'
require 'net/http'
require 'openssl'
 
url = URI('https://auth.reloadly.com/oauth/token')
 
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
 
request = Net::HTTP::Post.new(url)
request['Content-Type'] = 'application/json'
request.body = {
  client_id: 'qwcLzXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
  client_secret: '7kscVxQZ32-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
  grant_type: 'client_credentials',
  audience: 'https://topups-sandbox.reloadly.com'
}.to_json
 
response = http.request(request)
puts response.read_body

Production access tokens are valid for 60 days, test access tokens are only valid for 24 hours.

If your request is successful, you should get the following response.

{
    "access_token": "eyJraWQiOiI1N2JjZjNhNy01YmYwLTQ1M2QtODQ0Mi03ODhlMTA4OWI3MDIiLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI2NzkzIiwiaXNzIjoiaHR0cHM6Ly9yZWxvYWRseS1zYW5kYm94LmF1dGgwLmNvbS8iLCJodHRwczovL3JlbG9hZGx5LmNvbS9zYW5kYm94Ijp0cnVlLCJodHRwczovL3JlbG9hZGx5LmNvbS9wcmVwYWlkVXNlcklkIjoiNjc5MyIsImd0eSI6ImNsaWVudC1jcmVkZW50aWFscyIsImF1ZCI6Imh0dHBzOi8vdG9wdXBzLWhzMjU2LXNhbmRib3gucmVsb2FkbHkuY29tIiwibmJmIjoxNjU0MDgzNjY3LCJhenAiOiI2NzkzIiwic2NvcGUiOiJzZW5kLXRvcHVwcyByZWFkLW9wZXJhdG9ycyByZWFkLXByb21vdGlvbnMgcmVhZC10b3B1cHMtaGlzdG9yeSByZWFkLXByZXBhaWQtYmFsYW5jZSByZWFkLXByZXBhaWQtY29tbWlzc2lvbnMiLCJleHAiOjE2NTQxNzAwNjcsImh0dHBzOi8vcmVsb2FkbHkuY29tL2p0aSI6IjYwMTY4ODNiLWYxYTgtNGJhMy1hNmM3LWIwNjBkNDRmN2EyMCIsImlhdCI6MTY1NDA4MzY2NywianRpIjoiZGUwNzRlM2QtM2JkYi00N2ExLTkzNDktZTk1YmZiNjZlNGVmIn0.ZXUzCYbCCTzpDMr5hP7YvgWYqniy9kBY0Y5vWS8wRrA",
    "scope": "developer",
    "expires_in": 86400,
    "token_type": "Bearer"
}

Make an airtime or data top-up

Now that you have an access token, you can make an airtime or data top-up with the Airtime API. You can find details for the operator of your choice on your Reloadly dashboard by navigating on the sidebar to the Pricing > Airtime section.

In the examples below, we are using a mobile number and an operator registered in the United Arab Emirates to show how making an airtime top-up works in a Ruby application.

require 'json'
require 'uri'
require 'net/http'
require 'openssl'
 
url = URI('https://topups-sandbox.reloadly.com/topups')
 
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
 
request = Net::HTTP::Post.new(url)
request['Content-Type'] = 'application/json'
request['Authorization'] = 'Bearer <YOUR_TOKEN_HERE>'
request.body = {
  operatorId: 1100,
  amount: 832,
  useLocalAmount: false,
  customIdentifier: 'airtime-top-up',
  recipientEmail: 'jeanb@reloadly.com',
  recipientPhone: {
    countryCode: 'AE',
    number: '0503971821'
  },
  senderPhone: {
    countryCode: 'CA',
    number: '11231231231'
  }
}.to_json
 
response = http.request(request)
puts response.read_body

If your request is successful, you should receive a response from Reloadly

{
    "transactionId": 33469,
    "status": "SUCCESSFUL",
    "operatorTransactionId": null,
    "customIdentifier": "airtime-top-up",
    "recipientPhone": "971503971821",
    "recipientEmail": null,
    "senderPhone": "11231231231",
    "countryCode": "AE",
    "operatorId": 1100,
    "operatorName": "Etisalat United Arab Emirates",
    "discount": 41.6,
    "discountCurrencyCode": "NGN",
    "requestedAmount": 832,
    "requestedAmountCurrencyCode": "NGN",
    "deliveredAmount": 5.6,
    "deliveredAmountCurrencyCode": "AED",
    "transactionDate": "2022-06-06 10:57:48",
    "pinDetail": null,
    "balanceInfo": {
        "oldBalance": 809811.69103,
        "newBalance": 809021.29103,
        "cost": 790.4,
        "currencyCode": "NGN",
        "currencyName": "Nigerian Naira",
        "updatedAt": "2022-06-06 14:57:48"
    }
}
 

If you made it to this point, you have successfully made your first top-up in a Ruby application.