ยกเลิกรายการฝาก

POST /v1/pay/deposits/{id}/cancel เป็น Merchant API ของเรา ใช้คีย์ที่มี scope deposits:write, HMAC และ Idempotency-Key ตาม Authentication

ขอบเขต D06 ที่รองรับ

LIVE รองรับเฉพาะรายการ THB ของ Merchant เองที่ยังเป็น awaiting_liquidity และไม่เคยมีคำสั่งหรือปลายทางให้โอน ส่วน TEST ใช้รายการจำลอง awaiting_payment ในรอบปัจจุบัน การมี source เพียงอย่างเดียวไม่ยืนยันว่า deployment เปิด profile นี้แล้ว ให้ตรวจหลักฐานของ deployment ที่ใช้งาน

ยกเลิกได้เมื่อไหร่

รายการ	ผล
LIVE awaiting_liquidity ที่ไม่เคยออกคำสั่งโอน	ยกเลิกได้เมื่อผ่านการตรวจทั้งหมด
LIVE awaiting_payment หรือเคยแสดงบัญชี/QR	409 deposit_not_cancelable แม้ยังไม่มีสลิป
เคยมี allocation, reservation, destination, external route หรือ prepared external intent	409 deposit_not_cancelable รวมประวัติที่ไม่ active แล้ว
เคยรับสลิป หลักฐาน หรือใช้หลักฐานกับรายการ	409 deposit_not_cancelable
settled / expired / canceled / rejected / reversed หรือสถานะตรวจสลิป	คำสั่งใหม่ได้ 409 deposit_not_cancelable
TEST pending ของรอบเก่า	409 sandbox_transaction_archived

อย่าใช้การไม่มีสลิปเป็นเงื่อนไขเดียว ระบบตรวจประวัติแหล่งที่มาใน transaction เดียวกับ การยกเลิก รวมถึง original CREATE 202 receipt จริงของ awaiting_liquidity ที่ยังไม่มีคำสั่งโอนและ legs ว่าง และหยุด cascade โดยเปลี่ยน generation พร้อมล้าง claim/lease ของงานนั้น ไม่ปลด reservation หรือยกเลิกเส้นทางที่ออกคำสั่งไปแล้วเพื่อบังคับให้รายการยกเลิกได้

Request

Body ต้องมีเพียง reason เท่านั้น:

{ "reason": "ลูกค้าขอเปลี่ยนยอดก่อนมีคำสั่งโอน" }

• reason ยาว 1–500 Unicode codepoints ไม่ใช่ช่องว่างล้วน ไม่มี C0/C1 หรือ lone surrogate
• Body จำกัด 8 KiB และไม่รองรับ query parameters
• Idempotency-Key เป็น visible ASCII 8–200 ตัว ไม่มีช่องว่าง ใช้ key และ raw body เดิมเมื่อ retry
• ลงลายเซ็นจาก raw bytes จริง ระบบไม่ trim หรือจัด JSON ใหม่ก่อนตรวจ HMAC
• ใช้ timestamp/nonce/signature ใหม่ในการ retry ห้ามเปลี่ยน body ใต้ key เดิม
• เก็บ request/reason digest สำหรับตรวจสอบ ไม่เก็บข้อความเหตุผลให้ support อ่าน

ขอบเขตเวลาโดยรวม 4.5 วินาที ผลลัพธ์คลุมเครือจาก network ให้ retry คำสั่งเดิม อย่าสร้าง key ใหม่เพื่อเดาว่าคำสั่งก่อนหน้าล้มเหลว

Response 200

{
  "id": "dep_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "object": "deposit_order",
  "version": 2,
  "status": "canceled",
  "livemode": true,
  "merchant_reference": "ORDER-108",
  "end_user_ref": "customer-reference",
  "amount_minor": 50000,
  "currency": "THB",
  "created_at": "2026-10-18T08:00:00.000Z",
  "updated_at": "2026-10-18T08:01:00.000Z",
  "expires_at": "2026-10-18T08:30:00.000Z",
  "metadata": {},
  "legs": [],
  "canceled_by": "merchant",
  "cancel_reason_code": "merchant_request",
  "is_terminal": true,
  "late_slip_accepted_until": null
}

sender_id ที่เป็น public alias และ return_url อาจคงอยู่จากรายการเดิม ไม่มี canceled_at, payment instructions, upload capability, settlement fee หรือ balance transaction ที่สร้างขึ้นเพื่อคำสั่งนี้

ยกเลิกสำเร็จครั้งเดียว: บันทึก D06 transition, immutable source, deposit.canceled callback payload และ receipt ใน transaction เดียวกัน การส่งไป endpoint ที่ตั้งค่าไว้ใช้ signing scheduler เดิม ไม่มี journal หรือการเครดิต/คืนเงิน เพราะยังไม่มีเงินเข้ารายการ Current GET อ่าน canceled snapshot ส่วน replay ของ CREATE เดิมยังเป็นผล CREATE เดิม ไม่เปลี่ยน receipt เก่าให้เป็น canceled signed LIVE event มีเพียง id, object, type, api_version, livemode, created_at และ data รวมเจ็ด field ส่วน polling อ่าน immutable transition source เดียวกัน ไม่สร้าง event ใหม่จากสถานะรายการในภายหลัง

Idempotency และสิทธิ์

Exact replay ที่ยังมีสิทธิ์คืน 200 และ Idempotent-Replay: true โดยไม่สร้าง transition/event ซ้ำ เปลี่ยน raw body ใต้ key เดิมได้ 409 idempotency_key_reused คีย์หมดอายุ ถูกเพิกถอน หรือ Merchant/ancestor ถูกระงับจะไม่ได้ผลสำเร็จเดิม ระบบตรวจสิทธิ์ปัจจุบันอีกครั้งหลังการรอ lock และก่อน replay

คำสั่งใหม่สำหรับรายการ terminal ได้ 409; unknown/foreign order ได้ 404 JSON ผิดรูปได้ 400 malformed_json; body ที่เป็น JSON ถูกต้องแต่ไม่ผ่าน reason-only contract ได้ 422 validation_error ส่วน body เกินขนาดได้ 400 invalid_request และ quota ได้ 429 เมื่อระบบไม่พร้อมหรือเกิน deadline ได้ 503 service_unavailable หากผลคลุมเครือให้ retry คำสั่งเดิม ไม่มี balance.credited จากคำสั่งนี้

TEST / Sandbox

ใช้โฮสต์และ sk_test ของ Sandbox เท่านั้น ยกเลิกได้เฉพาะ own pending deposit ของ active run โดยคง fee/run snapshot และ original CREATE receipt ผลเป็น canceled / sandbox.outcome: cancel และ signed deposit.canceled ไม่มีเงินจริง ไม่มีการเปลี่ยนยอด wallet หรือสร้างแถวคืนเงินจำลอง

หลัง reset คำสั่งใหม่กับ archive เป็น 409 ส่วน retained exact cancel replay ยังคืน receipt เดิมก่อน quota/cleanup ไม่มี magic amount หรือตัวเลือก simulate ใหม่ อัปเกรด SDK และ refresh UI ที่รองรับ canceled deposit/event ก่อนเริ่มใช้ ดู Sandbox และ Webhooks