Skip to main content

Usage Flow

This article walks through the general usage flow of Integration Center, including how to create an integration, invoke an integration function, view runtime status, modify configuration, and delete integrations. For onboarding details of specific integration types (such as WeChat Pay), refer to the corresponding integration guide.

Prerequisites​

Before using Integration Center, please confirm:

  • A CloudBase environment has been activated
  • The current account has both "Integration Management" and "Cloud Function Management" permissions in this environment
  • The credentials required by the third-party service to be integrated (merchant ID, API key, certificate, etc.) are ready — refer to the integration details for the exact list

Create an Integration​

1. Enter Integration Center​

After logging in to the CloudBase console, select Templates & Integrations → Integration Center in the left menu, or directly visit the Integration Center home page.

The page lists all available integration types, grouped by category (Payment, Official Account, AI, Messaging, etc.).

2. Choose an Integration Type​

Click the target integration card (e.g. "Mini Program WeChat Pay") to enter the integration detail page. The detail page shows:

  • Capability description: which features the integration provides and the scope of third-party APIs covered
  • Onboarding doc link: full onboarding steps and sample code
  • Create entry: the "Create Integration" button in the upper-right corner

3. Fill in Integration Information​

After clicking "Create Integration", fill out the form:

  • Integration name: a custom identifier; lowercase letters and hyphens are recommended (e.g. miniapp-wxpay). This name will be used as the prefix of the generated cloud function name.
  • Credential fields: vary by integration type (merchant ID, APIv3 key, certificate content, etc.). Each field has a hint pointing to where to obtain the value.
  • Optional advanced settings: Some integrations support custom callback paths, debug-mode toggles, etc.

Please double-check before submitting, especially PEM-format certificates and keys — when pasting they easily lose newlines (replaced with spaces) or have missing leading/trailing lines, which causes downstream invocation failures.

4. Wait for Resources to Be Created​

After submission, the platform asynchronously completes the following operations (about 1–2 minutes):

ResourceDescription
HTTP cloud functionFunction name like <integration-name>-<random-string>, with template code preset
Environment variablesCredentials, callback URLs, etc. are injected into the function as env vars
Callback domainLike https://<integration-id>.integration-callback.tcloudbase.com
Callback routesReceiving paths for various asynchronous notifications (e.g. /wechatpay/order)

After creation, the integration detail page shows the actual values of all the resources above — copy them and use them.

Invoke the Integration Function​

The integration function is essentially an HTTP cloud function and can be called via any of the following methods:

The platform automatically injects user identity (x-wx-openid / x-wx-appid); no login or token is required:

wx.cloud.init({ env: 'your-env-id' })

wx.cloud.callHTTPFunction({
  name: 'miniapp-wxpay-rwmx67sc',     // actual function name (check after creation)
  config: { env: 'your-env-id' },
  method: 'POST',
  header: { 'Content-Type': 'application/json' },
  path: '/wx-pay/wxpay_order',         // Express standard route
  data: { /* business params */ },
  success: (res) => console.log(res.data),
  fail: console.error,
})

Mini Program base library version must be ≥ 3.15.2.

Call the cloud API gateway with a Bearer Token:

import cloudbase from '@cloudbase/js-sdk'

const app = cloudbase.init({ env: 'your-env-id' })
const auth = app.auth({ persistence: 'local' })
// ⚠️ "Authenticated login" is required (email, phone, custom login, etc.); anonymous login has no permission to call cloud functions
const accessToken = (await auth.signIn({ /* ... */ })).credential.accessToken

