如何拥有一个接入支付功能的网站？—— cppay 支付网关保姆级教程

作者： /

前言

本文面向「尽快在页面上跑通收款」的前端同学；需要自建下单、对账或与后台深度集成时，请一并阅读文末 与 REST API 的配合。

好多朋友都在给自己的网站添加收款的功能，自己手搓一个支付系统发现全是坑 。CPBOX团队干脆写出一整套的支付网关，直接解决了钱包互动，链上监听等多个方面的问题，只需要安装好相应的SDK，直接搞定你网站的支付功能

本文面向「尽快在页面上跑通收款」的前端同学；需要自建下单、对账或与后台深度集成时，请一并阅读文末 与 REST API 的配合

为什么选择 CPPay

CPPay 不仅是支付网关，更是一套面向加密收款的完整管理平台：

能力说明
可视化管理台在控制台查看订单列表、支付详情与收款记录；无需自建后台也能掌握资金动态
Webhook 管理在控制台配置、测试并查看 Webhook 推送日志，回调调试一目了然
无代码发起支付即使没有线上项目，也可在「API Key 管理」中直接创建订单并发起支付，适合快速验证或临时收款
订阅支付用户授权一次后，系统按周期自动扣款，无需重复引导
x402 协议基于 HTTP 402 的按次计费，适合 API 变现、按量付费
零 Web3 代码SDK 封装钱包连接、链切换、签名与广播；业务侧无需编写 Web3 逻辑，用户按弹窗步骤即可完成支付
多链与多币种支持 Ethereum、BSC 等主流链，USDT、USDC、ETH、BNB 等均可收款
按需定制链 / 币种有特殊链或代币需求，可加入 Telegram VIP 群，支持 7×24 沟通与定制方案
非托管架构资金直接进入你的钱包，CPPay 不经手资产

整体流程（从用户点击到到账）

用户侧与系统侧大致经历：选链 / 选币 → 钱包签名与链上确认 → 平台确认 → 可选 Webhook 通知你的服务端。下面用一张简图串起来（便于和联调同事对齐术语）。

四步即可在网站内完成收款：安装 SDK → 配置密钥 → 唤起支付 → 处理支付结果（含可选 Webhook）。

环境与前置条件

项目建议
运行环境现代浏览器；用户需能安装或使用浏览器钱包插件（如 MetaMask 等，以实际弹窗引导为准）
站点生产环境请使用 HTTPS，避免混合内容与钱包交互异常
框架React、Vue 等常见 SPA 均可；下方示例分别给出 CppayProvider 与 CppayPlugin 用法
构建工具Vite、Webpack、Rspack 等均可；若使用 SSR（如 Next.js），请将带 CppayProvider 的 subtree 置于 仅客户端渲染 的分支，或动态 import SDK，避免服务端执行浏览器专有 API

API Key 放在哪里

  • 快速接入时，apikey 通常写在前端并传入 showPayment。
  • 从安全角度，Key 会出现在打包产物中，不宜与极高权限的后台操作共用同一枚 Key；若控制台支持「仅前端收银」类权限或域名白名单，请按官方说明收紧范围。
  • 更稳妥的架构是：下单、改价、发货等放在你的服务端，用 Key 调用 创建订单 等接口；前端只拿你方业务订单号与短链或受控参数，具体以你方安全与产品要求为准。

第一步：准备

  1. 登录 CPPay 控制台。
  2. 进入 「API Key 管理」，点击右侧生成密钥。

注意：在生产密钥时，根据你产品的支付需求，选择需要的支付方式cppay提供了三种支付方式：单次支付、订阅支付、以及X402支付。这里我们选用默认的单词支付Instant

  1. 选择你api支付模式，以及需要接受的网络资产，目前支持BSC和ETH的原生代币和USDC，USDT

第二步：安装 SDK

CPPay JS SDK 面向多链加密货币支付场景，支持一次性支付与订阅。通过 SDK 暴露的接口，可在现有页面中弹出统一的支付 UI。

npm install @cppay.finance/sdk
# 或
# yarn add @cppay.finance/sdk
# 或
# pnpm add @cppay.finance/sdk

第三步：在前端唤起一次性支付

React 示例

在应用根组件外包一层 CppayProvider：

// App.tsx
import { CppayProvider } from "@cppay.finance/sdk/react";
import { PayButton } from "./PayButton";

function App() {
  return (
    <CppayProvider>
      <PayButton />
    </CppayProvider>
  );
}

export default App;

在需要收款的组件中调用 showPayment：

// PayButton.tsx
import { useCppayPayment } from "@cppay.finance/sdk/react";

export function PayButton() {
  const { showPayment } = useCppayPayment();

  const pay = () => {
    showPayment({
      apikey: "your-api-key",
      plain: "instant",
      // 若你有后台且需与用户订单关联，请使用业务侧唯一 ID；否则可自定义生成
      orderId: "ORDER_20250420_001",
      amount: "10.5", // 金额，USD 字符串
      onSuccess: () => {
        alert("支付成功");
      },
      onError: () => {
        alert("支付失败，请重试");
      },
      onExpired: () => {
        alert("支付超时，请重新发起");
      },
      onFailed: () => {
        alert("支付失败，请重试");
      },
    });
  };

  return <button onClick={pay}>立即支付</button>;
}

Vue 示例

在入口注册插件：

