/pix/key/otp/send Pix Key 验证码发送接口
接口背景
/pix/key/otp/send 用于在注册邮箱或手机号 Pix Key 前，向 Key 所有人发送 OTP 验证码。商户和合作商共用本接口，接入方需将用户收到的验证码用于后续 Pix Key 注册。
接口请求地址
| 项目 | 内容 |
|---|---|
| 请求方式 | POST |
| 请求路径 | /pix/key/otp/send |
| Content-Type | application/json |
| 接口用途 | 发送手机号或邮箱 Pix Key 注册验证码 |
接口接入规范
接口请求字段
| 字段名 | 位置 | 类型 | 字段长度 | 是否必填 | 说明 |
|---|---|---|---|---|---|
X-Merchant-Id | Header | string | 64 | 是 | 接入方商户号，用于网关接入认证和密钥定位；合作商使用一级商户号。 |
X-Timestamp | Header | int | 19 | 是 | Unix 秒级请求时间戳，用于请求时效校验。 |
X-Nonce | Header | string | 64 | 是 | 请求防重放随机字符串。 |
Digest | Header | string | 52 | 是 | 请求体摘要，格式为 SHA-256=<Base64摘要>。 |
Authorization | Header | string | 不定长 | 是 | ES256 请求签名信息，其中 keyId 为接入方密钥版本号。 |
keyType | Body | string | 10 | 是 | Pix Key 类型：EMAIL 表示邮箱，PHONE 表示手机号。 |
key | Body | string | 64 | 是 | 需验证归属的邮箱或手机号；手机号建议使用带国家码的国际格式，例如巴西手机号 +5511999999999。 |
请求示例
http
POST /pix/key/otp/send HTTP/1.1
Content-Type: application/json
X-Merchant-Id: 92315566000120
X-Timestamp: 1786867200
X-Nonce: 550e8400-e29b-41d4-a716-446655440001
Digest: SHA-256=<Base64摘要>
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"
{
"keyType": "EMAIL",
"key": "financeiro@example.com"
}接口响应字段
接口使用统一的 status、msg、data 响应结构。
| 字段名 | 类型 | 字段长度 | 是否必返 | 说明 |
|---|---|---|---|---|
status | int | 4 | 是 | 响应码 |
msg | string | 128 | 是 | 与 status 对应 |
data | object | 不适用 | 否 | 验证码发送结果；请求在验签或协议解析阶段失败时可能不返回。 |
data.verificationRequestId | string | 64 | 是 | 验证请求 ID，长度为 64 个字符，用于关联后续 Pix Key 注册流程。 |
data.expiresAt | int | 19 | 是 | 验证码有效截止时间，Unix 秒级时间戳。 |
响应示例
json
{
"status": 200,
"msg": "sucesso",
"data": {
"verificationRequestId": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"expiresAt": 1786955700
}
}