Online Checkout Integration Guide

Integrate WalletConnect Pay into your online checkout so buyers can pay with crypto from any wallet, using the assets they already hold.

PrerequisitesCopy Anchor Link

Before you begin, make sure you have:

• Completed merchant onboarding — sign up and complete KYB verification on the Merchant Dashboard
• API Key — available in your Merchant Dashboard after onboarding (used as the Api-Key header)
• Merchant ID — your merchant identifier from the Merchant Dashboard
• A backend server — all API calls must be made server-side to keep your API Key secure

How It WorksCopy Anchor Link

The checkout integration follows a redirect-based flow. Your backend creates a payment, redirects the buyer to the WalletConnect Pay checkout portal, and verifies the result after the buyer returns.

Integration StepsCopy Anchor Link

// Server-side only
const response = await fetch(
  "https://api.pay.walletconnect.com/v1/merchant/payment",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Api-Key": process.env.WCP_API_KEY,
      "Merchant-Id": process.env.WCP_MERCHANT_ID,
    },
    body: JSON.stringify({
      amount: {
        unit: "iso4217/USD",
        value: String(order.totalCents), // e.g., "5000" for $50.00
      },
      referenceId: order.id,
      checkout: {
        successUrl: `${process.env.BASE_URL}/order/${order.id}/success`,
        errorUrl: `${process.env.BASE_URL}/order/${order.id}/failed`,
      },
    }),
  }
);

const { paymentId, gatewayUrl } = await response.json();

// Client-side: redirect to checkout portal
window.location.href = gatewayUrl;

const url = new URL(window.location.href);
const paymentId = url.searchParams.get("payment_id");

if (!paymentId) {
  throw new Error("Missing payment_id in redirect URL");
}

const status = await verifyPayment(paymentId);

const order = await getOrderByPaymentId(paymentId);

const response = await fetch(
  `https://api.pay.walletconnect.com/v1/merchant/payment/${paymentId}/status`,
  {
    headers: {
      "Api-Key": process.env.WCP_API_KEY,
      "Merchant-Id": process.env.WCP_MERCHANT_ID,
    },
  }
);

const { status, isFinal } = await response.json();

if (status === "succeeded") {
  await fulfillOrder(order.id);
} else if (status === "processing") {
  // Transaction submitted but not yet confirmed — check again shortly
} else {
  // "failed" or "expired" — inform the buyer
}

Checkout URL RequirementsCopy Anchor Link

• The checkout portal appends ?payment_id={id} to your callback URLs automatically
• There is no cancelUrl — if the buyer abandons the flow, they simply close the tab
• Include your order reference in the URL path (e.g., /order/{orderId}/success) so you can correlate the redirect with the right order

Merchant BrandingCopy Anchor Link

The checkout portal displays your merchant name and icon to the buyer during the payment flow. These are configured in the Merchant Dashboard:

• merchant.name — displayed in the payment summary
• merchant.iconUrl — displayed alongside your name

TestingCopy Anchor Link

Use the staging environment to test your integration before going live:

Contact the WalletConnect team to obtain staging credentials.

Example ImplementationCopy Anchor Link

Complete working reference checkouts are available in the WalletConnect Pay examples repository:

The example includes:

• API client — payment creation with checkout URLs
• Checkout route — creates a payment and redirects the buyer
• Order confirmation page — receives the redirect and displays order status