API Documentation

1. Getting Started

KYC LIFE ให้บริการ 4 ระบบหลักผ่าน REST API:

• KYC Sessions — เก็บข้อมูลบัตรประชาชน, selfie, ที่อยู่ พร้อมระบบอนุมัติ
• Payment Links — สร้างลิงก์รับเงิน ตรวจสลิปอัตโนมัติ
• Bank Verifications — ยืนยันว่าลูกค้าเป็นเจ้าของบัญชีธนาคารจริง
• Banks — reference data รหัส/ชื่อ/logo ธนาคารไทย (public)

2. Authentication

ทุก request ต้องส่ง API key ผ่าน Authorization header:

Authorization: Bearer kyc_live_xxxxxxxxxxxxxxxxxxxxxxxx

• Live keys (kyc_live_...) — ใช้กับ production
• Test keys (kyc_test_...) — sandbox, ไม่นับโควตา
• Rate limit default: 60 req/min (ปรับได้ต่อ key)
• IP allowlist: ระบุได้ต่อ key
• Idempotency-Key header รองรับบน POST endpoints (cache 24 ชม.)

3. KYC Sessions

สร้าง session → รับ URL → ส่งให้ลูกค้ากรอกข้อมูล → admin อนุมัติ → webhook ส่งกลับ

3.1 Endpoints

{
  "id": "uuid",
  "sessionToken": "abc123...",
  "url": "https://kyc.life/kyc/abc123...",
  "status": "created",
  "expiresAt": "2026-04-19T12:00:00Z",
  "externalId": "customer-123",
  "createdAt": "2026-04-18T12:00:00Z",
  "environment": "live"
}

{
  "id": "uuid",
  "sessionToken": "abc123...",
  "status": "approved",
  "externalId": "customer-123",
  "personalInfo": {
    "firstName": "สมชาย",
    "lastName": "ใจดี",
    "idCardNumber": "1234567890123",
    "dateOfBirth": "1990-01-15T00:00:00Z",
    "nationality": "TH",
    "phone": "0812345678",
    "email": "[email protected]"
  },
  "address": { "addressLine1": "...", "district": "...", "province": "...", "postalCode": "..." },
  "documents": {
    "idCardFrontUrl": "https://...",
    "idCardBackUrl":  "https://...",
    "selfieUrl":      "https://..."
  },
  "bankAccount": {
    "status": "verified",
    "accountName": "สมชาย ใจดี",
    "accountNumber": "1234567890",
    "bankCode": "KBANK"
  },
  "riskScore": 12,
  "rejectionReason": null,
  "reviewedAt": "2026-04-18T13:00:00Z",
  "submittedAt": "2026-04-18T12:30:00Z",
  "createdAt":   "2026-04-18T12:00:00Z"
}

3.2 Session lifecycle

3.3 ตัวอย่าง: สร้าง session ธรรมดา

curl -X POST https://kyc.life/api/v1/sessions \
  -H "Authorization: Bearer kyc_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user-123",
    "expiresInHours": 48
  }'

# Response:
# { "url": "https://kyc.life/kyc/abc123...", ... }

3.4 ตัวอย่าง: สร้าง session + ยืนยันบัญชีธนาคาร

curl -X POST https://kyc.life/api/v1/sessions \
  -H "Authorization: Bearer kyc_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user-123",
    "requireBankVerify": true,
    "expiresInHours": 48,
    "metadata": { "order_id": "ORD-456" }
  }'

4. Payment Links

สร้างลิงก์รับเงินผ่าน API → ลูกค้าจ่ายแล้ว upload สลิป → ระบบยืนยันอัตโนมัติผ่าน EasySlip → webhook กลับ

4.1 Endpoints

{
  "id": "uuid",
  "token": "abc123...",
  "url": "https://kyc.life/pay/abc123...",
  "status": "pending",
  "amount": 1000,
  "description": "ค่าสินค้า ORD-123",
  "expiresAt": "2026-04-19T12:00:00Z",
  "externalId": "ORD-123",
  "createdAt": "2026-04-18T12:00:00Z"
}

4.2 Verification pipeline

1. ลูกค้าเปิดลิงก์ → เห็น QR PromptPay + รายละเอียดบัญชี + จำนวนที่ต้องโอน
2. โอนเงิน → upload สลิป → ส่งเข้า EasySlip API
3. Duplicate check — trans ref ห้ามซ้ำ (cross-check payment + KYC + bank verify)
4. Amount — ตรงกับ amount ใน payment link (tolerance 0.01)
5. Receiver account — ต้องตรงกับบัญชีระบบ
6. Transaction time — สลิปอายุไม่เกิน 24 ชม.
7. ถ้าผ่านทุกข้อ → paid + webhook payment.paid
8. ถ้าไม่ตรง → verifying รอ admin review

