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"
      }
    },
  ]
}

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 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",
    }
  }'

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 they are 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 eventually inform about success or failure.

Upon exiting the page, users are sent back to the redirectUrl provided initially. If no URL was provided, exiting leads to closing 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