ตรวจสอบใบหน้าจริงแบบ Active

พิสูจน์ว่ามีคนจริงอยู่หน้ากล้อง โดยตรวจซ้ำเซลฟี่และบันทึกการทำท่าที่ eKYC SDK เก็บบนอุปกรณ์ แล้วส่งผลตัดสินที่ลงนามกลับมา

POST/v3/store/ekyc/face-active-liveness/finalizeทดลองใช้

ราคา1 ICต่อครั้ง
ให้บริการแล้ว22.4Kครั้ง

v1.0
ใช้งานได้

Input

file: selfie.jpg
challenges: {"session_id":"b0e7c1a2-4f5d-4e6a-9b8c-7d6e5f4a3b2c","sdk":{"name":"iapp-ekyc-sdk-flutter","version":"0.1.0","platform":"android"},"started_at":1767500000000,"finished_at":1767500008000,"challenges":[{"type":"blink","issued_at":1767500000123,"completed_at":1767500001873,"passed":true},{"type":"turn_left","issued_at":1767500002000,"completed_at":1767500004100,"passed":true},{"type":"smile","issued_at":1767500004500,"completed_at":1767500006900,"passed":true}]}

OutputPOST /v3/store/ekyc/face-active-liveness/finalize

verdict: { passed, passive_liveness, challenge_summary, session_id, selfie_sha256, timestamp, nonce }
signature: hex(HMAC-SHA256(secret, canonicalJSON(verdict)))
signature_alg: HMAC-SHA256
process_time: 0.42

ฟิลด์ทั้งหมดอยู่ในหัวข้อ Response

Request

curl -X POST https://api.iapp.co.th/v3/store/ekyc/face-active-liveness/finalize \
  -H "apikey: YOUR_API_KEY" \
  -F "file=@selfie.jpg" \
  -F 'challenges={"session_id":"b0e7c1a2-4f5d-4e6a-9b8c-7d6e5f4a3b2c","sdk":{"name":"iapp-ekyc-sdk-flutter","version":"0.1.0","platform":"android"},"started_at":1767500000000,"finished_at":1767500008000,"challenges":[{"type":"blink","issued_at":1767500000123,"completed_at":1767500001873,"passed":true},{"type":"turn_left","issued_at":1767500002000,"completed_at":1767500004100,"passed":true},{"type":"smile","issued_at":1767500004500,"completed_at":1767500006900,"passed":true}]}'

Response

200OK ฟิลด์อธิบายไว้ในหัวข้อ Response

{
  "verdict": {
    "passed": true,
    "passive_liveness": { "predict": "REAL", "real_score": 0.9999, "threshold": 0.5 },
    "challenge_summary": { "total": 3, "passed": 3, "types": ["blink", "turn_left", "smile"],
                           "duration_ms": 8000, "valid": true, "reasons": [] },
    "session_id": "b0e7c1a2-4f5d-4e6a-9b8c-7d6e5f4a3b2c",
    "selfie_sha256": "ab12cd34ef56ab12cd34ef56ab12cd34ef56ab12cd34ef56ab12cd34ef56ab12",
    "timestamp": "2026-07-04T09:00:00.000Z",
    "nonce": "9f3a1c7e2b8d4f60"
  },
  "signature": "hex(HMAC-SHA256(secret, canonicalJSON(verdict)))",
  "signature_alg": "HMAC-SHA256",
  "process_time": 0.42
}

Request

ส่งเป็น multipart/form-data โดย SDK สร้าง Request ให้ ถ้าจะเรียก endpoint เอง ต้องทำท่าบนอุปกรณ์แบบเดียวกัน คือสุ่มจากกะพริบตา หันซ้าย หันขวา และยิ้ม ตรวจจากจุดบนใบหน้าแบบเรียลไทม์ พร้อมเวลาจริงของเครื่อง

Headers

apikeystringrequired

API key ของคุณ สร้างได้ที่เมนู API Keys ในแผงควบคุม

Body

filefilerequired

เซลฟี่เฟรมที่ดีที่สุดของรอบนั้น ไฟล์ JPEG หรือ PNG ตรวจจากไบต์ของไฟล์ ไม่เกิน 10 MB

challengesstringrequired

บันทึกการทำท่าเป็นสตริง JSON มี session_id, sdk, started_at, finished_at และรายการต่อท่าที่มี type, issued_at, completed_at และ passed ตามตัวอย่างในแผงด้านข้าง

return_imagestring

ใส่ true เพื่อรับเซลฟี่กลับเป็น Base64 ในฟิลด์ selfie

บันทึกจะผ่านเมื่อทุกท่าเป็นหนึ่งในสี่ท่า มีอย่างน้อยสองท่าและผ่านทั้งหมด เวลาเพิ่มขึ้นตามลำดับเสมอ แต่ละท่าใช้เวลา 300 มิลลิวินาทีถึง 30 วินาที ทั้งรอบไม่เกิน 120 วินาที และจบภายใน 5 นาทีจากเวลาของเซิร์ฟเวอร์

Response

การตรวจที่เสร็จได้ 200 และคิดเงิน แม้ passed เป็น false ส่วน Response ที่เป็นข้อผิดพลาดไม่คิดเงิน

verdictobject

verdict.passedboolean

เป็น true เมื่อบันทึกถูกต้องและเซลฟี่ผ่านการตรวจแบบ Passive ที่ทดสอบโดย iBeta ระดับ PAD Level 1 เท่านั้น

verdict.passive_livenessobject

ผลการตรวจแบบ Passive บนเซลฟี่

verdict.challenge_summaryobject

สรุปผลการทำท่าที่ตรวจแล้ว ถ้า valid เป็น false ดูสาเหตุใน reasons

verdict.session_idverdict.timestampverdict.nonce

รอบ เวลาเซิร์ฟเวอร์แบบ ISO 8601 และค่าสุ่มที่ทำให้ทุกผลตัดสินไม่ซ้ำกัน

verdict.selfie_sha256string

SHA-256 ของเซลฟี่ ผูกผลตัดสินกับไบต์ของภาพนั้น

signaturesignature_alg

HMAC-SHA256 ของ verdict ในรูปแบบมาตรฐาน ใช้ Signing Secret ของบัญชีคุณเป็นกุญแจ

selfie

เมื่อใช้ return_image=true เท่านั้น: filename, content_type, size, image_base64

process_timenumber

วินาที

ตรวจลายเซ็น

คำนวณ HMAC ใหม่บนระบบหลังบ้านของคุณ จาก verdict ในรูปแบบมาตรฐาน คือเรียงคีย์ทุกชั้น ไม่มีช่องว่างเกิน และเป็น UTF-8 แล้วเทียบแบบเวลาคงที่ จากนั้นตรวจ passed ตรวจว่า timestamp ยังใหม่ และถ้าส่งเซลฟี่แยกมา ตรวจว่า SHA-256 ตรงกับ selfie_sha256

ลายเซ็นคือฟิลด์ signature ใน response body ไม่ใช่ HTTP header กุญแจคือ Signing Secret ของบัญชีคุณ ดูได้ที่หน้า API Keys บัญชีหนึ่งมีค่าเดียว ใช้ร่วมกันทุก API key และไม่ใช่ API key ใดๆ เก็บไว้บนเซิร์ฟเวอร์เท่านั้น ถ้าฝังไว้ในแอปหรือหน้าเว็บ ใครก็ปลอมผลตัดสินได้

ส่ง response body ตามที่ได้รับมาโดยตรง ข้อความที่ถูกเซ็นใช้รูปแบบตัวเลขของ JavaScript (เช่น 0.00005 และ 3.4e-7) การใช้ JSON.parse แล้ว JSON.stringify ให้ผลตรงกัน แต่ json.dumps ของ Python เขียนเป็น 5e-05 ทำให้ตรวจไม่ผ่านเมื่อ real_score มีค่าน้อย ตัวอย่าง Python และ C# จึงเก็บข้อความของตัวเลขตามที่อยู่ใน body ทั้งสามตัวอย่างทดสอบกับผลการตรวจจริงแล้ว

Node.js
Python
C#

const crypto = require('crypto');

const sortKeysDeep = (v) =>
  Array.isArray(v) ? v.map(sortKeysDeep)
  : v && typeof v === 'object'
    ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, sortKeysDeep(v[k])]))
    : v;
const canonical = (o) => JSON.stringify(sortKeysDeep(o));

function verifyVerdict(responseBody, accountSecret) {
  const { verdict, signature } = JSON.parse(responseBody);
  const expected = crypto.createHmac('sha256', accountSecret).update(canonical(verdict)).digest('hex');
  return expected.length === signature.length &&
    crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(signature, 'hex'));
}

// responseBody: the finalize response as a string; accountSecret: from the API Keys page
const ok = verifyVerdict(responseBody, accountSecret);

import hashlib
import hmac
import json


class _RawNumber(str):
    """A JSON number kept exactly as the server wrote it."""


def _canonical(value):
    if isinstance(value, dict):
        keys = sorted(value, key=lambda k: k.encode("utf-16-be"))  # JavaScript sort order
        return "{" + ",".join(
            json.dumps(k, ensure_ascii=False) + ":" + _canonical(value[k]) for k in keys
        ) + "}"
    if isinstance(value, list):
        return "[" + ",".join(_canonical(v) for v in value) + "]"
    if isinstance(value, _RawNumber):
        return str(value)
    return json.dumps(value, ensure_ascii=False)  # strings, true, false, null


