Upload evidence files

curl --request POST \
  --url https://api.staging.payrails.io/dispute/disputes/{disputeId}/evidences \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-idempotency-key: <x-idempotency-key>'

import requests

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

payload = "-----011000010111000001101001\r\n-----011000010111000001101001--"
headers = {
    "x-idempotency-key": "<x-idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "multipart/form-data"
}

response = requests.post(url, data=payload, headers=headers)

print(response.text)

const form = new FormData();

const options = {
  method: 'POST',
  headers: {'x-idempotency-key': '<x-idempotency-key>', Authorization: 'Bearer <token>'}
};

options.body = form;

fetch('https://api.staging.payrails.io/dispute/disputes/{disputeId}/evidences', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data",
    "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"

	payload := strings.NewReader("-----011000010111000001101001\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-idempotency-key", "<x-idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")

	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")
  .header("x-idempotency-key", "<x-idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

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

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.body = "-----011000010111000001101001\r\n-----011000010111000001101001--"

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

{
  "evidences": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "displayTitle": "<string>",
      "status": "Active",
      "provenance": "Merchant",
      "contentType": "<string>",
      "contentLength": 123,
      "payload": {},
      "documentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "version": 123,
      "validFrom": "2023-11-07T05:31:56Z",
      "changeNote": "<string>",
      "workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "labels": [
        "<string>"
      ],
      "exhibit": {
        "kind": "transaction",
        "source": "<string>",
        "reading": "<string>",
        "writtenBy": "ai",
        "updatedAt": "2023-11-07T05:31:56Z"
      }
    }
  ],
  "failedEvidences": [
    {
      "name": "<string>",
      "errorMessage": "<string>"
    }
  ],
  "classifications": [
    {
      "evidenceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "disputeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "status": "classifying",
      "contentSummary": "<string>",
      "documentType": "<string>",
      "provesStatement": "<string>",
      "keyFacts": [
        "<string>"
      ],
      "suggestedPlanMatches": [
        {
          "defenseReasonCode": "<string>",
          "slug": "<string>",
          "position": 123,
          "rationale": "<string>"
        }
      ],
      "providerResponseId": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ]
}

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

Upload evidence files

curl --request POST \
  --url https://api.staging.payrails.io/dispute/disputes/{disputeId}/evidences \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-idempotency-key: <x-idempotency-key>'

import requests

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

payload = "-----011000010111000001101001\r\n-----011000010111000001101001--"
headers = {
    "x-idempotency-key": "<x-idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "multipart/form-data"
}

response = requests.post(url, data=payload, headers=headers)

print(response.text)

const form = new FormData();

const options = {
  method: 'POST',
  headers: {'x-idempotency-key': '<x-idempotency-key>', Authorization: 'Bearer <token>'}
};

options.body = form;

fetch('https://api.staging.payrails.io/dispute/disputes/{disputeId}/evidences', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data",
    "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"

	payload := strings.NewReader("-----011000010111000001101001\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-idempotency-key", "<x-idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")

	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")
  .header("x-idempotency-key", "<x-idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

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

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.body = "-----011000010111000001101001\r\n-----011000010111000001101001--"

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

{
  "evidences": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "displayTitle": "<string>",
      "status": "Active",
      "provenance": "Merchant",
      "contentType": "<string>",
      "contentLength": 123,
      "payload": {},
      "documentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "version": 123,
      "validFrom": "2023-11-07T05:31:56Z",
      "changeNote": "<string>",
      "workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "labels": [
        "<string>"
      ],
      "exhibit": {
        "kind": "transaction",
        "source": "<string>",
        "reading": "<string>",
        "writtenBy": "ai",
        "updatedAt": "2023-11-07T05:31:56Z"
      }
    }
  ],
  "failedEvidences": [
    {
      "name": "<string>",
      "errorMessage": "<string>"
    }
  ],
  "classifications": [
    {
      "evidenceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "disputeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "status": "classifying",
      "contentSummary": "<string>",
      "documentType": "<string>",
      "provesStatement": "<string>",
      "keyFacts": [
        "<string>"
      ],
      "suggestedPlanMatches": [
        {
          "defenseReasonCode": "<string>",
          "slug": "<string>",
          "position": 123,
          "rationale": "<string>"
        }
      ],
      "providerResponseId": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ]
}

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

multipart/form-data

Evidence to upload for the dispute. Provide at least one of files[] (binary file uploads) or inlineContexts (inline JSON context); both may be combined in a single request. A request with neither is rejected.

files[]

object[]

List of files supporting the dispute defense.

inlineContexts

object[]

