Atome QR

รับชำระเงินออนไลน์จากผู้ใช้ Atome ผ่านเว็บไซต์ของคุณด้วยช่องทางการชำระเงิน Atome QR

Atome เป็นบริการซื้อก่อนจ่ายทีหลัง (buy now, pay later หรือ BNPL) ที่ให้ลูกค้าแบ่งชำระค่าซื้อสินค้าเป็นงวด ๆ เอกสารนี้ครอบคลุมขั้นตอนการชำระเงินแบบสแกน QR โค้ดที่หน้าร้าน ซึ่งเป็นขั้นตอนแบบ offline สำหรับขั้นตอนการชำระเงินแบบเปลี่ยนเส้นทางบนเว็บไซต์ โปรดดู Atome

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

🔓 วิธีเปิดใช้งาน

• ประเทศที่รองรับ: ไทย, สิงคโปร์, มาเลเซีย
• เวอร์ชัน API ขั้นต่ำ: 2017-11-02

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

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

ลูกค้าที่ชำระเงินผ่าน Atome QR จะผ่านขั้นตอนการชำระเงินแบบ offline กล่าวคือ เมื่อสร้าง charge แล้ว จะสามารถอนุมัติได้แบบ offline เท่านั้น โดยลูกค้าต้องสแกน QR โค้ดที่สร้างขึ้นด้วยแอป Atome บนโทรศัพท์เพื่อทำขั้นตอนให้เสร็จสมบูรณ์

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

การใช้งานผ่านอุปกรณ์ POS

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

🛠️ การนำไปใช้งาน

หากต้องการสร้าง charge โดยใช้ Atome QR ให้เรียก API ตามขั้นตอนต่อไปนี้

1. สร้าง source การชำระเงิน (type: atome_qr) โดยใช้ Omise.js หรือ mobile SDK อย่างใดอย่างหนึ่ง (iOS และ Android)
2. สร้าง charge โดยใช้ identifier ของ source ที่สร้างในขั้นตอนที่ 1
3. หลังจากได้รับ webhook event การชำระเงินเสร็จสมบูรณ์ (charge completion) ให้เรียกดูข้อมูล charge เพื่อตรวจสอบสถานะ (ไม่บังคับ แต่แนะนำให้ทำ)

ใช้ public key เพื่อสร้าง source ของ Atome QR ฝั่ง client (เบราว์เซอร์หรือโทรศัพท์มือถือของลูกค้า) ใช้ secret key เพื่อสร้าง charge ของ Atome QR ฝั่ง server

การสร้าง source ของ Atome QR

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

ตัวอย่างต่อไปนี้แสดงการสร้าง source ของ Atome QR ใหม่จำนวน ฿500 ให้แทนที่ตัวแปร omise_public_key และ $OMISE_PUBLIC_KEY ด้วย test public key จากแดชบอร์ดของคุณ

Omise.setPublicKey(omise_public_key);

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

สำหรับการทดสอบ คุณสามารถสร้างคำขอเดียวกันได้โดยใช้ curl

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

{
  "object": "source",
  "id": "src_test_5ug0fx8sn9xw75uf0h4",
  "livemode": false,
  "location": "/sources/src_test_5ug0fx8sn9xw75uf0h4",
  "amount": 50000,
  "barcode": null,
  "bank": null,
  "created_at": "2023-01-12T10:40:54Z",
  "currency": "THB",
  "email": null,
  "flow": "offline",
  "installment_term": null,
  "absorption_type": null,
  "name": null,
  "mobile_number": null,
  "phone_number": null,
  "platform_type": null,
  "scannable_code": null,
  "billing": null,
  "shipping": null,
  "items": [],
  "references": null,
  "store_id": null,
  "store_name": null,
  "terminal_id": null,
  "type": "atome_qr",
  "zero_interest_installments": null,
  "charge_status": "unknown",
  "receipt_amount": null,
  "discounts": []
}

แอตทริบิวต์ id คือ identifier ของ source (ขึ้นต้นด้วย src)

