Add an evidence library document

curl --request POST \
  --url https://api.eu.staging.payrails.io/dispute/disputes/evidence-documents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --form 'title=Terms & conditions' \
  --form 'file=@example-file;type=application/pdf'

import requests

url = "https://api.eu.staging.payrails.io/dispute/disputes/evidence-documents"

files = { "file": ("example-file", open("example-file", "rb"), "application/pdf") }
payload = { "title": "Terms & conditions" }
headers = {
    "x-idempotency-key": "<x-idempotency-key>",
    "Authorization": "Bearer <token>"
}

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

print(response.text)

const form = new FormData();
form.append('title', 'Terms & conditions');
form.append('file', '<string>');

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

options.body = form;

fetch('https://api.eu.staging.payrails.io/dispute/disputes/evidence-documents', 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.eu.staging.payrails.io/dispute/disputes/evidence-documents",
  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\nContent-Disposition: form-data; name=\"title\"\r\n\r\nTerms & conditions\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/pdf\r\n\r\n<string>\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.eu.staging.payrails.io/dispute/disputes/evidence-documents"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nTerms & conditions\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/pdf\r\n\r\n<string>\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.eu.staging.payrails.io/dispute/disputes/evidence-documents")
  .header("x-idempotency-key", "<x-idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nTerms & conditions\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/pdf\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.eu.staging.payrails.io/dispute/disputes/evidence-documents")

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\nContent-Disposition: form-data; name=\"title\"\r\n\r\nTerms & conditions\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/pdf\r\n\r\n<string>\r\n-----011000010111000001101001--"

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

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "kind": "terms",
  "title": "<string>",
  "attachedTo": "matchingReasonCodes",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "usedInCount": 123,
  "workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "reasonCodes": [
    "10.4"
  ],
  "reasonCodesSetBy": "ai",
  "archivedAt": "2023-11-07T05:31:56Z",
  "currentVersion": {
    "evidenceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "version": 2,
    "validFrom": "2023-11-07T05:31:56Z",
    "contentType": "application/pdf",
    "contentLength": 123,
    "createdAt": "2023-11-07T05:31:56Z",
    "changeNote": "<string>",
    "summary": "<string>",
    "archivedAt": "2023-11-07T05:31:56Z",
    "links": {
      "download": "<string>"
    }
  },
  "lastUsedAt": "2023-11-07T05:31:56Z",
  "versions": [
    {
      "evidenceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "version": 2,
      "validFrom": "2023-11-07T05:31:56Z",
      "contentType": "application/pdf",
      "contentLength": 123,
      "createdAt": "2023-11-07T05:31:56Z",
      "changeNote": "<string>",
      "summary": "<string>",
      "archivedAt": "2023-11-07T05:31:56Z",
      "links": {
        "download": "<string>"
      }
    }
  ],
  "usages": [
    {
      "disputeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "evidenceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "version": 123,
      "linkedAt": "2023-11-07T05:31:56Z",
      "providerReference": "<string>",
      "merchantReference": "<string>",
      "reasonCode": "<string>",
      "schemeReasonCode": "<string>",
      "stage": "Created",
      "chargebackStatus": "Incoming",
      "defenseStatus": "NotDefendable"
    }
  ],
  "history": [
    {
      "event": "created",
      "actor": {
        "type": "user",
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "email": "jsmith@example.com"
      },
      "at": "2023-11-07T05:31:56Z",
      "version": 2,
      "note": "<string>",
      "previousReasonCodes": [
        "10.4"
      ],
      "reasonCodes": [
        "10.4"
      ]
    }
  ]
}

{
  "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": "07a1d642-dbf5-47d3-8563-700514b38e46",
      "code": "request.header.missing",
      "detail": "The request is missing a required header",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestheadermissing"
    }
  ]
}

