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, and you can point the card at a different Funding Source later without reissuing it.
Authentication
The authentication processes are described in the Authentication guide.
Funding Source Provisioning
A Funding Source is created by a request to the Create Funding Source endpoint. The funding wallet may be an EOA or a smart contract implementing the ERC-1271 interface.
Changing a Card's Funding Source
Call the Set Card Funding Sources endpoint to point an existing card at a different Funding Source owned by the same cardholder.
The change applies to that card alone. Other cards belonging to the cardholder keep the Funding Sources they are already linked to.
Payments in Flight
Changing a card's Funding Source takes effect immediately. Funds are always taken from the card's current Funding Source, whatever stage of the Payment Lifecycle the payment has reached. A single payment can therefore involve more than one Funding Source — whenever a payment takes further funds, such as an incremental authorization or a clearing for more than the amount authorized, those funds come from the card's current Funding Source rather than the one that authorized the payment.
Funds returned to the cardholder go back to the Funding Source they were taken from. A reversal, an expired authorization, and a clearing for less than the amount authorized all release funds on the Funding Source that was drawn from, normally the one that authorized the payment. When returned funds cannot be traced to an earlier payment, they are credited to the card's current Funding Source instead. A merchant refund carries no reliable link to the purchase it refunds, so it is credited that way.
Spending Prerequisites
Spending prerequisites are divided into funding, KYC, and AML stages. Only the funding stage is tied to a Funding Source, and it is satisfied per Funding Source: changing a card's Funding Source carries nothing over from the previous one. The KYC and AML stages unaffected by changing funding sources.
Call the Get Spending Prerequisites endpoint to retrieve spending prerequisites. A card pointed at a Funding Source with outstanding funding prerequisites cannot authorize transactions.
Reissuance Chains
Reissuance links a successor card to its predecessor in a chain sharing a seriesId, described in the Card Lifecycle guide. Each card in a chain holds its own Funding Sources, so a change made to one card does not propagate along the chain.
A successor card takes its Funding Sources from the predecessor card at the time the Reissue Card endpoint is called. Changing the predecessor's Funding Source after that point leaves the successor card on the Funding Source it was created with.
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 the deposit-holding address relating to the Funding Source.
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:
- Obtaining an Immersve-generated signature permitting a given withdrawal
- Executing a withdrawal and observing the effect on the funding source
To begin the withdrawal process your application will call Create 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 a list of checks that must be passed before the cardholder can spend with the provided funding source. Funding prerequisites, when not completed, will have action type and params attributes which indicate how to satisfy the prerequisite. The value of the type attribute will depend on the funding protocol in use. For example, an action type of "smart_contract_write" indicates that an EVM smart contract interaction is required.
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));