This endpoint generates an access token using the JWT standard. The response body's field is encrypted with the x-app-secretkey using the AES algorithm's GCM mode. The provided SDK includes a decoding functionality. Please ensure that the x-app-id and x-app-secretvalues provided by the MIS Pay Technical Team, are included in the HTTP header. Additionally, you must use the decrypted token value for all subsequent endpoint requests.

• Request:
  • Method: GET
  • URL: /token
  • Headers:
    1. x-app-secret: "The application secret key provided by the MIS Pay team"
    2. x-app-id: "The application ID provided by the MIS Pay team"
• Response:
  • Body:

  {
  "status": "success",
  "result": {
  "token": "An encrypted JWT token object which will be generated for the checkout process"
  }
  }

  
  

  Sample error responses

  App ID not providedApp Secret not providedMerchant Application could not be found (either App ID or App Secret is wrong).

  {
  "status": "error : 400",
  "result": "ExceptionType.ME01"
  }

  {
  "status": "error : 400",
  "result": "ExceptionType.ME02"
  }

  {
  "status": "error : 400",
  "result": "ExceptionType.ME03"
  }

  After receiving the response from the /token endpoint, it is necessary to decrypt the result.token field using the AES-256-GCM encryption method. This will yield a token object that contains the actual JWT token, as demonstrated below:

   {
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "expiration": "2022-12-31T23:59:59Z"
  }

The obtained JWT token can be utilized in subsequent endpoint requests, ensuring secure and authenticated communication with the "MIS Pay" system.

During this step, the Checkout process is initiated by users through the Merchant's checkout page. Users will be redirected to "MIS Pay" pages to provide user information and budget details. The Merchant app must share the required checkout information with the API.

• Parameters in the request body

• Request

  • Method: POST
  • URL: /start-checkout
  • Headers: authorization: Bearer <The JWT token generated via Get Access Token endpoint>x-app-id: "The application ID provided by the MIS Pay team"
  • Body

  {
  "orderId": "1233-ABCD",
  "invoiceId": "1234567890",
  "totalPrice": "215", 
  "shippingAmount": "0",
  "vat": "15",
  "discount": {
  "percentage": "15",
  "amount": "30",
  "voucherName": "MIS-30"
  },
  "purchaseAmount": "200”, // totalPrice+shippingAmount+vat - discount = purchaseAmount
  "purchaseCurrency": "SAR",
  "lang": "en",
  "version": "v1.2",
  "customerDetails": {
  "id": "customer ID",
  "firstName": "first name",
  "lastName": "last name",
  "mobileNumber": "+966512345678", // format = 0512345678 ,966512345678 , +966512345678
  "email": "[email protected]"
  },
  "orderDetails": {
  "items": [
  {
  "id": "OR12345",
  "sku": "1234568abcd",
  "nameArabic": "item name in arabic",
  "nameEnglish": "item name in english",
  "quantity": "2",
  "unitPrice": "100",
  "itemUrl": "https://itemurl.com",
  "imageUrl": "https://imagurle.com"
  }
  ]
  },
  "shippingDetails": {
  "firstName": "first name",
  "lastName": "last name",
  "countryCode": "96",
  "city": "riyadh",
  "district": "riyadh",
  "line1": "first line",
  "line2": "second line",
  "gpsCoordinates": "41.40338, 2.17403"
  },
  "isMobile": true
  }
  

  
  

• Response

  • Body:

  {
  "status": "success",
  "result": {
  "url": "A url generated specifically generated for the current checkout process",
  "trackId": "A unique ID to track the checkout status."
  }
  }

status : This field indicates the status of the response from the API. In this example, the value is "success," indicating that the request was processed successfully without errors.

result.url : This field represents the URL to which the user should be redirected to continue the checkout process on the "MISPay" pages.Merchants are required to use this redirect URL to guide their users to the "MIS Pay" pages, where users will provide additional information, confirm the purchase, and complete the checkout process. It is important to note that the redirect URL is specific to each checkout process and should not be stored or shared publicly. Merchants should dynamically generate and utilize this URL for each checkout process, ensuring the security and integrity of the transaction.

trackId : The trackId field is utilized to monitor the status of the checkout operation. You can long-poll the relevant endpoint to stay updated on the progress.

Sample Error Responses

❗️

The authorization token is not valid (provided via request header authorization)

{
"status": "error", 
"result": {
"code": 401,
"message": "ME10"
}
}

❗️

Session Expired

{
"status": "error", 
"result": {
"code": 401,
"message": "ME11"
}
}

❗️

The checkout session cache could not be found.

{
"status": "error :: 400", 
"result": "ExceptionType.ME04"
}

The system will trigger the callback endpoint with a query parameter named "_" (underscore). The value of this field will be a base64-encoded string containing orderId , code , and checkoutId fields, encrypted with AES GCM. Customers can decrypt this object using the appSecret provided by the MIS Pay team to retrieve the actual data. By using the orderId, they can confirm that the request is originating from the MIS Pay system, ensuring its authenticity and preventing it from another source

Merchant applications can utilize this endpoint to retrieve details of a specific Checkout process for which they are aware. The response will include relevant information for confirming orderId and other checkout values.

• Request:
  • Method: GET
  • URL: /checkout/\{checkoutId\}
  • Headers:
    • authorization: Bearer <The JWT token generated via Get Access Token endpoint>
    • x-app-id: "The application ID provided by the MIS Pay team"
