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.

Installation
Configuration
API Usage
1. Single Bill Operations
2. Multiple Bills Operations
  1. Create Bills
  2. 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.