版本：Next

SasS 公共请求及响应参数

1. 简介

提供Server To Server无人自助售货柜交易接口给服务商（下述描述机构均为服务商）调用。

注：涉及金额字段，单位均为元

1.1 接入信息准备

请在对接群中提供以下对接信息（包含测试与生产环境两套）：

接入方公钥信息（平台用于验证请求签名）
接入方接收回调地址（交易终态结果通知，仅支持统一配置接口回调地址，不支持单次请求配置回调地址）
IP（接入方调用API的公网IP，平台用于配置白名单）

1.2 接入参数

1.1 接入信息提供之后，由平台进行相关配置，并提供接入参数，主要包含：机构编号、机构密钥证书序列号、商户编号、平台公钥（见 6. 接口签名机制说明）

1.3 Java SDK接入示例

您可以下载我们提供的Java版本接入demo示例：Java SDK Demo

2. 接口地址

名称	信息
测试环境地址	https://payment-test-gw.cogolinks.com
生产环境地址	https://payment-sg-gw.cogolinks.com
请求方式	HTTPS
接口公共前缀	/saas/

3. 请求公共参数信息

介绍：包括请求头公共参数（如版本号、语言、接口名称、业务类型、机构编号、机构密钥证书序列号、机构签名、签名方法等）和请求公共参数信息（如请求 ID、请求时间、随机字符串、请求数据等）。

3.1 请求头公共参数信息

字段名	类型	是否必传	字段名称	说明
interfaceVersion	String	是	版本号	默认值：1.0.0
language	String	否	语言	语言（zh_CN，zh_TW，en_US）默认取值：zh_CN
interfaceName	String	是	接口名称，接口地址中的一级之后内容	示例：`/pos/auth/capture`接口填写：`auth/capture`
businessType	String	是	业务类型，接口地址中的一级内容	示例：`/pos/auth/capture`接口填写：`pos`
orgNo	String	是	机构编号
orgCertId	String	是	机构密钥证书序列号
signature	String	是	机构签名
signMethod	String	是	机构签名方法取值范围：RSA-SHA256，ECDSA-SHA256，HMAC-SHA256

3.2 请求公共参数信息

字段名	类型	是否必传	字段名称	说明
requestId	String	是	请求ID	请求唯一标识，调用方生成，用于唯一标识某次具体请求建议1-36位（例如：机构编号_时间戳_UUID，如ORG001_20231001123000123_9a8b7c6d5e4f）
requestTime	Timestamp	是	请求时间	ISO 8601标准格式（如yyyy-MM-dd'T'HH:mm:ss.SSSXXX），明确时区信息
nonceStr	String	是	随机字符串	短时防重放，调用方生成，服务端校验短时间内唯一建议1-32位可使用SecureRandom生成高强度随机数
data	Object	是	请求数据

4. 响应公共参数信息

介绍：涵盖响应头公共参数（机构密钥证书序列号、机构签名、签名方法）和响应公共参数信息（请求 UUID、请求时间、响应时间、响应码、响应描述、业务主应码、业务主应答信息、业务子应答码、业务子应答信息、响应数据等）

4.1 响应头公共参数信息

字段名	类型	是否必传	字段名称	说明
orgCertId	String	是	机构密钥证书序列号
signature	String	是	机构签名
signMethod	String	是	机构签名方法取值范围：RSA-SHA256，ECDSA-SHA256，HMAC-SHA256	默认使用RSA-SHA256

4.2 响应公共参数信息

字段名	类型	是否必传	字段名称	说明
requestId	String	是	请求UUID
requestTime	Timestamp	是	请求时间
responseTime	Timestamp	是	响应时间
respCode	Integer	是	响应码
respMsg	String	是	响应描述
busCode	Integer	否	业务主应码	业务失败时存在
busMsg	String	否	业务主应答信息	业务失败时存在
busSubCode	String	否	业务子应答码	业务失败时存在
busSubMsg	String	否	业务子应答信息	业务失败时存在
data	Object	否	响应数据	成功业务信息

5. 公共响应信息码

5.1 响应码

code响应码（RespCode）	响应描述（RespMsg）
200	success
400	fail
500	System error
504	timeout

5.2 响应业务码

仅异常场景

