Immersve Docs
Github X

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).

How It Works

  • Enable Partner Conducted KYC
    This is subject to an agreement between Immersve and the partner. Ask Immersve support for more details. Partner Conducted KYC is not currently supported in all regions.

  • Partner app presents any legal documents during consent
    See Presenting Legal Documents.

  • Partner app collects the data
    Partner app collects and verifies the KYC information from cardholders

  • Partner sends KYC data to Immersve
    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.

  • Ongoing monitoring
    Ongoing AML/CFT checks are performed by Immersve. If Immersve already has complete KYC information for the individual owning the wallet, for the requested region the user will not be required to go through KYC.

Integration Steps

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

Terminal window
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"
Environment variables used by the curl examples that follow.

Supply 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

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

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
Terminal window
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}'"
      }
    }'
Example curl supplying the cardholder's email and phone contact details.

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
Terminal window
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}'"
  }'
Example curl supplying the cardholder's expected monthly spend amount.

Upload Supporting Documents

API Reference: Upload File

Some regions require supporting documents (a passport scan, a selfie, a data source export, etc.) to accompany the KYC Statement. Upload each document with the Upload File endpoint to receive a file id, then reference those IDs from the statement — see Attaching Supporting Documents for the full list of mandatory regions and attachment types.

Terminal window
curl -X POST "https://${imsv_api_host}/api/file-uploads" \
  -H "Content-Type: multipart/form-data" \
  -H "x-api-key: ${card_issuer_api_key}" \
  -H "x-api-secret: ${card_issuer_api_secret}" \
  -F 'purpose="kyc-doc-upload"' \
  -F "accountId=${cardholder_account_id}" \
  -F 'file=@"/path/to/passport-scan.jpg"'
Example curl uploading a supporting KYC document and receiving a file ID.

The response contains an id field — use that value as the fileId when attaching the document to a KYC Statement.

Submit Cardholder KYC Statement

API Reference: Submit Kyc Statement

A KYC Statement captures a cardholder's region plus the claims and evidence that verify their identity. At least one piece of evidence is required, and every request must include an idempotency key so retries don't create duplicate statements. Some regions also require supporting documents.

The available claim types, evidence types, and any mandatory attachments vary by region — see Supported Regions.

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 script submits a minimal KYC statement with a residence permit as evidence. See the Full Statement Example below for a request that exercises every claim type and an attachments array.

Terminal window
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.


date_of_birth="" # YYYY-MM-DD
your_given_name=""
your_family_name=""


residence_permit_number=""
residence_permit_country="" # ISO 3166-2 Country Code
residence_permit_expiry="" # 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": {
          "givenName": "'${your_given_name}'",
          "familyName": "'${your_family_name}'"
        }
      }
    ],
    "evidence": [
      {
        "evidenceType": "RESIDENCE_PERMIT",
        "documentId": "'${residence_permit_number}'",
        "country": "'${residence_permit_country}'",
        "expiry": "'${residence_permit_expiry}'"
      }
    ]
  }'
Example curl submitting a minimal partner-conducted KYC statement with a residence permit.

Claim Types

Claims are the structured attributes of the cardholder's identity included on a KYC Statement. Every statement must carry a Date Of Birth, Full Name, and Residential Address claim.

Date Of Birth

The cardholder's date of birth in YYYY-MM-DD format.

{
  "claimType": "DOB",
  "attributes": {
    "dateOfBirth": "1990-04-23"
  }
}
Example date-of-birth claim on a KYC statement.

Full Name

The cardholder's legal name. givenName and familyName are required; the optional honorific and middleName fields are accepted where they apply.

{
  "claimType": "FULL_NAME",
  "attributes": {
    "honorific": "Ms", // optional
    "givenName": "Alex",
    "middleName": "Jordan", // optional
    "familyName": "Taylor"
  }
}
Example full-name claim on a KYC statement.

Residential Address

The cardholder's residential address, accepted in either structured or unstructured form — see Address Formatting for the field-by-field detail. A structured example:

{
  "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"
  }
}
Example structured residential-address claim on a KYC statement.

Supported Evidence Types

Evidence is the identity document or documents that back the claims on a KYC Statement. At least one piece of evidence is required, and multiple types can be combined into a single request. The accepted types vary by region — see Supported Regions.

Passport

A government-issued passport identifying the cardholder.

{
  "evidenceType": "PASSPORT",
  "documentId": "DS230475", // passport number
  "country": "NZ", // ISO 3166-2 Country Code
  "expiry": "2028-10-12" // YYYY-MM-DD
}
Example passport evidence on a KYC statement.

Driver's License

A government-issued driver's license. Some jurisdictions also require a region (state or province) and a version number.

