บิลเพย์เมนต์

ช่องทางบิลเพย์เมนต์จะช่วยให้ผู้ซื้อสามารถชำระค่าสินค้าและบริการด้วยเงินสด โดยการนำบาร์โค้ดที่ได้รับจากร้านค้าไปแสดงที่หน้าเคาน์เตอร์บริการ

ปัจจุบันผู้ซื้อสามารถนำบาร์โค้ดไปสแกนจ่ายได้ที่เคาน์เตอร์บริการของเทสโก้โลตัสกว่า 1,800 สาขาทั่วประเทศ และกำลังขยายให้มีเคาน์เตอร์บริการอื่นเพิ่มเติมเร็วๆ นี้

* เทสโก้โลตัสมีการคิดค่าธรรมเนียมการชำระเงินรายการละ 10 บาท

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

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

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

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

เมื่อผู้ซื้อมาถึงขั้นตอนการชำระเงินหลังจากใส่รายละเอียดในการจัดส่งและยืนยันรายการสินค้าเรียบร้อยแล้ว ขั้นตอนต่อไปผู้ซื้อจะทำการเลือกวิธีการชำระด้วย Tesco Lotus ดังรูปต่อไปนี้

Bill payment flow

ระบบจะทำการสร้างบาร์โค้ดเพื่อให้ผู้ซื้อนำไปสแกนชำระเงินที่หน้าเคาน์เตอร์บริการของเทสโก้ โลตัส บาร์โค้ดจะหมดอายุใน 24 ชั่วโมง

Bill payment flow 2

บาร์โค้ดที่แสดงต่อเจ้าหน้าที่ ณ เคาน์เตอร์ชำระเงินจะต้องมีความสูงไม่น้อยกว่า 1 เซนติเมตร

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

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

  1. การสร้าง payment source (type: bill_payment_tesco_lotus) โดยใช้ 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

ตัวอย่างด้านล่างนี้เป็นการสร้าง 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('bill_payment_tesco_lotus', {
  "amount": 400000,
  "currency": "THB"
}, 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=bill_payment_tesco_lotus"
{
  "object": "source",
  "id": "src_test_5irtsr1ejgp5x6t6cat",
  "livemode": false,
  "location": "/sources/src_test_5irtsr1ejgp5x6t6cat",
  "created_at": "2020-02-03T04:00:56Z",
  "type": "bill_payment_tesco_lotus",
  "flow": "offline",
  "amount": 400000,
  "currency": "THB",
  "mobile_number": null,
  "phone_number": null,
  "references": null,
  "name": null,
  "email": null,
  "barcode": null,
  "store_id": null,
  "store_name": null,
  "terminal_id": null,
  "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_5irtsr3v9x41t4b75cb",
  "livemode": false,
  "location": "/charges/chrg_test_5irtsr3v9x41t4b75cb",
  "created_at": "2020-02-03T04:00:56Z",
  "amount": 400000,
  "currency": "THB",
  "funding_amount": 400000,
  "funding_currency": "THB",
  "fee": 14600,
  "fee_vat": 1022,
  "interest": 0,
  "interest_vat": 0,
  "net": 384378,
  "description": null,
  "metadata": {},
  "status": "pending",
  "capture": true,
  "authorized": false,
  "schedule": null,
  "reversed": false,
  "reversed_at": null,
  "expires_at": "2020-02-04T04:00:56Z",
  "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-02-03T04:00:57Z",
    "offset": 0,
    "limit": 20,
    "total": 0,
    "order": "chronological",
    "location": "/charges/chrg_test_5irtsr3v9x41t4b75cb/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_5irtsqs5yk3ao2yvlpc",
    "livemode": false,
    "location": "/sources/src_test_5irtsqs5yk3ao2yvlpc",
    "created_at": "2020-02-03T04:00:55Z",
    "type": "bill_payment_tesco_lotus",
    "flow": "offline",
    "amount": 400000,
    "currency": "THB",
    "mobile_number": null,
    "phone_number": null,
    "references": {
      "expires_at": "2020-02-04T04:00:56Z",
      "device_id": null,
      "customer_amount": null,
      "customer_currency": null,
      "customer_exchange_rate": null,
      "omise_tax_id": "0105556091152",
      "reference_number_1": "247271784612135827",
      "reference_number_2": "708986646893499029",
      "barcode": "https://api.omise.co/charges/chrg_test_5irtsr3v9x41t4b75cb/documents/docu_test_5irtsr55sqqd5x3ppk6/downloads/CD35CC446DAB630D",
      "payment_code": null,
      "va_code": null
    },
    "name": null,
    "email": null,
    "barcode": null,
    "store_id": null,
    "store_name": null,
    "terminal_id": null,
    "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
}

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

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

curl https://api.omise.co/charges \
  -u $OMISE_SECRET_KEY: \
  -d "amount=400000" \
  -d "currency=THB" \
  -d "source[type]=bill_payment_tesco_lotus"

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

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

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

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

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

sequenceDiagram participant customer participant omise.js participant merchant participant api.omise.co participant offline provider customer->>omise.js: Send payment details for purchase omise.js->>api.omise.co: Request source using payment details api.omise.co-->>omise.js: Return source omise.js->>merchant: Merchant gets returned source merchant->>api.omise.co: Request charge using source and purchase details api.omise.co-xmerchant: Send "charge.create" webhook api.omise.co-->>merchant: Return charge customer->>offline provider: Provide payment or charge authorization at offline provider offline provider-->>api.omise.co: Return result of payment or charge authorization api.omise.co-xmerchant: Send "charge.complete" webhook merchant-xcustomer: Send charge result (e.g. via email)

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

ผู้ซื้อจะต้องแสดงบาร์โค้ดที่ถูกสร้างขึ้นให้กับเคาน์เตอร์ เทสโก้โลตัส เพื่ออนุมัติรายการ

{
  "expires_at": "2020-02-04T04:00:55Z",
  "device_id": null,
  "customer_amount": null,
  "customer_currency": null,
  "customer_exchange_rate": null,
  "omise_tax_id": "0105556091152",
  "reference_number_1": "757099754445710108",
  "reference_number_2": "282972983487871361",
  "barcode": "https://api.omise.co/charges/chrg_test_5irtsqv1znnzklv5ii0/documents/docu_test_5irtsqw86soml7amxi8/downloads/042C8177481D4820",
  "payment_code": null,
  "va_code": null
}

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

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

รหัสข้อขัดข้อง รายละเอียด
timeout ผู้ซื้อไม่ยืนยันการทำรายการภายในเวลาที่กำหนด

การยกเลิกรายการและการคืนเงิน

รายการที่ชำระผ่านบิลเพย์เมนต์ยังไม่สามารถทำการยกเลิกรายการหรือการคืนเงินได้ผ่านโอมิเซะ กรุณาติดต่อเทสโก้โลตัสโดยตรง

ข้อจำกัด

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

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