Rename an evidence library document

curl --request PATCH \
  --url https://api.staging.payrails.io/dispute/disputes/evidence-documents/{documentId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "title": "Terms of service"
}
'

import requests

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

payload = { "title": "Terms of service" }
headers = {
    "x-idempotency-key": "<x-idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {
    'x-idempotency-key': '<x-idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({title: 'Terms of service'})
};

fetch('https://api.staging.payrails.io/dispute/disputes/evidence-documents/{documentId}', 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}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'title' => 'Terms of service'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-idempotency-key: <x-idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

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

	payload := strings.NewReader("{\n  \"title\": \"Terms of service\"\n}")

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

	req.Header.Add("x-idempotency-key", "<x-idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.staging.payrails.io/dispute/disputes/evidence-documents/{documentId}")
  .header("x-idempotency-key", "<x-idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"title\": \"Terms of service\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["x-idempotency-key"] = '<x-idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"title\": \"Terms of service\"\n}"

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

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

PATCH

https://api.staging.payrails.io

dispute

disputes

evidence-documents

{documentId}

Rename an evidence library document

curl --request PATCH \
  --url https://api.staging.payrails.io/dispute/disputes/evidence-documents/{documentId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "title": "Terms of service"
}
'

import requests

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

payload = { "title": "Terms of service" }
headers = {
    "x-idempotency-key": "<x-idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {
    'x-idempotency-key': '<x-idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({title: 'Terms of service'})
};

fetch('https://api.staging.payrails.io/dispute/disputes/evidence-documents/{documentId}', 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}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'title' => 'Terms of service'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-idempotency-key: <x-idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

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

	payload := strings.NewReader("{\n  \"title\": \"Terms of service\"\n}")

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

	req.Header.Add("x-idempotency-key", "<x-idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.staging.payrails.io/dispute/disputes/evidence-documents/{documentId}")
  .header("x-idempotency-key", "<x-idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"title\": \"Terms of service\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["x-idempotency-key"] = '<x-idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"title\": \"Terms of service\"\n}"

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

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

A rename changes only the title. The versions and the disputes that use them stay the same.

The title rules are the same as when you add a document. Each title can be used only once per document type. Returns 409 when a document of the same type already has the title, including when that document is archived or belongs to another workspace.
Payrails ignores upper and lower case and extra spaces when it compares titles. It removes spaces at the start and end of the title and replaces repeated spaces with one space.
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.
Renaming a document to its current title returns the document unchanged.
You can rename an archived document. It stays archived.
Returns 403 when the document applies to all workspaces and your credentials give access to only some of them.
Returns 404 when the document does not exist, or 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

application/json

title

string

required

The new title. Payrails removes spaces at the start and end and replaces repeated spaces with one space. It must not end with a version, such as v2.

Required string length: 1 - 200

Example:

"Terms of service"

Response

The renamed document.

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 allDisputes. Payrails attaches every document to every new dispute.

Available options:

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.

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.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.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 was restored. renamed: the title changed; note holds the previous title.

Available options:

created,

versionAdded,

archived,

versionArchived,

restored,

renamed

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.

Available options:

user,

client,

system

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 also restored that version.

Required range: x >= 1

history.note

string

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

Payrails API Reference

Get started

Workflow

Payment

Provider

Merchant

Vault

Analytics

Reporting

Reconciliation

Dispute

Rename an evidence library document

Authorizations

Headers

Path Parameters

Body

Response