Recipients API
Recipients API ช่วยให้คุณจัดการบัญชีธนาคารปลายทางสำหรับการโอนเงิน Recipient แสดงถึงบัญชีธนาคารที่ได้รับการยืนยันซึ่งสามารถรับการจ่ายเงินจากยอดคงเหลือ Omise ของคุณ
ภาพรวม
Recipient ช่วยให้คุณสามารถ:
- จัดเก็บข้อมูลบัญชีธนาคาร อย่างปลอดภัยสำหรับการโอนเงินซ้ำ
- ยืนยันความเป็นเจ้าของบัญชี เพื่อป้องกันการฉ้อโ กงและข้อผิดพลาด
- จัดการผู้รับเงิน สำหรับผู้ขายในมาร์เก็ตเพลส ผู้จำหน่าย และพันธมิตร
- รองรับหลายธนาคาร ในประเทศต่างๆ
- ติดตาม metadata ของ Recipient สำหรับการจัดหมวดหมู่และรายงาน
ประเภทของ Recipient
Recipient บุคคลธรรมดา
บัญชีธนาคารส่วนบุคคลสำหรับบุคคลทั่วไป ต้องการ:
- ชื่อเต็ม (ตรงกับบัญชีธนาคาร)
- ข้อมูลบัญชีธนาคาร
- อีเมล (ไม่บังคับแต่แนะนำ)
Recipient นิติบุคคล
บัญชีธนาคารธุรกิจหรือนิติบุคคล ต้องการ:
- ชื่อบริษัท (ตรงกับบัญชีธนาคาร)
- เลขประจำตัวผู้เสียภาษีหรือเลขทะเบียนนิติบุคคล
- ข้อมูลบัญชีธนาคาร
- อีเมล
วงจรชีวิตของ Recipient
- สร้าง - เพิ่ม Recipient ใหม่พร้อมข้อมูลบัญชีธนาคาร
- ยืนยัน - ยืนยันความเป็นเจ้าของบัญชี (อัตโนมัติหรือด้วยตนเอง)
- ใช้งาน - Recipient สามารถรับการโอนเงินได้
- อัปเดต - แก้ไขรายละเอียดหรือ metadata ของ Recipient
- ลบ - ลบ Recipient (ไม่สามารถใช้สำหรับการโอนเงิน)
ข้อมูลบัญชีธนาคาร
Recipient ต้องการข้อมูลบัญชีธนาคาร:
- รหัสธนาคาร - รหัสธนาคาร (bbl, scb, kbank, ktb, bay เป็นต้น)
- เลขบัญชี - เลขบัญชีธนาคารเต็ม
- ชื่อบัญชี - ชื่อเจ้าของบัญชี (ต้องตรงกับบันทึกของธนาคาร)
- สาขา (ไม่บังคับ) - สาขาธนาคารสำหรับบางประเทศ
ธนาคารที่รองรับ (ประเทศไทย)
| รหัสธนาคาร | ชื่อธนาคาร |
|---|---|
| bbl | ธนาคารกรุงเทพ |
| kbank | ธนาคารกสิกรไทย |
| scb | ธนาคารไทยพาณิชย์ |
| ktb | ธนาคารกรุงไทย |
| bay | ธนาคารกรุงศรีอยุธยา |
| tmb | ธนาคารทหารไทย |
| citi | ซิตี้แบงก์ |
| smbc | ธนาคารซูมิโตโม มิตซุย แบงกิ้ง |
| sc | สแตนดาร์ดชาร์เตอร์ด |
กระบวนการยืนยัน
Recipient ต้องได้รับการยืนยันก่อนรับการโอนเงิน:
การยืนยันอัตโนมัติ
- Omise ยืนยันข้อมูลบัญชีกับธนาคาร
- โดยปกติเสร็จสิ้นภายในไม่กี่นาที
- สถานะ Recipient เปลี่ยนเป็น
verified: true
การยืนยันด้วยตนเอง
- สำหรับกรณีที่ซับซ้อนหรือประเภทธนาคารบางประเภท
- อาจต้องใช้เอกสารเพิ่มเติม
- ติดต่อฝ่ายสนับสนุนสำหรับการยืนยันด้วยตนเอง
สถานะการยืนยัน
verified: false- รอการยืนยันverified: true- ยืนยันแล้วและพร้อมสำหรับการโอนเงิน- การยืนยันล้มเหลวจะส่งผลให้เกิดข้อผิดพลาดระหว่างการสร้างการโอนเงิน
การยืนยันตัวตน
endpoint ทั้งหมดของ Recipient ต้องใช้ secret key สำหรับการยืนยันตัวตน อย่าเปิดเผย secret key ในโค้ดฝั่งไคลเอนต์
Endpoint ที่ใช้ได้
| เมธอด | Endpoint | คำอธิบาย |
|---|---|---|
| POST | /recipients | สร้าง Recipient ใหม่ |
| GET | /recipients/:id | ดึงข้อมูล Recipient เฉพาะ |
| GET | /recipients | แสดงรายการ Recipient ทั้งหมด |
| PATCH | /recipients/:id | อัปเดตรายละเอียด Recipient |
| DELETE | /recipients/:id | ลบ Recipient |
| PATCH | /recipients/:id/verify | ยืนยันบัญชี Recipient |
กรณีการใช้งานทั่วไป
การจ่ายเงินในมาร์เก็ตเพลส
สร้างบัญชี Recipient สำหรับผู้ขายแต่ละรายและประมวลผลการจ่ายเงินเป็นระยะตามยอดขาย
การจัดการผู้จำหน่าย
จัดเก็บบัญชีธนาคารของผู้จำหน่ายสำหรับการชำระเงินใบแจ้งหนี้และการคืนเงินค่าใช้จ่ายอัตโนมัติ
โปรแกรมพันธมิตร
จัดการบัญชีธนาคารของพันธมิตรสำหรับการจ่ายค่าคอมมิชชัน
การคืนเงินค่าใช้จ่ายพนักงาน
จัดเก็บบัญชีธนาคารของพนักงานสำหรับการคืนเงินค่าใช้จ่ายและการจ่ายเงินเดือน
การจ่ายเงินหลายสกุล
รองรับ Recipient ต่างประเทศที่มีสกุลเงินและระบบธนาคารที่แตกต่างกัน
แนวปฏิบัติที่ดี
- ยืนยัน Recipient ทันทีหลังสร้าง
- เก็บ Recipient ID ในฐานข้อมูลของคุณ
- ใช้ชื่อที่สื่อความหมาย เพื่อให้ระบุได้ง่าย
- เพิ่มอีเมล สำหรับการแจ้งเตือนและการยืนยัน
- ใช้ metadata สำหรับการจัดหมวดหมู่ (vendor_type, region เป็นต้น)
- จัดการความล้มเหลวในการยืนยัน อย่างเหมาะสม
- ทดสอบด้วยจำนวนเงินเล็กน้อย ก่อนการโอนเงินจำนวนมาก
- อัปเดตข้อมูล Recipient (แจ้งเตือนเมื่อข้อมูลธนาคารเปลี่ยนแปลง)
รหัสความ ล้มเหลวของ Recipient
เมื่อการสร้างหรือการยืนยัน Recipient ล้มเหลว แอตทริบิวต์ failure_code จะระบุเหตุผล:
| รหัส | ข้อความ | คำอธิบาย |
|---|---|---|
name_mismatch | "name mismatch" | ชื่อเจ้าของบัญชีไม่ตรงกับบันทึกของธนาคาร |
account_not_found | "account not found" | ไม่พบบัญชีธนาคาร |
bank_not_found | "bank not found" | รหัสธนาคารที่ระบุไม่ถูกต้อง |
invalid_bank_account | "invalid bank account" | ข้อมูลบัญชีธนาคารไม่ถูกต้อง |
invalid_recipient | "invalid recipient" | ข้อมูล Recipient ไม่ถูกต้อง |
verification_failed | "verification failed" | การยืนยันบัญชีล้มเหลว |
ข้อควรพิจารณาด้านความปลอดภัย
- PCI compliance - ข้อมูลบัญชีธนาคารถูกเข้ารหัสเมื่อจัดเก็บ
- การยืนยันบัญชี - ป้องกันการโอนเงินที่ฉ้อโกง
- การควบคุมการเข้าถึง - ใช้การยืนยันตัวตนด้วย secret key
- บันทึกการตรวจสอบ - ติดตามการแก้ไข Recipient ทั้งหมด
- การเก็บรักษาข้อมูล - สามารถลบ Recipient ได้เมื่อไม่จำเป็นแล้ว
แหล่งข้อมูลที่เกี่ยวข้อง
- Transfers API - ส่งเงินไปยัง Recipient
- Balance API - ตรวจสอบยอดคงเหลือที่ใช้ได้
- Transactions API - ดูธุรกรรมการโอนเงิน
- Webhooks - รับเหตุการณ์การยืนยัน Recipient
ต้องการความช่วยเหลือ? ติดต่อ support@omise.co สำหรับการยืนยันบัญชีธนาคาร ธนาคารที่รองรับ หรือความช่วยเหลือในการเชื่อมต่อ