Payouts (จ่ายเงิน)

payout คือการโอนเงินจากยอดคงเหลือของคุณไปยังบัญชีธนาคาร (หรือ wallet) ของ payer เช่น การถอนเงินของลูกค้าในระบบของคุณ

Method	Path	ใช้ทำอะไร
POST	/v1/payouts	สร้าง payout
GET	/v1/payouts/{id}	ดู payout
GET	/v1/payouts	ค้นหารายการ (พารามิเตอร์เดียวกับการค้นหา pay-in)
POST	/v1/payouts/{id}/cancel	ยกเลิก payout

สร้าง payout

POST /v1/payouts

ฟิลด์	จำเป็น	คำอธิบาย
payer	ส่ง payer หรือ payerId อย่างใดอย่างหนึ่ง	บัญชีธนาคารของผู้รับเงิน: bankCode, accountNumber, accountName และ accountNameEn (ไม่บังคับ) ถ้ามี payer ที่บัญชีตรงกันอยู่แล้วจะใช้ payer เดิม ไม่เช่นนั้นจะสร้างใหม่ ดูส่ง payer แบบ inline
payerId	ส่ง payer หรือ payerId อย่างใดอย่างหนึ่ง	payer_... ของผู้รับเงินที่มีอยู่แล้ว บัญชีปลายทางคือบัญชีธนาคารของ payer คนนี้
amount	ใช่	สตริงทศนิยม ต้องอยู่ในช่วง payoutMinimum-payoutMaximum ของบัญชีคุณ
currency	ใช่	THB, USD, USDT หรือ LAK
method	ไม่	auto (ค่าเริ่มต้น), bank_transfer, crypto, lao_qr
reference	ไม่	เลขอ้างอิงของคุณ ไม่เกิน 128 ตัว
webhookUrl	ไม่	URL ที่จะรับ webhook ถ้าไม่ใส่จะไม่มี webhook ของรายการนี้ ต้องตรวจสถานะเอง
walletAddress	เฉพาะ crypto	ที่อยู่ wallet ปลายทาง จำเป็นเมื่อ method เป็น crypto หรือ currency เป็น USDT
network	ไม่	เครือข่ายของ wallet เช่น BSC

{
  "payer": {
    "bankCode": "SCB",
    "accountNumber": "1234567890",
    "accountName": "สมชาย สบายดี"
  },
  "amount": "500.00",
  "currency": "THB",
  "reference": "withdraw-20001",
  "webhookUrl": "https://shop.example.com/webhooks/payments"
}

หรือส่ง "payerId": "payer_..." แทน payer สำหรับ payer ที่มีอยู่แล้ว

สิ่งที่ควรรู้

• ส่ง payerId หรือ payer อย่างใดอย่างหนึ่งเท่านั้น (ส่งทั้งคู่: 400 parameters_exclusive ไม่ส่งเลย: 400 parameter_missing) payer แบบ inline ทำงานเหมือนใน pay-in ทุกอย่าง คือถ้ามี payer ที่ bankCode และ accountNumber ตรงกันจะใช้ payer เดิมโดยไม่เปลี่ยนชื่อที่บันทึกไว้ (ถ้าชื่อต่างกัน response จะมีคำเตือน payer_name_differs) ไม่เช่นนั้นจะสร้าง payer ใหม่โดยตรวจสอบเหมือน POST /v1/payers เงินจะโอนเข้าบัญชีที่บันทึกไว้ของ payer ที่ใช้
• ยอดคงเหลือที่ใช้ได้ (balance.available จาก GET /v1/account) ต้องพอ ไม่เช่นนั้นได้ 422 insufficient_balance
• payer หนึ่งคนมี payout ที่ยังไม่จบได้ครั้งละหนึ่งรายการ ไม่เช่นนั้นได้ 409 pending_payout_exists
• ส่ง header Idempotency-Key เพื่อให้การส่งซ้ำหลัง timeout ไม่สร้าง payout ซ้ำ ดูส่งคำขอสร้างรายการซ้ำอย่างปลอดภัย
• payout ที่ยอดเกินเกณฑ์อนุมัติอัตโนมัติของบัญชีจะอยู่ในสถานะ in_review รอเจ้าหน้าที่ตรวจ เมื่ออนุมัติจะกลับเป็น pending (มี webhook payout.pending) และดำเนินการต่อ ถ้าไม่อนุมัติจะถูกยกเลิก

