อาลีเพย์ (บาร์โค้ด)

ยกระดับโปรแกรมขายหน้าร้าน (ระบบ POS) ให้สามารถสแกนคิวอาร์โค้ดและเชื่อมต่อเข้ากับระบบของโอมิเซะ เพื่อรองรับการรับชำระเงินผ่านอาลีเพย์ด้วย Barcode wallet API

การเปิดรับชำระเงิน

• ประเทศที่รองรับ: ประเทศไทย
• API เวอร์ชันล่าสุดที่รองรับ: 2017-11-02

ร้านค้าที่ต้องการเปิดใช้ระบบ อาลีเพย์ (บาร์โค้ด) กรุณาส่งอีเมลมาที่ support@opn.ooo ทางทีมงานโอเพ่นจะส่งข้อกำหนดและเงื่อนไขการใช้บริการให้ร้านค้าได้พิจารณาและลงลายมือชื่อก่อนเปิดใช้งานจริง

ขั้นตอนการรับชำระเงิน

ภาพประกอบด้านล่างนี้ อธิบายถึงกระบวนการทำงานของระบบสำหรับการรับชำระเงินผ่านอาลีเพย์ โดยแสดงปฏิสัมพันธ์ที่เกิดขึ้นระหว่าง ผู้ซื้อ, ร้านค้า, โอมิเซะ และอาลีเพย์

ขั้นตอนการชำระเงิน

1. เมื่อต้องการชำระเงินผู้ซื้อจะเปิดแอปพลิเคชันอาลีเพย์
2. เลือกที่เมนู ชำระเงิน และระบบจะสร้างบาร์โค้ด เพื่อให้ผู้ซื้อแสดงต่อแคชเชียร์
3. แคชเชียร์จะทำการสแกนบาร์โค้ด
4. เซิร์ฟเวอร์ของร้านค้าจะสร้างรายการรับชำระเงิน โดยส่งคำสั่งไปที่ Charge API
5. ร้านค้าจะได้รับสถานะรายการตอบกลับ แสดงเป็น กำลังดำเนินการ
6. ในบางกรณี ผู้ซื้ออาจต้องยืนยันการทำรายการในแอปพลิเคชัน
7. เซิร์ฟเวอร์ของทางร้านค้าจะสามารถรับสถานะรายการล่าสุดของรายการโดยส่งคำสั่งไปยัง Charge API
8. สถานะรายการแสดงเป็น สำเร็จ หมายถึงรายการรับชำระเงินนั้นสำเร็จแล้ว และยอดชำระถูกส่งเข้าบัญชีโอมิเซะของทางร้านค้า
   
9. สถานะรายการแสดงเป็น ไม่สำเร็จ หมายถึงเกิดข้อขัดข้องอย่างใดอย่างหนึ่ง:
   
   1. รายการเกินเวลาที่กำหนด - หากยังคงต้องการรับชำระเงิน แจ้งผู้ซื้อให้สร้างบาร์โค้ดอีกครั้ง
   2. วงเงินไม่เพียงพอสำหรับทำรายการ - ผู้ซื้อจะต้องเพิ่มวงเงินในบัญชีอาลีเพย์ หรือเลือกชำระเงินผ่านช่องทางอื่นๆ
      

* ระบบจะมีการส่ง webhook (POST) ไปยังเซิร์ฟเวอร์ของร้านค้าเมื่อมีการอัพเดตสถานะรายการ (สถานะเป็น สำเร็จ หรือ ไม่สำเร็จ)

การเชื่อมต่อระบบ

สามารถสร้างรายการรับชำระเงินอาลีเพย์ (บาร์โค้ด) ด้วยการส่งคำสั่ง API ดังนี้

1. สร้างรายการรับชำระเงิน พร้อมทั้งระบุ parameter
2. เมื่อได้รับการแจ้งเตือนรายการสำเร็จผ่าน webhook ให้เรียกดูข้อมูลอีกครั้งเพื่อความแม่นยำ (แนะนำ)

ใช้งาน secret key ในการสร้างรายการอาลีเพย์ (บาร์โค้ด)

สร้างรายการรับชำระเงิน

