> For the complete documentation index, see [llms.txt](https://raphaelugwu.gitbook.io/airtime/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://raphaelugwu.gitbook.io/airtime/top-ups/async-top-up.md).

# Make an asynchronous top-up

Using the  `/topup-async` endpoint, developers have a faster way to view the status of every top-up that they make in real-time

For every asynchronous top-up that is made, a transaction ID is the only parameter returned as a response. This transaction ID can be used to confirm if the top-up request is successful, still processing, or failed

## Async top-up

<mark style="color:green;">`POST`</mark> `https://topups.reloadly.com/topups-async`

#### Headers

| Name                                            | Type   | Description                                                             |
| ----------------------------------------------- | ------ | ----------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Your access token is required as a bearer token in the request's header |

#### Request Body

| Name                                            | Type    | Description                                                                                                                                                                                                |
| ----------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| operatorId<mark style="color:red;">\*</mark>    | integer | Indicates the operator's ID                                                                                                                                                                                |
| amount<mark style="color:red;">\*</mark>        | 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`. This option is only available for operators that support local top-ups                                     |
| customIdentifier                                | string  | <p>Indicates the transaction reference of the recharge<br><br><em>Note: Each transaction reference is to be unique. Once a reference has been used for a top-up transaction, it cannot be reused.</em></p> |
| recipientEmail                                  | string  | <p>This is the recipient's email address. It is required when the operator is  <code>Nauta Cuba</code><br>It supports only two email domains:<br><br>1.  @nauta.com.cu<br>2.  @nauta.co.cu</p>             |
| receiverPhone<mark style="color:red;">\*</mark> | object  | Indicates an object containing the receiver's country code and mobile number                                                                                                                               |
| senderPhone<mark style="color:red;">\*</mark>   | object  | Indicates an object containing the sender's country code and mobile number                                                                                                                                 |
| countryCode<mark style="color:red;">\*</mark>   | string  | Indicates the ISO code of the receiver's or sender's country. For top-up senders, this parameter is optional                                                                                               |
| number<mark style="color:red;">\*</mark>        | string  | Indicates the mobile number of the top-up receiver or sender. For top-up senders, this parameter is optional                                                                                               |

{% tabs %}
{% tab title="200 This response is gotten when a successful request is made. Note that a transaction ID will still be returned even when the top-up is not successful.

The status of each transaction ID can be confirmed through the/{{transactionId}}/status endpoint" %}
{% tabs %}
{% tab title="JSON" %}

```bash
{
  "transactionId": 282571
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="401 This response is gotten when an incorrect or expired access token is used to make a request" %}
{% tabs %}
{% tab title="JSON" %}

```bash
{
  "timeStamp":"2021-06-08 12:00:54",
  "message":"Full authentication is required to access this resource",
  "path":"/topups-async",
  "errorCode":"INVALID_TOKEN",
  "infoLink":null,
  "details":[
    
  ]
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="404 This response is gotten when a request is made with an incorrect path parameter" %}
{% tabs %}
{% tab title="JSON" %}

```bash
{
  "timestamp":"2021-06-08T12:20:51.818+0000",
  "status":404,
  "error":"Not Found",
  "message":"No message available",
  "path":"/topups-asyn"
}
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

### Request samples

{% tabs %}
{% tab title="cURL" %}

```bash
curl --location --request POST 'https://topups.reloadly.com/topups-async' \
--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"
	}
}'
```

{% endtab %}

{% tab title="C#" %}

```csharp
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-async"){
        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);
    }

  }
}
```

{% endtab %}

{% tab title="Golang" %}

```go
package main

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

func main() {

  url := "https://topups.reloadly.com/topups-async"
  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))
}
```

{% endtab %}

{% tab title="Java" %}

```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-async")
  .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();
```

{% endtab %}

{% tab title="Node JS" %}

```javascript
var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://topups.reloadly.com/topups-async',
  '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);
});
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://topups.reloadly.com/topups-async',
  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;
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import json

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

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

{% endtab %}
{% endtabs %}

###

### Request samples for Nauta Cuba top-ups

{% tabs %}
{% tab title="cURL" %}

```bash
curl --location --request POST 'https://topups.reloadly.com/topups-async' \
--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": "peter@nauta.com.cu",
	"senderPhone": {
		"countryCode": "CA",
		"number": "1231231231"
	}
}'
```

{% endtab %}

{% tab title="C#" %}

```csharp
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-async"){
        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);
    }

  }
}
```

{% endtab %}

{% tab title="Golang" %}

```go
package main

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

func main() {

  url := "https://topups.reloadly.com/topups-async"
  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))
}
```

{% endtab %}

{% tab title="Java" %}

```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\": \"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-async")
  .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();
```

{% endtab %}

{% tab title="Node JS" %}

```javascript
var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://topups.reloadly.com/topups-async',
  '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);
});
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://topups.reloadly.com/topups-async',
  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;
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import json

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

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

{% endtab %}
{% endtabs %}

### Response parameters

| Parameter       | Type    | Description                                                                           |
| --------------- | ------- | ------------------------------------------------------------------------------------- |
| `transactionId` | integer | Indicates the unique ID of an asynchronous top-up which is used to confirm its status |

![Flowchart for an asynchronous top-up](/files/-MgoFPyhzD2AG1BRd7JX)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://raphaelugwu.gitbook.io/airtime/top-ups/async-top-up.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.