sadad

Sadad Payments Gem

Ruby gem for integrating with Sadad payment gateway. This gem provides complete functionality for creating and managing bills through Sadad's API.

Table of Contents

• Installation
• Configuration
• API Usage
  • Single Bill Operations
    • Create Bill
    • Update Bill
    • Inquiry Bill
    • Expire Bill
  • Multiple Bills Operations
    • Create Bills
    • Deactivate Bill
• Error Handling
• Contributing
• License

Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add sadad

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install sadad

Next, you need to run the generator:

$ rails generate sadad:install

Note: This will create a config/initializers/sadad.rb file with the default configuration.

Configuration

Configure the gem with your configuration

Sadad.configure do |config|
  config.merchant_id = "merchant_id"
  config.program_id = "program_id"
  config.client_certificate_pem_file = "client_certificate_pem_file"
end

For merchant_id, program_id, and client_certificate_pem_file, you can set its value in 3 ways

• Global across whole application (through initializer and configuration)

  Sadad.configure do |config|
    config.merchant_id = "merchant_id"
    config.program_id = "program_id"
    config.client_certificate_pem_file = "client_certificate_pem_file"
  end
  

• Per method or block (through the application variables). All consecutive requests will use that token until it is set to a different value

  Sadad.merchant_id = "merchant_id"
  Sadad.program_id = "program_id"
  Sadad.client_certificate_pem_file = "client_certificate_pem_file"
  

• Per request (through opts parameter)

  Sadad::Bills.create(opts: { merchant_id: "merchant_id", program_id: "program_id", client_certificate_pem_file: "client_certificate_pem_file" })
  

• Note: client_certificate_pem_file should be set to the encoded file content of the certificate file using Base64. Use Base64.strict_encode64(File.read("path_to_file")) to encode the file content.

API Usage

Any API call will return an object with following methods:

result = Sadad.doSomething
result.success?
result.failure?
result.payload
result.error

Single Bill Operations

Create Bill

Sadad::SingleBill.create(
  user_national_id: "1133331101",
  user_first_name: "Khaled",
  user_last_name: "Ahmed",
  invoice_id: "1998654321",
  bill_type: "OneTime",
  display_info: "Details of the invoice issued",
  amount_due: 275.25,
  invoice_created_date: "2025-02-23T10:46:37",
  expiry_date: "2025-03-23T10:46:37"
  opts: {}
)

Update Bill

Sadad::SingleBill.update(
  user_national_id: "1133331101",
  user_first_name: "Khaled",
  user_last_name: "Ahmed",
  invoice_id: "1998654321",
  bill_type: "OneTime",
  display_info: "Details of the invoice issued",
  amount_due: 275.25,
  invoice_created_date: "2025-02-23T10:46:37",
  expiry_date: "2025-03-23T10:46:37",
  opts: {}
)

Expire Bill

Sadad::SingleBill.expire(
  user_national_id: "1133331101",
  user_first_name: "Khaled",
  user_last_name: "Ahmed",
  invoice_id: "1998654321",
  bill_type: "OneTime",
  display_info: "Details of the invoice issued",
  amount_due: 275.25,
  invoice_created_date: "2025-02-23T10:46:37",
  expiry_date: "2025-03-23T10:46:37",
  opts: {}
) 

Inquiry Bill

Sadad::SingleBill.inquiry(
  sadad_number: "1998654321",
  opts: {}
)

Multiple Bills Operations

Create Bills

invoices = [
  {
    user_national_id: "1133331101",
    user_first_name: "Khaled",
    user_last_name: "Ahmed",
    invoice_id: "1998054111",
    invoice_status: "BillNew",
    bill_type: "OneTime",
    display_info: "Details of the invoice issued",
    amount_due: 275.25,
    invoice_created_date: "2025-02-23T10:46:37",
    expiry_date: "2025-03-23T10:46:37"
  },
  {
    user_national_id: "1983331102",
    user_first_name: "Ahmed",
    user_last_name: "Ali",
    invoice_id: "1998254321",
    invoice_status: "BillNew",
    bill_type: "Recurring",
    display_info: "Monthly subscription payment",
    amount_due: 5000.00,
    invoice_created_date: "2025-02-23T10:46:37",
    expiry_date: "2025-03-23T10:46:37",
    minimum_partial_amount: 500
  }
]

Sadad::MultipleBills.create(invoices, opts: {})

Deactivate Bill

Sadad::MultipleBills.deactivate(sadad_numbers: ["1998654321", "1998654322"], opts: {})

Errors:

Errors could be one of the following:

Sadad::ForbiddenError
Sadad::APIConnectionError
Sadad::APIError
Sadad::InvalidRequestError (With `param` attribute)

Contributing

Bug reports and pull requests are welcome.

License

The gem is available as open source under the terms of the MIT License.