Getting Started

Authentication

Securing API access with authentication

Overview

All requests to the PayOS API require authentication to ensure secure access. PayOS supports OAuth 2.0 as the primary method of authentication. This guide explains how to use OAuth 2.0 effectively.

OAuth 2.0 Authentication

OAuth 2.0 is an advanced method for managing access, especially for larger teams or third-party integrations. It allows users to grant access to specific parts of the system without sharing credentials.

Steps to Set Up OAuth Authentication:

  1. Create an OAuth client from the API Access section in the PayOS dashboard.
  2. Configure redirect URIs for the client.
  3. Use the following endpoints for authorization and token management.

Example OAuth Flow:

$# Step 1: Request token with clientId and clientSecret
>curl --request POST 'https://api.payos.money/api/v1/oauth/token' --header 'Content-Type: application/json' --data-raw '{
>    "clientId": "YOUR_CLIENT_ID",
>    "clientSecret": "YOUR_CLIENT_SECRET"
>}'

Token Handling:

  • Access Token: Used to authenticate API requests.
  • Refresh Token: Allows you to obtain a new access token without user interaction.

Example API Call Using OAuth:

$curl --request GET 'https://api.payos.money/api/v1/transactions' --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Handling Authentication Failures

If authentication fails, the PayOS API returns a 401 Unauthorized response. Ensure that:

  • The access token is correctly included in the Authorization header.
  • Tokens are not expired or revoked.
  • OAuth clients have the necessary permissions.

Best Practices for Authentication

  • Monitor Usage: Keep track of token usage through the PayOS dashboard.
  • Secure Storage: Store tokens securely in environment variables or a secrets manager.
  • Revocation: Immediately revoke compromised tokens.