Guides
GuidesAPI ExplorerService StatusPartners PortalWidget DocsSupport

POS Integration

Tamara offers a direct API integration solution directly on your ERP/POS system so that you can create payment links and send them via SMS and collect payment instantly.

Suggest Edits
\*Screenshots and flow above are for demonstration purposes only.

*Screenshots and flow above are for demonstration purposes only.

Your POS/ERP software should be updated to add Tamara as a payment option for your customers.

๐Ÿšง

This page is a high-level explanation only.

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

Step 1: Add items to cart and choose Tamara as a payment method

When a customer decides to pay through Tamara, your server would need to create an in-store checkout session by using the Create In-store Checkout Session API that sends customer an SMS with checkout URL/payment link.

Endpoint

postย ย ย ย ย ย /checkout/in-store-session

Sample Request

Click here to show the sample request 
{
  "total_amount": {
    "amount": "100.00",
    "currency": "SAR"
  },
  "phone_number": "966512345678",
  "email": "[email protected]",
  "order_reference_id": "1231234123-asda-sdfs-afd31241",
  "order_number": "S12356",
  "items": [
    {
      "reference_id": "123456",
      "type": "Digital",
      "name": "Lego City 8601",
      "sku": "SA-12436",
      "image_url": "https://www.example.com/product.jpg",
      "item_url": "https://www.example.com/product.html",
      "quantity": 1,
      "unit_price": {
        "amount": "100.00",
        "currency": "SAR"
      },
      "discount_amount": {
        "amount": "100.00",
        "currency": "SAR"
      },
      "tax_amount": {
        "amount": "100.00",
        "currency": "SAR"
      },
      "total_amount": {
        "amount": "100.00",
        "currency": "SAR"
      }
    }
  ],
  "locale": "ar_SA",
  "payment_type": "PAY_BY_INSTALMENTS",
  "instalments": 3,
  "expiry_time": 15,
  "additional_data": {
    "store_code": "Store code A"
  }
}

The response of this API returns a unique order_id and a checkout_id for completing the transaction. Please store them as we will need them in the next steps.

Sample Response

Click here to show the sample response 
{
  "checkout_id": "34c4d9db-d56a-4155-8750-9281ac0f9ec3",
  "order_id": "3e318d93-0cbc-4689-9e6c-873daeb158de"
}

Step 2: SMS is sent to the customer and opened by customer on their phone

Order is now in the new state at Tamara, this checkout session expires in 15 mins by default and can be voided using our Void Checkout Session API, if needed.

Step 3: Check status of the order via Push or Pull methods

To identify and confirm that the customer has paid their first installment successfully, you will need to use any of the following methods to check:

Get Order Details APIs (Pull Method)

You will need to call Tamara via any of our Get order details APIs to check the status of the order if it has moved from new to fully_captured.

๐Ÿ‘

Check the order status via the APIs every 5-10 seconds until you get fully_captured

A. Using Tamara unique order_id

๐Ÿ‘

Good to Know

This API is preferable to be used IF you reuse your order reference IDs(order numbers) as Tamara's order_id is always unique.

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

Endpoint
getย ย ย ย ย ย /merchants/orders/{order_id}

B. Using your own unique order_reference_id

by replacing {order_reference_id} with the your order_reference_id that you have in your system and which was shared us in the 2. Create Checkout Session API request payload.

Endpoint
getย ย ย ย ย ย /merchants/orders/reference-id/{order_reference_id}

๐Ÿ“˜

You will receive the SAME response for both APIs

The response will detail all of the order details we have on our side which relies heavily on the information we got from your side in the 2. Create Checkout Session API and also we'll return all information from our side about the order status and amounts paid, captured, refunded...etc.

