Add a version to an evidence library document

curl --request POST \
  --url https://api.eu.staging.payrails.io/dispute/disputes/evidence-documents/{documentId}/versions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --form 'changeNote=Missing items: report within 14 days of delivery' \
  --form 'file=@example-file;type=application/pdf'

import requests

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

files = { "file": ("example-file", open("example-file", "rb"), "application/pdf") }
payload = { "changeNote": "Missing items: report within 14 days of delivery" }
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('changeNote', 'Missing items: report within 14 days of delivery');
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/{documentId}/versions', 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/{documentId}/versions",
  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=\"changeNote\"\r\n\r\nMissing items: report within 14 days of delivery\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/{documentId}/versions"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"changeNote\"\r\n\r\nMissing items: report within 14 days of delivery\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/{documentId}/versions")
  .header("x-idempotency-key", "<x-idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"changeNote\"\r\n\r\nMissing items: report within 14 days of delivery\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/{documentId}/versions")

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=\"changeNote\"\r\n\r\nMissing items: report within 14 days of delivery\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

{documentId}

versions

Add a version to an evidence library document

curl --request POST \
  --url https://api.eu.staging.payrails.io/dispute/disputes/evidence-documents/{documentId}/versions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --form 'changeNote=Missing items: report within 14 days of delivery' \
  --form 'file=@example-file;type=application/pdf'

import requests

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

files = { "file": ("example-file", open("example-file", "rb"), "application/pdf") }
payload = { "changeNote": "Missing items: report within 14 days of delivery" }
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('changeNote', 'Missing items: report within 14 days of delivery');
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/{documentId}/versions', 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/{documentId}/versions",
  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=\"changeNote\"\r\n\r\nMissing items: report within 14 days of delivery\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/{documentId}/versions"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"changeNote\"\r\n\r\nMissing items: report within 14 days of delivery\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/{documentId}/versions")
  .header("x-idempotency-key", "<x-idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"changeNote\"\r\n\r\nMissing items: report within 14 days of delivery\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/{documentId}/versions")

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=\"changeNote\"\r\n\r\nMissing items: report within 14 days of delivery\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"
    }
  ]
}

The new version gets the next version number and becomes the latest version. It takes the title, kind and workspace from the document. Earlier versions stay, because disputes that already use them keep them.

validFrom is deprecated and ignored.
Returns 409 when the document is archived, or when another version is added at the same time. In the second case, send the request again with a new idempotency key.
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:update

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

documentId

string<uuid>

required

Identifier of the resource in Payrails.

Body

multipart/form-data

changeNote

string

required

What changed in this version.

Maximum string length: 2000

Example:

"Missing items: report within 14 days of delivery"

file

required

The new version of the document.

validFrom

string<date-time>

deprecated

Ignored. New disputes always get the latest version.

Response

Version added. Returns the document with all its versions.

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 a version to an evidence library document

Authorizations

Scopes

Headers

Path Parameters

Body

Response