Submit representment plan evidences

curl --request POST \
  --url https://api.staging.payrails.io/dispute/disputes/{disputeId}/evidences/submit-plan \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "evidences": [
    {
      "evidenceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "position": 1,
      "labels": [
        "<string>"
      ]
    }
  ]
}
'

import requests

url = "https://api.staging.payrails.io/dispute/disputes/{disputeId}/evidences/submit-plan"

payload = { "evidences": [
        {
            "evidenceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "position": 1,
            "labels": ["<string>"]
        }
    ] }
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({
    evidences: [
      {
        evidenceId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
        position: 1,
        labels: ['<string>']
      }
    ]
  })
};

fetch('https://api.staging.payrails.io/dispute/disputes/{disputeId}/evidences/submit-plan', 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/submit-plan",
  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([
    'evidences' => [
        [
                'evidenceId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
                'position' => 1,
                'labels' => [
                                '<string>'
                ]
        ]
    ]
  ]),
  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/submit-plan"

	payload := strings.NewReader("{\n  \"evidences\": [\n    {\n      \"evidenceId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"position\": 1,\n      \"labels\": [\n        \"<string>\"\n      ]\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/submit-plan")
  .header("x-idempotency-key", "<x-idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"evidences\": [\n    {\n      \"evidenceId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"position\": 1,\n      \"labels\": [\n        \"<string>\"\n      ]\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.staging.payrails.io/dispute/disputes/{disputeId}/evidences/submit-plan")

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  \"evidences\": [\n    {\n      \"evidenceId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"position\": 1,\n      \"labels\": [\n        \"<string>\"\n      ]\n    }\n  ]\n}"

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

{
  "representmentPlan": {
    "disputeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "status": "GeneratingPlan",
    "providerResponseId": "<string>",
    "recommendation": "<string>",
    "rationale": "<string>",
    "defenseReasons": [
      {
        "code": "<string>",
        "title": "<string>",
        "description": "<string>",
        "selected": true,
        "options": [
          {
            "position": 123,
            "title": "<string>",
            "description": "<string>",
            "required": true,
            "slug": "<string>",
            "evidenceInfo": {
              "displayTitle": "<string>",
              "contentType": "<string>",
              "contentLength": 123
            }
          }
        ]
      }
    ]
  },
  "representmentSections": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "disputeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "position": 123,
      "indent": 123,
      "sectionType": "Text",
      "textSectionTitle": "<string>",
      "textSectionContent": "<string>",
      "pictureSectionEvidenceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "pictureSectionLabel": "<string>",
      "pictureSectionEvidenceLinks": {
        "download": "<string>"
      }
    }
  ],
  "timeline": [
    {
      "date": "2023-12-25",
      "message": "<string>"
    }
  ]
}

{
  "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"
    }
  ]
}

POST

https://api.staging.payrails.io

dispute

disputes

{disputeId}

evidences

submit-plan

Submit representment plan evidences

curl --request POST \
  --url https://api.staging.payrails.io/dispute/disputes/{disputeId}/evidences/submit-plan \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "evidences": [
    {
      "evidenceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "position": 1,
      "labels": [
        "<string>"
      ]
    }
  ]
}
'

import requests

url = "https://api.staging.payrails.io/dispute/disputes/{disputeId}/evidences/submit-plan"

payload = { "evidences": [
        {
            "evidenceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "position": 1,
            "labels": ["<string>"]
        }
    ] }
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({
    evidences: [
      {
        evidenceId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
        position: 1,
        labels: ['<string>']
      }
    ]
  })
};

fetch('https://api.staging.payrails.io/dispute/disputes/{disputeId}/evidences/submit-plan', 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/submit-plan",
  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([
    'evidences' => [
        [
                'evidenceId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
                'position' => 1,
                'labels' => [
                                '<string>'
                ]
        ]
    ]
  ]),
  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/submit-plan"

	payload := strings.NewReader("{\n  \"evidences\": [\n    {\n      \"evidenceId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"position\": 1,\n      \"labels\": [\n        \"<string>\"\n      ]\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/submit-plan")
  .header("x-idempotency-key", "<x-idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"evidences\": [\n    {\n      \"evidenceId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"position\": 1,\n      \"labels\": [\n        \"<string>\"\n      ]\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.staging.payrails.io/dispute/disputes/{disputeId}/evidences/submit-plan")

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  \"evidences\": [\n    {\n      \"evidenceId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"position\": 1,\n      \"labels\": [\n        \"<string>\"\n      ]\n    }\n  ]\n}"

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

{
  "representmentPlan": {
    "disputeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "status": "GeneratingPlan",
    "providerResponseId": "<string>",
    "recommendation": "<string>",
    "rationale": "<string>",
    "defenseReasons": [
      {
        "code": "<string>",
        "title": "<string>",
        "description": "<string>",
        "selected": true,
        "options": [
          {
            "position": 123,
            "title": "<string>",
            "description": "<string>",
            "required": true,
            "slug": "<string>",
            "evidenceInfo": {
              "displayTitle": "<string>",
              "contentType": "<string>",
              "contentLength": 123
            }
          }
        ]
      }
    ]
  },
  "representmentSections": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "disputeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "position": 123,
      "indent": 123,
      "sectionType": "Text",
      "textSectionTitle": "<string>",
      "textSectionContent": "<string>",
      "pictureSectionEvidenceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "pictureSectionLabel": "<string>",
      "pictureSectionEvidenceLinks": {
        "download": "<string>"
      }
    }
  ],
  "timeline": [
    {
      "date": "2023-12-25",
      "message": "<string>"
    }
  ]
}

