Integrate via SDK

Mthmr Cashback also provides an SDK to integrate it with your web or mobile application seamlessly. On this page, we will go over how to install and import the package and how to use its functions.

📘

Prerequisites

Before using the SDK, you will need to obtain the following information from the MTHMR Cashback application:

• URL: Refers to the environment that will be used.
• applicationId and applicationKey: Information used to perform the authenticattion, these will be given to you by the Mthmr team.

Installing and importing Mthmr library

The Mthmr SDK runs in Python. Therefore, before starting the installation, be sure to have pip installed on your machine.

Use the following command to install the Mthmr SDK package in your project.

pip install mthmrcashbacksdk

After importing the mthmr_query class from the Mthmr Cashback library.

from mthmrcashback import mthmr_query

URL = "ENVIRONMENT_URL"  
applicationId = "YOUR_APPLICATION_ID"  
applicationKey = "YOUR_APPLICATION_KEY"

Note that you need to replace the placeholders with your actual values for the URL, applicationId, and applicationKey.

Authentication

The get_token function retrieves an access token that allows your application to interact with the Mthmr Cashback system. You'll use the token to perform the other actions with the SDK. The following code block presents an example of how to use the function get_token:

Token = mthmr_query.get_token(URL, applicationId, applicationKey)  

Add Customer Data

This function lets you add new customer information to the Mthmr Cashback system. Later on, these customers will be associated with transactions through their customer_id to process their cashback. See the following code block:

dataCustomers=[
  {
    "customer_id": "a8de52aa-49e7-4e5c-bb66-1c82ac1d551d",
    "birthday": "1995-03-15",
    "gender": "Male",
    "location": {
    	"country": "Saudi Arabia",
    	"city": "Riyadh"
    }
  },
  {
    "customer_id": "a8de52aa-49e7-4e5c-bb66-1c82ac1d551d2",
    "birthday": "1983-05-01",
    "gender": "Female"
  }
]

addCustomers = mthmr_query.add_customers(URL, Token, dataCustomers)

In it, we created an array of objects called dataCustomers, with all the transaction details and information to be integrated into the system and sent as a parameter in the add_customers function.

See the Customer object page for more information on the object's parameters.

Read Customer Data

This function retrieves existing customer data from the Mthmr Cashback system.

customers = mthmr_query.get_customers(URL, Token)

Add Transaction Data

This function seamlessly incorporates into Mthmr Cashback transactions associated with your customers to process their cashback. See the following code block:

 dataTransactions=[
  {
    "transaction_id": "b65cca2a-6809-11ee-8c99-0242ac12001696",
    "description": "description",
    "customer_id": "a8de52aa-49e7-4e5c-bb66-1c82ac1d551d272",
    "date": "2024-04-25T10:27:03.987662",
    "merchant": : {
      "id":"f4e22e84d846e8c01de33b3cb19c8cae",
      "name":"MTHMR",
      "category_code":"75d80ed3fff52b2b7b2beaf3354be6d3"
    },
    "location": {
      "country":"KSA",
      "city":"Riyadh"
    },
    "amount": 100.50
   },
   {
    "transaction_id": "a8de52aa-49e7-4e5c-bb66-1c82ac1d551d273",
    "description": "description",
    "customer_id": "a8de52aa-49e7-4e5c-bb66-1c82ac1d551d272",
    "date": "2024-04-11T10:27:03.987662",
    "merchant": : {
      "id":"f4e22e84d846e8c01de33b3cb19c8cae",
      "name":"MTHMR",
      "category_code":"75d80ed3fff52b2b7b2beaf3354be6d3"
    },
    "location": {
      "country":"KSA",
      "city":"Riyadh"
    },
    "amount": 150.28
   }
]

addTransactions = mthmr_query.add_transactions(URL, Token, dataTransactions)

In it, we created an array of objects called dataTransactions, with all the transaction details and information to be integrated into the system and sent as a parameter in the.add_transactions function.

See the Transaction object page for more information on the object's parameters.

Adding Transactions History

Use this function to add historical transaction data for that particular customer, and based on that data, the customer can qualify for offers that better suit him. See the following code block:

  dataTransactionsHistory=[
    {
        "transaction_id": "a8de52aa-49e7-4e5c-bb66-1c82ac1d551d273",
        "description": "description",
        "customer_id": "a8de52aa-49e7-4e5c-bb66-1c82ac1d551d272",
        "date": "2024-04-11T10:27:03.987662",
        "merchant": : {
          "id":"f4e22e84d846e8c01de33b3cb19c8cae",
          "name":"MTHMR",
          "category_code":"75d80ed3fff52b2b7b2beaf3354be6d3"
        },
        "location": {
          "country":"KSA",
          "city":"Riyadh"
        },
        "amount": 150.12
     }
  ]

addTransactionsHistory = mthmr_query.add_transactions_history(URL, Token, dataTransactionsHistory)

It works similarly to the add_transactions function from the previous section, but no cashback is processed in this case.

Receiving Active Offers

This function retrieves information on active cashback offers within the Mthmr Cashback program. See an example on the following code block:

activeOffers = mthmr_query.get_active_offers(URL, Token)

You can then present these offers to your customers through your mobile or web app.

Receiving Cashback Data

This function allows you to retrieve cashback data for a specified date range. You can use it for accounting purposes or to retrieve a list of processed cashbacks. See the following code block:

date_from = "2023-01-01"  
date_to = "2024-02-01

cashBackData = mthmr_query.get_cashback_payments(URL, Token, date_from, date_to)