อาลีเพย์ (หน้าร้าน)

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

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

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

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

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

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

Flow

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

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

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

การติดตั้งใช้งาน

การรับชำระเงินผ่าน อาลีเพย์ (หน้าร้าน) ฝั่งร้านค้าจะต้องมีการสร้างรายการโดยใช้ API requests 3 อย่างด้วยกัน

  1. การสร้าง payment source (type: barcode_alipay) โดยใช้ Omise.js, omise-ios หรือ omise-android
  2. การสร้าง charge โดยใช้ source จากขั้นตอนแรก
  3. เมื่อได้รับ webhook event กลับมาหลังจากทำรายการสำเร็จหรือ charge.complete แล้ว โอมิเซะแนะนำให้ตรวจสอบสถานะด้วยตนเองเพื่อความแม่นยำ

การสร้าง source เพื่อรับชำระผ่าน อาลีเพย์ (หน้าร้าน) จะเกิดขึ้นในฝั่งของผู้ซื้อ (Client-side) เช่น บนเว็บไซต์หรือโทรศัพท์มือถือของผู้ซื้อ โดยจะต้องใช้ public key

ส่วนการสร้างรายการหรือ charge เพื่อรับชำระผ่าน อาลีเพย์ (หน้าร้าน) จะเกิดขึ้นในฝั่งของร้านค้า (Server-side) โดยจะต้องใช้ secret key ทางโอมิเซะแนะนำให้ใช้ Omise.js หรือ ไลบรารี่ เพื่อติดตั้ง source ในฝั่งผู้ซื้อ (Client-side)

หมายเหตุ: หากมีความจำเป็นที่ต้องสร้างทั้งรายการและ source ในฝั่งร้านค้า (Server-side) สามารถใช้ Charge API ในการสร้างทั้งรายการและ source ได้ภายใต้ single API request (ไม่แนะนำ)

การสร้าง Source

การรับชำระเงินผ่านระบบ อาลีเพย์ (หน้าร้าน) ระจะต้องมีการสร้าง source ผ่าน source API เมื่อผู้ซื้อยืนยันรายการ ร้านค้าจะต้องสร้าง source โดยกำหนด type, amount, currency, barcode, store_id, store_name, และ terminal_id

ตัวอย่างด้านล่างนี้เป็นการสร้าง source สำหรับรายการ อาลีเพย์ (หน้าร้าน) ระจำนวน ฿4,000

ให้แทนค่าของ omise_public_key และ $OMISE_PUBLIC_KEY ด้วย test public key ของร้านค้าซึ่งสามารถคัดลอกได้จากแดชบอร์ด: https://dashboard.omise.co/test/keys

หากใช้ Omise.js parameter type เป็นตัวแปรที่จำเป็นของฟังก์ชัน createSource

Omise.setPublicKey(omise_public_key);

Omise.createSource('barcode_alipay', {
  "amount": 400000,
  "currency": "THB"
  "type": "barcode_alipay"
  "barcode": "1234567890"
  "store_id": "store_1234"
  "store_name": "Some Store"
  "terminal_id": "POS-01"
}, function(statusCode, response) {
  console.log(response)
});

ถ้าร้านค้าต้องการทดสอบ ให้สร้าง request โดยใช้ curl

curl https://api.omise.co/sources \
  -u $OMISE_PUBLIC_KEY: \
  -d "amount=400000" \
  -d "currency=THB" \
  -d "type=barcode_alipay" \
  -d "barcode=1234567890" \
  -d "store_id=store_1234" \
  -d "store_name=Some Store" \
  -d "terminal_id=POS-01"
{
  "object": "source",
  "id": "src_test_5il9facpqf8s8h0f99n",
  "livemode": false,
  "location": "/sources/src_test_5il9facpqf8s8h0f99n",
  "created_at": "2020-01-17T09:07:37Z",
  "type": "barcode_alipay",
  "flow": "offline",
  "amount": 400000,
  "currency": "THB",
  "mobile_number": null,
  "phone_number": null,
  "references": null,
  "name": null,
  "email": null,
  "barcode": "1234567890",
  "store_id": "store_1234",
  "store_name": "Some Store",
  "terminal_id": "POS-01",
  "installment_term": null,
  "zero_interest_installments": null,
  "scannable_code": null
}

ตัวแปรของ id คือ source identifier

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

