Start Disbursement

POST {api-url}/disburse/start?ns={community}

Starts a disbursement asynchronously. This endpoint validates the CSV file, verifies sufficient funds from the funding source, and begins the process of creating vouchers in the background. It returns immediately with a disbursement route object, which contains the UIDx and DisbursementID needed to track the progress or to perform any other disbursement API call.

Request
Response

Parameters

Field	Type	Requirement	Description
`DisbursementID`	String	Required	The unique ID returned from the `/disburse/initiate` call.
`Name`	String	Required	A descriptive name for this disbursement batch. Does not have to be unique.
`ExpectedTotal`	Integer	Required	The total amount in cents that you expect to be disbursed. Must match the sum of valid amounts in the CSV.
`CheckIDCellMatch`	Boolean	Required	If `true`, enforces that the MSISDN and ID Number in the CSV must match an existing user record.
`VoucherNo`	String	Conditional	A valid Celbux cash voucher to fund the disbursement. Required if `OAuthToken` is not provided.
`OAuthToken`	String	Conditional	A valid OAuth token representing a user’s wallet to fund. Required if `VoucherNo` is not provided.
`ExpectedFeesTotal`	Integer	Optional	The total fees in cents that you expect to be charged. Must match calculated fees.
`IsSingleUse`	Boolean	Optional	Determines if the created voucher numbers change on a successful transaction.
`ShowVouchers`	Boolean	Optional	If `true`, fees are calculated based on `CostPerManualVoucher`, and MSISDNs are not validated on viral user creation. If `false`, fees are calculated based on `CostPerUserVoucher`.
`Metadata`	String	Optional	Any other detail that the merchant wishes to store on this transaction.

Example Body

{
  "Name": "Disbursement Test #1",
  "DisbursementID": "7bcddfd9-5b87-4d61-adb7-16f2c0cb32c1",
  "OAuthToken": "7d833123ee3cad96afce2c9ea449daaf1e7185e9fe26f814f3c7a1061a0d1b87",
  "VoucherNo": "",
  "ExpectedTotal": 208006280,
  "ExpectedFeesTotal": 99960,
  "IsSingleUse": true,
  "ShowVouchers": false,
  "CheckIDCellMatch": false,
  "Metadata": "{\"ActorUserIDs\": \"547828938941114\"}"
}

Parameters

Field	Type	Description
`VoucherRoute`	Object	The complete and updated VoucherRoute object for the disbursement.

Example Body

{
    "TID": "",
    "ReverseTID": "",
    "UIDx": 637,
    "DisbursementID": "7bcddfd9-5b87-4d61-adb7-16f2c0cb32c1",
    "Name": "Disbursement Test #1",
    "Status": "Enqueueing tasks...",
    "Username": "FunderDemo",
    "ExpectedTotal": 208006280,
    "FeesTotal": 99960,
    "RollbackTotal": 0,
    "RollbackFeesTotal": 0,
    "CostPerManualVoucher": 100,
    "CostPerUserVoucher": 10,
    "VoucherCount": 9996,
    "ScheduledTime": "",
    "ShouldNotify": false,
    "IsSingleUse": true,
    "ShowVouchers": false,
    "CheckIDCellMatch": true,
    "URL": "https://dev1celbux.appspot.com/FAPI?cmd=wbin",
    "Community": "fundingco"
}

curl -X POST '{api-url}/disburse/start?ns={community}' \
-H 'Authorization: bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"Name":"Disbursement Test #1","DisbursementID":"7bcddfd9-5b87-4d61-adb7-16f2c0cb32c1","OAuthToken":"7d833123ee3cad96afce2c9ea449daaf1e7185e9fe26f814f3c7a1061a0d1b87","VoucherNo":"","ExpectedTotal":208006280,"ExpectedFeesTotal":99960,"IsSingleUse":true,"ShowVouchers":false,"CheckIDCellMatch":false,"Metadata":"{\"ActorUserIDs\": \"547828938941114\"}"}'

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