4.3 Payment status

4.4 ตัวอย่าง: สร้าง payment link

curl -X POST https://kyc.life/api/v1/payment-links \
  -H "Authorization: Bearer kyc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "ค่าสินค้า ORD-456",
    "amount": 1500.00,
    "customerName": "สมชาย ใจดี",
    "externalId": "ORD-456",
    "expiresInMinutes": 15,
    "returnUrl": "https://your-site.com/order/success",
    "webhookUrl": "https://your-site.com/api/payment-callback"
  }'

5. Bank Verifications

ยืนยันว่าลูกค้าเป็นเจ้าของบัญชีธนาคารจริง — เป็นบริการแยกต่างหากไม่ยึดติดกับ KYC ใช้หลัก: โอนเงินจำนวนสุ่ม 0.01–2.99 บาทจากบัญชีลูกค้า → verify กับสลิปผ่าน EasySlip

5.1 Endpoints

{
  "id": "uuid",
  "token": "abc123...",
  "url": "https://kyc.life/bank-verify/abc123...",
  "status": "pending",
  "verifyAmount": 1.53,
  "verifyCode": "A3F9B2",
  "externalId": "user-123",
  "expiresAt": "2026-04-22T12:00:00Z",
  "createdAt": "2026-04-20T12:00:00Z"
}

5.2 Integration flow (เว็บต้นทาง)

1. ลูกค้ากรอกข้อมูลบัญชีธนาคารที่เว็บคุณ (ชื่อ, เลขบัญชี, ธนาคาร) แล้วกดส่ง
2. Backend ของคุณเรียก POST /api/v1/bank-verifications พร้อม accountName, accountNumber, bankCode + returnUrl, webhookUrl
3. ระบบคืน URL สำหรับลูกค้า → คุณ redirect ลูกค้าไป
4. ลูกค้าเห็นสรุปบัญชี (pre-filled) + QR บัญชีปลายทาง + ยอดสุ่ม + ref code
5. ลูกค้าโอน + upload สลิป → EasySlip verify → auto verified หรือ rejected
6. ระบบส่ง callback POST ไปที่ webhookUrl ทันที พร้อม event bank_verification.verified
7. ลูกค้าเห็น countdown 5 วินาที → auto-redirect ไป returnUrl?status=verified&token=...

5.3 Verification pipeline

1. Duplicate — trans ref ห้ามซ้ำ (cross-check ระบบ KYC + Payment + Bank Verify)
2. Amount — ตรงกับที่ระบบสุ่มไว้
3. Receiver — ตรงกับบัญชีระบบ (ของ tenant)
4. Sender name — ตรงกับ accountName (TH/EN name match)
5. Transaction time — สลิปอายุไม่เกิน 24 ชม.

5.4 ตัวอย่าง: สร้าง bank verification พร้อม pre-fill

curl -X POST https://kyc.life/api/v1/bank-verifications \
  -H "Authorization: Bearer kyc_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: user-123-${timestamp}" \
  -d '{
    "customerName":    "สมชาย ใจดี",
    "customerEmail":   "[email protected]",
    "externalId":      "user-123",
    "accountName":     "สมชาย ใจดี",
    "accountNumber":   "1234567890",
    "bankCode":        "KBANK",
    "expiresInMinutes": 5,
    "returnUrl":       "https://your-site.com/verified",
    "webhookUrl":      "https://your-site.com/api/bank-verify-callback"
  }'

5.5 Webhook payload: bank_verification.verified

{
  "event": "bank_verification.verified",
  "timestamp": 1729258800,
  "data": {
    "id": "uuid",
    "token": "abc123...",
    "externalId": "user-123",
    "status": "verified",
    "customer": { "name": "สมชาย ใจดี", "email": "..." },
    "account": {
      "accountName": "สมชาย ใจดี",
      "accountNumber": "1234567890",
      "bankCode": "KBANK"
    },
    "slip": {
      "url": "https://kyc.life/uploads/...",
      "transRef": "0123456789",
      "senderName": "สมชาย ใจดี",
      "senderAccount": "xxx-x-x7890",
      "senderBank": "Kasikornbank"
    },
    "verifyAmount": 1.53,
    "verifyCode": "A3F9B2",
    "verifiedAt": "2026-04-20T12:05:00Z",
    "metadata": { "yourOrderId": "..." }
  }
}

6. Banks Reference

Reference data ของธนาคารไทย — รหัส BOT, ชื่อ TH/EN, abbreviation, และ logo PNG เป็น public endpoint ไม่ต้องใช้ API key

6.1 Endpoints

