global_collect 0.1.0

data/lib/global_collect/api_client.rb

@@ -0,0 +1,71 @@
+module GlobalCollect
+  class ApiClient
+    include HTTParty
+    # WDL §4 specifies the body should be xml
+    format :xml
+    # WDL §3.1 specifies the content type
+    headers "Content-Type" => "text/xml; charset=utf-8"
+    # WDL §3.6 recommends this timeout
+    DEFAULT_TIMEOUT = 70
+    # Net::HTTP warns that debug_output should not be set in production
+    # because it is a security problem.
+    debug_output(nil)
+    
+    
+    attr_reader :service, :environment, :authentication
+    def initialize(service, environment, authentication)
+      @serivce = service
+      @environment = environment
+      @authentication = authentication
+      @service_url = ApiClient.service_url(service, environment, authentication)
+    end
+
+    def make_request(request, add_mixins=true)
+      xml = request.to_xml
+      GlobalCollect.wire_logger.info("POST [#{request.action} v#{request.version}] => [#{@service_url}] - body:\n#{xml}")
+      
+      response = nil
+      request_time = Benchmark.realtime do
+        response = self.class.post(@service_url,
+          :body     => xml,
+          :timeout  => DEFAULT_TIMEOUT
+        )
+      end
+      
+      unless response
+        error_message = "Request [#{request.action} v#{request.version}] => [#{@service_url}] failed! No response!"
+        GlobalCollect.wire_logger.error(error_message)
+        raise error_message
+      end
+      GlobalCollect.wire_logger.info("RESP [#{request.action} v#{request.version}] => #{response.code} - #{request_time} s - body:\n#{response.body}")
+      
+      base = GlobalCollect::Responses::Base.new(response.delegate, response.body)
+      raise "Malformed response to #{request.action} request! Body: '#{response.body}'" if base.malformed?
+      request.suggested_response_mixins.each{|m| base.extend(m) } if add_mixins
+      base
+    end
+    
+    private
+    
+    def self.service_url(service, environment, authentication)
+      # WDL §§3.4-5 specify the allowed arguments
+      raise ArgumentError.new("Only [Hosted] Merchant Link is currently supported!") unless [:merchant_link].include?(service)
+      raise ArgumentError.new("Only :test and :production are valid environemnts!") unless [:test, :production].include?(environment)
+      raise ArgumentError.new("Only :ip_check and :client_auth are valid authentication schemes!") unless [:ip_check, :client_auth].include?(authentication)
+      {
+        :merchant_link => {
+          # WDL §3.4 specifies the test environment urls
+          :test       => {
+            :ip_check     => "https://ps.gcsip.nl/wdl/wdl",
+            :client_auth  => "https://ca.gcsip.nl/wdl/wdl"
+          },
+          # WDL §3.5 specifies the prodution environment urls
+          :production => {
+            :ip_check     => "https://ps.gcsip.com/wdl/wdl",
+            :client_auth  => "https://ca.gcsip.com/wdl/wdl"
+          }
+        }
+      }[service][environment][authentication]
+    end
+  end
+end

data/lib/global_collect/builders/do_refund/credit_card_payment.rb

@@ -0,0 +1,12 @@
+module GlobalCollect::Builders::DoRefund
+  class CreditCardPayment < Payment
+    # WDL §5.16.1 defines the refund payment fields
+    def payment_fields
+      super + %w[
+        PAYMENTPRODUCTID
+        CREDITCARDNUMBER
+        EXPIRYDATE
+      ]
+    end
+  end
+end

data/lib/global_collect/builders/do_refund/payment.rb

