Validate

POST {api-url}/validate?ns={community}

Validates a previously uploaded CSV file for a given disbursement. It checks for data formatting errors (such as ensuring your file matches one of the supported CSV Formats), verifies recipients and voucher types, and returns a summary of valid and invalid records along with the calculated costs, without processing any payments.

Request

Parameters

Field	Type	Requirement	Description
DisbursementID	String	Required	The unique ID returned from the /disburse/initiate call.
ShowVouchers	Boolean	Optional	If true, calculate fees based on the manual voucher cost. Additionally, MSISDNs are not validated on viral user creation.
CheckIDCellMatch	Boolean	Optional	If true, enforces that the MSISDN and ID Number in the CSV must match an existing user record.
Metadata	String	Optional	Any other detail that the merchant wishes to store on this transaction.

Example Body

{
  "DisbursementID": "7bcddfd9-5b87-4d61-adb7-16f2c0cb32c1",
  "ShowVouchers": false,
  "CheckIDCellMatch": false,
  "Metadata": "{\"ActorUserIDs\": \"547828938941114\"}"
}

Response

Parameters

Field	Type	Description
SuccessTotal	Integer	The total value in cents of all valid records in the CSV.
FeesTotal	Integer	The total calculated fees in cents for all valid records.
ErrorTotal	Integer	The total value in cents of all invalid records in the CSV.
CostPerManualVoucher	Integer	The fee in cents applied per voucher if ShowVouchers is true.
CostPerUserVoucher	Integer	The standard fee in cents applied per voucher if ShowVouchers is false.
SignedURLErrors	String	A pre-signed URL to download the errors.csv file, returned only if errors are found. Expires in 15 minutes.

Note

To retrieve the data from SignedURLErrors, perform a GET request with the URL.

Example Body

{
    "SuccessTotal": 208006280,
    "FeesTotal": 99960,
    "ErrorTotal": 62800,
    "CostPerManualVoucher": 100,
    "CostPerUserVoucher": 10,
    "SignedURLErrors": "https://storage.googleapis.com/..."
}

cURL

curl -X POST '{api-url}/validate?ns={community}' \
-H 'Authorization: bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"DisbursementID":"7bcddfd9-5b87-4d61-adb7-16f2c0cb32c1","ShowVouchers":false,"CheckIDCellMatch":false,"Metadata":"{\"ActorUserIDs\": \"547828938941114\"}"}'

C#

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}/validate?ns={community}");
        request.Headers.Add("Authorization", "bearer YOUR_TOKEN");

        var jsonPayload = @"{
  ""DisbursementID"": ""7bcddfd9-5b87-4d61-adb7-16f2c0cb32c1"",
  ""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);
    }
}

Go

package main

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

func main() {
  url := "{api-url}/validate?ns={community}"
  payload := strings.NewReader(`{"DisbursementID":"7bcddfd9-5b87-4d61-adb7-16f2c0cb32c1","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))
}

Java

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 = """
                {
  "DisbursementID": "7bcddfd9-5b87-4d61-adb7-16f2c0cb32c1",
  "ShowVouchers": false,
  "CheckIDCellMatch": false,
  "Metadata": "{\"ActorUserIDs\": \"547828938941114\"}"
}
                """;

        var request = HttpRequest.newBuilder()
                .uri(URI.create("{api-url}/validate?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());
    }
}

Node.js

// Requires Node.js v18+
(async () => {
    const url = '{api-url}/validate?ns={community}';
    const payload = {
    "DisbursementID": "7bcddfd9-5b87-4d61-adb7-16f2c0cb32c1",
    "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

<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '{api-url}/validate?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 => '{
  "DisbursementID": "7bcddfd9-5b87-4d61-adb7-16f2c0cb32c1",
  "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;

Python

import requests
import json

url = "{api-url}/validate?ns={community}"
payload = {
  "DisbursementID": "7bcddfd9-5b87-4d61-adb7-16f2c0cb32c1",
  "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())

Ruby

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

url = URI("{api-url}/validate?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({
  "DisbursementID": "7bcddfd9-5b87-4d61-adb7-16f2c0cb32c1",
  "ShowVouchers": false,
  "CheckIDCellMatch": false,
  "Metadata": {
    "ActorUserIDs": "547828938941114"
  }
})

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