From d6b717d718720a016daa9cc6a84335b67ab7b908 Mon Sep 17 00:00:00 2001 From: Tomas R Date: Tue, 8 Sep 2026 14:11:47 -0300 Subject: [PATCH 1/4] docs: document Headless SDK access request and credentials Add a "Request access and collect the Keys" section to the Headless SDK overview covering the Developers -> API Keys dashboard flow, and update the implementation prerequisites and env vars to match the credentials that flow hands out. Co-Authored-By: Claude Opus 5 (1M context) --- payments/psps/headless-sdk/implementation.mdx | 10 +++-- payments/psps/headless-sdk/overview.mdx | 37 +++++++++++++++++++ payments/psps/overview.mdx | 2 + 3 files changed, 45 insertions(+), 4 deletions(-) diff --git a/payments/psps/headless-sdk/implementation.mdx b/payments/psps/headless-sdk/implementation.mdx index 979aeea..fe1b243 100644 --- a/payments/psps/headless-sdk/implementation.mdx +++ b/payments/psps/headless-sdk/implementation.mdx @@ -33,8 +33,10 @@ The wallet seam, the signer, and the clock all come from the SDK. Then `usePayme ## Prerequisites - **Node 18+**. The React example uses **Next.js** (App Router); the JavaScript example is framework-neutral. -- A **Reown Project ID** — create one at [dashboard.reown.com](https://dashboard.reown.com). Enable the **headless** feature on the project. -- A **WalletConnect Pay Gateway API key** for the WCP API (server-side). [Talk to us](https://share.hsforms.com/1XsMCkUxFT2Cte8SCeAh89wnxw6s) to get onboarded. +- **Headless checkout access** on your WalletConnect Pay account — request it from **Developers → API Keys** in the [dashboard](https://merchant.pay.walletconnect.com/en/api-keys). See [Request access and collect the Keys](/payments/psps/headless-sdk/overview#request-access-and-collect-the-keys). +- A **Reown project ID**, shown on the **Headless checkout** card once access is granted (public — used for wallet connection). +- A **Gateway wallet key** (prefix `wcw_`), created from the same card. Secret — server-side only. +- A **WalletConnect Pay key** (prefix `wcp_`, or `wcp_test_` for [test mode](/payments/test-mode)) from the same **API Keys** section, for creating payments through the Merchant API. ## Install @@ -340,10 +342,10 @@ That's a full gateway. Connect → options → (optional KYC) → confirm → si ## Environment variables ```bash .env.local -# Reown AppKit project ID — required for wallet connection / QR pairing (public) +# Reown project ID from the Headless checkout card — wallet connection / QR pairing (public) NEXT_PUBLIC_APPKIT_PROJECT_ID= -# WalletConnect Pay (WCP) API — server-side only, NEVER exposed to the browser +# Gateway wallet key (wcw_…) — server-side only, NEVER exposed to the browser WCP_API_URL=https://staging.api.pay.walletconnect.org WCP_WALLET_API_KEY= ``` diff --git a/payments/psps/headless-sdk/overview.mdx b/payments/psps/headless-sdk/overview.mdx index 2c7bc33..100eecf 100644 --- a/payments/psps/headless-sdk/overview.mdx +++ b/payments/psps/headless-sdk/overview.mdx @@ -51,6 +51,43 @@ If you just want to accept payments with the least effort, use the [hosted gatew The Headless SDK supports the full WalletConnect Pay token and network coverage — USDC, USDT, EURC, PYUSD and more across Ethereum, Polygon, Base, Optimism, Arbitrum (and Solana, rolling out). See [Token & chain coverage](/payments/token-and-chain-coverage) for the live list. +## Request access and collect the Keys + +The Headless SDK is gated. Access is granted per account from the WalletConnect Pay dashboard. + + + + + +Go to **Developers → API Keys** in the dashboard and sign in if prompted. + + + + + +Find the **Headless checkout** card and click **Request access**. The WalletConnect Pay team reviews the request and gets back to you. + + + + + +Once access is granted, the **Headless checkout** card exposes the credentials for embedding the SDK: + +- A **Reown project ID** — used to configure the Headless feature in Reown AppKit. It is public. +- A **Gateway wallet key** button — each key (prefix `wcw_`) authenticates your server against the WalletConnect Pay API. + + + + + +In the same **API Keys** section, copy your **WalletConnect Pay key** (prefix `wcp_` for live, `wcp_test_` for test) — the Merchant API key used to create payments. See [Test mode](/payments/test-mode) for the difference between the two. + + + + + +With the Reown project ID, a Gateway wallet key, and a WalletConnect Pay key, you have everything needed to run the Headless SDK end to end. Map them to environment variables as shown in [Implementation](/payments/psps/headless-sdk/implementation#environment-variables). + ## Full example The fastest way to learn the SDK is to read the reference checkout it's extracted from. Every snippet in these docs comes from it. diff --git a/payments/psps/overview.mdx b/payments/psps/overview.mdx index 95a938e..1f596a6 100644 --- a/payments/psps/overview.mdx +++ b/payments/psps/overview.mdx @@ -25,6 +25,8 @@ Reach for the **hosted gateway** if you want to accept payments with the least e Reach for the **Headless SDK** when you need to **own the experience** end to end — wallet selection, network and token choice, compliance prompts, success and error states — all inside your own design system and domain, with no redirect to a third-party page. +The Headless SDK is gated: request access from **Developers → API Keys** in the [dashboard](https://merchant.pay.walletconnect.com/en/api-keys) — see [Request access and collect the Keys](/payments/psps/headless-sdk/overview#request-access-and-collect-the-keys). + Both paths run on the same WCP backend and share the same token and network coverage. You can start with the hosted gateway and move to the Headless SDK later without re-doing your backend integration. From c503fb322eb8a878db5ca96b6a76ebac03440b04 Mon Sep 17 00:00:00 2001 From: Tomas R Date: Tue, 8 Sep 2026 14:12:27 -0300 Subject: [PATCH 2/4] docs: lowercase "keys" in Headless SDK access section heading Co-Authored-By: Claude Opus 5 (1M context) --- payments/psps/headless-sdk/implementation.mdx | 2 +- payments/psps/headless-sdk/overview.mdx | 2 +- payments/psps/overview.mdx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/payments/psps/headless-sdk/implementation.mdx b/payments/psps/headless-sdk/implementation.mdx index fe1b243..c437d69 100644 --- a/payments/psps/headless-sdk/implementation.mdx +++ b/payments/psps/headless-sdk/implementation.mdx @@ -33,7 +33,7 @@ The wallet seam, the signer, and the clock all come from the SDK. Then `usePayme ## Prerequisites - **Node 18+**. The React example uses **Next.js** (App Router); the JavaScript example is framework-neutral. -- **Headless checkout access** on your WalletConnect Pay account — request it from **Developers → API Keys** in the [dashboard](https://merchant.pay.walletconnect.com/en/api-keys). See [Request access and collect the Keys](/payments/psps/headless-sdk/overview#request-access-and-collect-the-keys). +- **Headless checkout access** on your WalletConnect Pay account — request it from **Developers → API Keys** in the [dashboard](https://merchant.pay.walletconnect.com/en/api-keys). See [Request access and collect the keys](/payments/psps/headless-sdk/overview#request-access-and-collect-the-keys). - A **Reown project ID**, shown on the **Headless checkout** card once access is granted (public — used for wallet connection). - A **Gateway wallet key** (prefix `wcw_`), created from the same card. Secret — server-side only. - A **WalletConnect Pay key** (prefix `wcp_`, or `wcp_test_` for [test mode](/payments/test-mode)) from the same **API Keys** section, for creating payments through the Merchant API. diff --git a/payments/psps/headless-sdk/overview.mdx b/payments/psps/headless-sdk/overview.mdx index 100eecf..3e2e153 100644 --- a/payments/psps/headless-sdk/overview.mdx +++ b/payments/psps/headless-sdk/overview.mdx @@ -51,7 +51,7 @@ If you just want to accept payments with the least effort, use the [hosted gatew The Headless SDK supports the full WalletConnect Pay token and network coverage — USDC, USDT, EURC, PYUSD and more across Ethereum, Polygon, Base, Optimism, Arbitrum (and Solana, rolling out). See [Token & chain coverage](/payments/token-and-chain-coverage) for the live list. -## Request access and collect the Keys +## Request access and collect the keys The Headless SDK is gated. Access is granted per account from the WalletConnect Pay dashboard. diff --git a/payments/psps/overview.mdx b/payments/psps/overview.mdx index 1f596a6..f79bdb8 100644 --- a/payments/psps/overview.mdx +++ b/payments/psps/overview.mdx @@ -25,7 +25,7 @@ Reach for the **hosted gateway** if you want to accept payments with the least e Reach for the **Headless SDK** when you need to **own the experience** end to end — wallet selection, network and token choice, compliance prompts, success and error states — all inside your own design system and domain, with no redirect to a third-party page. -The Headless SDK is gated: request access from **Developers → API Keys** in the [dashboard](https://merchant.pay.walletconnect.com/en/api-keys) — see [Request access and collect the Keys](/payments/psps/headless-sdk/overview#request-access-and-collect-the-keys). +The Headless SDK is gated: request access from **Developers → API Keys** in the [dashboard](https://merchant.pay.walletconnect.com/en/api-keys) — see [Request access and collect the keys](/payments/psps/headless-sdk/overview#request-access-and-collect-the-keys). Both paths run on the same WCP backend and share the same token and network coverage. You can start with the hosted gateway and move to the Headless SDK later without re-doing your backend integration. From 7a1acb5234437c332314f3682f42b39b2d05842e Mon Sep 17 00:00:00 2001 From: Tomas R Date: Tue, 8 Sep 2026 14:15:05 -0300 Subject: [PATCH 3/4] docs: link the WalletConnect Pay dashboard in the access section Co-Authored-By: Claude Opus 5 (1M context) --- payments/psps/headless-sdk/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/payments/psps/headless-sdk/overview.mdx b/payments/psps/headless-sdk/overview.mdx index 3e2e153..d30206c 100644 --- a/payments/psps/headless-sdk/overview.mdx +++ b/payments/psps/headless-sdk/overview.mdx @@ -53,7 +53,7 @@ The Headless SDK supports the full WalletConnect Pay token and network coverage ## Request access and collect the keys -The Headless SDK is gated. Access is granted per account from the WalletConnect Pay dashboard. +The Headless SDK is gated. Access is granted per account from the [WalletConnect Pay dashboard](https://merchant.pay.walletconnect.com/). From 6c5985f18042b0cc081fa8c2058ee81961f2b1a4 Mon Sep 17 00:00:00 2001 From: Tomas R Date: Tue, 8 Sep 2026 18:14:40 -0300 Subject: [PATCH 4/4] docs: trim the Reown project ID prerequisite note Co-Authored-By: Claude Opus 5 (1M context) --- payments/psps/headless-sdk/implementation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/payments/psps/headless-sdk/implementation.mdx b/payments/psps/headless-sdk/implementation.mdx index c437d69..e0f6c9a 100644 --- a/payments/psps/headless-sdk/implementation.mdx +++ b/payments/psps/headless-sdk/implementation.mdx @@ -34,7 +34,7 @@ The wallet seam, the signer, and the clock all come from the SDK. Then `usePayme - **Node 18+**. The React example uses **Next.js** (App Router); the JavaScript example is framework-neutral. - **Headless checkout access** on your WalletConnect Pay account — request it from **Developers → API Keys** in the [dashboard](https://merchant.pay.walletconnect.com/en/api-keys). See [Request access and collect the keys](/payments/psps/headless-sdk/overview#request-access-and-collect-the-keys). -- A **Reown project ID**, shown on the **Headless checkout** card once access is granted (public — used for wallet connection). +- A **Reown project ID**, shown on the **Headless checkout** card once access is granted (public). - A **Gateway wallet key** (prefix `wcw_`), created from the same card. Secret — server-side only. - A **WalletConnect Pay key** (prefix `wcp_`, or `wcp_test_` for [test mode](/payments/test-mode)) from the same **API Keys** section, for creating payments through the Merchant API.