@@ -0,0 +1,39 @@
+module GlobalCollect::Builders::DoRefund
+  class Payment < Struct.new(:payment)
+    def build(node)
+      node.tag!("PAYMENT") do |payment_node|
+        payment_fields.each do |field|
+          payment_node.tag!(field, payment[field]) if payment[field]
+        end
+      end
+    end
+    
+    # WDL §5.28 Table 105 specifies general payment fields
+    def payment_fields
+      %w[
+        ORDERID
+        EFFORTID
+        MERCHANTREFERENCE
+        REFERENCEORIGPAYMENT 
+        CURRENCYCODE
+        AMOUNT
+        COUNTRYCODE
+        REFUNDDATE
+        SURNAME
+        FIRSTNAME
+        PREFIXSURNAME
+        TITLE
+        COMPANYNAME
+        COMPANYDATA
+        STREET
+        HOUSENUMBER
+        ADDITIONALADDRESSINFO
+        ZIP
+        CITY
+        STATE
+        EMAILADDRESS
+        EMAILTYPEINDICATOR
+      ]
+    end
+  end
+end

data/lib/global_collect/builders/insert_order_with_payment/credit_card_online_payment.rb

@@ -0,0 +1,38 @@
+module GlobalCollect::Builders::InsertOrderWithPayment
+  class CreditCardOnlinePayment < Payment
+    # WDL §5.28 Table 106 specifies credit card payment fields
+    def payment_fields
+      super + %w[
+        EXPIRYDATE             
+        CREDITCARDNUMBER       
+        ISSUENUMBER            
+        CVV                    
+        CVVINDICATOR           
+        AVSINDICATOR           
+        AUTHENTICATIONINDICATOR
+        STTINDICATOR           
+        FIRSTNAME              
+        PREFIXSURNAME          
+        SURNAME                
+        STREET                 
+        HOUSENUMBER            
+        CUSTOMERIPADDRESS      
+        ADDITIONALADDRESSINFO  
+        ZIP                    
+        CITY                   
+        STATE                  
+        PHONENUMBER            
+        EMAIL                  
+        BIRTHDATE              
+        DCCINDICATOR           
+        ISSUERAMOUNT           
+        ISSUERCURRENCYCODE     
+        MARGINRATEPERCENTAGE   
+        EXCHANGERATESOURCENAME 
+        EXCHANGERATE           
+        EXCHANGERATEVALIDTO    
+        MAC                    
+      ]
+    end
+  end
+end

data/lib/global_collect/builders/insert_order_with_payment/hosted_credit_card_online_payment.rb

@@ -0,0 +1,4 @@
+module GlobalCollect::Builders::InsertOrderWithPayment
+  class HostedCreditCardOnlinePayment < CreditCardOnlinePayment
+  end
+end

data/lib/global_collect/builders/insert_order_with_payment/order.rb

@@ -0,0 +1,75 @@
+module GlobalCollect::Builders::InsertOrderWithPayment
+  class Order < Struct.new(:order)
+    def build(node)
+      node.tag!("ORDER") do |order_node|
+        order_fields.each do |field|
+          order_node.tag!(field, order[field]) if order[field]
+        end
+      end
+    end
+
+    # WDL §5.28.1 First table specifies the full list of possible fields
+    def order_fields
+      %w[
+        ORDERID
+        ORDERTYPE
+        AMOUNT
+        AMOUNTSIGN
+        CURRENCYCODE
+        LANGUAGECODE
+        COUNTRYCODE        
+        OVERWRITEPAYMENTREFERNCE
+        IPADDRESSCUSTOMER
+        CUSTOMERID
+        MANDATE
+        TITLE
+        FIRSTNAME
+        PREFIXSURNAME
+        SURNAME
+        STREET
+        HOUSENUMBER
+        ADDITIONALADDRESSINFO
+        ZIP
+        CITY
+        STATE
+        SHIPPINGTITLE
+        SHIPPINGFIRSTNAME
+        SHIPPINGPREFIXSURNAME
+        SHIPPINGSURNAME
+        SHIPPINGSTREET
+        SHIPPINGHOUSENUMBER
+        SHIPPINGADDITIONALADDRESSINFO
+        SHIPPINGZIP
+        SHIPPINGCITY
+        SHIPPINGSTATE
+        SHIPPINGCOUNTRYCODE
+        MERCHANTREFERENCE
+        DESCRIPTOR
+        RESELLERID
+        EMAIL
+        EMAILTYPEINDICATOR
+        COMPANYNAME
+        COMPANYDATA
+        SEX
+        VATNUMBER
+        PHONENUMBER
+        FAXNUMBER
+        INVOICENUMBER
+        INVOICETYPE
+        INVOICEDATE
+        INVOICECLASS
+        ORDERDATE
+        BIRTHDATE
+        TEXTQUALIFIER1
+        TEXTQUALIFIER2
+        TEXTQUALIFIER3
+        ADDITIONALDATA
+        STARTDATE
+        ENDDATE
+        NUMBEROFPAYMENTS
+        STEPWEEK
+        STEPMONTH
+      ]
+    end
+  end
+end

