Overview
This user guide provides detailed instructions on how to request and download reports from One Stop Portal (OSP) using REST API, secured with PayNet Single Sign-On (SSO) authentication.
The guide covers the steps for authentication, requesting reports, and the overall workflow for integrating with the OSP API.
Below is the flow diagram that visually represents the interaction process to generate and download various types of reports. This diagram provides a high-level overview of the key steps involved, from authentication to report retrieval.
Pre-requisites
Before you begin integrating with the API, ensure the following prerequisites are met:
1. Whitelist the FQDN and IP Addresses
- You need to whitelist the Fully Qualified Domain Name (FQDN) and IP addresses of the PayNet API endpoints in your network. This ensures that your system can connect to the PayNet API securely.
- Additionally, you must also request PayNet to whitelist the IP address and FQDN of your system. This allows PayNet’s API to accept requests from your network. Please provide these details to your IT team so they can submit the request to PayNet.
2. One-time Onboarding
To start using the API, you need to request a Client ID and Client Secret by submitting an email request to the OSP support team. These credentials will be used for authenticating your API calls.
PayNet SSO Authentication
For secure access to the OSP API, we use PayNet Single Sign-On (SSO) that combining OAuth 2.0 with X-Signature for enhance security by adding layer of validation.
Purpose of Combining OAuth2 and X-Signature
- OAuth2: Provides authentication and authorization by issuing an access token. It ensures that the caller is authorized to access a specific resource.
- X-Signature: Ensures message integrity and authenticity by verifying that the request has not been tampered with and originates from a trusted source.
Together, these mechanisms prevent unauthorised access and protect against data tampering.
How does it work?
In summary, OAuth2 authenticates and authorizes clients by issuing an access token, ensuring that only authorized clients can access the API.
X-Signature verifies the integrity of the request by ensuring the data hasn't been tampered with. The client generates a signature using a shared secret key, which the server verifies to confirm the request's authenticity.
Together, they provide strong security for both authentication and data integrity.
Step 1: Request OAuth2 Access Token
To begin, your client needs to request an access token by authenticating with the API, using grant type of Client Credentials Flow:
POST /oauth/token HTTP/1.1 <br/>
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=your_client_id&client_secret=your_client_secret
The Client Credentials Flow is ideal for:
- Machine-to-machine communication: It’s often used for service accounts, backend applications, or microservices that need to access an API without user interaction.
- No user delegation required: Since there’s no need for user consent or involvement, this flow is straightforward and efficient when the client needs to authenticate itself to the API.
If the Client ID and Client Secret are correct, the authorization server will respond with an access token. This token is used for authenticating future API requests.
Here’s an example of a successful response:
{
"access_token": "<access_token>",
"token_type": "bearer",
"expires_in": 3600
}
Step 2: Generate X-Signature
- Timestamp: A simple string representation of the current Unix timestamp (seconds since 1970-01-01 00:00:00 UTC). Use int(time.time()) to get the current timestamp.
- Secret Key: A private key shared between the sender and receiver.
- HMAC-SHA256:
- Combines the secret key and the timestamp.
- Produces a hash that uniquely identifies the request.
Below is an example code to generate the X-signature:
import hmac
import hashlib
import time
def generate_x_signature(timestamp: str, secret_key: str) -> str:
# Convert the timestamp and secret key to bytes
timestamp_bytes = timestamp.encode('utf-8')
secret_key_bytes = secret_key.encode('utf-8')
# Generate the HMAC-SHA256 signature
signature = hmac.new(secret_key_bytes, timestamp_bytes, hashlib.sha256).hexdigest()
return signature
# Example usage
# Generate the current timestamp as a string
timestamp = str(int(time.time()))
secret_key = "my_secret_key"
x_signature = generate_x_signature(timestamp, secret_key)
print("Timestamp:", timestamp)
print("X-Signature:", x_signature)
And here is the example output:
X-Timestamp: 1700000000
X-Signature: 9b6c2cbfcf5a2fcf1a03b2dcf263dc8a59e248a212a24635f515e1c8708d2b4c
Step 3: Send API Request with OAuth2 and X-Signature
Now that the client has obtained an OAuth2 access token and generated the X-Signature, the next step is to send the API request. This request should include the following headers:
Authorization: The Bearer token obtained from the OAuth2 flow.
X-Timestamp: The current Unix timestamp (in seconds), which provides a reference for when the request was made.
X-Signature: The generated signature, ensuring the integrity of the request.