Issue Your First Card

Create a card for an approved customer, fund it, decrypt the card details, and make a test purchase.

This quickstart takes an approved customer from card creation to a funded, spendable card: create the card, fund it based on your management model, and decrypt the card details for the cardholder.

Before you begin

Complete the shared setup steps: get your API keys, configure webhooks, and get your customer through compliance approval. You’ll also need to know your program type and management model, since it determines how you fund the card.

1. Issue a Card

   Create a virtual or physical card for the approved user by calling the Create a Card endpoint.

   • Virtual cards are available immediately but require client-side decryption to display the PAN
   • Physical cards require a shipping address and activation after delivery

   See Issuing Cards for configuration options and spending limits. See Push Provisioning steps to allow users to add their card to Apple Wallet or Google Wallet directly from your app.

   Virtual

   const card = await client.users.createCard(userId, {
     type: 'virtual',
   });
   
2. Fund the Card

   How you fund the card depends on your management model:

   Rain-Managed

   1. Retrieve the user’s smart contract address via Get Contract Info
   2. Send supported tokens (for example, USDC) directly to the contract on-chain
   3. The credit limit updates automatically once the deposit is confirmed

   See Rain-Managed Programs for detailed instructions and code examples. See Supported Chains & Tokens for the full list of supported networks.

   retrieveContractAddress.ts

   // One contract per chain, in no particular order. The list is empty while contracts deploy.
   const contracts = await client.users.retrieveContracts(userId);
   const contract = contracts.find((c) => c.chainId === 84532);
   
   if (!contract?.depositAddress) {
     throw new Error('Deposit address not yet available for this contract');
   }
   
   // Send supported tokens (for example, USDC) to this address on the specified chain
   console.log(`Deposit to: ${contract.depositAddress}`);
   console.log(`Chain ID: ${contract.chainId}`);
   // contract.tokens lists accepted ERC-20 tokens and their on-chain addresses
   

   84532 is Base Sepolia, the sandbox chain. Use the chain ID of the network you’re funding on.

   Partner-Managed

   Add collateral to your account through the Dashboard by clicking Add tokens. You can fund via wallet or Safe.

   See Partner-Managed Programs for payment options and balance management.

3. Decrypt and Use the Card

   For virtual cards, decrypt the card PAN on the client side so the cardholder can start spending. Rain uses RSA-OAEP encryption for card data.

   See Viewing Encrypted Card Details for the decryption implementation guide.

   decryptCardSecrets.ts

   import crypto from 'crypto';
   
   // RAIN_PUBLIC_KEY: environment-specific PEM key from /docs/resource-sessionid-keys
   const RAIN_PUBLIC_KEY = process.env['RAIN_PUBLIC_KEY'];
   
   // 1. Generate a random session key
   const sessionKey = crypto.randomBytes(32);
   
   // 2. Encrypt it with Rain's RSA public key (OAEP padding)
   const encryptedSessionId = crypto.publicEncrypt(
     { key: RAIN_PUBLIC_KEY, padding: crypto.constants.RSA_PKCS1_OAEP_PADDING },
     sessionKey,
   ).toString('base64');
   
   // 3. Fetch the encrypted card secrets
   //    Note: the param is `SessionId` (capital S, capital I)
   const secrets = await client.cards.retrieveSecrets(card.id, {
     SessionId: encryptedSessionId,
   });
   
   // secrets.encryptedPan → { data: string, iv: string }
   // secrets.encryptedCvc → { data: string, iv: string }
   // Decrypt both fields with sessionKey using AES
   
4. Make a Test Purchase

   In sandbox, simulate a purchase on the card to confirm it can spend. The card must be active (activate physical cards first). Call POST /simulate/transactions/authorize with the card’s id:

   curl -X POST "https://api-dev.rain.xyz/v1/simulate/transactions/authorize" \
     -H "Api-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "cardId": "YOUR_CARD_ID",
       "amount": 500,
       "currency": "USD",
       "merchantName": "Coffee Shop",
       "merchantCategoryCode": "5814"
     }'
   

   A status of authorized means the card works end to end, and your webhook endpoint receives transaction.requested and transaction.created. If you get declined with account_credit_limit_exceeded, the funding from the previous step hasn’t landed yet.

   See Simulating Transactions to settle, reverse, and refund the purchase.

What’s next

Testing in Sandbox

Simulate transactions and test your integration before going live.

Transaction Lifecycle

Understand how transactions flow from authorization to settlement.

Managing Transactions

View, authorize, and manage cardholder transactions.