TrueMoney QR (ออฟไลน์)

รับชำระเงินแบบออฟไลน์จากผู้ใช้ TrueMoney ผ่านร้านค้าของคุณด้วยวิธีการชำระเงิน TrueMoney QR (ออฟไลน์)

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

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

• ประเทศที่รองรับ: ไทย
• เวอร์ชัน API ขั้นต่ำ: 2017-11-02

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

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

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

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

TrueMoney QR รองรับวิธีการชำระเงินดังต่อไปนี้:

• TrueMoney Wallet (ยอดเงินในกระเป๋าเงิน)
• บัญชีธนาคาร
• บัตรเครดิต/เดบิต
• Pay Next (ชำระเต็มจำนวน)
• Pay Next Extra (ชำระเต็มจำนวน)

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

หากต้องการสร้างรายการเรียกเก็บเงินด้วย TrueMoney QR ให้ส่ง API request ตามขั้นตอนดังต่อไปนี้:

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

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

หากทั้งการสร้าง source และ charge จำเป็นต้องดำเนินการฝั่ง server คุณสามารถรวมทั้งสองขั้นตอนไว้ใน API request เดียว โดยใช้ secret key

การสร้าง source

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

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

ใน Omise.js พารามิเตอร์ type คืออาร์กิวเมนต์แรกที่ส่งให้กับเมธอด createSource

Omise.setPublicKey(omise_public_key);

