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 { walletCheckout } = useEasy();

const result = await 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 Payment

import { useEasy } from "@easylabs/react";
import { useState } from "react";

function WalletCheckout() {
  const { walletCheckout } = useEasy();
  const [loading, setLoading] = useState(false);
  const [walletId, setWalletId] = useState("");
  const [formData, setFormData] = useState({
    first_name: "",
    last_name: "",
    email: "",
    phone: "",
  });

  const handleSubmit = async (e) => {
    e.preventDefault();
    setLoading(true);

    try {
      const result = await walletCheckout({
        identity_id: "existing_customer_identity_id", // Required: existing customer only
        wallet_id: walletId,
        line_items: [{ price_id: "price_123", quantity: 1 }],
        customer_details: {
          first_name: formData.first_name,
          last_name: formData.last_name,
          email: formData.email,
          phone: formData.phone,
        },
        metadata: {
          payment_method: "wallet",
          order_source: "web",
        },
      });

      console.log("Wallet checkout successful:", result.data);
    } catch (error) {
      console.error("Wallet checkout failed:", error);
    } finally {
      setLoading(false);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        value={formData.first_name}
        onChange={(e) =>
          setFormData({ ...formData, first_name: e.target.value })
        }
        placeholder="First Name"
      />
      <input
        type="text"
        value={formData.last_name}
        onChange={(e) =>
          setFormData({ ...formData, last_name: e.target.value })
        }
        placeholder="Last Name"
      />
      <input
        type="email"
        value={formData.email}
        onChange={(e) => setFormData({ ...formData, email: e.target.value })}
        placeholder="Email"
      />
      <input
        type="tel"
        value={formData.phone}
        onChange={(e) => setFormData({ ...formData, phone: e.target.value })}
        placeholder="Phone"
      />
      <input
        type="text"
        value={walletId}
        onChange={(e) => setWalletId(e.target.value)}
        placeholder="Wallet ID"
        required
      />
      <button type="submit" disabled={loading}>
        {loading ? "Processing..." : "Pay with Wallet"}
      </button>
    </form>
  );
}

Minimal Wallet Payment

import { useEasy } from "@easylabs/react";
import { useState } from "react";

function MinimalWalletCheckout({ identityId }) {
  const { walletCheckout } = useEasy();
  const [loading, setLoading] = useState(false);
  const [walletId, setWalletId] = useState("");

  const handleCheckout = async () => {
    setLoading(true);

    try {
      const result = await walletCheckout({
        identity_id: identityId,
        wallet_id: walletId,
        line_items: [{ price_id: "price_456", quantity: 2 }],
      });

      console.log("Wallet checkout successful:", result.data);
    } catch (error) {
      console.error("Wallet checkout failed:", error);
    } finally {
      setLoading(false);
    }
  };

  return (
    <div>
      <input
        type="text"
        value={walletId}
        onChange={(e) => setWalletId(e.target.value)}
        placeholder="Wallet ID"
        required
      />
      <button onClick={handleCheckout} disabled={loading || !walletId}>
        {loading ? "Processing..." : "Pay with Wallet"}
      </button>
    </div>
  );
}

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 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);
  }
}

Related APIs

• Checkout API - For traditional card and bank account payments