Pay

Request a payment using the unified MiniKit API.

Use MiniKit.pay() to request a payment inside World App.

These examples assume MiniKit has already been initialized through MiniKitProvider or MiniKit.install().

Availability

• Works natively in World App
• Supports a custom fallback outside World App

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() {
  const response = await fetch("/api/initiate-payment", { 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",
  } satisfies MiniKitPayOptions;

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

Result

Type

type PayResponse =
  | {
      executedWith: "minikit";
      data: {
        transactionId: string;
        reference: string;
        from: string;
        chain: "worldchain";
        timestamp: string;
      };
    }
  | {
      executedWith: "fallback";
      data: unknown;
    };

Fallback Behavior

Use a custom fallback if you want equivalent payment behavior outside World App.

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

Preview