genesis_ruby 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7220a925cd5f4162c331e8f76df937b25d94c61ba2b00ffa2c0e658a9555a23
-  data.tar.gz: b24aece0771f858eeed93a62ebb8a6ad2b1751d85f30b72c98ed647ae3b17f9d
+  metadata.gz: 366d18ddee1ed33af60c71b5cf439c087c9fcb616bfd75ac0cc500a95c3b42c5
+  data.tar.gz: e147b273edf9fb53594ffdbd49c8402dccb07ec771677c796e5f35279ac95899
 SHA512:
-  metadata.gz: d061c605183153c41dbde88215322a084b06f3ac293509c54ba7109e2e4342437a813f340ad11fa26a3a8352c7201a05ca667d5b0092a3ef22125128501a1b3e
-  data.tar.gz: 108c00082a58b5addceb9f20f0d13eee410e86f4cfc38e2ad6ff47d2900f05876dc62cff5d498e56b1a10e575cb8446cce211a42d5b87e26b1be53d4578efcab
+  metadata.gz: 7c14b6dbd50dd0bd5a95e2c399dc0777b2568c6b935577fa753ef860494264d4039a02f2ffeab858fea74256216de1634b8eab9ab3fae5a3bf12426561784439
+  data.tar.gz: 5dca05cd79676548657d7d5f80e56ec2de46884dc4f1e4cbbbf6e1f1783304c536f84ef126f4b32dd441a204366af65cca2a8b0480a9d52e86b9781c6bebdbf4

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+0.1.3
+-----
+**Fixes**:
+
+* Fixed 3DSv2 Method element name in the XML document
+
+0.1.2
+-----
+**Features**:
+
+* Added 3D Secure Method Continue API request support
+* Updated Gateway response handling upon error cases like 3D Secure Method Continue with invalid identifier a Network error will be raised
+* Added `GenesisRuby::Api::Notification` handler that provides an easy way of handling Gateway instant payment notifications
+
 0.1.1
 -----
 **Features**:

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    genesis_ruby (0.1.1)
+    genesis_ruby (0.1.3)
       net-http (~> 0.3.2)
       nokogiri (~> 1.14)
 
@@ -11,14 +11,14 @@ GEM
     addressable (2.8.5)
       public_suffix (>= 2.0.2, < 6.0)
     ast (2.4.2)
-    base64 (0.1.1)
+    base64 (0.2.0)
     concurrent-ruby (1.2.2)
     crack (0.4.5)
       rexml
     diff-lcs (1.5.0)
     faker (2.23.0)
       i18n (>= 1.8.11, < 2)
-    faraday (2.7.11)
+    faraday (2.7.12)
       base64
       faraday-net_http (>= 2.0, < 3.1)
       ruby2_keywords (>= 0.0.4)
@@ -37,26 +37,26 @@ GEM
     json (2.6.3)
     language_server-protocol (3.17.0.3)
     mini_mime (1.1.5)
-    mini_portile2 (2.8.4)
+    mini_portile2 (2.8.5)
     multi_xml (0.6.0)
     mustermann (3.0.0)
       ruby2_keywords (~> 0.0.1)
     net-http (0.3.2)
       uri
-    nokogiri (1.15.4)
+    nokogiri (1.15.5)
       mini_portile2 (~> 2.8.2)
       racc (~> 1.4)
-    octokit (6.1.1)
+    octokit (7.2.0)
       faraday (>= 1, < 3)
       sawyer (~> 0.9)
     parallel (1.23.0)
-    parser (3.2.2.3)
+    parser (3.2.2.4)
       ast (~> 2.4.1)
       racc
-    pronto (0.11.1)
+    pronto (0.11.2)
       gitlab (>= 4.4.0, < 5.0)
       httparty (>= 0.13.7, < 1.0)
-      octokit (>= 4.7.0, < 7.0)
+      octokit (>= 4.7.0, < 8.0)
       rainbow (>= 2.2, < 4.0)
       rexml (>= 3.2.5, < 4.0)
       rugged (>= 0.23.0, < 2.0)
@@ -64,14 +64,14 @@ GEM
     pronto-rubocop (0.11.5)
       pronto (~> 0.11.0)
       rubocop (>= 0.63.1, < 2.0)
-    public_suffix (5.0.3)
-    racc (1.7.1)
+    public_suffix (5.0.4)
+    racc (1.7.3)
     rack (2.2.8)
     rack-protection (3.1.0)
       rack (~> 2.2, >= 2.2.4)
     rainbow (3.1.1)
-    rake (13.0.6)
-    regexp_parser (2.8.1)
+    rake (13.1.0)
+    regexp_parser (2.8.2)
     rexml (3.2.6)
     rspec (3.12.0)
       rspec-core (~> 3.12.0)
@@ -86,29 +86,28 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
     rspec-support (3.12.1)
-    rubocop (1.56.3)
-      base64 (~> 0.1.1)
+    rubocop (1.57.2)
       json (~> 2.3)
       language_server-protocol (>= 3.17.0)
       parallel (~> 1.10)
-      parser (>= 3.2.2.3)
+      parser (>= 3.2.2.4)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml (>= 3.2.5, < 4.0)
       rubocop-ast (>= 1.28.1, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.29.0)
+    rubocop-ast (1.30.0)
       parser (>= 3.2.1.0)
-    rubocop-capybara (2.18.0)
+    rubocop-capybara (2.19.0)
       rubocop (~> 1.41)
-    rubocop-factory_bot (2.23.1)
+    rubocop-factory_bot (2.24.0)
       rubocop (~> 1.33)
     rubocop-faker (1.1.0)
       faker (>= 2.12.0)
       rubocop (>= 0.82.0)
