Xtopay Logo

Authentication

Secure access to Xtopay's APIs using API keys and OAuth 2.0

Last updated July 21st, 2025

Authentication Methods

API Keys

Simple authentication using your unique API key for server-to-server communication.

Recommended for backend integrations
Higher rate limits
Keep keys secure - never expose in client-side code
View implementation
OAuth 2.0

Secure token-based authentication for user-facing applications.

Recommended for client-side applications
Short-lived access tokens
Refresh token support
View implementation

API Keys

Getting API Keys

Obtain your API keys from the Xtopay Developer Dashboard:

1
Log in

Access the Developer Dashboard with your merchant account.

2
Navigate

Go to Settings → API Keys in the navigation menu.

3
Create

Click "Create API Key" and copy your secret key (shown only once).

Using API Keys

Include your API key in the Authorization header:

javascript
Authorization: Bearer YOUR_API_KEY

Sample Request

bash
curl -X GET https://api.xtopay.com/v1/transactions \
  -H "Authorization: Bearer sk_test_xyz123" \
  -H "Content-Type: application/json"

Key Rotation

Rotate your API keys regularly for security:

  • Generate a new key in the dashboard
  • Update your integration with the new key
  • Revoke the old key after verification

OAuth 2.0

Overview

OAuth 2.0 provides secure delegated access to Xtopay APIs on behalf of your users.

Authorization Code Flow

Recommended for server-side applications where you can securely store client secrets.

User redirected to Xtopay for authentication
Your server exchanges code for tokens
Most secure flow for web applications
Client Credentials Flow

For machine-to-machine communication where no user is involved.

Application authenticates directly
No user context required
Limited to specific API endpoints

Registering Your Application

Before using OAuth, register your application in the Developer Dashboard:

Navigate to Settings → OAuth Applications
Click "New Application"
Provide application name, redirect URIs, and scopes
Copy your Client ID and Client Secret

Authorization Code Flow Implementation

Here's how to implement the OAuth 2.0 authorization code flow:

1. Redirect Users to Xtopay

javascript
https://auth.xtopay.com/oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  scope=transactions:read%20payments:create&
  state=RANDOM_STRING

2. Exchange Code for Tokens

javascript
// Node.js example
const response = await fetch('https://auth.xtopay.com/oauth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Authorization': 'Basic ' + Buffer.from(`${clientId}:${clientSecret}`).toString('base64')
  },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: authorizationCode,
    redirect_uri: redirectUri
  })
});


const tokens = await response.json();
// Returns: { access_token, refresh_token, expires_in, token_type }

3. Use the Access Token

bash
curl -X GET https://api.xtopay.com/v1/transactions \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

4. Refresh Expired Tokens

javascript
// Node.js example
const response = await fetch('https://auth.xtopay.com/oauth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Authorization': 'Basic ' + Buffer.from(`${clientId}:${clientSecret}`).toString('base64')
  },
  body: new URLSearchParams({
    grant_type: 'refresh_token',
    refresh_token: refreshToken
  })
});

Security Best Practices

API Key Security
  • Never commit API keys to version control - use environment variables
  • Restrict API key usage to specific IP addresses when possible
  • Rotate keys immediately if compromised
  • Use different keys for different environments (production vs test)
OAuth Security
  • Always use HTTPS for redirect URIs
  • Validate the state parameter to prevent CSRF
  • Store refresh tokens securely
  • Request only the minimum required scopes
General Recommendations
  • Implement rate limiting on your API calls
  • Monitor for suspicious activity
  • Keep your integration updated with our latest API versions
  • Use webhooks to receive real-time notifications

Troubleshooting