RETM Marketplace App Installation Guide (OAuth)

For partner developers integrating via RETM Marketplace

Overview

This document explains the end-to-end installation and OAuth authorization flow for a RETM Marketplace app, including how business_id is used to build the Production API hostname.

Key placeholders

Placeholder	Meaning / Where it comes from
{business_id}	Your app’s client_id from RETM DevPortal.
{your_install_url}	Returned in STEP 2 callback payload after the merchant grants access. Used as the Production subdomain.
{your_success_end_point}	Your optional pre-auth install page (login/verification) hosted by you.

Your endpoint that receives the STEP 2 POST callback (code + business_id + data).

Environment endpoints

Authorization endpoint (merchant consent screen):

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

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

Token exchange endpoint (STEP 3):

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

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

Step-by-step: How a merchant installs your app

1. Merchant clicks Install

In the RETM Marketplace, the merchant clicks Install on your app listing. RETM starts the flow by opening the authorization endpoint for your App.

2. Your Install URL (pre-auth)

If you want to verify the merchant on your side (recommended), configure an Install URL that shows a login/verification screen. After the merchant logs in, you redirect them back to RETM’s authorization endpoint.

3. Redirect to RETM authorization endpoint (you may attach tracking params)

Send the merchant to:
https://retm.sa/integrations/authorized?client_id={application_client_id}

Optionally, you may append your own parameters (example):
https://retm.sa/integrations/authorized?client_id={application_client_id}&account_id=12345&status=1&token=ABCD
These parameters will be returned back to you later in STEP 2 inside the data object.

The merchant reviews the requested permissions/scopes and approves access. If they decline, the flow stops.

5. STEP 2: RETM POSTs to your Success Endpoint

After approval, RETM sends a POST request to your configured success endpoint ({your_success_end_point}) with a payload like:

Your system should store code + business_id (and any data values you need).

6. STEP 3: Exchange code for Access Token

Use the business_id to build the correct hostname, then exchange the code for an access token:
POST https://{business_id}.retm.sa/api/oAuth/token
Body example:

7. Use the Production base URL for API calls

After token exchange, all Production API calls should use the merchant-specific base URL:
https://{business_id}.retm.sa/
Note: In Staging, business_id may be "stg" and the base URL is stg.retm.sa.

Partner checklist

DevPortal app visibility is set correctly (Public/Private for Production use).

Install URL is reachable publicly over HTTPS and responds quickly.

Success Endpoint is reachable publicly over HTTPS and can accept RETM POST callbacks.

Success Endpoint stores code + business_id and any needed tracking data.

Token exchange is performed against the correct environment hostname.

API requests use https://{business_id}.retm.sa/ in Production.

Common issues

404 on Production authorization

Most commonly caused by the app not being Public/active for Production, or an incorrect authorization URL.

Authorization page loads but never reaches STEP 2

Usually caused by an invalid/unreachable Success Endpoint, or the merchant canceling the consent step.

Staging works but Production token exchange fails

Ensure you use https://{business_id}.retm.sa/api/oAuth/token in Production (not stg.retm.sa).

Marketplace Installation Guide

RETM Marketplace App Installation Guide (OAuth)#

Overview#

Key placeholders#

Environment endpoints#

Step-by-step: How a merchant installs your app#

1. Merchant clicks Install#

2. Your Install URL (pre-auth)#

3. Redirect to RETM authorization endpoint (you may attach tracking params)#

4. Merchant grants access (consent)#

5. STEP 2: RETM POSTs to your Success Endpoint#

6. STEP 3: Exchange code for Access Token#

7. Use the Production base URL for API calls#

Partner checklist#

Common issues#

404 on Production authorization#

Authorization page loads but never reaches STEP 2#

Staging works but Production token exchange fails#

RETM Marketplace App Installation Guide (OAuth)

Overview

Key placeholders

Environment endpoints

Step-by-step: How a merchant installs your app

1. Merchant clicks Install

2. Your Install URL (pre-auth)

3. Redirect to RETM authorization endpoint (you may attach tracking params)

4. Merchant grants access (consent)

5. STEP 2: RETM POSTs to your Success Endpoint

6. STEP 3: Exchange code for Access Token

7. Use the Production base URL for API calls

Partner checklist

Common issues

404 on Production authorization

Authorization page loads but never reaches STEP 2

Staging works but Production token exchange fails