Getting Started

Run your first eKYC session in about 10 minutes using cURL and images you already have. This page skips the SDKs and every advanced option — read Overview when you need the whole picture.

What You Need

What	Description
Access ID + Access Key	Contact CAKE Support to obtain them.
Base URL	Issued by CAKE together with your credentials, for both stage and production.
Three test images	NID front, NID back, and a selfie. JPG or PNG, under 15MB.
An HMAC signer	Every request must be signed. Use the script below.

Step 0 — Sign the request

Every call needs the Authorization and X-TV-Timestamp headers. This produces both:

const CryptoJS = require("crypto-js");

const ACCESS_ID  = "<ACCESS_ID>";
const ACCESS_KEY = "<ACCESS_KEY>";

function sign(method, path, body) {
  const timestamp = new Date().toISOString();
  const hashedBody = CryptoJS.SHA256(body).toString(CryptoJS.enc.Hex);
  const stringToSign = `${method}\n${path}\n${timestamp}\n${hashedBody}`;
  const hmac = CryptoJS.HmacSHA256(stringToSign, ACCESS_KEY);
  const signature = CryptoJS.enc.Base64.stringify(
    CryptoJS.enc.Hex.parse(hmac.toString(CryptoJS.enc.Hex))
  );
  return {
    "X-TV-Timestamp": timestamp,
    "Authorization": `ATV ${ACCESS_ID}:${signature}`,
  };
}

The full algorithm is in Overview § Authentication.

Step 1 — Upload the images

Upload each image once and get back an image_id. Every later call takes that ID instead of the bytes.

curl -X POST '<BASE_URL>/v1/images' \
  -H 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  -H 'X-TV-Timestamp: <TIMESTAMP>' \
  -F 'file=@"nid-front.jpg"' \
  -F 'label="id_card.vn.national_id.front"'

{ "data": { "image_id": "20b457d2-cf11-4c2b-a491-8137ae6b0bc8" }, "success": true, "code": 0 }

Repeat for the back (id_card.vn.national_id.back) and the selfie (portrait). Keep all three IDs.

→ Upload Image

Step 2 — Check the card image quality

Always run this first. A blurred or glared image corrupts every check that follows.

curl -X POST '<BASE_URL>/v1/verify_id_card_sanity_sync' \
  -H 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  -H 'X-TV-Timestamp: <TIMESTAMP>' \
  -H 'Content-Type: application/json' \
  -d '{
    "card_type": "vn.national_id",
    "image1": { "id": "<FRONT_IMAGE_ID>" },
    "image2": { "id": "<BACK_IMAGE_ID>" }
  }'

{ "data": { "card_sanity": { "verdict": "good", "score": 1 }, "status": "success" } }

Anything other than good means the user must retake the photo — look the verdict up in Verdict Definitions.

→ Verify ID Card Sanity

Step 3 — Read the card

curl -X POST '<BASE_URL>/v1/read_id_card_info_sync' \
  -H 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  -H 'X-TV-Timestamp: <TIMESTAMP>' \
  -H 'Content-Type: application/json' \
  -d '{
    "card_type": "vn.national_id",
    "image1": { "id": "<FRONT_IMAGE_ID>" }
  }'

The response carries card_information — an array of fields, each with a confidence score.

→ Read ID Card Info

Step 4 — Match the face

Compare the selfie against the portrait printed on the card.

curl -X POST '<BASE_URL>/v1/compare_faces_sync' \
  -H 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  -H 'X-TV-Timestamp: <TIMESTAMP>' \
  -H 'Content-Type: application/json' \
  -d '{
    "image1": { "id": "<SELFIE_IMAGE_ID>" },
    "image2": { "id": "<FRONT_IMAGE_ID>" }
  }'

{
  "data": {
    "compare_faces": [
      { "result": "matched", "score": 0.95 }
    ],
    "status": "success"
  }
}

→ Compare Faces

That's the core

You have just run the spine of an eKYC session: upload → quality check → read the card → match the face.

WARNING

This flow is not production-ready. It is missing at least card tampering detection, selfie liveness, and duplicate checking. See Onboard a New Customer for the complete flow.

Next Steps

• Onboard a New Customer — the production-ready flow
• Choosing an Integration Method — API, Mobile SDK or Web SDK
• Testing — run the flow without a real camera
• Overview — architecture, authentication, response signing