Skip to main content

Authentication Setup

Pagamio uses Bearer token authentication for all API requests. Tokens are generated programmatically using your merchant credentials.

Authentication Method​

All API requests must include an Authorization header with your Bearer token:

Authorization: Bearer <YOUR_BEARER_TOKEN>

Obtaining Your Credentials​

Once your merchant/sub-merchant account is created, you will receive a welcome email from [email protected] containing your:

  • Username - Your merchant/sub-merchant username
  • Password - Your merchant/sub-merchant password
  • Portal Access - Portal access URL (sandbox/testing)

⚠️ Security Notice: Change your password after first login.

These credentials are used to generate Bearer tokens via the API.

Generating a Bearer Token​

Token Endpoint​

POST /api/v1/auth/token

Request​

curl -X POST $BASE_URL/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_username",
    "password": "your_password"
  }'

Response​

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 1800
}

Important Notes​

  • Token Validity: Tokens are valid for 30 minutes (1800 seconds)
  • Token Refresh: You must generate a new token every 30 minutes
  • Automatic Refresh: Implement automatic token refresh in your application

Using Your Bearer Token​

cURL Example​

curl -X GET $BASE_URL/products/categories \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"

JavaScript Example​

const axios = require("axios");

// Function to get Bearer token
async function getToken(baseUrl) {
  const response = await axios.post(`${baseUrl}/auth/token`, {
    username: process.env.PAGAMIO_USERNAME,
    password: process.env.PAGAMIO_PASSWORD,
  });
  return response.data.data.token;
}

// Use the token
const baseUrl = process.env.BASE_URL;
const token = await getToken(baseUrl);
const api = axios.create({
  baseURL: baseUrl,
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
});

const response = await api.get("/products/categories");

Python Example​

import requests
import os
from datetime import datetime, timedelta

class PagamioAuth:
    def __init__(self, username, password, base_url):
        self.username = username
        self.password = password
        self.base_url = base_url
        self.token = None
        self.token_expires = None

    def get_token(self):
        # Check if token is still valid
        if self.token and self.token_expires and datetime.now() < self.token_expires:
            return self.token

        # Generate new token
        response = requests.post(
            f"{self.base_url}/auth/token",
            json={"username": self.username, "password": self.password}
        )
        data = response.json()

        self.token = data['data']['token']
        self.token_expires = datetime.now() + timedelta(seconds=3600)
        return self.token

    def get_headers(self):
        return {
            'Authorization': f"Bearer {self.get_token()}",
            'Content-Type': 'application/json'
        }

# Usage
auth = PagamioAuth(
    username=os.getenv('PAGAMIO_USERNAME'),
    password=os.getenv('PAGAMIO_PASSWORD'),
    base_url=os.getenv('BASE_URL')
)

response = requests.get(
    f"{os.getenv('BASE_URL')}/products/categories",
    headers=auth.get_headers()
)

Troubleshooting​

401 Unauthorized - Token Generation​

Cause: Invalid username or password

Solution:

  • Verify credentials are correct
  • Check that you're using the right environment (sandbox vs production)
  • Ensure your account is active
  • Contact support if credentials are not working

401 Unauthorized - API Request​

Cause: Invalid, expired, or missing Bearer token

Solution:

  • Check that token hasn't expired (valid for 1 hour)
  • Verify Authorization header format: Authorization: Bearer <token>
  • Generate a new token
  • Implement automatic token refresh logic

403 Forbidden​

Cause: Account lacks permissions or is not properly configured

Solution:

  • Verify account status is active
  • Confirm merchant account has been approved
  • Check that you have access to the requested resources
  • Contact support for permission issues

Token Expiration Handling​

# Example: Test if token is expired
curl -X GET $BASE_URL/products/categories \
  -H "Authorization: Bearer YOUR_TOKEN"

# If you get 401, generate a new token
curl -X POST $BASE_URL/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username": "your_username", "password": "your_password"}'