Palm Vein SDK & Integration Guide
Build a clear path from your first palm scan to a production-ready biometric application.
Explore SDK testing, user registration, server deployment and capacity planning for palm vein payment and identity projects.
Test the workflow before planning deployment.
A working Demo helps your developers understand what the palm vein SDK expects, what the algorithm service returns and where your business logic belongs.
-
Share your project requirements
Tell us your host platform, preferred terminal, expected registered users and application, such as palm vein payment, access control or identity verification.
-
Run the large-scale SDK & Demo
Before purchasing the large-model algorithm, use the available public-cloud testing environment to validate registration and identification with compatible sample hardware.
-
Review results with your team
Check user binding, server responses and the complete application flow. Then confirm integration requirements and deployment scope.
Choose where your backend fits.
The current Large Scale SDK supports two server-based integration approaches. Your application owns the business workflow and payment decisions.
Connect directly to the algorithm service
Configure the algorithm server URL in the SDK. Your platform manages user information and connects identification results to your application workflow.
Route requests through your backend
Your backend exposes registration, query and deletion endpoints, forwards the corresponding requests and returns responses in the format expected by the SDK.
The current Large Scale SDK does not provide a standalone capture-only method that returns palm data without completing server-based registration. Capture-only requirements need a separate assessment.
Palm vein SDK support covers Android, Windows and Linux, with Flutter integration options. Confirm the relevant SDK, host USB permissions and hardware compatibility for your project.
Your platform defines the user identity.
In the Large Model, your system creates a stable, unique user_id and supplies it during palm registration. The SDK and algorithm service do not generate this ID.
Registered left and right palms can be associated with the same user ID. Your backend links that identity to the appropriate customer, employee or account record.
// Illustrative registration callnregisterUserWithPalmData(n userId = "customer-123"n)- Use a stable identifier from your business platform.
- IDs are case-sensitive and must be 1-128 bytes.
- Avoid control characters and backslashes. Letters, digits, hyphens and underscores are recommended.
- Registration biometric data is returned after registration succeeds.
The Small Model uses featureId to identify a palm. The Large Model uses your platform's user_id to identify a user. They are decoupled, do not merge automatically and their SDKs should not be included in the same app build.
Deploy on infrastructure you control.
Plan the large-model environment around your network conditions, operational responsibilities and expected workload.
Discuss deployment requirementsPrepare resources for restricted networks
Offline deployment documentation is available for the Large Model. After purchase, the resource configuration list enables your team to prepare the required chart packages and images in advance and transfer them to a private registry.
Arrange deployment support
Free remote deployment support is available. Kubernetes deployment requires cluster-admin access. Environment checks, configuration and deployment typically take two to three days once the required infrastructure is ready.
Keep control after handover
X-Telcom does not require ongoing access to your servers after deployment. The deployed algorithm does not require external links. Your team manages the production environment.
User capacity and request rate are different requirements.
Plan for both the number of registered users and peak simultaneous requests. Growing from 100,000 to one million users within the Large Model is capacity expansion within that system.
| Planning factor | What to review |
|---|---|
| Registered users | Select licence capacity for your expected user population. Purchased licences are lifetime-valid within that capacity; deleting users releases capacity. |
| Peak request rate | Confirm required queries per second, expected concurrency and acceptable response times separately from user count. |
| Server & storage | Review CPU, GPU, memory and storage against the configuration recommendations for your workload and growth plan. |
| Deployment topology | A single-server deployment is generally recommended around 50,000-100,000 users. Evaluate a Kubernetes cluster for populations above one million, or earlier where scalability requirements justify it. |
| Device SDK | The default device SDK does not need to change solely because user count increases. Server hardware, licence capacity and QPS configuration may need updating. |
Final sizing depends on workload and availability requirements. User population alone does not guarantee throughput or response time.
Define how palm data is protected.
Treat image encryption, transport security and application access as distinct parts of the integration.
Optional image encryption
The Large Model supports client-side AES-256-GCM image encryption. Encrypt the image before upload and set is_image_encrypted to true in metadata.
Compatible payloads
The encrypted payload must match the server's decryption format. Confirm key configuration and ciphertext packaging in the supplied documentation before implementation.
Customer data control
The customer owns and controls the deployed system and data. Define access, retention, deletion and operational procedures to support your GDPR and other applicable compliance obligations.
Practical answers for your development team.
Can I test the large-scale SDK before purchasing an algorithm licence?
A public-cloud testing environment and Demo are available before purchasing the large-model algorithm. Contact X-Telcom to arrange evaluation access and confirm the appropriate sample hardware.
Are the Small and Large Models connected?
No. They are entirely separate, decoupled systems. The Small Model uses featureId to identify a palm. The Large Model associates palm data with a user_id supplied by your platform. Do not use both SDKs in the same app build.
Can the large-scale SDK capture data without a server?
The current Large Scale SDK requires a valid server URL for registration and identification. It does not offer a separate capture-only method that returns palm data without completing the server registration flow.
Who creates the user_id?
Your platform generates and supplies a stable, unique user_id. The SDK and Algorithm Server do not generate it. Registered left and right palm data can be associated with that same user_id.
Does growth from 100,000 to one million users require a new device SDK?
An increase in user count alone does not require changing the default device SDK. Review server hardware, storage, licence capacity and QPS configuration with X-Telcom.
Can existing palm images be registered in the Large Model?
Where suitable palm images and their business user IDs have been retained, a customer-developed script can call the Large Scale registration API one user at a time. This is registration in a separate system, not a database merge. Without suitable images, new palm capture may be required.
Do purchased algorithm licences expire?
Purchased algorithm licences are valid for lifetime use within the purchased capacity. The free Small Model supports up to 10,000 IDs without an expiry. A separate three-month Large Model trial is available to qualifying customers who have placed an initial 100-device order and signed a strategic cooperation agreement.
Will X-Telcom need ongoing access to our production servers?
Remote deployment support is available. Deployment requires cluster-admin access for a Kubernetes environment and typically takes two to three days to check, configure and deploy a prepared environment. After deployment, X-Telcom does not require ongoing server access. Case analysis may require customer-provided images and error information.
Bring us your palm vein project.
Share your platform, preferred hardware, expected user population and peak request rate. We will help you identify a suitable testing and integration path.