HyperPay

HyperPay Gem

HyperPay is a powerful payment gateway, transforming the online buying experience in the MENA region. HyperPay enable internet businesses to accept and manage payments online, with more flexibility, security and ease.

HyperPay have been processing online payments since 2014. Today, HyperPay go beyond the payment gateway, as we provide merchants across almost every industry, a full-suite of online payment solutions, to serve every need.

Installation

gem 'HyperPay'

Configuration

config/initializers/hyperpay.rb

require 'hyper_pay'

HyperPay.configure do |config|
  config.authorization = "HYPER_PAY_AUTH_TOKEN"
  config.environment = :sandbox
end

Usage example

Generate Checkout ID

  checkout = HyperPay::CopyAndPay.new.create_checkout_id do |params|
    params.add "entityId", "HYPER_PAY_ENTITY_ID"
    params.add "customer.email", "[e-mail]"
    params.add "customer.mobile", "9665xxxxxxxx"
    params.add "customer.givenName", "John"
    params.add "customer.surname", "Doe"
    params.add "billing.street1", "STREET_NAME"
    params.add "billing.country", "SA"
    params.add "billing.city", "Riyadh"
    params.add "billing.state", ""
    params.add "billing.postcode", "00000"
    params.add "customParameters[3DS2_enrolled]", "true"
    params.add "merchantTransactionId", "YOUR_INVOICE_NUMBER"
    params.add "paymentType", "DB"
    params.add "currency", "SAR"
    params.add "amount", "100" # On Sandbox, HyperPay Can process non-decimal numbers only.
  end

  p checkout['id']
  p checkout['result']['code']
  p checkout['result']['description']

Response

{
  "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

  checkout = HyperPay::CopyAndPay.new.get_status(entity_id: "", checkout_id: "")
  p checkout['id']
  p checkout['result']['code']
  p checkout['result']['description']

Pending Response

{
  "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

{ 
  "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"=>"[e-mail]", 
    "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"
}

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:

base = HyperPay::Base.new
result = base.interpret_response_code("000.100.1")
puts result # :transaction_succeeded

BackOffice Operations

Capture Payment

HyperPay::CopyAndPay.new.capture_payment(entity_id: "", checkout_id: "", amount: "", currency: "")

Refund Payment

HyperPay::CopyAndPay.new.refund_payment(entity_id: "", checkout_id: "", amount: "", currency: "")

Reverse a payment

HyperPay::CopyAndPay.new.reverse_payment(entity_id: "", checkout_id: "")

Authors

• Mohamad Kaakati (@kaakati)