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.

How It Works

• Initiate Immersve Conducted KYC
  To begin the KYC process, call the Get Spending Prerequisites endpoint specifying KYC type as immersve-conducted. There are several optional parameters you can set to change the behavior of the KYC process.

  See the Get Spending Prerequisites endpoint reference for more details on the parameters, these are explained in more detail in the following sections.

  If Immersve already has complete KYC information for the individual owning the wallet, in the requested region the user will not be required to go through KYC.

• Handle Any Actions
  Depending on what options have been selected when calling spending prerequisites, the response may contain several actions.

  An action can be identified by looking at the list of prerequisites where "stage": "kyc" and "status": "action-required".

  [
    {
      "stage":"kyc",
      "status":"action-required",
      "actionType":"xxx"
    },
    //...other actions
  ]

  Each actionType identifies a specific action that must be made. e.g. follow_kyc_url, submit_contact_email, submit_contact_phone, set_expected_spend_amount.

  Once the necessary action has been taken for each actionType the action is removed from the list.

• Present Immersve Conducted KYC UI
  The follow_kyc_url action is the gateway to starting Immersve Conducted KYC.

  [
      {
        "stage":"kyc",
        "status":"action-required",
        "actionType":"follow_kyc_url",
        "params": {
          "kycUrl": "[url]"
        },
      },
      //...other actions
    ]

  The partner should navigate the user to the URL provided in the response.

• Wait for Background Checks
  Once the follow_kyc_url action has been completed. You will see a similar response to below from the Get Spending Prerequisites endpoint.

  [{
    "stage":"kyc","status":"pending"
  }]

  You must wait for the results of the KYC check to be returned.

• Immersve Conducted KYC is Complete
  Once all of the necessary actions have been completed and KYC checks have passed, all KYC prequisites have been completed. You'll see a similar response to the following:

  [{
    "stage":"kyc","status":"ok"
  }]

  Congratulations you've finished the Immersve Conducted KYC process.

Before You Get Started

The following steps are for manual integration via a terminal. An integrating application should implement this flow with whatever technology stack is convenient. 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>"

Calling Spending Prerequisites

Call the Spending prerequisites endpoint with kycType set to immersve-conducted to initiate Immersve Conducted KYC.

Any actions required to complete Immersve KYC will be returned in the response. The response will recalculate as actions are completed and any new prerequisite actions are identified.

When all prerequisites are completed and the user has completed Immersve Conducted KYC, background checks will be performed. This can take several minutes to several days depending on the effort required to verify an individual. Poll the endpoint until either a successful result is returned, or a new follow_kyc_url action is returned.

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

The below table outlines the required action to be taken for each actionType returned in the response.

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

Supply Residential Address (Optional)

If you would like to supply the user's residential address ahead of time, you can do so by calling the Submit Residential Addresses endpoint, before starting the KYC process. This will then allow the user to check and update the address as part of the Immersve Conducted KYC process (if residential-address step is not hidden).

You can submit either a structured or an unstructured address. We recommend using a structured address whenever possible as correct parsing of an unstructured address is not guaranteed.

• Structured Address

  Organizes address details into predefined fields, making it easier to validate and process the data.

  {
    "streetNumber": "140",
    "streetName": "Commonwealth Avenue",
    "town": "Yarralumla",
    "state": "ACT",
    "postalCode": "2600",
    "country": "AU"
  }

  Partners are strongly encouraged to use this format whenever possible.

• Unstructured Address

  This format consolidates the address into a single text string in the fullAddress field

  {
    "fullAddress": "140 Commonwealth Ave,
     Yarralumla ACT 2600, Australia",
    "country": "AU"
  }

  Immersve will attempt to structure a submitted unstructured address for addresses in New Zealand and Australia.

curl -X POST "https://${imsv_api_host}/api/accounts/${cardholder_account_id}/residential-addresses" \
  -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 '[
  {
    "streetNumber": "140",
    "streetName": "Commonwealth Avenue",
    "town": "Yarralumla",
    "state": "ACT",
    "postalCode": "2600",
    "country": "AU"
  }
]'

User Goes Through 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 contact details, expected spend amount, residential address (if not hidden) 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