Card Funding and Settlement

Learn how Rain embedded wallets fund card spend through collateral contracts, including funding, withdrawals, and settlement.

Applies to: Rain-managed

In Rain managed programs, each cardholder or company has a collateral contract owned by their registered wallet. Users transfer funds from their wallet into the contract to fund card spending. Rain manages transaction authorization and settlement, while users retain control of their wallets.

This guide covers the full process, from registering a wallet and creating a collateral contract to funding card spend and withdrawing collateral.

Implementation steps are labeled App for actions performed through the embedded wallet SDK and Backend for requests made to the Rain API using your API key.

For partner managed programs, see Flow of funds.

Card funding workflow

1. Create the wallet

   App The user logs in for the first time and the wallet is created. Read its addresses and send them to your backend.

   let evm = try await client.getWalletAddress()
   let sol = try await client.getWalletAddress(chainId: RainChain.solanaMainnet)   // if you fund on Solana
   

   See Wallet creation.

2. Create the application with the wallet address

   Backend Create the user’s consumer application with walletAddress (and solanaAddress where relevant), then run KYC as usual. For a corporate program, the wallet goes on initialUser.walletAddress of the company application.

   POST /v1/issuing/applications/user
   { "...": "...", "walletAddress": "0x3cA8…C0Ff", "solanaAddress": "7Np4…T4K2" }
   

   Full schemas: Create a consumer application, Create a corporate application.

3. Receive the collateral contract

   Backend When the application is approved, Rain deploys the user’s collateral contract on your program’s chain and sends contract.created. The wallet on the application is the contract’s owner and appears in adminAddresses. You can read the contract at any time:

   GET /v1/issuing/users/{userId}/contracts
   

   Response (abbreviated)

   [{
     "id": "cc_abc123",
     "chainId": 8453,
     "proxyAddress": "0xabcd…ef12",
     "controllerAddress": "0x9876…5432",
     "depositAddress": "0xfedc…ba09",
     "adminAddresses": ["0x3cA8…C0Ff"],
     "tokens": [{ "address": "0x8335…2913", "balance": "0", "exchangeRate": 1, "advanceRate": 0.9 }]
   }]
   

   The tokens entries carry no symbol or decimals. Resolve them in the app with rain.tokenMetadata(chainId:address:), which returns nil rather than guessing when the decimals can’t be established.

4. Fund the contract from the wallet

   Backend Hand the app the contract’s depositAddress (or proxyAddress when no deposit address is returned) and the accepted token addresses.

   App Funding is an ordinary token send from the wallet to that address, so it inherits everything from Sending funds, including gas sponsorship.

   iOS

   let result = try await client.sendToken(
       chainId: contract.chainId,
       contractAddress: usdcOnBase,
       to: contract.depositAddress ?? contract.proxyAddress,
       amount: 250
   )
   

   Users can also fund the contract from anywhere else (an exchange withdrawal straight to the deposit address, for example); the wallet is the convenient path, not the only one.

   Only tokens listed on the contract count as collateral; send anything else there and it neither funds the card nor comes back through the withdrawal flow. Check tokens before offering a token in the funding UI.

5. Watch spending power update

   Backend Rain detects the deposit and sends a transaction.created webhook of type collateral. Spending power updates within minutes; read it with GET /v1/issuing/users/{userId}/balances and show it in the app next to the wallet balance. Neither the wallet balance nor the on-chain contract balance is the spending limit; the balances endpoint is.

6. Issue the card and spend

   Backend Create the card with POST /v1/issuing/users/{userId}/cards. From here the wallet isn’t involved in a purchase: Rain authorizes each transaction against the user’s spending power, settles with the network by liquidating collateral from the contract, and keeps the ledger. You consume transaction.created, transaction.updated, and transaction.completed webhooks to show card activity; there’s no approval webhook to build. See Transaction lifecycle and Managing collateral.

7. Withdraw remaining collateral

   Backend + App The user takes collateral back out by signing a withdrawal with the wallet, authorized by a signature your backend fetches from Rain. Details below.

Withdrawals

Users can withdraw available collateral from their collateral contract to any recipient address. Each withdrawal requires two authorizations: Rain approves the amount available for withdrawal through an admin signature, and the contract’s owner wallet signs the transaction.

Your backend retrieves Rain’s admin signature, while your app uses the wallet SDK to sign and submit the withdrawal.

1. Fetch the admin signature

   Backend Request a signature for the exact withdrawal: chain, token, amount in the token’s base units, the admin (the user’s wallet address), and the recipient.

   GET /v1/issuing/users/{userId}/signatures/withdrawals
       ?chainId=8453
       &token=0x8335…2913
       &amount=100000000            # 100 USDC in base units
       &adminAddress=0x3cA8…C0Ff    # the user's wallet
       &recipientAddress=0x3cA8…C0Ff
       &isAmountNative=true
   

   Response

   {
     "status": "ready",
     "signature": { "salt": "0x…", "data": "0x…" },
     "expiresAt": "1727000000"
   }
   

   A pending status with retryAfter means Rain is still computing it; wait and retry. Treat anything other than ready with non-empty signature.data as not ready. Return the signature and the contract’s proxyAddress and controllerAddress to the app. Full reference: Get withdrawal signature for a user.

