Restore one archived version of an evidence library document

curl --request POST \
  --url https://api.staging.payrails.io/dispute/disputes/evidence-documents/{documentId}/versions/{version}/restore \
  --header 'Authorization: Bearer <token>' \
  --header 'x-idempotency-key: <x-idempotency-key>'

import requests

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

headers = {
    "x-idempotency-key": "<x-idempotency-key>",
    "Authorization": "Bearer <token>"
}

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

print(response.text)

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

fetch('https://api.staging.payrails.io/dispute/disputes/evidence-documents/{documentId}/versions/{version}/restore', 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/{version}/restore",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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"
	"net/http"
	"io"
)

func main() {

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

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

	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/{version}/restore")
  .header("x-idempotency-key", "<x-idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

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

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>'

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": "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

{version}

restore

Restore one archived version of an evidence library document

curl --request POST \
  --url https://api.staging.payrails.io/dispute/disputes/evidence-documents/{documentId}/versions/{version}/restore \
  --header 'Authorization: Bearer <token>' \
  --header 'x-idempotency-key: <x-idempotency-key>'

import requests

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

headers = {
    "x-idempotency-key": "<x-idempotency-key>",
    "Authorization": "Bearer <token>"
}

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

print(response.text)

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

fetch('https://api.staging.payrails.io/dispute/disputes/evidence-documents/{documentId}/versions/{version}/restore', 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/{version}/restore",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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"
	"net/http"
	"io"
)

func main() {

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

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

	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/{version}/restore")
  .header("x-idempotency-key", "<x-idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

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

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>'

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

Restoring a version makes it active again. Other archived versions stay archived. Payrails attaches the newest version that is not archived to new disputes. If you restore an older version while a newer version is active, currentVersion stays the newer version, and new disputes get the newer version. If the document is archived, Payrails restores it too, so that it attaches to new disputes again.

Restoring a version that is not archived returns the document unchanged.
Returns 404 when the document or the version 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.

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.

version

integer<int64>

required

Number of the version to restore.

Required range: x >= 1

Response

The document with the restored version.

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

Restore one archived version of an evidence library document

Authorizations

Scopes

Headers

Path Parameters

Response