{
  "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

Authorization

string

header

required

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

x-idempotency-key

string<uuid>

required

Idempotency key to be used. Sending again the same key would return the same result without re-executing the update.

Path Parameters

disputeId

string<uuid>

required

Identifier of the resource in Payrails.

Body

application/json

evidences

object[]

required

List of selected representment plan evidence items and target positions. Each position must be unique.

Minimum array length: 1

Hide child attributes

evidences.evidenceId

string<uuid>

required

Unique identifier of an uploaded evidence linked to this dispute.

evidences.position

integer

required

Target representment plan evidence position to associate with evidenceId.

Required range: x >= 0

evidences.labels

string[]

Labels to assign to this evidence for the dispute, used to categorise the document during representment.

selectedDefenseReasonCode

string

The provider reason code the merchant wants to defend with. If omitted, the LLM-suggested code from plan generation remains in effect.

userPrompt

string

Additional user prompt to generate representment sections. If not provided, the system will use a default prompt.

Response

Evidence selections saved and representment sections generated.

representmentPlan

object

required

Updated representment plan after selected evidences were stored.

Hide child attributes

representmentPlan.disputeId

string<uuid>

required

Unique identifier of the dispute in Payrails.

representmentPlan.createdAt

string<date-time>

required

Date and time when the representment plan was created in Payrails.

representmentPlan.updatedAt

string<date-time>

required

Date and time when the representment plan was last updated in Payrails.

representmentPlan.status

enum<string>

required

Status of the representment plan lifecycle.

Available options:

GeneratingPlan,

PlanReady,

StoringEvidences,

LabelingEvidences,

EvidencesReady,

GeneratingRepresentment,

RepresentmentReady,

Submitted

representmentPlan.providerResponseId

string

Provider response identifier for representment plan generation.

representmentPlan.recommendation

string

Recommended action for the merchant (e.g. "defend" or "accept").

representmentPlan.rationale

string

Explanation supporting the recommendation.

representmentPlan.defenseReasons

object[]

Defense reason codes with evidence options, grouped by provider reason code.

Hide child attributes

representmentPlan.defenseReasons.code

string

required

Adyen defense document type code.

representmentPlan.defenseReasons.title

string

required

Human-readable name for this defense document type.

representmentPlan.defenseReasons.description

string

required

Explanation of what this defense document type covers.

representmentPlan.defenseReasons.selected

boolean

required

Whether this defense type is the recommended selection.

representmentPlan.defenseReasons.options

object[]

required

Evidence suggestions within this defense type.

Hide child attributes

representmentPlan.defenseReasons.options.position

integer

required

Ordering position of this option within the defense type.

representmentPlan.defenseReasons.options.title

string

required

Suggested title for this evidence.

representmentPlan.defenseReasons.options.description

string

required

Suggested details to include for this evidence.

representmentPlan.defenseReasons.options.required

boolean

required

Whether this evidence is mandatory for the defense.

representmentPlan.defenseReasons.options.slug

string

Machine-readable identifier for the evidence type.

representmentPlan.defenseReasons.options.evidenceInfo

object

Display metadata for the already-uploaded evidence file, present when evidenceId is set.

Hide child attributes

representmentPlan.defenseReasons.options.evidenceInfo.displayTitle

string

Human-readable file name or title of the uploaded evidence.

representmentPlan.defenseReasons.options.evidenceInfo.contentType

string

MIME type of the uploaded evidence file.

representmentPlan.defenseReasons.options.evidenceInfo.contentLength

integer

Size of the uploaded evidence file in bytes.

representmentSections

object[]

required

Generated ordered representment sections based on selected evidences (Timeline sections excluded).

Hide child attributes

representmentSections.id

string<uuid>

required

Unique identifier of the representment section in Payrails.

representmentSections.disputeId

string<uuid>

required

Unique identifier of the dispute in Payrails.

representmentSections.createdAt

string<date-time>

required

Date and time when the representment section was created in Payrails.

representmentSections.updatedAt

string<date-time>

required

Date and time when the representment section was last updated in Payrails.

representmentSections.position

integer

required

Position of the section in the representment.

representmentSections.indent

integer

required

Indentation level of the section in the representment.

representmentSections.sectionType

enum<string>

required

Type of representment section.

Available options:

Text,

Picture,

Timeline

representmentSections.textSectionTitle

string

Title of the text section when sectionType is Text.

representmentSections.textSectionContent

string

Content of the text section when sectionType is Text.

representmentSections.pictureSectionEvidenceId

string<uuid>

Linked evidence identifier when sectionType is Picture.

representmentSections.pictureSectionLabel

string

Label for the picture section when sectionType is Picture.

representmentSections.pictureSectionEvidenceLinks

object

Links for downloading the picture section evidence file when sectionType is Picture.

Hide child attributes

representmentSections.pictureSectionEvidenceLinks.download

timeline

object[]

Deserialized timeline events extracted from the Timeline section, when present.

Hide child attributes

timeline.date

string<date>

required

Date of the timeline event in ISO 8601 format (YYYY-MM-DD).

timeline.message

string

required

Concise plain-text description of the timeline event (1-2 sentences, no HTML).

Payrails API Reference

Get started

Workflow

Payment

Provider

Merchant

Vault

Analytics

Reporting

Reconciliation

Dispute

Submit representment plan evidences

Authorizations

Headers

Path Parameters

Body

Response