{
  "banks": [
    {
      "code": "004",
      "abbreviation": "KBANK",
      "name": "ธนาคารกสิกรไทย",
      "nameTH": "ธนาคารกสิกรไทย",
      "nameEN": "Kasikornbank",
      "logo": "https://kyc.life/banks/kbank.png"
    }
  ],
  "count": 18
}

6.2 ตัวอย่าง: ดึงรายชื่อธนาคารทั้งหมด

curl https://kyc.life/api/v1/banks

# ใช้ใน dropdown ตอน customer เลือกธนาคาร
# หรือใช้ logo URL แสดงใน UI ของเว็บคุณ

6.3 ตัวอย่าง: แสดง logo ธนาคาร

<!-- ใช้ใน HTML ได้เลย -->
<img src="https://kyc.life/api/v1/banks/KBANK/logo" alt="KBANK" />

# หรือดึง metadata + logo URL ไปใช้
curl https://kyc.life/api/v1/banks/004
# → { "code": "004", "abbreviation": "KBANK", "logo": "...", ... }

7. Webhooks & Callbacks

ระบบส่งข้อมูลกลับ 2 แบบ — Tenant Webhook Endpoints (ตั้งได้หลาย URL ใน dashboard) และ Per-record Callback (ระบุ webhookUrl ตอนสร้าง resource)

7.1 Events ทั้งหมด

7.2 Request headers

X-KYC-Signature: t=1729258800,v1=abc123...
X-KYC-Event: session.approved
Content-Type: application/json

7.3 Payload (ตัวอย่าง session.approved)

{
  "event": "session.approved",
  "timestamp": 1729258800,
  "data": {
    "id": "uuid",
    "sessionToken": "abc123...",
    "externalId": "user-123",
    "status": "approved",
    "personalInfo": { "firstName": "...", "idCardNumber": "..." },
    "documents": { "idCardFrontUrl": "...", "selfieUrl": "..." },
    "riskScore": 12,
    "reviewedAt": "2026-04-18T13:00:00Z",
    "metadata": { "order_id": "ORD-456" }
  }
}

7.4 Payload (ตัวอย่าง payment.paid)

{
  "event": "payment.paid",
  "timestamp": 1729258900,
  "data": {
    "id": "uuid",
    "token": "abc123...",
    "status": "paid",
    "amount": 1500.00,
    "externalId": "ORD-456",
    "paidAt": "2026-05-06T09:00:00Z",
    "rejectionReason": null
  }
}

7.5 Payload (ตัวอย่าง payment.expired / session.expired)

{
  "event": "payment.expired",
  "timestamp": 1729259000,
  "data": {
    "id": "uuid",
    "token": "abc123...",
    "status": "expired",
    "amount": 1500.00,
    "externalId": "ORD-456",
    "paidAt": null,
    "rejectionReason": null
  }
}
// session.expired → data มี sessionToken, submittedAt = null
// bank_verification.expired → data มี token, verifiedAt = null

7.6 ตรวจสอบลายเซ็น (HMAC SHA-256)

import crypto from 'crypto'

// ใช้ Endpoint Secret (tenant webhook) หรือ CALLBACK_SECRET (per-record)
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET

const header = req.headers['x-kyc-signature']
const [ts, sig] = header.split(',').map(p => p.split('=')[1])

const expected = crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(`${ts}.${rawBody}`)
  .digest('hex')

const valid = crypto.timingSafeEqual(
  Buffer.from(sig, 'hex'),
  Buffer.from(expected, 'hex')
)

7.7 returnUrl — Browser Redirect

หาก resource มี returnUrl ระบบจะ redirect browser ลูกค้าอัตโนมัติ 5 วินาทีหลังสำเร็จ:

7.8 Retry policy (Tenant Endpoints เท่านั้น)

ถ้า endpoint ตอบ non-2xx ระบบจะ retry 5 ครั้ง ด้วย exponential backoff: 1m → 5m → 15m → 1h → 4h — retry ด้วย cron ที่รันทุกนาที

8. Error Codes

9. Node.js SDK

npm install @kyc-life/node

import { KycLife } from '@kyc-life/node'
const kyc = new KycLife({ apiKey: process.env.KYC_LIFE_API_KEY })

// KYC session
const session = await kyc.sessions.create({ externalId: 'user-123' })

// Payment link
const payment = await kyc.paymentLinks.create({
  description: 'Order #456',
  amount: 1500,
  externalId: 'order-456',
})

// Bank account verification (with pre-fill from your site)
const bv = await kyc.bankVerifications.create({
  customerName: 'สมชาย ใจดี',
  externalId: 'user-123',
  accountName: 'สมชาย ใจดี',
  accountNumber: '1234567890',
  bankCode: 'KBANK',
  returnUrl: 'https://your-site.com/verified',
})

// Redirect customer to bv.url / session.url / payment.url