Tutorial: Retail Customer Onboarding with Socure and Mbanq Cloud

This guide explains how an API consumer onboards an individual customer by using Socure for identity verification and Mbanq Cloud for the customer record, KYC documents, verification, and activation.

This guide describes the API-consumer-managed Socure flow. In this model, your application calls Socure and Mbanq Cloud separately. Do not also start Mbanq-managed hosted KYC for the same onboarding attempt unless Mbanq has configured your tenant for that integration pattern.

Responsibilities

End-to-end flow

Socure approval and Mbanq customer activation are different events. A successful Socure decision allows your application to continue; it does not by itself verify or activate the Mbanq customer.

Prerequisites

Before starting, obtain:

• Mbanq Cloud API credentials and tenant ID.
• Socure credentials for the intended environment.
• The Mbanq customer-identifier types enabled for your tenant.
• Your tenant's required KYC verification level, such as FULL.
• A secure mapping between the Mbanq clientId and Socure transaction/document references.

Use sandbox credentials and fictitious personal information during testing. Never submit real SSNs, identity documents, or selfies to a sandbox or simulator.

Step 1: Create the customer in Mbanq Cloud

Create the person customer before starting the external KYC process.

POST /v1/clients
Authorization: Bearer <MBANQ_ACCESS_TOKEN>
tenantId: <TENANT_ID>
Content-Type: application/json

Provide all fields required by your tenant, including:

• First and last name
• Date of birth
• Email address
• Mobile number and country code
• Primary residential address
• Nationality and tax information, when required

Store the returned clientId. Use it as the customer reference throughout the remaining flow.

API reference: Create Person Customer

Step 2: Start Socure document capture

Use Socure Predictive Document Verification to create a document-capture request.

Depending on your integration, the customer can complete capture through:

• A one-time link delivered by SMS
• Socure's Web SDK
• Socure's iOS SDK
• Socure's Android SDK

The capture experience collects the required identity-document images and a selfie/liveness result. Store the Socure document reference and transaction reference against the Mbanq clientId.

Do not treat creation of the document request as successful verification. Wait until Socure reports that document capture and processing have completed.

References:

• Socure Developer Hub
• Socure DocV iOS SDK
• Socure DocV Android SDK

Step 3: Perform Socure ID+ checks

Submit the customer's required identity data and configured modules to Socure ID+.

The modules enabled for your Socure account can include:

• Address Risk
• Fraud risk modules
• Alert List
• Decision
• Email Risk
• Global Watchlist
• Socure Verify (KYC)
• Phone Risk
• Predictive Document Verification
• Device Risk

Device Risk requires a separate device-intelligence SDK integration and a device/session reference. Do not enable the module unless your application captures the required device data.

Device SDK references:

• React Native
• Android
• iOS

Step 4: Handle the Socure decision

Use the final Socure decision—not only an individual module score—to decide the next action.

Persist the decision, transaction reference, and relevant reason codes for audit and support. Do not store unnecessary raw Socure responses containing personal information.

Step 5: Retrieve the approved document artifacts

After document verification finishes successfully, retrieve the permitted identity-document images or files from Socure.

Keep the artifacts encrypted and only as long as necessary to upload them to Mbanq Cloud and meet your retention obligations. Do not expose Socure credentials or raw document URLs to the client application.

Step 6: Create customer identifiers in Mbanq Cloud

Create a separate Mbanq customer identifier for each required identifier, for example:

• SSN or ITIN
• Passport
• Driver's license
• National identity card

POST /v1/clients/{clientId}/identifiers
Authorization: Bearer <MBANQ_ACCESS_TOKEN>
tenantId: <TENANT_ID>
Content-Type: application/json

Use the identifier type configured for your tenant and store the returned identifier ID.

If your tenant requires jurisdiction-qualified national identifiers, use the configured format, such as US-<SSN> or AE-<NATIONAL_ID>. Confirm this policy with Mbanq before implementation because identifier formats and duplicate checks are tenant-specific.

API reference: Create Client Identifier

Step 7: Attach documents to their identifiers

Attach each retrieved document to the matching Mbanq identifier.

POST /v1/client_identifiers/{clientIdentifierId}/documents
Authorization: Bearer <MBANQ_ACCESS_TOKEN>
tenantId: <TENANT_ID>
Content-Type: multipart/form-data

Examples:

• Attach passport images to the Passport identifier.
• Attach driver's-license images to the Driver's License identifier.
• Attach the configured SSN evidence to the SSN identifier when required.

API reference: Upload Client Documents

Step 8: Verify the customer in Mbanq Cloud

After all required profile data, identifiers, and documents are present, request Mbanq verification.

POST /v1/clients/{clientId}?command=verify
Authorization: Bearer <MBANQ_ACCESS_TOKEN>
tenantId: <TENANT_ID>
Content-Type: application/json

{
  "kycVerificationType": "FULL",
  "note": "External KYC completed and required documents uploaded"
}

This operation validates the Mbanq onboarding requirements. It is not another Socure ID+ request.

If the API returns a domain-rule error, inspect the returned developer or globalization code, correct the missing profile data, identifier, or document, and retry.

API reference: Verify Customer

Step 9: Activate the customer

Call activation only after Mbanq verification succeeds.

POST /v1/clients/{clientId}?command=activate
Authorization: Bearer <MBANQ_ACCESS_TOKEN>
tenantId: <TENANT_ID>
Content-Type: application/json

{
  "locale": "en",
  "dateFormat": "yyyy-MM-dd",
  "activationDate": "2026-08-20"
}

A successful response transitions the customer to Active and completes this onboarding flow.

API reference: Activate Customer

Consumer state model

Track the orchestration with explicit states rather than a single Boolean flag:

CUSTOMER_CREATED
DOCUMENT_CAPTURE_PENDING
DOCUMENT_PROCESSING
KYC_ACCEPTED
KYC_MANUAL_REVIEW
KYC_RESUBMISSION_REQUIRED
KYC_REJECTED
DOCUMENTS_UPLOADED
MBANQ_VERIFIED
MBANQ_ACTIVE
FAILED

Only MBANQ_ACTIVE means that the customer has completed the full platform onboarding flow.

Retry and security requirements

• Use an idempotency/correlation key for every onboarding attempt.
• Do not create a second Mbanq customer when retrying Socure.
• Do not create duplicate identifiers when retrying document upload.
• Verify Socure webhook signatures before accepting status changes.
• Treat webhook delivery as repeatable and potentially out of order.
• Keep Socure and Mbanq credentials on the server; never place them in a mobile or browser application.
• Redact SSNs, document images, access tokens, and full provider responses from logs.
• Present manual-review and rejection messaging approved by your compliance team.

Completion checklist

The customer is fully onboarded only when all of the following are true:

• The Mbanq customer exists.
• Socure returned an acceptable final decision.
• Required identifiers exist in Mbanq Cloud.
• Required files are attached to the correct identifiers.
• Mbanq customer verification succeeded.
• Mbanq customer activation succeeded.