New to our DevPortal 🤔

STEP 1: (Embark towards glory 🚀) Routing to your install URL

Purpose:

Initiates the installation and authorization process for your application within the RETM marketplace.

Endpoint:

Staging: https://stg.retm.sa/integrations/authorized?client_id={application_client_id}

Production: https://retm.sa/integrations/authorized?client_id={application_client_id}

Request Parameters:

client_id (required, string): Your application's client ID provided by RETM.

INFO

You can have data related to the merchant returned to your endpoint once the access is granted by simply sending a URL parameters with the STEP 1, for example:
https://retm.sa/integrations/authorized?client_id={application_client_id}&token=12345&status=1

The token and status will be sent within data key in the success callback in STEP 2.

Additional Information:

Your application's installation endpoint Best Practices:

Redirect the merchant to your platform.

Authenticate the merchant in your platform.

Redirect the merchant back to our marketplace through the endpoints mentioned in (Endpoint) section in (STEP 1) regarding the info (attach extra params to authenticate the merchant in the next steps).

STEP 2: (Your cooking is almost done 🍽️) Granting access

Purpose:

Allows the merchant to grant your application access to their RETM data.

Actions:

User decides whether to grant access in a consent window.

RETM sends a POST request to your success endpoint upon consent.

Success Endpoint:

Example: https://{your-success-end-point}

Request Body:

{
  "code": "string",  // Authorization code related to the merchant
  "business_id": "string", // Merchant's business ID
  "data": {  // Optional parameters sent in STEP 1
    // ...
  }
}

Response Body (OPTIONAL):

{
  "token": "string", // it is used by RETM to push requests to your webhooks as Bearer token in Authorization header.
  "url": "string" // a URL for settings of Retm App in your platform if exists, we will attach the token in this url as token query parameter if you want to further authorize the merchant
}

Additional Information:

Your application's success endpoint Best Practices:

It is REQUIRED that your success endpoint returns status code of 200 regarding that the timeout of request is 1 second.

Your success endpoint best to check the data param received in the request and validate the request against the merchant.

You have to store the code and business_id received in the request.

STEP 3: (Your app is ready 🥳), Making the Request for Access Token

Purpose:

Exchanges the authorization code for an access token.

Endpoint:

Staging: https://stg.retm.sa/api/oAuth/token

Production: https://{business_id}.retm.sa/api/oAuth/token

Method:

POST

Request Body:

{
  "code": "YOUR_AUTHORIZATION_CODE",
  "grant_type": "authorization_code",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

Response:

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "YOUR_REFRESH_TOKEN"
}

Additional Notes:

Use the business_id as a subdomain for future API requests.

Handle potential errors gracefully (e.g., invalid authorization code).

Consider security best practices (e.g., secure storage of tokens).

Each time you got unauthorized with status code of 401 in the following requests you have to regenrate token.

STEP 1: (Embark towards glory 🚀) Routing to your install URL#

Purpose:#

Endpoint:#

Request Parameters:#

Additional Information:#

STEP 2: (Your cooking is almost done 🍽️) Granting access#

Purpose:#

Actions:#

Success Endpoint:#

Request Body:#

Response Body (OPTIONAL):#

Additional Information:#

STEP 3: (Your app is ready 🥳), Making the Request for Access Token#

Purpose:#

Endpoint:#

Method:#

Request Body:#

Response:#

Additional Notes:#

STEP 1: (Embark towards glory 🚀) Routing to your install URL

Purpose:

Endpoint:

Request Parameters:

Additional Information:

STEP 2: (Your cooking is almost done 🍽️) Granting access

Purpose:

Actions:

Success Endpoint:

Request Body:

Response Body (OPTIONAL):

Additional Information:

STEP 3: (Your app is ready 🥳), Making the Request for Access Token

Purpose:

Endpoint:

Method:

Request Body:

Response:

Additional Notes: