ShopeePay การเปลี่ยนเส้นทางแบบ App-to-App (Jump App)

รับชำระเงินออนไลน์จากผู้ใช้ ShopeePay ผ่านเว็บไซต์ของคุณด้วยวิธีการชำระเงิน ShopeePay การเปลี่ยนเส้นทางแบบ App-to-App (Jump App)

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

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

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

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

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

ลูกค้าที่ชำระเงินผ่าน ShopeePay App Redirection จะดำเนินการผ่านกระบวนการชำระเงินแบบ app redirect ซึ่งแตกต่างจาก ShopeePay มาตรฐานที่เปิดหน้าเว็บเพื่อสแกน QR โค้ด — วิธีนี้จะเปลี่ยนเส้นทางลูกค้าโดยตรงเข้าสู่แอปพลิเคชัน ShopeePay บนมือถือเพื่อยืนยันและอนุมัติการชำระเงิน

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

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

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

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

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

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

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

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

การสร้าง source

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

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

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

Omise.setPublicKey(omise_public_key);

Omise.createSource('shopeepay_jumpapp', {
  "amount": 5000,
  "currency": "SGD"
}, function(statusCode, response) {
  console.log(response);
});

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

curl https://api.omise.co/sources \
  -u $OMISE_PUBLIC_KEY: \
  -d "amount=5000" \
  -d "currency=SGD" \
  -d "type=shopeepay_jumpapp"

ตัวอย่าง response:

{
  "object": "source",
  "id": "src_test_62784yixw757rznv0pa",
  "livemode": false,
  "location": "/sources/src_test_62784yixw757rznv0pa",
  "amount": 5000,
  "barcode": null,
  "bank": null,
  "created_at": "2024-12-26T07:19:58Z",
  "currency": "SGD",
  "email": null,
  "flow": "app_redirect",
  "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": "shopeepay_jumpapp",
  "zero_interest_installments": null,
  "charge_status": "unknown",
  "receipt_amount": null,
  "discounts": [],
  "promotion_code": null
}

แอตทริบิวต์ id คือตัวระบุ source (ขึ้นต้นด้วย src) โปรดสังเกตว่า flow มีค่าเป็น app_redirect สำหรับวิธีการชำระเงินนี้ ซึ่งแตกต่างจาก redirect ที่ใช้ใน ShopeePay มาตรฐาน

การสร้าง charge

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

• return_uri — URL บนเว็บไซต์ของคุณที่ลูกค้าจะถูกเปลี่ยนเส้นทางมาหลังจากยืนยันการชำระเงินเสร็จสิ้น
• 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=5000" \
  -d "currency=SGD" \
  -d "return_uri=https://example.com/orders/345678/complete" \
  -d "source=$SOURCE_ID"

ตัวอย่าง response:

{
  "object": "charge",
  "id": "chrg_test_62784ym7mj3s0f70xdm",
  "location": "/charges/chrg_test_62784ym7mj3s0f70xdm",
  "amount": 5000,
  "acquirer_reference_number": null,
  "net": 0,
  "fee": 0,
  "fee_vat": 0,
  "interest": 0,
  "interest_vat": 0,
  "funding_amount": 5000,
  "refunded_amount": 0,
  "transaction_fees": {
    "fee_flat": null,
    "fee_rate": null,
    "vat_rate": "0.0"
  },
  "platform_fee": {
    "fixed": null,
    "amount": null,
    "percentage": null
  },
  "currency": "SGD",
  "funding_currency": "SGD",
  "ip": null,
  "refunds": {
    "object": "list",
    "data": [],
    "limit": 20,
    "offset": 0,
    "total": 0,
    "location": "/charges/chrg_test_62784ym7mj3s0f70xdm/refunds",
    "order": "chronological",
    "from": "1970-01-01T00:00:00Z",
    "to": "2024-12-26T07:19:59Z"
  },
  "link": null,
  "description": null,
  "metadata": {},
  "card": null,
  "source": {
    "object": "source",
    "id": "src_test_62784y966l3i97hq1nq",
    "livemode": false,
    "location": "/sources/src_test_62784y966l3i97hq1nq",
    "amount": 5000,
    "barcode": null,
    "bank": null,
    "created_at": "2024-12-26T07:19:57Z",
    "currency": "SGD",
    "email": null,
    "flow": "app_redirect",
    "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": "shopeepay_jumpapp",
    "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,
  "merchant_advice": null,
  "status": "pending",
  "authorize_uri": "https://pay.omise.co/payments/pay2_test_62784ym9apoe3i9ozoh/authorize?acs=false",
  "return_uri": "https://example.com/orders/345678/complete",
  "created_at": "2024-12-26T07:19:58Z",
  "paid_at": null,
  "authorized_at": null,
  "expires_at": "2025-01-02T07:19:58Z",
  "expired_at": null,
  "reversed_at": null,
  "multi_capture": false,
  "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=5000" \
  -d "currency=SGD" \
  -d "return_uri=https://example.com/orders/345678/complete" \
  -d "source[type]=shopeepay_jumpapp"

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

โดยค่าเริ่มต้น charge ของ ShopeePay App Redirection จะหมดอายุ 20 นาทีหลังจากสร้าง คุณสามารถกำหนดระยะเวลาหมดอายุแบบกำหนดเองได้สูงสุด 60 นาที โดยส่ง timestamp แบบ UTC ในฟิลด์ expires_at ตอนสร้าง charge:

curl https://api.omise.co/charges \
  -u $OMISE_SECRET_KEY: \
  -d "amount=5000" \
  -d "currency=SGD" \
  -d "return_uri=https://example.com/orders/345678/complete" \
  -d "source[type]=shopeepay_jumpapp" \
  -d "expires_at=2020-07-01T15:00:00Z"

หากต้องการให้ charge หมดอายุก่อนกำหนด ให้ใช้ 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 ซึ่งจะเปลี่ยนเส้นทางลูกค้าโดยตรงเข้าสู่แอป ShopeePay บนมือถือเพื่ออนุมัติ charge หลังจากอนุมัติแล้ว ลูกค้าจะถูกเปลี่ยนเส้นทางไปยัง URL ที่ระบุใน return_uri

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

การรับ 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. เปลี่ยนเส้นทางไปยัง 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_

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

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

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

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

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

ขีดจำกัด

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

ไทย (THB)

สิงคโปร์ (SGD)

มาเลเซีย (MYR)

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

ความแตกต่างระหว่าง ShopeePay มาตรฐานกับ ShopeePay App Redirection (Jump App) คืออะไร?

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

ควรใช้ platform_type เมื่อใด?

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

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

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

ระยะเวลาหมดอายุเริ่มต้นของ charge ShopeePay App Redirection คือเท่าใด?

20 นาที ซึ่งสั้นกว่า ShopeePay มาตรฐาน (60 นาที) เพื่อให้สอดคล้องกับการใช้งานแบบ app redirect ที่คาดว่าลูกค้าจะยืนยันทันที คุณสามารถกำหนดระยะเวลาหมดอายุแบบกำหนดเองได้สูงสุด 60 นาที โดยใช้ฟิลด์ expires_at ตอนสร้าง charge

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

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

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

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

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

ได้ ให้ส่ง timestamp แบบ UTC ในฟิลด์ expires_at ตอนสร้าง charge โดยระยะเวลาหมดอายุสูงสุดที่อนุญาตคือ 60 นาทีนับจากเวลาที่สร้าง charge ดูรูปแบบ request ได้ที่ การกำหนดวันหมดอายุของ charge

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

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

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

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

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

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

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

ขีดจำกัดแตกต่างกันตามสกุลเงิน THB: ขั้นต่ำ 2000 (THB 20.00), สูงสุด 15000000 (THB 150,000.00) SGD: ขั้นต่ำ 100 (SGD 1.00), สูงสุด 2000000 (SGD 20,000.00) MYR: ขั้นต่ำ 100 (MYR 1.00), สูงสุด 999900 (MYR 9,999.00) ดูรายละเอียดได้ที่ ขีดจำกัด

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

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

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

• Charges API
• Sources API
• Webhooks
• Refunds API