class Program
{
    static async Task Main(string[] args)
    {
        var client = new HttpClient();
        var request = new HttpRequestMessage(HttpMethod.Post, "{api-url}/disburse/start?ns={community}");
        request.Headers.Add("Authorization", "bearer YOUR_TOKEN");

        var jsonPayload = @"{
  ""Name"": ""Disbursement Test #1"",
  ""DisbursementID"": ""7bcddfd9-5b87-4d61-adb7-16f2c0cb32c1"",
  ""OAuthToken"": ""7d833123ee3cad96afce2c9ea449daaf1e7185e9fe26f814f3c7a1061a0d1b87"",
  ""VoucherNo"": """",
  ""ExpectedTotal"": 208006280,
  ""ExpectedFeesTotal"": 99960,
  ""IsSingleUse"": true,
  ""ShowVouchers"": false,
  ""CheckIDCellMatch"": false,
  ""Metadata"": ""{\""ActorUserIDs\"": \""547828938941114\""}""
}";
        request.Content = new StringContent(jsonPayload, Encoding.UTF8, "application/json");

        var response = await client.SendAsync(request);
        response.EnsureSuccessStatusCode();

        var responseBody = await response.Content.ReadAsStringAsync();
        Console.WriteLine(responseBody);
    }
}

package main

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

func main() {
  url := "{api-url}/disburse/start?ns={community}"
  payload := strings.NewReader(`{"Name":"Disbursement Test #1","DisbursementID":"7bcddfd9-5b87-4d61-adb7-16f2c0cb32c1","OAuthToken":"7d833123ee3cad96afce2c9ea449daaf1e7185e9fe26f814f3c7a1061a0d1b87","VoucherNo":"","ExpectedTotal":208006280,"ExpectedFeesTotal":99960,"IsSingleUse":true,"ShowVouchers":false,"CheckIDCellMatch":false,"Metadata":"{\"ActorUserIDs\": \"547828938941114\"}"}`)

  req, _ := http.NewRequest("POST", url, payload)
  req.Header.Add("Authorization", "bearer YOUR_TOKEN")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()

  body, _ := ioutil.ReadAll(res.Body)
  fmt.Println(string(body))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ApiRequest {
    public static void main(String[] args) throws Exception {
        var payload = """
                {
  "Name": "Disbursement Test #1",
  "DisbursementID": "7bcddfd9-5b87-4d61-adb7-16f2c0cb32c1",
  "OAuthToken": "7d833123ee3cad96afce2c9ea449daaf1e7185e9fe26f814f3c7a1061a0d1b87",
  "VoucherNo": "",
  "ExpectedTotal": 208006280,
  "ExpectedFeesTotal": 99960,
  "IsSingleUse": true,
  "ShowVouchers": false,
  "CheckIDCellMatch": false,
  "Metadata": "{\"ActorUserIDs\": \"547828938941114\"}"
}
                """;

        var request = HttpRequest.newBuilder()
                .uri(URI.create("{api-url}/disburse/start?ns={community}"))
                .header("Authorization", "bearer YOUR_TOKEN")
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(payload))
                .build();

        var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

// Requires Node.js v18+
(async () => {
    const url = '{api-url}/disburse/start?ns={community}';
    const payload = {
    "Name": "Disbursement Test #1",
    "DisbursementID": "7bcddfd9-5b87-4d61-adb7-16f2c0cb32c1",
    "OAuthToken": "7d833123ee3cad96afce2c9ea449daaf1e7185e9fe26f814f3c7a1061a0d1b87",
    "VoucherNo": "",
    "ExpectedTotal": 208006280,
    "ExpectedFeesTotal": 99960,
    "IsSingleUse": true,
    "ShowVouchers": false,
    "CheckIDCellMatch": false,
    "Metadata": {
        "ActorUserIDs": "547828938941114"
    }
};

    try {
        const response = await fetch(url, {
            method: 'POST',
            headers: {
                'Authorization': 'bearer YOUR_TOKEN',
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(payload)
        });
        const data = await response.json();
        console.log(data);
    } catch (error) {
        console.error('Error:', error);
    }
})();

<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '{api-url}/disburse/start?ns={community}',
  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 => '{
  "Name": "Disbursement Test #1",
  "DisbursementID": "7bcddfd9-5b87-4d61-adb7-16f2c0cb32c1",
  "OAuthToken": "7d833123ee3cad96afce2c9ea449daaf1e7185e9fe26f814f3c7a1061a0d1b87",
  "VoucherNo": "",
  "ExpectedTotal": 208006280,
  "ExpectedFeesTotal": 99960,
  "IsSingleUse": true,
  "ShowVouchers": false,
  "CheckIDCellMatch": false,
  "Metadata": "{\"ActorUserIDs\": \"547828938941114\"}"
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: bearer YOUR_TOKEN',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);
curl_close($curl);
echo $response;

import requests
import json

url = "{api-url}/disburse/start?ns={community}"
payload = {
  "Name": "Disbursement Test #1",
  "DisbursementID": "7bcddfd9-5b87-4d61-adb7-16f2c0cb32c1",
  "OAuthToken": "7d833123ee3cad96afce2c9ea449daaf1e7185e9fe26f814f3c7a1061a0d1b87",
  "VoucherNo": "",
  "ExpectedTotal": 208006280,
  "ExpectedFeesTotal": 99960,
  "IsSingleUse": True,
  "ShowVouchers": False,
  "CheckIDCellMatch": False,
  "Metadata": {
    "ActorUserIDs": "547828938941114"
  }
}

headers = {
    "Authorization": "bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

require 'uri'
require 'net/http'
require 'json'

url = URI("{api-url}/disburse/start?ns={community}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'bearer YOUR_TOKEN'
request["Content-Type"] = 'application/json'

request.body = JSON.dump({
  "Name": "Disbursement Test #1",
  "DisbursementID": "7bcddfd9-5b87-4d61-adb7-16f2c0cb32c1",
  "OAuthToken": "7d833123ee3cad96afce2c9ea449daaf1e7185e9fe26f814f3c7a1061a0d1b87",
  "VoucherNo": "",
  "ExpectedTotal": 208006280,
  "ExpectedFeesTotal": 99960,
  "IsSingleUse": true,
  "ShowVouchers": false,
  "CheckIDCellMatch": false,
  "Metadata": {
    "ActorUserIDs": "547828938941114"
  }
})

response = http.request(request)
puts response.read_body