diff --git a/docs.json b/docs.json
index 7288552..086c482 100644
--- a/docs.json
+++ b/docs.json
@@ -74,7 +74,9 @@
           {
             "group": "Ecommerce and Online Checkout",
             "pages": [
-              "payments/ecommerce/overview"
+              "payments/ecommerce/overview",
+              "payments/ecommerce/integration",
+              "payments/ecommerce/api-reference"
             ]
           }
         ]
diff --git a/payments/ecommerce/api-reference.mdx b/payments/ecommerce/api-reference.mdx
new file mode 100644
index 0000000..3c5db9e
--- /dev/null
+++ b/payments/ecommerce/api-reference.mdx
@@ -0,0 +1,221 @@
+---
+title: "Merchant API Reference"
+description: "API reference for the WalletConnect Pay Merchant API used in ecommerce checkout integrations."
+sidebarTitle: "API Reference"
+---
+
+## Authentication
+
+Every request to the Merchant API requires the following headers:
+
+| Header | Required | Description |
+|--------|----------|-------------|
+| `Content-Type` | Yes | Must be `application/json` |
+| `Api-Key` | Yes | Partner API key from the [Merchant Dashboard](/payments/merchant/onboarding) |
+| `Merchant-Id` | Yes | Merchant identifier from the [Merchant Dashboard](/payments/merchant/onboarding) |
+
+<Warning>
+Keep your `Api-Key` secret. Never expose it in client-side code — all API calls should be made from your backend server.
+</Warning>
+
+## Base URLs
+
+| Environment | URL |
+|-------------|-----|
+| Production | `https://api.pay.walletconnect.org` |
+| Staging | `https://staging.api.pay.walletconnect.org` |
+
+---
+
+## Create Payment
+
+Creates a new payment for the buyer to complete on the WalletConnect Pay checkout portal.
+
+```
+POST /v1/merchant/payment
+```
+
+### Request Body
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `amount` | object | Yes | The payment amount |
+| `amount.unit` | string | Yes | Currency in `iso4217/{CODE}` format (e.g., `iso4217/USD`) |
+| `amount.value` | string | Yes | Amount in minor units as a string (e.g., `"5000"` for $50.00) |
+| `referenceId` | string | Yes | Your internal order or reference identifier |
+| `checkout` | object | No | Checkout redirect configuration |
+| `checkout.successUrl` | string | No | HTTPS URL to redirect the buyer after a successful payment |
+| `checkout.errorUrl` | string | No | HTTPS URL to redirect the buyer after a failed payment |
+
+<Info>
+The `amount.value` is expressed in the currency's **minor units**. For USD, `"5000"` equals $50.00 (5000 cents). For JPY (which has no minor unit), `"5000"` equals ¥5,000.
+</Info>
+
+<Warning>
+Both `successUrl` and `errorUrl` must be valid HTTPS URLs. If either is missing or invalid, the redirect feature is disabled entirely for that payment — the checkout portal will show generic terminal views instead.
+</Warning>
+
+### Request Example
+
+```json
+{
+  "amount": {
+    "unit": "iso4217/USD",
+    "value": "5000"
+  },
+  "referenceId": "order_abc123",
+  "checkout": {
+    "successUrl": "https://yourstore.com/order/abc123/success",
+    "errorUrl": "https://yourstore.com/order/abc123/failed"
+  }
+}
+```
+
+### Response
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `paymentId` | string | Unique payment identifier (e.g., `pay_xxx`) |
+| `gatewayUrl` | string | URL to the checkout portal for this payment — use this to redirect the buyer |
+| `status` | string | Initial payment status (typically `pending`) |
+| `expiresAt` | integer | Unix timestamp (seconds) when the payment expires |
+| `isFinal` | boolean | Whether the payment is already in a terminal state |
+| `pollInMs` | integer | Suggested polling interval in milliseconds for status checks |
+
+### Response Example
+
+```json
+{
+  "paymentId": "pay_abc123def456",
+  "gatewayUrl": "https://pay.walletconnect.com/?pid=pay_abc123def456",
+  "status": "pending",
+  "expiresAt": 1709831400,
+  "isFinal": false,
+  "pollInMs": 1000
+}
+```
+
+### Code Examples
+
+<CodeGroup>
+```bash cURL
+curl -X POST https://api.pay.walletconnect.org/v1/merchant/payment \
+  -H "Content-Type: application/json" \
+  -H "Api-Key: YOUR_API_KEY" \
+  -H "Merchant-Id: YOUR_MERCHANT_ID" \
+  -d '{
+    "amount": {
+      "unit": "iso4217/USD",
+      "value": "5000"
+    },
+    "referenceId": "order_abc123",
+    "checkout": {
+      "successUrl": "https://yourstore.com/order/abc123/success",
+      "errorUrl": "https://yourstore.com/order/abc123/failed"
+    }
+  }'
+```
+
+```typescript TypeScript
+const response = await fetch(
+  "https://api.pay.walletconnect.org/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),
+      },
+      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();
+```
+</CodeGroup>
+
+### Error Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `400` | Invalid request — check required fields and format |
+| `401` | Invalid or missing API key |
+| `404` | Merchant not found for the given `Merchant-Id` |
+| `500` | Internal server error |
+
+---
+
+## Verify Payment Status
+
+After the buyer completes (or abandons) the checkout, verify the payment status from your backend.
+
+```
+GET /v1/merchant/payment/{id}/status
+```
+
+### Path Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | string | The `paymentId` returned when creating the payment |
+
+### Headers
+
+| Header | Required | Description |
+|--------|----------|-------------|
+| `Api-Key` | Yes | Partner API key |
+| `Merchant-Id` | Yes | Merchant identifier |
+
+### Response
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `status` | string | Payment status (see below) |
+| `isFinal` | boolean | Whether the payment has reached a terminal state |
+
+### Payment Statuses
+
+| Status | Terminal | Description |
+|--------|----------|-------------|
+| `pending` | No | Payment created, waiting for buyer action |
+| `processing` | No | Transaction submitted, awaiting on-chain confirmation |
+| `succeeded` | Yes | Payment completed successfully |
+| `failed` | Yes | Payment failed or was rejected |
+| `expired` | Yes | Payment window closed without completion |
+
+### Code Example
+
+<CodeGroup>
+```bash cURL
+curl https://api.pay.walletconnect.org/v1/merchant/payment/pay_abc123def456/status \
+  -H "Api-Key: YOUR_API_KEY" \
+  -H "Merchant-Id: YOUR_MERCHANT_ID"
+```
+
+```typescript TypeScript
+async function verifyPaymentStatus(paymentId: string): Promise<string> {
+  const response = await fetch(
+    `https://api.pay.walletconnect.org/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();
+  return status;
+}
+```
+</CodeGroup>
diff --git a/payments/ecommerce/integration.mdx b/payments/ecommerce/integration.mdx
new file mode 100644
index 0000000..be2fa85
--- /dev/null
+++ b/payments/ecommerce/integration.mdx
@@ -0,0 +1,210 @@
+---
+title: "Online Checkout Integration Guide"
+description: "Step-by-step guide to integrate WalletConnect Pay into your ecommerce checkout flow."
+sidebarTitle: "Integration Guide"
+---
+
+Integrate WalletConnect Pay into your online checkout so buyers can pay with crypto from any wallet, using the assets they already hold.
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+- **Completed merchant onboarding** — sign up and complete KYB verification on the [Merchant Dashboard](/payments/merchant/onboarding)
+- **Partner API Key** — available in your Merchant Dashboard after onboarding
+- **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 Works
+
+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.
+
+```mermaid
+sequenceDiagram
+    participant B as Buyer
+    participant MF as Merchant Frontend
+    participant MB as Merchant Backend
+    participant API as WalletConnect Pay API
+    participant BX as Checkout Portal
+
+    B->>MF: Click "Pay with Crypto"
+    MF->>MB: Create payment request
+    MB->>API: POST /v1/merchant/payment
+    API-->>MB: { paymentId, gatewayUrl }
+    MB-->>MF: gatewayUrl
+    MF->>BX: Redirect buyer to checkout portal
+
+    Note over BX,B: Buyer connects wallet,<br>selects payment option,<br>and signs the transaction
+
+    alt Payment succeeds
+        BX->>MF: Redirect to successUrl?payment_id=id
+    else Payment fails
+        BX->>MF: Redirect to errorUrl?payment_id=id
+    end
+
+    MF->>MB: Verify payment status
+    MB->>API: GET /v1/merchant/payment/{id}/status
+    API-->>MB: { status: "succeeded" }
+    MB-->>MF: Order confirmed
+    MF->>B: Show order confirmation
+```
+
+## Integration Steps
+
+<Steps>
+  <Step title="Create a Payment" icon="file-invoice-dollar">
+    From your backend, call the Merchant API to create a payment with the order amount and redirect URLs.
+
+    ```typescript
+    // Server-side only
+    const response = await fetch(
+      "https://api.pay.walletconnect.org/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();
+    ```
+
+    Store the `paymentId` in your database alongside the order so you can verify the payment later.
+
+    <Info>
+    The `amount.value` is in **minor currency units** — for USD, `"5000"` equals $50.00. See the [API Reference](/payments/ecommerce/api-reference) for details.
+    </Info>
+  </Step>
+
+  <Step title="Redirect the Buyer" icon="arrow-up-right-from-square">
+    Redirect the buyer to the `gatewayUrl` returned by the API. This takes them to the WalletConnect Pay checkout portal where they can connect their wallet, choose a payment option, and complete the transaction.
+
+    ```typescript
+    // Client-side: redirect to checkout portal
+    window.location.href = gatewayUrl;
+    ```
+
+    The checkout portal handles the entire buyer-side payment flow — no additional integration is needed on your end for this step.
+  </Step>
+
+  <Step title="Handle the Return" icon="rotate-left">
+    After the payment completes (or fails), the checkout portal redirects the buyer back to your site:
+
+    - **Success**: `{successUrl}?payment_id={paymentId}`
+    - **Failure**: `{errorUrl}?payment_id={paymentId}`
+
+    The redirect happens automatically after a 3-second countdown on the checkout portal.
+
+    ```typescript
+    // Extract the payment ID from the redirect URL
+    const url = new URL(window.location.href);
+    const paymentId = url.searchParams.get("payment_id");
+
+    // Verify the payment status from your backend (next step)
+    const status = await verifyPayment(paymentId);
+    ```
+
+    <Warning>
+    **Never trust the redirect URL alone.** The redirect can be spoofed by a buyer navigating directly to your success URL. Always verify the payment status server-side before fulfilling an order.
+    </Warning>
+  </Step>
+
+  <Step title="Verify Payment Status" icon="shield-check">
+    From your backend, call the status endpoint to get the authoritative payment result.
+
+    ```typescript
+    // Server-side: verify payment status
+    const response = await fetch(
+      `https://api.pay.walletconnect.org/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(orderId);
+    } else if (status === "processing") {
+      // Transaction submitted but not yet confirmed — check again shortly
+    } else {
+      // "failed" or "expired" — inform the buyer
+    }
+    ```
+
+    If `isFinal` is `false` (status is `processing`), poll the endpoint at a reasonable interval until the payment reaches a terminal state.
+
+    | Status | Terminal | Action |
+    |--------|----------|--------|
+    | `succeeded` | Yes | Fulfill the order |
+    | `failed` | Yes | Show error, offer retry |
+    | `expired` | Yes | Show expiry message, offer new payment |
+    | `processing` | No | Poll again after a short delay |
+
+    See the full [API Reference](/payments/ecommerce/api-reference) for endpoint details and error codes.
+  </Step>
+</Steps>
+
+## Checkout URL Requirements
+
+<Note>
+Both `successUrl` and `errorUrl` must be valid **HTTPS** URLs. If either is missing or fails validation, the redirect feature is disabled for that payment — the checkout portal will show a generic success or error message instead.
+</Note>
+
+- 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 Branding
+
+The checkout portal displays your merchant name and icon to the buyer during the payment flow. These are configured in the [Merchant Dashboard](/payments/merchant/onboarding):
+
+- **`merchant.name`** — displayed in the payment summary
+- **`merchant.iconUrl`** — displayed alongside your name
+
+<Info>
+For best results, use a square icon with a minimum size of 72x72px in PNG, SVG, or WebP format.
+</Info>
+
+## Testing
+
+Use the staging environment to test your integration before going live:
+
+| Environment | API Base URL |
+|-------------|-------------|
+| Production | `https://api.pay.walletconnect.org` |
+| Staging | `https://staging.api.pay.walletconnect.org` |
+
+Contact the WalletConnect team to obtain staging credentials.
+
+## Example Implementation
+
+A complete working reference implementation is available in the WalletConnect buyer-experience repository:
+
+<CardGroup cols={1}>
+  <Card title="Ecommerce Example (Next.js)" icon="github" href="https://github.com/WalletConnect/buyer-experience/tree/main/examples/ecommerce-poc">
+    Full-stack example showing payment creation, checkout redirect, and order verification.
+  </Card>
+</CardGroup>
+
+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
diff --git a/payments/ecommerce/overview.mdx b/payments/ecommerce/overview.mdx
index 5df93b1..402dead 100644
--- a/payments/ecommerce/overview.mdx
+++ b/payments/ecommerce/overview.mdx
@@ -1,21 +1,24 @@
 ---
 title: "WalletConnect Pay for Ecommerce and Online Checkout"
+description: "Add crypto and stablecoin payments to your online checkout with a single API integration."
 sidebarTitle: "Overview"
 ---
 
 WalletConnect Pay enables you to add crypto and stablecoin payments to your online checkout with a single integration, offering a familiar, wallet-based experience for customers worldwide.
 
+<Note>
+Before integrating, complete [merchant onboarding](/payments/merchant/onboarding) to obtain your API Key and Merchant ID.
+</Note>
 
+## How It Works
 
-## Crypto payments, designed for online checkout
+Your backend creates a payment via a single API call and redirects the buyer to the WalletConnect Pay checkout portal. The buyer connects their wallet, selects a payment option, and completes the transaction. After payment, the buyer is redirected back to your site and you verify the result server-side.
 
-Enabling crypto payments for ecommerce and online checkout. For more information, contact us by filling out the form below:
-
-<CardGroup cols={2}>
-  <Card title="Contact Sales" icon="credit-card" href="https://share.hsforms.com/19Dpp4ayYR9uriB3xNAh0JAnxw6s">
-    Talk to our team about integrating WalletConnect Pay for ecommerce checkout.
-  </Card>
-</CardGroup>
+1. Your backend calls `POST /v1/merchant/payment` with the order amount and redirect URLs
+2. You redirect the buyer to the checkout portal using the `gatewayUrl` from the response
+3. The buyer connects their wallet, picks a token and network, and signs the transaction
+4. The checkout portal redirects the buyer back to your `successUrl` or `errorUrl`
+5. Your backend verifies the payment status via `GET /v1/merchant/payment/{id}/status`
 
 ## What does WalletConnect Pay offer for ecommerce?
 
@@ -37,3 +40,20 @@ Enabling crypto payments for ecommerce and online checkout. For more information
   </Step>
 </Steps>
 
+## Get Started
+
+<CardGroup cols={2}>
+  <Card title="Integration Guide" icon="code" href="/payments/ecommerce/integration">
+    Step-by-step guide to integrate WalletConnect Pay checkout into your site.
+  </Card>
+  <Card title="API Reference" icon="rectangle-terminal" href="/payments/ecommerce/api-reference">
+    Merchant API endpoint reference for creating and verifying payments.
+  </Card>
+  <Card title="Merchant Onboarding" icon="user-plus" href="/payments/merchant/onboarding">
+    Set up your merchant account and obtain your API credentials.
+  </Card>
+  <Card title="Example Implementation" icon="github" href="https://github.com/WalletConnect/buyer-experience/tree/main/examples/ecommerce-poc">
+    Full-stack Next.js reference implementation.
+  </Card>
+</CardGroup>
+