{
  "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.eu.staging.payrails.io

dispute

disputes

evidence-documents

Add an evidence library document

curl --request POST \
  --url https://api.eu.staging.payrails.io/dispute/disputes/evidence-documents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --form 'title=Terms & conditions' \
  --form 'file=@example-file;type=application/pdf'

import requests

url = "https://api.eu.staging.payrails.io/dispute/disputes/evidence-documents"

files = { "file": ("example-file", open("example-file", "rb"), "application/pdf") }
payload = { "title": "Terms & conditions" }
headers = {
    "x-idempotency-key": "<x-idempotency-key>",
    "Authorization": "Bearer <token>"
}

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

print(response.text)

const form = new FormData();
form.append('title', 'Terms & conditions');
form.append('file', '<string>');

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

options.body = form;

fetch('https://api.eu.staging.payrails.io/dispute/disputes/evidence-documents', 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.eu.staging.payrails.io/dispute/disputes/evidence-documents",
  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\nContent-Disposition: form-data; name=\"title\"\r\n\r\nTerms & conditions\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/pdf\r\n\r\n<string>\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.eu.staging.payrails.io/dispute/disputes/evidence-documents"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nTerms & conditions\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/pdf\r\n\r\n<string>\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.eu.staging.payrails.io/dispute/disputes/evidence-documents")
  .header("x-idempotency-key", "<x-idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nTerms & conditions\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/pdf\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.eu.staging.payrails.io/dispute/disputes/evidence-documents")

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\nContent-Disposition: form-data; name=\"title\"\r\n\r\nTerms & conditions\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/pdf\r\n\r\n<string>\r\n-----011000010111000001101001--"

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

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "kind": "terms",
  "title": "<string>",
  "attachedTo": "matchingReasonCodes",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "usedInCount": 123,
  "workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "reasonCodes": [
    "10.4"
  ],
  "reasonCodesSetBy": "ai",
  "archivedAt": "2023-11-07T05:31:56Z",
  "currentVersion": {
    "evidenceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "version": 2,
    "validFrom": "2023-11-07T05:31:56Z",
    "contentType": "application/pdf",
    "contentLength": 123,
    "createdAt": "2023-11-07T05:31:56Z",
    "changeNote": "<string>",
    "summary": "<string>",
    "archivedAt": "2023-11-07T05:31:56Z",
    "links": {
      "download": "<string>"
    }
  },
  "lastUsedAt": "2023-11-07T05:31:56Z",
  "versions": [
    {
      "evidenceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "version": 2,
      "validFrom": "2023-11-07T05:31:56Z",
      "contentType": "application/pdf",
      "contentLength": 123,
      "createdAt": "2023-11-07T05:31:56Z",
      "changeNote": "<string>",
      "summary": "<string>",
      "archivedAt": "2023-11-07T05:31:56Z",
      "links": {
        "download": "<string>"
      }
    }
  ],
  "usages": [
    {
      "disputeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "evidenceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "version": 123,
      "linkedAt": "2023-11-07T05:31:56Z",
      "providerReference": "<string>",
      "merchantReference": "<string>",
      "reasonCode": "<string>",
      "schemeReasonCode": "<string>",
      "stage": "Created",
      "chargebackStatus": "Incoming",
      "defenseStatus": "NotDefendable"
    }
  ],
  "history": [
    {
      "event": "created",
      "actor": {
        "type": "user",
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "email": "jsmith@example.com"
      },
      "at": "2023-11-07T05:31:56Z",
      "version": 2,
      "note": "<string>",
      "previousReasonCodes": [
        "10.4"
      ],
      "reasonCodes": [
        "10.4"
      ]
    }
  ]
}

{
  "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": "07a1d642-dbf5-47d3-8563-700514b38e46",
      "code": "request.header.missing",
      "detail": "The request is missing a required header",
      "docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestheadermissing"
    }
  ]
}

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

Payrails attaches a library document to a new dispute when the dispute’s card network reason code is one of the document’s reasonCodes. Each dispute gets the document’s latest version. A dispute without a Visa or Mastercard reason code gets no library document automatically, and you can still attach any document to any dispute. Payrails AI reads the file and suggests the reason codes a few seconds after you add the document. Until then, reasonCodes is null and Payrails attaches the document to no dispute. You can change the reason codes with Update an evidence library document. The kind is the document type: terms, policy or productDescription. It decides where the document appears in a dispute’s defense: terms and policies in the Merchant policy section, product descriptions in the Product as described section.

