Create a dispute by uploading a document.
- Paymish
- Dispute
Create a dispute by uploading a document.
Purpose
Use this endpoint to create a dispute by uploading a document. It belongs to the Dispute collection and is designed for backend integrations.
Request shape
0 parameters and
4 documented body fields
using multipart/form-data.
Recommended workflow
Authenticate first and inject a valid bearer token or secret key before calling the endpoint.
Validate the input data, identifiers, and account state in your application before making the request.
Send the POST request from your backend using the required headers and the expected content type (multipart/form-data).
Persist the important identifiers returned in the response so later lookups, webhooks, or support actions can be linked correctly.
Implementation notes
- Validate the request payload on your backend before sending it, especially the 4 documented body fields.
- Send file uploads as multipart form data and let your client library set the boundary automatically.
- Protect state-changing operations with strong validation, logging, and retry rules to avoid duplicate mutations.
Request Body
Content type: multipart/form-data
image
transactionRef
disputeReason
disputeDescription
Responses
Expected Outcomes
Dispute recorded
Dispute created successfully with the uploaded document
{
"message": "Create dispute successfully"
}Dispute rejected
Bad request due to invalid or missing parameters
{
"message": "Missing required fields or invalid data."
}- Verify the transaction reference and business reason before resubmitting the dispute flow.
- Persist the dispute ID and internal support case together as soon as the request succeeds.
- Retry only after correcting the payload or eligibility issue rather than repeating the same rejected request.
Language Notes
Python
Use `requests` from a backend worker, service, or Django/Flask app and centralize headers in a reusable helper.
Node.js
Use `axios` or `fetch` from Node.js services only; do not place secret credentials in frontend bundles.
PHP
Wrap cURL usage in a small client class so auth headers, error handling, and logging stay consistent.
cURL
Use cURL for smoke testing and debugging, then move the final logic into your backend service code.
Code Examples
import requests
headers = {
"Authorization": "Bearer YOUR_SECRET_KEY",
}
data = {
"transactionRef": "value",
"disputeReason": "value",
"disputeDescription": "value"
}
files = {
"image": open("path/to/file.pdf", "rb")
}
response = requests.post(
"https://api.paymish.com/api/dispute-service/external/v1/create-dispute",
headers=headers,
data=data,
files=files,
)
print(response.json())const axios = require("axios");
const fs = require("fs");
const FormData = require("form-data");
const formData = new FormData();
formData.append("transactionRef", "value");
formData.append("disputeReason", "value");
formData.append("disputeDescription", "value");
formData.append("image", fs.createReadStream("path/to/file.pdf"));
const response = await axios({
method: "post",
url: "https://api.paymish.com/api/dispute-service/external/v1/create-dispute",
headers: {
...formData.getHeaders(),
Authorization: "Bearer YOUR_SECRET_KEY",
},
data: formData
});
console.log(response.data);curl https://api.paymish.com/api/dispute-service/external/v1/create-dispute \
-X POST \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-F "transactionRef=value"\
-F "disputeReason=value"\
-F "disputeDescription=value"\
-F "image=@path/to/file.pdf"<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.paymish.com/api/dispute-service/external/v1/create-dispute");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Bearer YOUR_SECRET_KEY",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, [
"transactionRef" => "value",
"disputeReason" => "value",
"disputeDescription" => "value",
"image" => new CURLFile("path/to/file.pdf"),
]);
$response = curl_exec($ch);
curl_close($ch);
print_r(json_decode($response, true));