curl -X POST "https://dev.api.onekhusa.com/sandbox/v1/disputes/add" \
--header "Authorization: Bearer your-jwt-token" \
--header "Content-Type: application/json" \
-d '{
"documentTypeId": "CUC",
"contentType": "PDF",
"contentBase64": "UEsDBBQAAAAIAA..",
"evidenceDueBy": "2026-04-27T09:47:36.088Z",
"merchantAccountNumber": 55555836,
"transactionReferenceNumber": "250828AU2LXJ",
"transactionType": "SD",
"amountDisputed": 1000000000,
"reason": "Service not rendered",
"description": "The receiver did not get the funds despite being successful",
"capturedBy": "jamesgongwe@gmail.com"
}'import requests
url = "https://dev.api.onekhusa.com/sandbox/v1/disputes/add"
payload = {
"documentTypeId": "CUC",
"contentType": "PDF",
"contentBase64": "UEsDBBQAAAAIAA..",
"evidenceDueBy": "2026-04-27T09:47:36.088Z",
"merchantAccountNumber": 55555836,
"transactionReferenceNumber": "250828AU2LXJ",
"beneficiaryAccountNumber": "10012301020",
"transactionType": "SD",
"amountDisputed": 1000000000,
"reason": "Service not rendered",
"description": "The receiver did not get the funds despite being successful",
"capturedBy": "jamesgongwe@gmail.com"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
documentTypeId: 'CUC',
contentType: 'PDF',
contentBase64: 'UEsDBBQAAAAIAA..',
evidenceDueBy: '2026-04-27T09:47:36.088Z',
merchantAccountNumber: 55555836,
transactionReferenceNumber: '250828AU2LXJ',
beneficiaryAccountNumber: '10012301020',
transactionType: 'SD',
amountDisputed: 1000000000,
reason: 'Service not rendered',
description: 'The receiver did not get the funds despite being successful',
capturedBy: 'jamesgongwe@gmail.com'
})
};
fetch('https://dev.api.onekhusa.com/sandbox/v1/disputes/add', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://dev.api.onekhusa.com/sandbox/v1/disputes/add",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'documentTypeId' => 'CUC',
'contentType' => 'PDF',
'contentBase64' => 'UEsDBBQAAAAIAA..',
'evidenceDueBy' => '2026-04-27T09:47:36.088Z',
'merchantAccountNumber' => 55555836,
'transactionReferenceNumber' => '250828AU2LXJ',
'beneficiaryAccountNumber' => '10012301020',
'transactionType' => 'SD',
'amountDisputed' => 1000000000,
'reason' => 'Service not rendered',
'description' => 'The receiver did not get the funds despite being successful',
'capturedBy' => 'jamesgongwe@gmail.com'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://dev.api.onekhusa.com/sandbox/v1/disputes/add"
payload := strings.NewReader("{\n \"documentTypeId\": \"CUC\",\n \"contentType\": \"PDF\",\n \"contentBase64\": \"UEsDBBQAAAAIAA..\",\n \"evidenceDueBy\": \"2026-04-27T09:47:36.088Z\",\n \"merchantAccountNumber\": 55555836,\n \"transactionReferenceNumber\": \"250828AU2LXJ\",\n \"beneficiaryAccountNumber\": \"10012301020\",\n \"transactionType\": \"SD\",\n \"amountDisputed\": 1000000000,\n \"reason\": \"Service not rendered\",\n \"description\": \"The receiver did not get the funds despite being successful\",\n \"capturedBy\": \"jamesgongwe@gmail.com\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://dev.api.onekhusa.com/sandbox/v1/disputes/add")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"documentTypeId\": \"CUC\",\n \"contentType\": \"PDF\",\n \"contentBase64\": \"UEsDBBQAAAAIAA..\",\n \"evidenceDueBy\": \"2026-04-27T09:47:36.088Z\",\n \"merchantAccountNumber\": 55555836,\n \"transactionReferenceNumber\": \"250828AU2LXJ\",\n \"beneficiaryAccountNumber\": \"10012301020\",\n \"transactionType\": \"SD\",\n \"amountDisputed\": 1000000000,\n \"reason\": \"Service not rendered\",\n \"description\": \"The receiver did not get the funds despite being successful\",\n \"capturedBy\": \"jamesgongwe@gmail.com\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://dev.api.onekhusa.com/sandbox/v1/disputes/add")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"documentTypeId\": \"CUC\",\n \"contentType\": \"PDF\",\n \"contentBase64\": \"UEsDBBQAAAAIAA..\",\n \"evidenceDueBy\": \"2026-04-27T09:47:36.088Z\",\n \"merchantAccountNumber\": 55555836,\n \"transactionReferenceNumber\": \"250828AU2LXJ\",\n \"beneficiaryAccountNumber\": \"10012301020\",\n \"transactionType\": \"SD\",\n \"amountDisputed\": 1000000000,\n \"reason\": \"Service not rendered\",\n \"description\": \"The receiver did not get the funds despite being successful\",\n \"capturedBy\": \"jamesgongwe@gmail.com\"\n}"
response = http.request(request)
puts response.read_body{
"message": "Dispute has been created successfully"
}Add Dispute
This endpoint allows merchants to initiate a dispute by providing transaction details and the reason for the claim. Once submitted, the dispute enters the review workflow.
curl -X POST "https://dev.api.onekhusa.com/sandbox/v1/disputes/add" \
--header "Authorization: Bearer your-jwt-token" \
--header "Content-Type: application/json" \
-d '{
"documentTypeId": "CUC",
"contentType": "PDF",
"contentBase64": "UEsDBBQAAAAIAA..",
"evidenceDueBy": "2026-04-27T09:47:36.088Z",
"merchantAccountNumber": 55555836,
"transactionReferenceNumber": "250828AU2LXJ",
"transactionType": "SD",
"amountDisputed": 1000000000,
"reason": "Service not rendered",
"description": "The receiver did not get the funds despite being successful",
"capturedBy": "jamesgongwe@gmail.com"
}'import requests
url = "https://dev.api.onekhusa.com/sandbox/v1/disputes/add"
payload = {
"documentTypeId": "CUC",
"contentType": "PDF",
"contentBase64": "UEsDBBQAAAAIAA..",
"evidenceDueBy": "2026-04-27T09:47:36.088Z",
"merchantAccountNumber": 55555836,
"transactionReferenceNumber": "250828AU2LXJ",
"beneficiaryAccountNumber": "10012301020",
"transactionType": "SD",
"amountDisputed": 1000000000,
"reason": "Service not rendered",
"description": "The receiver did not get the funds despite being successful",
"capturedBy": "jamesgongwe@gmail.com"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
documentTypeId: 'CUC',
contentType: 'PDF',
contentBase64: 'UEsDBBQAAAAIAA..',
evidenceDueBy: '2026-04-27T09:47:36.088Z',
merchantAccountNumber: 55555836,
transactionReferenceNumber: '250828AU2LXJ',
beneficiaryAccountNumber: '10012301020',
transactionType: 'SD',
amountDisputed: 1000000000,
reason: 'Service not rendered',
description: 'The receiver did not get the funds despite being successful',
capturedBy: 'jamesgongwe@gmail.com'
})
};
fetch('https://dev.api.onekhusa.com/sandbox/v1/disputes/add', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://dev.api.onekhusa.com/sandbox/v1/disputes/add",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'documentTypeId' => 'CUC',
'contentType' => 'PDF',
'contentBase64' => 'UEsDBBQAAAAIAA..',
'evidenceDueBy' => '2026-04-27T09:47:36.088Z',
'merchantAccountNumber' => 55555836,
'transactionReferenceNumber' => '250828AU2LXJ',
'beneficiaryAccountNumber' => '10012301020',
'transactionType' => 'SD',
'amountDisputed' => 1000000000,
'reason' => 'Service not rendered',
'description' => 'The receiver did not get the funds despite being successful',
'capturedBy' => 'jamesgongwe@gmail.com'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://dev.api.onekhusa.com/sandbox/v1/disputes/add"
payload := strings.NewReader("{\n \"documentTypeId\": \"CUC\",\n \"contentType\": \"PDF\",\n \"contentBase64\": \"UEsDBBQAAAAIAA..\",\n \"evidenceDueBy\": \"2026-04-27T09:47:36.088Z\",\n \"merchantAccountNumber\": 55555836,\n \"transactionReferenceNumber\": \"250828AU2LXJ\",\n \"beneficiaryAccountNumber\": \"10012301020\",\n \"transactionType\": \"SD\",\n \"amountDisputed\": 1000000000,\n \"reason\": \"Service not rendered\",\n \"description\": \"The receiver did not get the funds despite being successful\",\n \"capturedBy\": \"jamesgongwe@gmail.com\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://dev.api.onekhusa.com/sandbox/v1/disputes/add")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"documentTypeId\": \"CUC\",\n \"contentType\": \"PDF\",\n \"contentBase64\": \"UEsDBBQAAAAIAA..\",\n \"evidenceDueBy\": \"2026-04-27T09:47:36.088Z\",\n \"merchantAccountNumber\": 55555836,\n \"transactionReferenceNumber\": \"250828AU2LXJ\",\n \"beneficiaryAccountNumber\": \"10012301020\",\n \"transactionType\": \"SD\",\n \"amountDisputed\": 1000000000,\n \"reason\": \"Service not rendered\",\n \"description\": \"The receiver did not get the funds despite being successful\",\n \"capturedBy\": \"jamesgongwe@gmail.com\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://dev.api.onekhusa.com/sandbox/v1/disputes/add")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"documentTypeId\": \"CUC\",\n \"contentType\": \"PDF\",\n \"contentBase64\": \"UEsDBBQAAAAIAA..\",\n \"evidenceDueBy\": \"2026-04-27T09:47:36.088Z\",\n \"merchantAccountNumber\": 55555836,\n \"transactionReferenceNumber\": \"250828AU2LXJ\",\n \"beneficiaryAccountNumber\": \"10012301020\",\n \"transactionType\": \"SD\",\n \"amountDisputed\": 1000000000,\n \"reason\": \"Service not rendered\",\n \"description\": \"The receiver did not get the funds despite being successful\",\n \"capturedBy\": \"jamesgongwe@gmail.com\"\n}"
response = http.request(request)
puts response.read_body{
"message": "Dispute has been created successfully"
}Authorizations
Bearer authentication header of the form Bearer Token, Where accessToken is the access token used to authenticate the request.
Body
Due date of the evidence
"2026-04-27T09:47:36.088Z"
Required string length: 8
10000000 <= x <= 9999999955555836
Unique reference number for the transaction
"250828AU2LXJ"
The type of the transaction being disputed (e.g., "SD", "BD")
"SD"
The amount being disputed
100000000
The reason for opening the dispute
"Service not rendered"
More details for opening the dispute
"The receiver did not get the funds despite being successful"
User identifier who added the dispute
"jamesgongwe@gmail.com"
The identifier of the document type
"CUC"
The content type of the file eg (PNG,JPG,CSV,XLSX & PDF)
"PDF"
Base64-encoded content of the file
"UEsDBBQAAAAIAA.."
Response
Dispute has been created successfully
"Dispute has been created successfully"