// main.ts
import { createApp } from "vue";
import App from "./App.vue";
import { CppayPlugin } from "@cppay.finance/sdk/vue";

const app = createApp(App);

app.use(CppayPlugin);
app.mount("#app");

在页面中唤起支付：

<script setup lang="ts">
import { useCppayPayment } from "@cppay.finance/sdk/vue";

const { showPayment } = useCppayPayment();

const pay = () => {
  showPayment({
    apikey: "your-api-key",
    plain: "instant",
    orderId: "ORDER_20250420_001",
    amount: "10.5",
    onSuccess: () => alert("支付成功"),
    onError: () => alert("支付失败，请重试"),
    onExpired: () => alert("支付超时，请重新发起"),
    onFailed: () => alert("支付失败，请重试"),
  });
};
</script>

<template>
  <button @click="pay">立即支付</button>
</template>

参数说明

参数 / 回调说明
apikey控制台创建的 API Key
plain一次性支付固定为 “instant”
orderId你方订单号，需保证在业务范围内唯一；若同一 orderId 已用于成功支付，再次发起可能被拒绝或产生歧义，见 常见误区
amount订单金额，以 USD 计价的字符串（如 “10.5”）；链上实际支付的代币数量由系统按汇率换算
onSuccess支付流程在 SDK 侧判定为成功时的回调
onError发生错误（如网络、参数、环境异常等，具体以 SDK 行为为准）
onExpired支付超时或订单过期；官方 REST 文档中一次性订单默认约 30 分钟 有效，过期后需用户重新发起
onFailed支付失败（用户拒绝、链上失败等场景，与 onError 区分：前者偏「结果」，后者偏「异常」）

前端回调与服务端状态如何对齐

SDK 回调用于即时反馈 UI；发货、开通权益、记账等应以服务端为准。官方 查询支付订单 接口返回的 status 包括：pending（待支付）、paid（已支付）、expired（已过期）、failed（失败）。Webhook 与查询结果应一起纳入你的状态机设计。

支付演示

代码成功跑通后，我们就能够直接进入到支付页面。这个页面就是CPPay组件里自带的支付样式。

如果你能成功进入这个页面，就表示你网站的支付功能已经成功接入了！

进入该页面后用户可以选择使用钱包支付或者是手动扫码支付。CPPAY会自动的帮你检查转账是否到账。

那如果你在支付成功后还需要有一些消息的提示，或者是触发下一步，就需要你自行配置WebHook

Webhook：服务端确认支付（可选）

若希望订单状态自动落库或与后台对账，建议配置 Webhook。

配置步骤

  1. 在控制台打开 Webhook 配置。
  2. 填写可公网访问的 HTTPS 地址，例如：https://api.your-domain.com/webhook/cppay。
  3. 保存。

本地开发时，若无法被公网访问，可使用内网穿透或先在控制台用「测试」能力（若有）验证 URL，再部署到可访问环境。

回调载荷示例

对接完成后，你的服务端可能收到类似结构：

{
  "order_no": "ORDER_20250420_001",
  "payment_type": "instant",
  "payment_id": "PAY_1234567890",
  "status": "payment.success"
}

响应要求

建议返回 HTTP 200，且响应体包含：

{ "code": 1, "message": "success" }

code: 1 表示本次处理成功；具体约定以控制台与正式接口文档为准。

安全建议

  1. 幂等：同一笔订单可能多次推送，业务需幂等，避免重复发货或重复记账。
  2. 二次校验：收到成功通知后，建议再调用官方查询接口确认订单状态，再执行发货等副作用；避免因异常或重放通知导致误处理。查询接口见 即时支付 API 文档。
  3. HTTPS 与鉴权：回调 URL 仅对可信网络开放；若官方文档提供签名或 IP 白名单，请按文档校验请求来源。

与 REST API 的配合（可选）

SDK 适合快速接入收银台；若你要在服务端创建订单、展示「应付代币数量」、或做自动化对账，可直接使用同一 API Key 调用 HTTP 接口（与 一次性支付 API 一致）：

能力方法典型用途
查询支持的代币GET /api/srv/payment/token展示当前链、币种、参考价格
创建支付订单POST /api/srv/payment/create服务端生成 order_no、payment_id、收款地址与过期时间
查询订单GET /api/srv/payment/queryWebhook 或定时任务对账，确认 paid 后再发货

与 amount 的关系：REST 文档说明，amount 为商户期望收到的 USD 金额，系统会按代币价格换算链上应付数量；这与前端 showPayment 的 amount 含义一致，便于前后端共用同一套订单语义。

常见误区

  • 不要对同一笔业务重复使用已支付过的 orderId。
  • 若前端提示超时，用户可重新发起支付；服务端仍以 Webhook 与查询接口为准。
  • Webhook 可能重试，处理逻辑须可安全重复执行。
  • 仅依赖 onSuccess 发货有风险：用户关闭页面、网络抖动时，应以 Webhook + 查询接口为准。

常见问题（简要）

问题说明
弹窗打不开或白屏检查是否在 HTTPS、是否被广告插件拦截、控制台是否有跨域或 CSP 报错
金额与链上不一致USD 标价会换算为代币数量，以订单详情与查询接口返回的 pay_amount 为准
想先在后端创建订单使用 POST /api/srv/payment/create，前端再带同一 order_no 走 SDK，或按你们产品流程设计（以官方文档为准）

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部