Integration Setup
This guide covers the prerequisites and basic information you need before integrating the White-Label API.
Environment Credentials
The Sandbox and Production environments are completely separate, each using distinct Merchant IDs and keys.
| Environment | Merchant ID | Auth Key | Purpose |
|---|---|---|---|
| Sandbox | Shared test Merchant ID | Shared test key | Development and testing (no actual payments processed) |
| Production | Merchant-specific ID | Merchant-specific key | Live service (actual payments processed) |
Merchant-Specific Key Issuance (Post-Contract)
After signing a contract with Hecto Financial, the following credentials are issued for use in the Production environment.
| Item | Description |
|---|---|
| Merchant ID (mchtId) | Unique merchant identifier |
| License Key | Key used for signature (hash) generation |
| Encryption Key | Key for protecting transaction amounts and personal data (AES-256) |
Server Integration Environment
For server domains, IP addresses, and firewall settings, see Servers & Network.
Development Requirements
White-Label integration requires both a frontend and a backend.
| Component | Role |
|---|---|
| Frontend (required) | Invoke payment checkout, receive payment result |
| Backend (required) | Generate signature, AES-256 encrypt amount, call payment/void APIs |
Backend Required
For security reasons, signature generation and amount encryption must be handled server-side. Integration cannot be completed with a frontend-only implementation.
Encryption and Tamper Protection
White-Label payments use two security mechanisms to protect data.
Personal and Sensitive Data Encryption
Encryption scheme for protecting personal and sensitive information.
| Item | Detail |
|---|---|
| Algorithm | AES-256 / ECB / PKCS5Padding |
| Encoding | Base64 |
| Encrypted fields | Transaction amount, customer name, mobile number, email, etc. |
| Sandbox key | pgSettle30y739r82jtd709yOfZ2yK5K |
| Production key | Issued separately after contract |
Tamper Protection Algorithm (pktHash)
Hash generation scheme for verifying data integrity.
| Item | Detail |
|---|---|
| Algorithm | SHA-256 |
| Encoding | Hex |
| Sandbox key | ST1009281328226982205 |
| Production key | Issued separately after contract |
| Generation method | Concatenate parameters → SHA-256 hash → Hex encode |
pktHash Verification Required
• Request: pktHash must be generated and included (requests with mismatched hash are rejected).
• Response: Verify pktHash before serving the result (skipping verification leaves you vulnerable to tampering attacks).
Important Notes
Production Environment Testing
- Production environment testing caution: Any costs incurred from testing in the Production environment are the merchant's responsibility. Always complete testing in the Sandbox environment first.
API Request Guidelines
- Use POST method only.
- Use only the parameters defined in the integration specification.
- Do not use special characters (
:,&,?,',<,>, etc.). - Do not use HTML tags or emojis.
- Request and response parameters are subject to change without prior notice.
Frontend Integration Guidelines
- Avoid using iframes (may malfunction in some browsers).
- nextUrl and cancUrl should use HTTPS (HTTP may cause cross-origin errors).
- nextUrl: Called when payment completes (not called if the window is force-closed).
- cancUrl: Called when the user closes the payment checkout via the 'X' button.
Browser and Protocol Requirements
- TLS 1.2 or higher is required.
- HTTPS (port 443) only; HTTP is not supported.
- TLS 1.1 and lower may be discontinued without prior notice.
- Supported browsers: Chrome, Edge
- Unsupported browsers: Internet Explorer, Firefox, Safari, Opera, etc.
Browser Restrictions
The White-Label service supports only Chrome and Edge browsers. Other browsers may not function correctly.
