PayEngine OAuth 2.0 Authentication

PayEngine utilizes OAuth 2.0 to enable secure access to PayEngine merchant accounts by third-party applications, acting on behalf of merchant account users. This guide provides instructions for integrating PayEngine’s OAuth flow into your application.

1. Initiate the OAuth Flow

To start the OAuth flow, redirect merchants to PayEngine’s authorization URL:

Endpoint:

https://connect.payengine.co/oauth/authorize
https://connect.payengine.dev/oauth/authorize (Sandbox)

Parameters:

Please contact PayEngine support team to enroll your application and obtain client_id and access credentials

Parameter
Description

client_id*

Your application's client ID (assigned by PayEngine).

response_type*

Must be code

scope

Optional: Comma-separated list of permissions required. Currently only "default" is supported

redirect_uri

Optional: Your registered redirect URI where merchant account users are sent after authorization. If set it must match with the URL you registered with the client ID.

state*

A randomly generated value to prevent CSRF attacks.

Example:

https://connect.payengine.co/oauth/authorize?response_type=code
&client_id=YOUR_CLIENT_ID
&scope=default
&redirect_uri=https://yourapp.com/oauth/callback
&state=secure_random_string

2. Merchant Authorization

Upon visiting the authorization URL, merchants will be directed to a PayEngine-hosted page where they can authenticate and authorize your application using their merchant portal credentials.

3. Receive Authorization Code

Upon merchant account user approval, PayEngine will redirect them to the specified redirect_uri, appending an authorization code.

https://yourapp.com/oauth/callback?code=AUTHORIZATION_CODE&state=secure_random_string

Your backend should capture this code and verify the state parameter for security.

4. Exchange Authorization Code for an Access Token

To obtain an access token, your server must send a POST request to PayEngine's token endpoint, using the authorization code for exchange.

Endpoint:

https://connect.payengine.co/api/oauth/token

Request Parameters:

Parameter
Description

client_id*

Your application's client ID.

client_secret*

Your application's client secret.

code*

The authorization code received.

grant_type*

Must be authorization_code.

redirect_uri*

The same redirect URI used in the initial request.

Example Request (cURL):

curl -X POST https://connect.payengine.co/api/oauth/token \
     -d client_id=YOUR_CLIENT_ID \
     -d client_secret=YOUR_CLIENT_SECRET \
     -d code=AUTHORIZATION_CODE \
     -d grant_type=authorization_code \
     -d redirect_uri=https://yourapp.com/oauth/callback

Example Response:

{
    "data": {
        "token_type": "Bearer",
        "access_token": "oaat_d77b322172a3a7cc3d8eeb1019f5a807369010d5d57df0481f0feef5b12fca10",
        "expires_in": 3600,
        "refresh_token": "oart_6ec15424a18102a3c7b72e1b985067b49349551405ed6012b29c63a6c088520b",
        "refresh_expires_in": 1209600,
        "user": {
            "id": "186b9dfd-de11-46db-8fdb-4124a0b1e155",
            "type": "merchant",
            "accountId": "fdd24695-1298-496f-c553-89733fc17413"
        }
    }
}

5. Make API Requests Using the Access Token

With the access token in hand, include it in the Authorization header of your API requests for any API that is available for merchants to use.

Please refer to Merchant API section for available APIs and usage.

Example Request (cURL):

curl -X GET https://console.payengine.co/api/merchant/<MERCHANT_ID>/transaction \
     -H "Authorization: Bearer <ACCESS_TOKEN>"

6. Refreshing the Access Token

Access tokens have a one-hour expiration. Utilize the refresh token to obtain a new access token without requiring the merchant account user to re-authenticate.

Refresh tokens expire after 14 days of inactivity. If a refresh token is not used within this period, it becomes invalid. To continue accessing protected resources, the user must re-authenticate and obtain a new authorization code to request fresh tokens

  1. Use the refresh token before it expires – When an access token expires, exchange the refresh token for a new access token.

  2. Monitor refresh failures – If the refresh token is expired or invalid, prompt the user to re-authenticate.

  3. Handle token rotation (if applicable) – If refresh tokens are rotated (i.e., a new one is issued on each refresh), always store the latest refresh token.

  4. Provide a seamless re-authentication experience – If the refresh token expires, implement an automatic redirect to re-authenticate instead of forcing users to log in manually

Endpoint:

https://connect.payengine.co/api/oauth/token

Request Parameters:

Parameter
Description

client_id*

Your application's client ID.

client_secret*

Your application's client secret.

refresh_token*

The refresh token received earlier.

grant_type*

Must be refresh_token.

Example Request (cURL):

curl -X POST https://connect.payengine.co/api/oauth/token \
     -d client_id=YOUR_CLIENT_ID \
     -d client_secret=YOUR_CLIENT_SECRET \
     -d refresh_token=REFRESH_TOKEN \
     -d grant_type=refresh_token

Example Response:

{
    "data": {
        "token_type": "Bearer",
        "access_token": "oaat_3d45cffc0d1195fe3e99558271463eb88cf27f99f4240cb7dc35e531c91705c7",
        "expires_in": 3600,
        "refresh_token": "oart_876b8d9fa90c7b2ba7051bd6da93099ee6c3d4a2c1e8af203f46460a1411f619",
        "refresh_expires_in": 1209600,
        "user": {
            "id": "186b9dfd-de11-46db-8fdb-4124e0b1e155",
            "type": "merchant",
            "accountId": "fdd24695-1298-496f-b997-89733fc17413"
        }
    }
}

Security Best Practices

  • Always verify the state parameter to prevent CSRF attacks.

  • Use HTTPS for all OAuth requests.

  • Store tokens securely and never expose client_secret in front-end code.

By following this guide, you can integrate PayEngine’s OAuth 2.0 authentication seamlessly into your application. 🚀

Last updated