Omise.js

Omise.js เป็น JavaScript Library ที่พัฒนาขึ้นเพื่อให้นักพัฒนาสามารถนำระบบรับชำระเงินของ Omise ไปเชื่อมต่อกับเว็บไซต์ได้อย่างรวดเร็ว โดยไม่ต้องอาศัยการเขียนโค้ดมากนัก

Country support

Country Payment methods
Thailand credit_card, internet_banking, alipay, bill_payment_tesco_lotus
Japan credit_card, pay_easy, net_banking, convenience_store

Payment API

setPublicKey(key)

กำหนด public key เพื่อใช้การในยืนยันตัวตนกับ Omise API

Argument Value
key (required) key is the public keys that you can find in your dashboard once you're signed in.

Example

<script>
  Omise.setPublicKey("pkey_test_4xpip92iqmehclz4a4d");
</script>

createSource(type, object, callback)

ส่งข้อมูลไปยัง Omise API เพื่อสร้าง source ที่ใช้เพื่อเป็นตัวแทนในการรับชำระเงิน

Argument Value
type (required) type of source you want to create. Visit Source API for the source payment type.
object (required) a JavaScript object containing the 2 values required for a source: currency, amount. Parameters reference can be found here.
callback (required) a callback that will be triggered whenever the request with Omise server is completed (for both error and success). Two arguments will be passed back into the callback. The first argument is HTTP status code; 200 for success or others for error such as 400. The second argument is the response from the Omise API.

Example

<script>
  Omise.createSource(type, object, function(statusCode, response) { /* callback */ });
</script>

createToken(type, object, callback)

ส่งข้อมูลบัตรไปยัง Omise vault เพื่อสร้าง token ที่ใช้เพื่อเป็นตัวแทนของบัตรในการรับชำระเงิน

Argument Value
type (required) type of token you want to create. For now this value must be card.
object (required) a javascript object containing the 5 values required for a card: name, number, expiration_month, expiration_year, security_code. Parameters reference is here.
callback (required) a callback that will be triggered whenever the request with omise server completes (for both error and success). Two arguments will be passed back into the callback. The HTTP statusCode, like 200 for success or 400 for bad request, etc... The second argument is the response from the Omise API.

ตัวอย่างการใช้งาน

ตัวอย่างเว็บไซต์ที่ทำการส่งข้อมูลบัตรเครดิตไปยัง Omise เพื่อแปลงเป็น Token ก่อนส่งไปตัดเงินที่เซอร์เวอร์ของร้านค้า

เริ่มจากเพิ่มคำสั่งเรียกใช้ Omise.js ในหน้ากรอกบัตรเครดิต โดยสามารถเลือกจาก CDN ที่ใดที่หนึ่งจากที่เราเตรียมไว้

CDN หลัก (สิงคโปร์)

<script src="https://cdn.omise.co/omise.js.gz"></script>

CDN รอง (ญี่ปุ่น)

<script src="https://cdn2.omise.co/omise.js.gz"></script>

เมื่อเสร็จแล้วให้นำ public key ที่ได้จาก dashboard เพิ่มลงใน JavaScript โดยใช้คำสั่งต่อไปนี้ (อ่านเพิ่มเกี่ยวกับการยืนยันตัวตน).

Omise.setPublicKey("pkey_test_4xpip92iqmehclz4a4d");

ตอนนี้หน้าเว็บไซต์พร้อมที่จะส่งข้อมูลบัตรเครดิตไปยัง Omise อย่างปลอดภัยแล้ว ต่อจากนี้จะเป็นการสร้างฟอร์มรับข้อมูลบัตรเครดิตจากลูกค้า โดยเขียนด้วย HTML ได้ดังนี้

HTML (index.html)