• Response:
  • Body:

  {
  "status": "success",
  "result": {
  "id": "The identifier generated for the checkout operation",
  "orderId": "A string representing the current order which is being checked out",
  "purchaseAmount": "The amount of the purchase",
  "purchaseCurrency": "SAR",
  "purchaseDate": "The date of the checkout"
  }
  }

  status : This field indicates the status of the response from the API. In this example, the value is "success," indicating that the request was processed successfully without any errors.

  result.id : This field represents the identifier generated for the checkout operation. It is a unique value associated with this specific checkout process.

  result.orderId : This field is a string that represents the current order being checked out. It serves as an identifier for the order within the merchant's system.

  result.purchaseAmount : This field denotes the amount of the purchase being made during the checkout process.

  result.purchaseCurrency : This field represents the currency used for the purchase. In this example, the value is "SAR" which stands for Saudi Riyal.

  result.purchaseDate : This field specifies the date of the checkout, indicating when the purchase was initiated or confirmed.

Sample error responses

 {
"status": "error",
"result": {
"code": 401,
"message": "ME10"
}
}

{
"status": "error", 
"result": {
"code": 401,
"message": "ME11"
}
}

{
"status": "error :: 400",
"result": "ExceptionType.ME05"
}

The "track-checkout" endpoint allows merchants to monitor and track the checkout process of their customers. This feature is valuable for gaining insights into the progress of purchases made through the MIS Pay system. Merchants can implement long-polling to receive real-time updates on the status of checkout.

Authentication

To access this endpoint, you need to include the following information in the request headers:

• Authorization: This header should contain the authentication token provided by the MIS Pay system. This ensures that only authorized users can access the endpoint.
• x-app-id: This header should contain the appId provided by the MIS Pay system. It is used to identify your application and grant access to the "track-checkout" functionality.
• Request:
  • Method: GET
  • URL: /track-checkout/{trackId}\
  • Headers:
    • authorization: Bearer <The JWT token generated via Get Access Token endpoint>
    • x-app-id: "The application ID provided by the MIS Pay team"
• Response:
  • Body:

  {
  checkoutId?: "Unique Id for the checkout"
  orderId: "The order ID associated with the checkout" 
  purchaseAmount: "The purchase amount as a number" 
  purchaseCurrency: "SAR"
  status: "The status of the checkout" }

  1. checkoutId : If available, this field represents the unique identifier for the checkout process. It is provided upon the successful completion of the process.
  2. orderId : This field contains the identifier given by the merchant for the checkout.
  3. purchaseAmount : The purchase amount.
  4. purchaseCurrency : The currency of the purchase.
  5. status : The status field provides information about the progress of the checkout and can have one of the following values:
     • pending : The checkout has not yet been completed, but the customer has made some progress on the checkout.
     • in-progress : The checkout is currently started
     • success : The checkout process has been completed.
     • canceled : The checkout has been canceled.
     • error : An error occurred during the checkout process.

Merchants can use the refund endpoint to initiate a refund for a specific purchase.

• Request:

  • Method: POST
  • Path: /refund
  • Headers:
    • authorization : Bearer <The JWT token generated via Get Access Token endpoint>
    • x-app-id : "The application id provided by the MIS Pay Instore team"
  • Body:

  {
  "purchaseId": "{{checkoutId}}",
  "totalAmount": "200",
  "amount": "10",
  "currency": "SAR",
  "orderId": "767676",
  "merchantRefundId": "REF-87654321",
  "userDetails": {
  "id": "fbbdfe50-7613-4f05-b022f",
  "name": "name",
  "email": "[email protected]",
  "userType": "Agent"
  },
  "comments": "Customer returned item due to size mismatch"
  }

  Field Descriptions:

  • amount : The amount to refund to the customer.
  • purchaseId: Unique identifier created for the purchase operation.
  • orderId : Unique orderId created by the merchant for the purchase.

• Response:

  {
  "status": "success",
  "result": {
  "transactionId":"673da3652b2decc3fb260b5",
  "userId": "66a8c3b089008b54aa19c662",
  "merchantId": "648e1d5f8a65485327aad4e8",
  "orderId": "8454@-Wughvv",
  "newPurchaseAmount": 150,
  "moneyRefundToUser": 10,
  "moneyRefundAmount": 0,
  "increaseUserBalance": 10,
  "refundPaymentHistories": []
  }
  }

  
  

The "update-order-id" endpoint allows merchants to update the order ID associated with a checkout. This feature ensures that merchants can synchronize the correct order details with the MIS Pay system after the checkout process has completed.

• Request:

  • Method: PUT

  • URL:

  • Headers:

    • authorization: Bearer <The JWT token generated via Get Access Token endpoint>
    • x-app-id: "The application ID provided by the MIS Pay team"

  • body:

  {
  "orderId": "test-order-id-1234" // The new order ID you want to associate with the checkout"
  }

• Response:

  • Body:

   {
   "status": "success",
   "result": {
   "orderId": "The new order ID"
   }
   }

  status : This field indicates the status of the response from the API. In this example, the value is "success," indicating that the request was processed successfully without errors.

  result.orderId : This showed that order id updated successfully

Sample error responses

{
"status": "error",
"result": {
"code": 400,
"message": "ME05"
}