docs: add ecommerce checkout integration guide by tomiir · Pull Request #27 · WalletConnectFoundation/wc-pay-docs

tomiir · 2026-03-06T12:12:55Z

Summary

New: Integration Guide (payments/ecommerce/integration.mdx) — Step-by-step guide for merchants to integrate the online checkout flow: create payment via Merchant API, redirect buyer to BX portal, handle return redirect, and verify payment status server-side. Includes Mermaid sequence diagram, TypeScript code examples, checkout URL requirements, merchant branding, and staging/testing info.
New: API Reference (payments/ecommerce/api-reference.mdx) — Merchant API reference documenting POST /v1/merchant/payment (create payment) and GET /v1/merchant/payment/{id}/status (verify status) with request/response schemas, field tables, cURL/TypeScript examples, and error codes.
Updated: Overview (payments/ecommerce/overview.mdx) — Transformed from "Contact Sales" placeholder into a proper section overview with a "How It Works" flow description, prerequisite note linking to merchant onboarding, and Get Started navigation cards.
Updated: Navigation (docs.json) — Added new pages to the "Ecommerce and Online Checkout" sidebar group.

Test plan

Run npx mintlify broken-links — verified no broken links
Verify all 3 pages render under "Ecommerce and Online Checkout" in sidebar
Verify Mermaid sequence diagram renders on integration guide
Verify <CodeGroup> tabs work for cURL/TypeScript examples
Verify internal links to /payments/merchant/onboarding and /payments/ecommerce/api-reference resolve correctly

🤖 Generated with Claude Code

…ence Expand the Ecommerce and Online Checkout section from a placeholder into full merchant integration documentation covering payment creation, buyer redirect flow, and server-side status verification. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

Adds comprehensive merchant-facing documentation for the WalletConnect Pay ecommerce/online checkout flow, replacing the previous “Contact Sales” placeholder with actionable integration and API reference content.

Changes:

Added a step-by-step ecommerce checkout integration guide (redirect flow, Mermaid diagram, and TypeScript examples).
Added a Merchant API reference for creating payments and verifying payment status (schemas, examples, and status semantics).
Updated the ecommerce overview page and docs navigation to surface the new content.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.

File	Description
payments/ecommerce/overview.mdx	Replaces placeholder content with an overview of the checkout flow plus “Get Started” entry points.
payments/ecommerce/integration.mdx	New integration guide describing the redirect-based checkout flow with examples and operational notes.
payments/ecommerce/api-reference.mdx	New reference documentation for `POST /v1/merchant/payment` and `GET /v1/merchant/payment/{id}/status`.
docs.json	Adds the new ecommerce pages to the “Ecommerce and Online Checkout” sidebar group.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-06T12:19:00Z

payments/ecommerce/integration.mdx

+- **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


The prerequisites call the credential a “Partner API Key”, while the overview page refers to an “API Key”. Consider standardizing the term across the ecommerce docs (and aligning with the header name Api-Key) to reduce confusion for merchants.

Suggested change

- **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

- **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

Copilot · 2026-03-06T12:19:00Z

payments/ecommerce/api-reference.mdx

+
+| Header | Required | Description |
+|--------|----------|-------------|
+| `Content-Type` | Yes | Must be `application/json` |


The Authentication section says every request requires Content-Type: application/json, but the GET status endpoint examples/headers omit it. Either make Content-Type conditional (e.g., only required for requests with a JSON body) or include it consistently in the Verify Status section/examples.

Suggested change

| `Content-Type` | Yes | Must be `application/json` |

| `Content-Type` | Conditional | Must be `application/json` for requests with a JSON body |

Copilot · 2026-03-06T12:19:00Z

payments/ecommerce/integration.mdx

+        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


In the Mermaid diagram, the return redirect query string uses payment_id=id, which doesn’t match the rest of the guide’s placeholder ({paymentId}) and could mislead integrators copying the URL format. Update the diagram placeholders to consistently use paymentId (or {paymentId}) for the appended query param.

Suggested change

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

BX->>MF: Redirect to successUrl?paymentId={paymentId}

else Payment fails

BX->>MF: Redirect to errorUrl?paymentId={paymentId}

end

MF->>MB: Verify payment status

MB->>API: GET /v1/merchant/payment/{paymentId}/status

Copilot · 2026-03-06T12:19:01Z

payments/ecommerce/integration.mdx

+    // Extract the payment ID from the redirect URL
+    const url = new URL(window.location.href);
+    const paymentId = url.searchParams.get("payment_id");
+


url.searchParams.get("payment_id") can return null, but the example immediately passes paymentId into verifyPayment(...). Add a guard/error handling (or reflect the nullable type) so the example remains valid TypeScript and doesn’t imply payment_id is always present.

Suggested change

if (!paymentId) {

throw new Error("Missing payment_id in URL");

}

Copilot · 2026-03-06T12:19:01Z

payments/ecommerce/integration.mdx

+    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
+    }


In the server-side verification example, fulfillOrder(orderId) references orderId which is not defined anywhere in the snippet, making the example non-runnable and ambiguous about how to correlate the payment back to an order. Use a defined identifier (e.g., the order you stored alongside paymentId / referenceId) or clarify where orderId comes from.

Copilot · 2026-03-06T12:19:01Z

payments/ecommerce/integration.mdx

+    // 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();


The integration flow currently shows taking the payment_id query parameter from the redirect URL and passing it directly to your backend to decide whether to fulfill an order. Because buyers can tamper with the URL, this pattern allows replay or substitution of a previously successful paymentId to mark a different order as paid if the backend relies only on status for fulfillment. Instead, treat the redirect payment_id as an untrusted hint: look up the expected paymentId for the current order from your own database (or verify the referenceId/amount against your records) and only fulfill the order if the verified payment matches that specific order.

Copilot AI review requested due to automatic review settings March 6, 2026 12:12

Copilot started reviewing on behalf of tomiir March 6, 2026 12:13 View session

mintlify bot deployed to staging March 6, 2026 12:13 View deployment

Copilot AI reviewed Mar 6, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add ecommerce checkout integration guide#27

docs: add ecommerce checkout integration guide#27
tomiir wants to merge 1 commit intomainfrom
tomiir/buyer-checkout-docs

tomiir commented Mar 6, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 6, 2026

Uh oh!

Copilot AI Mar 6, 2026

Uh oh!

Copilot AI Mar 6, 2026

Uh oh!

Copilot AI Mar 6, 2026

Uh oh!

Copilot AI Mar 6, 2026

Uh oh!

Copilot AI Mar 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	\| `Content-Type` \| Yes \| Must be `application/json` \|
	\| `Content-Type` \| Conditional \| Must be `application/json` for requests with a JSON body \|

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

Conversation

tomiir commented Mar 6, 2026

Summary

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants