ShopeePay

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

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

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

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

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

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

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

ภาพหน้าจอต่อไปนี้แสดงขั้นตอนดังกล่าว

การใช้งานผ่านเบราว์เซอร์มือถือ

❶ ลูกค้าเลือก ShopeePay เป็นวิธีการชำระเงิน ❷ ระบบเปลี่ยนเส้นทางลูกค้าไปยังแอป ShopeePay เพื่อยืนยันการชำระเงิน ❸ รายละเอียดการชำระเงินจะปรากฏขึ้น ❹ ลูกค้าสามารถกลับไปยังหน้ายืนยันของร้านค้าได้โดยกด กลับไปยังร้านค้า ❺ ลูกค้าถูกเปลี่ยนเส้นทางกลับมายังหน้าของร้านค้า

การใช้งานผ่านเบราว์เซอร์บนคอมพิวเตอร์

❶ ลูกค้าเลือก ShopeePay เป็นวิธีการชำระเงิน ❷ QR โค้ดจะปรากฏขึ้น ❸ ลูกค้าเปิดแอป ShopeePay และใช้ตัวสแกน QR ❹ ลูกค้าสแกน QR โค้ด ❺ หน้าสรุปรายการจะปรากฏขึ้นก่อนที่ลูกค้าจะยืนยันการชำระเงิน ❻ สลิปยืนยันการชำระเงินจะปรากฏขึ้น และลูกค้าสามารถถูกเปลี่ยนเส้นทางไปยังหน้ายืนยันของร้านค้าได้ ❼ เมื่อคุณได้รับ webhook event แจ้งการชำระเงินเสร็จสมบูรณ์ ให้ยืนยันการชำระเงินกับลูกค้า

ShopeePay รองรับวิธีการชำระเงินตามประเทศดังต่อไปนี้:

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

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

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

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

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

การสร้าง source

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

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

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

Omise.setPublicKey(omise_public_key);

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

สำหรับการทดสอบ คุณสามารถส่ง request เดียวกันผ่าน curl:

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

ตัวอย่าง response:

{
  "object": "source",
  "id": "src_test_5twksxr06g6ldfg3gaa",
  "livemode": false,
  "location": "/sources/src_test_5twksxr06g6ldfg3gaa",
  "amount": 150000,
  "barcode": null,
  "bank": null,
  "created_at": "2022-11-23T18:10:49Z",
  "currency": "MYR",
  "email": null,
  "flow": "redirect",
  "installment_term": null,
  "absorption_type": null,
  "name": null,
  "mobile_number": null,
  "phone_number": null,
  "platform_type": null,
  "scannable_code": null,
  "references": null,
  "store_id": null,
  "store_name": null,
  "terminal_id": null,
  "type": "shopeepay",
  "zero_interest_installments": null,
  "charge_status": "unknown",
  "receipt_amount": null,
  "discounts": []
}

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

การสร้าง charge

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

• return_uri — URL บนเว็บไซต์ของคุณที่ลูกค้าจะถูกเปลี่ยนเส้นทางมาหลังจากยืนยันการชำระเงินเสร็จสิ้น ต้องใช้ HTTPS เท่านั้น
• source — ตัวระบุ source ที่ได้รับจากขั้นตอนก่อนหน้า
• amount และ currency — ต้องตรงกับค่าที่ใช้ในการสร้าง source

Omise แนะนำให้ไม่ใช้แอตทริบิวต์ net, fee, fee_vat และ transaction_fees ของ charge จนกว่า status ของ charge จะเป็น successful

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

ตัวอย่าง response:

{
  "object": "charge",
  "id": "chrg_test_5twksxushmdv3if7ppe",
  "location": "/charges/chrg_test_5twksxushmdv3if7ppe",
  "amount": 150000,
  "net": 0,
  "fee": 0,
  "fee_vat": 0,
  "interest": 0,
  "interest_vat": 0,
  "funding_amount": 150000,
  "refunded_amount": 0,
  "transaction_fees": {
    "fee_flat": null,
    "fee_rate": null,
    "vat_rate": "0.0"
  },
  "platform_fee": {
    "fixed": null,
    "amount": null,
    "percentage": null
  },
  "currency": "MYR",
  "funding_currency": "MYR",
  "ip": null,
  "refunds": {
    "object": "list",
    "data": [],
    "limit": 20,
    "offset": 0,
    "total": 0,
    "location": "/charges/chrg_test_5twksxushmdv3if7ppe/refunds",
    "order": "chronological",
    "from": "1970-01-01T00:00:00Z",
    "to": "2022-11-23T18:10:49Z"
  },
  "link": null,
  "description": null,
  "metadata": {},
  "card": null,
  "source": {
    "object": "source",
    "id": "src_test_5twksxfiaojusv5zkyu",
    "livemode": false,
    "location": "/sources/src_test_5twksxfiaojusv5zkyu",
    "amount": 150000,
    "barcode": null,
    "bank": null,
    "created_at": "2022-11-23T18:10:47Z",
    "currency": "MYR",
    "email": null,
    "flow": "redirect",
    "installment_term": null,
    "absorption_type": null,
    "name": null,
    "mobile_number": null,
    "phone_number": null,
    "platform_type": null,
    "scannable_code": null,
    "references": null,
    "store_id": null,
    "store_name": null,
    "terminal_id": null,
    "type": "shopeepay",
    "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": "https://pay.omise.co/payments/pay2_test_5twksxuu4ehzo8d40mh/authorize",
  "return_uri": "https://example.com/orders/345678/complete",
  "created_at": "2022-11-23T18:10:49Z",
  "paid_at": null,
  "expires_at": "2022-11-30T18:10:49Z",
  "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 พร้อมกัน

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

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

การกำหนดวันหมดอายุของ charge

โดยค่าเริ่มต้น charge ของ ShopeePay จะหมดอายุ 60 นาทีหลังจากสร้าง หากต้องการให้หมดอายุก่อนกำหนด ให้ใช้ request ดังต่อไปนี้:

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

แทนที่ $CHARGE_ID ด้วย id ของ charge

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

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

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

การอนุมัติ charge

เปลี่ยนเส้นทางลูกค้าไปยัง URL ที่ระบุใน authorize_uri เพื่อให้ลูกค้ายืนยัน charge หลังจากลูกค้าดำเนินการยืนยันเสร็จสิ้น ระบบจะเปลี่ยนเส้นทางลูกค้าไปยัง URL ที่ระบุใน return_uri

ในโหมดทดสอบ คุณสามารถจำลองการยืนยันได้โดยเปิด authorize_uri และเลือกทำเครื่องหมาย charge เป็น สำเร็จ หรือ ล้มเหลว ด้วยตนเอง

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

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

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

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

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

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

การทดสอบ

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

1. สร้าง source และ charge โดยใช้ test public key และ secret key
2. เปลี่ยนเส้นทางไปยัง authorize_uri ที่ได้รับใน charge response
3. บนหน้ายืนยันในโหมดทดสอบ เลือก สำเร็จ หรือ ล้มเหลว เพื่อจำลองการชำระเงินของลูกค้า
4. ตรวจสอบว่า webhook endpoint ของคุณได้รับ event charge.complete และแอปพลิเคชันอัปเดตสถานะคำสั่งซื้อถูกต้อง
5. ยืนยันว่าลูกค้าถูกเปลี่ยนเส้นทางไปยัง return_uri ของคุณ

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

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

คุณสามารถคืนเงินบางส่วนหรือเต็มจำนวนได้ภายใน 180 วันนับจากวันที่ทำรายการ ผ่าน Refunds API หรือจากหน้า charge บน แดชบอร์ด

สำคัญ: การคืนเงินและการยกเลิกไม่สามารถดำเนินการได้สำหรับรายการ off-us เมื่อลูกค้าชำระเงินโดยใช้แอปธนาคารบนมือถือแทนการใช้ยอดเงินในกระเป๋า ShopeePay โดยตรง (รายการ off-us) การชำระเงินดังกล่าวไม่สามารถคืนเงินหรือยกเลิกผ่านระบบ Omise ได้ ในกรณีนี้ ร้านค้าจะต้องดำเนินการคืนเงินกับลูกค้าโดยตรงนอกระบบ Omise

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

ขีดจำกัด

จำนวนเงินทั้งหมดอยู่ในหน่วยเงินที่เล็กที่สุด ตัวอย่างเช่น MYR 1.00 = 100

หมายเหตุ: ขีดจำกัดข้างต้นใช้สำหรับรายการสกุลเงิน MYR ขีดจำกัดสำหรับ THB และ SGD ขึ้นอยู่กับแต่ละธุรกิจ ติดต่อ support@omise.co เพื่อขอรายละเอียดเพิ่มเติม

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

ความแตกต่างระหว่าง redirect flow และ offline flow คืออะไร?

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

return_uri ของฉันควรทำอะไรเมื่อลูกค้ามาถึง?

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

เหตุใด return_uri จึงต้องใช้ HTTPS?

ShopeePay กำหนดให้ URL สำหรับการเปลี่ยนเส้นทางต้องเป็น URL ที่ปลอดภัยสำหรับทุกกระบวนการยืนยัน URL ที่ใช้ HTTP จะถูกปฏิเสธเมื่อสร้าง charge

จะเกิดอะไรขึ้นหากลูกค้าปิดแอป ShopeePay ก่อนยืนยัน?

รายการ charge จะยังคงอยู่ในสถานะ pending จนกว่าจะหมดอายุ โดยค่าเริ่มต้น charge จะหมดอายุ 60 นาทีหลังจากสร้าง คุณจะได้รับ webhook charge.complete ที่มี status: failed และ failure_code: payment_expired เมื่อเกิดเหตุการณ์นี้

สามารถกำหนดระยะเวลาหมดอายุแบบกำหนดเองสำหรับ charge ได้หรือไม่?

ไม่สามารถกำหนดระยะเวลาหมดอายุแบบกำหนดเองได้ตอนสร้าง charge แต่คุณสามารถให้ charge หมดอายุก่อนกำหนดได้ทุกเมื่อโดยใช้ expire endpoint

รายการ off-us คืออะไร และทำไมจึงไม่สามารถคืนเงินได้?

รายการ off-us เกิดขึ้นเมื่อลูกค้าชำระเงินโดยใช้แอปธนาคารบนมือถือที่เชื่อมต่อไว้ แทนการใช้ยอดเงินในกระเป๋า ShopeePay โดยตรง ในกรณีนี้ การชำระเงินจะถูกประมวลผลนอกห่วงโซ่การชำระเงินของ Omise ทำให้ Omise ไม่สามารถเริ่มต้นการคืนเงินหรือการยกเลิกได้ ร้านค้าจะต้องดำเนินการคืนเงินกับลูกค้าโดยตรง

สามารถคืนเงินบางส่วนสำหรับ charge ของ ShopeePay ได้หรือไม่?

ได้ รองรับการคืนเงินบางส่วนสำหรับ charge ของ ShopeePay ตราบใดที่เริ่มต้นการคืนเงินภายใน 180 วันนับจากวันที่ทำรายการ และรายการดังกล่าวไม่ใช่รายการ off-us

จะเกิดอะไรขึ้นหากได้รับรหัสความล้มเหลว failed_processing?

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

ShopeePay รองรับสกุลเงินใดบ้าง?

ShopeePay รองรับ THB (ไทย), SGD (สิงคโปร์) และ MYR (มาเลเซีย) คุณต้องใช้สกุลเงินที่ถูกต้องตามประเทศของลูกค้า — การใช้สกุลเงินและประเทศที่ไม่ตรงกันจะส่งผลให้ charge ล้มเหลว

SPayLater รองรับในทุกประเทศที่รองรับหรือไม่?

ใช่ SPayLater รองรับในไทย, สิงคโปร์ และมาเลเซีย

ขีดจำกัดจำนวนเงินสำหรับ ShopeePay คือเท่าใด?

สำหรับรายการสกุลเงิน MYR ขั้นต่ำคือ 100 (MYR 1.00) และสูงสุดคือ 499900 (MYR 4,999.00) ขีดจำกัดสำหรับ THB และ SGD ขึ้นอยู่กับแต่ละธุรกิจ ดูรายละเอียดได้ที่ ขีดจำกัด

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

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

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

• Charges API
• Sources API
• Webhooks
• Events API
• Refunds API