Card Funding

A Funding Source is a record of available balance against which card transactions are authorized. A Funding Source is owned by a cardholder and can be associated with many cards transacting against the same available balance. A Funding Source must have sufficient balance for a transaction to be authorized.

A Funding Source balance is eventually consistent with the on-chain deposits and withdrawals. However, the balance available to spend may differ. This could happen if deposit or load limits are exceeded. AML/CFT rules can dictate that the funds should not be included in the balance.

A card will not authorize transactions without an associated Funding Source. You must reference a Funding Source when creating a card.

Authentication

The authentication processes are described in the authentication guide.

Funding Source Provisioning

A Funding Source is created by a request to the create a Funding Source for an account endpoint. The funding wallet may be an EOA or a smart contract implementing the ERC-1271 interface.

Depositing Funds

On-chain funds deposits can be made any time regardless of card or Funding Source provisioning. A Funding Source can be loaded with digital assets without using Immersve APIs by depositing funds directly to our smart contract.

However, our APIs aim to reduce the complexity of determining what is the amount of digital assets needed to meet a users desired spend in their desired fiat currency. They also provide pre-built "smart-contract-write" transactions for successful interactions with the Immersve smart contract.

If multiple transactions are present then they should be carried out in the order in which they are presented.

The client application is responsible for creating the raw blockchain transaction so that it can be signed and submitted to the relevant blockchain through the cardholder's web3 wallet.

Withdrawing Funds

Withdrawals are conducted as a two-stage process:

1. Obtaining an Immersve-generated signature permitting a given withdrawal
2. Executing a withdrawal and observing the effect on the funding source

To begin the withdrawal process your application will create a withdrawal intent, providing the amount of the intended withdrawal and a reference to the relevant funding source.

Prior to returning a response, Immersve will identify the current blockchain nonce for the cardholder. The nonce is used to ensure only the intended withdrawal intent can be executed by the cardholder. The returned withdrawal intent is valid for the period indicated by the expiresAt property.

When a withdrawal intent is created, the relevant funding source balance is debited by the amount of the funding source interaction. The funding source interaction status will be "pending" at this time and will remain so until such time as the withdrawal intent is executed.

The cardholder may create further withdrawal intents to change the amount of the withdrawal prior to having executed it. If there are multiple withdrawal intents created with the same nonce, the funding source will be reduced by the amount of the highest withdrawal intent.

To execute a withdrawal the cardholder must submit the transaction contained in the execution property of the withdrawal intent prior to the expiresAt timestamp of the intent. Your application should prompt the cardholder to sign and submit the transaction. Upon observation of the the execution of the withdrawal intent on the blockchain, Immersve will update the status of the funding source interaction. Your application should query the List Funding Source Interactions endpoint, and inform the cardholder when the withdrawal status is no longer pending.

Withdrawal Intent Javascript Example

The create withdrawal intent endpoint creates a withdrawal intent for a given amount and returns the parameters needed to execute the withdrawal on the cardholder's web3 wallet.

const { abi, contractAddress, method, params } =
  response.data.execution.params;

const contract = new Contract(contractAddress, abi, signer); // third param Signer is required

const { hash } = await contract[method](...Object.values(params));

Currency Conversion

A user may be quoted a price for a purchase by a merchant in a local fiat currency. To determine the sufficient amount of local fiat currency to fund a card in its billing currency (USD), use the currency conversion endpoint.

The returned value can be passed to the get spending prerequisites endpoint as detailed below.

Prerequisites Execution Javascript Example

The get spending prerequisites endpoint returns an array of both regulatory and smart contract prerequisite transactions. Each object in the array has type and params. Type "smart_contract_write" means that this action is about interaction with the smart contract. params contains all the details required to perform this interaction.

const { abi, contractAddress, method, params } =
  response.data.prerequisites.params;

const contract = new Contract(contractAddress, abi, signer); // third param Signer is required

const { hash } = await contract[method](...Object.values(params));

Wallet Funding for Development and Testing

To ensure that integrators can obtain sufficient ERC-20 tokens to facilitate development and testing, Immersve uses an ERC-20 token contract that allows tokens to be freely minted as needed.

In non-production environments, any transaction returned by get spending prerequisites with actions related to ERC20 smart contract will refer to the "IMMUSDC" token. The "IMMUSDC" token has a mint function allowing for the unlimited minting of the token to any wallet address.

Polygonscan can be used to get the necessary tokens.

• Open the IMMUSDC token in Polygonscan
• Click Write as Proxy
• Click Connect to Web3 to connect your wallet with Polygonscan
• Open the mint function
• Set the destination wallet address (where assets are to be sent) in the to field. Set an amount in the amount field.
• Initiate the web3 transaction by clicking the Write button
• Confirm the transaction in the web3 wallet and pay the gas fees