Omise.createSource('truemoney_qr', {
  "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=truemoney_qr"

ตัวอย่าง response:

{
  "object": "source",
  "id": "src_test_616e6qe9duz2cthauum",
  "livemode": false,
  "location": "/sources/src_test_616e6qe9duz2cthauum",
  "amount": 400000,
  "barcode": null,
  "bank": null,
  "created_at": "2024-09-23T03:18:39Z",
  "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": "truemoney_qr",
  "zero_interest_installments": null,
  "charge_status": "unknown",
  "receipt_amount": null,
  "discounts": [],
  "promotion_code": null
}

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

การสร้าง charge

สร้าง charge โดยระบุ source, amount และ currency:

• source — ตัวระบุ source ที่ได้รับจากขั้นตอนก่อนหน้า
• amount และ currency — ต้องตรงกับค่าที่ใช้ในการสร้าง source

แทนที่ $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 "return_uri=http://example.com/orders/345678/complete" \
  -d "source=$SOURCE_ID"

ตัวอย่าง response:

{
  "object": "charge",
  "id": "chrg_test_616e6qhdvp3gv5hb31y",
  "location": "/charges/chrg_test_616e6qhdvp3gv5hb31y",
  "amount": 400000,
  "acquirer_reference_number": null,
  "net": 0,
  "fee": 0,
  "fee_vat": 0,
  "interest": 0,
  "interest_vat": 0,
  "funding_amount": 400000,
  "refunded_amount": 0,
  "transaction_fees": {
    "fee_flat": null,
    "fee_rate": null,
    "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_616e6qhdvp3gv5hb31y/refunds",
    "order": "chronological",
    "from": "1970-01-01T00:00:00Z",
    "to": "2024-09-23T03:18:40Z"
  },
  "link": null,
  "description": null,
  "metadata": {},
  "card": null,
  "source": {
    "object": "source",
    "id": "src_test_616e6q22leajy1hszrg",
    "livemode": false,
    "location": "/sources/src_test_616e6q22leajy1hszrg",
    "amount": 400000,
    "barcode": null,
    "bank": null,
    "created_at": "2024-09-23T03:18:38Z",
    "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_616e6qjb5979wb1nopf",
        "deleted": false,
        "filename": "qrcode.png",
        "location": "/charges/chrg_test_616e6qhdvp3gv5hb31y/documents/docu_test_616e6qjb5979wb1nopf",
        "kind": "qr",
        "download_uri": "https://api.omise.co/charges/chrg_test_616e6qhdvp3gv5hb31y/documents/docu_test_616e6qjb5979wb1nopf/downloads/0AF28F77E29F13C1",
        "created_at": "2024-09-23T03:18:40Z"
      }
    },
    "billing": null,
    "shipping": null,
    "items": [],
    "references": null,
    "provider_references": {
      "reference_number_1": "pay2_test_616e6qhftlwd4241yc1",
      "reference_number_2": null
    },
    "store_id": null,
    "store_name": null,
    "terminal_id": null,
    "type": "truemoney_qr",
    "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": "https://pay.omise.co/payments/pay2_test_616e6qhftlwd4241yc1/authorize?acs=false",
  "return_uri": "http://example.com/orders/345678/complete",
  "created_at": "2024-09-23T03:18:40Z",
  "paid_at": null,
  "authorized_at": null,
  "expires_at": "2024-09-24T03:18:40Z",
  "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 และ charge พร้อมกัน

อีกทางเลือกหนึ่ง คุณสามารถสร้างและเรียกเก็บเงินจาก source ใน API request เดียวโดยใช้ secret key:

curl https://api.omise.co/charges \
  -u $OMISE_SECRET_KEY: \
  -d "amount=400000" \
  -d "currency=THB" \
  -d "return_uri=http://example.com/orders/345678/complete" \
  -d "source[type]=truemoney_qr"

การดำเนินการ charge ให้เสร็จสมบูรณ์

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

แผนภาพลำดับต่อไปนี้แสดงขั้นตอนการชำระเงินทั้งหมด:

การแสดง QR โค้ด

หลังจากสร้าง charge แล้ว ให้แสดง QR โค้ดแก่ลูกค้าเพื่อให้สแกนด้วยแอป TrueMoney รูปภาพ QR โค้ดสามารถเข้าถึงได้ผ่าน download_uri ที่อยู่ภายใน charge object:

charge
  └── source
        └── scannable_code
              └── image
                    └── download_uri  (URL ของรูปภาพ QR โค้ด)

นำค่า download_uri มาแสดงเป็น img tag บนหน้าชำระเงินของคุณ:

<img src="{download_uri}" alt="TrueMoney QR โค้ด" />

ตัวอย่าง object scannable_code:

{
  "object": "barcode",
  "type": "qr",
  "image": {
    "object": "document",
    "livemode": false,
    "id": "docu_test_616e6q70sr2xc8a3ugl",
    "deleted": false,
    "filename": "qrcode.png",
    "location": "/charges/chrg_test_616e6q4xsj0jk1y0ozi/documents/docu_test_616e6q70sr2xc8a3ugl",
    "kind": "qr",
    "download_uri": "https://api.omise.co/charges/chrg_test_616e6q4xsj0jk1y0ozi/documents/docu_test_616e6q70sr2xc8a3ugl/downloads/989A209A9C571BFB",
    "created_at": "2024-09-23T03:18:38Z"
  }
}

หมายเหตุ: QR โค้ดมีอายุการใช้งาน 24 ชั่วโมงนับจากเวลาที่สร้าง charge ตามที่ระบุในฟิลด์ expires_at ของ charge object หลังจากหมดอายุ สถานะ charge จะเปลี่ยนเป็น expired และ QR โค้ดจะไม่สามารถใช้งานได้อีก ควรแสดงการนับถอยหลังหรือแจ้งเตือนการหมดอายุแก่ลูกค้า

การอนุมัติ charge

ลูกค้าสแกน QR โค้ดด้วยแอป TrueMoney บนโทรศัพท์เพื่ออนุมัติรายการเรียกเก็บเงินกับผู้ให้บริการออฟไลน์ของ TrueMoney

การรับ event แจ้งการชำระเงินเสร็จสมบูรณ์

ใช้ webhook events เพื่อรับการแจ้งเตือนเมื่อการชำระเงินเสร็จสมบูรณ์ กำหนดค่า webhook endpoint บน แดชบอร์ดของคุณ เพื่อรับ event ดังต่อไปนี้:

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

หลังจากได้รับ event charge.complete ให้ดึงข้อมูล charge โดยใช้ id และยืนยันว่า status ใน charge object ตรงกับ status ใน webhook event

รหัสความล้มเหลว:

การทดสอบ

คุณสามารถจำลองขั้นตอนการชำระเงินทั้งหมดในโหมดทดสอบโดยไม่ต้องใช้เงินจริง

1. สร้าง source และ charge โดยใช้ test public key และ secret key
2. เปิด แดชบอร์ด Omise และไปที่รายการ charge
3. คลิก Actions และเลือก Mark as Successful หรือ Mark as Failed เพื่อจำลองการสแกน QR โค้ดของลูกค้า
4. ตรวจสอบว่า webhook endpoint ของคุณได้รับ event charge.complete และแอปพลิเคชันอัปเดตสถานะคำสั่งซื้อถูกต้อง

test key จะขึ้นต้นด้วย pkey_test_ (public) และ skey_test_ (secret) ส่วน live key จะขึ้นต้นด้วย pkey_ และ skey_

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

รายการเรียกเก็บเงิน TrueMoney สามารถยกเลิก (void) ได้เฉพาะในวันเดียวกับที่อนุมัติรายการ ส่วนการคืนเงิน (refund) สามารถทำได้ภายใน 30 วันหลังจากสร้าง charge

ดูข้อมูลเพิ่มเติมเกี่ยวกับการคืนเงินได้ที่ เอกสาร Refunds API

• วิธีการชำระเงินทั้งห้าวิธีรองรับการยกเลิกเต็มจำนวนในวันเดียวกับที่อนุมัติรายการ
• ไม่มีวิธีการชำระเงินใดที่รองรับการยกเลิกบางส่วน
• สำหรับการคืนเงิน TrueMoney Wallet (ยอดเงินในกระเป๋าเงิน) และบัญชีธนาคารรองรับทั้งการคืนเงินเต็มจำนวนและบางส่วน
• บัตรเครดิต/เดบิต, Pay Next และ Pay Next Extra รองรับเฉพาะการคืนเงินเต็มจำนวนเท่านั้น ไม่รองรับการคืนเงินบางส่วนสำหรับสามวิธีนี้

ขีดจำกัด

จำนวนเงินทั้งหมดอยู่ในหน่วยเงินที่เล็กที่สุด (สตางค์) โดย 1 บาท = 100 สตางค์ ตัวอย่างเช่น ฿20.00 = 2000

TrueMoney Wallet

Pay Next

หมายเหตุ: ขีดจำกัดสูงสุดสำหรับ Pay Next ขึ้นอยู่กับแต่ละธุรกิจ

Pay Next Extra

หมายเหตุ: ขีดจำกัดสูงสุดสำหรับ Pay Next Extra ขึ้นอยู่กับแต่ละธุรกิจ

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

จะเกิดอะไรขึ้นหากลูกค้าไม่สแกน QR โค้ดทันเวลา?

รายการ charge จะหมดอายุหลังจาก 24 ชั่วโมง ตามที่ระบุในฟิลด์ expires_at ของ charge object เมื่อเกิดเหตุการณ์นี้ status ของ charge จะเปลี่ยนเป็น expired QR โค้ดจะไม่สามารถใช้งานได้อีก และคุณต้องสร้าง charge ใหม่เพื่อรับการชำระเงินจากลูกค้า

สามารถสร้าง charge ใหม่หากรายการก่อนหน้าหมดอายุได้หรือไม่?

ได้ สร้าง source และ charge ใหม่โดยใช้ขั้นตอนเดิม รายการ charge ที่หมดอายุไม่มีผลต่อรายการใหม่

สามารถยกเลิก charge บางส่วนได้หรือไม่?

ไม่ได้ การยกเลิก (void) รายการ TrueMoney จะเป็นการยกเลิกเต็มจำนวนเท่านั้น ไม่รองรับการยกเลิกบางส่วนในวันเดียวกัน

วิธีการชำระเงินใดที่รองรับการคืนเงินบางส่วน?

เฉพาะ TrueMoney Wallet (ยอดเงินในกระเป๋าเงิน) และบัญชีธนาคารเท่านั้นที่รองรับการคืนเงินบางส่วน บัตรเครดิต/เดบิต, Pay Next และ Pay Next Extra รองรับเฉพาะการคืนเงินเต็มจำนวน

ควรทำอย่างไรหากได้รับรหัสความล้มเหลว failed_processing?

รหัสนี้บ่งชี้ว่าเกิดความล้มเหลวในการประมวลผลทั่วไปจากฝั่ง TrueMoney แนะนำให้ลูกค้าลองชำระเงินใหม่อีกครั้ง หากปัญหายังคงเกิดขึ้น ให้แนะนำลูกค้าตรวจสอบแอป TrueMoney หรือเลือกวิธีการชำระเงินอื่น หากความล้มเหลวยังเกิดขึ้นต่อเนื่องในโหมด live ให้ติดต่อ support@omise.co

จะทราบได้อย่างไรว่าควรยกเลิก (void) หรือคืนเงิน (refund)?

หากต้องการยกเลิกรายการในวันเดียวกับที่อนุมัติ ให้ใช้การยกเลิก (void) หากต้องการยกเลิกหรือคืนเงินในวันถัดไป (ภายใน 30 วันหลังจากสร้าง charge) ให้ใช้การคืนเงิน (refund) ดูตาราง การยกเลิกและการคืนเงิน สำหรับการรองรับแต่ละวิธีการชำระเงิน

TrueMoney QR ใช้งานได้นอกประเทศไทยหรือไม่?

ไม่ได้ ขณะนี้ TrueMoney QR รองรับเฉพาะในประเทศไทยและประมวลผลการชำระเงินเป็นสกุลเงินบาท (THB) เท่านั้น

จะหา API key ได้จากที่ไหน?

ดูข้อมูลได้ที่ วิธีเข้าถึง Omise API keys

จำนวนเงินขั้นต่ำและสูงสุดสำหรับ TrueMoney QR คือเท่าใด?

• จำนวนเงินขั้นต่ำและสูงสุดขึ้นอยู่กับวิธีการชำระเงินที่ใช้ในแอป TrueMoney
• TrueMoney Wallet มีขั้นต่ำ 2000 (฿20.00) และสูงสุด 5000000 (฿50,000.00)
• Pay Next มีขั้นต่ำ 30000 (฿300.00)
• Pay Next Extra มีขั้นต่ำ 100000 (฿1,000.00)
• ขีดจำกัดสูงสุดสำหรับ Pay Next และ Pay Next Extra ขึ้นอยู่กับแต่ละธุรกิจ ดูรายละเอียดได้ที่ ขีดจำกัด

ทำไม charge ถึงถูกปฏิเสธ — อาจเป็นปัญหาเรื่องขีดจำกัดหรือไม่?

หาก charge ล้มเหลวทันทีเมื่อสร้าง ให้ตรวจสอบว่า amount ถึงขั้นต่ำสำหรับวิธีการชำระเงินที่ต้องการและไม่เกินขีดจำกัดสูงสุดที่กำหนด จำนวนเงินทั้งหมดต้องส่งเป็นสตางค์ (หน่วยเงินที่เล็กที่สุด) — ตัวอย่างเช่น ฿300.00 ต้องส่งเป็น 30000 ไม่ใช่ 300

เอกสาร API ที่เกี่ยวข้อง

• Charges API
• Sources API
• Webhooks
• Refunds API