Transaction Authorisation

One of the most important steps merchants must take to complete checkout integration is TRANSACTION AUTHORISATION. Because this procedure assists you and Tamara in reaching an agreement on a successful transaction from both sides.

Authorisation Process Workflow

Webhook Notification

On your Tamara Partner portal, you must register our Webhook service with at least this event 'order_approved'

Tamara will notify your webhook endpoint when order information is updated (status changes) with the event you registered. Please use HTTPS. (You can also manage your webhook by visiting this API. Tamara API Documentation)

Once the customer has completed the payment on Tamara checkout, the order will be moved from new to approved status. Meanwhile, Tamara will send a webhook payload for approved notification using the (Http POST request) method to the previously registered webhook URL.

It is recommended that you test the communication, by using a tool like https://webhook.site to see how it works.

Notification Payload

Request Payload

{
"order_id": "8c5e39bb-698d-4c9a-bf9b-efe9bb133fca",
"order_reference_id": "903961577356246",
"order_number": "903961577356246",
"event_type": "order_approved",
"data": []
}

order_id: Tamara’s unique order ID that was created after the checkout session request order_reference_id: merchant’s order reference ID that was provided to Tamara in checkout session request order_number: merchant’s order number that was provided to Tamara in checkout session request

Curl Sample

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <tamaraToken>" \
--data '{"data":[],"order_id":"<tamaraOrderId>","order_reference_id":"<yourRefOrderId>","order_number":"<yourOrderNumber>","event_type":"order_approved"}' \
"<theNotiticationUrlParamInCreateCheckoutRequest>?tamaraToken=<tamaraToken>"

curl --location '{your_notification_url}&tamaraToken=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2ODEyMTY0NDMsImlhdCI6MTY4MTIxNTU0MywiaXNzIjoiVGFtYXJhIn0.oD9V-HhWrAUTpti342QduaBeapncZBZ1apSY9dH8vfs' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2ODEyMTY0NDMsImlhdCI6MTY4MTIxNTU0MywiaXNzIjoiVGFtYXJhIn0.oD9V-HhWrAUTpti342QduaBeapncZBZ1apSY9dH8vfs' \
--header 'Content-Type: application/json' \
--data '{
    "order_id": "8c5e39bb-698d-4c9a-bf9b-efe9bb133fca",
    "order_reference_id": "903961577356246",
    "order_number": "903961577356246",
    "event_type": "order_approved",
    "data": []}' \

Note that we're also sending TamaraToken in Authorization Header, please check if it will conflict with your side.

<tamaraToken> encoded JWT token using HS256 algorithm, and you can use the Notification Token provided by Tamara, to decode it, to ensure that the request to your Notification endpoint comes from Tamara (security aspect).

Authorisation request

After receiving the notification, i.e., once the order payment is ‘approved’ from the checkout flow, your server would need to call back Tamara to confirm the receipt of the transaction response by authorisation, using our Authorisation API

This backend-to-backend communication will also help to avoid the frontend redirection issue during the checkout. For e.g., once the customer has completed the payment on Tamara checkout and couldn't redirect back to your frontend website/ app due to any network/ connection problem, your system would still receive the notification from us in the background.

Once we receive the Authorisation callback, the transaction will be moved to authorised status, and you can start shipping the items to the customer.

If we don't receive the authorisation callback from your end, the order/ transaction on our side would be stuck at approved status, and you will not be able to trigger the Capture API for that payment later, also that payment would be implicitly excluded from your next settlement cycle. Therefore, please implement and test this flow carefully on our sandbox environment before going live.