From f78d08b48d92da5eaf424d4e5524bf427088eaeb Mon Sep 17 00:00:00 2001 From: Enes Date: Thu, 27 Aug 2026 15:32:16 +0300 Subject: [PATCH 1/3] docs(headless-sdk): add a Test mode section How to run the full flow with no real wallet and no real funds: a `wcp_test_` API key on the proxy + the `testMode` flag on usePaymentSession / createPaymentController, plus the extra `/transition` proxy route the test transport calls. Notes that both the client flag and the server test key are required. Co-Authored-By: Claude Opus 4.8 (1M context) --- payments/psps/headless-sdk/implementation.mdx | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/payments/psps/headless-sdk/implementation.mdx b/payments/psps/headless-sdk/implementation.mdx index f2d4996..032b1e1 100644 --- a/payments/psps/headless-sdk/implementation.mdx +++ b/payments/psps/headless-sdk/implementation.mdx @@ -337,6 +337,33 @@ switch (snapshot.state) { That's a full gateway. Connect → options → (optional KYC) → confirm → sign → settle, all driven by the runtime; you only render and call actions. Once a wallet is connected, `disconnectWallet(namespace?)` drops one namespace or all of them. +## Test mode + +Build and click through the whole flow **without a real wallet or real funds** — two pieces: + +1. **A test API key** on your server proxy. Create a `wcp_test_…` key in the [dashboard](https://merchant.pay.walletconnect.com/en/api-keys) and use it as `WCP_WALLET_API_KEY`. Payments created and driven with a test key settle synthetically — nothing runs on-chain (see [Test mode](/payments/test-mode)). +2. **The `testMode` flag** on the session. Pass your normal `seams` + `wallet` and set `testMode`; the SDK swaps in a mock wallet (already connected to a funded address, so options load with no wallet-connect step), a mock signer, and commits via the test `/transition` endpoint instead of `/confirm` (auto-settling to `succeeded`). Remove the flag for the real flow — the same code. + + +```tsx React +usePaymentSession({ paymentId, seams, wallet, testMode: true }) +``` + +```typescript JavaScript +createPaymentController({ paymentId, seams, wallet, testMode: true }) +``` + + +Your proxy must also expose the transition route the test transport calls (alongside the five from [Step 1](#step-1-—-server-proxy-keep-the-api-key-server-side)): + +| Route Handler | Method | WCP call | +| ----------------------------------------------- | ------ | ------------ | +| `app/api/wcp/payment/[id]/transition/route.ts` | `POST` | `transition` | + + + Test mode is client **and** server: the flag mocks the wallet + signer in the browser, and the **test API key** makes WCP treat the payment as a test payment (and allow `/transition`). Both are required — a test key alone still runs the real wallet/sign path, and the flag alone hits a live key that rejects `/transition`. + + ## Environment variables ```bash .env.local From c9fc81c9c7e72403e0f733011c5c68ab7dcaa9a9 Mon Sep 17 00:00:00 2001 From: Enes Date: Thu, 27 Aug 2026 16:08:15 +0300 Subject: [PATCH 2/3] docs(headless-sdk): fix test API key dashboard path MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The /en/api-keys route does not exist; the key lives behind the navbar Live/Test dropdown → Developers → API Keys. --- 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 032b1e1..0760a73 100644 --- a/payments/psps/headless-sdk/implementation.mdx +++ b/payments/psps/headless-sdk/implementation.mdx @@ -341,7 +341,7 @@ That's a full gateway. Connect → options → (optional KYC) → confirm → si Build and click through the whole flow **without a real wallet or real funds** — two pieces: -1. **A test API key** on your server proxy. Create a `wcp_test_…` key in the [dashboard](https://merchant.pay.walletconnect.com/en/api-keys) and use it as `WCP_WALLET_API_KEY`. Payments created and driven with a test key settle synthetically — nothing runs on-chain (see [Test mode](/payments/test-mode)). +1. **A test API key** on your server proxy. In the [dashboard](https://merchant.pay.walletconnect.com), switch to **Test** with the navbar Live/Test dropdown, then open **Developers → API Keys** and create a `wcp_test_…` key; use it as `WCP_WALLET_API_KEY`. Payments created and driven with a test key settle synthetically — nothing runs on-chain (see [Test mode](/payments/test-mode)). 2. **The `testMode` flag** on the session. Pass your normal `seams` + `wallet` and set `testMode`; the SDK swaps in a mock wallet (already connected to a funded address, so options load with no wallet-connect step), a mock signer, and commits via the test `/transition` endpoint instead of `/confirm` (auto-settling to `succeeded`). Remove the flag for the real flow — the same code. From f8a8ebde6c5a371d7268480fdc7c342df2abe874 Mon Sep 17 00:00:00 2001 From: Enes Date: Thu, 27 Aug 2026 16:17:55 +0300 Subject: [PATCH 3/3] docs(headless-sdk): clarify test mode is a test payment, not a gateway key Test vs live is a property of the payment (created with a test merchant key), not of the proxy's wallet/gateway key. --- 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 0760a73..4b7baf6 100644 --- a/payments/psps/headless-sdk/implementation.mdx +++ b/payments/psps/headless-sdk/implementation.mdx @@ -341,7 +341,7 @@ That's a full gateway. Connect → options → (optional KYC) → confirm → si Build and click through the whole flow **without a real wallet or real funds** — two pieces: -1. **A test API key** on your server proxy. In the [dashboard](https://merchant.pay.walletconnect.com), switch to **Test** with the navbar Live/Test dropdown, then open **Developers → API Keys** and create a `wcp_test_…` key; use it as `WCP_WALLET_API_KEY`. Payments created and driven with a test key settle synthetically — nothing runs on-chain (see [Test mode](/payments/test-mode)). +1. **A test payment.** Create it with a **test merchant key** (`wcp_test_…`): in the [dashboard](https://merchant.pay.walletconnect.com), switch to **Test** with the navbar Live/Test dropdown, then open **Developers → API Keys**. Payments created with a test key are test payments — they settle synthetically, nothing runs on-chain (see [Test mode](/payments/test-mode)). Your proxy's own wallet/gateway key is unchanged; test vs live is a property of the payment, not the gateway key. 2. **The `testMode` flag** on the session. Pass your normal `seams` + `wallet` and set `testMode`; the SDK swaps in a mock wallet (already connected to a funded address, so options load with no wallet-connect step), a mock signer, and commits via the test `/transition` endpoint instead of `/confirm` (auto-settling to `succeeded`). Remove the flag for the real flow — the same code.