HyperPay 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb8d58ae8360368a30935be12cc4e3dc0d2c5a234b6d1d31cad4959428864b3e
-  data.tar.gz: dfa14a6b30908707bc19eff2e4165b86bb42cc349ec50e32e659ec4fdeb2a5ed
+  metadata.gz: 3d0bf2a05890ebbdd9fbd9e516c679e69cc0a6a8555af7c4210ef0c866a49f8b
+  data.tar.gz: f706cde04cc238345f4f850c154445dee05daf1cd335df8478bd9d46123367ca
 SHA512:
-  metadata.gz: dd532c6e1f74bbd756f0f544871edf1b3096a2395a50c62781848cfce90fdd62f3bac08ff1d95d0f310889f3432a434140b9337e2e419f1d8589f5e527478626
-  data.tar.gz: 279b7866cf4eae7488f5f574366621bc274e3f60aaef460512a6f8ff299433725e1a8a19fd6295f9be26dcce1ae922f2369bdea755822fb5e5ea4fbede1e111c
+  metadata.gz: 4a22241cdf4ee982fb4d62e971756412c6f9b8e491493a4685673af74c42d8c334b67f4b2f53b745cd3cde05f6136146743961a3c1650c07d9a7a9d6732f045b
+  data.tar.gz: b32871687e2a251d90535e3325c06c877b9360a9cf661aafdc20ffa75bdf3767444f9e68ec004754aa7bcc8e75dcb5bcf0696a8291d85f49b6ddad76c09b199e

data/README.md

@@ -16,6 +16,8 @@ gem 'HyperPay'
 
 `config/initializers/hyperpay.rb`
 ```ruby
+require 'hyper_pay'
+
 HyperPay.configure do |config|
   config.authorization = "HYPER_PAY_AUTH_TOKEN"
   config.environment = :sandbox
@@ -26,12 +28,6 @@ end
 
 ### Generate Checkout ID
 ```ruby
-  # Generate HyperPay Checkout ID
-  #
-  # Parameters:
-  # @entity_id Entity ID that was used to generate the Checkout ID
-  # @return [Hash] {"result"=>{"code"=>"000.200.100", "description"=>"successfully created checkout"}, "buildNumber"=>"a58fee65f51ad5776b3c44e9929ca39a62a7cb43@2024-03-04 12:55:38 +0000", "timestamp"=>"2024-03-05 13:50:22+0000", "ndc"=>"ABCE449B5FC84ED5A1C7174840C7A3F8.uat01-vm-tx03", "id"=>"ABCE449B5FC84ED5A1C7174840C7A3F8.uat01-vm-tx03"}
-
   checkout = HyperPay::CopyAndPay.new.create_checkout_id do |params|
     params.add "entityId", "HYPER_PAY_ENTITY_ID"
     params.add "customer.email", "john@doe.com"
@@ -58,37 +54,139 @@ end
 
 ### Response
 ```ruby
-{"result"=>{"code"=>"000.200.100", "description"=>"successfully created checkout"}, "buildNumber"=>"a58fee65f51ad5776b3c44e9929ca39a62a7cb43@2024-03-04 12:55:38 +0000", "timestamp"=>"2024-03-05 13:50:22+0000", "ndc"=>"ABCE449B5FC84ED5A1C7174840C7A3F8.uat01-vm-tx03", "id"=>"ABCE449B5FC84ED5A1C7174840C7A3F8.uat01-vm-tx03"}
+{
+  "result"=>{
+    "code"=>"000.200.100", 
+    "description"=>"successfully created checkout"
+  }, 
+  "buildNumber"=>"a58fee65f51ad5776b3c44e9929ca39a62a7cb43@2024-03-04 12:55:38 +0000", 
+  "timestamp"=>"2024-03-05 13:50:22+0000", 
+  "ndc"=>"ABCE449B5FC84ED5A1C7174840C7A3F8.uat01-vm-tx03", 
+  "id"=>"ABCE449B5FC84ED5A1C7174840C7A3F8.uat01-vm-tx03"
+}
 ```
 
+-----
 ### Get Payment Status for Checkout ID
 ```ruby
-  # Get HyperPay payment status for a given checkout
-  #
-  # Parameters:
-  # @entity_id Entity ID that was used to generate the Checkout ID
-  # @checkout_id HyperPay Checkout ID
-  # @return [Hash] {"result"=>{"code"=>"000.200.000", "description"=>"transaction pending"}, "buildNumber"=>"a58fee65f51ad5776b3c44e9929ca39a62a7cb43@2024-03-04 12:55:38 +0000", "timestamp"=>"2024-03-05 13:50:29+0000", "ndc"=>"ABCE449B5FC84ED5A1C7174840C7A3F8.uat01-vm-tx03"}
-  def get_status(entity_id:, checkout_id:)
-    get("/v1/checkouts/#{checkout_id}/payment"+"?entityId=#{entity_id}")
-  end
-
   checkout = HyperPay::CopyAndPay.new.get_status(entity_id: "", checkout_id: "")
   p checkout['id']
   p checkout['result']['code']
   p checkout['result']['description']
 ```
 
-### Response
+### Pending Response
+```ruby
+{
+  "result"=>{
+    "code"=>"000.200.000", 
+    "description"=>"transaction pending"
+  }, 
+  "buildNumber"=>"a58fee65f51ad5776b3c44e9929ca39a62a7cb43@2024-03-04 12:55:38 +0000", 
+  "timestamp"=>"2024-03-05 13:50:29+0000", 
+  "ndc"=>"ABCE449B5FC84ED5A1C7174840C7A3F8.uat01-vm-tx03"
+}
+```
+
+### Success Response
 ```ruby
-{"result"=>{"code"=>"000.200.000", "description"=>"transaction pending"}, "buildNumber"=>"a58fee65f51ad5776b3c44e9929ca39a62a7cb43@2024-03-04 12:55:38 +0000", "timestamp"=>"2024-03-05 13:50:29+0000", "ndc"=>"ABCE449B5FC84ED5A1C7174840C7A3F8.uat01-vm-tx03"}
+{ 
+  "id"=>"8ac7a4a08e10b158018e1486506e0397",
+  "paymentType"=>"DB", 
+  "paymentBrand"=>"VISA", 
+  "amount"=>"600.00", 
+  "currency"=>"SAR", 
+  "descriptor"=>"0000.0000.0000 Company Name",
+  "merchantTransactionId"=>"139895288", 
+  "result"=>{
+    "code"=>"000.000.000", 
+    "description"=>"Transaction succeeded"
+  },
+  "resultDetails"=>{
+    "ExtendedDescription"=>"Successfully processed", 
+    "ProcStatus"=>"0", 
+    "clearingInstituteName"=>"NCB BANK", 
+    "AuthCode"=>"f2e7a815c3",
+    "ConnectorTxID1"=>"8ac7a4a08e10b158018e1486506e0397", 
+    "ConnectorTxID3"=>"10b158018e1486506e0397", 
+    "ConnectorTxID2"=>"8ac7a4a0", 
+    "AcquirerResponse"=>"00",
+    "EXTERNAL_SYSTEM_LINK"=>"https://csi-test.retaildecisions.com/RS60/TransDetail.aspx?oid=000194001101S2E20110926045038668&support=Link+to+Risk+Details", 
+    "TermID"=>"71F00820",
+    "OrderID"=>"8316384413"
+  },
+  "card"=>{
+    "bin"=>"411111", 
+    "binCountry"=>"PL", 
+    "last4Digits"=>"1111", 
+    "holder"=>"DFGY", 
+    "expiryMonth"=>"05", 
+    "expiryYear"=>"2025", 
+    "issuer"=>{
+      "bank"=>"CONOTOXIA SP. Z O.O"
+    }, 
+    "type"=>"DEBIT", 
+    "level"=>"CLASSIC", 
+    "country"=>"PL", 
+    "maxPanLength"=>"16", 
+    "binType"=>"PERSONAL", 
+    "regulatedFlag"=>"N"
+  }, 
+  "customer"=>{
+    "givenName"=>"Mohamad", 
+    "surname"=>"Kaakati", 
+    "mobile"=>"966540000000", 
+    "email"=>"john@doe.com", 
+    "ip"=>"0.0.0.0", 
+    "ipCountry"=>"SA"
+  }, 
+  "billing"=>{
+    "street1"=>"Saudi Arabia", 
+    "city"=>"Jeddah", 
+    "country"=>"SA"
+  }, 
+  "threeDSecure"=>{
+    "eci"=>"05", 
+    "xid"=>"CAACCVVUlwCXUyhQNlSXAAAAAAA=", 
+    "authenticationStatus"=>"Y"
+  }, 
+  "customParameters"=>{
+    "SHOPPER_MSDKIntegrationType"=>"Checkout UI", 
+    "SHOPPER_device"=>"Apple iPhone 15 Pro", 
+    "CTPE_DESCRIPTOR_TEMPLATE"=>"", 
+    "SHOPPER_OS"=>"iOS 17.4", 
+    "SHOPPER_MSDKVersion"=>"4.12.0", 
+    "3DS2_enrolled"=>"true"
+  }, 
+  "risk"=>{
+    "score"=>"100"
+  }, 
+  "buildNumber"=>"e41989c9076807bb305850f77ce20740230863b9@2024-03-05 14:10:27 +0000", 
+  "timestamp"=>"2024-03-06 16:08:56+0000", 
+  "ndc"=>"67F1CF7891ADB9400CD013BC77A4CE5C.uat01-vm-tx03"
+}
 ```
 
-## Backoffce Operations
+## Response Code Interpretation
+
+----
+
+Now, anywhere in your application where you have a response code from HyperPay that you want to interpret, you can easily get its meaning:
+
+```ruby
+base = HyperPay::Base.new
+result = base.interpret_response_code("000.100.1")
+puts result # :transaction_succeeded
+
+```
+
+## BackOffice Operations
+
+-----
 
 ### Capture Payment
 ```ruby
-HyperPay::CopyAndPay.new.capture_payment(entity_id:, checkout_id:, amount:, currency:)
+HyperPay::CopyAndPay.new.capture_payment(entity_id: "", checkout_id: "", amount: "", currency: "")
 ```
 
 ### Refund Payment

data/lib/HyperPay/base.rb

@@ -2,6 +2,7 @@
 
 require "httparty"
 require "HyperPay/configuration"
+require "HyperPay/response_code_interpreter"
 
 module HyperPay
   class Base
@@ -11,6 +12,10 @@ module HyperPay
       self.class.base_uri base_url
     end
 
+    def interpret_response_code(code)
+      ResponseCodeInterpreter.interpret(code)
+    end
+
     private
 
     def get(path)
@@ -48,8 +53,6 @@ module HyperPay
       HyperPay.configuration.environment == :sandbox ? "https://eu-test.oppwa.com" : "https://eu-prod.oppwa.com"
     end
 
-    private
-
     def prepare_headers(options)
       content_type = options.dig(:headers, "Content-Type") == "application/x-www-form-urlencoded" ?
                        "application/x-www-form-urlencoded" : "application/json"

data/lib/HyperPay/copy_and_pay.rb

@@ -23,6 +23,14 @@ module HyperPay
     # @entity_id Entity ID that was used to generate the Checkout ID
     # @checkout_id HyperPay Checkout ID
     # @return [Hash] {"result"=>{"code"=>"000.200.000", "description"=>"transaction pending"}, "buildNumber"=>"a58fee65f51ad5776b3c44e9929ca39a62a7cb43@2024-03-04 12:55:38 +0000", "timestamp"=>"2024-03-05 13:50:29+0000", "ndc"=>"ABCE449B5FC84ED5A1C7174840C7A3F8.uat01-vm-tx03"}
