{"id":20881990,"url":"https://github.com/5xruby/spgateway-rails","last_synced_at":"2025-08-30T17:46:46.475Z","repository":{"id":72023237,"uuid":"90936726","full_name":"5xRuby/spgateway-rails","owner":"5xRuby","description":"智付通金流的 Rails plugin (well, not completely tested for production yet)。","archived":false,"fork":false,"pushed_at":"2017-09-11T07:34:58.000Z","size":72,"stargazers_count":25,"open_issues_count":1,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-12T17:36:48.246Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/5xRuby.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-05-11T04:18:00.000Z","updated_at":"2024-01-04T16:13:57.000Z","dependencies_parsed_at":null,"dependency_job_id":"30f4199a-688d-435f-996e-bf5137452b95","html_url":"https://github.com/5xRuby/spgateway-rails","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/5xRuby/spgateway-rails","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5xRuby%2Fspgateway-rails","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5xRuby%2Fspgateway-rails/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5xRuby%2Fspgateway-rails/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5xRuby%2Fspgateway-rails/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/5xRuby","download_url":"https://codeload.github.com/5xRuby/spgateway-rails/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5xRuby%2Fspgateway-rails/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272884345,"owners_count":25009599,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-30T02:00:09.474Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-18T07:28:31.436Z","updated_at":"2025-08-30T17:46:46.424Z","avatar_url":"https://github.com/5xRuby.png","language":"Ruby","readme":"# Spgateway Rails Plugin [![Build Status](https://travis-ci.org/5xRuby/spgateway-rails.svg?branch=master)](https://travis-ci.org/5xRuby/spgateway-rails)\n\nThis plugin provides convenient integration with [Spgateway](https://www.spgateway.com) - an online payment service in Taiwan.\n\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'spgateway-rails', github: '5xRuby/spgateway-rails'\n```\n\nAnd then execute:\n\n```bash\n$ bundle\n```\n\nFinally, run the install generator:\n\n```bash\n$ rails generate spgateway:install\n```\n\nthen set your `merchant_id`, `hash_key` and `hash_iv` in `config/initializers/spgateway.rb`.\n\n\n## Basic Usage\n\n### The simplest integration: only support immediate credit card pay off\n\n1. Place the pay button in a view, such as:\n\n    ```erb\n    \u003c%= spgateway_pay_button 'Go pay', payment_methods: [:credit_card], order_number: @order.serial, item_description: @order.description, amount: @order.amount, payer_email: current_user\u0026.email, class: 'btn btn-success' %\u003e\n    ```\n\n    \u003e Note that we restrict the supported payment methods to only `credit_card` here.\n\n2. Configure how to process payment results in `config/initializers/spgateway.rb`, for example:\n\n    ```rb\n      config.mpg_callback do |mpg_response|\n        if mpg_response.status == 'SUCCESS'\n          Order.find_by(serial: mpg_response.result.merchant_order_no)\n               .update_attributes!(paid: true)\n          flash[:success] = mpg_response.message\n        else\n          flash[:error] = mpg_response.message\n        end\n\n        redirect_to orders_path\n      end\n    ```\n\n### Supporting non-real-time payment methods: using `notify_callback`\n\nWith some payment methods, such as ATM 轉帳 (VACC), 超商代碼繳費 (CVS) or 超商條碼繳費 (BARCODE), users will not complete their transaction on the web browser but maybe in front of an ATM or in a convenient store or so. Spgateway will notify our application later if such transactions has been done, and we will need an additional setup to deal with these notifications.\n\n\u003e Note that you will not be able to test this intergration with an local application server (i.e. `http://localhost:3000`) directly, because (in normal cases) Spgateway cannot connect to your local computer. Consider using services like [ngrok](https://ngrok.com/) to get a public URL tunneled to your local application server, and use that public URL in the browser to get things work.\n\n1. You'll need to setup `mpg_callback` and `notify_callback` like this:\n\n    ```rb\n      # Callback after the user has been redirect back from Spgateway MPG gateway.\n      config.mpg_callback do |spgateway_response|\n        # Only shows the results to the user here, while notify_callback will do the\n        # actual work.\n\n        if spgateway_response.status == 'SUCCESS'\n          flash[:success] = spgateway_response.message\n        else\n          flash[:error] = spgateway_response.message\n        end\n\n        redirect_to orders_path\n      end\n\n      # Callback triggered by Spgateway after an order has been paid.\n      config.notify_callback do |spgateway_response|\n\n        if spgateway_response.status == 'SUCCESS'\n          # Find the order and mark it as paid.\n          Order.find_by(serial: spgateway_response.result.merchant_order_no)\n               .update_attributes!(paid: true)\n        else\n          # Or log the error.\n          Rails.logger.info \"Spgateway Payment Not Succeed: #{spgateway_response.status}: #{spgateway_response.message} (#{spgateway_response.result.to_json})\"\n        end\n      end\n    ```\n\n    The `notify_callback` will be called when Spgateway tries to notify us about payment status updates, nomatter which payment method does the user select. So in the `mpg_callback` block, we should only write code for user-facing logic, to prevent dulipaced work and unexpected results.\n\n2. Now you can add non-real-time payment methods to your pay button:\n\n    ```erb\n    \u003c%= spgateway_pay_button 'Go pay', payment_methods: [:credit_card, :vacc, :cvs, :barcode], order_number: @order.serial, item_description: @order.description, amount: @order.amount, payer_email: current_user\u0026.email, class: 'btn btn-success' %\u003e\n    ```\n\n### Get the customer's ATM transfer account or payment code and show them on your website with `payment_code_callback`\n\nBy default, Spgateway will show the payment instruction of ATM 轉帳 (VACC), 超商代碼繳費 (CVS) or 超商條碼繳費 (BARCODE) to users on their site directly, this way you can not get the payment info and users will not be redirected back to your site.\n\nYou can add the `payment_code_callback` config to let users be redirected back to your site, so then you can have the payment info and show it to your users by yourself. Do something like this:\n\n```rb\n  config.payment_code_callback do |spgateway_response|\n    if spgateway_response.status == 'SUCCESS' \u0026\u0026\n       spgateway_response.result.payment_type == 'VACC'\n\n      bank_code = spgateway_response.result.bank_code\n      account_number = spgateway_response.result.code_no\n      expired_at =\n        DateTime.parse(\"#{spgateway_response.result.expire_date} #{spgateway_response.result.expire_time} UTC+8\")\n      Order.find_by(serial: spgateway_response.result.merchant_order_no)\n           .update_attributes!(bank_code: bank_code, account_number: account_number, expired_at: expired_at)\n      flash[:info] =\n        \"Please transfer the money to bank code #{bank_code}, account number #{account_number} before #{I18n.l(expired_at)}\"\n    else\n      Rails.logger.error \"Spgateway Payment Code Receive Not Succeed: #{spgateway_response.status}: #{spgateway_response.message} (#{spgateway_response.result.to_json})\"\n      flash[:error] = \"Our apologies, but an unexpected error occured, please try again\"\n    end\n\n    redirect_to orders_path\n  end\n```\n\n\n## TODO\n\n- Support ClientBackURL.\n- Build API wrapper for QueryTradeInfo.\n- Add option to double check the payment results after callback.\n- Build API wrapper for CreditCard/Cancel.\n- Wtite docs.\n- Test, test everything!\n\n\n## Contributing\n\nJust open an issue or send a PR :)\n\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F5xruby%2Fspgateway-rails","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F5xruby%2Fspgateway-rails","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F5xruby%2Fspgateway-rails/lists"}