Integrating USDC Payments in World App Mini Apps
One of the most exciting parts about building on World App is how developers can plug into an ecosystem of verified humans, onchain identity, and crypto-native payments—all inside a mobile wallet interface that will be familiar to your users.
If you're a developer shipping a mini app in World App, you now have a native way to accept USDC payments from users directly within the app experience. No more context switching. No external wallets. Just seamless, onchain payments powered by World App and the MiniKit-JS SDK.
In this post, we’ll walk through how to integrate USDC payments using the pay command from the MiniKit-JS SDK.
Let’s get started.
Why Add USDC Payments?
Adding a checkout flow with USDC unlocks a new revenue path for developers building digital storefronts, donation platforms, membership apps, and more—all without the risk of chargebacks or delays in settlement.
Because your mini app runs inside World App, your users already have:
- A wallet connected
- USDC balances on World Chain
- An identity verified via World ID
That means you can build an end-to-end onchain commerce experience in just a few lines of code.
Check out the repo here.
Step 1: Install MiniKit-JS
Your mini app will use the @worldcoin/minikit-js package to interact with the World App. Install it with:
npm install @worldcoin/minikit-jsYou can use this in any React or Next.js project.
Step 2: Set Up the MiniKit Provider
To initialize MiniKit properly, wrap your app in a provider component:
// components/minikit-provider.tsx
"use client"
import { type ReactNode, useEffect } from "react"
import { MiniKit } from "@worldcoin/minikit-js"
export default function MiniKitProvider({ children }: { children: ReactNode }) {
useEffect(() => {
MiniKit.install()
}, [])
return <>{children}</>
}Then plug it into your app’s layout:
// app/layout.tsx
import MiniKitProvider from "@/components/minikit-provider"
export default function RootLayout({ children }) {
return (
<html lang="en">
<body>
<MiniKitProvider>{children}</MiniKitProvider>
</body>
</html>
)
}This ensures that the SDK is initialized every time your mini app is launched in World App.
Step 3: (Optional) Verify the User with World ID
You can optionally require that a user verify their humanity via World ID before allowing them to complete a payment. This is great for blocking bots or enforcing gated access.
Here's how you'd call the verification flow:
import { MiniKit, VerificationLevel } from "@worldcoin/minikit-js"
const handleVerify = async () => {
if (!MiniKit.isInstalled()) {
alert("Please open this app in World App")
return
}
const { finalPayload } = await MiniKit.commandsAsync.verify({
action: "access_checkout",
verification_level: VerificationLevel.Orb,
})
if (finalPayload.status === "success") {
await fetch("/api/verify", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ payload: finalPayload, action: "access_checkout" }),
})
}
}Step 4: Accept USDC Payments with the Pay Command
Once the user is verified (if needed), you can initiate a USDC payment using the pay command.
import { MiniKit, Tokens, tokenToDecimals } from "@worldcoin/minikit-js"
const handlePurchase = async () => {
const res = await fetch("/api/initiate-payment", { method: "POST" })
const { id } = await res.json()
const paymentPayload = {
reference: id, // Unique identifier from your backend
to: "0xYourMerchantWalletAddress", // Replace with your address
tokens: [
{
symbol: Tokens.USDC,
token_amount: tokenToDecimals(25, Tokens.USDC).toString(), // $25 in USDC
},
],
description: "Checkout: World Chain T-Shirt",
}
const { finalPayload } = await MiniKit.commandsAsync.pay(paymentPayload)
if (finalPayload.status === "success") {
await fetch("/api/confirm-payment", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(finalPayload),
})
}
}This triggers a native payment experience inside the World App. The user sees a confirmation screen and approves the USDC transfer from their wallet directly to your address.
Step 5: Connect the UI
You can easily wire this into your React component:
<div className="text-3xl font-bold mb-6">$25.00 USDC</div>
{!isVerified ? (
<Button onClick={handleVerify}>Verify with World ID</Button>
) : (
<Button onClick={handlePurchase}>Buy with USDC</Button>
)}Wrapping Up
With just a few components and function calls, you can enable USDC payments directly in your World App mini app:
- No wallets to connect
- No confusing UX for end users
- No payment processor middlemen
Just stablecoin payments over World Chain, triggered from a single SDK call.
If you’re building for a global audience and want to monetize directly within the World App, adding a USDC checkout with MiniKit-JS is one of the fastest and most reliable ways to do it.
