Omise.js

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

ก่อนเริ่มใช้งาน
การทำงานของ Omise.js
ตัวอย่าง
แบบฟอร์มชำระเงินสำเร็จรูป
การเรียก token และ source โดยตรง
- การใช้งาน
- คำสั่งของ Omise
การสร้างรายการโดยใช้ token และ source
CDNs

Omise.js คือส่วนหนึ่งของไลบรารี่ JavaScript ที่ใช้ในการเรียกเก็บข้อมูลการชำระเงินบนเบราว์เซอร์ของผู้ซื้อและทำการส่งข้อมูลมาที่เซิร์ฟเวอร์ของ Opn Payments อย่างปลอดภัย ร้านค้าจำเป็นที่จะต้องใช้ Omise.js เพื่อเรียกเก็บข้อมูลการรับชำระเงินบนเว็บไซต์

คู่มือฉบับนี้จะอธิบายการทำงานของ Omise.js พร้อมแนะนำวิธีการเพิ่มช่องทางการรับชำระเงินบนหน้าเช็คเอ้าท์ของเว็บไซต์ร้านค้า

ก่อนเริ่มใช้งาน

เปิดใช้งาน HTTPS บนหน้าเช็คเอ้าท์ของเว็บไซต์ f > Opn Payments แนะนำเป็นอย่างยิ่งให้เปิดการใช้งาน HTTPS บนเว็บไซต์ทั้งหมด > > ห้ามเก็บและบันทึกข้อมูลบัตรของผู้ซื้อบนเซิร์ฟเวอร์ส่วนตัวของร้านค้าโดยเด็ดขาด > กรุณาอ่าน แนวทางปฏิบัติเพื่อความปลอดภัย สำหรับข้อมูลเพิ่มเติม

การทำงานของ Omise.js

Omise.js จะช่วยเก็บข้อมูลบัตรเครดิต บัตรเดบิต และข้อมูลที่ใช้ในการชำระเงินช่องทางอื่นๆ จากเบราว์เซอร์ของผู้ซื้ออย่างปลอดภัย จากนั้น Omise.js จะทำการส่งข้อมูลดังกล่าวไปที่เซิร์ฟเวอร์ของ Opn Payments แล้วส่งข้อมูลนั้นกลับมาในรูปแบบของ token หรือ source ที่สามารถนำไปใช้ได้เพียงครั้งเดียว (one-time-use)

ร้านค้าจะสามารถใช้ข้อมูลที่ถูกส่งกลับมาในรูปแบบ token หรือ source เพื่อสร้างรายการรับชำระได้อย่างปลอดภัย

ตัวอย่าง

สามารถดูตัวอย่างการทำงานของ Omise.js ได้จากลิงก์ด้านล่างนี้

แบบฟอร์มชำระเงินสำเร็จรูป

ร้านค้าสามารถใช้ Omise.js เพื่อเรียกใช้ token และ source โดยตรงหรือใช้แบบฟอร์มรับชำระเงินสำเร็จรูปที่ Opn Payments ได้เตรียมไว้ให้ แบบฟอร์มนี้จะช่วยเก็บ ตรวจสอบ และทำการส่งข้อมูลไปที่เซิร์ฟเวอร์ของ Opn Payments อย่างปลอดภัย พร้อมทั้งเก็บข้อมูลเพิ่มเติมจากเบราว์เซอร์ของผู้ซื้อเพื่อช่วยในการลดความเสี่ยงของรายการทุจริต

Credit Card form example

ค่าเริ่มต้นของ Omise.js จะแสดงปุ่ม Pay with Opn Payments โดยอัตโนมัติ กรุณาคลิกที่ปุ่มด้านล่างเพื่อดูตัวอย่างจากแบบฟอร์มชำระเงินสำเร็จรูป

ผู้ซื้อจะต้องใส่ข้อมูลบัตรบนหน้าแบบฟอร์มเช็คเอ้าท์ เมื่อผู้ซื้อกดปุ่ม Pay 123.45 THB ระบบจะสร้าง token หรือ source ที่ใช้ได้เพียงครั้งเดียวจากเซิร์ฟเวอร์ของ Opn Payments เพื่อสร้างรายการ

แบบฟอร์มชำระเงินสำเร็จรูปสามารถตั้งค่าโดยใช้ ตัวแปร data ของ HTML และ JavaScript

การใช้ตัวแปร data

ร้านค้าสามารถตั้งค่า Omise.js โดยการใส่ตัวแปร data ลงไปใน HTML ของหน้าเช็คเอ้าท์แทนการปรับแต่ง JavaScript

การใช้งาน

โค้ดที่ต้องเพิ่มบนหน้าเช็คเอ้าท์ของร้านค้า:

<form id="checkoutForm" method="POST" action="/charge">
  <script type="text/javascript" src="https://cdn.omise.co/omise.js"
          data-key="OMISE_PUBLIC_KEY"
          data-amount="12345"
          data-currency="THB"
          data-default-payment-method="credit_card">
  </script>
</form>

หมายเหตุ:

ตัวแปร action คือ URL ของเว็บไซต์ร้านค้าที่รับค่า token และ source โดยผ่านการส่งข้อมูลแบบ POST
<script> จะต้องตั้งอยู่ภายใน <form>
ค่า data-key เป็นตัวกำหนด public key ของร้านค้า
ค่า data-amount เป็นตัวกำหนดจำนวนเงินโดยใช้ หน่วยเงินที่เล็กที่สุด เพื่อแสดงบนหน้าเช็คเอ้าท์สำเร็จรูป
ค่า data-default-payment-method เป็นตัวกำหนดค่าเริ่มต้นของช่องทางการชำระเงิน
กรุณาดู การตั้งค่า สำหรับค่าและตัวแปรอื่นๆ ที่รองรับ

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

ร้านค้าต้องสร้าง /charge URL บนเซิร์ฟเวอร์ (หรือ URL ที่กำหนดจากตัวแปร action) เพื่อรับค่า omiseToken และ omiseSource

หากมีการส่งข้อมูลบัตรไปที่ /charge ค่า omiseToken จะถูกสร้างและส่งกลับมาในรูปแบบ token identifier และค่าของ omiseSource จะเป็น null

หากมีการส่งข้อมูลโดยช่องชำระเงินอื่น ค่า omiseSource จะถูกสร้างและส่งกลับมาในรูปแบบ source identifier และค่าของ omiseToken จะเป็น null

กรุณาดู การสร้างรายการโดยใช้ token และ source

การใช้ JavaScript

ร้านค้าสามารถออกแบบ ปรับแต่ง และแก้ไขคุณสมบัติการทำงานของฟอร์มรับชำระเงินโดยใช้ JavaScript โดยผ่าน object OmiseCard ใน Omise.js

การใช้งาน

โค้ดที่ต้องเพิ่มบนหน้าเช็คเอ้าท์ของร้านค้า:

<form id="checkoutForm" method="POST" action="/charge">
  <input type="hidden" name="omiseToken">
  <input type="hidden" name="omiseSource">
  <button type="submit" id="checkoutButton">Checkout</button>
</form>

<script type="text/javascript" src="https://cdn.omise.co/omise.js">
</script>

<script>
  OmiseCard.configure({
    publicKey: "OMISE_PUBLIC_KEY"
  });

  var button = document.querySelector("#checkoutButton");
  var form = document.querySelector("#checkoutForm");

  button.addEventListener("click", (event) => {
    event.preventDefault();
    OmiseCard.open({
      amount: 12345,
      currency: "THB",
      defaultPaymentMethod: "credit_card",
      onCreateTokenSuccess: (nonce) => {
          if (nonce.startsWith("tokn_")) {
              form.omiseToken.value = nonce;
          } else {
              form.omiseSource.value = nonce;
          };
        form.submit();
      }
    });
  });
</script>

หมายเหตุ:

ตัวแปร action คือ URL ของเว็บไซต์ร้านค้าที่รับค่า token และ source โดยผ่านการส่งข้อมูลแบบ POST
กรุณาดู การตั้งค่า สำหรับค่าและตัวแปรอื่นๆ ที่รองรับ

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

กรุณาดู การสร้างรายการโดยใช้ token และ source

คำสั่งใน OmiseCard

ร้านค้าสามารถใช้คำสั่งใน OmiseCard เพื่อปรับแต่งและแก้ไขคุณสมบัติการทำงานของฟอร์มการรับชำระเงิน

configure

คำสั่งในการตั้งค่าพื้นฐานสำหรับฟอร์มรับชำระเงิน ร้านค้าสามารถตั้ง public key ผ่านคำสั่งนี้ ปุ่มที่ถูกตั้งค่าผ่านคำสั่ง configureButton จะใช้การตั้งค่าเดียวกันกับคำสั่งข้างต้น แบบฟอร์มการรับชำระเงินที่เปิดโดยคำสั่ง open จะใช้การตั้งค่าเดียวกันกับคำสั่งข้างต้น

ร้านค้าต้องเรียกใช้คำสั่งนี้ก่อนที่จะใช้คำสั่ง open

Parameter	Type	Default	Description
config	object	{}	Default configuration for button(s).

OmiseCard.configure({
  publicKey: 'OMISE_PUBLIC_KEY',
});

configureButton

คำสั่งในการตั้งค่าสำหรับปุ่มในแบบฟอร์มการรับชำระเงิน หากปุ่มถูกตั้งอยู่นอก <form> ให้ใส่ค่า submitFormTarget เพื่อระบุปุ่มที่ต้องการใช้

Parameter	Type	Default	Description
selector	string	-	Selector for button.
config	object	{}	Configuration for button.

OmiseCard.configure({
  publicKey: 'OMISE_PUBLIC_KEY'
});

OmiseCard.configureButton('#checkout-button', {
  amount: 3000,
  currency: 'USD',
  buttonLabel: 'Pay 30 USD'
});

OmiseCard.configureButton('#checkout-button-alt', {
  amount: 100000,
  currency: 'THB',
  buttonLabel: 'Pay 1000 THB'
});

attach

การเชื่อมต่อค่าที่ถูกตั้งไว้แล้วผ่านคำสั่ง configureButton ไปที่ปุ่มที่ระบุไว้ เมื่อเชื่อมต่อกับปุ่มที่ระบุไว้ทั้งหมด การคลิกปุ่มดังกล่าวจะเป็นการส่งแบบฟอร์มชำระเงิน

OmiseCard.configureButton('#checkout-button', {
  publicKey: 'OMISE_PUBLIC_KEY',
  amount: 10000,
  frameLabel: 'Merchant Name',
  submitLabel: 'Pay',
});

OmiseCard.attach();

open

เปิดแบบฟอร์มรับชำระเงิน

ร้านค้าจะต้องเรียกใช้คำสั่ง configure ก่อนใช้คำสั่งนี้

Parameter	Type	Default	Description
config	object	{}	Configuration for target button.

OmiseCard.open({
  amount: 10000,
  submitFormTarget: '#checkout-form',
  onCreateTokenSuccess: (nonce) => {
    /* Handler on token or source creation.  Use this to submit form or send ajax request to server */
  },
  onFormClosed: () => {
    /* Handler on form closure. */
  },
})

การตั้งค่า

