Basic Usage
import { MiniKit } from "@worldcoin/minikit-js";
import {
Tokens,
tokenToDecimals,
type CommandResultByVia,
type MiniKitPayOptions,
type PayResult,
} from "@worldcoin/minikit-js/commands";
export async function sendPayment() {
// Create a nonce in the backend to use as a reference for this payment.
const response = await fetch("/api/generate-nonce", { method: "POST" });
const { id } = await response.json();
const input = {
reference: id,
to: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
tokens: [
{
symbol: Tokens.WLD,
token_amount: tokenToDecimals(1, Tokens.WLD).toString(),
},
],
description: "Example payment",
fallback: () => {
alert("Please complete the payment in World App to proceed.");
},
};
const result: CommandResultByVia<PayResult, PayResult, "minikit"> =
await MiniKit.pay(input);
await fetch("/api/confirm-payment", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify(result.data),
});
}
type MiniKitPayOptions = {
reference: string;
to: string;
tokens: {
symbol: Tokens;
token_amount: string;
}[];
description: string;
fallback?: () => unknown;
};
Result
type PayResponse =
| {
executedWith: "minikit";
data: {
transactionId: string;
reference: string;
from: string;
chain: "worldchain";
timestamp: string;
};
}
| {
executedWith: "fallback";
data: unknown;
};
{
"executedWith": "minikit",
"data": {
"transactionId": "tx_1234567890abcdef",
"reference": "order-123",
"from": "0x1234567890123456789012345678901234567890",
"chain": "worldchain",
"timestamp": "2026-03-28T18:24:00.000Z"
}
}
Backend Verification
Always verify the payment on your backend before treating it as final.import { NextRequest, NextResponse } from "next/server";
import type { PayResult } from "@worldcoin/minikit-js/commands";
type RequestBody = {
payload: PayResult;
};
export async function POST(req: NextRequest) {
const { payload } = (await req.json()) as RequestBody;
const response = await fetch(
`https://developer.worldcoin.org/api/v2/minikit/transaction/${payload.transactionId}?app_id=${process.env.APP_ID}&type=payment`,
{
method: "GET",
headers: {
Authorization: `Bearer ${process.env.DEV_PORTAL_API_KEY}`,
},
},
);
const transaction = await response.json();
return NextResponse.json(transaction);
}
Error Codes
| Code | Meaning |
|---|---|
input_error | The payment payload is invalid |
user_rejected | The user rejected the request |
payment_rejected | The user cancelled the payment |
invalid_receiver | The recipient address is invalid or not allowed |
insufficient_balance | The user does not have enough balance |
transaction_failed | The payment failed on-chain |
generic_error | Unexpected failure |
user_blocked | Payments are not available in the user’s region |
Fallback Behavior
Define a custom fallback in the command payload for support outside mini apps.Preview
