Pay

Request a payment from the user

This command is an abstraction for a simple transfer. This shouldn’t be used outside of World App. Pay supports WLD and all local stablecoins.

Basic Usage

Example

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

Result

Type

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

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