/pix/key/otp/send Send Verification Code
Background
/pix/key/otp/send sends an OTP verification code to the owner of the key before an email or mobile number Pix Key is registered. The endpoint is shared by merchants and partners, and the integrator must use the verification code received by the user for the subsequent Pix Key registration.
Endpoint
| Item | Value |
|---|---|
| Method | POST |
| Path | /pix/key/otp/send |
| Content-Type | application/json |
| Purpose | Send the verification code for mobile number or email Pix Key registration |
Access Requirements
Request Fields
| Field | Location | Type | Max Length | Required | Description |
|---|---|---|---|---|---|
X-Merchant-Id | Header | string | 64 | Yes | Merchant ID of the integrator, used for gateway access authentication and key lookup; partners use the primary merchant ID. |
X-Timestamp | Header | int | 19 | Yes | Unix request timestamp in seconds, used to validate request freshness. |
X-Nonce | Header | string | 64 | Yes | Anti-replay random string for the request. |
Digest | Header | string | 52 | Yes | Digest of the request body, in the format SHA-256=<Base64 digest>. |
Authorization | Header | string | Variable | Yes | ES256 request signature information, where keyId is the integrator's key version number. |
keyType | Body | string | 10 | Yes | Pix Key type: EMAIL for email, PHONE for mobile number. |
key | Body | string | 64 | Yes | The email or mobile number whose ownership is to be verified; for mobile numbers, use the international format with the country code, for example the Brazilian mobile number +5511999999999. |
Request Example
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 digest>
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"
{
"keyType": "EMAIL",
"key": "financeiro@example.com"
}Response Fields
The endpoint uses the standard status, msg, and data response structure.
| Field | Type | Max Length | Always Returned | Description |
|---|---|---|---|---|
status | int | 4 | Yes | Response code |
msg | string | 128 | Yes | Corresponds to status |
data | object | N/A | No | Verification code delivery result; it may be omitted when the request fails at the signature verification or protocol parsing stage. |
data.verificationRequestId | string | 64 | Yes | Verification request ID, 64 characters long, used to correlate the subsequent Pix Key registration. |
data.expiresAt | int | 19 | Yes | Expiration time of the verification code, as a Unix timestamp in seconds. |
Response Example
json
{
"status": 200,
"msg": "sucesso",
"data": {
"verificationRequestId": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"expiresAt": 1786955700
}
}