2. Execute the withdrawal

   App Assemble the addresses and the signature and call withdrawCollateral. The SDK checks that the wallet is an admin of the contract before signing (RAIN_407 otherwise), signs, and broadcasts. On EVM chains it returns the transaction hash; on Solana, the transaction signature.

   iOS

   let addresses = RainWithdrawAddresses(
       proxyAddress: contract.proxyAddress,
       controllerAddress: contract.controllerAddress,
       tokenAddress: usdcOnBase,
       recipientAddress: try await client.getWalletAddress()   // back to the wallet, or anywhere
   )
   let adminSignature = RainAdminSignature(
       salt: response.signature.salt,
       signature: response.signature.data,
       expiresAt: response.expiresAt
   )
   
   let txHash = try await client.withdrawCollateral(
       chainId: contract.chainId,
       addresses: addresses,
       amount: 100,
       decimals: 6,                     // from rain.tokenMetadata(chainId:address:)
       adminSignature: adminSignature
   )
   

   amount and decimals must reproduce the exact base-unit amount the signature was issued for. Pass the token’s real decimals; on Solana they aren’t checked against the mint.

Quoting the fee and preparing without broadcasting

estimateWithdrawalFee quotes the withdrawal’s network cost in the chain’s native currency (EVM only). Because a withdrawal is an EIP-712-signed call, estimating from scratch asks the wallet to sign; to quote without a second signature, prepare once and estimate on the result:

let prepared = try await client.prepareWithdrawal(
    chainId: contract.chainId, addresses: addresses, amount: 100, decimals: 6, adminSignature: adminSignature
)
let fee = try await client.estimateWithdrawalFee(chainId: contract.chainId, prepared: prepared)

prepareWithdrawal also serves apps that broadcast themselves: prepared.evmParameters holds the signed transaction parameters, and prepared.solanaTransfer the unsigned Solana transfer, without anything being sent. Preparation works on every chain, including the chains the Rain wallet can’t broadcast on, so it’s the path for a program funding on Avalanche while sends there are pending. With gas sponsorship on, the fee estimate is informational; the user doesn’t pay it.

Withdrawal errors

Error	Meaning	What to do
RAIN_407 walletNotAuthorized	The wallet isn’t an admin of the contract; the SDK checked before signing	The application was created with a different wallet, or the owner was changed. See below
RAIN_405 withdrawalRevertedByNetwork	The contract rejected the withdrawal on-chain, usually a reused signature after the same amount was withdrawn recently	Fetch a fresh signature; if the user retries the same amount immediately, reuse the signature you already have rather than requesting another
RAIN_104 chainNotSupported	The contract is on a chain the Rain wallet can’t broadcast on	Use prepareWithdrawal and broadcast yourself, or fund on a send-capable chain
RAIN_402 insufficientFunds	With sponsorship off, the wallet lacks native currency for gas	Show the shortfall

A signature is bound to one (token, amount, recipient) and is consumed by a successful broadcast. Cache it with those inputs so a retry after a transient failure reuses it; a different amount needs a new one.

Changing the owner wallet

The contract’s owner is fixed at deployment from the address on the application. Changing it today is a two-step operation your backend runs against the Rain API, described in Update a user’s wallet address: add the new wallet as an admin on every EVM collateral contract the user has, then PATCH /v1/issuing/users/{userId} with the new walletAddress. Rain verifies the new wallet is an admin on all of the user’s EVM contracts and returns 423 Locked when it isn’t.

This matters for the Rain wallet in one scenario: a user who signs up again with a different contact gets a new account and therefore a new wallet, and withdrawals from their existing contract fail with RAIN_407. Avoid it by steering returning users to log in rather than sign up (see Authentication options), and handle it, when it happens, by changing the owner to the new wallet.

Coming at GA: SDK calls to set and change the collateral contract’s owner wallet from the app, so this no longer requires a manual admin step.

Corporate programs

The flow is the same with the company in place of the user. The initial user’s wallet goes on the corporate application and becomes the owner of the company’s contract; additional contracts on other chains can be created with POST /v1/issuing/companies/{companyId}/contracts, which takes an explicit ownerAddress. Cards for the company’s members all spend from the company contract, and the owner wallet funds and withdraws it exactly as above, using the company variants of the endpoints (contracts, withdrawal signature).

Real-time funding from the wallet

Where your tenant has Real-time funding enabled, pre-funding the contract becomes optional: the user approves Rain’s operator once as a spender of the supported asset in their wallet, and at authorization time Rain pulls the purchase amount from the wallet into the contract before approving. It is available to Rain-managed programs only, on the assets and chains listed in the Real-time funding guide. A decline for insufficient spending power results when the wallet lacks the asset, the allowance is too low, or the pull fails within the authorization window.

Real-time funding is in beta; the wallet-side approval steps for the SDK are documented as it goes live. Follow the Real-time funding guide for the current prerequisites and operator addresses.

What’s next

Flow of funds

Rain-managed vs partner-managed, and what changes for the wallet.

Transaction webhooks and history

The events your backend receives along this flow.

Testing

Run the whole flow against the sandbox.