[SDK] Rename verifyPayment() to processPayment() for x402 payments

Author: joaquim-verges

.changeset/some-moons-burn.md

@@ -2,4 +2,4 @@
 "thirdweb": minor
 ---
 
-Accept arbitrary chain ids for x402 payments with new verifyPayment() backend utility
+Accept arbitrary chain ids for x402 payments with new processPayment() backend utility

apps/playground-web/src/app/payments/x402/page.tsx

@@ -57,7 +57,7 @@ function ServerCodeExample() {
             className="h-full rounded-none border-none"
             code={`// src/middleware.ts
 
-import { facilitator, verifyPayment } from "thirdweb/x402";
+import { facilitator, processPayment } from "thirdweb/x402";
 import { createThirdwebClient } from "thirdweb";
 
 const client = createThirdwebClient({ secretKey: "your-secret-key" });
@@ -71,7 +71,7 @@ export async function middleware(request: NextRequest) {
   const resourceUrl = request.nextUrl.toString();
   const paymentData = request.headers.get("X-PAYMENT");
 
-  const result = await verifyPayment({
+  const result = await processPayment({
     resourceUrl,
     method,
     paymentData,

apps/playground-web/src/middleware.ts

@@ -1,7 +1,7 @@
 import { type NextRequest, NextResponse } from "next/server";
 import { createThirdwebClient } from "thirdweb";
 import { arbitrumSepolia } from "thirdweb/chains";
-import { facilitator, verifyPayment } from "thirdweb/x402";
+import { facilitator, processPayment } from "thirdweb/x402";
 
 const client = createThirdwebClient({
   secretKey: process.env.THIRDWEB_SECRET_KEY as string,
@@ -26,7 +26,7 @@ export async function middleware(request: NextRequest) {
   const resourceUrl = `${request.nextUrl.protocol}//${request.nextUrl.host}${pathname}`;
   const paymentData = request.headers.get("X-PAYMENT");
 
-  const result = await verifyPayment({
+  const result = await processPayment({
     resourceUrl,
     method,
     paymentData,

apps/portal/src/app/payments/x402/page.mdx

@@ -41,15 +41,15 @@ const response = await fetchWithPay('https://api.example.com/paid-endpoint');
 
 ## Server Side
 
-To make your API calls payable, you can use the `verifyPayment` function in a simple middleware or in your endpoint directly.
+To make your API calls payable, you can use the `processPayment` function in a simple middleware or in your endpoint directly.
 
-Use the `facilitator` configuration function settle transactions with your thirdweb server wallet gaslessly and pass it to the `verifyPayment` function.
+Use the `facilitator` configuration function settle transactions with your thirdweb server wallet gaslessly and pass it to the `processPayment` function.
 
 Here's an example with a Next.js middleware:
 
 ```typescript
 import { createThirdwebClient } from "thirdweb";
-import { facilitator, verifyPayment } from "thirdweb/x402";
+import { facilitator, processPayment } from "thirdweb/x402";
 
 const client = createThirdwebClient({ secretKey: "your-secret-key" });
 const thirdwebX402Facilitator = facilitator({
@@ -62,7 +62,7 @@ export async function middleware(request: NextRequest) {
   const resourceUrl = request.nextUrl.toString();
   const paymentData = request.headers.get("X-PAYMENT");
 
-  const result = await verifyPayment({
+  const result = await processPayment({
     resourceUrl,
     method,
     paymentData,

packages/thirdweb/src/exports/x402.ts

@@ -4,8 +4,5 @@ export {
   type ThirdwebX402FacilitatorConfig,
 } from "../x402/facilitator.js";
 export { wrapFetchWithPayment } from "../x402/fetchWithPayment.js";
-export {
-  type VerifyPaymentArgs,
-  type VerifyPaymentResult,
-  verifyPayment,
-} from "../x402/verify-payment.js";
+export { processPayment } from "../x402/process-payment.js";
+export type { PaymentArgs, ProcessPaymentResult } from "../x402/types.js";

packages/thirdweb/src/x402/facilitator.ts

@@ -19,7 +19,7 @@ const DEFAULT_BASE_URL = "https://api.thirdweb.com/v1/payments/x402";
 
 /**
  * Creates a facilitator for the x402 payment protocol.
- * You can use this with `verifyPayment` or with any x402 middleware to enable settling transactions with your thirdweb server wallet.
+ * You can use this with `processPayment` or with any x402 middleware to enable settling transactions with your thirdweb server wallet.
  *
  * @param config - The configuration for the facilitator
  * @returns a x402 compatible FacilitatorConfig

packages/thirdweb/src/x402/verify-payment.ts renamed to packages/thirdweb/src/x402/process-payment.ts

@@ -3,78 +3,23 @@ import {
   type Money,
   moneySchema,
   type Network,
-  type PaymentMiddlewareConfig,
   SupportedEVMNetworks,
 } from "x402/types";
-import { type Address, getAddress } from "../utils/address.js";
+import { getAddress } from "../utils/address.js";
 import { stringify } from "../utils/json.js";
 import { decodePayment, safeBase64Encode } from "./encode.js";
 import type { facilitator as facilitatorType } from "./facilitator.js";
 import {
   type FacilitatorNetwork,
-  type FacilitatorSettleResponse,
   networkToChainId,
   type RequestedPaymentPayload,
   type RequestedPaymentRequirements,
 } from "./schemas.js";
-
-const x402Version = 1;
-
-/**
- * Configuration object for verifying X402 payments.
- *
- * @public
- */
-export type VerifyPaymentArgs = {
-  /** The URL of the resource being protected by the payment */
-  resourceUrl: string;
-  /** The HTTP method used to access the resource */
-  method: "GET" | "POST" | ({} & string);
-  /** The payment data/proof provided by the client, typically from the X-PAYMENT header */
-  paymentData?: string | null;
-  /** The wallet address that should receive the payment */
-  payTo: Address;
-  /** The blockchain network where the payment should be processed */
-  network: FacilitatorNetwork;
-  /** The price for accessing the resource - either a USD amount (e.g., "$0.10") or a specific token amount */
-  price: Money | ERC20TokenAmount;
-  /** The payment facilitator instance used to verify and settle payments */
-  facilitator: ReturnType<typeof facilitatorType>;
-  /** Optional configuration for the payment middleware route */
-  routeConfig?: PaymentMiddlewareConfig;
-};
-
-/**
- * The result of a payment verification operation.
- *
- * @public
- */
-export type VerifyPaymentResult =
-  | {
-      /** HTTP 200 - Payment was successfully verified and settled */
-      status: 200;
-      /** Response headers including payment receipt information */
-      responseHeaders: Record<string, string>;
-      /** The settlement receipt from the payment facilitator */
-      paymentReceipt: FacilitatorSettleResponse;
-    }
-  | {
-      /** HTTP 402 - Payment Required, verification failed or payment missing */
-      status: 402;
-      /** The error response body containing payment requirements */
-      responseBody: {
-        /** The X402 protocol version */
-        x402Version: number;
-        /** Human-readable error message */
-        error: string;
-        /** Array of acceptable payment methods and requirements */
-        accepts: RequestedPaymentRequirements[];
-        /** Optional payer address if verification partially succeeded */
-        payer?: string;
-      };
-      /** Response headers for the error response */
-      responseHeaders: Record<string, string>;
-    };
+import {
+  type PaymentArgs,
+  type ProcessPaymentResult,
+  x402Version,
+} from "./types.js";
 
 /**
  * Verifies and processes X402 payments for protected resources.
@@ -89,7 +34,7 @@ export type VerifyPaymentResult =
  * @example
  * ```ts
  * // Usage in a Next.js API route
- * import { verifyPayment, facilitator } from "thirdweb/x402";
+ * import { processPayment, facilitator } from "thirdweb/x402";
  * import { createThirdwebClient } from "thirdweb";
  *
  * const client = createThirdwebClient({
@@ -104,7 +49,7 @@ export type VerifyPaymentResult =
  * export async function GET(request: Request) {
  *   const paymentData = request.headers.get("x-payment");
  *
- *   const result = await verifyPayment({
+ *   const result = await processPayment({
  *     resourceUrl: "https://api.example.com/premium-content",
  *     method: "GET",
  *     paymentData,
@@ -138,12 +83,22 @@ export type VerifyPaymentResult =
  * ```ts
  * // Usage in Express middleware
  * import express from "express";
- * import { verifyPayment, facilitator } from "thirdweb/x402";
+ * import { processPayment, facilitator } from "thirdweb/x402";
+ * import { createThirdwebClient } from "thirdweb";
+ *
+ * const client = createThirdwebClient({
+ *   secretKey: process.env.THIRDWEB_SECRET_KEY,
+ * });
+ *
+ * const thirdwebFacilitator = facilitator({
+ *   client,
+ *   serverWalletAddress: "0x1234567890123456789012345678901234567890",
+ * });
  *
  * const app = express();
  *
  * async function paymentMiddleware(req, res, next) {
- *   const result = await verifyPayment({
+ *   const result = await processPayment({
  *     resourceUrl: `${req.protocol}://${req.get('host')}${req.originalUrl}`,
  *     method: req.method,
  *     paymentData: req.headers["x-payment"],
@@ -176,9 +131,9 @@ export type VerifyPaymentResult =
  * @beta
  * @bridge x402
  */
-export async function verifyPayment(
-  args: VerifyPaymentArgs,
-): Promise<VerifyPaymentResult> {
+export async function processPayment(
+  args: PaymentArgs,
+): Promise<ProcessPaymentResult> {
   const {
     price,
     network,
@@ -316,47 +271,6 @@ export async function verifyPayment(
     };
   }
 
-  try {
-    const verification = await facilitator.verify(
-      decodedPayment,
-      selectedPaymentRequirements,
-    );
-
-    if (!verification.isValid) {
-      return {
-        status: 402,
-        responseHeaders: {
-          "Content-Type": "application/json",
-        },
-        responseBody: {
-          x402Version,
-          error:
-            errorMessages?.verificationFailed ||
-            verification.invalidReason ||
-            "Payment verification failed",
-          accepts: paymentRequirements,
-          payer: verification.payer,
-        },
-      };
-    }
-  } catch (error) {
-    return {
-      status: 402,
-      responseHeaders: {
-        "Content-Type": "application/json",
-      },
-      responseBody: {
-        x402Version,
-        error:
-          errorMessages?.verificationFailed ||
-          (error instanceof Error
-            ? error.message
-            : "Payment Verification error"),
-        accepts: paymentRequirements,
-      },
-    };
-  }
-
   // Settle payment
   try {
     const settlement = await facilitator.settle(

packages/thirdweb/src/x402/types.ts

@@ -0,0 +1,74 @@
+import type {
+  ERC20TokenAmount,
+  Money,
+  PaymentMiddlewareConfig,
+} from "x402/types";
+import type { Address } from "../utils/address.js";
+import type { Prettify } from "../utils/type-utils.js";
+import type { facilitator as facilitatorType } from "./facilitator.js";
+import type {
+  FacilitatorNetwork,
+  FacilitatorSettleResponse,
+  RequestedPaymentRequirements,
+} from "./schemas.js";
+
+export const x402Version = 1;
+
+/**
+ * Configuration object for verifying or processing X402 payments.
+ *
+ * @public
+ */
+export type PaymentArgs = {
+  /** The URL of the resource being protected by the payment */
+  resourceUrl: string;
+  /** The HTTP method used to access the resource */
+  method: "GET" | "POST" | ({} & string);
+  /** The payment data/proof provided by the client, typically from the X-PAYMENT header */
+  paymentData?: string | null;
+  /** The wallet address that should receive the payment */
+  payTo: Address;
+  /** The blockchain network where the payment should be processed */
+  network: FacilitatorNetwork;
+  /** The price for accessing the resource - either a USD amount (e.g., "$0.10") or a specific token amount */
+  price: Money | ERC20TokenAmount;
+  /** The payment facilitator instance used to verify and settle payments */
+  facilitator: ReturnType<typeof facilitatorType>;
+  /** Optional configuration for the payment middleware route */
+  routeConfig?: PaymentMiddlewareConfig;
+};
+
+type PaymentRequiredResult = {
+  /** HTTP 402 - Payment Required, verification or processing failed or payment missing */
+  status: 402;
+  /** The error response body containing payment requirements */
+  responseBody: {
+    /** The X402 protocol version */
+    x402Version: number;
+    /** Human-readable error message */
+    error: string;
+    /** Array of acceptable payment methods and requirements */
+    accepts: RequestedPaymentRequirements[];
+    /** Optional payer address if verification partially succeeded */
+    payer?: string;
+  };
+  /** Response headers for the error response */
+  responseHeaders: Record<string, string>;
+};
+
+/**
+ * The result of a payment verification or processing operation.
+ *
+ * @public
+ */
+export type ProcessPaymentResult = Prettify<
+  | {
+      /** HTTP 200 - Payment was successfully processed */
+      status: 200;
+      /** Response headers including payment receipt information */
+      responseHeaders: Record<string, string>;
+      /** The payment receipt from the payment facilitator */
+      paymentReceipt: FacilitatorSettleResponse;
+    }
+  | PaymentRequiredResult
+>;