data/lib/global_collect/builders/insert_order_with_payment/payment.rb

@@ -0,0 +1,25 @@
+module GlobalCollect::Builders::InsertOrderWithPayment
+  class Payment < Struct.new(:payment)
+    def build(node)
+      node.tag!("PAYMENT") do |payment_node|
+        payment_fields.each do |field|
+          payment_node.tag!(field, payment[field]) if payment[field]
+        end
+      end
+    end
+    
+    # WDL §5.28 Table 105 specifies general payment fields
+    def payment_fields
+      %w[
+        PAYMENTPRODUCTID
+        AMOUNT
+        AMOUNTSIGN
+        CURRENCYCODE
+        LANGUAGECODE
+        COUNTRYCODE
+        HOSTEDINDICATOR
+        RETURNURL
+      ]
+    end
+  end
+end

data/lib/global_collect/builders/set_payment/payment.rb

@@ -0,0 +1,23 @@
+module GlobalCollect::Builders::SetPayment
+  class Payment < Struct.new(:payment)
+    def build(node)
+      node.tag!("PAYMENT") do |payment_node|
+        payment_fields.each do |field|
+          payment_node.tag!(field, payment[field]) if payment[field]
+        end
+      end
+    end
+    
+    # WDL §5.33.1 specifies general payment fields
+    def payment_fields
+      %w[
+        ORDERID
+        EFFORTID
+        PAYMENTPRODUCTID
+        AMOUNT
+        CURRENCYCODE
+        DATECOLLECT
+      ]
+    end
+  end
+end

data/lib/global_collect/const/payment_product.rb

@@ -0,0 +1,38 @@
+module GlobalCollect::Const
+  module PaymentProduct
+    def self.from_sym(sym)
+      info(sym)
+    end
+    
+    def self.from_code(code)
+      sym = PRODUCTS.detect{|k,v| v.first == code.to_i }.first
+      from_sym(sym)
+    end
+    
+    private
+    def self.info(sym)
+      raise ArgumentError.new("Invalid payment product symbol ''!") unless PRODUCTS[sym]
+      Product.new(sym, *PRODUCTS[sym])
+    end
+    class Product < Struct.new(:symbol, :code, :description)
+      def to_s
+        symbol.to_s
+      end
+    end
+    
+    PRODUCTS = {
+       :visa          => [1  , "Visa Online"            ],
+       :amex          => [2  , "American Express Online"],
+       :mc            => [3  , "MasterCard Online"      ],
+       :visa_delta    => [111, "Visa Delta"             ],
+       :maestro       => [117, "Maestro"                ],
+       :solo          => [118, "Solo"                   ],
+       :visa_electron => [122, "Visa Electron"          ],
+       :dankort       => [123, "Dankort"                ],
+       :laser         => [124, "Laser"                  ],
+       :jcb           => [125, "JCB"                    ],
+       :discover      => [128, "Discover"               ],
+       :carte_bleue   => [130, "Carte Bleue Online"     ]
+    }
+  end
+end

data/lib/global_collect/const/payment_status.rb

