curl --request POST \
--url https://api.staging.payrails.io/dispute/disputes/{disputeId}/evidences/generate-representment \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'x-idempotency-key: <x-idempotency-key>' \
--data '
{
"caseDetails": [
{
"label": "Chargeback ID",
"value": "1234567890"
},
{
"label": "Dispute Amount",
"value": "USD 100.00"
}
]
}
'import requests
url = "https://api.staging.payrails.io/dispute/disputes/{disputeId}/evidences/generate-representment"
payload = { "caseDetails": [
{
"label": "Chargeback ID",
"value": "1234567890"
},
{
"label": "Dispute Amount",
"value": "USD 100.00"
}
] }
headers = {
"x-idempotency-key": "<x-idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-idempotency-key': '<x-idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
caseDetails: [
{label: 'Chargeback ID', value: '1234567890'},
{label: 'Dispute Amount', value: 'USD 100.00'}
]
})
};
fetch('https://api.staging.payrails.io/dispute/disputes/{disputeId}/evidences/generate-representment', 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://api.staging.payrails.io/dispute/disputes/{disputeId}/evidences/generate-representment",
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([
'caseDetails' => [
[
'label' => 'Chargeback ID',
'value' => '1234567890'
],
[
'label' => 'Dispute Amount',
'value' => 'USD 100.00'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"x-idempotency-key: <x-idempotency-key>"
],
]);
$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://api.staging.payrails.io/dispute/disputes/{disputeId}/evidences/generate-representment"
payload := strings.NewReader("{\n \"caseDetails\": [\n {\n \"label\": \"Chargeback ID\",\n \"value\": \"1234567890\"\n },\n {\n \"label\": \"Dispute Amount\",\n \"value\": \"USD 100.00\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-idempotency-key", "<x-idempotency-key>")
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://api.staging.payrails.io/dispute/disputes/{disputeId}/evidences/generate-representment")
.header("x-idempotency-key", "<x-idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"caseDetails\": [\n {\n \"label\": \"Chargeback ID\",\n \"value\": \"1234567890\"\n },\n {\n \"label\": \"Dispute Amount\",\n \"value\": \"USD 100.00\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.staging.payrails.io/dispute/disputes/{disputeId}/evidences/generate-representment")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-idempotency-key"] = '<x-idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"caseDetails\": [\n {\n \"label\": \"Chargeback ID\",\n \"value\": \"1234567890\"\n },\n {\n \"label\": \"Dispute Amount\",\n \"value\": \"USD 100.00\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"representmentPlan": {
"disputeId": "bfa98e50-9ae0-42ac-bcc7-e1bd22b2f869",
"providerResponseId": "response_123",
"createdAt": "2026-01-10T12:00:00.000000Z",
"updatedAt": "2026-01-12T14:30:00.000000Z",
"status": "RepresentmentReady",
"evidences": [
{
"disputeId": "bfa98e50-9ae0-42ac-bcc7-e1bd22b2f869",
"createdAt": "2026-01-10T12:00:00.000000Z",
"updatedAt": "2026-01-12T14:30:00.000000Z",
"position": 0,
"title": "Order receipt",
"description": "Attach the purchase receipt.",
"required": true
}
]
},
"generatedEvidence": {
"id": "cf398647-890a-442f-ba49-3776d5f6229e",
"createdAt": "2026-01-13T16:20:11.699603Z",
"updatedAt": "2026-01-13T21:26:55.757444Z",
"workspaceId": "7f9f1882-a103-408d-ac96-46a7021e537a",
"displayTitle": "representment.pdf",
"status": "Active",
"provenance": "Payrails",
"contentType": "application/pdf",
"contentLength": 12456
}
}{
"errors": [
{
"id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
"code": "request.malformed",
"detail": "The request has malformed syntax",
"docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestmalformed"
}
]
}{
"errors": [
{
"id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
"code": "request.unauthorized",
"detail": "The request lacks necessary credentials to perform the specified action",
"docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestunauthorized"
}
]
}{
"errors": [
{
"id": "e7db22b3-914e-4975-928e-9edfb0885bea",
"code": "request.forbidden",
"detail": "The request credentials lack the required permissions to perform the specified action",
"docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestforbidden"
}
]
}{
"errors": [
{
"id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
"code": "request.not-found",
"detail": "The requested resource was not found",
"docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestnot-found"
}
]
}{
"errors": [
{
"id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
"code": "request.conflict",
"detail": "The request operation is not allowed due to a conflict with the current state of the resource",
"docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestconflict"
}
]
}{
"errors": [
{
"id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
"code": "request.rate-limit",
"detail": "Too many requests",
"docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestrate-limit"
}
]
}{
"errors": [
{
"id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
"code": "internal",
"detail": "An internal error occurred",
"docUrl": "https://docs.payrails.com/docs/resources/error-codes#internal"
}
]
}Generate representment PDF
Compile your representment sections into a PDF and attach it to the dispute. Call this after you are satisfied with the written sections and ready to finalize your representment.
curl --request POST \
--url https://api.staging.payrails.io/dispute/disputes/{disputeId}/evidences/generate-representment \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'x-idempotency-key: <x-idempotency-key>' \
--data '
{
"caseDetails": [
{
"label": "Chargeback ID",
"value": "1234567890"
},
{
"label": "Dispute Amount",
"value": "USD 100.00"
}
]
}
'import requests
url = "https://api.staging.payrails.io/dispute/disputes/{disputeId}/evidences/generate-representment"
payload = { "caseDetails": [
{
"label": "Chargeback ID",
"value": "1234567890"
},
{
"label": "Dispute Amount",
"value": "USD 100.00"
}
] }
headers = {
"x-idempotency-key": "<x-idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-idempotency-key': '<x-idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
caseDetails: [
{label: 'Chargeback ID', value: '1234567890'},
{label: 'Dispute Amount', value: 'USD 100.00'}
]
})
};
fetch('https://api.staging.payrails.io/dispute/disputes/{disputeId}/evidences/generate-representment', 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://api.staging.payrails.io/dispute/disputes/{disputeId}/evidences/generate-representment",
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([
'caseDetails' => [
[
'label' => 'Chargeback ID',
'value' => '1234567890'
],
[
'label' => 'Dispute Amount',
'value' => 'USD 100.00'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"x-idempotency-key: <x-idempotency-key>"
],
]);
$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://api.staging.payrails.io/dispute/disputes/{disputeId}/evidences/generate-representment"
payload := strings.NewReader("{\n \"caseDetails\": [\n {\n \"label\": \"Chargeback ID\",\n \"value\": \"1234567890\"\n },\n {\n \"label\": \"Dispute Amount\",\n \"value\": \"USD 100.00\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-idempotency-key", "<x-idempotency-key>")
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://api.staging.payrails.io/dispute/disputes/{disputeId}/evidences/generate-representment")
.header("x-idempotency-key", "<x-idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"caseDetails\": [\n {\n \"label\": \"Chargeback ID\",\n \"value\": \"1234567890\"\n },\n {\n \"label\": \"Dispute Amount\",\n \"value\": \"USD 100.00\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.staging.payrails.io/dispute/disputes/{disputeId}/evidences/generate-representment")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-idempotency-key"] = '<x-idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"caseDetails\": [\n {\n \"label\": \"Chargeback ID\",\n \"value\": \"1234567890\"\n },\n {\n \"label\": \"Dispute Amount\",\n \"value\": \"USD 100.00\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"representmentPlan": {
"disputeId": "bfa98e50-9ae0-42ac-bcc7-e1bd22b2f869",
"providerResponseId": "response_123",
"createdAt": "2026-01-10T12:00:00.000000Z",
"updatedAt": "2026-01-12T14:30:00.000000Z",
"status": "RepresentmentReady",
"evidences": [
{
"disputeId": "bfa98e50-9ae0-42ac-bcc7-e1bd22b2f869",
"createdAt": "2026-01-10T12:00:00.000000Z",
"updatedAt": "2026-01-12T14:30:00.000000Z",
"position": 0,
"title": "Order receipt",
"description": "Attach the purchase receipt.",
"required": true
}
]
},
"generatedEvidence": {
"id": "cf398647-890a-442f-ba49-3776d5f6229e",
"createdAt": "2026-01-13T16:20:11.699603Z",
"updatedAt": "2026-01-13T21:26:55.757444Z",
"workspaceId": "7f9f1882-a103-408d-ac96-46a7021e537a",
"displayTitle": "representment.pdf",
"status": "Active",
"provenance": "Payrails",
"contentType": "application/pdf",
"contentLength": 12456
}
}{
"errors": [
{
"id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
"code": "request.malformed",
"detail": "The request has malformed syntax",
"docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestmalformed"
}
]
}{
"errors": [
{
"id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
"code": "request.unauthorized",
"detail": "The request lacks necessary credentials to perform the specified action",
"docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestunauthorized"
}
]
}{
"errors": [
{
"id": "e7db22b3-914e-4975-928e-9edfb0885bea",
"code": "request.forbidden",
"detail": "The request credentials lack the required permissions to perform the specified action",
"docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestforbidden"
}
]
}{
"errors": [
{
"id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
"code": "request.not-found",
"detail": "The requested resource was not found",
"docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestnot-found"
}
]
}{
"errors": [
{
"id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
"code": "request.conflict",
"detail": "The request operation is not allowed due to a conflict with the current state of the resource",
"docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestconflict"
}
]
}{
"errors": [
{
"id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
"code": "request.rate-limit",
"detail": "Too many requests",
"docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestrate-limit"
}
]
}{
"errors": [
{
"id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
"code": "internal",
"detail": "An internal error occurred",
"docUrl": "https://docs.payrails.com/docs/resources/error-codes#internal"
}
]
}Authorizations
You can use an OAuth2 JWT bearer token in the Authorization header of your API requests for supported endpoints: Authorization: Bearer <YOUR_JWT_HERE>.
These tokens are valid for 10 minutes and can be requested via the access token endpoint endpoint.
Headers
Idempotency key to be used. Sending again the same key would return the same result without re-executing the update.
Path Parameters
Identifier of the resource in Payrails.
Body
Response
Representment PDF compiled and attached to the dispute.
Updated representment plan after representment PDF was generated.
Hide child attributes
Hide child attributes
Unique identifier of the dispute in Payrails.
Date and time when the representment plan was created in Payrails.
Date and time when the representment plan was last updated in Payrails.
Status of the representment plan lifecycle.
GeneratingPlan, PlanReady, StoringEvidences, LabelingEvidences, EvidencesReady, GeneratingRepresentment, RepresentmentReady, Submitted Provider response identifier for representment plan generation.
Recommended action for the merchant (e.g. "defend" or "accept").
Explanation supporting the recommendation.
Defense reason codes with evidence options, grouped by provider reason code.
Hide child attributes
Hide child attributes
Adyen defense document type code.
Human-readable name for this defense document type.
Explanation of what this defense document type covers.
Whether this defense type is the recommended selection.
Evidence suggestions within this defense type.
Hide child attributes
Hide child attributes
Ordering position of this option within the defense type.
Suggested title for this evidence.
Suggested details to include for this evidence.
Whether this evidence is mandatory for the defense.
Machine-readable identifier for the evidence type.
Display metadata for the already-uploaded evidence file, present when evidenceId is set.
Hide child attributes
Hide child attributes
Human-readable file name or title of the uploaded evidence.
MIME type of the uploaded evidence file.
Size of the uploaded evidence file in bytes.
Generated representment PDF evidence metadata.
Hide child attributes
Hide child attributes
Unique identifier of the Dispute in Payrails.
Date and time when the Dispute was created in Payrails.
Date and time when the Dispute was last updated in Payrails.
Display title of the evidence, usually the file name.
Status of the dispute evidence.
Active, Inactive, Unknown Provenance of the dispute evidence.
Merchant, Payrails, Unknown MIME type of the evidence content.
Size of the evidence content in bytes.
Inline JSON payload for inline-context evidences. Present only for evidences created from inlineContexts; omitted for file-backed evidence.
Workspace ID that the Dispute belongs to.
Labels assigned to this evidence for the dispute, used to categorise the document during representment.