Merchant-Presented Mode (C scan B)

หัวข้อทั้งหมดในหน้านี้

คุณสามารถรับชำระเงินหน้าร้านจากผู้ใช้อาลีเพย์พลัส โดยแสดงโค้ดชำระเงินผ่านโปรแกรมขายหน้าร้าน (ระบบ POS) เพื่อให้ผู้ใช้สแกนชำระเงิน หรือที่เรียกว่าแบบ C scan B (Consumer-scan-Business)

ในคู่มือนี้จะอธิบายขั้นตอนการชำระเงิน และรายละเอียดวิธีการติดตั้งเพื่อใช้งาน

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

  • ประเทศที่รองรับ: ประเทศไทย, สิงคโปร์, มาเลเซีย
  • API เวอร์ชันล่าสุดที่รองรับ: 2017-11-02
วอลเล็ทที่รองรับ ประเทศไทย สิงคโปร์ มาเลเซีย
Alipay CN ✅ ✅
Alipay HK ✅ ✅ ✅
KakaoPay ✅ ✅ ✅
GCash ✅ ✅
Touch 'n Go ✅ ✅
TrueMoney ✅ ✅

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

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

เมื่อผู้ซื้อที่เลือกชำระเงินผ่าน Merchant-Presented Mode (C scan B) แสดงว่าจะต้องดำเนินขั้นตอนการชำระเงินผ่านช่องทางออฟไลน์ ซึ่งรายการรับชำระเงินที่ถูกสร้างขึ้น จะได้รับการอนุมัติผ่านทางออฟไลน์เท่านั้น และในกรณีดังกล่าวให้ผู้ซื้อสแกนคิวอาร์โค้ดผ่านแอปพลิเคชันของวอลเล็ทบนโทรศัพท์มือถือ เพื่อยืนยันการชำระเงินตามขั้นตอน

หลังจากที่ผู้ซื้อเลือกชำระเงินผ่าน Merchant-Presented Mode (C scan B) แล้ว ร้านค้าควรใช้เครื่อง POS (ระบบขายหน้าร้าน) สร้างคิวอาร์โค้ดขึ้นมาเพื่อรับชำระเงิน

payment flow

❶ ผู้ซื้อเปิดแอปพลิเคชันของวอลเล็ทที่รองรับ ❷ จากนั้นทำการสแกนคิวอาร์โค้ดที่ร้านค้าแสดงบน POS ❸ ผู้ซื้อตรวจสอบรายการ ❹ ผู้ซื้อยืนยันคำสั่งซื้อ ❺ เมื่อคำสั่งซื้อสำเร็จ ผู้ซื้อจะได้รับการยีนยันผ่านแอปพลิเคชันของวอลเล็ท

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

ในการสร้างรายการรับชำระเงินผ่านMerchant-Presented Mode (C scan B) ให้ร้านค้าส่งคำสั่ง API ดังนี้

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

การสร้าง source เพื่อรับชำระเงินผ่านMerchant-Presented Mode (C scan B) จะเกิดขึ้นในฝั่งของผู้ซื้อ (client-side) เช่นบนเว็บไซต์หรือโทรศัพท์มือถือของผู้ซื้อ ร้านค้าจะต้องใช้ public key

ส่วนการสร้างรายการ (charge) เพื่อรับชำระเงินผ่านMerchant-Presented Mode (C scan B) จะเกิดขึ้นในฝั่งของร้านค้า (server-side) ร้านค้าจะต้องใช้ secret key

หมายเหตุ: หากมีความจำต้องสร้างทั้งรายการและ source ในฝั่งร้านค้า (server-side) สามารถทำพร้อมกันได้เลยโดยการส่งคำสั่ง API เพียงครั้งเดียว และใช้งาน secret key

การสร้าง source


เมื่อผู้ซื้อเลือกชำระเงินผ่านช่องทางนี้ ให้ร้านค้าสร้าง source ผ่าน source API โดยกำหนด amount, currency, และ type


Parameter Type Description
amount integer (required) จำนวนเงิน
currency string (required) สกุลเงินตาม ISO 4217 (THB สำหรับประเทศไทย, SGD สำหรับสิงคโปร์, MYR สำหรับมาเลเซีย)
type string (required) alipayplus_mpm

ตัวอย่างด้านล่างนี้เป็นการสร้าง source สำหรับรายการ Merchant-Presented Mode (C scan B) จำนวน ฿1500 ให้แทนค่าของ omise_public_key และ $OMISE_PUBLIC_KEY ด้วย test public key ของร้านค้าซึ่งสามารถคัดลอกได้จาก แดชบอร์ด

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

Omise.setPublicKey(omise_public_key);

Omise.createSource('alipayplus_mpm', {
  "amount": 150000,
  "currency": "THB"
}, function(statusCode, response) {
  console.log(response)
});

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

curl https://api.omise.co/sources \
  -u $OMISE_PUBLIC_KEY: \
  -d "amount=150000" \
  -d "currency=THB" \
  -d "type=alipayplus_mpm"

{
  "object": "source",
  "id": "src_test_611biko734mtiic5iu5",
  "livemode": false,
  "location": "/sources/src_test_611biko734mtiic5iu5",
  "amount": 150000,
  "barcode": null,
  "bank": null,
  "created_at": "2024-09-10T03:57:23Z",
  "currency": "THB",
  "email": null,
  "flow": "offline",
  "installment_term": null,
  "ip": "35.198.236.178",
  "absorption_type": null,
  "name": null,
  "mobile_number": null,
  "phone_number": null,
  "platform_type": null,
  "scannable_code": null,
  "billing": null,
  "shipping": null,
  "items": [],
  "references": null,
  "provider_references": null,
  "store_id": null,
  "store_name": null,
  "terminal_id": null,
  "type": "alipayplus_mpm",
  "zero_interest_installments": null,
  "charge_status": "unknown",
  "receipt_amount": null,
  "discounts": [],
  "promotion_code": null
}