@@ -0,0 +1,90 @@
+module GlobalCollect::Const
+  module PaymentStatus
+    def self.from_code(code)
+      code = code.to_i
+      raise ArgumentError.new("Invalid payment status code!") unless STATUSES.key?(code)
+      Status.new(code, *STATUSES[code])
+    end
+    
+    def self.from_name(name)
+      code, strings = STATUSES.detect{|k,v| v.first == name }
+      status(code) if code
+    end
+
+    private
+
+    STATUSES = {
+      0     => ["CREATED"                                                                 , "The payment attempt was created."                                                                                                                                                                                                ],
+      20    => ["PENDING AT MERCHANT"                                                     , "The Hosted Merchant Link transaction is waiting for the consumer to be redirected by the merchant to WebCollect."                                                                                                                ],
+      25    => ["PENDING AT GLOBALCOLLECT"                                                , "The Hosted Merchant Link transaction is waiting for the consumer to enter missing data on the payment pages of GlobalCollect."                                                                                                   ],
+      30    => ["PENDING AT GLOBALCOLLECT"                                                , "The Hosted Merchant Link transaction is waiting for the consumer to be redirected by WebCollect to the payment pages of the bank (optionally after the completion of missing data)."                                             ],
+      50    => ["PENDING AT BANK (Real-time Bank Transfer)/ENROLLED (Credit Card Online)" , "The payment request and consumer have been forwarded to the payment pages of the bank./The payment request and consumer have been forwarded to the authentication pages of the card issuer."                                     ],
+      55    => ["PENDING AT CONSUMER"                                                     , "The consumer received all payment details to initiate the transaction. The consumer must go to the (bank) office to initiate the payment."                                                                                       ],
+      60    => ["NOT ENROLLED"                                                            , "The consumer is not enrolled for 3D Secure authentications."                                                                                                                                                                     ],
+      65    => ["PENDING PAYMENT (CONSUMER AT BANK)"                                      , "The consumer is at an office to initiate a transaction. The status isused when the supplier polls the WebCollect database to verify if apayment on an order is (still) possible."                                                ],
+      70    => ["INDOUBT AT BANK"                                                         , "The status of the payment is in doubt at the bank."                                                                                                                                                                              ],
+      100   => ["REJECTED"                                                                , "WebCollect rejected the payment instruction."                                                                                                                                                                                    ],
+      120   => ["REJECTED BY BANK"                                                        , "The bank rejected the payment."                                                                                                                                                                                                  ],
+      125   => ["CANCELLED BY BANK"                                                       , "The consumer cancelled the payment while on the bank’s payment pages."                                                                                                                                                           ],
+      130   => ["FAILED VERIFICATION"                                                     , "The payment has failed."                                                                                                                                                                                                         ],
+      140   => ["EXPIRED AT BANK"                                                         , "The payment was not completed within the given set time limit by the consumer and is expired. The payment has failed."                                                                                                           ],
+      150   => ["TIMED OUT AT BANK"                                                       , "WebCollect did not receive information regarding the outcome of the payment at the bank."                                                                                                                                        ],
+      160   => ["DENIED"                                                                  , "The transaction had been rejected for reasons of suspected fraud."                                                                                                                                                               ],
+      170   => ["AUTHORISATION EXPIRED"                                                   , "The authorisation is expired because no explicit settlement request was received in time."                                                                                                                                       ],
+      172   => ["AUTHENTICATION_ENROLLMENT_EXPIRED"                                       , "The enrolment period was pending too long."                                                                                                                                                                                      ],
+      175   => ["AUTHENTICATION_VALIDATION_EXPIRED"                                       , "The validation period was pending too long."                                                                                                                                                                                     ],
+      180   => ["INVALED PARES OR NOT COMPLETED"                                          , "The cardholder authentication response from the bank was invalid or not completed."                                                                                                                                              ],
+      200   => ["CARDHOLDER AUTHENTICATED"                                                , "The cardholder was successfully authenticated."                                                                                                                                                                                  ],
+      220   => ["COULD NOT AUTHENTICATE"                                                  , "The authentication service was out of order, cardholder could not be authenticated."                                                                                                                                             ],
+      230   => ["CARDHOLDER NOT PARTICIPATING"                                            , "The cardholder is not participating in the 3D Secure authentication program."                                                                                                                                                    ],
+      280   => ["INVALED PARES OR NOT COMPLETED"                                          , "The cardholder authentication response from the bank was invalid or not completed. Authorization not possible."                                                                                                                  ],
+      300   => ["AUTHORISATION TESTED"                                                    , "Authorisation tested. This payment will be re-authorised and settled offline."                                                                                                                                                   ],
+      310   => ["NOT ENROLLED"                                                            , "The consumer is not enrolled for 3D Secure authentications. Authorization not possible."                                                                                                                                         ],
+      320   => ["COULD NOT AUTHENTICATE"                                                  , "The authentication service was out of order, cardholder could not be authenticated. Authorization not possible."                                                                                                                 ],
+      330   => ["CARDHOLDER NOT PARTICIPATING"                                            , "The cardholder is not participating in the 3D Secure authentication program. Authorization not possible."                                                                                                                        ],
+      350   => ["CARDHOLDER AUTHENTICATED"                                                , "The cardholder was successfully authenticated. Authorization not possible."                                                                                                                                                      ],
+      400   => ["REVISED"                                                                 , "The consumer or WebCollect has revised the payment (with other payment product)."                                                                                                                                                ],
+      525   => ["CHALLENGED"                                                              , "The payment was challenged by your Fraud Ruleset and is pending. Use Process Challenged API or Web Payment Console if you choose to process further."                                                                            ],
+      550   => ["REFERRED"                                                                , "The payment was referred. A ‘manual’ authorisation attempt will be made shortly."                                                                                                                                                ],
+      600   => ["PENDING"                                                                 , "The payment instruction is pending waiting for a mandate (direct debit), settlement (credit card online) or acceptation (recurringorders)."                                                                                      ],
+      650   => ["PENDING VERIFICATION"                                                    , "The real-time bank payment is pending verification by the batch process. If followed by 50 PENDING AT BANK, the verificationcould not be carried out successfully."                                                              ],
+      800   => ["READY"                                                                   , "GlobalCollect accepted the payment instruction. For Credit Card Online the payment is authorized, but not yet settled. For a Real-time Bank Transfer the return message from the bank indicates that the payment was successful."],
+      850   => ["MARKED FOR SENDING"                                                      , "Temporary status. The payment instruction was accepted and is being further processed."                                                                                                                                          ],
+      900   => ["SENT"                                                                    , "Temporary status. The payment instruction was accepted and is being further processed."                                                                                                                                          ],
+      900   => ["PROCESSED"                                                               , "The refund was processed."                                                                                                                                                                                                       ],
+      950   => ["INVOICE_SENT"                                                            , "The invoice was printed and sent."                                                                                                                                                                                               ],
+      975   => ["SETTLEMENT IN PROGRESS"                                                  , "The settlement file was sent for processing at the financiali nstitution."                                                                                                                                                       ],
+      1000  => ["PAID"                                                                    , "The payment was paid."                                                                                                                                                                                                           ],
+      1010  => ["ACCOUNT DEBITED"                                                         , "GlobalCollect debited the consumer account."                                                                                                                                                                                     ],
+      1020  => ["CORRECTED"                                                               , "GlobalCollect corrected the payment information given."                                                                                                                                                                          ],
+      1030  => ["WITHDRAWN CHARGEBACK"                                                    , "The chargeback has been withdrawn."                                                                                                                                                                                              ],
+      1050  => ["REMITTED"                                                                , "The funds have been made available for remittance to the merchant."                                                                                                                                                              ],
+      1100  => ["REJECTED"                                                                , "GlobalCollect rejected the payment attempt."                                                                                                                                                                                     ],
+      1110  => ["REFUSED BY ACCEPTING BANK"                                               , "The acquiring bank rejected the direct debit."                                                                                                                                                                                   ],
+      1120  => ["REFUSED SETTLEMENT"                                                      , "Refused settlement before payment from Acquirer."                                                                                                                                                                                ],
+      1150  => ["REFUSED SETTLEMENT"                                                      , "Refused settlement after payment from Acquirer"                                                                                                                                                                                  ],
+      1210  => ["REFUSED BY CONSUMER BANK"                                                , "The bank of the consumer rejected the direct debit."                                                                                                                                                                             ],
+      1250  => ["BOUNCED"                                                                 , "The payment bounced."                                                                                                                                                                                                            ],
+      1500  => ["CHARGED BACK BY CONSUMER"                                                , "The payment was charged back by the consumer."                                                                                                                                                                                   ],
+      1510  => ["REVERSAL BY CONSUMER"                                                    , "The consumer reversed the direct debit payment."                                                                                                                                                                                 ],
+      1520  => ["REVERSED"                                                                , "The payment was reversed."                                                                                                                                                                                                       ],
+      1800  => ["REFUNDED"                                                                , "The payment was refunded."                                                                                                                                                                                                       ],
+      1810  => ["CORRECTED REFUND"                                                        , "GlobalCollect corrected the refund information given."                                                                                                                                                                           ],
+      1850  => ["REFUSED REFUND"                                                          , "Refund is refused by the Acquirer"                                                                                                                                                                                               ],
+      2000  => ["ACCOUNT CREDITED"                                                        , "GlobalCollect credited the consumer account."                                                                                                                                                                                    ],
+      2030  => ["WITHDRAWN REVERSED PAYOUT"                                               , "Withdrawn Reversed Payout"                                                                                                                                                                                                       ],
+      2110  => ["REJECTED BY GLOBALCOLLECT"                                               , "GlobalCollect rejected the payout attempt."                                                                                                                                                                                      ],
+      2120  => ["REFUSED BY ACCEPTING BANK"                                               , "The acquiring bank rejected the payout attempt."                                                                                                                                                                                 ],
+      2130  => ["REFUSED BY CONSUMER BANK"                                                , "The consumer bank rejected the payout attempt."                                                                                                                                                                                  ],
+      2210  => ["REVERSAL BY CONSUMER"                                                    , "The consumer reversed the payout."                                                                                                                                                                                               ],
+      2220  => ["REVERSED"                                                                , "The payout was reversed."                                                                                                                                                                                                        ],
+      99999 => ["CANCELLED"                                                               , "Payment/Refund/Payout attempt was cancelled by the merchant."                                                                                                                                                                    ]
+    }
+
+    class Status < Struct.new(:code, :name, :description)
+      def to_s
+        name
+      end
+    end
+  end
+end

