Payers (บัญชีผู้ใช้ปลายทาง)

payer คือบัญชีธนาคารของผู้ใช้ปลายทาง (ลูกค้าของคุณ) ทุก pay-in และ payout ต้องอ้างถึง payer หนึ่งคน

• สำหรับ pay-in ระบบใช้บัญชีของ payer ช่วยจับคู่การโอนเข้า จึงควรเป็นบัญชีที่ผู้ใช้จะโอนออกจริง
• สำหรับ payout บัญชีของ payer คือบัญชีปลายทางที่จะได้รับเงิน

สร้าง payer ได้สองวิธี

• ส่งแบบ inline ตอนใช้งานครั้งแรก (แนะนำ) ส่งบัญชีธนาคารเป็น payer: { bankCode, accountNumber, accountName } ตอนสร้าง pay-in หรือ payout ระบบจะสร้าง payer ในครั้งแรก และใช้ payer เดิมกับคำขอถัดไปที่ bankCode และ accountNumber ตรงกัน response มี payerId ของ payer นั้น
• สร้างไว้ก่อน ด้วย POST /v1/payers ด้านล่าง แล้วส่ง payerId

ทั้งสองวิธีตรวจสอบข้อมูลเหมือนกัน เก็บ id ไว้คู่กับผู้ใช้ในระบบของคุณถ้าต้องการอ้างถึง payer ภายหลัง

การส่ง payer แบบ inline จะไม่เปลี่ยนชื่อที่บันทึกไว้ของ payer เพราะระบบใช้ชื่อนี้จับคู่การโอนเข้า ถ้าชื่อต่างกันจะได้แค่คำเตือน payer_name_differs ถ้าต้องการเปลี่ยนชื่อ ใช้ PATCH /v1/payers/{id}

Method	Path	ใช้ทำอะไร
GET	/v1/banks	รายชื่อธนาคารที่รองรับ
POST	/v1/payers	สร้าง payer
GET	/v1/payers/{id}	ดู payer
GET	/v1/payers	ค้นหา payer
PATCH	/v1/payers/{id}	แก้ไข payer (ฟิลด์ที่ไม่ส่งจะคงค่าเดิม)
DELETE	/v1/payers/{id}	ลบ payer ที่ยังไม่มีรายการ
GET	/v1/payers/{id}/payments	pay-in และ payout ทั้งหมดของ payer

รายชื่อธนาคาร

GET /v1/banks

คืนรายการทั้งหมดในครั้งเดียว (ไม่มีการแบ่งหน้า) ใช้ code เป็น bankCode ตอนสร้าง payer รายการนี้เปลี่ยนไม่บ่อย ควร cache ไว้และดึงใหม่เป็นระยะ

{
  "data": [
    { "object": "bank", "code": "SCB", "name": "Siam Commercial Bank", "localName": "ธนาคารไทยพาณิชย์" },
    { "object": "bank", "code": "KBANK", "name": "Kasikorn Bank", "localName": "ธนาคารกสิกรไทย" }
  ],
  "requestId": "req_..."
}

สร้าง payer

POST /v1/payers

ฟิลด์	จำเป็น	คำอธิบาย
bankCode	ใช่	รหัสธนาคารจาก GET /v1/banks
accountNumber	ใช่	เลขบัญชี ตัวเลขเท่านั้น ไม่มีขีด (สูงสุด 32 หลัก)
accountName	ใช่	ชื่อบัญชีตามที่ธนาคารแสดง (สูงสุด 200 ตัว)
accountNameEn	ไม่	ชื่อบัญชีภาษาอังกฤษ
status	ไม่	active (ค่าเริ่มต้น) หรือ inactive payer ที่ inactive ใช้สร้างรายการไม่ได้
referralCode	ไม่	รหัสผู้แนะนำ ถ้ามี (สูงสุด 64 ตัว)

{
  "bankCode": "SCB",
  "accountNumber": "1234567890",
  "accountName": "สมชาย สบายดี",
  "accountNameEn": "Somchai Sabuydee"
}

response (201)

{
  "data": {
    "object": "payer",
    "id": "payer_7c0a4b8e2f3d4a1b9c8d7e6f5a4b3c2d",
    "bankCode": "SCB",
    "bankName": "Siam Commercial Bank",
    "accountNumber": "1234567890",
    "accountName": "สมชาย สบายดี",
    "accountNameEn": "Somchai Sabuydee",
    "status": "active",
    "referralCode": null,
    "createdAt": "2026-01-01T00:00:00.000Z"
  },
  "requestId": "req_..."
}

แก้ไข payer

PATCH /v1/payers/{id}

ส่งเฉพาะฟิลด์ที่ต้องการเปลี่ยน (ฟิลด์เดียวกับตอนสร้าง) ฟิลด์ที่ไม่ส่งจะคงค่าเดิม เช่น ปิดการใช้งาน payer

{ "status": "inactive" }

ค้นหา payer

GET /v1/payers?accountNumber=4567&bankCode=SCB

พารามิเตอร์	คำอธิบาย
accountNumber	เลขบัญชีที่มีข้อความนี้อยู่
accountName	ชื่อบัญชีที่มีข้อความนี้อยู่ ไม่สนตัวพิมพ์เล็กใหญ่
bankCode	รหัสธนาคาร
limit, cursor	การแบ่งหน้า

ลบ payer

DELETE /v1/payers/{id}

ลบได้เฉพาะ payer ที่ยังไม่เคยมี pay-in หรือ payout ถ้ามีแล้วจะได้ 409 payer_has_payments ให้เปลี่ยน status เป็น inactive แทน

{ "data": { "id": "payer_7c0a4b8e2f3d4a1b9c8d7e6f5a4b3c2d", "deleted": true }, "requestId": "req_..." }

รายการของ payer

GET /v1/payers/{id}/payments?status=succeeded

คืน pay-in และ payout ปนกัน เรียงจากใหม่ไปเก่า ให้ดูชนิดจากฟิลด์ object ("payin" หรือ "payout") รองรับตัวกรอง status, reference, createdFrom, createdTo, limit, cursor

ข้อผิดพลาดที่พบบ่อย

HTTP	code	ความหมาย
400	parameter_missing, parameter_invalid	ฟิลด์ขาดหรือผิดรูปแบบ เช่น เลขบัญชีมีตัวอักษรอื่นนอกจากตัวเลข ดู error.param
404	resource_not_found	ไม่พบ payer หรือไม่ใช่ของบัญชีคุณ
409	payer_has_payments	payer มีรายการแล้ว ลบไม่ได้
422	bank_not_found	bankCode ไม่อยู่ในรายการธนาคาร
422	referral_code_not_found, referrer_inactive	รหัสผู้แนะนำไม่ถูกต้องหรือผู้แนะนำถูกปิด
422	payer_blocked	บัญชีนี้ถูกระงับการใช้งาน