ตรวจสอบสลิปแบบ Async

ส่งสลิปธนาคารเข้าตรวจสอบแบบ asynchronous — แทนที่จะรอผลลัพธ์ค้างไว้ API จะคืน jobId กลับมาทันที แล้วตรวจสอบสลิปเบื้องหลัง ผลลัพธ์จะถูกส่งไปที่ webhook ของคุณ และ/หรือดึงได้ด้วยการpolling job

เหมาะกับงานปริมาณมาก / bulk ที่ไม่ต้องการผลลัพธ์ทันที ถ้าต้องการผลลัพธ์แบบ inline ครั้งเดียว ให้ใช้POST /verify/bank แบบ synchronous แทน

เฉพาะธนาคาร

Async ใช้ได้กับสลิปธนาคารเท่านั้น และรับเฉพาะ QR payload string (ไม่รองรับ image / base64 / url) TrueWallet ไม่มี payload จึงใช้ route /verify/truewallet แบบ synchronous

Endpoint

POST /verify/bank/async

URL เต็ม: https://api-partners.easyslip.com/v2/verify/bank/async

การยืนยันตัวตน

จำเป็น ใช้ HMAC-SHA256 กับ Branch UUID เป็น X-API-Key ดูคู่มือ Authentication

X-API-Key: YOUR_BRANCH_UUID
X-Timestamp: 1700000000
X-Nonce: 550e8400-e29b-41d4-a716-446655440000
X-Signature: HMAC_SHA256_SIGNATURE
Content-Type: application/json

Request

พารามิเตอร์

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
payload	string	ใช่	QR Code Payload (1-128 ตัวอักษร)
callbackUrl	string	มีเงื่อนไข	URL แบบ HTTPS ที่จะรับผลลัพธ์ (POST) จำเป็นถ้า branch ไม่ได้ตั้ง webhook URL เริ่มต้นไว้ สูงสุด 255 ตัวอักษร
remark	string	ไม่	หมายเหตุ (1-255 ตัวอักษร)
matchAccount	boolean	ไม่	จับคู่ผู้รับกับบัญชีที่ลงทะเบียน
matchAmount	number	ไม่	จำนวนเงินที่คาดหวัง
checkDuplicate	boolean	ไม่	ตรวจสอบสลิปซ้ำ (ค่าเริ่มต้น: false)

ข้อกำหนดของ callbackUrl

callbackUrl ต้องเป็น HTTPS และต้อง resolve ไปยัง address สาธารณะ — URL ที่ชี้ไปยัง IP ภายใน/ส่วนตัวจะถูกปฏิเสธ ถ้าไม่ใส่ callbackUrl จะใช้ webhook URL ที่ตั้งไว้ที่ branch ถ้าไม่มีทั้งคู่ request จะถูกปฏิเสธด้วย VALIDATION_ERROR

Request Body

{
  "payload": "00000000000000000000000000000000000000000000000",
  "callbackUrl": "https://example.com/webhooks/easyslip",
  "remark": "Order #12345",
  "checkDuplicate": true
}

Type Definitions

// Request
interface AsyncVerifyBankRequest {
  payload: string;          // 1-128 ตัวอักษร
  callbackUrl?: string;     // https URL, สูงสุด 255 ตัวอักษร (จำเป็นถ้า branch ไม่มี webhook)
  remark?: string;          // 1-255 ตัวอักษร
  matchAccount?: boolean;
  matchAmount?: number;
  checkDuplicate?: boolean;
}

// Response
interface AsyncVerifyResponse {
  success: true;
  data: {
    jobId: string;          // UUID — ใช้ poll GET /verify/bank/jobs/:jobId
  };
  message: string;
}

ตัวอย่าง

cURL

curl -X POST https://api-partners.easyslip.com/v2/verify/bank/async \
  -H "X-API-Key: YOUR_BRANCH_UUID" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-Nonce: ${NONCE}" \
  -H "X-Signature: ${SIGNATURE}" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": "00000000000000000000000000000000000000000000000",
    "callbackUrl": "https://example.com/webhooks/easyslip",
    "checkDuplicate": true
  }'

JavaScript

