Add a version to an evidence library document

curl --request POST \
  --url https://api.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.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.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.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.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.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.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": "allDisputes",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "usedInCount": 123,
  "workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "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>"
  },
  "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>"
    }
  ],
  "usages": [
    {
      "disputeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "evidenceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "version": 123,
      "linkedAt": "2023-11-07T05:31:56Z",
      "reasonCode": "<string>",
      "schemeReasonCode": "<string>",
      "stage": "Created",
      "chargebackStatus": "Incoming",
      "defenseStatus": "NotDefendable"
    }
  ]
}

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

dispute

disputes

evidence-documents

{documentId}

versions

Add a version to an evidence library document

curl --request POST \
  --url https://api.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.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.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.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.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.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.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": "allDisputes",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "usedInCount": 123,
  "workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "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>"
  },
  "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>"
    }
  ],
  "usages": [
    {
      "disputeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "evidenceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "version": 123,
      "linkedAt": "2023-11-07T05:31:56Z",
      "reasonCode": "<string>",
      "schemeReasonCode": "<string>",
      "stage": "Created",
      "chargebackStatus": "Incoming",
      "defenseStatus": "NotDefendable"
    }
  ]
}

{
  "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. Earlier versions stay, because disputes for purchases made before validFrom still use them.

validFrom may be in the past, or in the future for a scheduled version that becomes current on that date.
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.

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>

When this version starts to apply. Defaults to now; may be in the past or the future. Each dispute uses the version valid at its purchase time. A version dated before the current version never becomes current. A version dated after the current version but before a scheduled future one becomes current now.

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

Which new disputes Payrails attaches the document to, derived from its kind.

Available options:

allDisputes,

notAsDescribedDisputes

createdAt

string<date-time>

required

updatedAt

string<date-time>

required

usedInCount

integer

required

Number of disputes that use any version of the document. For a caller limited to some workspaces, only disputes in those workspaces count.

workspaceId

string<uuid>

Absent when the document applies to every workspace.

archivedAt

string<date-time>

currentVersion

object

The version valid now. Absent when every version starts in the future.

Hide child attributes

currentVersion.evidenceId

string<uuid>

required

Evidence that holds this version's file.

currentVersion.version

integer<int64>

required

Required range: x >= 1

currentVersion.validFrom

string<date-time>

required

Disputes for purchases made on or after this time use this version, until a later version starts.

currentVersion.contentType

string

required

Example:

"application/pdf"

currentVersion.contentLength

integer

required

currentVersion.createdAt

string<date-time>

required

currentVersion.changeNote

string

lastUsedAt

string<date-time>

When a dispute last started to use a version of the document. For a caller limited to some workspaces, only disputes in those workspaces count.

versions

object[]

All versions, lowest first. Returned by create (version 1 only), get, add version and archive; not returned by list.

Hide child attributes

versions.evidenceId

string<uuid>

required

Evidence that holds this version's file.

versions.version

integer<int64>

required

Required range: x >= 1

versions.validFrom

string<date-time>

required

Disputes for purchases made on or after this time use this version, until a later version starts.

versions.contentType

string

required

Example:

"application/pdf"

versions.contentLength

integer

required

versions.createdAt

string<date-time>

required

versions.changeNote

string

usages

object[]

The latest 100 dispute links to a version of the document, newest first, one entry per link; usedInCount is the total. Returned by get, add version and archive; not returned by list.

Maximum array length: 100

Hide child attributes

usages.disputeId

string<uuid>

required

usages.evidenceId

string<uuid>

required

The version's evidence linked to the dispute.

usages.version

integer<int64>

required

usages.linkedAt

string<date-time>

required

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

Payrails API Reference

Get started

Workflow

Payment

Provider

Merchant

Vault

Analytics

Reporting

Reconciliation

Dispute

Add a version to an evidence library document

Authorizations

Headers

Path Parameters

Body

Response