Immersve Conducted KYC

In the Immersve-conducted KYC mode, partner application directs their users to complete KYC through the Immersve UI. This contrasts with Partner Conducted KYC mode where Immersve is not directly involved with partners' cardholders.

We recommend this mode of KYC for partners not obligated to perform KYC as part of their main product, like crypto wallets. That's because implementing one's own KYC process can require a significant effort.

Integration steps

The following steps are for manual integration via a terminal. An integrating application should implement this flow with whatever technology stack is convenient.

Prerequisites

This guide assumes that the partner has already obtained an access token or API keys, and has the card program and funding source IDs ready.

token="<your_access_token>"
card_program_id="<your_card_program_id>"
funding_source_id="<funding_source_id>"

Request spending prerequisites

To begin the KYC process, call spending prerequisites specifying KYC type as immersve-conducted. Optionally, a redirectUrl can be provided to indicate where the user should be redirected upon completion of the KYC process.

If KYC is required, the response to the spending prerequisites request will contain a URL, where the user must be redirected to complete the KYC verification.

If KYC is not required, is already in progress, or the maximum number of retries has been exceeded, the URL will not be returned and the status will indicate the problem. See the Get Spending Prerequisites endpoint reference for more details on possible statuses.

Example Request:

curl -X POST "https://test.immersve.com/api/spending-prerequisites" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $token" \
  --data '{
    "cardProgramId": "'${card_program_id}'",
    "fundingSourceId": "'${funding_source_id}'",
    "spendableAmount": 100,
    "spendableCurrency": "USD",
    "kycType": "immersve-conducted",
    "kycRedirectUrl: "https://app.example.io",
  }'

Example Response:

{
  "prerequisites": [
    {
      "stage": "kyc",
      "status": "action-required",
      "type": "kyc",
      "actionType": "follow_kyc_url",
      "params": {
        "status": "kyc_required",
        "kycUrl": "https://verify.test.immersve.com/kyc/session/hg40904ddkr43?code=r938j9g"
      }
    },
  ]
}

Bypass KYC Steps (Optional)

Some KYC steps can be optionally bypassed by providing this information about the user in advance via API and using the kycHiddenSteps option when requesting spending prerequisites.

If spending prerequisites is called with the kycHiddenSteps option but information about the user has not yet been supplied, the response from spending prerequisites will indicate that additional information is required instead of providing a KYC URL. KYC steps that can be bypassed are explained in the table below.

Supply Contact Details (Optional)

If you would like to supply the user's contact details ahead of time, you can do so by calling the Update Contact Details endpoint, before starting the KYC process. This will then allow the user to check and update them as part of the Immersve Conducted KYC process.

Immersve requires users contact details (phone number and email) for the following reasons, this should be explained to customers:

• Adding cards to Apple/Google Pay wallets (X-Pay)
• Performing 3DS validation for online transactions

If a user doesn't provide contact details, they risk online transactions being rejected and might not be able to add cards to X-Pay wallets.

Before you share contact details with Immersve you must collect user consent via a checkbox. This can be done at the same time as KYC information sharing.

curl -X PATCH "https://${imsv_api_host}/api/accounts/${cardholder_account_id}/contact-details" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $token" \
  --data '{
    "email": {
      "emailAddress": "joe@cardholder.email",
    },
    "phone": {
      "phoneNumber": "+64123456789",
    }
  }'

Supply Expected Spend Amount (Optional)

Regulations require that Immersve obtain information on the “nature and purpose” of the proposed business relationship between ourselves and the cardholder.

Collection of the anticipated monthly spending level when onboarding a new cardholder is one measure that assists in our understanding of the nature and purpose of the cardholder account.

If you are using the kycHiddenSteps option to bypass the expected spend KYC step, you will need to supply the user's expected spend ahead of time. You can do this by calling the Update Expected Spend Amount endpoint, before starting the KYC process.

expected_spend_amount="" # in minor units
curl -X POST "https://${imsv_api_host}/api/accounts/${cardholder_account_id}/expected-spend-amount" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${card_issuer_api_key}" \
  -H "X-Api-Secret: ${card_issuer_api_secret}" \
  -H "X-Account-Id: ${cardholder_account_id}" \
  --data '{
    "expectedSpendAmount": "'${expected_spend_amount}'"
  }'

User goes through the KYC flow

Upon being redirected to the Immersve KYC page, the user will go through the process that involves the collection of the user's address and the verification of their identity through document and biometry (facial scan) collection.

At the end of the process the user is presented with a screen indicating that their profile is under review. The user does not have to stay on the page to know the outcome, as it will be communicated via email. If they stay on the page, it will update to display their KYC result once their KYC check has passed or failed.

Upon exiting the page, users are sent back to the redirectUrl provided in the spending prerequisites request. If no redirectUrl was provided, the exit button will close the browser tab.

Unsuccessful KYC check

If the KYC check was unsuccessful, the spending prerequisites response will return "kyc_check_failed" for the KYC prerequisite status, along with an array listing the reasons for the failure. If possible, a new KYC URL will be provided for the user to try again.

Confirmation of KYC Completion

Once redirected, check the spending prerequisites again to ensure no further KYC actions are required. Once there is no KYC prerequisite returned, and given all other checks are completed, the cardholder will be allowed to create and use their Immersve card.

Example Request:

curl -X POST "https://test.immersve.com/api/spending-prerequisites" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $token" \
  --data '{
    "cardProgramId": "'${card_program_id}'",
    "fundingSourceId": "'${funding_source_id}'",
    "spendableAmount": 100,
    "spendableCurrency": "USD",
    "kycType": "immersve-conducted",
    "kycRedirectUrl: "https://app.example.io",
  }'

Example Response:

{
  "prerequisites": []
}

Testing

For a complete guide on passing KYC in test mode, please read Passing KYC in Test