Server

Mars server side SDKs and libraries

Why is Server SDK needed?

Server SDK handles 2 task:

  • Verifying and validating the JWT received from marax server (which contains the reward applicable to the user, if any) which confirms any cashback, discounts, etc are not tampered by malicious users

  • Sending critical events to marax server, as sending them through mobile SDK could be tampered by users with malicious intentions

Installation

You can find the SDK on

  1. NPM npm i marax_server_sdk

  2. Yarn yarn add marax_server_sdk

  3. PyPi pip install marax_server_sdk

Verifying and validating JWT

  1. Import the server SDK

JavaScript
Python
JavaScript
const MaraxServerSdk = require('marax_server_sdk');
Python
import marax_server_sdk

2. Create an object of MaraxServerSdk class

JavaScript
Python
JavaScript
const marax = new MaraxServerSdk.RewardApi()
Python
marax = marax_server_sdk.RewardApi()

3. Create an object from the cart state you have received from the user. Below are the details about the properties that make up the object

Transportation
e-Commerce
Transportation

finalPrice Number

Total Fare Estimate + fulfillment charges (surcharge, taxes, etc) + ( - Discounts ) i.e., price which the user will be charged considering all the discounts (if any)

  • float : numeric value of the fare estimate including discounts

  • This value will be calculated by the marax and will be available within mobile SDK (in JWT obtained by marax server)

  • finalPrice will be same as the totalOrderPrice if:

    • No rewards are applicable for that user

    • Applied reward involve client server to redeem the reward (where handledBy is client ). For eg., if the user is part of wallet cashback campaign where cashbacks are to the wallet of the user, which will be handled by the client server

fulfillment [{array of objects}]

This includes charges that are not directly related to the services/products that is being sold and will apply on the overall service/product. Eg., surcharge, taxes, etc

  • type string : "surcharge"

  • price float : Numeric value of the price of the fulfillment

  • priceUnits string : currency of the above price

  • discount float : Numeric value, (if applicable)

  • discountType string : Indicates whether monetary or non-monetary (super coins, etc)

discount and discountType is provided by marax and will be available within mobile SDK (in JWT obtained by marax server)

paymentMode "string"

Mode through which the user has selected to pay for the ride

Options :

  • cash

  • wallet

  • card

  • upi

  • other

products [{object}]

  • In Transportation industry, this would be populated when client would want to run campaign on the features that are provided by them which are not simple discount campaign. For Eg., 50% off on pass

  • This value will be null when basic incentive constructs are used to run a campaign

Used when describing the features/special properties on which the campaign is run

  • id String

  • quantity String

  • name String

  • category String

  • price String

  • unit String

  • discount float

  • discountUnit String

totalProductsPrice Number

Sum of all products in the cart WITHOUT discounts and WITHOUT any fulfillment charges (surcharge, taxes, etc)

  • Note that this is only used if the products array is populated.

  • Value will be null if not applicable

  • float : numeric value of the fare estimate

totalDiscount Number

Sum of all discounts across all fulfillments (Eg., surcharge, taxes etc) & products OR Discount obtained on overall ride

  • float : Numeric value of discount

totalOrderPrice Number

Total fare estimate including fulfillment charges (surcharge, taxes, etc) WITHOUT discount

  • numeric value of the fare estimate

e-Commerce

The example object structure look as

// Example Object
const rideProperties =
{
"finalPrice": {
"value": 500.5,
"units": "rupees"
},
"fulfillment": [
{
"type": "surcharge",
"price": 15,
"priceUnits": "rupees",
"discount": 0,
"discountType": "monetory"
}
],
"paymentMode": "cash",
"products": null,
"timestamp": "2020-03-03T10:10:17.207Z",
"totalCartPrice": null,
"totalDiscount": {
"value": 10,
"type": "monetory"
},
"totalOrderPrice": {
"value": 510.5,
"units": "rupees"
}
}

4. Call the reward checker function to verify and validate the JWT along with JWT key obtained from marax through dashboard.

JavaScript
Python
JavaScript
try {
// .. Business Logic
const rewardObject = await marax.rewardChecker(rideProperties, token, key);
// ... Business Logic
} catch(error) {
// Process the error
// Do not redirect to payment page
}
Python
try:
# ... Business Logic
reward_object = marax.reward_checker(rideProperties, token, key);
# ... Business Logic
except:
# Process the error
# Do not redirect to payment page

Note that you receive a reward object if the validation and verification is successful. This is needed when calling marax server to process critical events (Eg., ORDER_COMPLETED, RIDE_COMPLETED, etc)

Send critical Events to marax

  1. Import the server SDK

JavaScript
Python
JavaScript
const MaraxServerSdk = require('marax_server_sdk');
Python
import marax_server_sdk
from marax_server_sdk.rest import ApiException

2. Instantiate an object, initialize the URI and provide the API Key obtained

JavaScript
Python
JavaScript
const marax = MaraxServerSdk.ApiClient.instance;
marax.basePath = 'https://<client-name>.marax.ai'
marax.authentications['ApiKeyAuth'].apiKey = "api-key-obtained-by-marax-from-dashboard"
Python
configuration = marax_server_sdk.Configuration()
# Configure API key authorization: ApiKeyAuth
configuration.api_key['X-API-KEY'] = "api-key-obtained-by-marax-from-dashboard"
# Defining host is optional and default to https://<client-name>.marax.ai
configuration.host = "https://<client-name>.marax.ai"
# Enter a context with an instance of the API client
api_client=marax_server_sdk.ApiClient(configuration)
#Instantiate the RewardApi Object with given configuration
marax = marax_server_sdk.RewardApi(api_client)

3. Create an properties of an event as below (Example shown below is for ORDER_COMPLETED event). Note that this requires the reward object obtained above in Verifying and Validating reward step 4

{
"properties": {
"timestamp": "2020-03-03T11:12:51.208Z",
"maraxId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"clientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"reward": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"expiry": "2020-03-03T11:12:51.208Z",
"timezone": "Asia/Kolkata",
"promocode": "SWIGGYIT",
"title": "Flat Rs 100/- off",
"body": "Applicable on all order above",
"updatedAt": "2020-03-03T11:12:51.208Z",
"type": "monetory",
"ui": "scratch_card",
"handledBy": "marax"
},
"finalPrice": {
"value": 500.5,
"units": "rupees"
},
"paymentMode": "cash",
"totalCartPrice": null,
"totalDiscount": {
"value": 10,
"type": "rupees"
},
"totalOrderPrice": {
"value": 510.5,
"units": "rupees"
},
"products": null,
"fulfillment": [
{
"type": "surcharge",
"price": 15,
"priceUnits": "rupees",
"discount": 0,
"discountType": "monetory"
}
]
}
}

4. Create a requestBody as below and call the processEvent to send the event along with its properties to Marax Server through the SDK

JavaScript
Python
JavaScript
const options = {
'requestBody': new MaraxServerSdk.RequestBody('ORDER_COMPLETED', props)
};
try {
// .. Business Logic ..
const response = await marax.processEvent(options);
// .. Business Logic ..
} catch(error) {
// .. Handle the error
}
Python
# RequestBody | Details of transactional event (optional)
request_body = marax_server_sdk.RequestBody()
try:
# .. Business Logic ..
# Perform reward post-processing
api_response = api_instance.process_event(request_body=request_body)
# .. Business Logic ..
except ApiException as e:
print("Exception when calling RewardApi->process_event: %s\n" % e)