# 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](https://3833678278-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M_S2rY6WiakWTQjQh8S%2F-MgoF1Gv3A7-z2FLB6J5%2F-MgoFPyhzD2AG1BRd7JX%2Freloadly%20flows-02.png?alt=media\&token=7de524a2-b97d-4d3a-bcc8-a59707d187cd)