Merchant integration

MyKad OCR API

Extract text and structured fields from the front of a Malaysian MyKad.

HTTPS API available Base URL: https://api.orpheuscapitalmy.com

Call this API from your server using the merchant key supplied by the operator. Send it in the X-API-Key header. Do not put the key in client-side code, URLs, or logs.

Parse a MyKad

POST /documents/mykad/parse accepts multipart/form-data with one image file. Supported formats are JPG, PNG, BMP, WebP, TIFF and PDF; maximum upload size is 20 MiB. A MyKad request must contain one page.

Form field	Default	Purpose
`image`	required	Front image of a MyKad
`mask_sensitive`	`false`	Mask most digits of the ID number in the response
`include_raw_ocr`	`false`	Include raw OCR text and coordinates; cannot be combined with masking

curl --fail-with-body https://api.orpheuscapitalmy.com/documents/mykad/parse \
  -H "X-API-Key: $OCR_API_KEY" \
  -F 'image=@./document.jpg' \
  -F 'mask_sensitive=true' \
  -F 'include_raw_ocr=false'

The response contains fields.id_number, fields.name, fields.address, fields.citizenship, fields.religion and fields.gender. Each field carries its OCR confidence and source line indexes. Read success and warnings; HTTP 200 can still require review.

OCR confidence is not an accuracy guarantee. This service extracts printed text; it does not authenticate the card, check a government database, or match a person to the portrait. Route missing, ambiguous or important fields to human review. Masking the number does not hide the name or address.

Other endpoints

Endpoint	Purpose
`POST /ocr`	Generic OCR; returns unmasked text
`GET /documents`	Supported document types (API key required)
`GET /languages`	OCR language profiles (API key required)
`GET /health`	Service status

Interactive API schema: Swagger UI · OpenAPI JSON.

Errors and limits

Authentication failures return 401 or 403; oversized files return 413; unsupported formats return 415; invalid requests return 422. A 429 can indicate the merchant's monthly quota or gateway traffic limit. Retry timeouts only when your workflow permits duplicate processing.

Upload a neutral filename such as document.jpg. The API does not intentionally retain uploaded images or OCR text in the merchant usage database. Clients must protect their own request and response logs.