Overview
Every API request to 88Pay requires a valid authentication token. This guide explains how to generate, cache, and refresh tokens efficiently.Tokens are short-lived (60 seconds) for security. You’ll need to generate new tokens regularly or implement caching.
Why Tokens?
88Pay uses a two-layer authentication system:- API Credentials (API Key + Merchant ID) - Long-lived, never sent with each request
- Access Tokens (JWT) - Short-lived, used for individual API calls
- ✅ Enhanced security (credentials not exposed in every request)
- ✅ Rate limiting and abuse prevention
- ✅ Session tracking and auditing
- ✅ Easy credential rotation without disrupting active sessions
Token Generation Endpoint
Endpoint Details
Required Headers
| Header | Type | Required | Description |
|---|---|---|---|
x-api-key | string | ✅ Yes | Your API Key from the dashboard |
x-merchant-id | string | ✅ Yes | Your Merchant ID |
No Body Required
This endpoint doesn’t require a request body. Authentication is done via headers only.Making the Request
Response Structure
Success Response (200 OK)
Response Fields
Status of the request. Always
"Success" for 200 responsesHTTP status code.
200 for successful token generationHuman-readable message about the operation
JWT token to use in the
Authorization header of subsequent requestsFormat: Bearer {access_token}Token lifetime in seconds. Always
60 (1 minute)Unique session identifier. Must be included in the
x-session-id headerFormat: sess_{uuid}Error Responses
- 403 Forbidden
- 429 Rate Limited
- 500 Server Error
Token Caching (Best Practice)
Implement token caching to reuse tokens within their 60-second lifetime:Simple Token Manager
Using the Token
Once you have a token, include it in all API requests:Required Headers
Example API Request
Rate Limits
Token generation has specific rate limits:| Limit | Sandbox | Production |
|---|---|---|
| Per minute | 10 requests | 10 requests |
| Per hour | 100 requests | 100 requests |
Best Practices
Cache Tokens
Reuse tokens for up to 50 seconds to avoid rate limits
Safety Margin
Refresh tokens 10 seconds before expiry to prevent race conditions
Error Handling
Handle 401 errors by generating a fresh token and retrying
Concurrent Requests
Use a single TokenManager instance across your application
Troubleshooting
Token expires too quickly
Token expires too quickly
Issue: Tokens expire in 60 secondsSolution: Implement token caching as shown above. Each token can be reused for multiple requests within its lifetime.
Rate limit errors
Rate limit errors
Issue: Receiving 429 errorsSolution:
- Implement token caching
- Don’t generate tokens unnecessarily
- Use a singleton TokenManager instance
401 errors on API requests
401 errors on API requests
Issue: Token rejected by APISolution:
- Check token hasn’t expired
- Verify both Authorization and x-session-id headers are included
- Generate a new token
Tokens work in sandbox but not production
Tokens work in sandbox but not production
Issue: Different credentials for different environmentsSolution: Ensure you’re using production credentials with production URLs

