接口的两层认证:客户端证书(mTLS)与 Bearer 令牌。
信用卡 API 的认证由两层机制协同完成:
- 双向 TLS(mTLS):与 API 的每个连接都使用由 PayZu 签发的客户端证书,在通信过程中同时保证服务器和客户端的身份。
- JWT token:在 mTLS 连接之上,通过
POST /token获取access_token,并在所有其他路由的Authorization: Bearerheader 中发送。
环境
| 环境 | 基础 URL |
|---|---|
| 生产环境 | https://api.payzu.io/v1 |
| Sandbox | https://api.sandbox.payzu.io/v1 |
Mutual TLS
在发起任何调用之前,请安装 PayZu 团队提供的客户端证书,并将您的系统配置为在对 API 的所有调用中使用该证书,且始终通过 HTTPS。
在 curl 中,证书通过 --cert(客户端证书)、--key(私钥)和 --cacert(证书颁发机构链)这几个标志传入:
curl --request GET \
--url https://api.sandbox.payzu.io/v1/charges \
--header 'accept: application/json' \
--cert cliente.crt \
--key cliente.key \
--cacert ca.pem获取 token
POST /token 路由返回用于各路由认证的 JWT token。它使用 Basic Auth(client_id 作为用户名,client_secret 作为密码),始终在 mTLS 连接之上,并在请求体中接收值为 client_credentials 的 grant_type:
curl --request POST \
--url https://api.sandbox.payzu.io/v1/token \
--user "$CLIENT_ID:$CLIENT_SECRET" \
--header 'content-type: application/json' \
--cert cliente.crt \
--key cliente.key \
--cacert ca.pem \
--data '{ "grant_type": "client_credentials" }'在生产环境中,请将基础 URL 换成 https://api.payzu.io/v1。
响应包含 token 及其过期时间:
{
"access_token": "string",
"token_type": "string",
"expires_in": 0
}| 字段 | 用途 |
|---|---|
access_token | 在其他路由的 Authorization header 中使用的 JWT token |
token_type | 返回的 token 类型 |
expires_in | token 的有效期,以秒为单位 |
认证调用
获取 token 之后,API 的每个路由都在同样的 mTLS 配置之上接收 Authorization: Bearer header:
curl --request GET \
--url https://api.sandbox.payzu.io/v1/charges \
--header 'accept: application/json' \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--cert cliente.crt \
--key cliente.key \
--cacert ca.pem切勿泄露 client_secret 或客户端证书的私钥。不要将它们发送到前端,不要提交到代码仓库,并请保存在密钥保管库中。如怀疑发生泄露,请联系 PayZu 团队进行更换。