-    rubocop-rspec (2.24.0)
-      rubocop (~> 1.33)
+    rubocop-rspec (2.25.0)
+      rubocop (~> 1.40)
       rubocop-capybara (~> 2.17)
       rubocop-factory_bot (~> 2.22)
     ruby-progressbar (1.13.0)
@@ -124,10 +123,10 @@ GEM
       tilt (~> 2.0)
     terminal-table (3.0.2)
       unicode-display_width (>= 1.1.1, < 3)
-    thor (1.2.2)
+    thor (1.3.0)
     tilt (2.3.0)
-    unicode-display_width (2.4.2)
-    uri (0.12.2)
+    unicode-display_width (2.5.0)
+    uri (0.13.0)
     webmock (3.19.1)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)

data/README.md

@@ -105,6 +105,8 @@ rescue GenesisRuby::Error => error
 end
 ```
 
+A full list of the Transaction Types and Custom Attributes can be found [here](https://emerchantpay.github.io/gateway-api-docs/?shell#wpf-transaction-types).
+
 ### Transactions
 
 ```ruby
@@ -144,7 +146,280 @@ rescue GenesisRuby::Error => error
 end
 ```
 
-A full list of the Transaction Types and Custom Attributes can be found [here](https://emerchantpay.github.io/gateway-api-docs/?shell#wpf-transaction-types).
+### Example 3DSv2 Request
+
+Sample request including all the conditionally required/optional params for initiating a 3DS transaction with the 3DSv2-Method authentication protocol.
+
+Also, an example is provided for the 3DS-Method-continue API call that will have to be submitted after the 3DS-Method is initiated.
+<details>
+
+```ruby
+require 'genesis_ruby'
+
+begin
+  genesis_3ds_v2 = GenesisRuby::Genesis.for(config: configuration, request: GenesisRuby::Api::Requests::Financial::Cards::Sale3d) do |request|
+    # Common Attributes
+    request.transaction_id     = '12345-67890'
+    request.remote_ip          = '127.0.0.1'
+    request.amount             = '0.99'
+    request.currency           = 'EUR'
+    request.usage              = 'Example usage'
+    request.customer_email     = 'travis@example.com'
+    request.customer_phone     = '+1987987987987'
+
+    # Credit Card Attributes
+    request.card_holder      = 'Travis Pastrana'
+
+    # Test Cases
+    request.card_number = '4012000000060085' # Test Case: Synchronous 3DSv2 Request with Frictionless flow
+    # request.card_number = '4066330000000004' # Test Case: Asynchronous 3DSv2 Request with 3DS-Method and Frictionless flow
+    # request.card_number = '4918190000000002' # Test Case: Asynchronous 3DSv2 Request with Challenge flow
+    # request.card_number = '4938730000000001' # Test Case: Asynchronous 3DSv2 Request with 3DS-Method Challenge flow
+    # request.card_number = '4901170000000003' # Test Case: Asynchronous 3DSv2 Request with Fallback flow
+    # request.card_number = '4901164281364345' # Test Case: Asynchronous 3DSv2 Request with 3DS-Method Fallback flow
+
+    request.expiration_month = '12'
+    request.expiration_year  = '2040'
+    request.cvv              = '123'
+
+    # Async Attributes
+    request.notification_url   = 'https://example.com/notification'
+    request.return_success_url = 'https://example.com/success'
+    request.return_failure_url = 'https://example.com/failure'
+
+    # Billing Attributes
+    request.billing_first_name = 'Travis'
+    request.billing_last_name  = 'Pastrana'
+    request.billing_address1   = 'Kreisfreie Stadt Berlin'
+    request.billing_zip_code   = '10115'
+    request.billing_city       = 'Berlin'
+    request.billing_country    = 'DE'
+
+    # Threeds V2 Attributes
+
+    ## Method Attributes
+    request.threeds_v2_method_callback_url = 'https://www.example.com/threeds/threeds_method/callback'
+
+    ## Control Attributes
+    request.threeds_v2_control_device_type           =
+            GenesisRuby::Api::Constants::Transactions::Parameters::Threeds::Version2::Control::DeviceTypes::BROWSER
+    request.threeds_v2_control_challenge_window_size =
+            GenesisRuby::Api::Constants::Transactions::Parameters::Threeds::Version2::Control::ChallengeWindowSizes::FULLSCREEN
+    request.threeds_v2_control_challenge_indicator   =
+            GenesisRuby::Api::Constants::Transactions::Parameters::Threeds::Version2::Control::ChallengeIndicators::MANDATE
+
+    ## Browser Attributes
+    ## When Control Device Type is Browser
+    request.threeds_v2_browser_accept_header    = '*/*'
+    request.threeds_v2_browser_java_enabled     = true
+    request.threeds_v2_browser_language         = 'en-GB'
+    request.threeds_v2_browser_color_depth      = 48
+    request.threeds_v2_browser_screen_height    = 900
+    request.threeds_v2_browser_screen_width     = 1440
+    request.threeds_v2_browser_time_zone_offset = '+0'
+    request.threeds_v2_browser_user_agent       = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/78.0.3904.97 Safari/537.36'
+
+    ## SDK
+    ## When Control Device Type is SDK
+    request.threeds_v2_sdk_interface                 =
+            GenesisRuby::Api::Constants::Transactions::Parameters::Threeds::Version2::Sdk::Interfaces::BOTH
+    request.threeds_v2_sdk_ui_types                  =
+            GenesisRuby::Api::Constants::Transactions::Parameters::Threeds::Version2::Sdk::UiTypes::TEXT
+    request.threeds_v2_sdk_ui_types                  =
+            GenesisRuby::Api::Constants::Transactions::Parameters::Threeds::Version2::Sdk::UiTypes::SINGLE_SELECT
+    request.threeds_v2_sdk_ui_types                  =
+            GenesisRuby::Api::Constants::Transactions::Parameters::Threeds::Version2::Sdk::UiTypes::MULTI_SELECT
+    request.threeds_v2_sdk_application_id            = 'fc1650c0-5778-0138-8205-2cbc32a32d65'
+    request.threeds_v2_sdk_encrypted_data            = 'encrypted-data-here'
+    request.threeds_v2_sdk_ephemeral_public_key_pair = 'public-key-pair'
+    request.threeds_v2_sdk_max_timeout               = 10
+    request.threeds_v2_sdk_reference_number          = 'sdk-reference-number-her'
+
+
+    ## Purchase Attributes
+    request.threeds_v2_purchase_category =
+            GenesisRuby::Api::Constants::Transactions::Parameters::Threeds::Version2::Purchase::Categories::GOODS
+
+    ## Recurring
+    request.threeds_v2_recurring_expiration_date = '12-12-2024'
+    request.threeds_v2_recurring_frequency       = 30
+
+    ## Merchant Risk Attributes
+    request.threeds_v2_merchant_risk_shipping_indicator           =
+            GenesisRuby::Api::Constants::Transactions::Parameters::Threeds::Version2::MerchantRisk::ShippingIndicators::SAME_AS_BILLING
+    request.threeds_v2_merchant_risk_delivery_timeframe           =
+            GenesisRuby::Api::Constants::Transactions::Parameters::Threeds::Version2::MerchantRisk::DeliveryTimeframes::ANOTHER_DAY
+    request.threeds_v2_merchant_risk_reorder_items_indicator      =
+            GenesisRuby::Api::Constants::Transactions::Parameters::Threeds::Version2::MerchantRisk::ReorderItemIndicators::FIRST_TIME
+    request.threeds_v2_merchant_risk_pre_order_purchase_indicator =
+            GenesisRuby::Api::Constants::Transactions::Parameters::Threeds::Version2::MerchantRisk::PreOrderPurchaseIndicators::MERCHANDISE_AVAILABLE
+    request.threeds_v2_merchant_risk_pre_order_date               = '31-12-2030'
+    request.threeds_v2_merchant_risk_gift_card                    = true
+    request.threeds_v2_merchant_risk_gift_card_count              = 99
+
+    ## Card Holder Account Attributes
+    request.threeds_v2_card_holder_account_creation_date                       = '31-12-2022'
+    request.threeds_v2_card_holder_account_update_indicator                    =
+            GenesisRuby::Api::Constants::Transactions::Parameters::Threeds::Version2::CardHolderAccount::UpdateIndicators::MORE_THAN_60DAYS
+    request.threeds_v2_card_holder_account_last_change_date                    = '31-12-2022'
+    request.threeds_v2_card_holder_account_password_change_indicator           =
+            GenesisRuby::Api::Constants::Transactions::Parameters::Threeds::Version2::CardHolderAccount::PasswordChangeIndicators::NO_CHANGE
+    request.threeds_v2_card_holder_account_password_change_date                = '31-12-2022'
+    request.threeds_v2_card_holder_account_shipping_address_usage_indicator    =
+            GenesisRuby::Api::Constants::Transactions::Parameters::Threeds::Version2::CardHolderAccount::ShippingAddressUsageIndicators::MORE_THAN_60DAYS
+    request.threeds_v2_card_holder_account_shipping_address_date_first_used    = '31-12-2022'
+    request.threeds_v2_card_holder_account_transactions_activity_last24_hours  = 2
+    request.threeds_v2_card_holder_account_transactions_activity_previous_year = 10
+    request.threeds_v2_card_holder_account_provision_attempts_last24_hours     = 1
+    request.threeds_v2_card_holder_account_purchases_count_last6_months        = 5
+    request.threeds_v2_card_holder_account_suspicious_activity_indicator       =
+            GenesisRuby::Api::Constants::Transactions::Parameters::Threeds::Version2::CardHolderAccount::SuspiciousActivityIndicators::NO_SUSPICIOUS_OBSERVED
+    request.threeds_v2_card_holder_account_registration_indicator              =
+            GenesisRuby::Api::Constants::Transactions::Parameters::Threeds::Version2::CardHolderAccount::RegistrationIndicators::MORE_THAN_60DAYS
+    request.threeds_v2_card_holder_account_registration_date                   = '31-12-2022'
+
+  end.execute
+
+  response_3ds_v2 = genesis_3ds_v2.response
+
+  if response_3ds_v2.approved?
+    # Transaction approved no customer action required
+    # Test Case: Synchronous 3DSv2 Request with Frictionless flow
+    puts response_3ds_v2.response_object
+  end
+
+  if response_3ds_v2.declined? || response_3ds_v2.error?
+    # Transaction declined no customer action required
+    # Synchronous 3DSv2 Request with Frictionless flow
+    puts response_3ds_v2.response_object
+  end
+
+  if response_3ds_v2.pending_async?
+    # Additional Actions Required
+    response_object_3ds_v2 = response_3ds_v2.response_object
+
+    if response_object_3ds_v2[:redirect_url]
+      # An interaction between consumer and issuer is required
+      # 3DSv2 Challenge required
+      # 3DSv1 payer authentication required - fallback from 3DSv2 to 3DSv1
+      # Test Case: Asynchronous 3DSv2 Request with Challenge flow
+      # Test Case: Asynchronous 3DSv2 Request with Fallback flow
+      puts response_object_3ds_v2[:redirect_url_type]
+      puts response_object_3ds_v2[:redirect_url]
+    end
+
+    if response_object_3ds_v2[:threeds_method_url]
+      # 3DS-Method submission is required
+      # Generate 3DSv2-Method Signature token used for Threeds Method Continue Request. It's not required when the 3DS-Method continue request is built by the initial request's response object.
+      puts GenesisRuby::Utils::Threeds::V2.generate_signature(
+              unique_id: response_object_3ds_v2[:unique_id],
+              amount: response_object_3ds_v2[:amount],
+              timestamp: response_object_3ds_v2[:timestamp].strftime(GenesisRuby::Api::Constants::DateTimeFormats::YYYY_MM_DD_H_I_S_ZULU),
+              merchant_password: configuration.password
+      )
+
+      # Execute 3DS-Method Continue Request after initiating the 3DS-Method submission
+      # The new request is loaded from the response object of the initial request
+      genesis_3ds_v2_continue = GenesisRuby::Api::Requests::Financial::Cards::Threeds::V2::MethodContinue.build_from_response_object(
+              configuration,
+              genesis_3ds_v2.response.response_object
+      )
+
+      genesis_3ds_v2_continue.execute
+
+      response_3ds_v2_continue = genesis_3ds_v2_continue.response
+
+      if response_3ds_v2_continue.approved?
+        # Transaction APPROVED no customer action required
+        # Test Case: Asynchronous 3DSv2 Request with 3DS-Method and Frictionless flow
+        puts response_3ds_v2_continue.response_object
+      end
+
+      if response_3ds_v2_continue.declined? || response_3ds_v2_continue.error?
+        # Transaction declined no customer action required
+        puts response_3ds_v2_continue.response_object
+      end
+
+      if response_3ds_v2_continue.pending_async?
+        # Customer action required
+        continue_response_object = response_3ds_v2_continue.response_object
+
+        if continue_response_object[:redirect_url]
+          # Test Case: Asynchronous 3DSv2 Request with 3DS-Method Challenge flow
+          # Test Case: Asynchronous 3DSv2 Request with 3DS-Method Fallback flow
+          puts continue_response_object[:redirect_url_type]
+          puts continue_response_object[:redirect_url]
+        end
+      end
+    end
+  end
+
+rescue GenesisRuby::Error => error
+  puts error.message
+end
+```
+
+</details>
+
+### Standalone ThreedsV2 Method Continue Request.
+
+<details>
+
+```ruby
+require 'genesis_ruby'
+
+begin
+  genesis = GenesisRuby::Genesis.for(config: configuration, request: GenesisRuby::Api::Requests::Financial::Cards::Threeds::V2::MethodContinue) do |request|
+    # Amount in minor currency unit
+    # If the AMOUNT is not in a minor currency unit then SET the CURRENCY. The AMOUNT will be converted into minor currency unit internally using the CURRENCY property.
+    # Ex. amount = 10.00
+    #     currency = 'EUR'
+    #   The AMOUNT in that case for signature generation will be 1000
+    # Amount is included in the response from the initial request in major currency unit genesis.response.response_object[:amount]
+    request.amount = 10.00
+
+    # If CURRENCY is set, AMOUNT value will be converted into MINOR currency unit
+    # If you SET the AMOUNT in MINOR currency unit DO NOT set CURRENCY
+    # Currency is included in the response from the initial request in major currency unit genesis.response.response_object[:currency]
+    request.currency = 'EUR'
+
+    # Set only one of the unique_id or url
+    # request.url = 'https://staging.gate.emerchantpay.net/threeds/threeds_method/d6a6aa96292e4856d4a352ce634a4335'
+    request.transaction_unique_id = 'd6a6aa96292e4856d4a352ce634a4335'
+
+    # String representation of the timestamp
+    # request.transaction_timestamp = genesis.response
+    #   .response_object[:timestamp].strftime(GenesisRuby::Api::Constants::DateTimeFormats::YYYY_MM_DD_H_I_S_ZULU)
+    request.transaction_timestamp = '2020-12-31T23:59:59Z'
+  end.execute
+
+  response = genesis.response
+
+  if response.approved?
+    # Asynchronous 3DSv2 Request with 3DS-Method and Frictionless flow
+    # Transaction approved no customer action required
+    puts response.response_object
+  end
+
+  if response.pending_async?
+    # Customer action required
+    response_object = response.response_object
+
+    if response_object[:redirect_url]
+      # Asynchronous 3DSv2 Request with 3DS-Method Challenge flow
+      # Asynchronous 3DSv2 Request with 3DS-Method Fallback flow
+      puts response_object[:redirect_url_type]
+      puts response_object[:redirect_url]
+    end
+  end
+
+rescue GenesisRuby::Error => error
+  puts error.message
+end
+```
+
+</details>
+
 
 ### Recurring
 
@@ -277,6 +552,88 @@ rescue GenesisRuby::Error => error
 end
 ```
 