const verifyBankAsync = async (payload, callbackUrl, options = {}) => {
  const body = JSON.stringify({ payload, callbackUrl, ...options });
  const response = await fetch('https://api-partners.easyslip.com/v2/verify/bank/async', {
    method: 'POST',
    headers: {
      ...signRequest({ method: 'POST', path: '/verify/bank/async', body, apiKey: 'YOUR_BRANCH_UUID', secretKey: 'YOUR_SECRET_KEY' }),
      'Content-Type': 'application/json'
    },
    body
  });

  const result = await response.json();
  if (!result.success) throw new Error(result.error.message);

  return result.data.jobId;
};

// การใช้งาน
const jobId = await verifyBankAsync(
  '00000000000000000000000000000000000000000000000',
  'https://example.com/webhooks/easyslip',
  { checkDuplicate: true }
);
console.log('Queued job:', jobId);

TypeScript

interface AsyncOptions {
  remark?: string;
  matchAccount?: boolean;
  matchAmount?: number;
  checkDuplicate?: boolean;
}

async function verifyBankAsync(payload: string, callbackUrl: string, options: AsyncOptions = {}): Promise<string> {
  const body = JSON.stringify({ payload, callbackUrl, ...options });
  const response = await fetch('https://api-partners.easyslip.com/v2/verify/bank/async', {
    method: 'POST',
    headers: {
      ...signRequest({ method: 'POST', path: '/verify/bank/async', body, apiKey: process.env.EASYSLIP_API_KEY!, secretKey: process.env.EASYSLIP_SECRET_KEY! }),
      'Content-Type': 'application/json'
    },
    body
  });

  const result = await response.json();
  if (!result.success) throw new Error(result.error?.message || 'Async verify failed');

  return result.data.jobId;
}

PHP

function verifyBankAsync(string $payload, string $callbackUrl, array $options = []): string
{
    $data = array_merge(['payload' => $payload, 'callbackUrl' => $callbackUrl], $options);

    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL => 'https://api-partners.easyslip.com/v2/verify/bank/async',
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => [
            // ใช้ helper signRequest() - ดูคู่มือ Authentication
            'Content-Type: application/json'
        ],
        CURLOPT_POSTFIELDS => json_encode($data)
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    $result = json_decode($response, true);
    if (!$result['success']) {
        throw new Exception($result['error']['message']);
    }

    return $result['data']['jobId'];
}

Python

import requests
import os

def verify_bank_async(payload: str, callback_url: str, **options) -> str:
    data = {'payload': payload, 'callbackUrl': callback_url, **options}
    response = requests.post(
        'https://api-partners.easyslip.com/v2/verify/bank/async',
        headers={
            **sign_request('POST', '/verify/bank/async', data, os.environ['EASYSLIP_API_KEY'], os.environ['EASYSLIP_SECRET_KEY']),
            'Content-Type': 'application/json'
        },
        json=data
    )

    result = response.json()
    if not result['success']:
        raise Exception(result['error']['message'])

    return result['data']['jobId']

Response

Accepted (202)

{
  "success": true,
  "data": {
    "jobId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "message": "Verification job queued"
}

202 Accepted หมายถึง job ถูก queue แล้ว — ไม่ใช่ว่าตรวจสอบสลิปเสร็จ ให้รอ webhook หรือpoll job ด้วย jobId ที่ได้

Error Responses

ไม่มี Payload / callbackUrl (400)

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Payload is required and cannot be empty"
  }
}

callbackUrl ไม่ถูกต้อง (400)

{
  "success": false,
  "error": {
    "code": "INVALID_CALLBACK_URL",
    "message": "callbackUrl must use the https protocol"
  }
}

เกิน Rate Limit (429)

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded"
  }
}

ดูRate Limits สำหรับ header X-RateLimit-* และ Retry-After

หมายเหตุ

• jobId ที่คืนมาเป็น UUID เก็บไว้เพื่อจับคู่กับ webhook และใช้ poll สถานะ job
• ผลลัพธ์ถูกส่งไปที่ webhook (ดูWebhooks) การ poll เป็นทางเลือกสำรอง
• ส่งหลายสลิปในครั้งเดียวใช้POST /verify/bank/batch (สูงสุด 100 สลิป)
• Async รับเฉพาะ payload — ถ้าตรวจด้วยรูป/URL ใช้POST /verify/bank แบบ synchronous