Partner Conducted KYC

In the Partner conducted KYC mode, the partner collects and verifies the KYC information from cardholders, which is then supplied to Immersve via API (name, date of birth, ID details, etc).

Partner account must be configured to allow partner conducted KYC checks. This is subject to an agreement between Immersve and the partner. Ask Immersve support for more details.

Although Immersve still performs KYC checks on these details, we rely on the partner for verification of document scans and the cardholder's identity.

If Immersve already has complete KYC information for the individual owning the wallet, in any of the regions supported by the requested card program, the user will not be required to go through KYC.

Once Immersve has received and checked the KYC information for an Individual, the supported region associated with the wallet of the individual cannot be changed.

In the event that an individual wished to go through KYC in another supported region, a new wallet would be required.

Partner Conducted KYC is not currently supported in EU regions.

Below, we've outlined the steps for completion of this verification process, assuming all necessary details, such as document scans and biometrics, have been collected and verified.

Set up environment variables

card_issuer_api_key="<your_card_issuer_api_key>"
card_issuer_api_secret="<your_card_issuer_api_secret>"
card_program_id="<your_card_program_id>"
cardholder_account_id="<cardholder_account_id>"
funding_source_id="<funding_source_id>"

imsv_api_host="test.immersve.com"

Supply Contact Details

Immersve will not perform validation of a user's contact details.

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.

API Reference: Update Contact Details

your_email_address="" # the email address of the cardholder
your_mobile_number="" # the mobile number of the cardholder in E.164 format

curl -X PATCH "https://${imsv_api_host}/api/accounts/${cardholder_account_id}/contact-details" \
  -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 '{
      "email": {
        "emailAddress": "'${your_email_address}'"
      },
      "phone": {
        "phoneNumber": "'${your_mobile_number}'"
      }
    }'

Supply Expected Spend Amount

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.

API Reference: Update Expected Spend Amount

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

Submit Cardholder KYC statement

API Reference: Submit Kyc Statement

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

Be careful when setting the region as this cannot be changed. You will need to create a new wallet if this is incorrectly supplied.

The following sections show examples of how to submit individual types of identity evidence.

Note: You can combine multiple types of evidence into a single request when submitting.

Submitting a Statement with a Passport as evidence

The following script demonstrates how you could submit a KYC statement with a passport as evidence.

idempotencyKey="" # a unique key for each request. See submit KYC statement docs for more info
kyc_region="" # An ISO 3166-2 (Alpha-2) for the region you are submitting the statement for, i.e. EU, NZ, AU, etc.

# personal details
your_honorific="" #e.g. Mr, Mrs, Ms
your_given_name=""
your_middle_name=""
your_family_name=""
date_of_birth="" # YYYY-MM-DD

# address details
street_number=""
street_name=""
street_type="" #e.g. Road, Street, Avenue etc
suburb_name=""
town_name=""
region_name=""
state_name=""
postal_code=""
country_code="" #i.e. ISO 3166-2 Country Code

# passport details
passport_number=""
passport_country_code="" #i.e. ISO 3166-2 Country Code
passport_expiry_date="" # YYYY-MM-DD

curl -X PUT "https://${imsv_api_host}/api/accounts/${cardholder_account_id}/partner-kyc-statement" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-api-key: ${card_issuer_api_key}" \
  -H "x-api-secret: ${card_issuer_api_secret}" \
  --data '{
    "idempotencyKey": "'${idempotencyKey}'",
    "region": "'${kyc_region}'",
    "claims": [
      {
        "claimType": "DOB",
        "attributes": {
          "dateOfBirth": "'${date_of_birth}'"
        }
      },
      {
        "claimType": "FULL_NAME",
        "attributes": {
          "honorific": "'${your_honorific}'",
          "givenName": "'${your_given_name}'",
          "middleName": "'${your_middle_name}'",
          "familyName": "'${your_family_name}'"
        }
      },
      {
        "claimType": "ADDRESS",
        "attributes": {
          "addressType": "RESIDENTIAL",
          "streetNumber": "'${street_number}'",
          "streetName": "'${street_name}'",
          "streetType": "'${street_type}'",
          "suburb": "'${suburb_name}'",
          "town": "'${town_name}'",
          "region": "'${region_name}'",
          "state": "'${state_name}'",
          "postalCode": "'${postal_code}'",
          "country": "'${country_code}'"
        }
      }
    ],
    "evidence": [
      {
        "evidenceType": "PASSPORT",
        "documentId": "'${passport_number}'",
        "country": "'${passport_country_code}'",
        "expiry": "'${passport_expiry_date}'"
      }
    ]
  }'

Submitting a Statement with a Drivers License as evidence

The following script demonstrates how you could submit a KYC statement with a drivers license as evidence.