Sample Response
Click here to show the sample response 
{
  "order_id": "0ac038ef-de4a-491c-828e-b02ec0d4582d",
  "order_reference_id": "1231234123",
  "order_number": "1231234123",
  "description": "lorem ipsum dolor lorem ipsum dolor lorem ipsum dolor",
  "consumer": {
    "first_name": "Mona",
    "last_name": "Lisa",
    "email": "[email protected]",
    "phone_number": "966532298658",
    "national_id": "",
    "date_of_birth": "2023-07-10T00:00:00.000Z",
    "is_first_order": null
  },
  "status": "new",
  "shipping_address": {
    "first_name": "Mona",
    "last_name": "Lisa",
    "line1": "3764 Al Urubah Rd",
    "line2": "string",
    "region": "As Sulimaniyah",
    "postal_code": "",
    "city": "Riyadh",
    "country_code": "SA",
    "phone_number": "966532298658"
  },
  "billing_address": {
    "first_name": "Mona",
    "last_name": "Lisa",
    "line1": "3764 Al Urubah Rd",
    "line2": "string",
    "region": "As Sulimaniyah",
    "postal_code": "",
    "city": "Riyadh",
    "country_code": "SA",
    "phone_number": "966532298658"
  },
  "items": [
    {
      "reference_id": "123",
      "type": "Digital",
      "name": "Lego City 8601",
      "sku": "SA-12436",
      "quantity": 1,
      "tax_amount": {
        "amount": 10,
        "currency": "SAR"
      },
      "total_amount": {
        "amount": 100,
        "currency": "SAR"
      },
      "unit_price": {
        "amount": 490,
        "currency": "SAR"
      },
      "discount_amount": {
        "amount": 100,
        "currency": "SAR"
      },
      "image_url": "",
      "item_url": ""
    }
  ],
  "payment_type": "PAY_BY_INSTALMENTS",
  "instalments": 3,
  "total_amount": {
    "amount": 300,
    "currency": "SAR"
  },
  "shipping_amount": {
    "amount": 0,
    "currency": "SAR"
  },
  "tax_amount": {
    "amount": 0,
    "currency": "SAR"
  },
  "discount_amount": {
    "name": "Christmas 2020",
    "amount": {
      "amount": 200,
      "currency": "SAR"
    }
  },
  "captured_amount": {
    "amount": 0,
    "currency": "SAR"
  },
  "refunded_amount": {
    "amount": 0,
    "currency": "SAR"
  },
  "canceled_amount": {
    "amount": 0,
    "currency": "SAR"
  },
  "paid_amount": {
    "amount": 0,
    "currency": "SAR"
  },
  "settlement_status": "",
  "settlement_date": null,
  "created_at": "2023-07-10T08:05:59.000Z",
  "wallet_prepaid_amount": {
    "amount": 0,
    "currency": "SAR"
  },
  "transactions": {
    "cancels": [],
    "captures": [],
    "refunds": []
  },
  "processing": false,
  "store_code": "",
  "additional_data": {
    "single_checkout": false,
    "from_in_store_payment_link": false
  }
}

{
  "order_id": "0ac038ef-de4a-491c-828e-b02ec0d4582d",
  "order_reference_id": "1231234123",
  "order_number": "1231234123",
  "description": "lorem ipsum dolor lorem ipsum dolor lorem ipsum dolor",
  "consumer": {
    "first_name": "Mona",
    "last_name": "Lisa",
    "email": "[email protected]",
    "phone_number": "966532298658",
    "national_id": "",
    "date_of_birth": "2023-06-22T00:00:00.000Z",
    "is_first_order": null
  },
  "status": "fully_captured",
  "shipping_address": {
    "first_name": "Mona",
    "last_name": "Lisa",
    "line1": "3764 Al Urubah Rd",
    "line2": "string",
    "region": "As Sulimaniyah",
    "postal_code": "",
    "city": "Riyadh",
    "country_code": "SA",
    "phone_number": "966532298658"
  },
  "billing_address": {
    "first_name": "Mona",
    "last_name": "Lisa",
    "line1": "3764 Al Urubah Rd",
    "line2": "string",
    "region": "As Sulimaniyah",
    "postal_code": "",
    "city": "Riyadh",
    "country_code": "SA",
    "phone_number": "966532298658"
  },
  "items": [
    {
      "reference_id": "123",
      "type": "Digital",
      "name": "Lego City 8601",
      "sku": "SA-12436",
      "quantity": 1,
      "tax_amount": {
        "amount": 10,
        "currency": "SAR"
      },
      "total_amount": {
        "amount": 100,
        "currency": "SAR"
      },
      "unit_price": {
        "amount": 490,
        "currency": "SAR"
      },
      "discount_amount": {
        "amount": 100,
        "currency": "SAR"
      },
      "image_url": "",
      "item_url": ""
    }
  ],
  "payment_type": "PAY_BY_INSTALMENTS",
  "instalments": 3,
  "total_amount": {
    "amount": 300,
    "currency": "SAR"
  },
  "shipping_amount": {
    "amount": 0,
    "currency": "SAR"
  },
  "tax_amount": {
    "amount": 0,
    "currency": "SAR"
  },
  "discount_amount": {
    "name": "Christmas 2020",
    "amount": {
      "amount": 200,
      "currency": "SAR"
    }
  },
  "captured_amount": {
    "amount": 300,
    "currency": "SAR"
  },
  "refunded_amount": {
    "amount": 0,
    "currency": "SAR"
  },
  "canceled_amount": {
    "amount": 0,
    "currency": "SAR"
  },
  "paid_amount": {
    "amount": 100,
    "currency": "SAR"
  },
  "settlement_status": "",
  "settlement_date": null,
  "created_at": "2023-06-22T10:21:22.000Z",
  "wallet_prepaid_amount": {
    "amount": 0,
    "currency": "SAR"
  },
  "transactions": {
    "cancels": [],
    "captures": [
      {
        "capture_id": "d5a4be96-30de-4df1-a93f-43bb7b85a60a",
        "order_id": "4187f2ee-4b5e-40b7-8244-9cb7d5e54674",
        "merchant_id": "6d9f752e-0bbc-47eb-bcf7-be13adf6f04d",
        "total_amount": {
          "amount": 300,
          "currency": "SAR"
        },
        "refunded_amount": {
          "amount": 0,
          "currency": "SAR"
        },
        "shipping_info": {
          "shipped_at": "2023-06-22T00:00:00.000Z",
          "shipping_company": "N/A",
          "tracking_number": null,
          "tracking_url": null
        },
        "items": [],
        "shipping_amount": {
          "amount": 0,
          "currency": "SAR"
        },
        "tax_amount": {
          "amount": 0,
          "currency": "SAR"
        },
        "discount_amount": {
          "amount": 200,
          "currency": "SAR"
        },
        "created_at": "2023-07-10T08:08:52.000Z"
      }
    ],
    "refunds": []
  },
  "processing": false,
  "store_code": "",
  "additional_data": {
    "single_checkout": false,
    "from_in_store_payment_link": false
  }
}

