How to use Mthmr

To start using Mthmr, you have to follow and complete three steps:

Authenticate into Mthmr
Add transactions history
Get a cashback

See the following section for more details on each step of the process.

Authenticating into Mthmr

Every request done to the Mthmr Cashback API must have a token in its headers to authenticate the request. Otherwise, the request is not authorized. To obtain this token, you need the following keys:

applicationId
applicationKey

These keys are provided by Mthmr Team to you. Once you have them, you can use the Get Token endpoint to generate your token. The code block below presents a request example.

curl --request GET \
     --url https://bank-api.mthmr.com/get-token \
     --header 'applicationId: <Your applicationId>' \
     --header 'applicationKey: <Your applicationKey>' \
     --header 'accept: application/json'

You should receive your token in response when a successful request is made. The following code block shows an example of a Token you will receive:

{
  "Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MTE2NTU2NDgsImlhdCA3MTcxMTY0OTY0OCwic3ViIjoibFFSUE2frtk5dG5HVnhYYmc0VHMifQ.W5SVuoeUI5PMBBcIJjBiaTVy1Snn1u61FeF291mQD7o"
}

You will use the token to authenticate and authorize your requests.

🚧
The security of your authentication token is critical. Therefore, treat your token as confidential information and safeguard it diligently to prevent unauthorized access.

Adding transactions history

The Add Transactions History endpoint allows you to add historical transaction data for that particular customer, and based on that data, the customer can qualify for offers that better suit him. For example, suppose we have particular offers for returning customers. The historical data allows us to determine whether a customer is a returning one and present him the offer for returning customers.

Here is an example of the request and response:

curl --request POST \
     --url https://bank-api.mthmr.com/transactions-history \
     --header 'Token: <Your token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
[
  {
    "transaction_id": "b65cca2a-6809-11ee-8c99-0242ac120002",
    "description": "This is a brief note about the transaction.",
    "customer_id": "a8de52aa-49e7-4e5c-bb66-1c82ac1d",
    "date": "2024-08-08T10:27:03.987662",
    "amount": 150.23,
    "merchant": : {
      "id":"f4e22e84d846e8c01de33b3cb19c8cae",
      "name":"MTHMR",
      "category_code":"75d80ed3fff52b2b7b2beaf3354be6d3"
    },
    "location": {
      "country": "Saudi Arabia",
      "city": "Riyadh"
    },
  }
]

[
  {
    "event_id": "f0b89e10-b372-4371-914e-052f540ad300",
    "errors": {
      "b65cca2a-6809-11ee-8c99-0242ac120002": "The Customer with the given ID not found",
      "b65cca2a-6809-11ee-8c99-0242ac134278": "The Customer with the given ID not found"
    }
  },
  {
    "event_id": "052f540ad300-b372-4371-914e-f0b89e10",
    "errors": {}
  }
]

Getting a cashback

To process a cashback with Mthmr Cashback, you need to complete a two-step process:

Create a customer
Add a transaction

See the following sections for more details on each step.

Creating a customer

First, create the customer using the Add Customers endpoint, providing the following parameters must be sent in the customer object:

customer_id: This unique identifier of the customer will be later used to associate it with the transaction.
birthday: The birthdate of the customer.
gender: The customer's gender.
location: An object containing details about the customer's location.

📘
Authorization Token
You need to insert the generated token in the previous Step in the headers of all requests.

See a request and response example in the following code block:

curl --request POST \
     --url https://bank-api.mthmr.com/customers/ \
     --header 'Token: <Your token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
[
  {
    "customer_id": "a8de52aa-49e7-4e5c-bb66-1c82ac1d551d",
    "birthday": "1999-06-02",
    "gender": "Male",
    "location": {
    	"country": "Saudi Arabia",
    	"city": "Riyadh"
    }
  }
]

{
  "Added": 1,
  "Updated": 2,
  "Errors": {
    "1454": "Multiple customers with the same ID were provided."
  }
}

Adding a transaction

Once the customer is created, you can add a transaction using the Add Transactions endpoint, which returns a token which can be used to receive the transactions' cashback record via webhook.

In the request, you must send the following parameters:

transaction_id: Input the transaction's unique identifier.
description: A simple description of the transaction.
customer_id: Input the customer's unique identifier to associate that customer with this transaction.
date: The date and time when the transaction was made.
amount: The monetary value of the transaction.
merchant: An object containing details about the merchant of the transaction.
location: An object containing details about the customer's location.

You can add multiple transactions in the request to process a cashback for the transactions that qualify for one. See a request and response example in the following code block:

curl --request POST \
     --url https://bank-api.mthmr.com/transactions \
     --header 'Token: <Your token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
[
  {
    "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.00
   },
   {
    "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.5
   }
]

[
  {
    "event_id": "3379cc86-3866-4a18-8ac9-e77332f74cea",
    "payments": [
      {
        "cashback": 15.04,
      	"payment_date": "2024-08-13",
     		"transaction_id": "e77332f74cea-3866-4a18-8ac9-3379cc86"
      }
    ],
    "errors": {
      "38664a18-8ac9-e77332-f74cea-cc863379": "The Customer with the given ID not found"
    },
  },
  {
    "event_id": "e77332f74cea-3866-4a18-8ac9-3379cc86",
    "payments": [
      {
        "cashback": 10.00,
      	"payment_date": "2024-02-12",
     		"transaction_id": "4a183866-3379cc86-4a18-8ac9-4a18"
      }
    ],
    "errors": {},
  }
]

The event_id parameter includes a token to compare the data sent to our server with the one received via webhook so that you can receive the transactions' cashback records via webhook.

The errors block will inform you if a transaction is already in our system or no cashback offer is associated.

📘
Webhook Address
You will provide the webhook address during your setup process.

How to use Mthmr

Authenticating into Mthmr

🚧

Adding transactions history

Getting a cashback

Creating a customer

📘
Authorization Token

Adding a transaction

📘
Webhook Address

Authenticating into Mthmr

🚧

Adding transactions history

Getting a cashback

Creating a customer

📘Authorization Token

Adding a transaction

📘Webhook Address

📘
Authorization Token

📘
Webhook Address