# Merchant Self-Authorization Integration Guide

## 1. Overview

### 1.1 What is Merchant Self-Authorization

Merchant self-authorization is an authorization mechanism based on the OAuth 2.0 protocol, enabling developers to facilitate merchant authorization through a standardized process without contacting Keeta team for manual processing. The entire authorization process is secure and efficient.

### 1.2 Authorization Mode Comparison

| **Authorization Mode** | **Operation Process** |
|  --- | --- |
| Merchant Self-Authorization (Recommended) | Developers provide authorization links to merchants, merchants complete online authorization |
| Keeta Assisted Authorization | Contact Keeta Team |


## 2. Detailed Solutions

Merchant self-authorization is implemented based on the standard OAuth 2.0 authorization protocol. Considering that the complete OAuth 2.0 process is relatively complex, Keeta has optimized the authorization process into three implementation solutions based on different developers' needs while maintaining security.

#### Why is simplification needed?

**Traditional OAuth 2.0 implementation requires:**

- Building complete frontend and backend services (requires implementing token API)
- Handling complex token lifecycle management (requires implementing refresh API)


#### Keeta's Solution

After thoroughly understanding the actual needs of various developers, Keeta provide three progressive integration solutions:

1. **Simplified Mode**
  - Zero development cost. Developers send authorization links to merchants, merchants log in and complete authorization in Keeta merchant platform, developers directly view authorized brand tokens in the Developer Portal.
2. **Server Callback Mode**
  - Only backend development required, automated token acquisition, no need to manually copy tokens from the Developer Portal.
3. **Standard OAuth2.0 Authorization Mode**
  - Standard OAuth 2.0 implementation, providing the best user experience.


Developers can choose based on their needs to ensure integration with Keeta at minimal development cost.

| OAuth2.0 Mode | Operation Process | Scenario | Features |
|  --- | --- | --- | --- |
| Simplified Mode | 1. Developer clicks "Add authorization" on Application Management page to get authorization link2. Merchant accesses authorization link, logs into Keeta merchant platform and confirms authorization3. System automatically generates access_token4. Developer views and copies access_token on application's Authorization Management | 1. Low authorization frequency2. Few brands, can accept manual token copying | No development required, simple and efficient |
| Server Callback Mode | 1. Developer configures Webhook URL on Application Management page2. Developer clicks "Add authorization" on Application Management page to get authorization link and sends to merchant3. Merchant accesses authorization link, logs into Keeta merchant platform and confirms authorization4. Keeta server sends authorization code to configured Webhook address5. Developer server receives authorization code and calls Token endpoint to exchange for access_token | 1. Expects automated code acquisition2. High authorization frequency3. No frontend pages for authorization | Development required, automated token retrieval, no frontend page needed |
| Standard OAuth2.0 Authorization Mode | 1. Developer configures default callback URL on Application Management page2. Developer constructs authorization link with following parameters:- redirectUri: redirect address after authorization- state: custom field to be returned by Keeta (e.g., store ID)3. Merchant accesses the authorization link, logs into Keeta merchant platform and confirms authorization4. After successful authorization, page redirects to specified redirectUri with authorization code5. Developer frontend page gets authorization code and passes to backend6. Developer backend calls Token endpoint to exchange authorization code for access_token | 1. Expects automated code acquisition2. High authorization frequency3. Has own frontend pages | Development required, automated token retrieval, direct redirect to developer's own page |


### 2.1 Simplified Mode

1. After logging in to the developer portal


**(1) View "Application Management"**

After developer logs in, view "Application Management" and select specific application

selfAuthor1.png
**(2) Click "Add authorization"**

selfAuthor2.png
**(3) Copy Authorization URL and send it to Merchant**

selfAuthor3.png
**(4) Merchant receives the URL, clicks to log into Keeta merchant platform, and completes authorization for the developer**

Note: Merchants can only log in with merchant accounts, **please do not use Keeta developer accounts**

selfAuthor4.png
1. After merchant authorization, developers can view tokens in the application's Authorization Management


selfAuthor5.png
selfAuthor6.png
1. Developer copies token, pastes it into their own system, and can then request Keeta APIs


selfAuthor7.png
### 2.2 Server Callback Mode

Server Callback Mode is recommended for developeres who required automated token acquisition, with no frontend pages in the third-party developer portal.

**After merchant conducted authorzation**, Keeta will send the authorization code to the Webhook URL. After receiving the authorization code, developers call the get token API to obtain the token.

**The specific process can be referenced below:**

1. Open "Edit Application", under "Push OAuth2 Authorization Code", configure the Webhook URL to receive Authorization code. Note: After merchant authorization, developers can receive Authorization Code at the Webhook URL.


selfAuthor8.png
1. Developer clicks "Add Authorization" on application management page to get authorization link (Authorization URL) and sends to merchant
2. After merchant authorization, Keeta sends Authorization Code to the Webhook URL



```JavaScript
// Webhook Request Example
curl "https://example.com/api?\
sig=831b9c1741991f747042c75e3864b52c13ffbef68ea5f82a591643f57d24d610&\
code=99bf245fb49d4c319d31f64ac983c654&\
appId=your appId&\
state= &\
timestamp=1747294159789"
```

1. Developer backend calls token endpoint to exchange authorization code for access_token and saves token in their own system.


### 2.3 OAuth2.0 Standard Authorization Mode

**If developers expect automated token acquisition and want merchants to be redirected back to their internal system pages after authorization, they can choose the complete OAuth2.0 standard authorization process.**

1. Open "Edit Application", under "Push OAuth2 Authorization Code", configure the Webhook URL to receive Authorization Code. Note: After merchant authorization, developers can receive Authorization Code at the Webhook URL.


selfAuthor9.png
1. Developer clicks "Add Authorization" on application management page to get authorization link (Authorization URL)
2. Modify Authorization URL content (add redirectUri and state values)


**Example: Standard authorization link:**

merchant.mykeeta.com/m/web/openapi/authorize?responseType=authorization_code&appId=1933049627&redirectUri=&state=&scope=all

**After modification: Add redirectUri and state values (parameter order doesn't matter). For example, to redirect to Google and pass state as Keeta. The modified link becomes:**

merchant.mykeeta.com/m/web/openapi/authorize?responseType=authorization_code&appId=1933049627&redirectUri=www.google.com&state=Keeta&scope=all

1. After successful merchant authorization, the authorization page will redirect to the specified redirectUri with the authorization code
2. Developer frontend page passes the obtained authorization code to backend service
3. Developer backend service calls token endpoint to exchange authorization code for access_token and saves token in their own system.