Data Attribute	Parameter	Description
`data-amount`	`amount`	(required) Amount shown on form
`data-key`	`publicKey`	(required) Your public key found on your dashboard
`data-button-label`	`buttonLabel`	Label to be displayed in the button embedded in your form. Default: Pay with Opn Payments
`data-currency`	`currency`	Currency to be displayed in the payment window. Default: `THB`
`data-default-payment-method`	`defaultPaymentMethod`	Default payment method. Default: `credit_card`.
`data-frame-description`	`frameDescription`	Description text displayed below header text
`data-frame-label`	`frameLabel`	Header text you want displayed in the popup window. Default: Omise
`data-hide-amount`	`hideAmount`	Whether to hide the amount on the submit button. Default: false
`data-image`	`image`	URI to your logo image. eg. `https://example.com/logo.png`
`data-locale`	`locale`	Language of form (`en`, `ja`, `th`). Default: `en`
`data-location`	`location`	Whether to include `postal_code` and `city` fields. Default: `no`
`data-other-payment-methods`	`otherPaymentMethods`	A comma-separated string of alternative payment method identifiers
`data-submit-label`	`submitLabel`	Label to be displayed in the submit button in pop-up window. Default: Pay.
`data-submit-form-target`	`submitFormTarget`	Selector for payment form. Default: form selector for button parent element
-	`onCreateTokenSuccess`	Callback for token or source creation event. One parameter is provided to the callback: the token or source identifier
-	`onFormClosed`	Callback for form closure event. No parameters are provided to the callback

ช่องทางการรับชำระเงินของแบบฟอร์มหน้าเช็คเอ้าท์สำเร็จรูป

ช่องทางรับชำระเงินด้านล่างนี้สามารถใช้ได้กับแบบฟอร์มหน้าเช็คเอ้าท์สำเร็จรูปของ Opn Payments ช่องทางการรับชำระเงินแต่ละรูปแบบขึ้นอยู่กับการตั้งค่าบัญชีของร้านค้าและประเทศที่ได้ลงทะเบียนบัญชีผู้ใช้ไว้

Alternative payment methods form example

Payment Method	Documentation	Supported Countries
`alipay`	Alipay	Thailand
`alipay_cn`	Alipay CN	Thailand, Singapore
`alipay_hk`	Alipay HK	Singapore
`bill_payment_tesco_lotus`	Bill Payment	Thailand
`boost`	Boost	Malaysia
`convenience_store`, `net_banking`, `pay_easy`*	Convenience Store, Pay Easy, Online Banking	Japan
`credit_card`	Credit Card	Thailand, Singapore, Japan
`dana`	DANA	Singapore
`duitnow_obw`	DuitNow Online Banking/Wallets	Malaysia
`duitnow_qr`	DuitNow QR	Malaysia
`fpx`	FPX	Malaysia
`gcash`	GCash	Singapore
`googlepay`	Google Pay	Thailand, Singapore
`grabpay`	GrabPay	Thailand, Singapore, Malaysia
`installment`	Installments	Thailand
`internet_banking`†, `internet_banking_bay`, `internet_banking_bbl`	Internet Banking	Thailand
`kakaopay`	KakaoPay	Singapore
`maybank_qr`	Maybank QR	Malaysia
`mobile_banking_bbl`	Bangkok Bank (Bualuang mBanking)	Thailand
`mobile_banking_kbank`	KBank (K PLUS)	Thailand
`mobile_banking_ktb`	Krung Thai (KTB NEXT)	Thailand
`mobile_banking_bay`	Krungsri (KMA)	Thailand
`mobile_banking_ocbc_pao`	OCBC Pay Anyone	Singapore
`mobile_banking_scb`	SCB (SCB Easy)	Thailand
`paynow`	PayNow	Singapore
`points_citi`	Pay With Points	Thailand
`promptpay`	PromptPay	Thailand
`rabbit_linepay`	Rabbit Line Pay	Thailand
`shopeepay`	ShopeePay	Thailand
`touch_n_go`	Touch 'n Go	Singapore
`truemoney`	TrueMoney Wallet	Thailand

* Source type ที่ถูกสร้างขึ้นมาจะอยู่ในรูปแบบ econtext
† ช่องทางการรับชำระเงินของอินเทอร์เน็ตแบงก์กิ้งทั้งหมดจะแสดงให้ผู้ใช้เป็นคนเลือก

กรุณาติดต่อ support@opn.ooo หากต้องการเปิดช่องทางรับชำระเงินมากขึ้น สำหรับร้านค้าที่มีบัญชีใช้งานจริงเท่านั้น

การเรียก token และ source โดยตรง