业务主码（busCode）	主码描述（busMsg）	业务子码（busSubCode）	业务子码描述（busSubMsg）
30000	请求入口验证错误	30000	请求入口验证错误
30000	请求入口验证错误	30001	请求ID为空
30000	请求入口验证错误	30002	请求接口重复
31000	请求参数错误	31000	请求参数错误
34000	验签信息有误	34000	验签信息有误
610	验签信息有误	610	验签信息有误
610	验签信息有误	34500	数据验签失败
610	验签信息有误	34501	验签密钥不存在
620	验签信息有误	46202	批次流水号重复
34000	验签信息有误	34011	密码输入错误，无法加载主密钥！
34000	验签信息有误	34015	没有获取到有效卡信息
34000	验签信息有误	34013	运营经理卡不可用
34000	验签信息有误	34014	运营经理卡配置错误，不能使用！
34000	验签信息有误	34503	未查找到有效的KSN信息
34000	验签信息有误	34504	终端异常，KSN被替换
36000	验签信息有误	36000	POS系统参数错误
40000	商户信息有误	34504	终端异常，KSN被替换
40000	商户信息有误	40013	商户业务开关配置不存在
42000	验签信息有误	42000	客户信息有误
44000	终端信息有误	44000	终端信息有误
44000	终端信息有误	44006	终端交易设置异常
44000	终端信息有误	44008	终端交易配置信息不存在
45000	机构信息有误	45000	机构信息有误
45000	产品信息有误	45500	产品信息有误
46000	交易处理信息有误	46000	交易处理信息有误
46000	交易处理信息有误	46016	订单不存在
46000	交易处理信息有误	46201	订单重复交易
50000	计费处理信息有误	50000	订单重复交易
51000	清算处理信息有误	51000	清算处理信息有误
51003	对账文件有误	51003	对账文件未生成或对账日有误
52000	风控处理信息有误	52000	风控处理信息有误
52000	风控处理信息有误	RCS-SYS-0002	风控系统参数有误
53000	账务处理信息有误	53000	账务处理信息有误
53000	账务处理信息有误	AMS0003	账户系统没有数据
54000	渠道处理信息有误	01	渠道处理信息有误
54000	渠道处理信息有误	03	无效商户
80000	文件信息有误	80000	文件信息有误
400	参数列表错误	400001	参数列表错误

6. 接口签名机制说明

签名算法：RSA-SHA256

签名规则：按照接口要求的请求参数，转换为 JSON 字符串，使用平台方提供的签名密钥生成签名，并放入头信息中（签名密钥联系平台方技术提供）

代码示例：

加签：

            String content = JSON.toJSONString(requestBean);// requestBean为请求对象
            SignatureValidator orgSignatureValidator = SignatureValidatorFactory.getValidator(SignMethod.RSA_SHA256.getCode());// 指定签名算法
            String signature = orgSignatureValidator.generateSignature(content, PropertiesUtils.getPrivateKey());//PropertiesUtils.getPrivateKey() 为私钥

验签：

            SignatureValidator orgSignatureValidator = SignatureValidatorFactory.getValidator(SignMethod.RSA_SHA256.getCode());// 指定签名算法
orgSignatureValidator.verifySignature(jsonString, signature, PropertiesUtils.getPublicKey())
//jsonString为需要验签的字符串，signature为签名，PropertiesUtils.getPublicKey()为公钥

生成公私钥对:

以RSA为例，调用RSASignatureValidator.generateKey()方法生成公私钥对
    public String generateKey() {
        try {
            KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("RSA");
            keyPairGenerator.initialize(2048);
            KeyPair keyPair = keyPairGenerator.generateKeyPair();
            System.out.println(Base64.getEncoder().encodeToString(keyPair.getPrivate().getEncoded()));// 私钥
            System.out.println(Base64.getEncoder().encodeToString(keyPair.getPublic().getEncoded()));// 公钥 
            return Base64.getEncoder().encodeToString(keyPair.getPrivate().getEncoded());
        } catch (NoSuchAlgorithmException e) {
            throw new RuntimeException("Error generating RSA key", e);
        }
    }

平台方测试环境公钥:

MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtEUVfqe6KcSiYvwwhkEZEfr6GA/3nYVtR5CmvRMojP/o5J5k14xFyYL+3WRGr/a/vUbwK3HM3xh09Nsmcv09qY9La8B87t+1ZulHVvnrDmbsPlJkqqNH+Iy8cmhKPN41nHiXq0KbLTsfnIxvwtX5VyppptSBMxZek0Cc0ikfopfimldqZ2EBfmofS0tRjwgzajhQ7CZU0TdfjRUzs9vqLt0aHUWisxEyFTIxwF9QJJqYUJRrwmJP/QMZY050fXqOjO1fEHKSorDWCW3onPQbVwazADWzr9k8pK7hDBFGmFOJfN5GflZGRwmT5H9AJGMnZuPaq+Fw6oNsQMqdFUT/KwIDAQAB

平台方测试环境机构密钥证书序列号：

4B5330BB58120A860F696E90988C4059C9A5486E

平台方生产环境公钥:

MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAkebsfISXmDjCHX6qJIAhdujsNhMKi08RODLp51Pl9nogaSonPdpcORXWJwaWeETZxFmIE7zwBMlVBADdUTJmvSqJ4Rj69toWzv/VSKxA57h7xNfqHNmXjmhO/KmVWKUGbjWjIWwpS8JTPC9BIRv9X4CudfTw7gjAuSO6cHIHISYc0ovlebTdrJ8M1PouXoXJLMfZbhPlXAT7qxCel7lwT2R6gN4Hux0X2jP7SaDrxZ1dBq8Hbwk+g6JScmF7XCltOZ5pLP/kTJiJApdaNAtfTjnFCqkprw3pyE+9b4RJPIW4OmEr8+uc3Au0sljRguE5+wjdcF9pBMa6E9I6JZsD6wIDAQAB

平台方生产环境机构密钥证书序列号：

E193A01ECF8D30AD0AFFEFD332CE934E32FFCE72

1. 简介​

1.1 接入信息准备​

1.2 接入参数​

1.3 Java SDK接入示例​

2. 接口地址​

3. 请求公共参数信息​

3.1 请求头公共参数信息​

3.2 请求公共参数信息​

4. 响应公共参数信息​

4.1 响应头公共参数信息​

4.2 响应公共参数信息​

5. 公共响应信息码​

6. 接口签名机制说明​