สร้างรายการรับชำระเงินโดยระบุ parameter source, amount และ currency

  • source จะเป็นตัวกำหนด source identifier
  • amount และ currency จะต้องมีค่าตรงกับ amount และ currency ของ source

ตัวอย่างด้านล่างนี้จะแสดงการสร้างรายการโดยใช้ curl โดยให้แทน $OMISE_SECRET_KEY ด้วย test secret key ของร้านค้าซึ่งหาได้จากแดชบอร์ด และให้แทน $SOURCE_ID ด้วย id ของ source

curl https://api.omise.co/charges \
  -u $OMISE_SECRET_KEY: \
  -d "amount=400000" \
  -d "currency=THB" \
  -d "source=$SOURCE_ID"
{
  "object": "charge",
  "id": "chrg_test_5il9fafogj7nj4ifoyv",
  "livemode": false,
  "location": "/charges/chrg_test_5il9fafogj7nj4ifoyv",
  "created_at": "2020-01-17T09:07:37Z",
  "amount": 400000,
  "currency": "THB",
  "funding_amount": 400000,
  "funding_currency": "THB",
  "fee": 6600,
  "fee_vat": 462,
  "interest": 0,
  "interest_vat": 0,
  "net": 392938,
  "description": null,
  "metadata": {},
  "status": "pending",
  "capture": true,
  "authorized": false,
  "schedule": null,
  "reversed": false,
  "reversed_at": null,
  "expires_at": "2020-01-18T09:07:37Z",
  "expired": false,
  "expired_at": null,
  "voided": false,
  "paid": false,
  "paid_at": null,
  "transaction": null,
  "refunded_amount": 0,
  "refunds": {
    "object": "list",
    "from": "1970-01-01T00:00:00Z",
    "to": "2020-01-17T09:07:38Z",
    "offset": 0,
    "limit": 20,
    "total": 0,
    "order": "chronological",
    "location": "/charges/chrg_test_5il9fafogj7nj4ifoyv/refunds",
    "data": []
  },
  "link": null,
  "return_uri": null,
  "failure_code": null,
  "failure_message": null,
  "card": null,
  "customer": null,
  "ip": null,
  "dispute": null,
  "source": {
    "object": "source",
    "id": "src_test_5il9fa4kb60obwcoeo6",
    "livemode": false,
    "location": "/sources/src_test_5il9fa4kb60obwcoeo6",
    "created_at": "2020-01-17T09:07:36Z",
    "type": "barcode_alipay",
    "flow": "offline",
    "amount": 400000,
    "currency": "THB",
    "mobile_number": null,
    "phone_number": null,
    "references": {
      "expires_at": "2020-01-18T09:07:37Z",
      "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
    },
    "name": null,
    "email": null,
    "barcode": "1234567890",
    "store_id": "store_1234",
    "store_name": "Some Store",
    "terminal_id": "POS-01",
    "installment_term": null,
    "zero_interest_installments": null,
    "scannable_code": null
  },
  "platform_fee": {
    "percentage": null,
    "fixed": null,
    "amount": null
  },
  "disputable": false,
  "capturable": false,
  "reversible": false,
  "refundable": false,
  "zero_interest_installments": true,
  "authorize_uri": 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:

การสร้าง source และ charge

ร้านค้าสามารถสร้างทั้ง source และ charge ผ่านการเรียกใช้ API เพียงครั้งเดียว

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]=store_1234" \
  -d "source[store_name]=Some Store" \
  -d "source[terminal_id]=POS-01"

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

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

สถานะของรายการรับชำระเงินสามารถเป็นได้ทั้ง successful, failed และ expired

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

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

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

การรับ 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 เพื่ออ่านคำอธิบายเพิ่มเติม

สาเหตุขัดข้องดูได้ที่ตารางด้านล่างนี้

รหัสข้อขัดข้อง รายละเอียด
payment_cancelled ผู้ซื้อยกเลิกการชำระเงิน
failed_processing ระบบทำรายการไม่สำเร็จ
insufficient_balance วงเงินคงเหลือไม่เพียงพอหรือวงเงินเต็ม
payment_rejected รายการถูกปฏิเสธโดยธนาคารผู้ออกบัตร
timeout ผู้ซื้อไม่ยืนยันการทำรายการภายในเวลาที่กำหนด

การคืนเงิน

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

ข้อจำกัด

  • รายการชำระขั้นต่ำ: 2000 (THB20.00)
  • รายการชำระสูงสุด: 100000000 (THB1,000,000.00)

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