ZOLOZZOLOZDOCS

获取API凭证

为确保您的业务与ZOLOZ服务之间能够安全地传输报文，在接入ZOLOZ网关之前，您需要先获取相应的API凭证，用于对传输报文进行签名、验证、加密和解密。

ZOLOZ支持通过公私钥方式和AK/SK方式接入ZOLOZ网关，两种接入方式所需的API凭证不同：

  • 公私钥方式：需要准备客户ID、ZOLOZ交易公钥、商户交易公钥、商户交易私钥。
  • AK/SK方式：需要准备客户ID、Access Key、Secret Key。

有关两种接入方式的区别，详见接入ZOLOZ网关概述。

前提条件

  • 您已拥有登录ZOLOZ门户的管理员账号，请参见创建管理员账号。
  • 您已了解ZOLOZ网关协议相关内容，以便创建API请求和处理安全响应。

公私钥接入所需的API凭证

API凭证介绍

通过公私钥方式接入ZOLOZ网关时，您需要准备以下API凭证以确保数据传输安全。

API凭证

描述

用途

客户ID

商户账号的唯一标识。

用于识别报文发送端。在请求签名和响应验证的内容中均包含客户ID。

ZOLOZ交易密钥对

ZOLOZ提供的密钥对，包含一个公钥和一个私钥。

公钥的用途：

  • 商户对发送给ZOLOZ的请求进行加密
  • 商户对ZOLOZ返回的响应进行签名验证

私钥的用途：

  • ZOLOZ对商户发送的请求进行解密
  • ZOLOZ对返回给商户的回复进行签名

商户交易密钥对

商户提供的密钥对，包含一个公钥和一个私钥。

公钥必须在ZOLOZ门户注册。

公钥的用途：

  • ZOLOZ对商户请求中的签名进行验证
  • ZOLOZ对返回给商户的响应进行加密

私钥的用途：

  • 商户对发送给ZOLOZ的请求进行签名
  • 商户对来自于ZOLOZ的响应进行解密
  • 客户ID和ZOLOZ交易密钥对：在创建ZOLOZ管理员账号时由系统自动生成，您可以在ZOLOZ门户中获取客户ID和ZOLOZ交易公钥，私钥由ZOLOZ保存。
  • 商户交易密钥对：可以通过以下两种方式获取。
    • 方式一：通过ZOLOZ门户自动生成商户交易密钥对。当用于测试场景，想要快速在ZOLOZ门户注册商户交易公钥时，建议使用此方法。
    • 方式二：自己手动创建商户交易密钥对，并将生成的公钥通过ZOLOZ门户注册。当处于生产环境时，为了您的私钥安全，建议使用此方法。

获取API凭证

  1. 使用管理员账号登录ZOLOZ门户。不同的站点和环境对应的ZOLOZ门户地址不同，请根据您的实际站点和环境选择登录地址。详细信息，请参见选择站点和环境。
  2. 在左侧导航栏，选择Integration > API Key。
  3. 复制Client ID和ZOLOZ transaction public key对应的字符串，并保存到本地供后续使用。image.png
    • Client ID：客户ID。
    • ZOLOZ transaction public key：ZOLOZ交易公钥。
  1. 创建商户交易密钥对。商户交易密钥对支持自动生成和手动创建，请参见附录：创建商户交易密钥对。
  2. 单击Submit，在ZOLOZ门户中注册商户交易公钥。

附录：创建商户交易密钥对

以下介绍自动生成和手动创建商户交易密钥对的方法，您可以选择一种方法进行创建。

注意：无论是自动生成还是手动创建商户交易密钥对，都需要在ZOLOZ门户中注册商户交易公钥。

自动生成商户交易密钥对

  1. 在API Key页面，单击Auto-generate，系统会为商户自动生成一个RSA密钥对。
    • 商户交易公钥对应的字符串会自动填写到Merchant transaction public key字段，请勿修改该字段的内容。image.png
    • 商户交易私钥会自动下载到您的本地，文件名为merchant_private_key.pem，请您妥善保管，不要与任何人共享。注意：ZOLOZ不保存商户交易私钥，且ZOLOZ团队从不要求您提供商户交易私钥。
  1. 单击Submit，在ZOLOZ门户中注册商户交易公钥。如果未提交，注册流程将不会生效。

手动创建商户交易密钥对

  1. 使用OpenSSL工具包或KeyPairGenerator Java类手动创建商户交易密钥对。示例1：OpenSSL工具包
copy
# Generate the private key, which will be used to sign your request.
# Note: this key cannot be directly used for Java. You need to transform the key to the PKCS8 format.
openssl genrsa -out priv_key_tmp.pem

# Transform the private key to the PKCS8 format if Java is used
openssl pkcs8 -topk8 -inform PEM -in priv_key_tmp.pem -outform PEM -nocrypt -out priv_key.pem 

# Generate the public key
openssl rsa -in priv_key_tmp.pem -pubout -out pub_key.pem 

# Generate the public key that is applicable to Java
cat pub_key.pem | grep -v "^\-" | tr -d "\n" | sed 's/%$//' > pub_key.base64

示例2：Java类

copy
KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("RSA");

SecureRandom secureRandom = new SecureRandom();
keyPairGenerator.initialize(2048, secureRandom);

KeyPair keyPair = keyPairGenerator.generateKeyPair();
Key publicKey = keyPair.getPublic();
Key privateKey = keyPair.getPrivate();

String publicKeyBase64 = Base64.getEncoder().encodeToString(publicKey.getEncoded());
String privateKeyBase64 = Base64.getEncoder().encodeToString(privateKey.getEncoded());
  1. 在ZOLOZ门户中，将商户交易公钥对应的字符串拷贝到API Key页面中的Merchant transaction public key字段。
  2. 单击Submit，在ZOLOZ门户中注册商户交易公钥。如果未提交，注册流程将不会生效。

AK/SK接入所需的API凭证

Access Key（AK）和Secret Key（SK）是一组用于身份验证和授权的密钥对。通过AK/SK方式接入ZOLOZ网关时，您需要准备AK和SK，用于对报文进行签名和签名验证。

获取AK/SK的方法如下：

  1. 使用管理员账号登录ZOLOZ Portal。
    不同的站点和环境对应的ZOLOZ Portal地址不同，请根据您的实际站点和环境选择登录地址，详见选择站点和环境。
  2. 在左侧导航栏，选择Integration > AK/SK Keys。
  3. 单击Generate New AK/SK，系统将自动生成一组AK/SK。
    image.png
    • 每组AK/SK都具有唯一性。SK默认不展示，仅在点击查看图标后临时显示明文。
    • 支持新增多组AK/SK，多组AK/SK可同时生效。
  1. 成功生成AK/SK后，可在AK/SK Keys页面查看所有的AK/SK。