/pix/key/register Register Pix Key

Background

/pix/key/register binds a Pix Key of the specified type to a merchant bank account. The endpoint is shared by merchants and partners.

Pix Key types support PHONE, EMAIL, CPF, CNPJ, and EVP. The PHONE and EMAIL types require a key; the CPF and CNPJ types do not need a key — the system registers the key from the merchant's registered tax ID; an EVP key is generated by the system, and key is not sent in the request. Before registering a mobile number or email Pix Key, call the Send Verification Code endpoint first, fill the verification code into token, and fill the data.verificationRequestId from its response into verificationRequestId.

Endpoint

Item	Value
Method	POST
Path	/pix/key/register
Content-Type	application/json
Purpose	Register a Pix Key for a merchant bank account

Access Requirements

• Common Authentication

Request Fields

Field	Location	Type	Max Length	Required	Description
X-Merchant-Id	Header	string	64	Yes	Merchant ID of the integrator; 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.
key	Body	string	64	Conditional	Pix Key value. Required for the PHONE and EMAIL types; the CPF and CNPJ types do not need a key (registered from the merchant's tax ID); omitted for the EVP type. For mobile numbers, use the international format with the country code, for example the Brazilian mobile number +5511999999999.
keyType	Body	string	10	Yes	Pix Key type: PHONE for mobile number, EMAIL for email, CPF for the Brazilian personal tax ID, CNPJ for the Brazilian business tax ID, and EVP for a system-generated random key.
token	Body	string	6	Conditional	The 6-digit verification code received by the mobile number or email Pix Key; required for the PHONE and EMAIL types, omitted for the other types.
verificationRequestId	Body	string	64	Conditional	Verification request ID, 64 characters long, taken from data.verificationRequestId in the response of the Send Verification Code endpoint; required for the PHONE and EMAIL types, omitted for the other types.

Request Example

POST /pix/key/register HTTP/1.1
Content-Type: application/json
X-Merchant-Id: 92315566000120
X-Timestamp: 1786867200
X-Nonce: 550e8400-e29b-41d4-a716-446655440000
Digest: SHA-256=<Base64 digest>
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"

{
  "key": "financeiro@example.com",
  "keyType": "EMAIL",
  "token": "123456",
  "verificationRequestId": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}

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	Pix Key registration result; it may be omitted when the request fails at the signature verification or protocol parsing stage.
data.key	string	64	Yes	The Pix Key after successful registration; for the EVP type, returns the system-generated random key.
data.keyType	string	10	Yes	The registered Pix Key type: PHONE for mobile number, EMAIL for email, CPF for the Brazilian personal tax ID, CNPJ for the Brazilian business tax ID, and EVP for a system-generated random key.

Response Example

{
  "status": 200,
  "msg": "sucesso",
  "data": {
    "key": "financeiro@example.com",
    "keyType": "EMAIL"
  }
}

Response Error Codes

• Response Status