Web3 Wallet Card Issuing Integration Guide

This guide details the steps to add Immersve card issuing capabilities into a non-custodial web3 wallet. It lists the API calls required to set up a partner, onboard users, and create and test a card, with card spending pre-funded through deposits to an on-chain contract.

If you have custody over your users' funds then the Custodial Card Issuing Integration Guide will provide a better starting point for your integration.

Before You Get Started

Verify Your Asset is Supported

Before you begin integrating ensure your chain and token combination is supported. See Supported Chains and Supported Tokens.

Select Funding Protocol

See the Funding Protocols guide to find which protocol would best suit your use case.

Select KYC Mode

Immersve Conducted KYC is the recommended KYC mode for non-custodial apps. If users have already been verified then Partner Conducted KYC may be an option.

Provision Application Resources

Set Up Your Partner Account

Contact support to get your: Partner Account ID, Client Application, API Key(s) and Card Program ID. You will initially have credentials to integrate with the Immersve test environment. When you are ready to test a live integration you will also receive live credentials.

Register a Funding Channel

You will need a funding channel per token and chain. See: Creating a Funding Channel.

Setup Environment

Install Dependencies

This guide uses bash, curl and jq for example API interactions.

Configure Variables

The following variables are referenced from the example bash scripts throughout this guide.

partner_account_id="<your_partner_account_id>"
card_program_id="<your_card_program_id>"
funding_channel_id="<your_funding_channel_id>"
kyc_redirect_url="<your_app_kyc_redirect_url>"
imsv_api_host=test.immersve.com
imsv_client_origin=https://your.domain

Immersve Environments

The Immersve test environment allows you to interact with all Immersve APIs while utilizing testnet assets. Test payments are initiated using the Payment Simulator. Note that the XPay capability is not available in the test environment.

Resource identifiers are not shared between the live and test environments. Your Partner Account, Client Application, API Keys and Card Program will all be different in the live environment.

Per cardholder setup

Deploy On-Chain Resources

Depending on the intended funding protocol there may be cardholder-scoped resources that can be deployed on chain before the cardholder has authenticated with Immersve APIs. For example, when using a Flexi variant of the Immersve card funding protocol, each cardholder will have their own deposit-holding contract deployed on-chain.

Login / Signup

Non-custodial integrations should use Immersve User Session authentication. Users shall be prompted to sign a login challenge message to authenticate with Immersve APIs and obtain access and refresh tokens.

Save the access token, refresh token, and cardholder account for later.

imsv_access_token="<access token from login response>"
imsv_refresh_token="<refresh token from login response>"
cardholder_account_id="<account from login response>"

Once a user is authenticated you will need to use the access token in the Authorization header of every API request.

Refresh Access Token

Access tokens expire after approximately 20 minutes. The refesh token can be sent to the Token Exchange endpoint to get a new access token without asking the user to re-authenticate.

tokens_json="$(
  curl -X POST "https://${imsv_api_host}/auth/token" \
  -H 'Content-Type: application/json' \
  -H "Origin: ${imsv_client_origin}" \
  --data '{
    "refreshToken": "'${imsv_refresh_token}'",
    "clientApplicationId": "'${imsv_client_id}'"
    }')"
imsv_access_token="$(echo $tokens_json | jq -r .accessToken)"
imsv_refresh_token="$(echo $tokens_json | jq -r .refreshToken)"

Select Region

Prompting the user to select their region helps them to avoid the card onboarding journey if their region is not yet available. Call the Get Supported Regions endpoint to get the current list of available regions for your application.

See: Supported Regions.

Register Cardholder Funding Source

Creating a Funding Source for a cardholder enables Immersve to attribute transactions to and from a funding address to the individual cardholders account.

funding_source_id=$(curl -X POST "https://${imsv_api_host}/api/funding-sources" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${imsv_access_token}" \
  --data '{
    "accountId": "'${cardholder_account_id}'",
    "fundingAddress": "'${wallet_address}'",
    "fundingChannelId": "'${funding_channel_id}'"
  }' | jq -r '.id')

If the funding address is not related to the user's login wallet address then first call the Create Challenge endpoint. The signed challenge can be used to prove ownership of the funding address. Include the "challengeId" and "signature" as additional parameters in the funding source request.

For more context and information on card funding and executing deposits and withdrawals see the Card Funding guide.

Complete Cardholder Onboarding

The spending prerequisites endpoint can be used to check whether the KYC and other requirements for a cardholder have been satisfied.

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

Note that "spendableAmount" is required. If the user has not yet been prompted for the amount to load into their Immersve card then any non-zero placeholder amount can be used.

The response will contain a prerequisite instruction like the following. Guide the user to open the "kycUrl" in a web browser so they can complete the Immersve KYC onboarding process. After onboarding is complete, the user will be redirected back to your "kycRedirectUrl".

Refer to Immersve Conducted KYC for more information.

{
  "stage": "kyc",
  "status": "action-required",
  "type": "kyc",
  "actionType": "follow_kyc_url",
  "params": {
    "status": "kyc_required",
    "kycUrl": "https://verify.immersve.com/session/wg92ikmc34ki"
  }
}

Request a Card

The Create Card, Get Card, and Get Card Token endpoints are all involved in requesting a card. See Issue a Virtual Card for further information.

Create a Card

Post the funding source ID and your provided card program ID to the card orders endpoint and record the returned card ID.

card_id=$(curl -X POST "https://test.immersve.com/api/cards" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${imsv_access_token}" \
  --data '{
    "cardProgramId": "'${card_program_id}'",
    "fundingSourceId": "'${funding_source_id}'"
  }' | jq -r .cardId)

Get Card Details

Call Get Card Details to see card status and ensure it is active.

curl -X GET "https://test.immersve.com/api/cards/${card_id}" \
  -H "Authorization: Bearer ${imsv_access_token}"

Get Sensitive Card Details

Card sensitive details are obtained by generating a unique time-limited token. The response contains a callback URL which can be used to obtain the sensitive card details. See Fetching Secure Card Information for more details.

curl -X POST "https://test.immersve.com/api/cards/${card_id}/pan-token" \
  -H "Authorization: Bearer ${imsv_access_token}"

Deposit Cardholder Funds

Before spending with a card, funds must be deposited to a funding source connected to the card. Use the Get Spending Prerequisites endpoint to get the correct Smart Contract write transaction for the specified amount, chain, and token.

For more information on executing deposits and withdrawals see the Card Funding guide.

curl -X POST "https://${imsv_api_host}/api/spending-prerequisites" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${imsv_access_token}" \
  --data '{
    "cardProgramId": "'${card_program_id}'",
    "fundingSourceId": "'${funding_source_id}'",
    "spendableAmount": 100,
    "spendableCurrency": "USD"
  }'

Check Card Balance

Verify that the balance is reflected on the Funding Source.

curl -X GET "https://${imsv_api_host}/api/accounts/${cardholder_account_id}/funding-sources" \
  -H "Authorization: Bearer ${imsv_access_token}"

Perform a Test Card Payment

Perform a card payment using the Immersve Payment Simulator. Call the simulator endpoint with the sensitive card details.

curl -X POST "https://${imsv_api_host}/api/simulator/authorize" \
  -H "Authorization: Bearer ${imsv_access_token}" \
  --data '{
    "transactionType": "purchase",
    "transactionAmount": "10",
    "cardPan": "1234567812345678",
    "cardExpiry": "202510",
    "cardCvv": "123"
  }'