การสร้าง charge ของ Atome QR

สร้าง charge โดยระบุพารามิเตอร์ source, amount และ currency

• source ระบุ identifier ของ source
• amount และ currency ต้องตรงกับ amount และ currency ของ source

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

curl https://api.omise.co/charges \
  -u $OMISE_SECRET_KEY: \
  -d "amount=50000" \
  -d "currency=THB" \
  -d "source=$SOURCE_ID"

{
  "object": "charge",
  "id": "chrg_test_5ug0fxc8vlqb5zg9g4p",
  "location": "/charges/chrg_test_5ug0fxc8vlqb5zg9g4p",
  "amount": 50000,
  "net": 48047,
  "fee": 1825,
  "fee_vat": 128,
  "interest": 0,
  "interest_vat": 0,
  "funding_amount": 50000,
  "refunded_amount": 0,
  "transaction_fees": {
    "fee_flat": "0.0",
    "fee_rate": "3.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_5ug0fxc8vlqb5zg9g4p/refunds",
    "order": "chronological",
    "from": "1970-01-01T00:00:00Z",
    "to": "2023-01-12T10:40:56Z"
  },
  "link": null,
  "description": null,
  "metadata": {},
  "card": null,
  "source": {
    "object": "source",
    "id": "src_test_5ug0fx8sn9xw75uf0h4",
    "livemode": false,
    "location": "/sources/src_test_5ug0fx8sn9xw75uf0h4",
    "amount": 50000,
    "barcode": null,
    "bank": null,
    "created_at": "2023-01-12T10:40:54Z",
    "currency": "THB",
    "email": null,
    "flow": "offline",
    "installment_term": null,
    "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_5ug0fxibl7d1ee5hqj8",
        "deleted": false,
        "filename": "qrcode.jpg",
        "location": "/charges/chrg_test_5ug0fxc8vlqb5zg9g4p/documents/docu_test_5ug0fxibl7d1ee5hqj8",
        "kind": "qr",
        "download_uri": "https://api.omise.co/charges/chrg_test_5ug0fxc8vlqb5zg9g4p/documents/docu_test_5ug0fxibl7d1ee5hqj8/downloads/679C6686556F8F0A",
        "created_at": "2023-01-12T10:40:55Z"
      }
    },
    "billing": null,
    "shipping": null,
    "items": [],
    "references": null,
    "store_id": null,
    "store_name": null,
    "terminal_id": null,
    "type": "atome_qr",
    "zero_interest_installments": null,
    "charge_status": "pending",
    "receipt_amount": null,
    "discounts": []
  },
  "schedule": null,
  "customer": null,
  "dispute": null,
  "transaction": null,
  "failure_code": null,
  "failure_message": null,
  "status": "pending",
  "authorize_uri": null,
  "return_uri": null,
  "created_at": "2023-01-12T10:40:55Z",
  "paid_at": null,
  "expires_at": "2023-01-12T22:40:55Z",
  "expired_at": null,
  "reversed_at": null,
  "zero_interest_installments": true,
  "branch": null,
  "terminal": null,
  "device": null,
  "authorized": false,
  "capturable": false,
  "capture": true,
  "disputable": false,
  "livemode": false,
  "refundable": false,
  "reversed": false,
  "reversible": false,
  "voided": false,
  "paid": false,
  "expired": false
}

การสร้าง source และ charge ของ Atome QR พร้อมกัน

หรืออีกวิธีหนึ่งคือสร้างและชำระ source ได้ในคำขอ API เดียว

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

การตั้งค่าให้ QR โค้ดของ Atome QR หมดอายุ

โดยค่าเริ่มต้น QR โค้ดจะหมดอายุ 12 ชั่วโมงหลังจากสร้าง

