Skip to content

CHEQUE API · INTEGRATION GUIDE

Cheque API integration for your application.

Submit a cheque image, receive structured JSON and use the fields in your workflow. Start with the upload example, then connect result mapping, retries and review to your application.

  • Multipart image upload
  • Structured JSON response
  • Access provisioned for your deployment
IMAGE IN. RESULT OUT.TRANSPORT OUTLINE
POST/api/v1/ocr/cheque/upload
multipart/form-datafile: sample-cheque.jpg
Provisioned service URL + credentials
MAP THE DOCUMENTED RESPONSE
Extracted fields
Missing values & disagreements
Source image for review

Agree the versioned contract for your deployment before building.

01 / GET API ACCESS

Set up cheque API authentication and access.

Integration detailWhat to confirm
Base URL, credentials and network accessUse the provisioned service URL. Keep service credentials on your server.
API version and enabled fieldsUse the versioned response schema and endpoints supplied for your deployment.
Image formats, size and concurrency limitsValidate images before upload and test the traffic your application will send.
Errors, timeouts and retry rulesSeparate a failed request from an unreadable field and avoid creating duplicate workflow records.
Retention, hosting and security controlsAgree data handling, access, logging and deletion responsibilities for the actual deployment.

02 / SUBMIT AN IMAGE

Upload the cheque from your backend.

Send the image in the multipart field “file”. This example outlines the transport; use the service URL and authentication scheme supplied for your deployment.

cURL · server-side requestDeployment URL required
curl --fail-with-body --request POST \
  "${CHEQUEDB_BASE_URL}/api/v1/ocr/cheque/upload" \
  --header "Authorization: Bearer ${CHEQUEDB_TOKEN}" \
  --form "file=@./sample-cheque.jpg"

Replace the URL and token placeholders with provisioned access. Obtain the versioned API reference and limits from our team.

03 / USE THE RESULT

Map the cheque OCR JSON response to your workflow.

Use the eight cheque fields and validation values below to plan your result mapping. Confirm date formatting and validation behaviour in your deployment’s API contract.

01

Preserve the raw read

Map the fields documented for your deployment. Keep missing values explicit and retain the source text alongside normalised values.

02

Apply your checks

Compare written and numeric amounts, handle ambiguous dates and use your bank’s duplicate and eligibility rules.

03

Create a review task

Show the source image, disputed field and reason to the reviewer. Record the corrected value and final decision in your workflow.

JSON · response exampleCheque fields
{
  "date": "2026-06-09",
  "payee": "Willow Trading Ltd",
  "amount_in_numerals": "1268.69",
  "amount_in_words": "One thousand two hundred sixty-eight pounds — 69p",
  "bank_name": "Barclays Bank PLC",
  "branch": "Leicester",
  "cheque_number": "000042",
  "drawer_name": "Cedar Works Ltd",
  "validation": {
    "amount_match": true,
    "post_dated": false
  }
}

04 / DESIGN THE EXCEPTIONS

Handle cheque API errors, timeouts and retries.

ConditionApplication behaviour to design
Invalid or unsupported imageExplain the accepted formats and request a new capture.
Missing or conflicting fieldSend the image and affected values to review instead of silently accepting them.
Rate limit or temporary service failureUse the documented retry policy and delay. Preserve your job identifier.
Timeout or interrupted connectionTrack request state; do not treat an unknown outcome as an accepted deposit.
Duplicate submissionUse an application idempotency strategy and bank/account context; a cheque number alone is not a unique global identifier.

Use the HTTP status codes, error bodies and delivery mechanism documented for your deployment.

05 / FIELD REFERENCE

Cheque API response fields.

Each response returns the eight cheque fields and the validation values shown in the example above. Treat every field as optional in your mapping: a field can be missing when the cheque is blank, damaged or unreadable.

FieldWhat it containsMapping advice
dateThe cheque date, normalised where it can be readKeep the raw value too; day/month order differs by country.
payeeThe handwritten or printed payee nameMatch against your customer or account records rather than exact string equality.
amount_in_numeralsThe amount from the numeric boxStore as a decimal string to avoid rounding errors.
amount_in_wordsThe written legal amount, including colloquial formsCompare with the numeric amount; disagreements go to review.
bank_nameThe drawee bank printed on the chequeCombine with MICR routing or sort code data where available.
branchThe branch name printed on the chequeOptional on many layouts; do not make it required.
cheque_numberThe cheque serial numberPreserve leading zeros. Combine with bank and account for duplicate checks.
drawer_nameThe account holder who wrote the chequeUse for review and matching, not as proof of identity.
validation.amount_matchWhether the written and numeric amounts agreeFalse or missing should create a review task.
validation.post_datedWhether the cheque date is in the futureApply your bank’s rules for post-dated and stale cheques.

06 / SERVER QUICKSTART

Call the cheque API from Node.js.

A minimal backend handler: read the image, upload it, and return the fields your application needs. Keep the token on the server and add your own retry and job tracking around it.

Node.js 20 · fetch + FormDataDeployment URL required
import { readFile } from 'node:fs/promises'

export async function extractCheque(path) {
  const form = new FormData()
  form.append('file', new Blob([await readFile(path)], { type: 'image/jpeg' }), 'cheque.jpg')

  const res = await fetch(`${process.env.CHEQUEDB_BASE_URL}/api/v1/ocr/cheque/upload`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.CHEQUEDB_TOKEN}` },
    body: form,
  })
  if (!res.ok) throw new Error(`Cheque API ${res.status}: ${await res.text()}`)

  const result = await res.json()
  const needsReview = !result.validation?.amount_match || !result.amount_in_numerals
  return { ...result, needsReview }
}

QUESTIONS & ANSWERS

Cheque API authentication and integration questions

What is the ChequeDB cheque API?

A cheque processing API that takes a cheque image and returns structured JSON: date, payee, the amount in words and numerals, bank, branch, cheque number and drawer, plus validation values such as whether the two amounts agree.

Can the cheque API be used for mobile or scanner deposit?

Yes. Mobile apps and scanner adapters both submit images through your backend. The API returns the extracted fields; deposit submission and clearing stay with your banking integration.

How are rate limits and image sizes set?

Limits, accepted formats and concurrency are agreed for each deployment. Validate images before upload, and handle a rate-limit response by retrying after a delay with the same job identifier.

Where can I get the API reference?

Request the versioned API reference, credentials, supported fields and limits from our team. Use the upload example and response fields here to plan your integration.

Can I call the OCR service directly from a mobile app?

Keep service credentials in your backend and connect the mobile capture flow through an authenticated application service. Agree the upload and data-handling design for your deployment.

Are webhooks, OAuth or native SDKs included?

Agree the authentication scheme, result delivery and SDK or capture components with our team as part of your integration scope.

Does an OCR response create a bank deposit?

No. OCR returns extraction results. Deposit submission, acceptance, clearing and settlement require the relevant banking integrations and bank policies.

BUILD WITH CHEQUEDB

Add cheque scanning to your workflow.

Tell us about your app, cheque layouts and required fields. Let’s plan an evaluation with your documents.

Contact sales