validFrom is deprecated and ignored.
Without workspaceId the document applies to every workspace. Callers limited to some workspaces must set workspaceId to one of theirs; they get 403 for a merchant-wide document.
Each document type can have a title only once. Returns 409 when a document of the same type already has the title, also when that document is archived or in another workspace. Payrails ignores upper and lower case and extra spaces when it compares titles.
The same title is allowed for a different document type.
Payrails removes extra spaces from the title before it saves it.
The title must not end with a version, such as Refund policy v2 or Refund policy version 2. Returns 422 for such a title. To update the file, add a new version instead.
Returns 404 when the evidenceLibraryEnabled feature flag is off.

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.

Scopes

disputeevidences:create

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.

Body

multipart/form-data

title

string

required

The document title. It must not end with a version, such as v2.

Maximum string length: 200

Example:

"Terms & conditions"

kind

enum<string>

required

Kind of library document. terms and policy documents are attached to every dispute; productDescription documents to not-as-described disputes.

Available options:

terms,

policy,

productDescription

file

required

The document.

workspaceId

string<uuid>

Workspace the document belongs to. Omit to apply it to every workspace.

validFrom

string<date-time>

deprecated

Ignored. New disputes always get the latest version.

Response

Document and its version 1 created.

string<uuid>

required

kind

enum<string>

required

Kind of library document. terms and policy documents are attached to every dispute; productDescription documents to not-as-described disputes.

Available options:

terms,

policy,

productDescription

title

string

required

attachedTo

enum<string>

required

deprecated

Always matchingReasonCodes. Payrails attaches a document to a new dispute when the dispute's card network reason code is one of the document's reasonCodes. allDisputes is no longer returned.

Available options:

matchingReasonCodes,

allDisputes

createdAt

string<date-time>

required

updatedAt

string<date-time>

required

usedInCount

integer

required

Number of disputes that use any version of the document. If your credentials can access only some workspaces, only disputes in those workspaces count.

workspaceId

string<uuid>

Absent when the document applies to every workspace.

reasonCodes

enum<string>[] | null

The card network reason codes this document helps defend. Payrails AI suggests them when you add the document or a new version, and you can change them. null until Payrails AI or a person sets them. An empty list means that no reason code applies.

A card network reason code. Visa: 10.4 other fraud, card-absent; 13.1 merchandise or services not received; 13.2 cancelled recurring transaction; 13.3 not as described or defective; 13.6 credit not processed; 13.7 cancelled merchandise or services. Mastercard: 4837 no cardholder authorization; 4853 cardholder dispute; 4855 goods or services not provided.

Available options:

10.4,

13.1,

13.2,

13.3,

13.6,

13.7,

4837,

4853,

4855

reasonCodesSetBy

enum<string> | null

Who set reasonCodes. ai: Payrails AI. user: a person on your team in the Payrails portal. client: your system through the API. null until the reason codes are set. Payrails AI never replaces reason codes that a person or your system set.

Available options:

ai,

user,

client,

null

archivedAt

string<date-time>

currentVersion

object

The latest version that is not archived. New disputes get this version. Absent when every version is archived.

Hide child attributes

currentVersion.evidenceId

string<uuid>

required

ID of the stored file of this version.

currentVersion.version

integer<int64>

required

Required range: x >= 1

currentVersion.validFrom

string<date-time>

required

deprecated

Deprecated. Payrails ignores it.

currentVersion.contentType

string

required

Example:

"application/pdf"

currentVersion.contentLength

integer

required

currentVersion.createdAt

string<date-time>

required

currentVersion.changeNote

string

currentVersion.summary

string | null

A short summary of this version, written by Payrails AI. null until Payrails AI writes it, or when Payrails AI is off for your account.

currentVersion.archivedAt

string<date-time>

Set when the version is archived. Payrails never attaches an archived version.

currentVersion.links

object

Returned only by Get document (on each item of versions) and Get version.

Hide child attributes

currentVersion.links.download

Temporary link to the version's file. When it expires, get the document or the version again for a new link.

lastUsedAt

string<date-time>

When a dispute last started to use a version of the document. If your credentials can access only some workspaces, only disputes in those workspaces count.

versions

object[]

All versions of the document, oldest first. Returned by Add document (version 1 only), Get document, Add version, Archive document and Archive version. List documents does not return it.

Hide child attributes

versions.evidenceId

string<uuid>

required

ID of the stored file of this version.

versions.version

integer<int64>

required

Required range: x >= 1

