Prepare the connector
Backbase deploys this connector. To share connectivity details and provide the environment details, follow these steps:- Share connectivity details. Share connectivity details between Banking OS and Jumio as described in Network connectivity.
-
Send environment details to Backbase.
Send
jumio.baseUrl,jumio.retrievalBaseUrl, and anyjumio.template.key.<templateId>overrides to your Backbase support team. -
Register the webhook with Jumio.
Ask your Backbase support team for the inbound callback URL. Register that URL in your Jumio callback configuration. Backbase sets the
jumio.callbackUrlconfiguration property to the same URL. -
Configure Sync Hub consumption.
Configure your consumer to subscribe to the Sync Hub topic
identity-verificationand to parse the CloudEvent typecom.backbase.party.lifecycle.event.spec.v1.IdentityVerificationEvent. For thedatapayload fields, see Jumio reference.
Test your integration
To use the Party Lifecycle Unified API, include your Banking OS subscription key in the request header. If you don’t have a key, contact your Backbase support team to request one.
For the full contract, see the API playground.
To create an applicant and start a workflow, call
POST /applicant-workflows. Include personName, userData.identification, userData.templateId, and userData.customerRelationship. The connector maps userData.identification to the Jumio customerInternalReference. For an NTB journey, set customerRelationship to false and don’t send userData.applicantId. For an ETB journey, set customerRelationship to true and include userData.applicantId. The response includes clientLaunchUrl for the Jumio browser experience, plus sessionId, applicantId, and sdkToken.
To retrieve results on demand, call POST /workflow-result with sessionId and applicantId. Jumio doesn’t use sdkToken on this call.
Troubleshooting
If your connector doesn’t respond as expected, check these common scenarios.5xx: internal server error or core system down
5xx: internal server error or core system down
Cause: The Banking OS gateway can’t establish a handshake with the Jumio endpoint. This typically indicates an upstream service outage at Jumio or a network routing failure.Solution: Verify the operational status of the Jumio environment with Jumio.
5xx: timeout or SocketTimeoutException
5xx: timeout or SocketTimeoutException
Cause: The request to Jumio exceeded the configured timeout threshold. This can occur during high load or network latency issues.Solution: Verify the operational status of the Jumio environment with Jumio.
Invalid authentication
Invalid authentication
Cause: You entered incorrect credentials during setup.Solution: Verify your credentials with Jumio and contact your Backbase support team to update the connection.
429: rate limit exceeded
429: rate limit exceeded
Cause: The number of incoming requests exceeded the defined threshold for your subscription tier. This response protects the stability of the Banking OS and partner infrastructure.Solution: Review your request patterns to identify unexpected spikes. If you require higher throughput, contact your Backbase support team to request an adjustment to your Azure API Management (APIM) rate limit policy.
Create applicant workflow validation fails
Create applicant workflow validation fails
Cause: Required Jumio fields are missing or inconsistent, for example
customerRelationship, identification, templateId, personName, or an ETB applicantId.Solution: Confirm customerRelationship is set. For ETB (true), include applicantId. For NTB (false), omit applicantId. Confirm that templateId resolves to a configured Jumio workflow key. Include personName and identification.Identity verification events not received on Sync Hub
Identity verification events not received on Sync Hub
Cause: You haven’t registered the Jumio callback, inbound authentication failed, the callback status is not
PROCESSED, Sync Hub publishing isn’t enabled, or your consumer doesn’t subscribe to the identity-verification topic.Solution: Confirm that Jumio delivers callbacks to the Banking OS inbound URL. Verify that retrieval succeeds after PROCESSED, that Sync Hub publishing is enabled, and that your consumer subscription is active.