Active Merchant

Active Merchant เป็น library ที่พัฒนาขึ้นเพื่ออนุญาตและสนับสนุนการทำงานของระบบรับชำระเงินที่มีพื้นฐานการทำงานของ API ที่แตกต่างกันบนเว็บไซต์ Shopify โดย library นี้เจาะจงพัฒนาเพื่อกลุ่มผู้ใช้งาน ruby โดยเฉพาะ ในปัจจุบันพบว่าได้รับความนิยมสูงในกลุ่มแอปพลิเคชัน ruby ที่ดำเนินการเกี่ยวกับธุรกิจด้านการเงิน

github.com/Shopify/active_merchant

Active Merchant รองรับระบบรับชำระเงิน Omise เวอร์ชัน 1.50.0 ขึ้นไป

การติดตั้ง

ติดตั้งจาก GitHub

Source code บน GitHub

git clone git://github.com/Shopify/active_merchant.git

ติดตั้งจาก RubyGems

gem install activemerchant
gem install json

หรือหากใช้ Bundler ให้เพิ่มไฟล์เหล่านี้ลง Gemfile:

gem 'activemerchant'
gem 'json'

การใช้งาน

วิธีการชำระเงินผ่านบัตรเครดิต การสร้าง Customer และการคืนเงิน (refund) ทั้ง 2 แบบ

1. กระบวนการและขั้นตอน

เพื่อการดำเนินงานที่สอดคล้องตามระเบียบและนโยบายความปลอดภัยของมาตรฐาน PCI ร้านค้าจะต้องไม่ส่งข้อมูลบัตรไปยังเซิร์ฟเวอร์ของตน เว้นเสียแต่ว่าจะผ่านการประเมินและได้รับรองมาตรฐาน PCI-DSS ฉบับปัจจุบันเท่านั้น

การใช้ Omise.js

  1. ในหน้าเช็คเอาท์ ลูกค้าของคุณ (ผู้ถือบัตร) จะทำการกรอกข้อมูลบัตรลงในฟอร์มรับชำระเงินที่หน้าเว็บของร้านค้า (ไม่ต้องห่วงว่าผู้ถือบัตรจะถูก redirect ไปยังหน้าต่างใหม่หรือปรากฏแบรนด์ Omise ที่ใด เพราะระบบเราทำงานอยู่เบื้องหลังเท่านั้น!)
  2. Omise.js จะทำหน้าที่ส่งข้อมูลจากเบราว์เซอร์ผู้ถือบัตรมายังเซิร์ฟเวอร์ Omise โดยตรงผ่านโปรโตคอล HTTPS
  3. ระบบจะมี respose กลับไปเพื่อระบุว่าบัตรที่ใช้ผ่านการ authorize หรือไม่ (สามารถตรวจสอบได้จากค่า card.security_code_check) หากบัตรได้รับการ authorize จะมี token ตอบกลับ
  4. เว็บไซต์ของร้านค้าจะส่ง token ที่ได้รับต่อไปยังเซิร์ฟเวอร์ และมีการสร้าง charge เรื่อยไปจนสิ้นสุดขั้นตอนที่การ capture ยอดเงิน

หมายเหตุ:
ในขั้นตอนที่ 3 หากบัตรไม่ผ่านการ authorize card.security_code_check ซึ่งอาจเกิดจากการกรอกหมายเลขยืนยันบัตร 3 หลัก (CVV) วันหมดอายุ หรือหมายเลขบัตร 16 หลัก ผิดไป เราแนะนำให้ไซต์ของร้านค้าแสดงข้อความแจ้งให้ผู้ถือบัตรทำการกรอกข้อมูลใหม่

ในขั้นตอนที่ 4 Omise จะทำการ capture ยอดเงิน หากรายการ fail แต่ token ผ่านการ authorize นั่นหมายถึงว่าบัตรมีวงเงินไม่เพียงพอ

2. โค้ด

การทำธุรกรรมใดๆ ผ่านระบบของเรา ผู้ใช้งานจะต้องทำการยืนยันตัวตนด้วย keys ที่รับมาเสียก่อน
สร้างบัญชีหรือลงชื่อเข้าใช้งานเพื่อรับ key ทั้ง 2 ชุด

require 'json'
require 'active_merchant'

gateway = ActiveMerchant::Billing::OmiseGateway.new(
  public_key: "pkey_test_5033ct7tcw7l4rb3bjz",
  secret_key: "skey_test_5033ctmg92i4mhfq3ru"
)

ส่วนใน rails initializer config/initializers/omise.rb สามารถโหลด keys ได้จาก secrets.yml

GATEWAY = ActiveMerchant::Billing::OmiseGateway.new(
  public_key: "pkey_test_5033ct7tcw7l4rb3bjz",
  secret_key: Rails.application.secrets.omise_secret_key
)

หากใช้ Heroku ให้ตั้งค่า secret key ด้วย ENV variables

GATEWAY = ActiveMerchant::Billing::OmiseGateway.new(
  public_key: "pkey_test_5033ct7tcw7l4rb3bjz",
  secret_key: ENV["omise_secret_key"]
)