versions.validFrom

string<date-time>

required

deprecated

Deprecated. Payrails ignores it.

versions.contentType

string

required

Example:

"application/pdf"

versions.contentLength

integer

required

versions.createdAt

string<date-time>

required

versions.changeNote

string

versions.summary

string | null

A short summary of this version, written by Payrails AI. null until Payrails AI writes it, or when Payrails AI is off for your account.

versions.archivedAt

string<date-time>

Set when the version is archived. Payrails never attaches an archived version.

versions.links

object

Returned only by Get document (on each item of versions) and Get version.

Hide child attributes

versions.links.download

Temporary link to the version's file. When it expires, get the document or the version again for a new link.

usages

object[]

The 100 disputes that most recently started to use the document, newest first, with the version each one uses. A dispute that uses two versions appears twice. usedInCount is the total number of disputes. Returned by Get document, Add version, Archive document and Archive version. To see every dispute, use List the disputes that use an evidence library document.

Maximum array length: 100

Hide child attributes

usages.disputeId

string<uuid>

required

usages.evidenceId

string<uuid>

required

ID of the stored file of the version that the dispute uses.

usages.version

integer<int64>

required

usages.linkedAt

string<date-time>

required

usages.providerReference

string

The payment provider's reference of the dispute.

usages.merchantReference

string

usages.reasonCode

string

usages.schemeReasonCode

string

usages.stage

enum<string>

Stage of the dispute.

Available options:

Created,

FraudReport,

Retrieval,

Chargeback,

PreArbitration,

Arbitration,

Unknown

usages.chargebackStatus

enum<string>

Status of the chargeback.

Available options:

Incoming,

Executed,

Reversed,

SecondChargeback,

IssuerReponseTimeframeExpired,

ArbitrationReversed

usages.defenseStatus

enum<string>

Status of the defense.

Available options:

NotDefendable,

Undefended,

ReadyToSubmit,

Submitted,

Failed,

UnderReview,

Won,

Lost,

Accepted,

Resolved,

Unknown

history

object[]

The changes to the document, newest first, with who made each change and when. Returned by Get document only. For documents changed before this history existed, it shows only what their stored dates show. An archive and restore that happened before then does not appear.

Hide child attributes

history.event

enum<string>

required

What changed. created: the document was added with version 1. versionAdded: a new version was added. archived: the document was archived. versionArchived: one version was archived. When it was the last version that was not archived, the document was archived with it. restored: the document, or one archived version, was restored. renamed: the title changed; note holds the previous title. reasonCodesChanged: the reason codes changed; previousReasonCodes and reasonCodes hold the codes before and after.

Available options:

created,

versionAdded,

archived,

versionArchived,

restored,

renamed,

reasonCodesChanged

history.actor

object | null

required

Who made the change. It is null for a change made before Payrails recorded who made each change.

Hide child attributes

history.actor.type

enum<string>

required

user: a person on your team made the change in the Payrails portal. client: your software made the change through the API with your API credentials. system: Payrails made the change, or Payrails could not tell who made it. ai: Payrails AI made the change.

Available options:

user,

client,

system,

ai

history.actor.id

string<uuid>

The ID of the user. Only for a user.

history.actor.email

string<email>

The email of the user. Only for a user. It is absent when Payrails cannot find the user.

history.at

string<date-time>

required

When the change was made.

history.version

integer<int64>

The version that was added, archived or restored. A restore has a version only when it restored that version.

Required range: x >= 1

history.note

string

On versionAdded, what changed in the new version. On renamed, the previous title.

history.previousReasonCodes

enum<string>[]

On reasonCodesChanged, the reason codes before the change. Absent when the document had no reason codes yet.

Available options:

10.4,

13.1,

13.2,

13.3,

13.6,

13.7,

4837,

4853,

4855

history.reasonCodes

enum<string>[]

On reasonCodesChanged, the reason codes after the change. An empty list means that no reason code applies.

Available options:

10.4,

13.1,

13.2,

13.3,

13.6,

13.7,

4837,

4853,

4855

Payrails API Reference

Get started

Workflow

Payment

Provider

Merchant

Vault

Analytics

Reporting

Reconciliation

Dispute

Add an evidence library document

Authorizations

Scopes

Headers

Body

Response