ID Forgery Check - Singapay Documentation

curl --request POST \
  --url https://sandbox-apigw.singapay.id/api/v1/kyc/id-forgery-check \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "request_id": "TXN-20260917-001",
  "image_url": "https://cdn.example.com/ktp.jpg"
}
'

{
  "code": "SUCCESS",
  "message": "OK",
  "data": {
    "is_forged": false,
    "reason": "PASS"
  },
  "request_id": "TXN-20260917-001",
  "pricing": "PAID"
}

ID Forgery Check

Assesses whether a photo of an Indonesian ID card (KTP) is a forgery / presentation-attack (photocopy, photograph of the original, edited image, or failed information checks).

A completed assessment is billed (pricing=PAID), including when data.is_forged is TRUE. Validation failures and service failures are not billed (pricing=FREE).

This feature must be enabled on your account. If it is not, the API returns UNAUTHORIZED.

Outcomes

Result	Response
Assessment completed	`code=SUCCESS`, `data.is_forged` / `data.reason`, `pricing=PAID`
Missing `request_id` / image, both `image_url` and `image_base64`, or wrong image format	`code=CLIENT_ERROR`, `pricing=FREE` (HTTP 400)
Image exceeds 8MB	`code=CLIENT_ERROR`, `pricing=FREE` (HTTP 413)
Temporary service issue	`code=SERVER_ERROR`, `pricing=FREE`
Same `request_id` reused after a completed check	`code=DUPLICATE_REFERENCE`, `pricing=FREE` (HTTP 409)
Same `request_id` reused after a failed attempt	Retried for real: the image you send this time is what actually gets processed and (if it succeeds) billed
Missing token, feature not enabled, or IP not allowlisted	`code=UNAUTHORIZED`, `pricing=FREE`
Prepaid balance too low	`code=INSUFFICIENT_BALANCE`, `pricing=FREE`

Images

JPEG and PNG only, 8 MB or smaller. Send the photo either as:

application/json — request_id plus exactly one of image_url (HTTPS URL fetched by the engine) or image_base64 (raw base64, no line breaks, no data:image/… prefix)
multipart/form-data — request_id as a text field, image as a file part

Do not mix the two encodings in one request.

`data.reason` mapping

`is_forged`	`reason`
`FALSE`	`PASS`
`TRUE`	Known labels joined with `"; "` — photocopy, photograph of the original, edited, format validation failed, consistency check failed. Empty string when the engine returned no mapped codes.

Vendor warning codes are never returned to merchants.

Idempotency

Use a unique request_id for each new check (UUID v4 is recommended). Reusing a request_id that already resolved to a completed check always returns DUPLICATE_REFERENCE. Reusing a request_id whose prior attempt failed retries for real.

POST

api

kyc

id-forgery-check

curl --request POST \
  --url https://sandbox-apigw.singapay.id/api/v1/kyc/id-forgery-check \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "request_id": "TXN-20260917-001",
  "image_url": "https://cdn.example.com/ktp.jpg"
}
'

{
  "code": "SUCCESS",
  "message": "OK",
  "data": {
    "is_forged": false,
    "reason": "PASS"
  },
  "request_id": "TXN-20260917-001",
  "pricing": "PAID"
}

Authorizations

Authorization

string

header

required

Access token from POST /api/v1/kyc/auth/get-auth-token. Valid for one hour.

Body

Send exactly one of image_url or image_base64. Sending both, or neither, is CLIENT_ERROR.

request_id

string

required

Your unique reference for this check. Use a new UUID for each new attempt. Reusing a request_id that already completed returns DUPLICATE_REFERENCE.

Example:

"TXN-20260917-001"

image_url

string<uri>

Public HTTPS URL of the ID-card photo. JPEG or PNG. Mutually exclusive with image_base64. The image is fetched by the OCR engine; we do not store it.

Example:

"https://cdn.example.com/ktp.jpg"

image_base64

string

ID-card photo as raw base64 (JPEG or PNG). No line breaks and no data:image/… prefix. Maximum 8 MB after decoding. Mutually exclusive with image_url.

Example:

"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="

Response

Assessment complete. code is SUCCESS. data holds is_forged and reason. pricing is PAID.

code

enum<string>

required

Always SUCCESS on this response.

Available options:

SUCCESS

Example:

"SUCCESS"

message

enum<string>

required

Always OK. Use code and data, not this field, to branch.

Available options:

OK

Example:

"OK"

data

object

required

Merchant-facing assessment. Vendor warning codes are not returned; they are mapped to is_forged and reason only.

Show child attributes

request_id

string

required

The request_id you sent.

Example:

"TXN-20260917-001"

pricing

enum<string>

required

A completed check is always billed.

Available options:

PAID

Example:

"PAID"