OAuth 2.0

100Pay supports OAuth 2.0 for third-party applications that need to access user account information or perform actions on behalf of a user. This enables secure, user-consented authorization without sharing passwords.

When to Use OAuth

Use the OAuth flow when you need to:

Identify users by their 100Pay account (PayID login)
Access a user’s profile, account info, or app details
Execute transfers or actions on behalf of a user

Unlike standard API calls that authenticate your app, OAuth authenticates your user and grants scoped access to their data.

Available Scopes

Scope	Description
`read_user_info`	Read the user’s profile (name, email, phone, etc.)
`read_app_info`	Read the user’s app and business details

Full Authorization Flow

Register Your OAuth Application

This is a one-time setup. Register your app to get a clientId and clientSecret.


import { Pay100 } from "@100pay-hq/100pay.js";
 
const client = new Pay100({
  publicKey: "your_public_key",
  secretKey: "your_secret_key",
});
 
const app = await client.oauth.registerApp({
  appName: "My Application",
  appDescription: "A brief description of what your app does.",
  appLogo: "https://example.com/logo.png",
  redirectUris: ["https://myapp.com/auth/callback"],
  allowedScopes: ["read_user_info", "read_app_info"],
});
 
console.log("Client ID:", app.clientId);
console.log("Client Secret:", app.clientSecret);
// Store these securely — you'll need them in subsequent steps

Get the Authorization URL

Build the URL to redirect your user to for login and consent:


const authUrl = await client.oauth.getAuthorizationUrl({
  client_id: app.clientId,
  redirect_uri: "https://myapp.com/auth/callback",
  scope: "read_user_info read_app_info",
  state: "a_random_csrf_token",   // Recommended: use to prevent CSRF
});
 
// Redirect the user to this URL
window.location.href = authUrl;

Handle the Callback

After the user authorizes your app, 100Pay redirects them to your redirect_uri with a code query parameter:


https://myapp.com/auth/callback?code=AUTH_CODE&state=a_random_csrf_token

Validate the state parameter, then exchange the code for an access token:


// Server-side: /auth/callback handler
const { code, state } = req.query;
 
// Validate state to prevent CSRF attacks
if (state !== expectedState) throw new Error("Invalid state");
 
const tokenResponse = await client.oauth.exchangeCodeForToken({
  grant_type: "authorization_code",
  code: code,
  client_id: "your_client_id",
  client_secret: "your_client_secret",
  redirect_uri: "https://myapp.com/auth/callback",
});
 
const { access_token, expires_in, scope } = tokenResponse.data;
// Store access_token securely (server-side session, encrypted cookie, etc.)

Access User Data

Use the access token to fetch the user’s profile or app information:


// Get user profile
const userInfo = await client.oauth.getUserInfo(access_token);
console.log("Name:", userInfo.data.first_name, userInfo.data.last_name);
console.log("Email:", userInfo.data.email);
console.log("Username:", userInfo.data.username);
 
// Get app / business info
const appInfo = await client.oauth.getAppInfo(access_token);
console.log("App name:", appInfo.data.app_name);
console.log("Business:", appInfo.data.business_name);

Revoke the Token

When the user logs out or you no longer need access, revoke the token:


await client.oauth.revokeToken(access_token);
console.log("Token revoked");

API Reference

`oauth.registerApp()`

Field	Type	Required	Description
`appName`	`string`	✅	Your application’s display name
`appDescription`	`string`	✅	Short description shown to users on the consent screen
`appLogo`	`string`	✅	URL to your app logo
`redirectUris`	`string[]`	✅	Allowed callback URLs for your app
`allowedScopes`	`string[]`	✅	Scopes your app requests (e.g. `["read_user_info"]`)

`oauth.getAuthorizationUrl()`

Field	Type	Required	Description
`client_id`	`string`	✅	Your app’s client ID from `registerApp()`
`redirect_uri`	`string`	✅	Must match one of your registered `redirectUris`
`scope`	`string`	—	Space-separated list of scopes (e.g. `"read_user_info read_app_info"`)
`state`	`string`	—	Random string to prevent CSRF — verify this on callback

`oauth.exchangeCodeForToken()`

Field	Type	Required	Description
`grant_type`	`"authorization_code"`	✅	Always `"authorization_code"`
`code`	`string`	✅	Authorization code from the callback URL
`client_id`	`string`	✅	Your app’s client ID
`client_secret`	`string`	✅	Your app’s client secret
`redirect_uri`	`string`	✅	Must match the URI used in `getAuthorizationUrl()`

TypeScript Types


interface IOAuthApp {
  clientId: string;
  clientSecret: string;
  appName: string;
  redirectUris: string[];
  allowedScopes: string[];
}
 
interface ITokenData {
  access_token: string;
  token_type: string;  // e.g. "Bearer"
  expires_in: number;  // seconds
  scope: string;
}
 
interface IUserInfo {
  id: string;
  first_name: string;
  last_name: string;
  username: string;
  country: string;
  avatar: string;
  email: string;
  isEmailVerified: boolean;
  phone: string;
  verified: boolean;
}
 
interface IAppInfo {
  id: string;
  app_name: string;
  business_name: string;
  country: string;
  status: string;
  support_email: string;
}

Security Best Practices

Always validate state on the callback to prevent CSRF attacks
Store tokens server-side — never in localStorage or client-accessible cookies
Revoke tokens when users log out
Never expose client_secret in client-side code

Next Steps

Asset Transfers — use oauthAccessToken to transfer funds on behalf of a user
Webhooks — receive real-time event notifications