Skip to main content

Wallet Checkout API

Process payments using stablecoin wallets (USDC, USDT) for instant settlement and lower fees.

walletCheckout​

Process payments with existing customers using their connected stablecoin wallets.

const result = await easy.walletCheckout({
  identity_id: "existing_customer_identity_id",
  wallet_id: "wallet_12345",
  line_items: [{ price_id: "price_123", quantity: 1 }],
  customer_details: {
    first_name: "John",
    last_name: "Doe",
    email: "[email protected]",
  },
});

Parameters​

interface CreateWalletCheckout {
  identity_id: string; // Required: existing customer ID
  wallet_id: string; // Required: wallet ID for payment
  line_items: LineItem[]; // Required: items to purchase
  customer_details?: {
    // Optional: customer info update
    first_name?: string;
    last_name?: string;
    email?: string;
    phone?: string;
  };
  metadata?: Record<string, string>; // Optional: custom order data
}

interface LineItem {
  price_id: string; // One-time purchase price only
  quantity: number;
}

Returns​

Promise<
  ApiResponse<{
    order: OrderData & { solana_signature: string };
    transation: {
      signature: string;
      token_amount: number;
      explorerUrl: string;
    };
  }>
>;

Examples​

Basic Wallet Checkout​

import { createClient } from "@easylabs/node";

const easy = await createClient({
  apiKey: process.env.EASY_API_KEY!,
});

const result = await easy.walletCheckout({
  identity_id: "existing_customer_identity_id",
  wallet_id: "wallet_12345",
  line_items: [
    { price_id: "price_123", quantity: 2 },
    { price_id: "price_456", quantity: 1 },
  ],
  customer_details: {
    first_name: "John",
    last_name: "Doe",
    email: "[email protected]",
    phone: "+1234567890",
  },
  metadata: {
    payment_method: "wallet",
    order_source: "web",
  },
});

Minimal Wallet Checkout​

const result = await easy.walletCheckout({
  identity_id: "identity_67890",
  wallet_id: "wallet_54321",
  line_items: [{ price_id: "price_def456", quantity: 2 }],
});

Express.js Server Example​

import { createClient } from "@easylabs/node";
import express from "express";

const app = express();
app.use(express.json());

const easy = await createClient({
  apiKey: process.env.EASY_API_KEY!,
});

app.post("/api/wallet-checkout", async (req, res) => {
  try {
    const { identityId, walletId, lineItems, customerDetails } = req.body;

    const result = await easy.walletCheckout({
      identity_id: identityId,
      wallet_id: walletId,
      line_items: lineItems,
      customer_details: customerDetails,
      metadata: {
        payment_method: "wallet",
        source: "api",
      },
    });

    if (result.success) {
      res.json({
        success: true,
        orderId: result.data.orderId,
        walletTransactionId: result.data.walletTransactionId,
      });
    } else {
      res.status(400).json({ error: "Wallet checkout failed" });
    }
  } catch (error) {
    console.error("Wallet checkout error:", error);
    res.status(500).json({ error: "Internal server error" });
  }
});

app.listen(3000, () => {
  console.log("Server running on port 3000");
});

Benefits​

Wallet Advantages
  • Instant Settlement: Payments settle immediately on-chain
  • Lower Fees: Significantly reduced processing costs compared to traditional cards
  • Global Access: Accept payments from anywhere with stablecoin support
  • Transparency: All transactions are verifiable on the blockchain

Important Limitations​

Current Restrictions
  • Existing Customers Only: Requires an existing customer (identity_id)
  • No Customer Creation: Customer creation is not supported during wallet checkout
  • One-time Purchases Only: Subscriptions are not currently supported
  • Connected Wallets: Customer must have a connected wallet (wallet_id)

Error Handling​

try {
  const result = await easy.walletCheckout({
    identity_id: customerId,
    wallet_id: walletId,
    line_items: lineItems,
  });

  // Handle success
  console.log("Order ID:", result.data.orderId);
} catch (error) {
  if (error.code === "WALLET_INSUFFICIENT_FUNDS") {
    // Handle insufficient wallet balance
  } else if (error.code === "WALLET_NOT_CONNECTED") {
    // Handle wallet connection issues
  } else {
    // Handle other errors
    console.error("Checkout failed:", error);
  }
}
  • Checkout API - For traditional card and bank account payments