Integration Security Guide for Partners with Loa Heo Vang System#
1. Introduction#
To ensure the security, integrity, and trustworthiness of communications between your system and the Loa Heo Vang system, we require the implementation of three main security layers:1.
API Authentication with OAuth 2.0: Ensures secure access to Loa Heo Vang's APIs using standard token-based authentication.
2.
Transport Layer Security with mTLS (Mutual Transport Layer Security): Guarantees the confidentiality of data in transit and provides mutual authentication of both systems, applied to all communications, including outbound notifications from Loa Heo Vang.
3.
Application/Data Layer Security with Digital Signatures for Payload: Ensures the integrity of the data within the message and authenticates the origin of the message, applied to all communications, including outbound notifications from Loa Heo Vang.
2. General Requirements#
Key Algorithm: RSA (2048 bits or higher recommended).
Hashing Algorithm: SHA256.
Signature Algorithm: SHA256withRSA.
TLS Protocol: TLSv1.2 or TLSv1.3.
Certificate and Key Management:Partners are responsible for generating, securely storing, and protecting their private keys.
Partners must have a process in place to renew certificates periodically before expiration.
Do not share private keys with any third party.
3. API Authentication: OAuth 2.0 Client Credentials Flow#
All API calls initiated by the Partner to the Loa Heo Vang system must be authenticated using OAuth 2.0. We support the Client Credentials Flow.3.1. Obtaining an Access Token#
To get an access token, your system must make a POST request to our authentication endpoint using your assigned client_id and client_secret.Endpoint: api/v1/partner/auth/token
Content-Type: application/x-www-form-urlencoded
grant_type: client_credentials (fixed value)
client_id: Your unique client_id provided by Loa Heo Vang.
client_secret: Your unique client_secret provided by Loa Heo Vang.
POST /api/v1/partner/auth/token HTTP/1.1
Host: api.loaheovang.com
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "eyJhbGciOiJIUzI1Ni...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "eyJhbGciOiJIUzI1Ni..."
}
access_token: The token to be used for accessing protected resources.
token_type: Indicates the type of token. Always Bearer.
expires_in: The lifetime in seconds of the access token. (e.g., 3600 seconds = 1 hour).
refresh_token: A token used to obtain a new access token when the current one expires.
3.2. Refreshing an Expired Access Token#
When your access_token expires, you must use the refresh_token to obtain a new access_token.Endpoint: api/v1/partner/auth/refresh
Content-Type: application/x-www-form-urlencoded
grant_type: refresh_token (fixed value)
refresh_token: The refresh_token obtained from the initial authentication.
client_id: Your unique client_id provided by Loa Heo Vang (required for validation).
POST /api/v1/partner/auth/refresh HTTP/1.1
Host: api.loaheovang.com
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN&client_id=YOUR_CLIENT_ID
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "eyJhbGciOiJIUzI1Ni...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "eyJhbGciOiJIUzI1Ni..."
}
3.3. Using the Access Token for API Calls#
Once you have an access_token, you must include it in the Authorization header of all subsequent API requests to protected resources.Value: Bearer YOUR_ACCESS_TOKEN
GET /api/v1/partner/transactions/status HTTP/1.1
Host: api.loaheovang.com
Authorization: Bearer eyJhbGciOiJIUzI1Ni...
4. Transport Layer Security: mTLS (Mutual Transport Layer Security)#
mTLS ensures that both the Loa Heo Vang system and the Partner's system authenticate each other before establishing an encrypted communication channel. This applies to all communications, including API calls from Partner to Loa Heo Vang, and notification webhooks from Loa Heo Vang to Partner.4.1. Required Certificate Types#
To implement mTLS, Partners need to prepare the following certificates:Partner's Client Certificate:partner_client.crt: The public certificate of the Partner's system.
partner_client.key: The private key of the Partner's system.
The Partner needs to generate a key pair and submit a Certificate Signing Request (CSR) for signing by Loa Heo Vang's CA.
4.2. mTLS Certificate Exchange and Signing Process#
1.
Partner Generates mTLS Key Pair:The Partner generates a private key (partner_client.key) and a Certificate Signing Request (CSR) (partner_client.csr).
Note: The CN (Common Name) should be a unique ID or the name of the Partner's system. 2.
Partner Submits CSR to Loa Heo Vang:The Partner sends the generated partner_client.csr file to us.
**Loa Heo Vang will sign this CSR and return the signed certificate file (partner_client.crt) to the Partner.
4.3. mTLS Configuration on Partner's System#
The Partner must configure their application or server (e.g., Nginx, Apache, Spring Boot, Node.js client, etc.) to:Establish an HTTPS connection to the Loa Heo Vang system for API calls.
Set up an HTTPS server to receive notification webhooks from Loa Heo Vang.
Present the Partner's certificate (partner_client.crt and partner_client.key) when requested by the Loa Heo Vang system (for outbound API calls to us) and when Loa Heo Vang connects to your notification endpoint (for inbound calls from us).
curl (for testing outbound mTLS):(Replace /path/to/ with the actual paths to the Partner's certificate and key files, and https://api.loaheovang.com/your-endpoint with the actual Loa Heo Vang API URL).
5. Application Layer Security: Digital Signature for Payload#
In addition to mTLS, every message (payload) exchanged between the two systems must be digitally signed to ensure data integrity and source authentication. This applies to all communications, including API calls from Partner to Loa Heo Vang, and notification webhooks from Loa Heo Vang to Partner.5.1. Required Certificate Types#
Partner's Digital Signature Keypair:partner_signature.crt: The public certificate used for digital signing (we will issue this after the Partner submits the CSR).
partner_signature.key: The private key used for digital signing (Partner's responsibility for management).
Loa Heo Vang's Digital Signature Public Certificate: We will provide our public certificate (loa_heo_vang_signature.crt) for Partners to verify our digital signatures on inbound notifications.
5.2. Digital Signature Certificate Exchange and Signing Process#
1.
Partner Generates Digital Signature Key Pair:The Partner generates a private key (partner_signature.key) and a Certificate Signing Request (CSR) (partner_signature.csr).
Note: The CN should be a distinct ID or system name for signing purposes. 2.
Partner Submits CSR to Loa Heo Vang:The Partner sends the partner_signature.csr file to us.
Loa Heo Vang will sign this CSR using our internal CA and return the signed certificate file (partner_signature.crt) to the Partner.
The Partner must then provide the partner_signature.crt file to Loa Heo Vang so we can verify the Partner's digital signatures on API calls.
3.
Loa Heo Vang Provides Our Digital Signature Public Certificate:We will provide loa_heo_vang_signature.crt to the Partner. The Partner will use this to verify digital signatures on notifications sent by Loa Heo Vang.
5.3. Message (Payload) Signing and Verification Process#
5.3.1. On Partner's System (When sending a message to Loa Heo Vang)#
1.
Prepare Payload: The data to be signed is the entire Payload (the main content of the message).
2.
Hash the Payload: Use the SHA256 algorithm to compute the hash value of the Payload. 3.
Sign the Hash: Use the Partner's digital signature private key (partner_signature.key) and the RSA algorithm to sign the generated hash value.digital_signature = RSA_Sign(hash, partner_signature.key)
4.
Base64 Encode the Signature: Convert the digital_signature to Base64 format.
5.
Attach the Signature to the Message: Include the Base64-encoded digital signature in a specific HTTP header field or within the Payload of the message (e.g., X-Signature, Digital-Signature).
5.3.2. On Partner's System (When receiving a notification from Loa Heo Vang)#
1.
Loa Heo Vang will sign the notification Payload using its own digital signature private key.
2.
Partner will receive the notification with the signature attached.
3.
Partner extracts Payload and Signature: Extract the entire Payload and the digital signature from the received message.
4.
Base64 Decode the Signature: Decode the digital signature from Base64 back to binary format.
5.
Hash the Received Payload: Compute the hash value of the received Payload using SHA256.received_hash = SHA256(Received_Payload)
6.
Verify the Signature: Use Loa Heo Vang's digital signature public certificate (loa_heo_vang_signature.crt) to verify the digital signature against the newly computed hash value.is_valid = RSA_Verify(received_hash, digital_signature, loa_heo_vang_signature.crt)
7.
If is_valid is true, the message is considered authentic and untampered, originating from Loa Heo Vang.
If is_valid is false, the message has been altered or did not originate from Loa Heo Vang, and it will be rejected.
6. Partner Notification Webhook System#
Loa Heo Vang will send real-time notifications to the Partner's system via a webhook.Endpoint: The Partner must implement an API endpoint to receive these notifications. An example endpoint could be api/v1/lhv/notification.
Registration: The exact endpoint URL should be registered and configured with the Loa Heo Vang system administrator.
Security for Notifications: When Loa Heo Vang sends notifications to the Partner's webhook endpoint, both mTLS (Section 4) and Digital Signature (Section 5) will be applied. The Partner's system must be configured to support mTLS to receive these calls and verify the digital signature on the notification payload.
7. Private Key Storage and Protection#
This is of paramount importance. The Partner's private keys (for mTLS and digital signatures) must be protected with the utmost rigor.Never expose private keys or share them through insecure channels.
Use tightly access-controlled environments for key storage (e.g., encrypted drives, permission-protected files, or ideally, a Hardware Security Module - HSM).
Limit access to key files and only allow authorized applications/processes to use them.
8. Testing and Operations#
After implementation, the Partner must perform thorough testing to ensure all three security layers (OAuth 2.0, mTLS, Digital Signature) are functioning correctly for both inbound and outbound communications.
Test both success and failure scenarios (e.g., expired tokens, invalid client certificates, unsigned payloads, altered payloads).
Always keep security libraries and software updated to the latest versions to patch known vulnerabilities.
Establish robust logging and monitoring mechanisms to detect security incidents and unusual activities.
We believe that strict adherence to these guidelines will establish an extremely secure and reliable communication channel between your system and the Loa Heo Vang system, providing maximum support for sensitive banking transactions.Should you have any questions during the implementation process, please do not hesitate to contact the Loa Heo Vang technical support team via email (cto@anvui.vn).
Modified at 2025-07-01 07:24:24
