spree_emerchantpay_genesis 0.1.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f3f946f18fcb121abeb5227927b4d8480f73aedfd549cca1eae4a069a322b34b
+  data.tar.gz: 675f4efd4755f39eca482ef49dcb4c75555eb98e8cd89217cd2b713f90074d59
+SHA512:
+  metadata.gz: eda4500c230e18a04b44eb67613c7911666e27730dd8f9eafc19fe6e43d636673479b3f47c9762465ee839ccbff026acb2e4b6dad5cde36f0b7fd07c2fff216f
+  data.tar.gz: 958cdcf91ac6ce0cd617e14d17c8cc09bde302fb829197e1b74c77ff9829f8e961b5847c419710b2372149baf1b1e72eb4956b0ce7ffaaa7e94121304af46895

data/CHANGELOG.md

@@ -0,0 +1,52 @@
+0.1.3
+-----
+**Features**
+
+* Added tests to the library
+* Added Appraisals for Spree 4.4 and Spree main GitHub Branch
+* Added `spree_emerchantpay_genesis` to [RubyGems](https://rubygems.org/gems/spree_emerchantpay_genesis)
+
+**Fixes**:
+
+* Fixed 3DSv2 parameters handling
+* Fixed engine installation without Spree Rails Frontend
+* Fixed minor issues
+
+0.1.2
+-----
+
+**Features**:
+
+* Updated project license to MIT
+* Added support for the following transaction types:
+  * Authorize 3D
+  * Sale 3D
+* Added 3DSv2 parameters support to the 3D payments
+* Added support for 3DSv2 payment flow
+* Added `emerchantpay_payment` inside Spree API V2 Create Payment response containing payment state and redirect_url
+* Added Gateway Notifications handling used for asynchronous payments
+* Updated Genesis Ruby SDK to version 0.1.3
+
+0.1.1
+-----
+
+**Features**:
+
+* Added support for the following reference payment actions via Genesis Gateway:
+  * Capture
+  * Void
+  * Refund
+
+0.1.0
+-----
+
+**Features**:
+
+* Added initial code base for emerchantpay Gateway Module for Spree payment method
+* Added EmerchantpayDirect Spree Gateway
+* Added Spree Payment Creation decoration
+* Added Spree Payment Methods settings decorator
+* Added Payment Source View decorator
+* Added Spree V2 Checkout controller decorator
+* Added Emerchantpay Payments database migration
+* Added Spree Payment Processing decorator

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 emerchantpay ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,269 @@
+# emerchantpay Genesis Gateway for Spree
+This is a Payment Module for Spree eCommerce that gives you the ability to process payments through emerchantpay's Payment Gateway - Genesis.
+
+# Requirements
+* Spree Core 4.x (Tested up to 4.4.0)
+* Spree Backend 4.x (Tested up to 4.4.0)
+* Spree FrontEnd - Optional (Tested up to 4.4.0)
+* Ruby >= 2.7
+* Ruby on Rails >= 6.1.4
+* [GenesisRuby v0.1.3](https://github.com/GenesisGateway/genesis_ruby/releases/tag/0.1.3)
+* PCI-certified server in order to use emerchantpay Direct
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'spree_emerchantpay_genesis'
+```
+
+And then execute:
+```bash
+bundle
+```
+
+Or install it yourself as:
+```bash
+gem install spree_emerchantpay_genesis
+```
+
+Copy & run migrations
+```bash
+bundle exec rails g spree_emerchantpay_genesis:install
+```
+
+Restart your server
+
+## Create Payment Method
+* Sign in to Spree Admin BackEnd
+* Navigate to Configurations -> Payment Methods -> New Payment Method
+* For Provider `Choose Spree::Gateway::Emerchantpay*`
+* Fill in Name, Description and Stores
+* Click Create
+
+# Usage
+
+## Configuration
+* Navigate to the `Spree::Gateway::Emerchantpay*` payment method in the Configurations
+* Fill in Username, Password and Token
+* Fill in `hostname` used for the generation of the notification webhook. In most cases, the hostname should be the hostname of the Spree backend.
+* Fill in `return_success_url` and `return_failure_url`. Those endpoints will be returned to the `create_payment` response
+  * If you add `|:ORDER:|` pattern in the URLs. The pattern will be replaced with the Spree Order Number
+
+## Spree Storefront API V2
+
+1. Create Cart
+
+```bash
+curl --request 'POST' \
+  --url 'http://127.0.0.1:4000/api/v2/storefront/cart'
+```
+
+Response:
+
+```text
+{
+  "data":{
+    "id":"59",
+    "type":"cart",
+    "attributes":{
+      "number":"R702094375",
+      ...
+      "currency":"USD",
+      "state":"cart",
+      "token":"EsDjq1oXEgKI6kuujgfvFw1694531383712",
+      ...
+    },
+    ...
+  }
+}
+```
+
+2. Add Items
+<details>
+<summary>List Products</summary>
+
+```bash
+curl --request 'GET' \
+  --url 'https://demo.spreecommerce.org/api/v2/storefront/products' \
+  --header 'Accept: application/vnd.api+json'
+```
+
+</details>
+
+```bash
+curl --request 'POST' \
+ --url 'http://localhost:4000/api/v2/storefront/cart/add_item' \
+ --header 'Accept: application/vnd.api+json' \
+ --header 'X-Spree-Order-Token: EsDjq1oXEgKI6kuujgfvFw1694531383712' \
+ --header 'Content-Type: application/vnd.api+json' \
+ --data '{
+   "variant_id": "130",
+   "quantity": "1"
+ }'
+```
+
+3. Add Shipping
+<details>
+<summary>List Shipping Rates</summary>
+
+```bash
+curl --request 'GET' \
+  --url 'https://demo.spreecommerce.org/api/v2/storefront/checkout/shipping_rates' \
+  --header 'Accept: application/vnd.api+json' \
+  --header 'X-Spree-Order-Token: EsDjq1oXEgKI6kuujgfvFw1694531383712'
+```
+
+</details>
+
+```bash
+curl --request 'PATCH' \
+ --url 'http://localhost:4000/api/v2/storefront/checkout/select_shipping_method' \
+ --header 'Accept: application/vnd.api+json' \
+ --header 'X-Spree-Order-Token:  EsDjq1oXEgKI6kuujgfvFw1694531383712' \
+ --header 'Content-Type: application/vnd.api+json' \
+ --data '{
+   "shipping_method_id": "1"
+ }'
+```
+
+4. Update Order
+```bash
+curl --request 'PATCH' \
+  --header 'Accept: application/vnd.api+json' \
+  --header 'X-Spree-Order-Token: EsDjq1oXEgKI6kuujgfvFw1694531383712' \
+  --header 'Content-Type: application/vnd.api+json' \
+  --url 'http://localhost:4000/api/v2/storefront/checkout' \
+  --data '{
+  "order": {
+    "email": "john.smith@example.com",
+    "bill_address_attributes": {
+      "firstname": "John",
+      "lastname": "Smith",
+      "address1": "1 Area",
+      "city": "Louisville",
+      "phone": "01234567891",
+      "zipcode": "40202",
+      "country_iso": "US",
+      "state_id": 500
+    },
+    "ship_address_attributes": {
+      "firstname": "John",
+      "lastname": "Smith",
+      "address1": "1 Area",
+      "city": "Louisville",
+      "phone": "01234567891",
+      "zipcode": "40202",
+      "country_iso": "US",
+      "state_id": 500
+    },
+    "payments_attributes":[
+      {
+        "payment_method_id":"5"
+      }
+    ]
+  },
+  "payment_source": {
+    "5": {
+      "name": "John Smith",
+      "number": "4200000000000000",
+      "month": 1,
+      "year": 2040,
+      "verification_value": "123",
+      "cc_type": "visa"
+    }
+  }
+}'
+```
+5. Create Payment
+**CAUTION** Create Payment endpoint will Complete the order! Call this endpoint in order to finish the order!  
+Accept Header, Java Enabled, Language, Color Depth, Screen height, Screen Width, Time Zone Offset, User Agent parameters must be retrieved from the customer browser. More info [here](https://emerchantpay.github.io/gateway-api-docs/?shell#3ds-v2-request-params).
+
+```bash
+curl --request 'POST' \
+  --header 'Accept: application/vnd.api+json' \
+  --header 'X-Spree-Order-Token: EsDjq1oXEgKI6kuujgfvFw1694531383712' \
+  --header 'Content-Type: application/vnd.api+json' \
+  --url 'http://localhost:4000/api/v2/storefront/checkout/create_payment' \
+  --data '{
+  "payment_method_id": "5",
+  "source_attributes": {
+    "name": "John Smith",
+    "number": "4200000000000000",
+    "month": 1,
+    "year": 2040,
+    "verification_value": "123",
+    "cc_type": "visa",
+    "accept_header": "*/*",
+    "java_enabled": "true",
+    "language": "en-GB",
+    "color_depth": "32",
+    "screen_height": "400",
+    "screen_width": "400",
+    "time_zone_offset": "+0",
+    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36"
+  }
+}'
+```
+
+Response:
+**CAUTION** If a redirect URL exists in the response object you MUST redirect the customer for payment completion
+
+Create Payment response will contain `emerchantpay_payment` object. It will contain the current status of the payment.
+Redirect URL will give you the next step.
+
+States:
+* error or declined - redirect URL will be the Failure URL filled in plugin settings
+* approved - redirect URL will be the Success URL filled in the plugin settings
+* pending_async - redirect URL will be the 3DSecure Method Continue endpoint for the next step of the payment
+
+```json
+{
+  "data": {
+    "id": "XXX",
+    "type": "cart",
+    "attributes": {...},
+    "relationships": {...},
+    "emerchantpay_payment": {
+      "state": "pending_async",
+      "redirect_url": "<customer-redirect-url>"
+    }
+  }
+}
+```
+
+## Reference Actions
+**CAUTION** the following transaction actions must be executed via Spree Admin backend:
+* Capture
+* Refund
+* Void
+
+## Contributing
+Contribution directions go here.
+
+## Development
+
+### Running Specs
+
+`rake test`
+
+### Running Linters
+
+`rake styles`
+
+### Appraisals
+
+#### Spree 4.4
+
+`bundle exec appraisal spree-4.4 rake test`
+
+#### Spree Master
+
+`bundle exec appraisal spree-master rake test`
+
+#### Configure
+
+`bundle exec appraisal install`
+
+## License
+The gem is available as open source under the terms of the [GPL-2.0 License](https://opensource.org/license/gpl-2-0/).

data/Rakefile

@@ -0,0 +1,50 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+require 'spree/testing_support/extension_rake'
+
+desc 'Generates a dummy app for testing'
+task :test_app do
+  ENV['LIB_NAME'] = 'spree_emerchantpay_genesis'
+  Rake::Task['extension:test_app'].invoke
+end
+
+RSpec::Core::RakeTask.new(:spec)
+RSpec::Core::RakeTask.new(:spec_junit) do |t|
+  t.rspec_opts = ['--format RspecJunitFormatter', '--out rspec_report.xml']
+  t.pattern    = '**/*_spec.rb'
+end
+
+task :rspec, [:format] do |_task, args|
+  if Dir['spec/dummy'].empty?
+    Rake::Task[:test_app].invoke
+    Dir.chdir('../../')
+  end
+
+  case args.format
+  when 'junit'
+    Rake::Task[:spec_junit].invoke
+  else
+    Rake::Task[:spec].invoke
+  end
+end
+
+require 'rubocop/rake_task'
+RuboCop::RakeTask.new(:rubocop_default)
+RuboCop::RakeTask.new(:rubocop_progress) do |t|
+  t.formatters = %w(progress)
+  t.options    = %w(--out rubocop_report.txt)
+end
+
+task :test do
+  Rake::Task[:rspec].invoke('')
+end
+
+task :test_junit do
+  Rake::Task[:rspec].invoke('junit')
+end
+
+task default: %i[test rubocop_default]
+task styles: :rubocop_default
+task style_progress: :rubocop_progress

data/app/assets/javascripts/spree/emerchantpay_threeds.js

@@ -0,0 +1,126 @@
+(function(document) {
+    document.body.onload = function (){
+        empThreedsSecureMethod('threedsMethodForm').execute()
+    }
+})(document);
+
+const empThreedsSecureMethod = function(form_id) {
+    let interval        = null
+    let delay           = 500
+    let retries         = 0
+    let max_retries     = 12
+    let status_complete = 'completed'
+    let internal_error  = 'internal_error'
+
+    // ThreedsForm HTML Element
+    const threedsForm = function() {
+        return document.getElementById(form_id)
+    }
+
+    // 3DSv2 Callback Status endpoint
+    const getCallbackStatusUrl = function() {
+        return threedsForm().dataset.statusUrl
+    }
+
+    // 3DSv2 Method Continue endpoint
+    const getMethodContinueUrl = function() {
+        return threedsForm().dataset.methodSecureUrl
+    }
+
+    const getFailureUrl = function() {
+        return threedsForm().dataset.failureUrl
+    }
+
+    // Execute 3DSv2 submission
+    const submitThreedsMethod = function(){
+        threedsForm().submit()
+        startLoop()
+    }
+
+    // 3DSv2 Secure Method Handler
+    const startLoop = function() {
+        initInterval(function() {
+            checkCallbackStatus(function(data) {
+                handleInternalError(data)
+
+                if (retries >= max_retries || data.status === status_complete) {
+                    clearInterval(interval)
+
+                    sendBackEndData(function(data) {
+                        handleInternalError(data)
+
+                        redirectTo(data.redirect_url)
+                    })
+                }
+
+                retries++;
+            })
+        })
+    }
+
+    const handleInternalError = function(data) {
+        if (data.status === internal_error) {
+            clearInterval(interval)
+            redirectTo(getFailureUrl())
+        }
+    }
+
+    // Redirect to the given url
+    const redirectTo = function(url) {
+        parent.location.href = url
+    }
+
+    // Initialize the Interval
+    const initInterval = function(callback) {
+        interval = setInterval(callback, delay)
+    }
+
+    // Check Callback status
+    const checkCallbackStatus = function(callback) {
+        ajaxCall(
+            { method: 'GET', url: getCallbackStatusUrl(), async: false },
+            (data) => { callback(data) },
+            (status, response) => { callback({ status: internal_error }) }
+        )
+    }
+
+    function sendBackEndData(callback) {
+        ajaxCall(
+            { method: 'POST', url: getMethodContinueUrl(), async: false, form_data: new FormData(threedsForm()) },
+            (data) => { callback(data) },
+            (status, response) => { callback({ status: internal_error }) }
+        )
+    }
+
+    const ajaxCall = function(options, success, failure) {
+        let xhr = new XMLHttpRequest()
+        xhr.open(options.method, options.url, options.async)
+
+        try {
+            xhr.onload = function() {
+                if (xhr.status === 200) {
+                    return success(parseData(xhr.responseText))
+                }
+
+                return failure(xhr.status, xhr.responseText)
+            };
+
+            xhr.onerror = () => { failure(500, 'Network Error') }
+
+            xhr.send(options.form_data)
+        } catch(err) {
+            failure(0, 'System error')
+        }
+    }
+
+    const parseData = function(data) {
+        try {
+            return JSON.parse(data)
+        } catch (error) {
+            return {}
+        }
+    }
+
+
+    return { execute: submitThreedsMethod }
+};