const res = await fetch(
  `https://your-env-id.api.tcloudbasegateway.com/v1/functions/miniapp-wxpay-rwmx67sc?webfn=true`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${accessToken}`,
    },
    body: JSON.stringify({ /* business params */ }),
  }
)
const body = await res.json()

Method 3: Server-Side SDK / HTTP Invocation​

Calling an integration function from a backend service is the same as calling a regular HTTP cloud function — see HTTP Access Service docs.

Handle Callbacks​

Asynchronous notifications from third-party services (payment results, message pushes, etc.) first arrive at the callback domain provided by Integration Center. After Integration Center completes signature verification and decryption, it forwards the plaintext to a specific route of the cloud function (e.g. /wechatpay/order).

The business side only needs to handle the plaintext data on the corresponding route in the cloud function code:

// pay-common/services/orderService.js (excerpt)
async function handlerUnifiedTrigger(params) {
  // params is already verified and decrypted plaintext
  // - params.out_trade_no
  // - params.transaction_id
  // - params.amount.total
  // - params.payer.openid
  
  // 1. Idempotency check: has the order already been processed?
  // 2. Amount cross-check: matches the amount at order time
  // 3. Atomic state update: PENDING → PAID
  // 4. Trigger business side effects: shipping, points, notifications, etc.
  
  return { code: 'SUCCESS' }   // must return within 5 seconds
}

Principles to follow when handling callbacks:

  • Return quickly: Return success within 5 seconds, otherwise the third party will retry
  • Idempotency: The same callback may be delivered repeatedly; multiple executions must produce the same result
  • Amount/signature cross-checks: In addition to the verification done by Integration Center, the business side is still recommended to cross-check key fields
  • Move time-consuming operations to async: Shipping, push notifications, external API calls, etc. should be dispatched to a queue or scheduled task

View and Manage Integrations​

View the Integration List​

Integration Center home page → "My Integrations" tab. View all integrations created in the current environment, including:

  • Integration name and type
  • Creation time, status (Running / Configuration Error / Stopped)
  • Associated cloud function name

View Integration Details​

Click any integration name to enter the detail page, where you can see:

  • Basic info: name, type, creation time
  • Associated resources: cloud function, callback domain, callback paths
  • Environment variables overview: all env vars currently injected into the function (credential fields are masked)
  • Callback logs: recent callback records, including source, status, latency, error code

Modify Integration Configuration​

The "Edit" button in the upper-right corner of the detail page lets you modify integration parameters. After saving, the platform will automatically redeploy the cloud function; the new configuration takes effect in about 1–2 minutes.

Common modification scenarios:

  • Credential rotation (e.g. APIv3 key updated upon expiry)
  • Switching between certificate mode and public-key mode
  • Adding optional fields (e.g. service_app_id for transfer scenarios)

⚠️ Requests in flight during modification may be affected; off-peak operation is recommended.

View Runtime Logs​

The integration function is essentially a cloud function. Logs can be viewed via:

  • Console → Cloud Functions → find the corresponding function → "Logs" tab
  • CLI: tcb fn log <function-name> --tail

A dedicated entry for callback logs is available on the integration detail page, including verification status and other integration-layer information.

Modify the Integration Function Code​

The cloud function code generated when an integration is created is a template. The business side typically needs to fill in business logic (such as order persistence and callback handling). Ways to modify:

Method 1: Download and Deploy via CLI​

# Download function source
tcb fn code <function-name> --download

# Deploy after modification
tcb fn deploy <function-name>

Method 2: Edit Online via Console​

Console → Cloud Functions → find the corresponding function → "Function Code" → modify in the online editor and deploy.

⚠️ Do not modify the env vars or configuration files injected by Integration Center — they will be overwritten the next time Integration Center redeploys. Only modify business logic code (e.g. services/orderService.js).

Delete an Integration​

Integrations no longer in use can be removed via the "Delete" button in the upper-right corner of the detail page. On deletion:

  1. The associated cloud function is deleted
  2. The callback domain is released (cannot be recovered)
  3. All env vars are cleared

⚠️ Before deletion, please confirm:

  • The third-party platform's dependency on this integration's callback URL has been revoked (e.g. the merchant platform's payment notification URL has been switched or stopped)
  • The business side has stopped calling this integration function
  • Necessary runtime logs have been backed up

FAQ​

Q1: Integration creation fails with "credential validation failed"​

Usually a field is filled incorrectly. Check:

  • Whether the field value is complete (especially PEM format: -----BEGIN ...----- and -----END ...----- lines intact, internal newlines not corrupted)
  • Whether the credential type matches (e.g. WeChat Pay public-key mode and platform-certificate mode cannot be mixed)
  • Whether the associated app (e.g. Mini Program AppID) is bound to the merchant ID

Q2: Calling the integration function returns 401​

The caller did not provide a valid accessToken or openid:

  • Mini Program scenario: confirm wx.cloud.init has been executed and the user has logged in to WeChat
  • Web scenario: the accessToken must come from authenticated login (anonymous login tokens have no permission to call cloud functions)

Q3: Third-party async notifications don't trigger the business function​

Troubleshoot in this order:

  1. Is the callback URL filled in on the third-party platform set to the address generated by Integration Center?
  2. Are there matching records in "Callback Logs" on the integration detail page?
  3. If callback logs show signature verification failure: check credential consistency
  4. If the callback was forwarded to the function: check function logs to see whether the business code threw an error

Q4: Can I create multiple integrations of the same type at the same time?​

Yes. For example, you can create multiple WeChat Pay integrations to serve different Mini Programs or merchant IDs. Each integration generates its own cloud function and callback URL.

Q5: Can integration functions be called by other cloud functions?​

Yes. The integration function is essentially an HTTP cloud function and can be invoked between functions via tcb.callFunction / tcb.callContainer, etc. See the Cloud Function docs.

Next Steps​