Endpoints

This endpoint generates an access token using the JWT standard. The response body's result field is encrypted with the x-app-secret key using the AES algorithm's GCM mode. The provided SDK includes a decoding functionality. Please ensure that the x-app-id and x-app-secret values, 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:
    • x-app-secret : "The application secret key provided by the MIS Pay team"
    • 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 instore process"
   }
  }

  • Field Descriptions:
    • status : Indicating the status of the response.
    • result.token : The JWT token the merchant needed to continue with the payment process.

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.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2
}

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 purchase process is initiated by users through the Merchant's POS application. After customers click 'In-Store-Payment' on their mobile app, a payment code will appear on their screen. Merchants are required to take that payment code and use it in this step.

• Request:
  • Method: POST
  • URL: /purchase
  • 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:

    {
     "amount": 200,
     "orderId": "unique orderId created by merchant",
     "paymentCode": 123123
    }

    • Field Descriptions:
      • amount : The amount of the purchase.
      • orderId : Unique orderId created by the merchant for the purchase.
      • paymentCode : Payment Code the customer is generated on the mobile app.
• Response:

{
 "status": "success",
 "result": {
 "trackId": "33c97446-3f0d-43c7-bef7-8688cebc708d",
 "ivrCallbackId": "6536d42a7a9617ada16dfe04",
 "status": "in-progress"
 }
}

• Field Descriptions:
  • status : Indicating the status of the response
  • result.trackId : The unique identifier generated to let the merchants track the payment status using the tracking endpoint.
  • result.ivrCallbackId : Merchants won’t be needing this field.
  • result.status : This field indicates the status of the payment. It will be gradually updated when the customer advances on the payment steps.

  After the MIS Pay system receives this request, the customer will be redirected to the payment page on their mobile device.

After customers are redirected to the payment page, merchants can track their progress with this API. The 'status' field in the response to this request indicates the current status of the customer's payment. A polling method can be used to track the purchase process.

• Request:
  • Method: GET
  • Path: /status?trackId=<TRACK_ID>
  • 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"
• Response:

  {
   "status": "success",
   "purchaseId": "<purchaseId>",
   "order": {
   "status": "success", // "in-progress" | "canceled" | "failed"
   "purchaseId": "6565c3fabf6c06c0273c8ed8",
   "amount": 201.05,
   "orderId": "<ORDER_ID>"
   }
  }

  • Field Descriptions:
    • status : Indicating the status of the response.
    • purchaseId : Unique identifier created for the purchase operation.
    • order.status : This field indicates the status of the payment. It will be gradually updated when the customer advances on the payment steps. Possible values are:
      • success : InStore purchase operation has been successfully completed by the customer.
      • in-progress : InStore process is still in-progress on the customer’s side.
      • canceled : Customer canceled the InStore purchase process.
      • failed : There was an error during the InStore purchase process.
    • order.purchaseId : The unique identifier for the purchase. This field is appended to the response once the purchase is completed by the customer.
    • order.amount : The total amount of the purchase. This field is appended to the response once the purchase is completed by the customer.
    • order.orderId : Unique orderId created by the merchant for the purchase. This field is appended to the response once the purchase is completed by the customer.

This step allows merchants to track the status of the purchase process by polling the specified endpoint with the trackId .

When the instore purchase process concludes on the customer's mobile device, this endpoint returns the status as 'success.' This indicates that the InStore purchase has been successfully completed.

🚧

In order to get the final amount of the purchase, merchants must use the Retrieve Purchase Details API. The amount provided with this API is just to inform the merchant during the instore purchase process. In case of a refund, Track API’s response amount will still indicate the original purchase amount.

To retrieve details for a specific purchase, merchants can use this API.

• Request:
  • Method: GET
  • Path: /purchase/<PURCHASE_ID>
  • 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"
• Response:

  {
   "status": "success",
   "result": {
   "merchantId": "64e86620adbe5a41f2d41b75",
   "orderId": "<ORDER_ID>",
   "purchaseAmount": 201.05,
   "purchaseCurrency": "SAR",
   "purchaseDate": "2023-11-28T10:42:02.384Z"
   }
  }

  • Field Descriptions:
    • status : Indicating the status of the response.
    • result.merchantId : The unique identifier of the merchant in the MIS Pay system
    • result.orderId : Unique orderId created by the merchant for the purchase.
    • result.purchaseAmount : The amount of purchase.
    • result.purchaseCurrency : The currency of the purchase.
    • result.purchaseDate : The date when the purchase was created.

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

• Request:

  • Method: GET
  • 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:

  {
   "amount": 200.45,
   "purchaseId": "<purchaseId>",
   "orderId": "<orderID>"
  }

  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": {
   "status": "success"
   }
  }

  • Field Descriptions:
    • status : Indicating the status of the response.
    • result.status : Indicating the status of the refund process.

📘

Merchants can use this endpoint to request a refund for a specific purchase, providing details such as the amount , purchaseId , and orderId .

Sample error responses:

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

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

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