Cloudbase Wechat Integration

CloudBase WeChat Integration

This skill routes WeChat payment and official-account work through CloudBase Integration Center. It gives the agent the stable execution contract and points to official index.md docs for console details that may change.

Standalone Install Note

This skill is designed to work when distributed independently on platforms such as OpenClaw. If sibling CloudBase skills are unavailable, use the references in this skill directory plus the official index.md documentation links in each reference file.

• CloudBase main entry: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/SKILL.md
• Current skill raw source: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloudbase-wechat-integration/SKILL.md
• CloudBase Integration Center overview: https://docs.cloudbase.net/integration/introduce/index.md
• CloudBase Integration Center usage: https://docs.cloudbase.net/integration/usage/index.md
• When cloud function deployment or log operations are needed and no sibling skill is available, use the current platform's CloudBase MCP tools or CloudBase console instead of guessing unsupported APIs.

Activation Contract

Use this first when

• The user asks about WeChat Pay, 小程序支付, 微信支付, JSAPI 支付, 公众号支付, Native 扫码支付, 二维码支付, refund callbacks, payment callbacks, wx.requestPayment, WeixinJSBridge, openid, or Official Account OAuth in a CloudBase app.
• The task mentions CloudBase Integration Center, 集成中心, generated payment functions, pay-common, offiaccount-common, or callback routing for WeChat payment.
• The user needs to extend a CloudBase Integration Center generated function with order persistence, idempotency, fulfillment, or payment-status sync.

Then also read

• Mini Program structure and preview work -> ../miniprogram-development/SKILL.md (standalone fallback: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/miniprogram-development/SKILL.md; if unavailable, use the current mini program platform docs and the mini-program payment reference in this skill)
• Web frontend work -> ../web-development/SKILL.md (standalone fallback: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/web-development/SKILL.md; if unavailable, use the JSAPI or Native references in this skill)
• Cloud function runtime, logs, deployment, or gateway work -> ../cloud-functions/SKILL.md (standalone fallback: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloud-functions/SKILL.md; if unavailable, use CloudBase console/MCP function tools and the generated-function guidance in this skill)

Do NOT use for

• Generic CloudBase Web Auth or Mini Program native identity work that does not involve WeChat payment or official-account OAuth.
• General CloudBase cloud function development unrelated to Integration Center generated functions.
• Creating or managing Integration Center instances through guessed MCP tools, guessed Manager SDK methods, or undocumented Cloud API actions.
• Storing merchant secrets, private keys, APIv3 keys, AppSecret values, or certificates in app source code, generated examples, README files, commits, or prompts.

Operating Rules

1. Treat Integration Center creation as a console-first workflow unless a public Manager SDK or Cloud API contract is confirmed in official docs. 2. Use official index.md docs for console UI steps and credential fields; do not copy stale console screenshots or invent field names. 3. Never ask the user to paste secrets into chat. Tell them to configure merchant and official-account credentials in the CloudBase console Integration Center form. 4. Do not assume generated function names are fixed. pay-common and offiaccount-common are examples; ask for or inspect the actual function name before writing calls. 5. Treat frontend payment success as UI feedback only. The authoritative payment state must come from server-side query results or payment callbacks. 6. When extending generated functions, preserve credential environment variables and generated callback verification/decryption logic. Add business logic around order checks, persistence, idempotency, and fulfillment. 7. Before changing payment or callback code, identify the target scenario and load only the matching reference file.

Routing

Quick Workflow

1. Classify the scenario: Mini Program Pay, JSAPI Pay, Native Pay, Official Account OAuth, generated-function extension, or troubleshooting. 2. Load the matching reference and the official index.md docs linked there. 3. Confirm the actual CloudBase environment ID and generated function name. 4. Generate or modify only the required client/backend code; keep merchant credentials in Integration Center configuration. 5. Add order-status query, callback idempotency, and amount/order validation when payment state affects business data. 6. Verify through function logs, callback logs, and an end-to-end payment sandbox or low-value production test as appropriate.

Minimum Self-Check

• Did I avoid guessing undocumented Integration Center management APIs?
• Did I use the actual generated function name instead of assuming pay-common?
• Did I keep all merchant secrets and certificates out of source code and chat?
• Did the payment flow rely on callback/query state rather than only frontend success?
• Did I load only the scenario reference needed for the user's task?

Mini Program WeChat Pay

Official docs:

• https://docs.cloudbase.net/integration/wechat-pay-miniprogram/index.md
• https://docs.cloudbase.net/integration/usage/index.md

When To Use

