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.
Transaction statuses
Two transaction statuses are specific to document validation. You will see them on GET /v1/transactions/{id}:
| Status | Meaning | What to do |
|---|---|---|
AWAITING_DOC_VALIDATION | The transaction is paused while a document is validated — or, if your account allows submitting without a document, while Caliza waits for you to upload one. | Nothing if a document was already uploaded; otherwise upload the document. |
HELD_FOR_DOC_REVIEW | The document was not accepted, or the window to upload one has passed. The transaction stays paused until an acceptable document is uploaded. | Upload a (corrected) document. |
Funds are not moved while a transaction is in either state.
When a transaction enters HELD_FOR_DOC_REVIEW, a TRANSACTION_UNDER_REVIEW webhook is sent to your callback URL. No webhook is sent when a transaction enters AWAITING_DOC_VALIDATION — if you submit without a document, you are expected to already know one is owed. Once the hold is resolved and the transaction completes, you receive the usual TRANSACTION_COMPLETED webhook.
Submitting without a document
By default, a transaction that requires a supporting document must include one at creation, and a document-less submission is rejected with HTTP 400.
Your account can instead be configured for deferred upload: submit the transaction without a document, then upload it afterwards. In that mode:
POST /v1/transactionssucceeds without a document. The transaction proceeds until it reaches the point where the document is required, then pauses with statusAWAITING_DOC_VALIDATION.- Upload the document with
POST /v1/transactions/{id}/documentsat any time. If it passes validation, the transaction resumes automatically. - If no document arrives within your account's upload window (1 hour by default), the transaction moves to
HELD_FOR_DOC_REVIEWand aTRANSACTION_UNDER_REVIEWwebhook is sent. This is a reminder, not a dead end — uploading an acceptable document still releases the transaction automatically.
Contact your Caliza representative to enable deferred upload or adjust the upload window for your account.
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 acceptanceEach 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
Updated 12 days ago