Omise.js

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

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

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

โอมิเซะแนะนำเป็นอย่างยิ่งให้เปิดการใช้งาน HTTPS บนเว็บไซต์ทั้งหมด

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

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

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

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

Image

ตัวอย่าง

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

ร้านค้าสามารถดู Source code ของ Omise.js ได้บน GitHub: https://github.com/omise/omise.js

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

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

Credit Card form example

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


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

แบบฟอร์มชำระเงินสำเร็จรูปสามารถตั้งค่าโดยใช้ ตัวแปร 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
  • กรุณาดู การตั้งค่า สำหรับค่าและตัวแปรอื่นๆ ที่รองรับ

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

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

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

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

กรุณาดู การสร้างรายการโดยใช้ 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 Omise
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: Checkout.
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

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

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

Alternative payment methods form example

Payment Method Documentation Supported Countries
alipay Alipay Thailand
bill_payment_tesco_lotus Bill Payment Thailand
convenience_store*, net_banking*, pay_easy* Convenience Store, Pay Easy, Online Banking Japan
credit_card Credit Card Thailand, Singapore, Japan
installment Installments Thailand
internet_banking†, internet_banking_bay, internet_banking_bbl, internet_banking_ktb, internet_banking_scb Internet Banking Thailand

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

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

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

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

โอมิเซะไม่อนุญาตให้ใช้ค่าของ 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 เพื่อยืนยันตัวตนกับโอมิเซะ

Parameter Type Description
key string (required) Public key found on your dashboard
Omise.setPublicKey("OMISE_PUBLIC_KEY");

createToken

สร้าง token จากเซิร์ฟเวอร์ของโอมิเซะ โดย 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 จากเซิร์ฟเวอร์ของโอมิเซะ โดย 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 (สิงคโปร์)
  • https://cdn2.omise.co/omise.js (ญี่ปุ่น)