วิธีนี้ให้อิสระกับร้านค้าในการเลือกใช้ช่องทางการรับชำระเงินมากที่สุด โดยร้านค้าจะต้องเป็นผู้สร้างแบบฟอร์มการรับชำระเงินและจัดการ event เองทั้งหมด

Opn Payments ไม่อนุญาตให้ใช้ค่าของ name เป็นตัวกำหนดชื่อให้กับ <input> เพราะข้อมูลบัตรและข้อมูลการทำรายการอื่นๆ จะถูกส่งไปที่เซิร์ฟเวอร์ของร้านค้า กรุณาใช้ค่าของ id เป็นตัวกำหนดแทน วิธีนี้จะช่วยป้องกันไม่ให้ข้อมูลบัตรของผู้ซื้อถูกส่งไปที่เซิร์ฟเวอร์ของร้านค้า กรุณาดู แนวทางปฏิบัติเพื่อความปลอดภัย สำหรับข้อมูลเพิ่มเติม

การใช้งาน

ร้านค้าจะต้องสร้าง <script> เพื่อโหลด Omise.js

<script type="text/javascript" src="https://cdn.omise.co/omise.js"></script>

เมื่อโหลดสำเร็จแล้วตัวแปร Omise จะสามารถใช้งานได้บนหน้าเว็บ

คำสั่งของ Omise

ร้านค้าสามารถใช้วิธีดังต่อไปนี้เพื่อสร้าง token หรือ source ที่ใช้ได้ครั้งเดียว (one-time-use)

setPublicKey

ตั้งค่า public key เพื่อยืนยันตัวตนกับ Opn Payments

Parameter	Type	Description
key	string	(required) Public key found on your dashboard

Omise.setPublicKey("OMISE_PUBLIC_KEY");

createToken

สร้าง token จากเซิร์ฟเวอร์ของ Opn Payments โดย token นี้จะสามารถนำไปใช้สร้างรายการได้ทันทีหรือจัดเก็บไว้กับ customer object

Parameter	Type	Description
type	string	(required) `card`
tokenParameters	object	(required) Request parameters for token
callback	function	(required) A function that will be called when the request with Omise server is completed. Two parameters are provided to the callback: the HTTP status code of the response and the response itself

tokenParameters = {
  "city": "New York",
  "country": "US",
  "expiration_month": 2,
  "expiration_year": 2022,
  "name": "Somchai Prasert",
  "number": "4242424242424242",
  "phone_number": "0123456789",
  "postal_code": 10320,
  "security_code": 123,
  "state": "NY",
  "street1": "476 Fifth Avenue"
};

Omise.createToken("card",
                  tokenParameters,
                  function(statusCode, response) {

  // response["id"] is token identifier

  console.log(response)
});

createSource

สร้าง source จากเซิร์ฟเวอร์ของ Opn Payments โดย source นี้จะสามารถนำไปใช้สร้างรายการได้ทันที อ่านเพิ่มเติมเกี่ยวกับชนิดของ source ได้ที่ Source API

Parameter	Type	Description
type	string	(required) Source type
sourceParameters	object	(required) Request parameters for source
callback	function	(required) A function that will be called when the request with Omise server is completed. Two parameters are provided to the callback: the HTTP status code of the response and the response itself

sourceParameters = {
  "amount": 12345,
  "currency": "THB",
  "phone_number": "0123456789"
}

Omise.createSource("truemoney",
                   sourceParameters,
                   function(statusCode, response) {

  // response["id"] is source identifer

  console.log(response)
});

การสร้างรายการโดยใช้ token และ source

สำหรับการใช้ token เพื่อสร้างรายการรับชำระ กรุณาดู วิธีสร้างรายการ หากต้องการรายละเอียดเพิ่มเติมหรือตัวอย่างการเขียนโค้ด สามารถดูได้ที่ Charge API

สำหรับการสร้าง source สามารถอ่านเพิ่มเติมได้ที่ คู่มือการใช้งาน API ภายใต้หัวข้อ Payment methods

CDNs

ร้านค้าสามารถดาวน์โหลด Omise.js ได้จาก:

https://cdn.omise.co/omise.js