Use this reference for WeChat Mini Program payment flows on CloudBase, including 小程序微信支付, wx.cloud.callHTTPFunction, wx.requestPayment, Mini Program openid handling, payment callbacks, refunds, and order-status sync.

Agent Must Know

• The CloudBase Integration Center generated payment function is an HTTP cloud function.
• pay-common is an example function name; use the actual generated function name.
• Mini Program openid can be injected by CloudBase when calling through the Mini Program cloud function path.
• The client-side wx.requestPayment success callback is not the final business truth.
• Fulfillment must be driven by callback handling or explicit order query.

Minimal Contract

Typical Mini Program flow:

1. Mini Program calls the generated payment function over wx.cloud.callHTTPFunction. 2. The request path targets the generated payment route, commonly an order-creation path such as /wx-pay/wxpay_order. 3. The generated function returns payment parameters for wx.requestPayment. 4. The Mini Program invokes wx.requestPayment. 5. Backend callback or query logic confirms paid state before updating business data.

Example shape:

const functionName = "replace-with-generated-payment-function";

const orderResult = await wx.cloud.callHTTPFunction({
  name: functionName,
  path: "/wx-pay/wxpay_order",
  data: {
    out_trade_no: orderId,
    description: "Order payment",
    amount: {
      total: 1,
      currency: "CNY",
    },
  },
});

// callHTTPFunction returns { data, statusCode, header }
// The generated function typically returns { code, data, message }
// Payment params are under orderResult.data.data
const payment = orderResult.data?.data;
if (!payment) {
  throw new Error("Missing payment parameters from CloudBase payment function");
}

await wx.requestPayment(payment);

Adjust field names to the official docs and the generated function contract before using in production.

Implementation Checklist

• Confirm wx.cloud.init({ env }) uses the canonical full CloudBase environment ID.
• Confirm the Mini Program AppID matches the WeChat Pay merchant binding.
• Confirm the generated function name and path in CloudBase console.
• Generate a unique out_trade_no on the backend or trusted business layer.
• Validate amount and product data server-side before creating payment.
• Persist pending order state before initiating payment.
• Handle payment callback idempotently.
• Query the order after client payment success before showing final fulfillment state.

Common Extensions

• Write order and payment status to CloudBase database.
• Add an idempotency key on out_trade_no.
• Add fulfillment only after callback/query confirms success.
• Add refund initiation and refund callback handling if the product supports refunds.

Do Not

• Do not place merchant keys or certificates in Mini Program code.
• Do not trust client-provided amount without server-side validation.
• Do not assume frontend success means the order is paid.
• Do not hard-code pay-common if the console generated a different function name.

Native QR-Code Pay

Official docs:

• https://docs.cloudbase.net/integration/wechat-pay-native/index.md
• https://docs.cloudbase.net/integration/usage/index.md

When To Use

Use this reference for PC/Web checkout, Native WeChat Pay, QR-code payment, or flows where the generated function returns a payment code_url for the frontend to render as a QR code.

Agent Must Know

• Native payment does not use wx.requestPayment or WeixinJSBridge.
• The generated payment function creates an order and returns a QR-code URL such as code_url.
• The frontend renders the QR code and polls or subscribes to payment state.
• Fulfillment must wait for callback or query confirmation.

Minimal Contract

Typical Native flow:

1. Backend or frontend calls the generated payment function to create a Native order. 2. The generated function returns code_url. 3. The frontend renders code_url as a QR code. 4. The user scans the QR code in WeChat. 5. The app polls order status or waits for callback-driven state changes.

Example frontend shape:

async function createNativePayment(orderId) {
  const response = await fetch("/api/pay/native-order", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ orderId }),
  });
  const data = await response.json();
  if (!data.code_url) {
    throw new Error("Missing Native payment code_url");
  }
  return data.code_url;
}

In CloudBase frontend-only projects, the API wrapper can call the generated HTTP function directly if the access model and CORS/security rules are appropriate. For production, prefer a trusted backend or generated function extension that validates amount and order ownership.

Implementation Checklist

• Confirm this is Native QR-code payment, not JSAPI or Mini Program payment.
• Confirm generated function name and Native order path.
• Generate a unique order number and persist pending state.
• Validate amount and goods details before creating payment.
• Render QR code from code_url.
• Poll order status with backoff, or update UI from callback-driven status.
• Expire stale QR codes and handle closed orders.

Do Not

• Do not call wx.requestPayment for Native QR-code pay.
• Do not fulfill the order when the QR code is generated.
• Do not rely on frontend polling alone if callback data says otherwise.

Official Account JSAPI Pay

Official docs:

• https://docs.cloudbase.net/integration/wechat-pay-jsapi-h5/index.md
• https://docs.cloudbase.net/integration/wechat-official-oauth/index.md
• https://docs.cloudbase.net/integration/usage/index.md

When To Use

Use this reference for WeChat Official Account webpage payment, JSAPI payment inside the WeChat browser, H5 checkout that calls WeixinJSBridge.invoke, and flows that need an official-account openid before creating the payment order.

Agent Must Know

• JSAPI payment requires the page to run in the WeChat built-in browser.
• The payer openid must belong to the correct Official Account, not the Mini Program openid.
• Official Account OAuth is commonly needed before JSAPI order creation.
• The generated payment function name and routes must be read from the user's Integration Center setup.
• Final business state still depends on payment callback or order query.

Minimal Contract

Typical JSAPI flow:

1. Redirect the user through Official Account OAuth to get an openid. 2. Call the generated payment function to create a JSAPI order. 3. Pass returned payment parameters to WeixinJSBridge.invoke("getBrandWCPayRequest", ...). 4. Use payment callback or order query to confirm paid state.

Example invocation shape:

function invokeJsapiPay(paymentParams) {
  return new Promise((resolve, reject) => {
    if (!window.WeixinJSBridge) {
      reject(new Error("WeixinJSBridge is unavailable; open this page in WeChat"));
      return;
    }

    window.WeixinJSBridge.invoke(
      "getBrandWCPayRequest",
      paymentParams,
      (res) => {
        if (res.err_msg === "get_brand_wcpay_request:ok") {
          resolve(res);
          return;
        }
        reject(new Error(res.err_msg || "JSAPI payment failed"));
      },
    );
  });
}

Adjust request paths and parameter names to the generated function contract and official docs.

Implementation Checklist

• Confirm the app is an Official Account web flow, not a Mini Program page.
• Confirm the page runs inside WeChat before showing JSAPI checkout.
• Obtain the Official Account openid through OAuth before order creation.
• Confirm merchant account binding matches the Official Account AppID.
• Persist pending order state before invoking payment.
• Confirm paid state through callback or query before fulfillment.

Do Not

• Do not reuse Mini Program openid for Official Account JSAPI pay.
• Do not show JSAPI checkout in a normal desktop browser.
• Do not put AppSecret, merchant private keys, or APIv3 keys in browser code.

Official Account OAuth

Official docs:

• https://docs.cloudbase.net/integration/wechat-official-oauth/index.md
• https://docs.cloudbase.net/integration/usage/index.md

When To Use

Use this reference for WeChat Official Account OAuth, openid retrieval, userinfo retrieval, token refresh, OAuth config inspection, or preparation for Official Account JSAPI payment.

Agent Must Know

• Official Account openid is different from Mini Program openid.
• OAuth credentials should be configured through CloudBase Integration Center, not embedded in frontend code.
• The generated official-account function name may differ from example names such as offiaccount-common.
• OAuth route names must be confirmed from the generated function and official docs.

Minimal Contract

Common generated OAuth routes include:

• /oauth/config
• /oauth/token
• /oauth/refresh
• /oauth/userinfo
• /oauth/verify

Typical flow:

1. Get OAuth config or construct the authorization URL according to the generated function contract. 2. Redirect the user to WeChat authorization. 3. Exchange the returned code for token/openid through the generated function. 4. Optionally fetch userinfo if the scope and product requirement allow it. 5. Store only the user identifiers and business-safe profile fields required by the app.

Example exchange shape:

async function exchangeOfficialAccountCode(code) {
  const response = await fetch("/api/wechat/oauth/token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ code }),
  });
  const data = await response.json();
  if (!data.openid) {
    throw new Error("Missing Official Account openid");
  }
  return data;
}

Use the actual generated function path or an application backend wrapper instead of copying this path literally.

Implementation Checklist

• Confirm the target is an Official Account web scenario.
• Confirm OAuth callback domain and redirect URI are configured.
• Confirm the generated function name and OAuth routes.
• Decide whether the product needs only openid or also userinfo.
• Store tokens securely if refresh is required.
• For JSAPI pay, pass the Official Account openid into the payment order creation flow.

Do Not

• Do not expose AppSecret in browser code.
• Do not confuse Official Account openid with Mini Program openid.
• Do not request userinfo scope unless the product actually needs profile data.

CloudBase WeChat Integration Overview

Official docs:

• https://docs.cloudbase.net/integration/introduce/index.md
• https://docs.cloudbase.net/integration/usage/index.md

What Integration Center Provides