data/lib/global_collect/field_validator.rb

@@ -0,0 +1,47 @@
+module GlobalCollect
+   # WDL §5 TABLE 10 specifies the tokens and their meaning
+  class FieldValidator
+    def initialize(token, required)
+      if token =~ /([A-Z]{1,2})(\d+)?/
+        @type = $1
+        @size = $2.to_i
+        @required = (required == "R")
+      else
+        raise ArgumentError.new("Invalid validation token '#{token}'!")
+      end
+    end
+    
+    def to_sym
+      case @type
+      when "D"  then :datetime
+      when "AN" then :alphanumeric
+      when "N"  then :numeric
+      end
+    end
+    
+    def inspect
+      "<FieldValidator #{to_sym}[#{@size}]>"
+    end
+    
+    def validate(value)
+      return false if  @required && value.nil?
+      return true  if !@required && value.nil?
+      value = value.to_s
+      case @type
+      # Examples throughout §5 suggest this date format.
+      # See §5.1.3. Example for instance.
+      when "D"
+        size = @size.zero? ? 14 : @size
+        return !!(value =~ /^\d{#{size}}$/) && (!!Time.parse(value) rescue false)
+      # This is a liberal interpretation of alphanumeric, but examples like
+      # §5.3.1 (IPADDRESS), §5.28.1 (CITY) suggest that spaces and punctuation
+      # are acceptable as well. This leaves us just checking max size.
+      when "AN"
+        return (value.size <= @size)
+      # §5.28.1 (AMOUNT) seems to allow for size <= the specifier.
+      when "N"
+        return !!(value =~ /^\d{1,#{@size}}$/)
+      end
+    end
+  end
+end