การสร้าง charge ด้วย token

ก่อนจะรับชำระเงินได้ ร้านค้าต้องมี token ซึ่งใช้เป็นตัวแทนของบัตรเสียก่อน โดย token นี้จะได้รับมาจาก Omise.js จากฝั่งเบราว์เซอร์ผู้ถือบัตร ตัวอย่าง Omise.js บน github.com/omise/omise.js

# Example, token from an ajax post in a Rails app
token = params["token"] # tokn_test_50frulul1q6bn6qjcre

# Amount must be an Integer including in cents (Thai Baht Satangs)
amount = 10000  # => 100.00 THB

# Capture the full amount
charge = gateway.purchase(amount, nil, { token_id: token })

charge.message
# => "Success"

Authorize and Hold

ตัวอย่างนี้เป็นการ authorize และ hold ยอดเงินที่ได้รับชำระมาไว้ก่อน
ร้านค้าสามารถทำการ capture ยอดได้ในภายหลัง เช่น capture เมื่อสินค้าพร้อมจัดส่ง ระยะเวลาการ hold จะขึ้นอยู่กับธนาคารผู้ออกบัตร โดยอาจ hold ได้เพียงไม่กี่วันหรือนานหลายเดือน

# You got this token from Omise.js Javascript
token = "tokn_test_50fs5cznlz4vp72uhdu"

# Amount must be an Integer including in cents (Thai Baht Satangs)
amount = 10000  # => 100.00 THB

# Hold a charge without capture, by adding the option 'capture: false'
authorize = gateway.authorize(amount, nil, { token_id: token, capture: false })

# Now let's capture that charge, i.e. now that your product is ready.
charge_id = authorize.params["id"]
charge = gateway.capture(amount, charge_id)

charge.message
# => "Success"

จัดเก็บบัตรในรูปแบบ Customer

การจัดเก็บบัตรไว้ในรูปแบบ Customer สามารถเพิ่มความสะดวกสบายให้ได้ทั้งผู้ซื้อและผู้ขาย ในส่วนของผู้ถือบัตรฟีเจอร์นี้จะอนุญาต one-click checkout คือสามารถให้ระบบจดจำข้อมูลบัตรไว้สำหรับการชำระครั้งต่อๆ ไป ส่วนธุรกิจที่มีการรับชำระแบบต่อเนื่องซ้ำๆ ก็ยังได้รับความสะดวกสบายจากฟีเจอร์นี้เช่นกัน

หมายเหตุ: การจัดเก็บบัตรไว้ในรูปแบบ Customer จะต้องได้รับการยินยอมจากผู้ถือบัตรก่อน

การสร้าง Customer จะมีขั้นตอนเพิ่มมาจากการสร้าง charge ด้วย token หนึ่งข้อคือระบบจะแปลง token ธรรมดาๆ เป็น Customer object และจะทำการสร้าง charge ที่ Customer นั้นโดยตรง

อย่างไรก็ตาม Omise.js ยังจะทำหน้าที่สร้าง token ตามเดิม


# Example token from Omise.js
token = "tokn_test_50frulul1q6bn6qjcre"

# Create a customer from the token
customer = gateway.store(
  nil,
  {
    token_id: token,               # Required: Token
    email: "john.doe@gmail.com",   # Optional
    description: "Customer ID: 37" # Optional
  }
)

# Amount must be an Integer including in cents (Thai Baht Satangs)
amount = 10000  # => 100.00 THB

# You should store the customer ID in your database
# so that you can charge it anytime later.
customer_id = customer.params["id"]

# Let's charge this customer
charge = gateway.purchase(amount, nil, { customer_id: customer_id })

charge.message
# => "Success"

การคืนเงิน (refund)


# Capture 100 THB from the credit card (as previous example)
charge = gateway.purchase(amount, nil, { token_id: token })

# We need to use the charge ID for a refund
charge_id = charge.params["id"]

# Refund the full amount using charge_id
refund = gateway.refund(amount, charge_id)

refund.message
# => "Success"

สามารถทำการคืนเงินเพียงบางส่วนได้ โดยให้ระบุจำนวนเงินใน refund method

refund = gateway.refund(amount/2.0, charge_id)

หมายเหตุ: สำหรับฟีเจอร์ Ruby อื่นๆ ที่ใช้กับ Omise API ไปที่ omise-ruby rubygem

E-commerce platform ที่ทำงานบน/ทำงานร่วมกับ/ใช้ ActiveMerchant

  1. SpreeCommerce: เป็น platform opensource ที่มาพร้อมฟังก์ชันค่อนข้างครบครันสำหรับร้านค้าของทางฝั่ง Ruby ถูกออกแบบมาให้ปรับเปลี่ยนและพัฒนาต่อยอดได้ง่าย (Omise Spree Demo)

  2. ror_ecommerce: เป็น e-commerce platform ที่เขียนขึ้นด้วย Ruby on Rails 4 ทั้งหมด ถูกพัฒนาเพื่อร้านค้าขนาดย่อมๆ โดยเฉพาะ