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

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:

‍

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

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:

‍

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.