+### Gateway Notification
+
+With the asynchronous payment flows like Web Payment Form the Gateway sends the transaction events upon status change on the defined `notification_url`.
+The library contains a Notification module that helps handle the received gateway notification and can provide easy reconciliation execution.
+
+#### Initialization
+The notification module requires notification data or any object that responds to `to_h` with a Hash return value.
+For example, with Ruby on Rails you can permit the params and to_h method can be executed without errors:
+
+```ruby
+permitted_params = params.permit(:transaction_id, :terminal_token, :unique_id, :transaction_type, :status, :signature, :amount)
+```
+A full list of the available params that can be received upon notification can be found [here](https://emerchantpay.github.io/gateway-api-docs/?shell#asynchronous-transactions).
+
+```ruby
+begin
+  notification = GenesisRuby::Api::Notification.new configuration, permitted_params
+
+  # Helper methods
+  notification.api_notification?
+  notification.wpf_notification?
+  notification.unique_id
+
+  # Executes Gateway Transaction Reconciliation
+  # This provides the latest information on the transaction from the Gateway
+  notification.reconcile
+
+  # Provides information if the given reconcile response contains transaction information
+  notification.transaction_reconciliation?
+
+  # Get the Reconcile Response Object in Hash data structure
+  notification.reconciliation.response_object
+
+  # Generate response document expected from the Gateway
+  notification.generate_response
+rescue GenesisRuby::ParameterError => error
+  puts error.message
+end
+```
+
+#### Reconcile
+Minimum required data for execution of `reconcile`:
+
+```ruby
+{
+  unique_id: 'unique_id received from the gateway in the notification params',
+  signature: 'the signature received in the notification'
+}
+```
+
+If the signature can't be verified Genesis::Ruby::ParameterError will be raised.
+
+#### Helpers
+`notification.reconcile` returns GenesisRuby::Api::Response. The response object can be accessed via `notification.reconciliation`.
+The reconciliation object has every helper that [Response](#response-helpers) contains like checking the status with `error?`, `approved?`, etc.
+
+For checking if the `reconciliation.response_object` is a successful transaction response you can use `notification.transaction_reconciliation?`
+
+#### Errors
+Upon wrong data like configuration terminal token, `reconciliation.response_object` can be similar:
+
+```ruby
+{
+   status: 'error',
+   code: '220',
+   message: 'Reconcile request failed, please contact support!',
+   technical_message: 'Invalid Terminal'
+}
+```
+
+#### Respond to the Gateway
+When receiving the notification, you are required to render an xml page containing the transaction’s unique id so that the gateway knows that you have accepted the notification.
+If the XML is not delivered, the notification is sent periodically until the XML is received.
+
+`GenesisRuby::Api::Notification` provides helper method for generation of the expected xml content. The Gateway expects a response with:
+* Status 200
+* Content Type `text/xml`
+
+```ruby
+notification.generate_response
+```
+
 ### Response Helpers
 
 #### Sates

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.1.3

data/lib/genesis_ruby/api/constants/date_time_formats.rb

@@ -16,7 +16,7 @@ module GenesisRuby
         DD_MM_YYYY_L_SLASHES  = '%d/%m/%Y'.freeze
 
         # Zulu timestamp
-        YYYY_MM_DD_H_I_S_ZULU = '%Y-%m-%dT%H:%M:%S%z'.freeze
+        YYYY_MM_DD_H_I_S_ZULU = '%Y-%m-%dT%H:%M:%SZ'.freeze
 
         # Modified Zulu timestamp
         YYYY_MM_DD_H_I_S      = '%Y-%m-%d %H:%M:%S'.freeze

data/lib/genesis_ruby/api/mixins/requests/financial/threeds/version2/common_attributes.rb

@@ -31,7 +31,7 @@ module GenesisRuby
                 # Threeds V2 Web Payment Form Attributes
                 def threeds_v2_common_attributes_structure
                   {
-                    method:              method_attributes,
+                    threeds_method:      method_attributes,
                     control:             control_attributes,
                     purchase:            purchase_attributes,
                     merchant_risk:       merchant_risk_attributes,

data/lib/genesis_ruby/api/notification.rb

@@ -0,0 +1,156 @@
+require 'cgi'
+require 'digest'
+
+module GenesisRuby
+  module Api
+    # Gateway Notification handler
+    class Notification
+
+      attr_reader :unique_id, :notification, :reconciliation
+
+      # Signature algorithms
+      SHA1_SIGNATURE_TYPE   = 'SHA1'.freeze
+      SHA256_SIGNATURE_TYPE = 'SHA256'.freeze
+      SHA512_SIGNATURE_TYPE = 'SHA512'.freeze
+
+      # Possible request/response identifier fields
+      API_UNIQUE_FIELD = 'unique_id'.freeze
+      WPF_UNIQUE_FIELD = 'wpf_unique_id'.freeze
+      KYC_UNIQUE_FIELD = 'reference_id'.freeze
+
+      # Class constructor
+      def initialize(configuration, data)
+        @configuration = configuration
+
+        parse_notification data
+      end
+
+      # Check if the given data is API notification
+      def api_notification?
+        notification.key? :unique_id
+      end
+
+      # Check if the given data is Web Payment Form notification
+      def wpf_notification?
+        notification.key? :wpf_unique_id
+      end
+
+      # Check if the given data is Know Your Customer notification
+      def kyc_notification?
+        notification.key? :reference_id
+      end
+
+      # Generates XML document expected from the Gateway
+      def generate_response
+        response = {
+          notification_echo: [[fetch_response_unique_field, unique_id]].to_h
+        }
+
+        builder = GenesisRuby::Builder.new Builder::XML
+        builder.parse_structure response
+
+        builder.document
+      end
+
+      # Execute Reconcile API Request
+      def reconcile
+        request_object = fetch_reconciliation_request
+
+        begin
+          genesis = Genesis.for config: @configuration, request: request_object do |req|
+            req.unique_id = unique_id
+          end.execute
+
+          @reconciliation = genesis.response
+        rescue Error
+          @reconciliation = nil
+        end
+      end
+
+      # Determinate if the executed reconciliation response contains transaction data
+      def transaction_reconciliation?
+        response_object = reconciliation&.response_object
+
+        return false if response_object.nil?
+
+        response_object.key?(:unique_id) && response_object.key?(:transaction_id) && response_object.key?(:status)
+      end
+
+      private
+
+      # Parse the given notification data
+      def parse_notification(data, authenticate: true)
+        @notification = parse_raw_data data
+        @unique_id    = fetch_unique_id
+
+        raise ParameterError, 'Invalid Genesis Notification!' if authenticate && !authentic?
+      end
+
+      # Parse the given raw data
+      def parse_raw_data(data)
+        normalize_data data.to_h
+      rescue StandardError => e
+        raise ParameterError, "Given notification data doesn't respond to_h! #{e.message}"
+      end
+
+      # Normalize the given notification data
+      def normalize_data(data)
+        data.map { |key, value| [CGI.unescape(key.to_s).to_sym, CGI.unescape(value.strip)] }.to_h
+      end
+
+      # Assign the unique_id property based on the given notification data
+      def fetch_unique_id
+        return @notification[API_UNIQUE_FIELD.to_sym] if api_notification?
+        return @notification[WPF_UNIQUE_FIELD.to_sym] if wpf_notification?
+        return @notification[KYC_UNIQUE_FIELD.to_sym] if kyc_notification?
+
+        nil
+      end
+
+      # Validate the Notification signature
+      def authentic?
+        if unique_id.nil? || notification[:signature].nil?
+          raise ParameterError, 'Missing Notification attributes: unique_id or signature'
+        end
+
+        generated_signature = fetch_signature_generator.hexdigest "#{unique_id}#{@configuration.password}"
+
+        notification[:signature] == generated_signature
+      end
+
+      # Fetch the hash generator based on the hash type
+      def fetch_signature_generator
+        Digest.const_get fetch_hash_type
+      end
+
+      # Fetch the hash algorithm by the given signature length
+      def fetch_hash_type
+        case notification[:signature].length
+        when 40 then SHA1_SIGNATURE_TYPE
+        when 64 then SHA256_SIGNATURE_TYPE
+        when 128 then SHA512_SIGNATURE_TYPE
+        else
+          SHA1_SIGNATURE_TYPE
+        end
+      end
+
+      # Fetches the response field identifier name witch is expected from the Gateway
+      def fetch_response_unique_field
+        return API_UNIQUE_FIELD if api_notification?
+        return WPF_UNIQUE_FIELD if wpf_notification?
+        return KYC_UNIQUE_FIELD if kyc_notification?
+
+        raise ParameterError, 'Unknown notification type!'
+      end
+
+      # Fetch the Reconcile object
+      def fetch_reconciliation_request
+        return Requests::NonFinancial::Reconcile::Transaction if api_notification?
+        return Requests::Wpf::Reconcile if wpf_notification?
+
+        raise ParameterError, 'Unsupported notification type for Reconciliation'
+      end
+
+    end
+  end
+end

data/lib/genesis_ruby/api/requests/financial/cards/threeds/v2/method_continue.rb

@@ -0,0 +1,145 @@
+require 'genesis_ruby/utils/threeds/v2'
+
+module GenesisRuby
+  module Api
+    module Requests
+      module Financial
+        module Cards
+          module Threeds
+            module V2
+              # Method Continue API request
+              class MethodContinue < Request
+
+                include Mixins::Requests::Financial::PaymentAttributes
+                include Mixins::Requests::RestrictedSetter
+
+                attr_writer :url, :transaction_unique_id, :signature
+
+                class << self
+
+                  def build_from_response_object(configuration, response_object)
+                    if response_object[:threeds_method_continue_url].nil? ||
+                       response_object[:unique_id].nil? ||
+                       response_object[:amount].nil? || response_object[:currency].nil? ||
+                       response_object[:timestamp].nil? || !response_object[:timestamp].is_a?(DateTime)
+
+                      raise ParameterError, 'Response object is incomplete or required attributes are missing!'
+                    end
+
+                    build_method_continue_request configuration, response_object
+                  end
+
+                  private
+
+                  # Build Method Continue Request
+                  def build_method_continue_request(configuration, response_object)
+                    request = new configuration
+
+                    request.url                   = response_object[:threeds_method_continue_url]
+                    request.transaction_unique_id = response_object[:unique_id]
+                    request.amount                = response_object[:amount]
+                    request.currency              = response_object[:currency]
+                    request.transaction_timestamp = response_object[:timestamp].strftime(
+                      Constants::DateTimeFormats::YYYY_MM_DD_H_I_S_ZULU
+                    )
+
+                    GenesisRuby::Genesis.new configuration, request
+                  end
+
+                end
+
+                # Override default constructor with FORM Builder Interface
+                def initialize(configuration, _builder_interface = nil)
+                  super(configuration, Builder::FORM)
+                end
+
+                # A link between the customer's browser and the card issuer must be opened with a hidden iframe
+                def url
+                  return @url = generate_endpoint_url if @url.nil?
+
+                  @url
+                end
+
+                # Equivalent to the value of the unique_id,
+                # received from the response of the initial transaction request
+                def transaction_unique_id
+                  return extract_unique_id_from_url @url if @transaction_unique_id.nil?
+
+                  @transaction_unique_id
+                end
+
+                # SHA512 of а concatenated string (unique_id, amount, timestamp, merchant_api_password)
+                def signature
+                  return @signature unless @signature.nil?
+
+                  payment_amount = @currency.nil? ? amount : transform_amount(amount, currency)
+
+                  Utils::Threeds::V2.generate_signature(
+                    unique_id: transaction_unique_id,
+                    amount: payment_amount,
+                    timestamp: transaction_timestamp,
+                    merchant_password: @configuration.password
+                  )
+                end
+
+                # The timestamp from the initial transaction response
+                def transaction_timestamp
+                  @transaction_timestamp&.strftime(
+                    GenesisRuby::Api::Constants::DateTimeFormats::YYYY_MM_DD_H_I_S_ZULU
+                  )
+                end
+
+                # The timestamp from the initial transaction response
+                def transaction_timestamp=(value)
+                  parse_date attribute: __method__, value: value, allow_empty: true
+                end
+
+                protected
+
+                # Init Method Continue Request configuration
+                def init_configuration
+                  init_form_configuration
+
+                  @api_config.type = Request::METHOD_PUT
+
+                  init_api_gateway_configuration request_path: 'threeds/threeds_method/:unique_id', include_token: false
+                end
+
+                # Build correct endpoint url during runtime
+                def process_request_parameters
+                  @api_config.url = url
+
+                  super
+                end
+
+                # Method Continue Request structure
+                def populate_structure
+                  @tree_structure = {
+                    unique_id: transaction_unique_id,
+                    signature: signature
+                  }
+                end
+
+                private
+
+                # Fills the Unique Id in the endpoint URL
+                def generate_endpoint_url
+                  @api_config.url&.sub! ':unique_id', transaction_unique_id.to_s
+                end
+
+                # Extract the Unique Id
+                def extract_unique_id_from_url(url)
+                  uri           = URI.parse url || ''
+                  exploded_path = uri.path&.split('/')
+
+                  exploded_path.last
+                end
+
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/genesis_ruby/api/response.rb

@@ -57,6 +57,8 @@ module GenesisRuby
         @parser = GenesisRuby::Parsers.new(GenesisRuby::Parser::JSON) if network.json?
         @parser = GenesisRuby::Parser.new(GenesisRuby::Parser::XML) if network.xml?
 
+        raise NetworkError, network.server_message if @parser.nil? || @response_raw.empty?
+
         @parser.skip_root_node if @request_api_config[:parser_skip_root_node]
 
         @parser

data/lib/genesis_ruby/builder.rb

@@ -1,4 +1,5 @@
 require 'genesis_ruby/builders/xml'
+require 'genesis_ruby/builders/form'
 require 'genesis_ruby/errors/builder_error'
 
 module GenesisRuby
@@ -17,8 +18,8 @@ module GenesisRuby
     # Initialize the Builder Interface based on the Request requirements
     def initialize(request_interface)
       case request_interface
-      when XML
-        @builder_context = GenesisRuby::Builders::Xml.new
+      when XML then @builder_context = Builders::Xml.new
+      when FORM then @builder_context = Builders::Form.new
       else
         raise GenesisRuby::BuilderError, 'Invalid Builder interface!'
       end

data/lib/genesis_ruby/builders/form.rb

@@ -0,0 +1,44 @@
+require 'genesis_ruby/builders/base'
+require 'uri'
+
+module GenesisRuby
+  module Builders
+    # XML, Nokogiri Builder Implementation
+    class Form < Base
+
+      # Initialize Nokogiri XML Builder
+      def initialize
+        @builder = URI
+        super
+      end
+
+      # Generated HTTP Query Document
+      def output
+        document
+      end
+
+      def populate_nodes(structure)
+        self.document = @builder.encode_www_form(transform_structure(structure))
+      end
+
+      private
+
+      attr_accessor :buffer, :document
+
+      # Transform structure from hash to array
+      # { key: 'value' } -> [[key, value]]
+      def transform_structure(structure)
+        self.buffer = []
+        structure.each { |key, value| add_buffer [key, value] }
+
+        buffer
+      end
+
+      # Fill up parameters
+      def add_buffer(value)
+        @buffer.push(value)
+      end
+
+    end
+  end
+end

data/lib/genesis_ruby/dependencies.rb

@@ -18,6 +18,7 @@ Dir["#{File.dirname(__FILE__)}/api/mixins/**/*_attributes.rb"].sort.each { |file
 require 'genesis_ruby/api/requests/base/financial'
 require 'genesis_ruby/api/requests/base/financials/credit_card'
 require 'genesis_ruby/api/requests/base/reference'
+require 'genesis_ruby/api/notification'
 
 # Load Financial and Non Financial API Requests
 Dir["#{File.dirname(__FILE__)}/api/requests/*financial/**/*.rb"].sort.each { |file| require file }

data/lib/genesis_ruby/network/adapter/base_adapter.rb

@@ -25,6 +25,16 @@ module GenesisRuby
           raise NotImplementedError, 'Execute method must be implemented'
         end
 
+        # Whether the response is an error (HTTP Code != 200)
+        def error?
+          raise NotImplementedError, 'Error? method must be implemented'
+        end
+
+        # Response server message
+        def server_message
+          raise NotImplementedError, 'Server Message method must be implemented'
+        end
+
       end
     end
   end

data/lib/genesis_ruby/network/adapter/net_http_adapter.rb

@@ -25,14 +25,13 @@ module GenesisRuby
         def execute
           raise NetworkError, 'Request is not initialized' unless @request
 
-          begin
-            # TODO: Use GenesisRuby::Api::Request::METHOD_XXX constants for sending GET and PUT request_data.type
-            @response = @request.post(path, request_data.body, headers)
-          rescue StandardError => e
-            raise NetworkError, "Network error raised by #{e.class.name}: #{e.message}"
-          ensure
-            # Close the request
-            @request.finish
+          safe_execute do
+            case request_data.type
+            when Api::Request::METHOD_POST then @response = @request.post path, request_data.body, headers
+            when Api::Request::METHOD_PUT then @response = @request.put path, request_data.body, headers
+            else
+              raise 'Invalid Request Type!'
+            end
           end
         end
 
@@ -46,6 +45,19 @@ module GenesisRuby
           @response_headers ||= @response ? @response.each_header.to_h : {}
         end
 
+        # Whether the response is an error (HTTP Code != 200)
+        def error?
+          !@response.is_a? Net::HTTPSuccess
+        end
+
+        # Response server message
+        def server_message
+          message = status
+          message += " #{@response.message}" if @response.message
+
+          message
+        end
+
         private
 
         attr_reader :uri, :request, :response, :request_data
@@ -86,6 +98,16 @@ module GenesisRuby
           }
         end
 
+        # Safe Request execution
+        def safe_execute(&block)
+          block.call
+        rescue StandardError => e
+          raise NetworkError, "Network error raised by #{e.class.name}: #{e.message}"
+        ensure
+          # Close the request
+          @request.finish
+        end
+
       end
     end
   end

data/lib/genesis_ruby/network/base_network.rb

@@ -9,6 +9,7 @@ module GenesisRuby
 
       XML_HEADER  = 'application/xml'.freeze
       JSON_HEADER = 'application/json'.freeze
+      HTML_HEADER = 'text/html'.freeze
 
       # Base constructor
       def initialize(configuration)
@@ -27,6 +28,16 @@ module GenesisRuby
         @context.response_headers
       end
 
+      # Whether returned response is an error response
+      def error?
+        @context.error?
+      end
+
+      # Returns the server message
+      def server_message
+        @context.server_message
+      end
+
       # Send the request
       def send_request
         @context.execute
@@ -47,6 +58,11 @@ module GenesisRuby
         raise NotImplementedError, 'Is JSON method must be implemented'
       end
 
+      # Every child defines is HTML Response Type
+      def html?
+        raise NotImplementedError, 'Is HTML method must be implemented'
+      end
+
       protected
 
       # GenesisRuby::Configuration, Adapter Context, Network Adapter Config mapper

data/lib/genesis_ruby/network/net_http.rb

@@ -16,6 +16,11 @@ module GenesisRuby
         response_headers['content-type'].downcase.include?(BaseNetwork::JSON_HEADER)
       end
 
+      # HTML Response Type
+      def html?
+        response_headers['content-type'].downcase.include?(BaseNetwork::HTML_HEADER)
+      end
+
       protected
 
       # Adapter Initialization

data/lib/genesis_ruby/utils/options/network_adapter_config.rb

@@ -22,13 +22,12 @@ module GenesisRuby
 
         # Retrieve the Request data format that must be used as Content-Type header
         def fetch_content_type(data_format)
-          # TODO: Builder Constants
           case data_format
-          when 'xml'
+          when Builder::XML
             'text/xml'
-          when 'json'
+          when Builder::JSON
             'application/json'
-          when 'form'
+          when Builder::FORM
             'application/x-www-form-urlencoded'
           else
             raise InvalidArgumentError, 'Invalid request format type. Allowed are XML, JSON and FORM'

data/lib/genesis_ruby/utils/threeds/v2.rb

@@ -0,0 +1,21 @@
+require 'digest'
+
+module GenesisRuby
+  module Utils
+    module Threeds
+      # Threeds V2 Utils
+      class V2
+
+        class << self
+
+          # Generate 3DSV2 signature
+          def generate_signature(unique_id:, amount:, timestamp:, merchant_password:)
+            Digest::SHA512.hexdigest "#{unique_id}#{amount}#{timestamp}#{merchant_password}"
+          end
+
+        end
+
+      end
+    end
+  end
+end

data/lib/genesis_ruby/version.rb

@@ -1,5 +1,5 @@
 module GenesisRuby
 
-  VERSION = '0.1.1'.freeze
+  VERSION = '0.1.3'.freeze
 
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: genesis_ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - emerchantpay Ltd.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-10-09 00:00:00.000000000 Z
+date: 2023-12-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-http
@@ -292,6 +292,7 @@ files:
 - lib/genesis_ruby/api/mixins/requests/financial/threeds/version2/sdk.rb
 - lib/genesis_ruby/api/mixins/requests/financial/threeds/version2/wpf_attributes.rb
 - lib/genesis_ruby/api/mixins/requests/restricted_setter.rb
+- lib/genesis_ruby/api/notification.rb
 - lib/genesis_ruby/api/request.rb
 - lib/genesis_ruby/api/requests/base/financial.rb
 - lib/genesis_ruby/api/requests/base/financials/credit_card.rb
@@ -301,6 +302,7 @@ files:
 - lib/genesis_ruby/api/requests/financial/cards/authorize3d.rb
 - lib/genesis_ruby/api/requests/financial/cards/sale.rb
 - lib/genesis_ruby/api/requests/financial/cards/sale3d.rb
+- lib/genesis_ruby/api/requests/financial/cards/threeds/v2/method_continue.rb
 - lib/genesis_ruby/api/requests/financial/refund.rb
 - lib/genesis_ruby/api/requests/financial/void.rb
 - lib/genesis_ruby/api/requests/non_financial/reconcile/date_range.rb
@@ -310,6 +312,7 @@ files:
 - lib/genesis_ruby/api/response.rb
 - lib/genesis_ruby/builder.rb
 - lib/genesis_ruby/builders/base.rb
+- lib/genesis_ruby/builders/form.rb
 - lib/genesis_ruby/builders/xml.rb
 - lib/genesis_ruby/configuration.rb
 - lib/genesis_ruby/connection.rb
@@ -345,6 +348,7 @@ files:
 - lib/genesis_ruby/utils/options/api_config.rb
 - lib/genesis_ruby/utils/options/base.rb
 - lib/genesis_ruby/utils/options/network_adapter_config.rb
+- lib/genesis_ruby/utils/threeds/v2.rb
 - lib/genesis_ruby/utils/transactions/financial_types.rb
 - lib/genesis_ruby/utils/transactions/references/capturable_types.rb
 - lib/genesis_ruby/utils/transactions/references/refundable_types.rb
@@ -374,7 +378,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.1
+rubygems_version: 3.1.2
 signing_key:
 specification_version: 4
 summary: Ruby Client for Genesis Payment Processing Gateway