ตัวแปรของ id คือ source identifier (เริ่มต้นด้วย src)

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

สร้างรายการรับชำระเงินโดยระบุ 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=150000" \
  -d "currency=THB" \
  -d "source=$SOURCE_ID"

{
  "object": "charge",
  "id": "chrg_test_611bikr8vyiylwxpjk4",
  "location": "/charges/chrg_test_611bikr8vyiylwxpjk4",
  "amount": 150000,
  "acquirer_reference_number": null,
  "net": 147352,
  "fee": 2475,
  "fee_vat": 173,
  "interest": 0,
  "interest_vat": 0,
  "funding_amount": 150000,
  "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_611bikr8vyiylwxpjk4/refunds",
    "order": "chronological",
    "from": "1970-01-01T00:00:00Z",
    "to": "2024-09-10T03:57:24Z"
  },
  "link": null,
  "description": null,
  "metadata": {},
  "card": null,
  "source": {
    "object": "source",
    "id": "src_test_611bik9nzzlq0zb943d",
    "livemode": false,
    "location": "/sources/src_test_611bik9nzzlq0zb943d",
    "amount": 150000,
    "barcode": null,
    "bank": null,
    "created_at": "2024-09-10T03:57:22Z",
    "currency": "THB",
    "email": null,
    "flow": "offline",
    "installment_term": null,
    "ip": "35.198.236.178",
    "absorption_type": null,
    "name": null,
    "mobile_number": null,
    "phone_number": null,
    "platform_type": null,
    "scannable_code": {
      "object": "barcode",
      "type": "qr",
      "image": {
        "object": "document",
        "livemode": false,
        "id": "docu_test_611bikst9lvqz47s247",
        "deleted": false,
        "filename": "qrcode.svg",
        "location": "/charges/chrg_test_611bikr8vyiylwxpjk4/documents/docu_test_611bikst9lvqz47s247",
        "kind": "qr",
        "download_uri": "https://api.omise.co/charges/chrg_test_611bikr8vyiylwxpjk4/documents/docu_test_611bikst9lvqz47s247/downloads/AB9B72DACA9ECCB4",
        "created_at": "2024-09-10T03:57:24Z"
      }
    },
    "billing": null,
    "shipping": null,
    "items": [],
    "references": null,
    "provider_references": null,
    "store_id": null,
    "store_name": null,
    "terminal_id": null,
    "type": "alipayplus_mpm",
    "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:57:24Z",
  "paid_at": null,
  "authorized_at": null,
  "expires_at": "2024-09-11T03:57:24Z",
  "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
}

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

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

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

การตั้งค่ารายการหมดอายุ

ร้านค้าสามารถตั้งค่ารายการหมดอายุได้ทันที สำหรับรายการรับชำระเงินในโหมดที่ผู้ซื้อชำระเงินผ่านการแสดงโค้ดชำระเงินของร้านค้า และมีสถานะยังไม่ได้รับการอนุมัติวงเงิน (status=pending) โดยถือเป็นการยกเลิกรายการรับชำระเงิน

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

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

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

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

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

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)

การอนุมัติรายการรับชำระเงิน

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

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

ค้นหาคิวอาร์โค้ดที่อยู่ในรายการรับชำระเงิน ดังนี้

charge:
  source:
    scannable_code:
      image:
        download_uri: QR code image to present to the customer

{
  "object": "barcode",
  "type": "qr",
  "image": {
    "object": "document",
    "livemode": false,
    "id": "docu_test_611bikf68dcclqb1rvc",
    "deleted": false,
    "filename": "qrcode.svg",
    "location": "/charges/chrg_test_611bikctw6ubxi0dzso/documents/docu_test_611bikf68dcclqb1rvc",
    "kind": "qr",
    "download_uri": "https://api.omise.co/charges/chrg_test_611bikctw6ubxi0dzso/documents/docu_test_611bikf68dcclqb1rvc/downloads/8A1F56E69E4A1FA1",
    "created_at": "2024-09-10T03:57:22Z"
  }
}

การรับ 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_expired รายการชำระเงินหมดอายุ
payment_rejected รายการถูกปฏิเสธโดยธนาคารผู้ออกบัตร
insufficient_fund วงเงินคงเหลือไม่เพียงพอหรือวงเงินเต็ม
failed_processing ระบบทำรายการไม่สำเร็จ

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

สำหรับรายการชำระเงินในโหมดที่ผู้ซื้อชำระเงินผ่านการแสดงโค้ดชำระเงินของร้านค้า สามารถยกเลิกรายการได้จนกว่าจะถึงเวลา 16:15 UTC ของวันที่ทำรายการ และสามารถทำการคืนเงินบางส่วนหรือเต็มจำนวนได้ภายในระยะเวลา 1 ปี นับตั้งแต่วันที่ทำรายการ

ข้อจำกัด

ประเทศไทย

  • จำนวนรับชำระขั้นต่ำ: 2000 (THB 20.00)
  • จำนวนรับชำระสูงสุด: 15000000 (THB 150,000.00)

สิงคโปร์

  • จำนวนรับชำระขั้นต่ำ: 100 (SGD 1.00)
  • จำนวนรับชำระสูงสุด: 2000000 (SGD 20,000.00)

มาเลเซีย

  • จำนวนรับชำระขั้นต่ำ: 100 (MYR 1.00)
  • จำนวนรับชำระสูงสุด: 3000000 (MYR 30,000.00)

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

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