In-App Payments in Alien Mini Apps: React SDK Guide

 
function CheckoutButton() {
  const { authToken } = useAlien();
 
  const {
    pay,
    status,
    isLoading,
    isPaid,
    isCancelled,
    isFailed,
    txHash,
    errorCode,
    error,
    reset,
    callable,
  } = usePayment({
    onPaid: (txHash) => {
      console.log('Payment successful:', txHash);
    },
    onCancelled: () => {
      console.log('Payment cancelled by user');
    },
    onFailed: (errorCode, error) => {
      console.error('Payment failed:', errorCode, error);
    },
  });
 
  const handlePayment = async () => {
    // Step 1: Create invoice on your backend
    const res = await fetch('/api/invoices', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${authToken}`,
      },
      body: JSON.stringify({
        recipientAddress: 'YOUR_WALLET_ADDRESS',
        amount: '10000',
        token: 'USDC',
        network: 'solana',
        productId: 'my-product',
      }),
    });
    const { invoice } = await res.json();
 
    // Step 2: Open Alien payment UI
    await pay({
      recipient: 'YOUR_WALLET_ADDRESS',
      amount: '10000',
      token: 'USDC',
      network: 'solana',
      invoice,
      item: {
        title: 'Premium Plan',
        iconUrl: 'https://example.com/icon.png',
        quantity: 1,
      },
    });
  };
 
  if (!callable) {
    return <p>Payments not supported in this environment</p>;
  }
 
  return (
    <button onClick={handlePayment} disabled={isLoading}>
      {isLoading ? 'Processing...' : 'Pay Now'}
    </button>
  );
}

// UUID (36 bytes)
const invoice = crypto.randomUUID();
 
// SHA-256 as base64url (43 bytes) — fits well under 64
const invoice = createHash('sha256')
  .update(orderId)
  .digest('base64url');
 
// Nano ID (21 bytes)
const invoice = nanoid();
 
// Custom short ID
const invoice = `ord_${Date.now()}`;

interface WebhookPayload {
  invoice: string;
  recipient: string;
  amount: string; // in the token's smallest unit
  decimals: number; // 9 for SOL and ALIEN, 6 for USDC
  token: string; // normalized: mint address or 'native'
  network: string; // 'solana' or 'alien'
  status: 'finalized' | 'failed';
  txHash?: string;
  test: boolean; // false for real payments, true for test events
}

async function verifySignature(
  publicKeyHex: string,
  signatureHex: string,
  body: string,
): Promise<boolean> {
  // Import the Ed25519 public key from hex
  const publicKey = await crypto.subtle.importKey(
    'raw',
    Buffer.from(publicKeyHex, 'hex'),
    { name: 'Ed25519' },
    false,
    ['verify'],
  );
 
  // Verify the signature
  return crypto.subtle.verify(
    'Ed25519',
    publicKey,
    Buffer.from(signatureHex, 'hex'),
    Buffer.from(body),
  );
}

// verifySignature() from the previous section
 
// The webhook schema version this handler implements
const SUPPORTED_WEBHOOK_VERSION = '3';
 
export async function POST(request: Request) {
  // 1. Read the raw body (must be read before parsing JSON)
  const rawBody = await request.text();
 
  // 2. Get the signature from headers
  const signatureHex =
    request.headers.get('x-webhook-signature') ?? '';
  if (!signatureHex) {
    return NextResponse.json(
      { error: 'Missing webhook signature' },
      { status: 401 },
    );
  }
 
  // 3. Reject schema versions you don't implement
  const version = request.headers.get('x-webhook-version');
  if (version !== null && version !== SUPPORTED_WEBHOOK_VERSION) {
    return NextResponse.json(
      { error: `Unsupported webhook version: ${version}` },
      { status: 400 },
    );
  }
 
  try {
    // 4. Verify the Ed25519 signature
    const isValid = await verifySignature(
      process.env.WEBHOOK_PUBLIC_KEY!,
      signatureHex,
      rawBody,
    );
 
    if (!isValid) {
      return NextResponse.json(
        { error: 'Invalid signature' },
        { status: 401 },
      );
    }
 
    // 5. Parse the payload and look up your stored order
    const payload = JSON.parse(rawBody);
    const order = await findOrderByInvoice(payload.invoice);
 
    if (!order) {
      return NextResponse.json(
        { error: 'Invoice not found' },
        { status: 404 },
      );
    }
 
    // 6. Cross-check the payload against the stored order.
    //    Compare recipient, amount, and network — NOT token: the
    //    platform sends a normalized slug ('native' or a mint
    //    address), which differs from the slug used in pay().
    if (
      payload.recipient !== order.recipientAddress ||
      payload.amount !== order.amount ||
      payload.network !== order.network
    ) {
      return NextResponse.json(
        { error: 'Payload does not match order' },
        { status: 400 },
      );
    }
 
    // 7. Update the order status
    if (payload.status === 'finalized') {
      // Transaction confirmed on-chain — fulfill the order
      await fulfillOrder(payload.invoice, payload.txHash);
    } else if (payload.status === 'failed') {
      // Transaction failed — handle accordingly
      await markOrderFailed(payload.invoice);
    }
 
    return NextResponse.json({ success: true });
  } catch (error) {
    console.error('Webhook processing error:', error);
    return NextResponse.json(
      { error: 'Failed to process webhook' },
      { status: 500 },
    );
  }
}

await pay({
  recipient: 'YOUR_WALLET_ADDRESS',
  amount: '10000',
  token: 'USDC',
  network: 'solana',
  invoice: 'test-order-123',
  test: 'paid',  // Simulate successful payment
});

 
function PaymentStatus() {
  const {
    status, isPaid, isFailed, isCancelled,
    txHash, errorCode, reset,
  } = usePayment();
 
  if (isPaid) {
    return (
      <div>
        <h2>Payment Successful</h2>
        <p>Transaction: {txHash}</p>
        <button onClick={reset}>Make Another Payment</button>
      </div>
    );
  }
 
  if (isFailed) {
    return (
      <div>
        <h2>Payment Failed</h2>
        <p>Error: {errorCode}</p>
        <button onClick={reset}>Try Again</button>
      </div>
    );
  }
 
  if (isCancelled) {
    return (
      <div>
        <h2>Payment Cancelled</h2>
        <button onClick={reset}>Try Again</button>
      </div>
    );
  }
 
  return <p>Status: {status}</p>;
}

 
function BuyButton({ product }) {
  const { authToken } = useAlien();
 
  const payment = usePayment({
    onPaid: (txHash) => console.log('Paid!', txHash),
    onCancelled: () => console.log('Cancelled'),
    onFailed: (code) => console.log('Failed:', code),
  });
 
  const handlePurchase = useCallback(async () => {
    if (!authToken) return;
 
    // 1. Create invoice on your backend
    const res = await fetch('/api/invoices', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${authToken}`,
      },
      body: JSON.stringify({
        recipientAddress: product.recipientAddress,
        amount: product.amount,
        token: product.token,
        network: product.network,
        productId: product.id,
      }),
    });
    const { invoice } = await res.json();
 
    // 2. Open payment UI
    await payment.pay({
      recipient: product.recipientAddress,
      amount: product.amount,
      token: product.token,
      network: product.network,
      invoice,
      item: {
        title: product.name,
        iconUrl: product.iconUrl,
        quantity: product.quantity,
      },
    });
  }, [authToken, payment, product]);
 
  if (!payment.callable) {
    return <p>Payments not available</p>;
  }
 
  return (
    <button onClick={handlePurchase} disabled={payment.isLoading}>
      {payment.isLoading ? 'Processing...' : `Buy for ${product.price}`}
    </button>
  );
}

 
const authClient = createAuthClient({
  audience: 'your-miniapp-provider-address',
});
 
function extractBearerToken(
  header: string | null,
): string | null {
  return header?.startsWith('Bearer ')
    ? header.slice(7)
    : null;
}
 
export async function POST(request: Request) {
  try {
    const token = extractBearerToken(
      request.headers.get('Authorization'),
    );
 
    if (!token) {
      return NextResponse.json(
        { error: 'Missing authorization token' },
        { status: 401 },
      );
    }
 
    // Verify JWT — `sub` is the user's Alien ID
    const { sub } = await authClient.verifyToken(token);
 
    const body = await request.json();
    const {
      recipientAddress, amount,
      token: paymentToken, network, productId,
    } = body;
 
    // Validate that the product parameters match your catalog
    // to prevent clients from sending arbitrary amounts
    const product = PRODUCTS.find((p) => p.id === productId);
 
    if (
      !product ||
      product.amount !== amount ||
      product.token !== paymentToken ||
      product.network !== network ||
      product.recipientAddress !== recipientAddress
    ) {
      return NextResponse.json(
        { error: 'Invalid product parameters' },
        { status: 400 },
      );
    }
 
    // Any unique string under 64 bytes
    const invoice = randomUUID();
 
    // Save payment intent to your database
    await db.paymentIntents.create({
      invoice,
      senderAlienId: sub,
      recipientAddress,
      amount,
      token: paymentToken,
      network,
      productId,
      status: 'pending',
    });
 
    return NextResponse.json({ invoice });
  } catch (error) {
    if (error instanceof JwtErrors.JWTExpired) {
      return NextResponse.json(
        { error: 'Token expired' },
        { status: 401 },
      );
    }
    if (error instanceof JwtErrors.JOSEError) {
      return NextResponse.json(
        { error: 'Invalid token' },
        { status: 401 },
      );
    }
 
    console.error('Failed to create invoice:', error);
    return NextResponse.json(
      { error: 'Failed to create invoice' },
      { status: 500 },
    );
  }
}