ActiveMerchant 使用與實做

講解 ActiveMerchant 的使用方式，以及怎樣實做新的金流串流介面。

Transcript

1. github: http://github.com/lulalala twitter: @lulalala_it
2. ✵≛工商時間⍟✬ ↑LOGO URL↑
3. ✵≛工商時間⍟✬ 找團購 團購好生活
4. ✵≛工商時間⍟✬ 預測油價/加油站 油價公告
5. ✵≛工商時間⍟✬ 找麥噹噹優惠 行動優惠券
6. ✵≛技術的工商時間⍟✬ cells 需要 render 同一種 view 許多次 有用 memcached Cells-Collection gem https://github.com/GoodLife/cells-collection
7. ✵≛技術的工商時間⍟✬ 只用 Rails 的 to_json 硬幹 API 的 Rails-Patch-Json-Encode gem https://github.com/GoodLife/rails-patch-json-encode
8. ✵≛技術的工商時間⍟✬ 想寫個跟台灣新聞有關的網站的： 台灣新聞網站parser https://github.com/lulalala/taiwanese_news_parser
9. ✵≛技術的工商時間⍟✬ 一個 Rails 想有多個 logger 的 multi_logger gem https://github.com/lulalala/multi_logger
10. ✵≛工商時間⍟✬ 找Rails工作 ryan@goodlife.tw
11. ✵≛工商時間結束⍟✬ ↑LOGO URL↑
12. ActiveMerchant 使用與實作
13. 網路開店平台 (用Rails做的） • GitHub Store: https://github.myshopify.com/ • Wikipedia Store: http://shop.wikimedia.org/ 有名的開源程式碼： • ActiveMerchant • Batman.js • liquid
16. ActiveMerchant有兩種 Gateway Integration (Offsite payment) • 需接觸信用卡卡號 (網站安全就要注意) • 使用金流API通知扣 款金額 • 官網教學 • RailsCasts • 不需接觸信用卡卡號 • 跳轉到金流網站付款 • 付款完成後跳回來 • 金流網站另行透過你 提供的API通知付款 成功
18. OH NO DO I COUNT AS MAN?
19. 初音只是個軟體
20. 初音只是個軟體 程設猿欣賞軟體也是很正常滴
21. Offsite Payment (Integration) 原理 1. 準備一個 form 內含金額呀訂單編號呀 使用者按下按鈕跑到金流業者那付款 2. 使用者在金流網站完成付款 3. 付款完金流網站會把使用者導回你的網站 4. 付款後金流業者會通知你的伺服器
23. Offsite Payment (Integration) 兩個部份 helper 也就是 form helper 產生付款頁面的表單 （步驟1） notification 解析金流那裡傳過來 的付款通知的 class （步驟4）
24. Setup Add gem gem ‘active_merchant’ then > bundle install
25. Setup # in initializer ActionView::Base.send(:include, ActiveMerchant::Billing::Integrations::ActionViewHelper) if !Rails.env.production? ActiveMerchant::Billing::Base.mode = :test end
26. Form #1 payment_service_for( @order.id, '001253', #你在金流業者那的ID :amount => @order.total, #金額 :service => :smile_pay, #金流業者 :html => { :authenticity_token => false, :enforce_utf8 => false }) do |service| ＊這在 view 中
27. Form #2 在 block 裡面 service.notify_url( payment_notify_order_url(@order) ) service.customer :name => @order.name, :phone => @order.phone, :email => @order.email ＊這在 view 中
28. Form #3 各金流專有設定 case @order.payment_method when :paypal service.currency 'USD' service.add_field('lc','zh_TW') service.cancel_return_url order_url(@order) service.return_url order_url(@order) end 這裡都是個別金流業者的專屬參數 有些會提供 helper method 有些還是使用 add_field() 方法添加比較簡單 ＊這在 view 中
29. Form #4 結尾 submit_tag("Save changes") end ＊這在 view 中
30. Form 使用時 請對照金流業者提供的 API 文件， 以及閱讀實做本身的原始碼， 知道有甚麼方法可以用， 以及什麼參數得自己 add_field() 加入
31. Notification #1 (通知) def notify @order = Order.find(params[:id]) am_class = ActiveMerchant::Paypal notification = am_class.notification(request.raw_post) ＊這在 controller中
32. Notification #2 (通知) # 驗證用 if !notification.acknowledge raise ExternalError, 'acknowledge failed' end # 是否付款成功 if !notification.complete? raise ExternalError, 'notification not complete' end ＊這在 controller中
33. Notification #3 (通知) # 錢對嗎 if @order.total != notification.gross() raise ExternalError, '金額不對' end # 已經付過錢了嗎嗎 if @order.paid? raise ExternalError, '已經付過款' end @order.pay! #要清蒸要紅燒自己決定 ＊這在 controller中
34. Notification #4 (通知) render text:'1|OK', status:200 and return end ＊這在 controller中
35. Disclaimer: 以上都是教學範例，把許多檢查/實際需要的邏輯拿掉了
36. 目前台灣相關的實作 https://github.com/Shopify/active_merchant/ ActiveMerchant 本身有內建以下介面： HiTrust（安心付）跟 Paypal https://github.com/xwaynec/active_merchant_allpay 歐付寶介面 綠界跟歐買尬合作後，綠界 Ecbank 也停止註冊並且把顧客 導到歐付寶了。 https://github.com/GoodLife/active_merchant-smile_pay SmilePay 訊航科技介面連接 iBon 的部份
37. 1/3場FAQ時間
38. 實作 第二部
39. ActiveMerchant 沒有支援 想學 AM 的原理~ 想造福其他程設人~ 實作！ 實作！ 實作！ 反正就是實作就對了
40. OK! Let’s ROCK
41. Let’s implement offline_payment gem
42. OFFSITE_PAYMENTS GEM https://github.com/Shopify/offsite_payments Shopify 最近把 offsite_payment 抽出來， 並且簡化設計， 一個實作只有一個檔案： lib / offsite_payments / integrations / paypal.rb ＊還沒正式公布
43. 以前(ActiveMerchant gem) 實作都放在 lib/active_merchant/billing/integrations 下： 每個實作會有三個檔案，舉 paypal 為例子： paypal.rb ← 統合用 paypal/helper.rb ← form helper paypal/notification.rb ← 處理接收到的付款通知
44. What the *#$#% is Shopify doing?! active_merchant / offsite_payment • 沒說明 • 沒有範例 ◦ Luke, read the source • 有些地方比較老舊 • 沒有實作規範 ◦ 結果大家只好抄 paypal 實作 ◦ 有時候方法語義錯誤導致兩個實作不相容
45. 為何不自己手刻就好 • 有一次串多個金流的需求 • 有架構，就像是保護網一樣 不用特別想要怎樣寫才是好讀 • 寫個 gem 讓別人用～爽 ◦ 節省別人的開發時間 ◦ 我踩雷你就不必踩了
46. OK! Let’s ROCK
47. Step 1: 準備金流商 API文件一份
48. Step 2: bundle gem offsite_payments- integrations-smilepay
49. Step 3: 修改 gemfile spec.add_development_dependency('test-unit', '~> 2.5.5') spec.add_dependency('offsite_payments', '~> 2.0.1') 然後 > bundle install
50. Step 4: 打開主程式檔 lib/offsite_payments/integrations/smile_pay.rb require "offsite_payments/integrations/smile_pay/version" require “offsite_payments” module OffsitePayments module Integrations module SmilePay # Your code goes here... end end end
51. Module基本設定 參考 paypal 即可 # in module SmilePay mattr_accessor :production_url, :test_url self.production_url = 'https://example.com/xxx' self.test_url = 'https://example.com/yyy' def self.notification(post) Notification.new(post) end def self.service_url case OffsitePayments.mode when :production self.production_url when :test self.test_url end
52. offsite_payment helper class Helper < OffsitePayments::Helper
53. mapping(方法名,表單input名) 產生convenience method，比如說有了： mapping :currency, 'currency_code' 就能使用 f.currency(‘TWD’) 產生 <input name=”currency_code” value=”TWD” type=”hidden”/> helper - mapping()方法
54. mapping(方法名,表單input名) 產生convenience method，比如說有了： mapping :currency, 'currency_code' 就能使用 f.currency(‘TWD’) 產生 <input name=”currency_code” value=”TWD” type=”hidden”/> helper - mapping()方法
55. 常見 mapping 方法名 語義 account 你在金流業者那的ID order 你的訂單編號 amount 金額 notify_url 通知你這端付款成功的 url return_url 付款成功後使用者瀏覽器返回到你這端的 url description 訂單內容 currency 幣值 各個實作的介面統計一覽
56. 最好標上官方文件上的欄位說明好作對照 # 商家代號 mapping :account, 'Dcvc' # 金額 mapping :amount, 'Amount' # 訂單號碼 mapping :order, 'Data_id' # 交易完成後要回送的位置 mapping :notify_url, 'Roturl'
57. 實作 helper 時 盡量參考別的實作， 來統一方法名稱與語義的對應， 讓不同的實作介面能相容。 比如說：
58. Url mappers XXXXX_url 有許多種，請多參考其他實作的語意。 notify_url (25個有實作） 通知你這端付款成功的 API url return_url (27個有實作） 付款成功後使用者瀏覽器返回到你這端的 url cancel_return_url (18個有實作) 付款失敗時使用者瀏覽器從金流方返回你這端的url
59. Helper - 常駐參數 寫在 helper 的 initialize 裡面即可： class Helper < OffsitePayments::Helper def initialize(order,account,options={}) super add_field('Rvg2c', 1) end add_field(表單input名) 產生 <input> 用的方法
60. Helper - 複合參數 f.customer(first_name:”!xobile”, last_name:””, email:”xobile.example.com”) 這是怎樣實作的呢： mapping :customer, :first_name => 'first_name', :last_name => 'last_name', :email => 'email'
61. Helper - beyond mapping 記得，你寫的是RUBY，不怕被框架卡到 # 把 shipping address 轉成單一欄位 def shipping_address(params = {}) a = [params[:country], params[:city], params[:address].join(‘,’) add_field(“address”, a) end
62. Helper - 不用走火入魔 不需要所有參數都寫個方法， 有時候使用者自行利用 add_field() 添加更好， 因為不需要記得 input name <-> method_name 之對照。 以後對照官方文件也更直覺易懂。
63. Helper 設計的其實很不錯 實作開發者有寫 mapping 實作開發者沒有寫 mapping 使用者使用方 法時 會出現在 form 上 silently ignored 使用了 method_missing 同時使用多種金流時， 也不用怕使用某實作專有的方法， A金流的特有設定在B金流會自動忽略。
64. offsite_payment notification class Notification < OffsitePayments:: Notification
65. Notification 解析從金流端 POST 回來的資料 1. 使用 raw_post 字串來 new 一個 notification 2. 可以用定義的方法取出裡面資訊 a. e.g. complete?() 知道付款是否完成 3. 可以用定義的方法作驗證 a. e.g. acknowledge() 可以詢問金流方避免有人造假
66. Notification - 重要介面 方法 語意 acknowledge (注意沒有 ? 唷） 與金流端發 request 作驗證 status 通知本身狀態（如：failed） gross 總金額（客人付款的金額） item_id 你這端的訂單編號 complete? 是否交易成功 currency 交易幣別 transaction_id 金流端編號 test? 是否為測試
67. Notification 上述幾個方法盡量實作， 沒有對應也寫 stub 方法。 同時盡量參考別的實作， 來統一方法名稱與語義的對應， 讓不同的實作介面能相容。 各個實作的介面一覽 https://docs.google. com/spreadsheets/d/13i41t3ZZ_LoW59ayt1C9 oy- 3XGWhArVugWuCKDDpnKo/edit#gid=258741
68. Notification acknowledge() 原本是遠端認證用， 後來變成如果金流沒有機制能遠端認證， 但是有提供其他驗證方式（如 checksum）， 也一併寫在 acknowledge 裡面
69. Notification # in class Notification def item_id # 訂單號碼 params['Data_id'] end def transaction_id # Smile Pay 端訂單號碼 params['Smseid'] end # When was this payment received by the client. def received_at params['Process_date'] + params['Process_time'] end
70. Notification def currency case params['Moneytype'] when 'TW' 'TWD' when 'CN' 'CNY' end end # the money amount we received in X.2 decimal. def gross ::Money.new(params['Amount'].to_i * 100, currency) end
71. Notification # Was this a test transaction? def test? OffsitePayments.mode == :test end def status 'Completed' end
72. Notification # SmilePay 認證碼 def acknowledge if test? # SmilePay 客服回答測試環境時認證碼只會傳0 true else params['Mid_smilepay'].to_i == calculated_mid_smile_key end end
73. 記得寫測試喔！ （照抄其他實作的架構即可） 我當年寫了測試， 但是還是上線時才發現錯誤
74. 測試可參考其他實作 ActiveMerchant 因為傳統， 都是使用 testunit 測試。 如要這樣測試， 可複製一份官方 test_helper.rb 來使用： https://github. com/Shopify/offsite_payments/blob/master/test/ test_helper.rb
75. 測試 有個 staging 能測是最好 不過為了加速開發，可用以下方法在 local 端測 試 notification ssh -R 3334:localhost:3000 your- staging-domain.com 這樣 notification 就能透過你的網域:3334送回你 的開發機（前提是金流商支援 port）
76. 測試 • 注意 big5 編碼，常常會忘了測中文最後上線 才發現錯誤。 • 時間是什麼時區的要小心 • 因為不是 Rails ，在 notification 裡面，要取得 params 記得用 string 當 key X params[:gross] O params[‘gross’]
77. FAQ時間