idempotencyKey="" # a unique key for each request. See api docs for more info
kyc_region="" # An ISO 3166-2 (Alpha-2) for the region you are submitting the statement for, i.e. EU, NZ, AU, etc.

# personal details
your_honorific="" #e.g. Mr, Mrs, Ms
your_given_name=""
your_middle_name=""
your_family_name=""
date_of_birth="" # YYYY-MM-DD

# address details
street_number=""
street_name=""
street_type="" #e.g. Road, Street, Avenue etc
suburb_name=""
town_name=""
region_name=""
state_name=""
postal_code=""
country_code="" #i.e. ISO 3166-2 Country Code

# drivers license details
license_number=""
license_country_code="" #i.e. ISO 3166-2 Country Code
license_region="" #See submit KYC statement docs for more info
license_version=""

curl -X PUT "https://${imsv_api_host}/api/accounts/${cardholder_account_id}/partner-kyc-statement" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-api-key: ${card_issuer_api_key}" \
  -H "x-api-secret: ${card_issuer_api_secret}" \
  --data '{
    "idempotencyKey": "'${idempotencyKey}'",
    "region": "'${kyc_region}'",
    "claims": [
      {
        "claimType": "DOB",
        "attributes": {
          "dateOfBirth": "'${date_of_birth}'"
        }
      },
      {
        "claimType": "FULL_NAME",
        "attributes": {
          "honorific": "'${your_honorific}'",
          "givenName": "'${your_given_name}'",
          "middleName": "'${your_middle_name}'",
          "familyName": "'${your_family_name}'"
        }
      },
      {
        "claimType": "ADDRESS",
        "attributes": {
          "addressType": "RESIDENTIAL",
          "streetNumber": "'${street_number}'",
          "streetName": "'${street_name}'",
          "streetType": "'${street_type}'",
          "suburb": "'${suburb_name}'",
          "town": "'${town_name}'",
          "region": "'${region_name}'",
          "state": "'${state_name}'",
          "postalCode": "'${postal_code}'",
          "country": "'${country_code}'"
        }
      }
    ],
    "evidence": [
      {
        "evidenceType": "DRIVERS_LICENSE",
        "documentId": "'${license_number}'",
        "country": "'${license_country_code}'",
        "region": "'${license_region}'",
        "version": "'${license_version}'"
      }
    ]
  }'

KYC Statement Addresses in Partner conducted KYC

The Submit Kyc Statement endpoint accepts both structured, and unstructured address formats in an Address claim.

Structured Address

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

{
  "claimType": "ADDRESS",
  "attributes": {
    "addressType": "RESIDENTIAL",
    "streetNumber": "73",
    "streetName": "Great Southern",
    "streetType": "ROAD",
    "suburb": "Auckland CBD",
    "town": "Auckland",
    "region": "Auckland",
    "state": "AKL",
    "postalCode": "6140",
    "country": "NZ"
  }
}

Partners are strongly encouraged to use this format whenever possible.

Unstructured Address
When it is not possible to provide a Structured Addresses, partners can provide an Unstructured Address.
{ "claimType": "ADDRESS", "attributes": { "addressType": "RESIDENTIAL", "fullAddress": "2/45 Laddier Road, Centurion, The Reeds, Auckland, Auckland 0100, New Zealand", "country": "NZ" } }
This format consolidates the address into a single text string in the fullAddress field, which Immersve later attempts to parse into structured address components.
Key Considerations
Use Structured Address where possible: Structured addresses are preferred for accuracy and consistency.
Use Unstructured Addresses only if structured address data is not available from your IDV provider.
Immersve attempts to parse Unstructured Addresses into structured address components after submission. Ensure the fullAddress field is as detailed as possible.

Poll spending prerequisites

API Reference: Get Spending Prerequisites

Poll the Get Spending Prerequisites endpoint to wait for KYC checks to complete. The initial call to the endpoint when there is a new KYC statement for the cardholder will create a new KYC check and the endpoint will return "check_in_progress" for the KYC prerequisite status.

The endpoint will keep returning "check_in_progress" until the check is completed. Once the check is completed successfully, the response should contain "ok" status for the KYC prerequisite. However, if the check failed, the response will return "kyc_check_failed", along with an array listing the reasons for the failure. Check the KYC statement and submit it again or contact Immersve support.

Example request

curl -X POST "https://${imsv_api_host}/api/spending-prerequisites" \
  -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 '{
    "cardProgramId": "'${card_program_id}'",
    "fundingSourceId": "'${funding_source_id}'",
    "spendableAmount": 100,
    "spendableCurrency": "USD",
    "kycType": "partner-conducted"
  }'

Example response

{
  "prerequisites": [
    {
      "stage": "kyc",
      "status": "action-required",
      "type": "kyc",
      "actionType": "submit_kyc_statement",
      "params": {
        "status": "check_in_progress"
      }
    }
  ]
}