Card Funding
A Funding Source is an off-chain 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. 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 claim a Funding Source for an account endpoint. The funding wallet may be an EOA or a smart contract implementing the ERC-1271 interface.
Funding Process
On-chain funding can be done at 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.
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 API endpoint.
The returned value can passed to the get spending prerequisites endpoint as detailed below.
Lock Funds
To ensure that funds are sufficiently locked within the smart
contract such that Immersve are in a position to
approve an authorization request received via the card scheme network you will
need to have first locked sufficient digital assets within the smart contract
via digital asset transfer and smart contract invocations as instructed by the
get spending prerequisites
operation. The necessary blockchain transactions are contained within the
prerequisites
collection returned.
If the user has not transacted using the solution before then the get spending
prerequisites response will
typically call for an ERC20 approve
in favour of the smart contract followed
by a depositAndLock
invocation of the 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 to parse and formulate the raw blockchain transaction message such that it is presented to the user within the web3 wallet and signed and sent to the relevant blockchain.
How to use prerequisites example for ts/js
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.
Code snippet (using ethers.js)
Typescript code
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.
One particularly convenient way to get the necessary tokens is to use the Polygonscan interface.
- 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 theamount
field. - Initiate the web3 transaction by clicking the
Write
button - Confirm the transaction in the web3 wallet and pay the gas fees