Bill Presentment SDK Authentication

The Bill Presentment SDK uses existing B2B API Key + HMAC authentication for session creation, then a single session_token for SDK API calls.

Overview

Authentication involves two parties:

Party	Authenticates With	Purpose
Client backend	X-Api-Key + HMAC headers	Create SDK sessions (POST /v2/sdk/sessions)
SDK WebView (hosted app)	Authorization: Bearer {session_token}	Fetch bills and outstanding amounts

INFO

There is no separate client_id/client_secret flow, no SDK-specific secret rotation, and no POST /v2/sdk/token exchange endpoint.

API Key + HMAC Authentication

Session creation uses the same authentication scheme as other B2B API key endpoints.

Required headers:

• X-Api-Key
• X-Timestamp
• X-Nonce
• X-Signature (v1=...)

Request body for POST /v2/sdk/sessions:

{
  "ic_number": "901234567890"
}

• ic_number is required and must be exactly 12 digits

DANGER

HMAC signing must be done on your backend only. Never expose API keys or HMAC secrets in frontend or mobile code.

Session Flow

Session Token

Property	Value
Format	bp_sess_xxxx (prefixed random token)
TTL	15 minutes sliding (extended on each API call)
Absolute max lifetime	1 hour
Delivery transport	URL fragment (#token=...)
API transport	Authorization: Bearer {session_token}

Single-use delivery behavior:

1. SDK wrapper opens bills.iimmpact.com/#token=...
2. Hosted app reads token from location.hash
3. Hosted app clears the fragment immediately
4. All subsequent auth uses Authorization header only

Session Lifecycle

IC Number Handling

The IC number you provide when creating a session is used to look up the user's registered bill accounts. IIMMPACT handles IC number security:

• IC numbers are never returned in SDK API responses
• IC numbers are stored as hashes for account lookup
• Stored securely using one-way hashing for account lookup
• Plaintext IC exists only briefly during active session processing and is automatically cleaned up

INFO

The user object in the SDK result includes the IC number for your reference. This is the same IC you provided when creating the session.

Security Considerations

Concern	How It's Handled
Session creation abuse	Authenticated with your existing API Key + HMAC
Token leakage in URLs	Delivered via URL fragment, cleared immediately after read
Token replay	Short lifetime (15 min sliding, 1 hour absolute max)
Unauthorized bill lookup	Each session is scoped to one IC number; bill pairs are validated server-side
IC number exposure	Hashed for storage; plaintext only during active session, auto-cleaned
Cross-origin embedding	CORS allows all origins; access requires valid scoped session token