def verify_verdict(response_body: str, account_secret: str) -> bool:
    """response_body: the finalize response exactly as received (str)."""
    resp = json.loads(response_body, parse_float=_RawNumber, parse_int=_RawNumber)
    canonical = _canonical(resp["verdict"])
    expected = hmac.new(account_secret.encode(), canonical.encode("utf-8"), hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, resp["signature"])


ok = verify_verdict(response.text, account_secret)  # e.g. requests.Response.text

using System;
using System.Linq;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

public static class IappLivenessVerdict
{
    // responseBody: the finalize response exactly as received. Do not deserialize it into
    // a class and serialize it again; that can change numbers and key order.
    // accountSecret: the Face Active Liveness Signing Secret from the iApp API Keys page.
    public static bool Verify(string responseBody, string accountSecret)
    {
        using var doc = JsonDocument.Parse(responseBody);
        var root = doc.RootElement;
        var signature = root.GetProperty("signature").GetString() ?? "";

        var canonical = new StringBuilder();
        WriteCanonical(root.GetProperty("verdict"), canonical);

        using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(accountSecret));
        var expected = Convert.ToHexString(hmac.ComputeHash(Encoding.UTF8.GetBytes(canonical.ToString()))).ToLowerInvariant();
        return CryptographicOperations.FixedTimeEquals(Encoding.ASCII.GetBytes(expected), Encoding.ASCII.GetBytes(signature));
    }

    // Canonical JSON: object keys sorted by UTF-16 code unit at every level, no whitespace,
    // numbers exactly as the server wrote them.
    static void WriteCanonical(JsonElement e, StringBuilder sb)
    {
        switch (e.ValueKind)
        {
            case JsonValueKind.Object:
                sb.Append('{');
                var first = true;
                foreach (var p in e.EnumerateObject().OrderBy(p => p.Name, StringComparer.Ordinal))
                {
                    if (!first) sb.Append(',');
                    first = false;
                    WriteString(p.Name, sb);
                    sb.Append(':');
                    WriteCanonical(p.Value, sb);
                }
                sb.Append('}');
                break;
            case JsonValueKind.Array:
                sb.Append('[');
                var n = 0;
                foreach (var item in e.EnumerateArray())
                {
                    if (n++ > 0) sb.Append(',');
                    WriteCanonical(item, sb);
                }
                sb.Append(']');
                break;
            case JsonValueKind.String:
                WriteString(e.GetString()!, sb);
                break;
            default: // number, true, false, null
                sb.Append(e.GetRawText());
                break;
        }
    }

    // Escapes a string the way JavaScript's JSON.stringify does.
    static void WriteString(string s, StringBuilder sb)
    {
        sb.Append('"');
        foreach (var c in s)
        {
            switch (c)
            {
                case '"': sb.Append("\\\""); break;
                case '\\': sb.Append("\\\\"); break;
                case '\b': sb.Append("\\b"); break;
                case '\f': sb.Append("\\f"); break;
                case '\n': sb.Append("\\n"); break;
                case '\r': sb.Append("\\r"); break;
                case '\t': sb.Append("\\t"); break;
                default:
                    if (c < 0x20) sb.Append("\\u").Append(((int)c).ToString("x4"));
                    else sb.Append(c);
                    break;
            }
        }
        sb.Append('"');
    }
}

// var ok = IappLivenessVerdict.Verify(responseBody, accountSecret);

รหัสสถานะ

รหัส	ความหมาย
400	`INVALID_CHALLENGE_LOG`, `INVALID_IMAGE` หรือ `MISSING_FIELD` พร้อมรายการ `reasons`
413	เซลฟี่เกิน 10 MB
502	`UPSTREAM_UNAVAILABLE` ลองใหม่ภายหลัง

รายละเอียดเพิ่มเติม

ข้อจำกัด

รอบจะเริ่มใหม่เมื่อหน้าหลุดจากกล้อง มีหน้าที่สองเข้ามา หรือคนเปลี่ยน

การจัดการข้อมูล

รูปภาพประมวลผลในหน่วยความจำและไม่เก็บไว้หลังส่งผลกลับ ผลตัดสินมีเพียงค่าแฮชของเซลฟี่ iApp ไม่เก็บสำเนา ส่วนการขอความยินยอมและการแจ้งเจ้าของข้อมูลตาม PDPA และ GDPR เป็นหน้าที่ของคุณในฐานะผู้ควบคุมข้อมูล และผลตัดสินที่ลงนามตรวจได้แบบออฟไลน์บนระบบของคุณเอง

Request​

Response​

รายละเอียดเพิ่มเติม​

Request

Response

รายละเอียดเพิ่มเติม