เมื่อผู้ซื้อเลือกชำระเงินผ่านช่องทางนี้ ให้ร้านค้าสร้างรายการรับชำระเงิน พร้อมทั้งระบุ parameter amount, currency, source[type] (barcode_alipay), source[barcode], source[store_id], source[store_name], and source[terminal_id]

ตัวอย่างนี้ แสดงวิธีการสร้างรายการด้วย curl แทน $OMISE_SECRET_KEYด้วย test secret key ของร้านค้า สามารถไปคัดลอกจากแดชบอร์ด

curl https://api.omise.co/charges \
  -u $OMISE_SECRET_KEY: \
  -d "amount=400000" \
  -d "currency=THB" \
  -d "source[type]=barcode_alipay" \
  -d "source[barcode]=1234567890" \
  -d "source[store_id]=BJ_ZZ_001" \
  -d "source[store_name]=Some Store" \
  -d "source[terminal_id]=T80001"

{
  "object": "charge",
  "id": "chrg_test_611bht4c4nhbua89yi2",
  "location": "/charges/chrg_test_611bht4c4nhbua89yi2",
  "amount": 400000,
  "acquirer_reference_number": null,
  "net": 392938,
  "fee": 6600,
  "fee_vat": 462,
  "interest": 0,
  "interest_vat": 0,
  "funding_amount": 400000,
  "refunded_amount": 0,
  "transaction_fees": {
    "fee_flat": "0.0",
    "fee_rate": "1.65",
    "vat_rate": "7.0"
  },
  "platform_fee": {
    "fixed": null,
    "amount": null,
    "percentage": null
  },
  "currency": "THB",
  "funding_currency": "THB",
  "ip": null,
  "refunds": {
    "object": "list",
    "data": [],
    "limit": 20,
    "offset": 0,
    "total": 0,
    "location": "/charges/chrg_test_611bht4c4nhbua89yi2/refunds",
    "order": "chronological",
    "from": "1970-01-01T00:00:00Z",
    "to": "2024-09-10T03:55:14Z"
  },
  "link": null,
  "description": null,
  "metadata": {},
  "card": null,
  "source": {
    "object": "source",
    "id": "src_test_611bht3wsjtx99ja92o",
    "livemode": false,
    "location": "/sources/src_test_611bht3wsjtx99ja92o",
    "amount": 400000,
    "barcode": "1234567890",
    "bank": null,
    "created_at": "2024-09-10T03:55:13Z",
    "currency": "THB",
    "email": null,
    "flow": "offline",
    "installment_term": null,
    "ip": null,
    "absorption_type": null,
    "name": null,
    "mobile_number": null,
    "phone_number": null,
    "platform_type": null,
    "scannable_code": null,
    "billing": null,
    "shipping": null,
    "items": [],
    "references": {
      "expires_at": "2024-09-11T03:55:13Z",
      "device_id": null,
      "customer_amount": null,
      "customer_currency": null,
      "customer_exchange_rate": null,
      "omise_tax_id": null,
      "reference_number_1": null,
      "reference_number_2": null,
      "barcode": null,
      "payment_code": null,
      "va_code": null
    },
    "provider_references": null,
    "store_id": "BJ_ZZ_001",
    "store_name": "Some Store",
    "terminal_id": "T80001",
    "type": "barcode_alipay",
    "zero_interest_installments": null,
    "charge_status": "pending",
    "receipt_amount": null,
    "discounts": [],
    "promotion_code": null
  },
  "schedule": null,
  "linked_account": null,
  "customer": null,
  "dispute": null,
  "transaction": null,
  "failure_code": null,
  "failure_message": null,
  "status": "pending",
  "authorize_uri": null,
  "return_uri": null,
  "created_at": "2024-09-10T03:55:13Z",
  "paid_at": null,
  "authorized_at": null,
  "expires_at": "2024-09-11T03:55:13Z",
  "expired_at": null,
  "reversed_at": null,
  "zero_interest_installments": false,
  "branch": null,
  "terminal": null,
  "device": null,
  "authorized": false,
  "capturable": false,
  "capture": true,
  "disputable": false,
  "livemode": false,
  "refundable": false,
  "partially_refundable": false,
  "reversed": false,
  "reversible": false,
  "voided": false,
  "paid": false,
  "expired": false,
  "can_perform_void": false,
  "approval_code": null
}