คุณสามารถกำหนดระยะเวลาหมดอายุที่แตกต่างกันให้กับ QR โค้ดแต่ละรายการได้ โดยระบุ timestamp ที่อยู่ระหว่าง 30 วินาทีถึง 12 ชั่วโมงนับจากเวลาปัจจุบันในฟิลด์ expires_at ของ Charge API หากระบุ timestamp ถูกต้อง QR โค้ดจะหมดอายุตามเวลาที่กำหนดแทนระยะเวลาเริ่มต้น

หลังจากสร้าง charge แล้ว คุณสามารถเรียก Expire API ด้วยตนเองเพื่อทำให้ charge ที่อยู่ในสถานะ pending หมดอายุได้

curl https://api.omise.co/charges \
  -u $OMISE_SECRET_KEY: \
  -d "amount=50000" \
  -d "currency=THB" \
  -d "source[type]=atome_qr" \
  -d "expires_at=2020-12-17T00:00:00Z"

การทำให้ charge ของ Atome QR เสร็จสมบูรณ์

คุณได้สร้าง charge ใหม่ที่มี status เป็น pending แล้ว ค่าอื่น ๆ ที่เป็นไปได้ของ status ของ charge ได้แก่ successful, failed และ expired

หัวข้อต่อไปนี้จะอธิบายรายละเอียดวิธีอนุมัติ charge, การรับ webhook event เมื่อทำรายการเสร็จสมบูรณ์ และการอัปเดตสถานะ

แผนภาพลำดับเหตุการณ์ (sequence diagram) นี้แสดงขั้นตอนทั้งหมด

การอนุมัติ charge ของ Atome QR

แสดง QR โค้ดที่สร้างขึ้นตอน charge ถูกสร้างให้ลูกค้าเห็น ลูกค้าจะสแกน QR โค้ดด้วยแอป Atome เพื่ออนุมัติ charge

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

หา QR โค้ดที่ซ้อนอยู่ภายใน charge object ได้ดังนี้

charge:
  source:
    scannable_code:
      image:
        download_uri: รูปภาพ QR โค้ดสำหรับแสดงให้ลูกค้าเห็น

{
  "object": "barcode",
  "type": "qr",
  "image": {
    "object": "document",
    "livemode": false,
    "id": "docu_test_5ug0fxibl7d1ee5hqj8",
    "deleted": false,
    "filename": "qrcode.jpg",
    "location": "/charges/chrg_test_5ug0fxc8vlqb5zg9g4p/documents/docu_test_5ug0fxibl7d1ee5hqj8",
    "kind": "qr",
    "download_uri": "https://api.omise.co/charges/chrg_test_5ug0fxc8vlqb5zg9g4p/documents/docu_test_5ug0fxibl7d1ee5hqj8/downloads/679C6686556F8F0A",
    "created_at": "2023-01-12T10:40:55Z"
  }
}

การรับ event เมื่อ charge ของ Atome QR เสร็จสมบูรณ์

วิธีที่ดีที่สุดในการรับการแจ้งเตือนเมื่อ charge เสร็จสมบูรณ์คือการใช้webhook events ให้ตั้งค่าตำแหน่งบนเซิร์ฟเวอร์ของคุณเพื่อรับ webhook events แล้วเพิ่มตำแหน่งนี้เป็น webhook endpoint บนแดชบอร์ด

เมื่อ charge เสร็จสมบูรณ์ ระบบจะส่งคำขอ POST ที่มีข้อมูล response ของ charge ฝังอยู่มายัง endpoint นี้

แอตทริบิวต์ key ของ event object จะมีค่าเป็น charge.complete และแอตทริบิวต์ data จะมี charge object อยู่ ดู Events API สำหรับโครงสร้างของ event object

การตรวจสอบสถานะของ charge ของ Atome QR

หลังจากได้รับ event นี้ ให้เรียกดูข้อมูล charge โดยใช้ id และตรวจสอบว่า status ตรงกับ status ของ charge ที่อยู่ใน event

หากค่าของ status เป็น successful แสดงว่าการชำระเงินสำเร็จ หากค่าของ status เป็น failed ให้ตรวจสอบ failure_code และ failure_message ใน charge object เพื่อดูสาเหตุ

