Custodial On-Chain Card Issuing Integration Guide

This guide details the steps to add Immersve card issuing capabilities into applications that have custody of user funds. 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 do not have custody over your users' funds then the Web3 Wallet 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

Partner Conducted KYC is the recommended KYC mode for custodial apps that have already verified their users. If users have not already been verified then Immersve Conducted KYC can be used.

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.

card_issuer_api_key="<your_card_issuer_api_key>"
card_issuer_api_secret="<your_card_issuer_api_secret>"
partner_account_id="<your_partner_account_id>"
card_program_id="<your_card_program_id>"
funding_channel_id="<your_funding_channel_id>"
imsv_api_host=test.immersve.com

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

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.

Create a Cardholder Account

Provision each cardholder with an account and save their ID. In the custodial case it is assumed that you have gained permission to act on the cardholders behalf. All cardholder resources on our platform will be fully owned by your app. Each request on a cardholder resource must specify the cardholder by referencing the cardholder ID in the headers as specified in the Authentication Guide.

cardholder_account_id=$(curl \
  -X POST "https://${imsv_api_host}/api/accounts" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${card_issuer_api_key}" \
  -H "X-Api-Secret: ${card_issuer_api_secret}" \
  --data '{
    "parentAccountId": "'${partner_account_id}'",
    "type": "cardholder",
    "name": "<e.g. Cardholder Account of Joe>"
  }' | jq -r .id)

Prove Ownership of Web3 Address

In order to prove ownership of the respective EOA (Externally owned account), sign a challenge message using the EOA's private key. Use an address that you control and would like to use to fund a user's card(s). To learn more about web3 message signing, checkout Etherscan, Eth Signer and Ethers.js.

wallet_address="<wallet_address>"

response=$(curl -X POST "https://${imsv_api_host}/api/challenges" \
  -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 '{
    "purpose": "claim-web3-address",
    "network": "<network name e.g polygon-amoy>",
    "address": "'${wallet_address}'"
  }')

challenge_id=$(echo $response | jq -r '.id')
message=$(echo $response | jq -r '.message')

echo "Message:${message}"

Register Cardholder Funding Source

Creating a Funding Source for a cardholder enables Immersve to attribute transactions from a funding address to individual cardholders. The "signature" parameter is the signature of the signed message from the previous step. For more context and information on card funding and executing deposits and withdrawals see the Card Funding guide.

signature="<signature hash of cardholder signing the challenge message with their wallet>"

funding_source_id=$(curl -X POST "https://${imsv_api_host}/api/funding-sources" \
  -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 '{
    "accountId": "'${cardholder_account_id}'",
    "fundingAddress": "'${wallet_address}'",
    "fundingChannelId": "'${funding_channel_id}'",
    "signature": "'${signature}'",
    "challengeId": "'${challenge_id}'"
  }' | jq -r '.id')

Get KYC and Contact Details Prerequisites

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

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

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.

Supply KYC Details

KYC requirements need to be completed before a cardholder obtains a card. If your application has already captured user KYC details then you may be able to use Partner Conducted KYC. Otherwise, Immersve Conducted KYC should be used.

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://${imsv_api_host}/api/cards" \
  -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}'"
  }' | jq -r .cardId)

Get Card Details

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

curl -X GET "https://${imsv_api_host}/api/cards/${card_id}" \
  -H "X-Api-Key: ${card_issuer_api_key}" \
  -H "X-Api-Secret: ${card_issuer_api_secret}" \
  -H "X-Account-Id: ${cardholder_account_id}"

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://${imsv_api_host}/api/cards/${card_id}/pan-token" \
  -H "X-Api-Key: ${card_issuer_api_key}" \
  -H "X-Api-Secret: ${card_issuer_api_secret}" \
  -H "X-Account-Id: ${cardholder_account_id}"

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

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 "X-Api-Key: ${card_issuer_api_key}" \
  -H "X-Api-Secret: ${card_issuer_api_secret}" \
  -H "X-Account-Id: ${cardholder_account_id}"

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 "X-Api-Key: ${card_issuer_api_key}" \
  -H "X-Api-Secret: ${card_issuer_api_secret}" \
  -H "X-Account-Id: ${cardholder_account_id}"
  --data '{
    "transactionType": "purchase",
    "transactionAmount": "10",
    "cardPan": "1234567812345678",
    "cardExpiry": "202510",
    "cardCvv": "123"
  }'