CloudBase Integration Center is a console-driven capability for connecting third-party services to CloudBase. For WeChat scenarios, it can generate HTTP cloud functions, inject configuration through managed environment variables, and handle platform-specific callback verification or decryption.

Use this skill for the application-side work around those integrations:

• generating client calls to the generated functions
• adding order persistence, idempotency, and fulfillment logic
• diagnosing callback, credential, and routing issues
• guiding the user through console setup without collecting secrets

Agent Must Know

• Creation and credential binding are console-first unless official public API support is confirmed.
• Generated function names may vary. Examples such as pay-common and offiaccount-common are not a contract.
• Merchant secrets, private keys, APIv3 keys, AppSecret values, and certificates belong in CloudBase console configuration, not in source code.
• The payment callback or order-query result is the authoritative state for business fulfillment.
• Generated functions should be treated as platform-managed templates with safe business extensions, not as blank custom functions.

Scenario Map

Console-First Setup Checklist

1. Confirm the CloudBase environment ID. 2. Open Integration Center in the CloudBase console. 3. Choose the matching WeChat integration type. 4. Fill merchant or official-account credentials in the console form. 5. Record the generated function name and HTTP route paths. 6. Run a minimal call before adding business logic. 7. Add business data handling after the generated function works.

Independent Distribution Notes

When this skill is installed alone:

• Use only the references in this directory plus the official docs above.
• If no CloudBase MCP tools are available, guide the user to inspect function logs and configuration in the console.
• Do not reference local repository paths that may not exist in the target platform.

WeChat Integration Troubleshooting

Official docs:

• https://docs.cloudbase.net/integration/introduce/index.md
• https://docs.cloudbase.net/integration/usage/index.md
• https://docs.cloudbase.net/integration/wechat-pay-miniprogram/index.md
• https://docs.cloudbase.net/integration/wechat-pay-jsapi-h5/index.md
• https://docs.cloudbase.net/integration/wechat-pay-native/index.md
• https://docs.cloudbase.net/integration/wechat-official-oauth/index.md

First Checks

1. Confirm the scenario: Mini Program Pay, JSAPI Pay, Native Pay, or Official Account OAuth. 2. Confirm the CloudBase environment ID. 3. Confirm the actual generated function name. 4. Confirm the exact route path from Integration Center or generated function docs. 5. Check cloud function logs before changing code. 6. Check whether the issue is credential setup, route mismatch, callback delivery, or business logic.

Common Symptoms

404 or route not found

Likely causes:

• wrong function name
• wrong HTTP path
• calling Mini Program payment path from the wrong client
• generated function was deleted or redeployed incorrectly

Actions:

• inspect the generated function routes
• confirm the call target uses the actual function name
• check CloudBase function logs and HTTP access logs

Missing credentials or credential initialization errors

Likely causes:

• Integration Center form is incomplete
• merchant certificate/APIv3 key/private key was not configured
• function environment variables were removed or overwritten

Actions:

• re-check Integration Center credential configuration in the console
• do not paste secrets into code or chat
• restore generated environment variables if they were overwritten

Openid mismatch

Likely causes:

• Mini Program openid used for Official Account JSAPI pay
• Official Account AppID does not match merchant binding
• user authorized a different app than the one used for payment

Actions:

• identify whether the flow needs Mini Program openid or Official Account openid
• verify AppID and merchant binding
• rerun OAuth or Mini Program call in the correct client context

Payment succeeds in frontend but order is not fulfilled

Likely causes:

• business logic trusts frontend success only
• callback did not reach the generated function
• callback handler is not idempotent
• order status query is missing

Actions:

• use callback or query as the authoritative payment state
• add idempotent order update logic
• inspect payment callback logs
• verify out_trade_no maps to the application's order record

Callback not received

Likely causes:

• merchant platform notification URL is wrong
• callback path does not match generated function route
• APIv3 key/certificate mismatch prevents verification/decryption
• function security or deployment issue

Actions:

• check Integration Center callback configuration
• check merchant platform callback settings
• inspect generated function logs
• retry with a low-value test order after fixing configuration

callHTTPFunction is not a function

Likely causes:

• Mini Program base library or CloudBase SDK capability is too old
• the project is not initialized with wx.cloud.init
• the flow is running outside Mini Program runtime

Actions:

• confirm Mini Program runtime and base library support
• initialize CloudBase with the canonical full environment ID
• use the correct client flow for Web/JSAPI/Native scenarios

Before Editing Generated Code

• Keep generated credential handling intact.
• Add business logic around generated handlers instead of replacing verification/decryption logic.
• Preserve callback idempotency and order lookup.
• Keep secrets out of source code.