🚧

This page is a high-level explanation only.

Consult the API References for further details on how to use our APIs properly.

The Tamara online payment journey will always start with a customer adding items to their cart and heading to the checkout page to choose a payment method to use.

Step 1. Create Checkout Session API

Customer now sees Tamara as an available payment method on your store, and proceeds to choose it to checkout with.

When a customer decides to pay using Tamara and proceeds to checkout, your server needs to create a checkout session request to send the details of the purchase, such as the total amount to be paid using Tamara, currency, consumer information, item details and your unique order reference ID.

The response of this API returns a unique Tamara order_id, checkout_id, status and a checkout_url that the user should be redirected to, to complete their transaction with Tamara.

Endpoint

Sample Request and Response

https://docs.tamara.co/reference/createcheckoutsession

📘

Save the order_id and checkout_id in your DBs

Step 2. Customer Journey

Your server will then redirect the customer to the checkout_url received in the above step to complete their Tamara checkout experience.

The customer will then be redirected to your website via the respective redirect URLs that were provided under the merchant_url object in your checkout session request.

Tamara will also send a notification payload for approved status change by POST method, to the Webhook URL that you registered on our partner portal or via our Webhook Management APIs

If you'd like to check the order status while or after the customer completes the payment at Tamara, you can do so by using the Get Order Details API.

Step 3. Authorise Order API

After receiving the approved webhook notification in the previous step, i.e., once the order status is on approved state in the checkout flow, your server would need to call back Tamara to confirm the receipt of the approved notification by authorising the order/transaction, by replacing {order_id} in the endpoint path with the Tamara order_id you got from response of the **1. Create Checkout Session API **

Endpoint

Sample Request and Response

https://docs.tamara.co/reference/authoriseorder

👍

Once the authorised stage is reached, you can consider the order as paid, and proceed further.

Step 3.a Cancel API

If, for any valid reason, the customer wishes to not continue with receiving their order after it has been paid for using Tamara and authorized by the merchant, OR wishes to remove some items from their order, then you can initiate a Cancel Order Request.

Either completely cancel the order OR update the order and remove the items that are no longer needed by the customer from the original order.

Endpoint

Sample Request and Response

https://docs.tamara.co/reference/cancelorder

🚧

Order must be in authorized stage only to be able to use the Cancel API, otherwise this API will return an error.

Step 3.b Capture Order API

After authorising, and once the order is shipped/fulfilled, your server would then need to send a Capture request for the payment.

Endpoint

Sample Request and Response

https://docs.tamara.co/reference/captureorder

👍

❗️ NOTICE: Orders NOT captured are NOT settled to your account!

Once the partially_captured or fully_captured state is reached, you can consider the amounts captured to be added to your next settlement cycle.

If an order is not Captured within 21 days from when it is Authorised, Tamara will auto-capture that order and it will be moved to Fully Captured status

Optional Steps

Simplified Refund API

Based on your returns and refunds policies, after shipping/capturing, if a customer wishes to return the items or requests a refund, your server would need to send a refund request to Tamara

Endpoint

Sample Request and Response

https://docs.tamara.co/reference/simplifiedrefund

⚠️

❗️Refund transactions are processed in realtime on Tamara's end but,

Refunds might take several hours to several days to reflect on the customer's bank account depending on the customer's bank's processing time.

Once the fully_refunded or partially_refunded state is reached, you can consider the amount to have been refunded by Tamara to the customer's card right away, and the refunded amount will be deducted from your next settlement.

Get Order Details API

You may also check the order status for an order, in case your server did not receive any update/notification from our side, for any unforeseen reason.

Endpoint

by replacing {order_Id} with the Tamara order_id you got from response of the 1. Create Checkout Session API

Sample Request and Response

https://docs.tamara.co/reference/getorderdetails

Update order_reference_id

If you have the need to update your order's order_reference_id that is stored at our side since the creation of checkout session you can do so by using our API for updating this information.

Endpoint

by replacing {order_Id} with the Tamara order_id you got from response of the 1. Create Checkout Session API and sending the new order_reference_id in the request body.

Sample Request and Response

https://docs.tamara.co/reference/updateorderreferenceid