User Initialization
Complete the INI/HIA/HPB process to initialize your EBICS user.
Before an EBICS user can execute business transactions, they must complete a multi-step initialization process. This process establishes trust between your system and the bank by exchanging cryptographic keys.
Overview
The initialization process consists of seven steps:
┌─────────────────────────────────────────────────────────────┐
│ 1. Generate Keys → Create RSA key pairs │
│ 2. Send INI → Submit signature public key │
│ 3. Send HIA → Submit auth/encryption public keys │
│ 4. Generate Letter → Create INI letter with key hashes │
│ 5. Mail Letter → Send signed letter to bank │
│ 6. Fetch HPB → Download bank's public keys │
│ 7. Verify Keys → Confirm bank key fingerprints │
└─────────────────────────────────────────────────────────────┘
Step 1: Generate Cryptographic Keys
Three RSA key pairs are required for EBICS communication:
| Key Type | Purpose | Algorithm |
|---|---|---|
| Signature (A006) | Signs order data for authorization | RSA-SHA256 |
| Authentication (X002) | Signs EBICS messages | RSA-SHA256 |
| Encryption (E002) | Encrypts transaction keys | RSA |
Key Length Options
- 2048 bits - Standard security, faster operations
- 4096 bits - High security, recommended for large transactions
Step 2: Send INI Request
The INI (Initialize) request submits your signature public key to the bank.
Request Flow
Client Bank
│ │
│ INI Request (Signature Key) │
│ ─────────────────────────────────>│
│ │
│ Response: EBICS_OK │
│ <─────────────────────────────────│
│ │
User State After INI
- Status changes to:
PARTLY_INITIALISED_INI - Signature key is stored at bank (pending verification)
Step 3: Send HIA Request
The HIA (Host Initialization Agreement) request submits your authentication and encryption public keys.
Request Flow
Client Bank
│ │
│ HIA Request (Auth + Enc Keys) │
│ ─────────────────────────────────>│
│ │
│ Response: EBICS_OK │
│ <─────────────────────────────────│
│ │
User State After HIA
- Status changes to:
INITIALISED_PENDING - All three keys are stored at bank (pending verification)
Step 4: Generate INI Letter
The INI letter is a formal document containing your public key fingerprints (SHA-256 hashes). This letter must be:
- Printed on paper
- Signed by an authorized representative
- Sent to the bank via postal mail
Letter Contents
╔══════════════════════════════════════════════════════════════╗
║ EBICS INI LETTER ║
╠══════════════════════════════════════════════════════════════╣
║ Bank Information ║
║ ───────────────── ║
║ Host ID: EBIXHOST ║
║ Bank Name: Example Bank AG ║
║ ║
║ Partner / User Information ║
║ ────────────────────────── ║
║ Partner ID: PARTNER01 ║
║ User ID: USER001 ║
║ ║
║ Public Key Hashes (SHA-256) ║
║ ─────────────────────────── ║
║ Signature Key (A006): ║
║ A1B2 C3D4 E5F6 7890 1234 5678 9ABC DEF0 ║
║ 1234 5678 9ABC DEF0 A1B2 C3D4 E5F6 7890 ║
║ ║
║ Authentication Key (X002): ║
║ [hash value...] ║
║ ║
║ Encryption Key (E002): ║
║ [hash value...] ║
║ ║
║ ─────────────────────────────────────────────────────────── ║
║ Place: ________________ Date: ________________ ║
║ ║
║ Signature: ____________________________________________ ║
╚══════════════════════════════════════════════════════════════╝
Step 5: Send Letter to Bank
After printing and signing the INI letter:
- Send via registered mail to your bank's EBICS department
- Wait for bank confirmation (typically 1-3 business days)
- The bank will activate your user account
Step 6: Fetch Bank Keys (HPB)
Once the bank activates your account, download their public keys using the HPB request.
Request Flow
Client Bank
│ │
│ HPB Request │
│ ─────────────────────────────────>│
│ │
│ Response: Bank Public Keys │
│ - Authentication Key (X002) │
│ - Encryption Key (E002) │
│ <─────────────────────────────────│
│ │
Bank Keys Received
| Key | Purpose |
|---|---|
| Bank Auth Key | Verify bank's message signatures |
| Bank Enc Key | Encrypt data sent to bank |
Step 7: Verify Bank Keys
Critical Security Step: You must verify the bank's public key fingerprints match those provided by your bank through a separate channel (e.g., bank documentation, phone confirmation).
Verification Process
- Compare displayed SHA-256 hashes with bank-provided values
- If they match, accept the keys
- If they don't match, do not proceed - contact your bank
After Verification
- User status changes to:
READY - You can now execute business transactions
Common Issues
INI/HIA Failed: User Unknown
The User ID doesn't exist at the bank. Verify with your bank that the user has been created.
HPB Failed: User Not Ready
The bank hasn't activated your account yet. Wait for confirmation that your INI letter was processed.
Key Length Error
The bank doesn't support your chosen key length. Try 2048 bits if 4096 fails.
Next Steps
Once initialization is complete:
- Execute Orders - Upload payments, download statements
- VEU Workflows - Multi-signer authorization