Object ของ payout

ฟิลด์เหมือน pay-in ยกเว้นไม่มี returnUrl, checkoutUrl, paymentImage และ payTo และ payerAccount คือบัญชีปลายทางที่รับเงิน

{
  "object": "payout",
  "id": "pout_0f1e2d3c4b5a69788796a5b4c3d2e1f0",
  "reference": "withdraw-20001",
  "payerId": "payer_7c0a4b8e2f3d4a1b9c8d7e6f5a4b3c2d",
  "payer": { "object": "payer", "id": "payer_7c0a4b8e2f3d4a1b9c8d7e6f5a4b3c2d", "...": "..." },
  "requestedAmount": "500.00",
  "amount": "500.00",
  "fee": "5.00",
  "currency": "THB",
  "method": "bank_transfer",
  "status": "processing",
  "failureReason": null,
  "webhookUrl": "https://shop.example.com/webhooks/payments",
  "payerAccount": {
    "bankCode": "SCB",
    "accountNumber": "1234567890",
    "accountName": "สมชาย สบายดี"
  },
  "createdAt": "2026-01-01T01:00:00.000Z",
  "updatedAt": "2026-01-01T01:00:05.000Z"
}

สถานะ

สถานะ	ความหมาย	สิ้นสุดหรือยัง
pending	สร้างแล้ว รอดำเนินการ	ยัง
processing	อยู่ในคิวหรือส่งให้ธนาคารแล้ว	ยัง
in_review	ยอดเกินเกณฑ์อัตโนมัติ รอเจ้าหน้าที่ตรวจ	ยัง
succeeded	โอนสำเร็จ	สิ้นสุด
canceled	ถูกยกเลิกโดยคุณ เจ้าหน้าที่ หรือระบบ	สิ้นสุด
rejected	ถูกปฏิเสธ	สิ้นสุด
failed	โอนไม่สำเร็จ ดู failureReason คุณยกเลิกได้ หรือทีมงานอาจส่งใหม่	ยังไม่แน่นอน

ยกเลิก payout

POST /v1/payouts/{id}/cancel

ไม่มี body ยกเลิกได้เมื่อรายการ

• pending หรือ failed
• processing ที่ยังอยู่ในคิว
• processing ที่ส่งให้ธนาคารแล้ว และสร้างมานานกว่า 30 นาที

ถ้าสำเร็จจะคืน object ที่สถานะ canceled ถ้าธนาคารปฏิเสธการยกเลิก หรือรายการเปลี่ยนสถานะไปก่อน จะได้ 409 payout_not_cancelable การยกเลิกผ่าน API ไม่ส่ง webhook

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

HTTP	code	ความหมายและสิ่งที่ควรทำ
400	parameter_missing (param: walletAddress)	payout แบบ crypto หรือ USDT ต้องมี walletAddress
400	parameter_missing, parameter_invalid	ไม่ได้ส่งทั้ง payerId และ payer หรือฟิลด์ใน payer รูปแบบผิด ดู error.param
400	parameters_exclusive	ส่งทั้ง payerId และ payer มา
400	unsupported_currency, unsupported_method	สกุลเงินหรือช่องทางที่ไม่รองรับ
403	payouts_disabled	บัญชีของคุณปิดการจ่ายเงินอยู่
404	payer_not_found	payerId ไม่มีอยู่หรือไม่ใช่ของบัญชีคุณ
422	bank_not_found	payer.bankCode ไม่ใช่รหัสจาก GET /v1/banks
409	pending_payout_exists	payer มี payout ที่ยังไม่จบอยู่แล้ว
409	payout_not_cancelable	สถานะปัจจุบันยกเลิกไม่ได้
422	insufficient_balance	ยอดคงเหลือไม่พอ
422	amount_below_minimum, amount_above_maximum	ยอดนอกช่วงที่บัญชีกำหนด
422	amount_below_fee	ยอดต่ำกว่าค่าธรรมเนียม
422	payer_inactive, payer_blocked	payer ถูกปิดหรือถูกระงับ
422	no_payout_account_available	ขณะนี้ไม่มีบัญชีจ่ายเงินว่าง ลองใหม่ภายหลัง
422	not_available_now, maintenance	อยู่นอกเวลาให้บริการหรือปิดปรับปรุง

รายการรหัสทั้งหมดดูที่รหัสข้อผิดพลาด