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

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

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

{
  "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

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:

// Pseudocode example
function getValidToken() {
  if (token && !isExpired(token)) {
    return token;
  }
  return refreshToken();
}

Security Guidelines

1. Store tokens securely: Access tokens should be stored in an encrypted format at rest if stored server-side
2. Limit access: The number of employees with access to tokens should be kept to a need-to-know basis
3. Report breaches immediately: If a token breach is detected, contact Precium immediately so affected tokens can be revoked
4. Never expose in client-side code: Do not include credentials or tokens in client-side JavaScript or mobile apps
5. Use HTTPS: All API requests must be made over HTTPS

Error Handling

If your token is invalid or expired, the API will return:

{
  "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

The production base URL is https://api.revio.co.za/. Your production client_id and client_secret are issued at 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:

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.