When adding palm vein recognition to an existing application, one of the first architecture decisions is where to send the SDK’s requests.
Should the terminal communicate directly with the Algorithm Server? Or should requests pass through your existing backend?
X-Telcom’s Large Scale SDK supports both approaches. The important requirement is that the configured server exposes the expected interfaces and returns responses in the format required by the SDK.
This guide explains the two options, the responsibilities of your backend and the common misunderstandings that can delay integration.
Two Supported Palm Vein Integration Approaches
The Large Scale SDK requires a valid server URL for registration and identification. That URL can point to the Algorithm Server or to your backend.
| Integration approach | SDK server URL points to | Your team’s responsibility |
|---|---|---|
| Direct connection | Algorithm Server | Connect registration and identification results to your business application |
| Backend-mediated connection | Your backend | Forward the required operations to the Algorithm Server and return compatible responses to the SDK |
Both options use the algorithm service to complete the biometric workflow. Routing through your backend does not remove that dependency.
Option 1: Connect the SDK Directly to the Algorithm Server
With direct integration, you configure the Algorithm Server URL in the SDK.
The SDK sends registration and identification requests to that service, which returns the corresponding responses directly.
Request path: Terminal SDK → Algorithm Server
Response path: Algorithm Server → Terminal SDK
Your platform remains responsible for customer information, account associations and the business actions that follow identification.
When should you consider this approach?
Direct integration can be a practical starting point when your team wants to understand the standard SDK workflow before introducing an additional backend layer.
It lets developers validate the supplied registration and identification process and establish a working reference for later integration.
For evaluation, X-Telcom provides a Large Scale SDK Demo and public-cloud testing environment before customers purchase the large-model algorithm.
Option 2: Route SDK Requests Through Your Backend
If your architecture requires the terminal to communicate with your platform first, configure your backend URL in the SDK.
Your backend receives the request, calls the corresponding Algorithm Server API and returns the response to the terminal.
Request path: Terminal SDK → Your backend → Algorithm Server
Response path: Algorithm Server → Your backend → Terminal SDK
This approach allows your team to coordinate biometric requests with your existing application processes.
However, it also gives your backend a specific integration responsibility: it must preserve the SDK’s expected request-and-response contract.
What must your backend expose?
Your backend should provide the required interfaces for:
- Registration, or add.
- Identification or verification queries.
- Deletion.
Use the supplied API documentation for the exact request fields, input formats and responses. These operation names are not a substitute for the documented endpoint specifications.
The Response Must Return to the SDK
A frequent integration question is:
“After our backend registers the user with the Algorithm Server, do we still need to return anything to the SDK?”
Yes.
The backend must return the corresponding Algorithm Server response in the format expected by the SDK.
A server-side operation can succeed while the terminal workflow remains incomplete if the backend does not deliver a compatible response.
For example, replacing the expected registration response with a generic success message may prevent the SDK from completing its normal flow.
When troubleshooting, check both directions:
- Did the request reach the correct Algorithm Server interface?
- Did the corresponding response return through your backend to the SDK in the expected format?
Your Platform Creates the User ID
Whichever connection approach you choose, your platform generates and supplies the Large Model’s user identifier.
The SDK and Algorithm Server do not create this ID.
Your application passes the identifier during registration, for example:
registerUserWithPalmData(userId = "customer-123")
The registration flow associates the palm data with the supplied user ID. Registered left and right palms can be mapped to the same user.
Use a stable identifier that your platform can reliably associate with the intended customer or employee record.
The documented requirements are:
- Between 1 and 128 bytes.
- Case-sensitive.
- No control characters, such as tabs or newlines.
- No backslashes.
Letters, digits, hyphens and underscores are recommended.
Backend Routing Does Not Create a Capture-Only SDK
Some development teams want the terminal to capture a palm, return biometric data immediately and leave all further processing to their backend.
That requirement differs from routing the supported SDK workflow through a backend.
The current Large Scale SDK does not provide a standalone capture-only method that returns palm data without completing server-based registration.
The registration method does more than create a user record. It registers palm data with the algorithm service and associates it with the supplied user ID.
Registration biometric data is returned after successful registration.
If your application specifically requires an independent capture-only workflow, discuss that requirement with X-Telcom for a separate technical assessment.
Recognition and Payment Have Different Responsibilities
For palm vein payment integration, the algorithm service provides biometric identification. Your payment platform determines what happens next.
Your backend remains responsible for its own:
- Customer account association.
- Payment permissions and business rules.
- Payment authorisation.
- Transaction processing.
- Final payment status.
A successful palm match identifies a registered user. Your application must then use that result within its payment workflow.
Define these responsibilities early so that developers do not expect the recognition SDK to complete payment processing automatically.
How Should You Choose?
Start with the architecture your project actually requires.
| Project consideration | Integration implication |
|---|---|
| You need to understand and validate the standard SDK flow | Begin by testing the supplied Demo and direct algorithm-service connection |
| Your terminal must communicate through your existing platform | Evaluate backend-mediated integration |
| Your backend will sit between the SDK and algorithm service | Implement the required operations and compatible return responses |
| You need palm capture without server-based registration | Request a separate assessment of the capture-only requirement |
| You are building palm payment | Keep account and payment decisions within your business platform |
A successful direct Demo test provides a useful reference. If a later backend-mediated test fails, your team can compare the request and response handling against that working flow.
Keep Small and Large Model Integrations Separate
X-Telcom’s Small Model and Large Model are entirely separate, decoupled systems.
The Small Model uses featureId to identify a palm. The Large Model uses the customer platform’s user_id to identify a user.
The two SDKs should not be used together in the same application build.
The connection options discussed in this article concern the Large Scale SDK. They do not connect or merge the Small and Large Model systems.
Frequently Asked Questions
Can the SDK connect to our backend instead of the Algorithm Server?
Yes. Your backend must expose the required interfaces, call the corresponding Algorithm Server APIs and return responses in the format expected by the SDK.
Can our backend return only a simple success or failure value?
Follow the documented response contract. A simplified response may not contain the information the SDK needs to complete its workflow.
Does the Large Scale SDK require a server connection?
Yes. The current SDK requires a valid server URL for registration and identification.
Does routing through our backend change who generates user IDs?
No. Your platform generates and supplies the user ID in either integration approach.
Can we evaluate the workflow before purchasing the algorithm?
Yes. X-Telcom provides a Large Scale SDK Demo and public-cloud testing environment before algorithm purchase. Contact our team to confirm evaluation access and compatible sample hardware.
Plan Your Palm Vein Integration with X-Telcom
A clear server connection strategy helps your developers understand where requests go, which responses must return and which responsibilities belong to your platform.
Share your host platform, preferred terminal, backend architecture and application requirements with X-Telcom. Our team can help clarify the appropriate SDK evaluation and integration path.