+    # @return [Hash] {"id"=>"8ac7a4a08e10b158018e1486506e0397",
+    #  "paymentType"=>"DB", "paymentBrand"=>"VISA", "amount"=>"600.00", "currency"=>"SAR", "descriptor"=>"9539.3104.2548 Group",
+    #  "merchantTransactionId"=>"139895288", "result"=>{"code"=>"000.000.000", "description"=>"Transaction succeeded"},
+    #  "resultDetails"=>{"ExtendedDescription"=>"Successfully processed", "ProcStatus"=>"0", "clearingInstituteName"=>"NCB BANK", "AuthCode"=>"f2e7a815c3",
+    #                    "ConnectorTxID1"=>"8ac7a4a08e10b158018e1486506e0397", "ConnectorTxID3"=>"10b158018e1486506e0397", "ConnectorTxID2"=>"8ac7a4a0", "AcquirerResponse"=>"00",
+    #                    "EXTERNAL_SYSTEM_LINK"=>"https://csi-test.retaildecisions.com/RS60/TransDetail.aspx?oid=000194001101S2E20110926045038668&support=Link+to+Risk+Details", "TermID"=>"71F00820",
+    #                    "OrderID"=>"8316384413"},
+    #  "card"=>{"bin"=>"411111", "binCountry"=>"PL", "last4Digits"=>"1111", "holder"=>"DFGY", "expiryMonth"=>"05", "expiryYear"=>"2025", "issuer"=>{"bank"=>"CONOTOXIA SP. Z O.O"}, "type"=>"DEBIT", "level"=>"CLASSIC", "country"=>"PL", "maxPanLength"=>"16", "binType"=>"PERSONAL", "regulatedFlag"=>"N"}, "customer"=>{"givenName"=>"mohammad", "surname"=>"kassab", "mobile"=>"966544299944", "email"=>"mohammad.a.kassab@gmail.com", "ip"=>"213.204.77.158", "ipCountry"=>"LB"}, "billing"=>{"street1"=>"Saudi Arabia", "city"=>"Jeddah", "country"=>"SA"}, "threeDSecure"=>{"eci"=>"05", "xid"=>"CAACCVVUlwCXUyhQNlSXAAAAAAA=", "authenticationStatus"=>"Y"}, "customParameters"=>{"SHOPPER_MSDKIntegrationType"=>"Checkout UI", "SHOPPER_device"=>"samsung samsung SM-S918B", "CTPE_DESCRIPTOR_TEMPLATE"=>"", "SHOPPER_OS"=>"Android 14", "SHOPPER_MSDKVersion"=>"4.12.0", "3DS2_enrolled"=>"true"}, "risk"=>{"score"=>"100"}, "buildNumber"=>"e41989c9076807bb305850f77ce20740230863b9@2024-03-05 14:10:27 +0000", "timestamp"=>"2024-03-06 16:08:56+0000", "ndc"=>"67F1CF7891ADB9400CD013BC77A4CE5C.uat01-vm-tx03"}
     def get_status(entity_id:, checkout_id:)
       get("/v1/checkouts/#{checkout_id}/payment"+"?entityId=#{entity_id}")
     end

data/lib/HyperPay/response_code_interpreter.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class ResponseCodeInterpreter
+  CONSTANTS = {
+    transaction_succeeded: /^(000.000.|000.100.1|000.[36]|000.400.1[12]0)/,
+    transaction_succeeded_review: /^(000.400.0[^3]|000.400.100)/,
+    transaction_pending: /^(000\.200)/,
+    transaction_declined: /^(800\.[17]00|800\.800\.[123])/,
+    rejected_communication_error: /^(900\.[1234]00|000\.400\.030)/,
+    rejected_system_error: /^(800\.[56]|999\.|600\.1|800\.800\.[84])/,
+    rejected_for_risk: /^(100\.400\.[0-3]|100\.380\.100|100\.380\.11|100\.380\.4|100\.380\.5)/,
+    reject_blacklist: /^(800\.[32])/,
+    reject_risk_validation: /^(800\.1[123456]0)/,
+    reject_due_validation: /^(600\.[23]|500\.[12]|800\.121)/
+  }.freeze
+
+  def self.interpret(code)
+    CONSTANTS.find { |_status, regex| code.match?(regex) }&.first || :unknown_code
+  end
+end

data/lib/HyperPay/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HyperPay
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: HyperPay
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Mohamad Kaakati
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-03-06 00:00:00.000000000 Z
+date: 2024-03-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -47,6 +47,7 @@ files:
 - lib/HyperPay/configuration.rb
 - lib/HyperPay/copy_and_pay.rb
 - lib/HyperPay/payment_parameter_builder.rb
+- lib/HyperPay/response_code_interpreter.rb
 - lib/HyperPay/version.rb
 - lib/hyper_pay.rb
 - sig/HyperPay.rbs