รหัสความล้มเหลวที่เป็นไปได้มีดังนี้

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

charge ของ Atome QR สามารถคืนเงินได้บางส่วนหรือทั้งหมดภายใน 60 วันนับจากวันที่ทำรายการ

📊 วงเงินและข้อจำกัด

ไทย

• ขั้นต่ำ: 2000 (THB 20.00)
• สูงสุด: ขึ้นอยู่กับวงเงินเครดิต Atome ของลูกค้าแต่ละราย

สิงคโปร์

• ขั้นต่ำ: 150 (SGD 1.50)
• สูงสุด: 300000 (SGD 3,000.00)

มาเลเซีย

• ขั้นต่ำ: 1000 (MYR 10.00)
• สูงสุด: 500000 (MYR 5,000.00)

❓ คำถามที่พบบ่อย

Atome กับ Atome QR ต่างกันอย่างไร Atome ใช้ขั้นตอนแบบ redirect คือลูกค้าจะถูกส่งไปยังหน้าชำระเงินของ Atome เพื่ออนุมัติการชำระเงินแบบออนไลน์ ส่วนเอกสารนี้ (Atome QR) ใช้ขั้นตอนแบบ offline แทน โดยเว็บไซต์ของคุณจะสร้าง QR โค้ด แล้วให้ลูกค้าสแกนด้วยแอป Atome (เช่น ที่อุปกรณ์ POS) เพื่ออนุมัติการชำระเงิน เนื่องจากเป็นแบบ offline charge ของ Atome QR จึงไม่มี authorize_uri หรือ return_uri

หากลูกค้าไม่สแกน QR โค้ดก่อนหมดอายุจะเกิดอะไรขึ้น status ของ charge จะเปลี่ยนเป็น expired และไม่สามารถใช้ QR โค้ดเพื่ออนุมัติได้อีกต่อไป ให้สร้าง source และ charge ใหม่เพื่อสร้าง QR โค้ดใหม่

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

สามารถคืนเงินบางส่วนได้มากกว่าหนึ่งครั้งภายในระยะเวลา 60 วันหรือไม่ เอกสารนี้ยังไม่ได้ระบุไว้ — โปรดยืนยันรูปแบบการคืนเงินที่รองรับ (คืนเงินบางส่วนเพียงครั้งเดียว หรือคืนเงินบางส่วนได้หลายครั้งจนครบเต็มจำนวน) กับทีม payments ก่อนเพิ่มรายละเอียดในเอกสารนี้ต่อไป

Atome QR รองรับการชำระเงินแบบประจำ (recurring) หรือแบบตั้งเวลาล่วงหน้าหรือไม่ เอกสารนี้ไม่ได้ครอบคลุมเรื่องนี้ ขั้นตอนที่อธิบายในที่นี้เป็นการชำระเงินแบบ offline ครั้งเดียวต่อหนึ่ง charge โปรดยืนยันกับทีม payments ว่า Atome QR รองรับ charge แบบตั้งเวลาหรือแบบประจำหรือไม่ ก่อนที่จะแนะนำร้านค้าไปในทางใดทางหนึ่ง

วงเงินขั้นต่ำ/สูงสุดใช้ต่อ charge หรือต่อลูกค้าหนึ่งราย เอกสารนี้ไม่ได้ระบุไว้ หัวข้อวงเงินและข้อจำกัดระบุเพียงเกณฑ์แยกตามประเทศ แต่ไม่ได้ระบุว่าบังคับใช้ต่อธุรกรรมหรือรวมต่อลูกค้าหนึ่งราย ควรยืนยันและระบุให้ชัดเจนหากเป็นกรณีหลัง เนื่องจากเป็นคำถามที่ร้านค้ามักถาม

👉 ขั้นตอนถัดไป

• Atome (ขั้นตอนการชำระเงินแบบเปลี่ยนเส้นทางบนเว็บไซต์)
• Charge API
• Source API
• Webhooks API