Integration Preparation
This guide covers the prerequisites and key information required before integrating the Easy Cash Direct Debit (Firm Banking) API.
Environment Keys
Sandbox and Production environments are fully isolated and use separate Merchant IDs and keys.
| Environment | Merchant ID | Auth Key | Purpose |
|---|---|---|---|
| Sandbox | Shared test Merchant ID | Shared test key | Development and testing (no actual transfers occur) |
| Production | Merchant-specific ID | Merchant-specific key | Live service (actual transfers occur) |
Merchant Key Provisioning (Post-Contract)
After signing a contract with Hecto Financial, you will receive the following credentials for the Production environment.
| Item | Description |
|---|---|
| Merchant ID (mchtId) | Unique merchant identifier. |
| Hash generation key | SHA-256 key for tamper protection. |
| Encryption key | AES-256 key for protecting personal and sensitive data. |
NOTE
Provisioned via Sales Representative
Merchant IDs, encryption keys, and hash generation keys for both Sandbox and Production are issued through your Hecto Financial sales representative. Key values shown in this specification are example data for illustration purposes only.
Where to Find Your Keys
You can look up your issued keys on the merchant admin site. The merchant admin site URL and account are provided by your sales representative.
- In the left menu of the merchant admin site, select [Master Store Information] → [Basic Information].
- Check the hash generation key (license) and encryption key in the [License & Encryption key information] section at the top of the Basic Information page.
NOTE
Access inquiries
For the merchant admin site URL, account, or key issuance, contact your sales representative.
Server Integration Environment
For server domains, IP addresses, and firewall settings, see Servers & Network.
Development Requirements
Easy Cash Direct Debit integration requires a backend server.
| Layer | Role |
|---|---|
| Backend (required) | HMAC signature generation, personal data encryption, payment processing, response verification |
| Frontend | Identity verification screen invocation (if applicable) |
Backend Server Required
For security reasons, HMAC signature generation and personal data encryption must be performed server-side. A frontend-only integration is not supported.
Encryption and Tamper Protection
Easy Cash Direct Debit uses two security mechanisms to protect data.
Personal and Sensitive Data Encryption
| Item | Detail |
|---|---|
| Algorithm | AES-256 / ECB / PKCS5Padding |
| Encoding | Base64 |
| Encrypted fields | Manager name, landline number, mobile number, email, account holder name, account number, etc. |
| Sandbox key | pgSettle30y739r82jtd709yOfZ2yK5K (32 bytes) |
| Production key | Issued separately after contract |
Tamper-Protection Hash
| Item | Detail |
|---|---|
| Algorithm | SHA-256 |
| Encoding | Hex |
| Sandbox key | ST1009281328226982205 (21 bytes) |
| Production key | Issued separately after contract |
| Generation method | Concatenate parameters → SHA-256 hash → Hex encode |
Hash Validation Required
• Requests: Generate and include the hash in every request. Requests with mismatched hashes will be rejected.
• Responses: Verify the hash on every response. Skipping verification exposes your integration to tampering attacks.
Important Notes
Testing in Production
Production Environment Testing
Any testing in the Production environment must be coordinated with your Hecto Financial representative in advance. Costs incurred from uncoordinated production test transactions are the merchant's responsibility.
API Request Guidelines
- POST only — All APIs support POST method exclusively.
- JSON format — All requests and responses use
application/json;charset=UTF-8. - Prohibited characters — The following characters cannot be included in field values:
:,&,?,', newline,<,>. - Parameter validation — Missing required fields, hash mismatches, or length violations return an error response.
{
"outStatCd": "0031",
"outRsltCd": "ST09",
"outRsltMsg": "Invalid request message"
}
Response Parameters May Change
Response Parameters Subject to Change
Response parameters may be added or modified without prior notice. Design your integration to be resilient to parameter changes.
Network and Protocol Requirements
- TLS 1.2 or higher required — HTTPS (port 443) only.
- Timeout — API response timeout is 30 seconds.
- Firewall rules — Both Primary and Secondary Production IPs must be allowed.
- Avoid hosts file overrides — Hardcoded IPs prevent automatic IDC failover.
