Tamara

Ruby gem for Tamara

For reference on the internals & specifics of Tamara, please head to their official documentation

Table of Contents

1. Installation
2. Configuration
3. APIs
   1. List Available Payment Types
   2. Check Payment Options Availability
   3. Orders
      1. Create
      2. Authorize
      3. Cancel
      4. Order Details
         1. Get Order Details by Tamara's order_id
         2. Get Order Details by Merchant's order_reference_id
      5. Payments
      6. Capture
      7. Webhooks
      8. Register Webhook
   4. Errors
   5. Contributing
   6. License

Installation

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

$ bundle add tamara

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

$ gem install tamara

Next, you need to run the generator:

$ rails generate tamara:install

Configuration

Configure the gem with your configuration

Tamara.configure do |config|
  config.api_token = "api_token"
  config.notification_token = "notification_token"
  config.public_key = "public_key"
  config.checkout_optional_keys = {}
end

For api_token, you can set its value in 3 ways

• Global across whole application (through initializer and configuration)

  Tamara.configure do |config|
  config.api_token = "api_token"
  end
  

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

  Tamara.api_token = "api_token"
  

• Per request (through opts parameter)

  Tamara::PaymentTypes.list(opts: { api_token: "api_token" })
  

APIs

Any API call will return an object with following methods:

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

List Available Payment Types

Tamara::PaymentTypes.list(country: "SA", order_value: 1)

Check Payment Options Availability

Tamara::PaymentOptions.check(country: "SA", phone_number: "544337766", order_value: { amount: 100, currency: "SAR" })

Online Checkout:

Create

Tamara::Orders.create(
  order_reference_id: "abd12331-a123-1234-4567-fbde34ae",
  country_code: "SA",
  description: "Enter order description here",
  total_amount: {
    amount: 300,
    currency: "SAR"
  },
  shipping_amount: {
    amount: 10,
    currency: "SAR"
  },
  tax_amount: {
    amount: 0,
    currency: "SAR"
  },
  consumer: {
    email: "customer@email.com",
    first_name: "Mona",
    last_name: "Lisa",
    phone_number: "566027755"
  },
  items: [
    {
      name: "Lego City 8601",
      type: "Digital",
      reference_id: "123",
      sku: "SA-12436",
      quantity: 1,
      unit_price: {
        amount: 490,
        currency: "SAR"
      },
      total_amount: {
        amount: 100,
        currency: "SAR"
      }
    }
  ],
  merchant_url: {
    cancel: "http://example.com/#/cancel",
    failure: "http://example.com/#/fail",
    success: "http://example.com/#/success",
    notification: "https://example-notification.com/payments/tamaranotifications"
  },
  shipping_address: {
    city: "Riyadh",
    country_code: "SA",
    first_name: "Mona",
    last_name: "Lisa",
    line1: "3764 Al Urubah Rd",
    line2: "string",
    phone_number: "532298658",
    region: "As Sulimaniyah"
  }
)

:exclamation::exclamation::exclamation: For creating an online checkout session, some information might be optional. You can configure these through checkout_optional_keys in your initializer.

The below example will make description key optional and sku, type optional for items array.

Tamara.configure do |config|
  config.checkout_optional_keys = { description: [], items: [:sku, :type] }
end

:warning: This will not make items key optional. To do so, you need to pass an empty array [] to the key

Tamara.configure do |config|
  config.checkout_optional_keys = { description: [], items: [] }
end

Authorize

Tamara::Orders.authorize(order_id: "ff776045-513b-4cd7-8b4f-e60673daad84")

Cancel

Tamara::Orders.cancel(
  order_id: "abd12331-a123-1234-4567-fbde34ae",
  total_amount: {
    amount: 300,
    currency: "SAR"
  }
)

Order Details

Get Order Details by Tamara's order_id

Tamara::Orders.get_by_tamara_order_id(order_id: "ff776045-513b-4cd7-8b4f-e60673daad84")

Get Order Details by Merchant's order_reference_id

Tamara::Orders.get_by_merchant_order_reference_id(order_id: "ff776045-513b-4cd7-8b4f-e60673daad84")

Payments

Capture

Tamara::Payments.capture(
  order_id: "ff776045-513b-4cd7-8b4f-e60673daad84",
  total_amount: {
    amount: 300,
    currency: "SAR"
  },
  shipping_info: {
    shipped_at: "2020-03-31T19:19:52.677Z",
    shipping_company: "DHL",
    tracking_number: "100",
    tracking_url: "https://shipping.com/tracking?id=123456"
  },
  items: [
    {
      name: "Lego City 8601",
      type: "Digital",
      reference_id: "123",
      sku: "SA-12436",
      quantity: 1,
      discount_amount: {
        amount: 100,
        currency: "SAR"
      },
      tax_amount: {
        amount: 10,
        currency: "SAR"
      },
      unit_price: {
        amount: 490,
        currency: "SAR"
      },
      total_amount: {
        amount: 100,
        currency: "SAR"
      }
    }
  ]
)

Webhooks

Register Webhook

Tamara::Webhooks.register(
  type: "order",
  events: [
    "order_approved",
    "order_authorised",
    "order_canceled",
    "order_updated",
    "order_captured",
    "order_refunded"
  ],
  url: "https://www.enteryoursitehere.com/webhooks",
  headers: {
    authorization: "123344-1231-abcd-adfe-123456"
  }
)

Errors:

Errors could be one of the following:

Tamara::AuthenticationError
Tamara::InvalidRequestError (With `param` attribute)
Tamara::APIError

Contributing

Bug reports and pull requests are welcome.

License

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