Inline merchant-context evidences supplied as a JSON array in a single inlineContexts form field. Each item is stored as JSON evidence with no uploaded file. Maximum 10 items.

Hide child attributes

inlineContexts.payload

object

required

Arbitrary JSON object stored verbatim as the evidence payload. Maximum 64 KB.

inlineContexts.title

string

Optional display title for the inline context. When omitted or blank it defaults to "inline-context".

Response

Dispute evidences uploaded.

evidences

object[]

required

Hide child attributes

evidences.id

string<uuid>

required

Unique identifier of the Dispute in Payrails.

evidences.createdAt

string<date-time>

required

Date and time when the Dispute was created in Payrails.

evidences.updatedAt

string<date-time>

required

Date and time when the Dispute was last updated in Payrails.

evidences.displayTitle

string

Display title of the evidence, usually the file name.

evidences.status

enum<string>

Status of the dispute evidence.

Available options:

Active,

Inactive,

Unknown

evidences.provenance

enum<string>

Provenance of the dispute evidence.

Available options:

Merchant,

Payrails,

Unknown

evidences.contentType

string

MIME type of the evidence content.

evidences.contentLength

integer

Size of the evidence content in bytes.

evidences.payload

object

Inline JSON payload for inline-context evidences. Present only for evidences created from inlineContexts; omitted for file-backed evidence.

evidences.documentId

string<uuid>

Evidence library document this evidence is a version of. Present only for evidence library versions.

evidences.version

integer<int64>

Version number within the evidence library document. Present only for evidence library versions.

evidences.validFrom

string<date-time>

When this evidence library version starts to apply. Present only for evidence library versions.

evidences.changeNote

string

What changed in this evidence library version. Present only for evidence library versions that have a change note.

evidences.workspaceId

string<uuid>

Workspace ID that the Dispute belongs to.

evidences.labels

string[]

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

evidences.exhibit

object

The dispute's exhibit metadata for this evidence. Present on the dispute's evidence list when the dispute has any for it.

Hide child attributes

evidences.exhibit.kind

enum<string>

The defense section the exhibit supports.

Available options:

transaction,

proof-of-delivery,

customer-communication,

merchant-policy,

cancellation,

cardholder-authentication,

product-as-described

evidences.exhibit.source

string

Where the exhibit came from: library, upload, payrails_payments, or push: followed by the pushed record type.

evidences.exhibit.reading

string

What the exhibit shows, as the issuer reads it next to the file.

Maximum string length: 2000

evidences.exhibit.writtenBy

enum<string>

Who wrote the current reading.

Available options:

ai,

user

evidences.exhibit.updatedAt

string<date-time>

When the reading last changed.

failedEvidences

object[]

required

Hide child attributes

failedEvidences.name

string

required

Name of the evidence file.

failedEvidences.errorMessage

string

required

Error due to which evidence uploading failed.

classifications

object[]

AI classifications for the uploaded evidence files. Present for each file where classification completed (status "classified" or "failed"). Omitted when the evidence agent feature is not enabled.

Hide child attributes

classifications.evidenceId

string<uuid>

required

Unique identifier of the evidence file that was classified.

classifications.disputeId

string<uuid>

required

Unique identifier of the dispute the evidence belongs to.

classifications.status

enum<string>

required

Classification status.

Available options:

classifying,

classified,

failed

classifications.contentSummary

string

AI-generated summary of the evidence file content.

classifications.documentType

string

AI-inferred document type (e.g. "receipt", "shipping_label").

classifications.provesStatement

string

AI-generated statement of what the evidence proves in the dispute context.

classifications.keyFacts

string[]

List of key facts extracted from the evidence.

classifications.suggestedPlanMatches

object[]

Representment plan slots this evidence is suggested to fill, ordered by confidence.

Hide child attributes

classifications.suggestedPlanMatches.defenseReasonCode

string

required

Defense reason code of the plan slot this evidence matches.

classifications.suggestedPlanMatches.slug

string

required

Slug identifier of the matching plan evidence slot.

classifications.suggestedPlanMatches.position

integer

required

Position of the matching slot within the defense type.

classifications.suggestedPlanMatches.rationale

string

required

AI-generated explanation for why this evidence matches the slot.

classifications.providerResponseId

string

Identifier of the LLM provider response that produced this classification.

classifications.createdAt

string<date-time>

Date and time when the classification was created.

classifications.updatedAt

string<date-time>

Date and time when the classification was last updated.

Payrails API Reference

Get started

Workflow

Payment

Provider

Merchant

Vault

Analytics

Reporting

Reconciliation

Dispute

Upload evidence files

Authorizations

Headers

Path Parameters

Body

Response