数字营销
标准API开放接口规范
1.文档说明
2.接口规则
3.标准接口定义
会员营销
3.1.1会员账户信息查询
3.1.2会员充值
3.1.13第三方优惠试算
3.1.5会员注册
3.1.6统一登录注册
3.1.7会员商户优惠试算
3.1.10会员基本信息查询
3.1.16会员绑储值卡
3.1.17会员实名
3.1.18会员充值查询
3.1.21会员绑定实体卡(开卡)
3.1.22会员卡密码修改
3.1.23会员调账
3.1.24会员调账查询
3.1.25会员状态变更
3.1.26发送短信验证码
3.1.28会员消费查询
3.1.29会员消费撤销
3.1.30会员消费撤销查询
3.1.31会员无密码消费
3.1.32会员消费
3.1.34会员信息更新
3.1.35会员账户流水
3.1.37 获取用户基本信息(OAuth2)
3.1.38 获取基础营销授权链接
3.3.1 H5页面调用绑定微信和手机号(GET)
3.3.2 H5页面调用绑定微信和外部顾客编号(GET)
卡券营销
3.2.1卡/券查询
3.2.2发卡/券
3.2.4卡/券作废
3.2.5卡/券核券撤销
3.2.7发卡/券(套券)
3.2.8发卡/券查询
3.2.9作废优惠券发券
3.2.10储值卡充值
3.2.11储值卡充值查询
3.2.12实体储值卡激活(单张)
3.2.13可发卡/券列表查询(套)
3.2.14卡/券批量查询
3.2.15卡/券鉴权
3.2.16卡/券动态二维码生成
3.2.17卡/券转赠
3.2.18卡/券发放查询
3.2.19卡/券核销查询
3.2.20卡/券核销撤销查询
3.2.21卡/券模板详情查询
3.2.22 卡/券交易流水查询
3.2.23储值卡调账
3.2.24储值卡调账查询
3.2.25 卡/券交易流水分页查询
3.2.26 作废卡/券发放
3.2.27卡/券核销
3.2.33卡/券动账流水
3.2.35券号查询该顾客同券模板下的券号列表
3.2.36卡/券冻结
3.2.45卡券延期
外部平台券
3.2.28第三方核券准备接口
3.2.29第三方核券接口
3.2.30第三方核券流水查询接口
3.2.31第三方撤销核券接口
3.2.32第三方券码查询接口
3.2.34第三方门店验券历史接口
3.2.35券号查询该顾客同券模板下的券号列表
3.2.38美团到店综合预约数据
3.2.39美团到店综合消费数据
3.2.40美团到店综合团单消费详情数据
3.2.41美团到店综合门店流量数据
3.2.42美团餐饮门店套餐映射
3.2.43美团到店综合门店商品信息
3.2.44抖音商品线上数据
3.2.46抖音综合提现记录查询
3.2.47抖音综合账单详情查询
3.2.48抖音订单查询
3.2.49抖音账单详细查询
3.2.50抖音券状态批量查询
订单同步
3.5.1外部订单同步
3.5.2外部订单查询
3.5.3外部订单同步撤销
3.5.17外部订单核销
3.5.18外部订单查询
3.5.19外部订单撤销
订单支付
3.5.9订单查询
3.5.10订单退款
3.5.11退款订单查询
3.5.12统一扫码
3.5.13终端信息采集
3.5.14统一支付
3.5.15 ISV收银台
3.5.16生成订单
3.5.20终端信息查询
3.5.23分账确认
3.5.24分账确认结果查询
7.1终端信息字段说明
7.2 splitList字段说明
账户类
3.9.1 资金管理余额查询
3.9.3 资金管理提现
3.9.4 资金管理提现结果查询
3.9.5 资金管理账户批量导入
3.9.6 资金管理账户查询
通知相关
3.10通知相关
5.1券核销通知
5.2会员注册/修改通知
5.3订单支付通知
5.4券核销撤销通知
5.5跨机构订单支付通知
5.6微信核销通知转发
5.7发券通知
5.8卡券充值通知
5.9支付宝核销通知转发
5.10 卡券变动通知
5.11 实体卡入库通知
5.13顾客注册/修改通知
5.15提现结果通知
5.16资金管理小b开通通知
对账文件
6.1对账文件
6.2 分账对账流水文件下载
6.3 对账流水文件下载
机构管理类
3.8.1外部门店信息同步
3.8.2 创建/修改机构用户
3.8.3 查询机构用户信息
3.8.4 机构统计信息查询
附录
7.1终端信息字段说明
7.2 splitList字段说明
7.3 店铺经营类型枚举
7.6 支付方式说明
7.7 paytypeinfo-支付方式参数说明
7.9渠道交易类型(trxCode)
7.10交易返回码(trxStatus)
7.11扩展参数说明
4.1 公共返回码(code)
4.开发参考
4.1 SDK参考概述
4.2 Java SDK
4.3 Python SDK
4.4 PHP SDK
4.5 GO SDK
4.6 C# SDK
一码付开放接口规范
1.接口说明
2.接口规则
3.标准API
3.1统一扫码
3.2统一撤销
3.3统一退款
3.4统一查询
3.5交易结果通知
3.6订单生成
3.7终端信息采集报备
3.8统一支付
3.9资金管理余额查询
3.10资金管理提现
3.11资金管理提现结果查询
3.12资金管理转账
3.13资金管理转账结果查询
3.14终端信息查询
3.15订单关闭
3.16ISV收银台
3.17ISV前端跳转
3.18对账流水文件下载
3.19根据授权码(付款码)获取用户ID
3.20资金管理提现通知
3.21分账/收款确认
3.22分账/收款确认结果查询
3.23资金管理转账通知
3.24资金管理批量转账
3.25资金管理批量转账结果查询
3.26B2B订单支付收款
3.27B2B订单支付付款
3.31代付
3.32代付订单查询
3.33资金管理交易文件查询
3.34收支明细查询
3.35交易列表查询
4.附录
4.1 接口返回码retcode说明
4.2 交易返回码trxstatus说明
4.3 交易类型
4.4 支付渠道优惠信息填写规范(benefitdetail字段)
4.5 拓展参数说明(extendparams)
4.6 终端信息字段说明
4.7 asinfo字段说明
4.8 交易方式
4.9 splitlist字段说明
4.10支付方式
4.11paytypeinfo-支付方式参数说明
4.12民生/平安银行转账子账簿信息
5.13微信订单支付(小程序资金管控)接入说明
5.开发参考
5.1 SDK参考概述
5.2 Java SDK
5.3 C# SDK
5.4 PHP SDK
5.5 GO SDK
5.6 C SDK
5.6.1 安装指南
5.6.2 使用示例
通惠API开放接口规范
1. 文档说明
2. 接口规则
3.标准接口定义
3.1会员信息类
3.3页面调用类
3.4 银行活动类
3.7 互动营销类
3.8 机构管理类
4.公共返回码
5.通知相关
6.对账文件类
7.开发参考
8.接口权限申请表下载
9.常见问题合集
通联核心产品文档中心
-
+
5.6.2 使用示例
# 使用示例文档 本文档提供了一码付 C SDK 的常见使用场景和代码示例。 --- ## 基本使用流程 ### 完整示例 ```c #include "ocpay_sdk.h" #include <stdio.h> #include <stdlib.h> int main() { // 1. 加载配置 ocpay_config_t *config = ocpay_config_create(); if (ocpay_config_load_from_file(config, "config.json") != OCPAY_SUCCESS) { fprintf(stderr, "加载配置失败\n"); ocpay_config_free(config); return -1; } // 2. 创建 SDK 实例 ocpay_sdk_t *sdk = ocpay_sdk_create(); ocpay_sdk_set_config(sdk, config); // 3. 生成请求序列号 char *reqsn = ocpay_generate_reqsn(); // 4. 构建请求参数 const char *params[] = { "reqsn", reqsn, "trxamt", "28940", "goodsdesc", "测试商品", "notifyurl", "https://example.com/notify", NULL }; // 5. 发起请求 const char *endpoint = "https://api.example.com/pay"; ocpay_response_t *resp = ocpay_sdk_request(sdk, endpoint, params); free(reqsn); if (!resp) { fprintf(stderr, "请求失败: %s\n", ocpay_get_error_message(ocpay_get_last_error())); ocpay_sdk_free(sdk); ocpay_config_free(config); return -1; } // 6. 处理响应 if (ocpay_response_is_success(resp)) { printf("请求成功\n"); printf("交易ID: %s\n", ocpay_response_get_string(resp, "trxid")); } else { printf("请求失败: %s\n", ocpay_response_get_error_message(resp)); } // 7. 清理资源 ocpay_response_free(resp); ocpay_sdk_free(sdk); ocpay_config_free(config); return 0; } ``` --- ## 配置管理 ### 示例 1:从 JSON 文件加载配置 **config.json:** ```json { "app_id": "your_app_id", "sign_type": "RSA", "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----", "public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----", "debug_enabled": 1 } ``` **代码:** ```c #include "ocpay_config.h" #include <stdio.h> int main() { ocpay_config_t *config = ocpay_config_create(); if (ocpay_config_load_from_file(config, "config.json") != OCPAY_SUCCESS) { fprintf(stderr, "加载配置失败\n"); ocpay_config_free(config); return -1; } printf("配置加载成功\n"); printf("AppID: %s\n", config->app_id); printf("签名类型: %s\n", config->sign_type); printf("调试模式: %s\n", config->debug_enabled ? "开启" : "关闭"); ocpay_config_free(config); return 0; } ``` ### 示例 2:从环境变量加载配置 ```c #include "ocpay_config.h" #include <stdio.h> int main() { ocpay_config_t *config = ocpay_config_create(); if (ocpay_config_load_from_env(config) != OCPAY_SUCCESS) { fprintf(stderr, "从环境变量加载配置失败\n"); ocpay_config_free(config); return -1; } printf("配置加载成功\n"); printf("AppID: %s\n", config->app_id); ocpay_config_free(config); return 0; } ``` ### 示例 3:配置验证 ```c #include "ocpay_config.h" #include "ocpay_errors.h" #include <stdio.h> int main() { ocpay_config_t *config = ocpay_config_create(); ocpay_config_load_from_file(config, "config.json"); // 验证配置 if (ocpay_config_validate(config) != OCPAY_SUCCESS) { ocpay_error_code_t err = ocpay_get_last_error(); fprintf(stderr, "配置验证失败: %s\n", ocpay_get_error_message(err)); ocpay_config_free(config); return -1; } printf("配置验证通过\n"); ocpay_config_free(config); return 0; } ``` --- ## 支付请求 ### 示例 1:基本支付请求 ```c #include "ocpay_sdk.h" #include <stdio.h> #include <stdlib.h> int main() { // 初始化 SDK ocpay_config_t *config = ocpay_config_create(); ocpay_config_load_from_file(config, "config.json"); ocpay_sdk_t *sdk = ocpay_sdk_create(); ocpay_sdk_set_config(sdk, config); // 生成请求序列号 char *reqsn = ocpay_generate_reqsn(); // 构建支付参数 const char *params[] = { "reqsn", reqsn, // 请求序列号 "trxamt", "28940", // 交易金额(分) "goodsdesc", "测试商品", // 商品描述 "notifyurl", "https://example.com/notify", // 异步通知地址 NULL }; // 发起支付请求 const char *endpoint = "https://dms-api-test.shopoint.cn/shopoint-openapis-web/szyx/apiweb/pay/unifiedorder"; ocpay_response_t *resp = ocpay_sdk_request(sdk, endpoint, params); free(reqsn); if (resp && ocpay_response_is_success(resp)) { printf("支付请求成功\n"); printf("交易ID: %s\n", ocpay_response_get_string(resp, "trxid")); printf("支付信息: %s\n", ocpay_response_get_string(resp, "payinfo")); } else { fprintf(stderr, "支付请求失败\n"); } // 清理资源 ocpay_response_free(resp); ocpay_sdk_free(sdk); ocpay_config_free(config); return 0; } ``` ### 示例 2:带可选参数的支付请求 ```c // 构建支付参数(包含可选参数) const char *params[] = { "reqsn", reqsn, // 请求序列号(必填) "trxamt", "28940", // 交易金额(必填) "goodsdesc", "测试商品", // 商品描述(必填) "notifyurl", "https://example.com/notify", // 异步通知地址(必填) "cusid", "266649", // 商户号(可选) "appid", "your_app_id", // 应用ID(可选,SDK会自动添加) "body", "商品详细描述", // 商品详情(可选) "remark", "备注信息", // 备注(可选) "validtime", "300", // 订单有效期(秒,可选) "limit_pay", "no_credit", // 支付限制(可选) NULL }; ``` ### 示例 3:处理支付响应 ```c ocpay_response_t *resp = ocpay_sdk_request(sdk, endpoint, params); if (!resp) { fprintf(stderr, "请求失败: %s\n", ocpay_get_error_message(ocpay_get_last_error())); return -1; } if (ocpay_response_is_success(resp)) { printf("支付请求成功\n"); // 获取交易状态 if (ocpay_response_has(resp, "trxstatus")) { const char *status = ocpay_response_get_string(resp, "trxstatus"); printf("交易状态: %s\n", status); if (strcmp(status, "0000") == 0) { printf("交易成功\n"); } else if (strcmp(status, "1000") == 0) { printf("交易处理中\n"); } else if (strcmp(status, "2000") == 0) { printf("交易失败\n"); } } // 获取支付信息(二维码或链接) if (ocpay_response_has(resp, "payinfo")) { printf("支付信息: %s\n", ocpay_response_get_string(resp, "payinfo")); } // 获取交易ID if (ocpay_response_has(resp, "trxid")) { printf("交易ID: %s\n", ocpay_response_get_string(resp, "trxid")); } } else { printf("支付请求失败: %s\n", ocpay_response_get_error_message(resp)); } ocpay_response_free(resp); ``` --- ## 交易查询 ### 示例 1:查询交易状态 ```c #include "ocpay_sdk.h" #include <stdio.h> #include <stdlib.h> int main() { // 初始化 SDK ocpay_config_t *config = ocpay_config_create(); ocpay_config_load_from_file(config, "config.json"); ocpay_sdk_t *sdk = ocpay_sdk_create(); ocpay_sdk_set_config(sdk, config); // 生成随机字符串 char *randomstr = ocpay_generate_random_string(16); // 构建查询参数 const char *params[] = { "cusid", "266649", // 商户号 "version", "11", // 版本号 "reqsn", "PN20240101120000abcdef", // 原请求序列号 "randomstr", randomstr, // 随机字符串 NULL }; // 发起查询请求 const char *endpoint = "https://dms-api-test.shopoint.cn/shopoint-openapis-web/szyx/apiweb/tranx/query"; ocpay_response_t *resp = ocpay_sdk_request(sdk, endpoint, params); free(randomstr); if (resp && ocpay_response_is_success(resp)) { printf("查询成功\n"); printf("交易状态: %s\n", ocpay_response_get_string(resp, "trxstatus")); printf("交易金额: %s 分\n", ocpay_response_get_string(resp, "trxamt")); } else { fprintf(stderr, "查询失败\n"); } // 清理资源 ocpay_response_free(resp); ocpay_sdk_free(sdk); ocpay_config_free(config); return 0; } ``` ### 示例 2:解析查询响应 ```c ocpay_response_t *resp = ocpay_sdk_request(sdk, endpoint, params); if (resp && ocpay_response_is_success(resp)) { printf("查询成功\n\n"); // 基本信息 printf("交易基本信息:\n"); printf(" 交易ID: %s\n", ocpay_response_get_string(resp, "trxid")); printf(" 请求序列号: %s\n", ocpay_response_get_string(resp, "reqsn")); printf(" 商户号: %s\n", ocpay_response_get_string(resp, "cusid")); // 交易状态 const char *status = ocpay_response_get_string(resp, "trxstatus"); printf("\n交易状态: %s", status); if (strcmp(status, "0000") == 0) { printf(" (交易成功)\n"); } else if (strcmp(status, "1000") == 0) { printf(" (交易处理中)\n"); } else if (strcmp(status, "2000") == 0) { printf(" (交易失败)\n"); } else { printf("\n"); } // 金额信息 const char *amount = ocpay_response_get_string(resp, "trxamt"); long amt = atol(amount); printf("交易金额: %.2f 元 (%s 分)\n", amt / 100.0, amount); // 时间信息 if (ocpay_response_has(resp, "trxdate")) { printf("交易日期: %s\n", ocpay_response_get_string(resp, "trxdate")); } if (ocpay_response_has(resp, "trxtime")) { printf("交易时间: %s\n", ocpay_response_get_string(resp, "trxtime")); } // 支付方式 if (ocpay_response_has(resp, "paytype")) { const char *paytype = ocpay_response_get_string(resp, "paytype"); printf("支付方式: %s", paytype); if (strcmp(paytype, "W01") == 0) { printf(" (微信)\n"); } else if (strcmp(paytype, "A01") == 0) { printf(" (支付宝)\n"); } else { printf("\n"); } } } ocpay_response_free(resp); ``` --- ## 错误处理 ### 示例 1:基本错误处理 ```c #include "ocpay_sdk.h" #include "ocpay_errors.h" #include <stdio.h> int main() { ocpay_config_t *config = ocpay_config_create(); if (ocpay_config_load_from_file(config, "config.json") != OCPAY_SUCCESS) { ocpay_error_code_t err = ocpay_get_last_error(); fprintf(stderr, "错误: %s (错误码: %d)\n", ocpay_get_error_message(err), err); ocpay_config_free(config); return -1; } ocpay_config_free(config); return 0; } ``` ### 示例 2:详细错误处理 ```c ocpay_response_t *resp = ocpay_sdk_request(sdk, endpoint, params); if (!resp) { // 获取错误码 ocpay_error_code_t err = ocpay_get_last_error(); // 根据错误码进行不同处理 switch (err) { case OCPAY_ERR_INVALID_CONFIG: fprintf(stderr, "配置错误,请检查配置文件\n"); break; case OCPAY_ERR_SIGN_FAILED: fprintf(stderr, "签名失败,请检查私钥是否正确\n"); break; case OCPAY_ERR_NETWORK_FAILED: fprintf(stderr, "网络请求失败,请检查网络连接\n"); break; case OCPAY_ERR_VERIFY_FAILED: fprintf(stderr, "验签失败,请检查公钥是否正确\n"); break; default: fprintf(stderr, "未知错误: %s\n", ocpay_get_error_message(err)); break; } return -1; } ``` ### 示例 3:响应错误处理 ```c ocpay_response_t *resp = ocpay_sdk_request(sdk, endpoint, params); if (resp) { if (ocpay_response_is_success(resp)) { printf("请求成功\n"); } else { // 获取响应中的错误信息 const char *retcode = ocpay_response_get_string(resp, "retcode"); const char *retmsg = ocpay_response_get_error_message(resp); fprintf(stderr, "请求失败\n"); fprintf(stderr, "返回码: %s\n", retcode ? retcode : "未知"); fprintf(stderr, "错误信息: %s\n", retmsg ? retmsg : "未知错误"); // 根据返回码进行处理 if (retcode && strcmp(retcode, "FAIL") == 0) { fprintf(stderr, "业务处理失败,请检查请求参数\n"); } } ocpay_response_free(resp); } else { fprintf(stderr, "请求失败: %s\n", ocpay_get_error_message(ocpay_get_last_error())); } ``` --- ## 高级用法 ### 示例 1:调试模式 ```c // 在配置中启用调试模式 config->debug_enabled = 1; // 或在配置文件中设置 { "debug_enabled": 1 } // 调试模式下会输出详细的日志信息: // - 待签名字符串 // - 请求参数 // - 响应数据 ``` ### 示例 2:自定义请求序列号 ```c // 使用自定义格式的请求序列号 char reqsn[64]; time_t now = time(NULL); struct tm *tm_info = localtime(&now); char timestamp[32]; strftime(timestamp, sizeof(timestamp), "%Y%m%d%H%M%S", tm_info); // 生成随机字符串 char *random = ocpay_generate_random_string(16); snprintf(reqsn, sizeof(reqsn), "PN%s%s", timestamp, random); free(random); printf("请求序列号: %s\n", reqsn); ``` ### 示例 3:批量查询 ```c // 查询多个交易 const char *reqsn_list[] = { "PN20240101120000abcdef", "PN20240101120001ghijkl", "PN20240101120002mnopqr", NULL }; for (int i = 0; reqsn_list[i] != NULL; i++) { char *randomstr = ocpay_generate_random_string(16); const char *params[] = { "cusid", "266649", "version", "11", "reqsn", reqsn_list[i], "randomstr", randomstr, NULL }; ocpay_response_t *resp = ocpay_sdk_request(sdk, query_endpoint, params); free(randomstr); if (resp && ocpay_response_is_success(resp)) { printf("交易 %s 状态: %s\n", reqsn_list[i], ocpay_response_get_string(resp, "trxstatus")); } ocpay_response_free(resp); } ``` ### 示例 4:重试机制 ```c #include <unistd.h> // for sleep() #define MAX_RETRIES 3 #define RETRY_DELAY 2 // 秒 ocpay_response_t *resp = NULL; int retry_count = 0; while (retry_count < MAX_RETRIES) { resp = ocpay_sdk_request(sdk, endpoint, params); if (resp) { break; // 请求成功 } // 检查错误类型 ocpay_error_code_t err = ocpay_get_last_error(); if (err == OCPAY_ERR_NETWORK_FAILED) { retry_count++; printf("网络请求失败,%d 秒后重试 (%d/%d)...\n", RETRY_DELAY, retry_count, MAX_RETRIES); sleep(RETRY_DELAY); } else { // 其他错误不重试 break; } } if (!resp) { fprintf(stderr, "请求失败,已重试 %d 次\n", retry_count); } ``` ### 示例 5:多配置管理 ```c // 管理多个商户的配置 typedef struct { const char *name; ocpay_config_t *config; ocpay_sdk_t *sdk; } merchant_t; merchant_t merchants[] = { {"商户A", NULL, NULL}, {"商户B", NULL, NULL}, {NULL, NULL, NULL} }; // 初始化所有商户 for (int i = 0; merchants[i].name != NULL; i++) { char config_file[256]; snprintf(config_file, sizeof(config_file), "config_%s.json", merchants[i].name); merchants[i].config = ocpay_config_create(); ocpay_config_load_from_file(merchants[i].config, config_file); merchants[i].sdk = ocpay_sdk_create(); ocpay_sdk_set_config(merchants[i].sdk, merchants[i].config); printf("商户 %s 初始化成功\n", merchants[i].name); } // 使用特定商户的 SDK ocpay_response_t *resp = ocpay_sdk_request(merchants[0].sdk, endpoint, params); // 清理所有商户 for (int i = 0; merchants[i].name != NULL; i++) { ocpay_sdk_free(merchants[i].sdk); ocpay_config_free(merchants[i].config); } ``` --- ## 完整示例程序 完整的示例程序可以在 `examples/` 目录中找到: - `basic_usage.c` - 基本使用示例,演示完整的支付流程 - `query_transaction.c` - 交易查询示例,演示如何查询交易状态 编译并运行示例: ```bash # 编译 make # 运行基本使用示例 ./examples/basic_usage # 运行交易查询示例 ./examples/query_transaction PN20240101120000abcdef ``` --- ## 注意事项 1. **内存管理**:所有动态分配的对象(config、sdk、response)都需要手动释放 2. **参数数组**:传递给 `ocpay_sdk_request()` 的参数数组必须以 `NULL` 结尾 3. **错误处理**:始终检查函数返回值,并使用 `ocpay_get_last_error()` 获取详细错误信息 4. **线程安全**:SDK 不保证线程安全,多线程环境下每个线程应创建独立的 SDK 实例 5. **配置安全**:不要将配置文件提交到版本控制系统,建议使用环境变量或加密存储 ---
陈志平chenzp3
2026年3月10日 10:37
转发文档
收藏文档
上一篇
下一篇
手机扫码
复制链接
手机扫一扫转发分享
复制链接
Word文件
PDF文档
分享
链接
类型
密码
更新密码
有效期