OAuth 2.0 Integration Guide

Overview

Integrate OAuth 2.0 to securely access services through third-party servers.

Configuration

POST {BaseURL}/api/v1/configure/configure-redirect-url
Content-Type: application/json
Authorization: Basic base64encode({clientId:clientSecret})
{
  "white_list_redirect_urls": [
    "http://domain_webhook"
]
}

Step 1: Generate Connect Link

Construct the URL to initiate the OAuth flow:

{BaseURL}/connect?client_id={client_id}&redirect_url={encoded_redirect_url}&state={state}

Parameters

Parameter	Description	Required
`BaseURL`	The base URL of the API	Yes
`client_id`	The client's unique identifier	Yes
`encoded_redirect_url`	URL to redirect after authentication. Must be URL encoded	Yes
`state`	A unique state to maintain state between redirects	No

Example URL Encoding

Suppose your redirect URL is:

https://example.com/callback?param1=value1&param2=value2

After URL encoding, it becomes:

https%3A%2F%2Fexample.com%2Fcallback%3Fparam1%3Dvalue1%26param2%3Dvalue2

Complete Example

Using the encoded redirect URL in the OAuth flow URL:

https://api.example.com/connect?client_id=your_client_id&redirect_url=https%3A%2F%2Fexample.com%2Fcallback%3Fparam1%3Dvalue1%26param2%3Dvalue2&state=your_unique_state

Note

Ensure that the redirect_url is URL-encoded to handle special characters properly. This allows the API to correctly parse the redirect URL.

Step 2: Redirect Handling

Upon successful authentication, users are redirected with an authToken:

redirect_url?authToken={authToken}

Step 3: Token Request

Exchange the authToken for access and refresh tokens:

POST {BaseURL}/api/v1/auth/authorize/connect
Content-Type: application/json
Authorization: Basic base64encode({clientId:clientSecret})
{
  "auth_token": "{authToken}"
}

Headers

Content-Type: application/json
Authorization: Basic base64encode({clientId:clientSecret})
- The clientId:clientSecret should be base64 encoded.

Request Parameters

Parameter	Description	Required
`auth_token`	Temporary token from Step 2	Yes

Successful Response

{
  "access_token": "your_access_token_here",
  "refresh_token": "your_refresh_token_here",
  "business_info": {
    "moc_id": "1234567890",
    "company_name_en": "CH168 Co., Ltd",
    "company_name_kh": "ក្រុមហ៊ុនស៊ីអេច១៦៨",
    "tin": "1234567890",
    ...
  }
}

Response Parameters

Field	Description
`access_token`	Token to access the API securely
`refresh_token`	Token to renew the access_token
`business_info`	Object containing business details

Business Information Parameters

Field	Description
`endpoint_id`	The main identifier of this entity (CamInvoice ID). (e.g. KHUID00001234).
`moc_id`	Ministry of Commerce ID, a unique identifier for the company
`company_name_en`	The official name of the company in English
`company_name_kh`	The official name of the company in Khmer
`tin`	Tax Identification Number, unique tax number for the company
`date_of_incorporation`	The date on which the company was officially registered
`business_type`	Type of business the company is involved in
`city`	The city where the company is located
`country`	The country code for Cambodia (KH)
`phone_number`	The primary contact number for the company
`email`	The email address for business correspondence

Step 4: Make API Calls

To make API calls, replace ACCESS-TOKEN with your access token in the authorization header: -H Authorization: Bearer ACCESS-TOKEN. When your access token expires, request a new one by calling /api/v1/token with your refresh token.

💡

This guide assumes that you have already set up your client_id and know your redirect URL.

Overview Get New Access Token