GuidesAPI Reference
Guides
Guides
Guides

Document validation and review

Some transactions require a supporting document before they can be completed. When a document is attached, Caliza validates it against the transaction details. This page explains what happens during that validation, what it means when a transaction is held for document review, and how to resolve it.

Whether a document is required depends on your integrator configuration and the nature of the transaction. If you are not sure whether document validation applies to your account, contact your Caliza representative.

How validation works

A supporting document is validated whenever it is attached to a transaction — whether at creation time via POST /v1/transactions/:withDocuments or afterwards via POST /v1/transactions/{id}/documents. Validation runs asynchronously after the upload is accepted.

Validation has one of two outcomes:

  • Accepted — the document matches the transaction. The transaction proceeds normally.
  • Not accepted — the document could not be read, or its contents do not match the transaction. The transaction is held for document review until an acceptable document is provided.

When a transaction is held for review

A transaction that is held for document review is paused: funds are not moved while it waits. This happens when document validation is required and either no document was provided, or the document that was provided was not accepted.

You can detect this state by retrieving the transaction and inspecting its status:

curl --location 'https://api.sandbox.caliza.com/core-api/v1/transactions/{{TRANSACTION_ID}}' \
--header 'Authorization: Bearer YOUR_TOKEN'

A held transaction remains paused until it is resolved by uploading an acceptable document.

Resolve a held transaction

To resolve a held transaction, upload a corrected supporting document to the existing transaction:

curl --location 'https://api.sandbox.caliza.com/core-api/v1/transactions/{{TRANSACTION_ID}}/documents' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--form 'file=@"./corrected-invoice.pdf"'

The newly uploaded document is validated the same way. If it is accepted, the hold is released automatically and the transaction resumes from where it was paused — you do not need to recreate it. If it is still not accepted, the transaction stays held and you can upload another document.

📘

Uploading a new document does not undo a previous acceptance

Each upload is validated on its own. A transaction that has already passed validation and resumed is not sent back for review by a later upload.

See Attach supporting documents for the full request and response details of the upload endpoints.

Related Articles