Setting the charge to expire

Alipay In-Store charges that have not yet been authorized (status=pending) can be set to expire.

curl https://api.omise.co/charges/$CHARGE_ID/expire \
  -X POST \
  -u $OMISE_SECRET_KEY:

สร้างรายการสำเร็จ

เมื่อร้านค้าสร้างรายการรับชำระเงินขึ้นมาแล้ว จะพบว่าสถานะของรายการแสดงเป็น pending หรือ status==pending โดยสถานะของรายการรับชำระเงินสามารถเป็นได้ทั้ง successful, failed และ expired

ในส่วนต่อไปเราจะอธิบายวิธีอนุมัติรายการ, การรับ event แจ้งเตือนเมื่อรายการเสร็จสิ้นผ่าน webhook และการตรวจสอบสถานะรายการ

ภาพด้านล่างนี้แสดงให้เห็นถึงขั้นตอนทั้งหมดในการรับชำระเงินแต่ละรายการ

การอนุมัติรายการ

ในบางกรณี ผู้ซื้ออาจต้องเข้าแอปอาลีเพย์เพื่อยืนยันรายการชำระเงินด้วยตนเอง

การรับ event แจ้งเตือนรายการสำเร็จ

ร้านค้าสามารถรับการแจ้งเตือนเมื่อมีการทำรายการเสร็จสิ้นโดยใช้งาน webhook events

ในการติดตั้งให้ร้านค้ากำหนดตำแหน่งบนเซิร์ฟเวอร์เพื่อรับ webhook events และเพิ่มตำแหน่งเดียวกันนี้เป็น webhook endpoint บนแดชบอร์ด

เมื่อมีรายการเสร็จสิ้น ระบบจะส่ง POST request ไปยัง endpoint นี้ พร้อมทั้งแนบสถานะการตอบกลับของรายการนั้นๆ ไปด้วย

ตัวแปรหลักหรือ key สำหรับ event object ประกอบไปด้วย charge.complete และตัวแปร data ที่มี charge object

อ่านเพิ่มเติมได้ที่ Events API

การตรวจสอบสถานะรายการ

เมื่อได้รับ event ของรายการที่เสร็จสิ้นแล้ว ร้านค้าสามารถตรวจสอบสถานะรายการหรือ status โดยใช้ Charge API

หากค่าของ charge.status เป็น successful หมายถึงว่ารายการรับชำระเงินสำเร็จ หากค่าของ charge.status เป็น failed รายการรับชำระเงินนั้นไม่สำเร็จ ร้านค้าสามารถตรวจสอบ failure_code และ failure_message ได้ใน charge object เพื่ออ่านคำอธิบายเพิ่มเติม

สาเหตุขัดข้องที่อาจเกิดขึ้นได้มีดังนี้

การคืนเงิน

การคืนเงินสามารถทำได้ภายใน 12 เดือนนับจากวันทำรายการ โดยสามารถเลือกคืนเงินเต็มจำนวน หรือคืนเพียงบางส่วน

curl https://api.omise.co/charges/$REFUNDABLE_CHARGE_ID/refunds \
  -u $OMISE_SECRET_KEY: \
  -d "amount=400000"

{
  "object": "refund",
  "id": "rfnd_test_611bhtl3pd2rjcod9jt",
  "location": "/charges/chrg_test_611bhsvckygj3x8vypp/refunds/rfnd_test_611bhtl3pd2rjcod9jt",
  "livemode": false,
  "voided": true,
  "currency": "THB",
  "amount": 400000,
  "metadata": {},
  "charge": "chrg_test_611bhsvckygj3x8vypp",
  "terminal": null,
  "transaction": "trxn_test_611bhtlbmkxbqwdiib5",
  "status": "closed",
  "funding_amount": 400000,
  "funding_currency": "THB",
  "created_at": "2024-09-10T03:55:15Z",
  "acquirer_reference_number": null,
  "approval_code": null
}

ข้อจำกัด

• จำนวนรับชำระขั้นต่ำ: 2000 (THB20.00)
• จำนวนรับชำระสูงสุด: 15000000 (THB150,000.00)

ขั้นตอนต่อไป

• Charge API
• Source API
• Webhooks API