Authentication
The Precium API uses OAuth 2.0 Client Credentials Flow for authentication.
Overview
All API requests must include a valid Bearer token in the Authorization header. Tokens are obtained by making a POST request to the authentication endpoint with your client credentials.
Obtaining an Access Token
Endpoint
Request
HTML
POST /oauth2/token HTTP/1.1
Host: dev-payce.auth.eu-west-1.amazoncognito.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64_ENCODED_CREDENTIALS
grant_type=client_credentials
cURL Example
BASH
curl -X POST https://dev-payce.auth.eu-west-1.amazoncognito.com/oauth2/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
-d "grant_type=client_credentials"
Parameters
Response
JSON
{
"access_token": "eyJraWQiOiJYMHJhS...",
"expires_in": 86400,
"token_type": "Bearer"
}
Using the Access Token
Include the token in the Authorization header for all API requests:
GET /v2/merchantprofile/ HTTP/1.1
Host: dev.api.revio.co.za
Authorization: Bearer eyJraWQiOiJYMHJhS...
Content-Type: application/json
cURL Example
BASH
curl -X GET https://dev.api.revio.co.za/v2/merchantprofile/ \
-H "Authorization: Bearer eyJraWQiOiJYMHJhS..." \
-H "Content-Type: application/json"
Token Management Best Practices
Token Expiry
Access tokens expire every 24 hours. Implement token refresh logic in your application:
JSX
// Pseudocode example
function getValidToken() {
if (token && !isExpired(token)) {
return token;
}
return refreshToken();
}
Security Guidelines
- Store tokens securely: Access tokens should be stored in an encrypted format at rest if stored server-side
- Limit access: The number of employees with access to tokens should be kept to a need-to-know basis
- Report breaches immediately: If a token breach is detected, contact Precium immediately so affected tokens can be revoked
- Never expose in client-side code: Do not include credentials or tokens in client-side JavaScript or mobile apps
- Use HTTPS: All API requests must be made over HTTPS
Error Handling
If your token is invalid or expired, the API will return:
JSON
{
"statusCode": 401,
"message": "Unauthorized"
}
When you receive a 401 response, request a new access token before retrying the request.
Test Credentials
To request sandbox credentials, contact the Precium support team at support@precium.com
Your sandbox credentials will include:
client_id(username)client_secret(password)
Production Credentials
Production credentials are provided after go-live. Contact your Precium account manager to initiate the onboarding process.
API Endpoints
After authentication, use the following base URLs:
Troubleshooting
Common Issues
Testing Your Token
Verify your token is working by calling the merchant profile endpoint:
BASH
curl -X GET https://dev.api.revio.co.za/v2/merchantprofile/ \
-H "Authorization: Bearer YOUR_TOKEN"
A successful response confirms your authentication is configured correctly.