Registering a Webhook URL (Push Method)

In order to receive real-time updates from Tamara for every status change that happens on your orders, you are encouraged to register a notification webhook URL with Tamara either using our Register Webhook URL API or via our Partners Portal Webhooks management section.

Step 4. Customer wants to return items or requested a refund

Based on your policy, if the customer requests for return, you can fully/partially refund the order using the Refund API

Endpoint

postย ย ย ย ย ย /payments/simplified-refund/{order_id}

Replace the {order_id} with the unique Tamara order_id from the response of the creation of the in-store checkout session and the amount that needs to be refunded as well as a comment for future reference.

Sample Request

Click here to show the sample request 
{
  "total_amount": {
    "amount": 100,
    "currency": "SAR"
  },
  "comment": "Refund for the order 123"
}

Sample Response

In response you will receive the unique refund_id for this specific refund request, as well as the capture_id that was issued when the customer paid their first installment on checkout.

๐Ÿšง

Be Careful

You may have multiple refund_id if you perform multiple partial refunds for the same order_id, please try to store them all in your DBs.

Click here to show the sample response 
{
  "order_id": "0ac038ef-de4a-491c-828e-b02ec0d4582d",
  "comment": "Refund for the order 123",
  "refund_id": "a04390d4-5690-45cd-9086-6980d8a86f72",
  "capture_id": "bd10fc2c-4db8-426e-a1fd-b16388d42c01",
  "status": "fully_refunded",
  "refunded_amount": {
    "amount": 300,
    "currency": "SAR"
  }
}

{
  "order_id": "0ac038ef-de4a-491c-828e-b02ec0d4582d",
  "comment": "Refund for the order 123",
  "refund_id": "924001dc-0e25-463e-82f2-1848aca95542",
  "capture_id": "bd10fc2c-4db8-426e-a1fd-b16388d42c01",
  "status": "partially_refunded",
  "refunded_amount": {
    "amount": 100,
    "currency": "SAR"
  }
}

Optional Steps

Optional: Check customer ID verification/onboarding status

To further optimise the checkout time, you can the implement Customer's ID Verification Status API , to determine whether or not the customer has completed the onboarding previously

Endpoint

postย ย ย ย ย ย /merchants/customer/id-verification-status

While sending phone_number and country_code as query parameters.

Sample Response

Click here to show the sample response 
{
  "is_id_verified": true
}

{
  "is_id_verified": false
}

Optional: 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 such info.

Endpoint

putย ย ย ย ย ย /orders/{order_id}/reference-id

by replacing {order_Id} with the Tamara order_id you got from response of the Create In-store Checkout Session API

and sending the new order_reference_id in the request body.

Sample Request

Click here to show the sample request 
{
  "order_reference_id": "New Reference ID Here"
}

and Tamara will respond back with a success message as follows,

Sample Response

Click here to show the sample response 
{
  "message": "Order reference id was updated successfully"
}

Updated about 1 year ago

Whatโ€™s Next