{
  "evidenceType": "DRIVERS_LICENSE",
  "documentId": "DS230475", // license number
  "country": "AU", // ISO 3166-2 Country Code
  "region": "VIC", // See submit KYC statement docs for more info
  "version": "978",
  "expiry": "2028-10-12" // YYYY-MM-DD
}
Example driver's license evidence on a KYC statement.

National ID

A government-issued national identity card. The paternalFamilyName and maternalFamilyName fields are only applicable to Mexican (MX) IDs.

{
  "evidenceType": "NATIONAL_ID",
  "documentId": "S1234567A", // national ID number
  "country": "MX", // ISO 3166-2 Country Code
  "paternalFamilyName": "Garcia", // Only applicable for MX
  "maternalFamilyName": "Lopez", // Only applicable for MX
  "expiry": "2028-10-12" // YYYY-MM-DD
}
Example national ID evidence on a KYC statement.

Residence Permit

A residence permit issued to the cardholder by the country they live in.

{
  "evidenceType": "RESIDENCE_PERMIT",
  "documentId": "DS230475", // residence permit number
  "country": "CO", // ISO 3166-2 Country Code
  "expiry": "2028-10-12" // YYYY-MM-DD
}
Example residence permit evidence on a KYC statement.

Address Formatting

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

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.

Structured Addresses

Organizes address details into predefined fields, making it easier to validate and process the data. Partners are strongly encouraged to use this format whenever possible.

{
  "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"
  }
}
Example structured address claim payload.

Unstructured Addresses

When it is not possible to provide a Structured Addresses, partners may be able to provide an Unstructured Address. This format consolidates the address into a single text string in the fullAddress field, which Immersve later attempts to parse into structured address components.

{
  "claimType": "ADDRESS",
  "attributes": {
    "addressType": "RESIDENTIAL",
    "fullAddress": "2/45 Laddier Road, Centurion, The Reeds, Auckland, Auckland 0100, New Zealand",
    "country": "NZ"
  }
}
Example unstructured address claim payload.

Unstructured addresses are only allowed for the following regions: AR, AT, AU, BE, BG, BR, CA, CH, CL, CO, CZ, DE, DK, EE, ES, FI, FR, GB, HR, HU, IE, IT, LT, LU, LV, MX, MY, NL, NO, NZ, PL, PR, PT, SE, SG, SI, SK, US.

The list of supported regions, including whether each region allows this format, can be retrieved using the Get Supported Regions endpoint.

Attaching Supporting Documents

Supporting documents can be attached to the KYC Statement for any region, but are mandatory for the following regions: AT, BE, BG, CY, CZ, DE, DK, EE, ES, FI, FR, GR, HR, HU, IE, IS, IT, LI, LT, LU, LV, MT, NL, NO, PL, PT, RO, SE, SI, SK, UK.

The following supporting documents can be attached to the KYC statement:

  1. Self image for liveness checks
  2. Identity document
  3. Proof of address document (depending on the region)
  4. Document containing info about what datasources were used to perform partner checks (attachment type: data-source)

Supporting documents must be first uploaded using the Upload File endpoint for each document before being attached to the statement using their file IDs and the appropriate attachment type.

{
    "attachments": [
      {
        "fileId": "f4b8e8ef0d230d0a6bf755e07d39ab12",
        "type": "passport"
      },
      {
        "fileId": "a1c9e8ef0d230d0a6bf755e07d39cd34",
        "type": "self-image"
      }
    ]
  }
Example attachments array referencing uploaded supporting documents.

Monitor KYC Evaluation Process

For detailed guidance on detecting KYC completion, see Detecting KYC Completion.

Testing KYC in Test Mode

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

Full Statement Example

The following script submits a fully-populated KYC Statement: DOB, Full Name, and a structured Residential Address claim, a passport as evidence, and two supporting documents referenced by the file IDs returned from Upload Supporting Documents.

Terminal window
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.


passport_file_id="" # id returned from /api/file-uploads for the passport scan
selfie_file_id=""   # id returned from /api/file-uploads for the selfie


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": "1990-04-23"
        }
      },
      {
        "claimType": "FULL_NAME",
        "attributes": {
          "honorific": "Ms",
          "givenName": "Alex",
          "middleName": "Jordan",
          "familyName": "Taylor"
        }
      },
      {
        "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"
        }
      }
    ],
    "evidence": [
      {
        "evidenceType": "PASSPORT",
        "documentId": "DS230475",
        "country": "NZ",
        "expiry": "2028-10-12"
      }
    ],
    "attachments": [
      {
        "fileId": "'${passport_file_id}'",
        "type": "passport"
      },
      {
        "fileId": "'${selfie_file_id}'",
        "type": "self-image"
      }
    ]
  }'
Example curl submitting a fully populated partner-conducted KYC statement.