zkpsdk-client 中文文档教程
功能
- 允许商家访问 ZKPay API 以创建订单/交易、获取交易信息等
安装
客户端需要 Node.js v10+ 才能运行。 安装依赖项并启动服务器。
npm i zkpsdk-client
使用此客户端所需的信息
| # | 描述 |
|---|---|
| 代码 | 注册 zkpay 时接收。用于识别 |
| 商户秘密 | 注册到zkpay时接收的 。用于商户之间的哈希/安全检查数据 - zkpay |
| apiKey | 注册到 zkpay 时接收。用于访问标头为“x-api-key”的商户 API |
| returnUrl | 支付成功后返回页面/回调页面呈现给用户。 成功后，zkpay 会将用户重定向至 https://merchant.site/order?id=[merchantOrder] |
| 示例：returnUrl: https://merchant.site/order 支付测试 | 使用 test/sandbox 环境 |
开发
- 创建支付重定向页面：
...
// init client
const client = new ZkClient({
code: "...",
secret: "...",
apiKey: "...",
returnUrl: "...",
test: true,
});
// init order
const order: MerchantOrder = {
orderId: "...",
userId: "...",
amount: 1000000,
};
// create payment url
const redirectUrl = client.getOrderRedirectUrl(order);
...
- 回调结果 当 zkpay 收到您的订单付款时。具有详细负载的回调操作将执行到商家注册的钩子 API
Init order ->重定向至zkpay ->用户付款->订单成功回调
| # | 描述 |
|---|---|
| merchantId | 您的注册ID，用于标识该交易属于哪个商户 |
| merchantOrder | 您的订单ID |
| 状态 | 您订单的zkpay 交易状态。 “成功”=>已付费， // 或已过期 =>未付款 |
| transactionId | zkpay 交易 ID |
在某些意外情况下，您的订单可能会被标记为 EXPIRED（由于银行延迟）。再次收到成功付款后我们会执行回调动作。 在这种情况下，请处理以下流程：
Init order ->重定向至zkpay ->用户付款（银行延迟）->订单过期回调-> （zkpay收款->订单成功回调）
Features
- Allow merchant access to ZKPay APIs to create order/transaction, get transaction information and more
Installation
The client requires Node.js v10+ to run. Install the dependencies and start the server.
npm i zkpsdk-client
Required information to use this client
| # | Description |
|---|---|
| code | Receive when registered to zkpay. Use to identify merchant |
| secret | Receive when registered to zkpay. Use for hash/security check data between merchant - zkpay |
| apiKey | Receive when registered to zkpay. Use for access to merchant APIs with header "x-api-key" |
| returnUrl | Return page/Callback page after success payment to render to user. Example: returnUrl: https://merchant.site/order then zkpay will redirect user to https://merchant.site/order?id=[merchantOrder] after success payment |
| test | Use test/sandbox environment |
Development
- Create payment redirect page:
...
// init client
const client = new ZkClient({
code: "...",
secret: "...",
apiKey: "...",
returnUrl: "...",
test: true,
});
// init order
const order: MerchantOrder = {
orderId: "...",
userId: "...",
amount: 1000000,
};
// create payment url
const redirectUrl = client.getOrderRedirectUrl(order);
...
- Callback result When zkpay receive payment of your order. A callback action with detail payload will execute to merchant registered hook API
Init order -> Redirect to zkpay -> user make a payment -> success order callback
| # | Description |
|---|---|
| merchantId | Your registered ID to identity which merchant the transaction belongs to |
| merchantOrder | Your order ID |
| status | Status of zkpay transaction for your order. "SUCCESS" => Paid, // or EXPIRED => Unpaid |
| transactionId | zkpay transaction ID |
In some unexpected cases, your order can be marked as EXPIRED (due to banking delay). We will execute the callback action after receive success payment again. In this case please handle the following flow:
Init order -> Redirect to zkpay -> user make a payment (banking delay) -> Order expired callback -> (zkpay receive payment -> success order callback)
更多
