1. Get started¶
Click on WooCommerce > Settings > Payments > Tamara Gateway > Manage.
2.1 Enable/Disable: Tick/ untick this checkbox if you wish to enable/ disable Tamara Payment method for WooCommerce on Checkout.
2.2 Tamara Settings Help Texts: You can browse some help texts and find solutions to common issues with our plugin.
3. Credentials Configuration¶
3.1 Tamara Working Mode:
- Sandbox Mode: for Testing.
- Live Mode: for Live.
3.2 API URL, Merchant Token and Notification Token: Sandbox or Live API URL and tokens received from Tamara. This configuration specifies whether you would simulate test transactions using Tamara Sandbox or process live transactions using Tamara Production.
If you input the wrong token(s), the plugin will be disabled and an error for incorrect credentials will be shown.
4. Pay By Instalments Options¶
This option will be available after you save your token. The option fields for each country will be separated. You can also update the payment method title of each instalment method in both English and Arabic on checkout.
5. Order Statuses Mappings¶
Click on Manage Order Statuses Mappings
5.1 Order status for payment cancelled from Tamara: The status that you want to set when its payment is canceled from Tamara.
5.2 Order status for payment failed from Tamara: The status that you want to set when the payment is failed (declined) from Tamara.
5.3 Order status for Authorise success from Tamara: The status that you want to set when the payment is made and authorised successfully from Tamara.
5.4 Order status for Authorise failed from Tamara: The status that you want to set when the payment cannot be authorised from Tamara.
5.5 Order status for Capture failed from Tamara: The status that you want to set when the payment cannot be captured from Tamara.
5.6 Order status for cancelling the order from Tamara through Webhook:k The status that you want to set when it is cancelled from Tamara (Order Expired, Order Declined) through Webhook.
Click on WooCommerce > Orders to check the set order statuses reflecting for your orders.
6. Order Statuses to Trigger Tamara Events¶
Click on Manage Order Statuses Trigger
6.1 Order status that trigger Tamara cancel process for an order: The status that you want the extension to trigger Tamara API to proceed with the Cancel payment process.
6.2 Order status that trigger Tamara capture process for an order: The status that you want the extension to trigger Tamara API to proceed with the Capture payment process.
- An order can not be canceled if its payment has been captured from Tamara.
In this case, please use the WooCommerce “Refund” function instead.
- When initiating a refund, please choose at least one item to refund and enter the full shipping amount to refund.
7. Tamara General Settings¶
7.1 Enable Cron Job: If enabled, Tamara will use a cron-job to find all the completed orders that have not been verified/ authorised/ captured within 180 days and force them to be authorised or captured. It executes an asynchronous call at the Admin request to perform this action.
7.2 Allowed Shipping Countries: The shipping countries that are allowed to use Tamara. Payment types of a country will only be fetched if that country is included in this setting. If the shipping country of an order is not in this list, Tamara Payment method will be hidden from Checkout.
7.3 Default Billing Country: Default billing country to use with Tamara if none is set during the checkout progress.
7.4 Enable Tamara Custom Log Message: If enabled, all the message logs will be written and saved to the Tamara custom log file in your upload directory. The message log download link will be available below, after you enable this setting.
7.5 Force Enable Billing Phone: If enabled, the billing phone field will be forced to display on the checkout screen, which is required to be used for Tamara checkout.
7.6 Popup Widget Position: The position where you want to display the Tamara Payment Popup Widget on a single product page. Alternatively, you can use short code with attributes to show it on the custom pages, for e.g. [tamara_show_popup price="99" , currency="SAR" , language="en"].
7.7 Logo Image URL: The URL of the image icon to appear on payment method selected at checkout. The recommended size must be no larger than 230x60, image format.
7.8 Enable Webhook: If enabled, Tamara will use the webhook to handle the Order Declined and Order Expired. After a certain time, the order that has been declined or expired from Tamara will be updated to the status that is set in “Order Status for Cancelling from Tamara” option. The Webhook ID will also be shown at the field below.
7.9 Tamara Payment Cancel Url: The custom cancel URL for customers to be redirected to, after a payment is cancelled (blank = default). You can use
after_tamara_cancel to handle further actions.
7.10 Tamara Payment Failure Url: The custom failure URL customers to be redirected to, after a payment has failed (blank = default). You can use
after_tamara_failure to handle further actions.
7.11 Excluded Product Ids: The product Ids that you want to exclude from using Tamara to checkout (These Ids are separated by comma, for e.g., 101, 205).
7.12 Excluded Product Category Ids: The product category Ids that you want to exclude from using Tamara to checkout (These Ids are separated by commas, for e.g., 26, 104).
7.13 Enable Beautiful Merchant Urls: If enabled, the URLs for handling webhooks will be beautified. For e.g., if Tamara payment success URL is:
then once this option is enabled, it will be changed to:
- Click on Dashboard > Settings > Permalinks > Save changes.
7.14 Default Merchant URLs: The URLs used for corresponding pages.
7.15 Debug Info: This option allows to display the debug information with the PHP version and its loaded extensions used for the plugin.
8. Payment types limits and its caching¶
When using this plugin for the first time, you will need to:
- Put your API URL, Merchant Token and Notification token to the forms.
- Save the settings.
Based on the available payment types for your tokens:
- Tick to enable the respective payment option, as per your usage requirement.
- Save the settings again.
Country payment types and limit amounts cache will be saved and updated every 10 minutes. If you need to update the adjusted limits with Tamara:
- Click on “Save changes” or refresh the settings screen without changing anything, for the plugin to refresh the limits cache.
If you experience any issues with the payment types and limit amounts, it is recommended to click on “Save changes” to save the settings, so the cached limit amounts will be cleared and updated again, by pulling the latest updates from Tamara.
9. The Notification URL and Webhook URL¶
Notification URL: Used to handle instant Payment Notification from Tamara to update order. It's used when a payment is completed, for Tamara API to sent the notification to check if the payment is authorised or not. We use it to receive the response and handle further actions.
Webhook URL: Your Webhook endpoint that is used to receive notifications from Tamara when the order information is updated (status changes). You will need to enable the Webhook settings, to enable this feature. When a Webhook is retrieved, a unique webhook id from Tamara is sent. We use it to receive response from Tamara API to handle the order status on our site (for Order Declined and Order Expired).