Document API

Create, retrieve, and delete document files. Documents (for example, scanned receipts or shipment delivery slips) are used to help resolve disputes. Supported file types include PNG, JPG, and PDF.

Attributes

Name	Type	Description
object	string	The string `document`.
id	string	The document identifier matching `/docu(_test)?_[0-9a-z]+/`.
livemode	boolean	Whether this is a live (`true`) or test (`false`) document.
location	string	API path to retrieve the current `document` object.
created	string	UTC datetime of document creation in ISO 8601 format (`YYYY-MM-DDThh:mm:ssZ`).
deleted	boolean	Whether document is deleted.
download_uri	string	URI of document for download.
filename	string	Original filename of uploaded document.
kind	string	Document kind

Example

JSON Response

{
  "object": "document",
  "livemode": false,
  "id": "docu_test_no1t4tnemucod0e51mo",
  "filename": "this_is_fine.png",
  "location": "/disputes/dspt_test_no1t4tnemucod0e51mo/documents/docu_test_no1t4tnemucod0e51mo",
  "kind": "details_of_purchase",
  "created": "2019-12-31T12:59:59Z"
}

Upload a document

- POST https://api.omise.co/disputes/{id}/documents

This endpoint allows you to send an HTTP multipart upload to add a dispute evidence document. Note that documents may only be added to an open dispute and document file size may not exceed 10MB. Returns the newly created document.

Request Parameters

Name	Type	Description
file	string	(optional) File for upload as document. Valid formats include PNG, JPG, and PDF.
kind	string	(optional) Document kind. When providing evidence for a dispute, kind must be one of `cardholder_details`, `details_of_purchase`, `proof_of_receipt`, `proof_of_acceptance`.

Example

Create a document

curl
ruby

curl https://api.omise.co/disputes/dspt_test_5g5ih3pybo7v4wwrbjw/documents \
  -u $OMISE_SECRET_KEY: \
  -F kind=details_of_purchase \
  -F file=@evidence.png

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

dispute = Omise::Dispute.retrieve("dspt_test_4zgf15h89w8t775kcm8")

File.open("some/path.doc", "r") do |file|
  dispute.documents.upload(file)
end

Destroy a document

- DELETE https://api.omise.co/disputes/{id}/documents/{document_id}

Destroys the document matching :document_id belonging to dispute matching :id. Dispute status must be open.

Example

Destroy a document

curl
ruby

curl https://api.omise.co/disputes/dspt_test_5g5ih3pybo7v4wwrbjw/documents/docu_test_5g5iiejzhyhbfyj6kzs \
  -X DELETE \
  -u $OMISE_SECRET_KEY:

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

dispute  = Omise::Dispute.retrieve("dspt_test_4zgf15h89w8t775kcm8")
document = dispute.documents.retrieve("docu_test_53f7n2a4rzvii1p8tn7")

document.destroy

List documents

- GET https://api.omise.co/disputes/{id}/documents

Returns a list of documents belonging to the dispute.

Request Parameters

Name	Type	Description
from	string	(optional, default: `1970-01-01T00:00:00Z`) Earliest UTC datetime for returned records in ISO 8601 format (`YYYY-MM-DDThh:mm:ssZ`).
limit	integer	(optional, default: `20`) Number of records returned.
offset	integer	(optional, default: `0`) Offset of the first record returned (i.e. how many records to skip from the beginning).
order	string	(optional, default: `chronological`, one of: `chronological`, `reverse_chronological`) Order of records returned.
to	string	(optional) Latest UTC datetime for returned records in ISO 8601 format (`YYYY-MM-DDThh:mm:ssZ`).

Example

List all dispute documents

curl
ruby

curl https://api.omise.co/disputes/dspt_test_5g5ih3pybo7v4wwrbjw/documents \
  -u $OMISE_SECRET_KEY:

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

dispute   = Omise::Dispute.retrieve("dspt_test_4zgf15h89w8t775kcm8")
documents = dispute.documents

Retrieve a document

- GET https://api.omise.co/disputes/{id}/documents/{document_id}

Returns the document matching :document_id.

Example

Retrieve a document

curl
ruby

curl https://api.omise.co/disputes/dspt_test_5g5ih3pybo7v4wwrbjw/documents/docu_test_5g5iiejzhyhbfyj6kzs \
  -u $OMISE_SECRET_KEY:

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

dispute  = Omise::Dispute.retrieve("dspt_test_4zgf15h89w8t775kcm8")
document = dispute.documents.retrieve("docu_test_53f7n2a4rzvii1p8tn7")