<body>
  <!--
  This is your checkout form.

  NOTE: Here, we're using `data-name` to prevent sending credit card information fields to the backend server via HTTP Post
  (according to the security best practice https://www.omise.co/security-best-practices#never-send-card-data-through-your-servers).
  -->
  <form id="checkout-form" action="/checkout.php" method="POST">

    <!-- This is a hidden field you must add, to input omise token -->
    <input type="hidden" name="omiseToken" />

    <!-- This is card information fields that we required for tokenization -->
    <div>
      <label>Card Number</label>
      <input type="text" data-name="cardNumber" placeholder="••••••••••••••••" />
    </div>

    <div>
      <label>Name on card</label>
      <input type="text" data-name="nameOnCard" placeholder="Full Name" />
    </div>

    <div>
      <label>Expiry date</label>
      <select data-name="expiryMonth">
        <option value="">MM</option>
        <option value="1">1</option>
        <!-- ... -->
        <option value="12">12</option>
      </select>

      <select data-name="expiryYear">
        <option value="">YYYY</option>
        <option value="2017">2017</option>
        <!-- ... -->
        <option value="2025">2025</option>
      </select>
    </div>

    <div>
      <label>Security code</label>
      <input type="text" data-name="securityCode" placeholder="123" />
    </div>

    <div>
      <button>Checkout</button>
    </div>
  </form>

  <!-- Include omise.js. -->
  <script src="https://cdn.omise.co/omise.js"></script>

  <!-- Include your app.js. -->
  <script src="app.js"></script>
</body>

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

JavaScript (app.js)

(function() {

'use strict';

Omise.setPublicKey('YOUR_PUBLIC_KEY');

var cardForm     = document.getElementById('card-form');
var checkoutForm = document.getElementById('checkout-form')

cardForm.addEventListener('submit', submitHandler, false);

// Submit handler for checkout form.
function submitHandler(event) {
  event.preventDefault();

  var cardInformation = {
    name:             cardForm.nameOnCard.value,
    number:           cardForm.cardNumber.value,
    expiration_month: cardForm.expiryMonth.value,
    expiration_year:  cardForm.expiryYear.value,
    security_code:    cardForm.securityCode.value
  };

  Omise.createToken('card', cardInformation, function(statusCode, response) {
    if (statusCode === 200) {
      // Success: send back the TOKEN_ID to your server. The TOKEN_ID can be
      // found in `response.id`.
      checkoutForm.token.value = response.id;
      checkoutForm.submit();
    }
    else {
      // Error: display an error message. Note that `response.message` contains
      // a preformatted error message. Also note that `response.code` will be
      // "invalid_card" in case of validation error on the card.
    }
  });
}

})();

ดูตัวอย่างซอร์สโค้ดฉบับเต็มของ HTML และ JavaScript ได้ที่นี่

สำหรับโปรแกรมในฝั่งเซอร์เวอร์ของร้านค้า ที่สร้างขึ้นเพื่อส่งคำสั่ง Charge มายัง Omise โดยการส่ง Token และราคารวมที่ต้องการรับชำระ มายังเซอร์เวอร์ของ Omise ซึ่งสามารถพัฒนาได้ตามตัวอย่างต่อไปนี้

PHP (checkout.php)

<?php
require_once dirname(__FILE__).'/omise-php/lib/Omise.php';
define('OMISE_PUBLIC_KEY', 'YOUR_PUBLIC_KEY');
define('OMISE_SECRET_KEY', 'YOUR_SECRET_KEY');

try {
    if ($_POST['omiseSource']) { // For alternative payment methods.
        $charge = OmiseCharge::create(array(
            'amount'     => 10000,
            'currency'   => 'thb',
            'source'     => $_POST['omiseSource'],
            'return_uri' => 'https://www.store.com/callback'
        ));
    } elseif ($_POST['omiseToken']) { // For credit card payment method.
        $charge = OmiseCharge::create(array(
            'amount'     => 10000,
            'currency'   => 'thb',
            'card'       => $_POST['omiseToken'],
            'return_uri' => 'https://www.store.com/callback' // Only need when the 3-D Secure payment is enabled.
        ));
    }

    if ($charge['status'] == 'failed') {
        // Charge is failed.
        // Handle the failure case.
        exit;
    }

    if (! is_null($charge['source'])) { // For alternative payment methods.
        if ($charge['source']['type'] == 'bill_payment_tesco_lotus') {
            // display barcode from $charge['source']['references']['barcode']
            // i.e.
            echo '<img src="' . $charge['source']['references']['barcode'] . '"/>';
            exit;
        } else {
            // redirect users out to the `authorize_uri` location.
            header('Location: '. $charge['authorize_uri']);
            exit;
        }
    } else { // For credit card payment method.
        if ($charge['status'] == 'successful') {
            // Charge complete (authorized and captured).
            // ..
        } elseif ($charge['status'] == 'pending' && $charge['authorized'] && ! $charge['paid']) {
            // 'Authorized only' case.
            // ..
        } elseif ($charge['status'] == 'pending' && ! $charge['authorized'] && ! $charge['paid'] && ! is_null($charge['authorize_uri'])) {
            // 3-D Secure payment is enabled.
            // redirect users out to the `authorize_uri` location.
            header('Location: '. $charge['authorize_uri']);
            exit;
        }
    }
} catch (Exception $e) {
    // Handle an execption case.
}
?>

เมื่อทำการ Charge แล้ว หน้าจอจะแสดงตัวอย่างผลลัพธ์ของการทำรายการ ซึ่งร้านค้าสามารถเลือกที่จะแสดงหรือไม่แสดงก็ได้ โดยรายการ Charge ที่เกิดขึ้นสามารถตรวจสอบได้จาก Dashbord ของร้านค้า

ฟอร์มกรอกบัตรเครดิตสำเร็จรูป

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

ก่อนหน้านี้ฟอร์มกรอกบัตรเครดิตจะแยกเป็น library ชื่อ card.js เพื่อความสะดวกในการใช้งานจึงรวมเข้ากับ omise.js และเพิ่มความสามารถในการปรับแต่งเข้าไปอีก

Credit Card form example

Data attributes

Name type default description
data-key string "" (required) the public key which can be found on your dashboard
data-amount number 0 (required) the amount to be paid in the smallest unit of the currency, e.g. Satangs (100 Satangs = THB 1)
data-currency string THB the currency to be displayed in the payment window (THB, USD, JPY it can be lowercase)
data-image string "" the URI to your logo image. eg. http://example.com/logo.png
data-frame-label string Omise the header text you want displayed in the credit card popup window
data-frame-description string "" the description text will display below header text
data-submit-label string Checkout the label to be displayed in the submit button in credit card popup window
data-button-label string Pay with Omise the label to be displayed in the button that is embeded in your form
data-location string no presence of this attribute with any non-blank value indicates that the popup will have the postal code and city fields included (yes or no)
data-locale string en language of credit card form. (en, ja, th)

ตัวอย่าง

ท่านสามารถเรียกใช้ฟอร์มกรอกบัตรเครดิตสำเร็จรูปได้ตามตัวอย่างต่อไปนี้

HTML

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="initial-scale=1, maximum-scale=1">
  <title>Example using `omise.js` credit card form</title>
</head>
<body>
<form class="checkout-form" name="checkoutForm" method="POST" action="/checkout">
  <script type="text/javascript" src="https://cdn.omise.co/omise.js"
          data-key="YOUR_PUBLIC_KEY"
          data-frame-label="Merchant site name"
          data-frame-description="Merchant site description"
          data-amount="10000"
          data-currency="usd">
  </script>
</form>

</body>
</html>

CSS

.checkout-form > button {
  display: inline-block;
  padding: 1em;
  border: 0;
  background-color: #1A53F0;
  color: white;
  outline: none;
  border-radius: 4px;
}

Omise.js จะสร้างปุ่ม Pay with Omise ไว้บนหน้าเว็บ เมื่อกดปุ่มจะมีหน้าจอสำหรับกรอกบัตรเครดิตเปิดขึ้นมา โดยมี <input type="hidden" name="omiseToken"> อยู่ในฟอร์มอัตโนมัติเมื่อกด submit

การรับชำระเงินผ่านช่องทางอื่น

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

1. หากต้องการเปิดรับชำระเงินผ่านช่องทางอื่นๆ สามารถติดต่อและแจ้งความประสงค์กับทีมงานของเราได้ที่ https://www.omise.co/support

2. รองรับการทำงานบน API เวอร์ชัน 2017-11-02 ขึ้นไป สามารถอัพเกรดที่หน้า dashboard

Alternative payment methods form example

Name type default description
data-default-payment-method string credit_card The main payment method.
credit_card
internet_banking
alipay
bill_payment_tesco_lotus
pay_easy
net_banking
convenience_store
data-other-payment-methods string "" the alternative payment methods.
internet_banking - display all bank
internet_banking(scb, ktb, bay, bbl) - specific banks
alipay
bill_payment_tesco_lotus
credit_card
pay_easy
net_banking
convenience_store

ตัวอย่าง

ท่านสามารถเรียกใช้ฟอร์มช่องทางอื่นๆ ได้ตามตัวอย่างต่อไปนี้

HTML (checkout.html)

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="initial-scale=1, maximum-scale=1">
  <title>Example using `omise.js` alternative payment form</title>
</head>
<body>
<form class="checkout-form" name="checkoutForm" method="POST" action="checkout.php">
  <script type="text/javascript" src="https://cdn.omise.co/omise.js"
          data-key="YOUR_PUBLIC_KEY"
          data-frame-label="Merchant site name"
          data-frame-description="Merchant site description"
          data-default-payment-method="alipay"
          data-other-payment-methods="internet_banking, bill_payment_tesco_lotus, alipay, credit_card"
          data-amount="10000"
          data-currency="usd"
          data-button-label="Click to see an example">
  </script>
</form>

</body>
</html>

Omise.js จะสร้างปุ่ม Pay with Omise ไว้บนหน้าเว็บ เมื่อกดปุ่มจะมีหน้าจอสำหรับชำระเงินเปิดขึ้นมา โดยมี <input type="hidden" name="omiseSource"> และ <input type="hidden" name="omiseToken"> อยู่ในฟอร์มอัตโนมัติเมื่อกด submit

ตัวอย่าง PHP (checkout.php)

<?php
require_once dirname(__FILE__).'/omise-php/lib/Omise.php';
define('OMISE_PUBLIC_KEY', 'pkey_test_52jyu0r8o4307z0zz00');
define('OMISE_SECRET_KEY', 'skey_test_52jyu0r8mim84ylp454');


if ($_POST['omiseSource']) { // for alternative payment methods
  $charge = OmiseCharge::create(array(
    'amount'   => 10000,
    'currency' => 'thb',
    'source'     => $_POST["omiseSource"],
    'type' => 'alipay'
  ));
} elseif ($_POST['omiseToken']) { // for credit card
  $charge = OmiseCharge::create(array(
    'amount'   => 10000,
    'currency' => 'thb',
    'card'     => $_POST["omiseToken"]
  ));
}

if ($charge['status'] == 'successful') {
  // Update order status to 'successful'.
} else {
  // Update order status to 'failed'.
}
?>

ปรับแต่งฟอร์มกรอกบัตรเครดิตผ่าน JavaScript

หน้าจอฟอร์มกรอกบัตรเครดิตของ Omise.js ถูกออกแบบให้ปรับแต่งได้ง่าย ผ่าน OmiseCard ร้านค้าจึงสามารถเพิ่มปุ่ม หรือปรับข้อความได้ด้วยตนเอง

configure(config)

ตั้งค่าเริ่มต้นให้กับทุกปุ่มที่ต้องการเปิดหน้าจอสำหรับกรอกบัตรเครดิต สำหรับรายละเอียดฟิลด์ต่างๆ สามารถดูได้ที่ Data attributes

Name type default description
config object {} Default config all button. please see available config from example below.

ตัวอย่าง

// Set default config.
OmiseCard.configure({
  publicKey:        'YOUR_PUBLIC_KEY',
  amount:           10000,
  currency:         'thb',
  image:            'YOUR_LOGO_URL',
  frameLabel:       'Merchant name',
  frameDescription: 'Merchant description',
  submitLabel:      'Pay',
  buttonLabel:      'Pay with Omise',
  location:         'no',
  defaultPaymentMethod: '',
  otherPaymentMethods: [],
  submitFormTarget: null,
});

configureButton(selector, config)

เป็นการตั้งค่าเฉพาะให้กับปุ่ม เมื่อมีปุ่มเปิดหน้าจอกรอกข้อมูลบัตรมากกว่าหนึ่งปุ่ม และต้องการให้แต่ละปุ่มแสดงผลหน้ากรอกบัตรเครดิตไม่เหมือนกัน

Name type default description
selector string {} Selector for target button.
config object {} Configure for button. (You can using config same as default.)

ตัวอย่าง

// Default configure
OmiseCard.configure(/* ...config */);


// Button configure will merged and override with default configure.
// And has effect with this button only.
OmiseCard.configureButton('#checkout-button', {
  amount:           10000,
  currency:         'thb',
  image:            'YOUR_LOGO_URL',
  frameLabel:       'Merchant name',
  frameDescription: 'Merchant description',
  submitLabel:      'Pay',
  buttonLabel:      'Pay with Omise',
  location:         'no',
  billingName:      '',
  billingAddress:   '',
  submitFormTarget: '#checkout-form',
});

open(config)

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

โดยสามารถใช้ onCreateTokenSuccess เพื่อควบคุมการทำงานเมื่อสร้าง Token สำเร็จ เช่น ส่งค่าไปที่ระบบหลังบ้านหรือเซ็ทค่าต่างๆ ก่อนที่จะ submit form

และ onFormClosed สำหรับจัดการเมื่อผู้ซื้อปิดฟอร์มการจ่ายเงิน

Name type default description
config object {} Configure for button. (You can using config same as default.)
OmiseCard.open({
  frameLabel: 'Esimo',
  frameDescription: 'Invoice #3847',
  amount: 10000,
  onCreateTokenSuccess: (token) => {
    /* Your code, e.g., submit form or send ajax request to server */
  },
  onFormClosed: () => {
    /* Your handler when form was closed */
  },
})

attach()

ยืนยันให้การตั้งค่ามีผลกับปุ่มทั้งหมดที่ได้ตั้งค่าไว้ด้วยคำสั่ง configureButton

ตัวอย่าง

OmiseCard.configure({
  publicKey: 'YOUR_PUBLIC_KEY',
  amount: 10000
});

OmiseCard.configureButton('#checkout-button', {
  frameLabel: 'Merchant name',
  submitLabel: 'PAY RIGHT NOW !',
});

OmiseCard.attach();

ซอร์สโค้ด

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