Include PIX Key

Headers

Parameter	Type	Description	Example
Authorization	String	Bearer + Access_token	Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEzMzAwOTMxLCJpYXQiOjE3MTMyOTczMzEsImp0aSI6Ijc2ZWI4ZTE5ZjM4YjQ4NmZiODdmNzNjNTdkMWVmNDJhIiwidXNlcl9pZCI6MjQ2fQ.5zekMa7CUj9p-MvNHns5ke4ZPhYV3Y1CLOsYL7hDUUo
hmac	String	HMAC (Hash-based Message Authentication Code). Required for API audience. For Web audience with CPF, CNPJ and EVP types, use MFA token in the `token` body field.	hmac: 57373705c83bc5efe41001790c54642e670088c0c87d56bc8f990f2260c7740b99f4081ff231b87f82118c1e77a959e1f40eacf690a8fa61a827a9ba01d546f6

Body Details

{
  "source_account_branch_identifier": "0001",
  "source_account_number": "123456",
  "reason": "PIX key registration for receiving payments",
  "type": "EMAIL",
  "verification_request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "token": "123456"
}

Field	Type	Description	Required or Optional
source_account_branch_identifier	String	Source account branch (agency) identifier.	required
source_account_number	String	Source account number.	required
reason	String	Reason for registering the key in the DICT. Maximum 255 characters.	required
type	String	PIX key type. Accepted values: `CPF`, `CNPJ`, `EMAIL`, `CELL_PHONE`, `EVP`.	required
verification_request_id	String	Required for EMAIL and CELL_PHONE. Verification request ID (OTP) obtained from the `/v3/key/verifications/send` endpoint. For other key types, this field is not required.	conditional
token	String	For EMAIL and CELL_PHONE: 6-digit OTP code received by email or SMS (required, used with `verification_request_id`). For CPF, CNPJ and EVP with Web audience: MFA TOTP (required). For API audience: Omit or leave empty (authentication via HMAC).	conditional

Request Examples

Register EMAIL PIX key (with OTP):

POST /v3/key
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "source_account_branch_identifier": "0001",
  "source_account_number": "123456",
  "reason": "PIX key registration for receiving payments",
  "type": "EMAIL",
  "verification_request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "token": "123456"
}

Register CELL_PHONE PIX key (with OTP):

POST /v3/key
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "source_account_branch_identifier": "0001",
  "source_account_number": "654321",
  "reason": "Cell phone key for quick payments",
  "type": "CELL_PHONE",
  "verification_request_id": "a8b9c0d1-1234-5678-9abc-def012345678",
  "token": "987654"
}

Register CPF PIX key (Web audience with MFA):

POST /v3/key
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "source_account_branch_identifier": "0001",
  "source_account_number": "789012",
  "reason": "CPF key for commercial transactions",
  "type": "CPF",
  "token": "123456"
}

Register EVP PIX key (random key, API audience):

POST /v3/key
Authorization: Bearer <access_token>
hmac: <computed_hmac>
Content-Type: application/json

{
  "source_account_branch_identifier": "0001",
  "source_account_number": "345678",
  "reason": "Random key for multiple transactions",
  "type": "EVP"
}

Response Details

{
  "worked": true,
  "type": "EMAIL",
  "key": "[email protected]",
  "created_at": "2026-05-07T14:30:00Z"
}

Field	Type	Description
worked	Boolean	Always `true` for successful requests.
type	String	Registered PIX key type (`CPF`, `CNPJ`, `EMAIL`, `CELL_PHONE`, `EVP`).
key	String	PIX key value registered in DICT. For EVP, it is a UUID string automatically generated by the banking system.
created_at	DateTime	Creation date and time (UTC) of the PIX key record.

Error Responses

HTTP Code	Error Message	Description
400	HMAC header required for API audience	The `hmac` header is required when the request is made with API audience.
400	Authentication failed	The authentication token could not be validated.
400	MFA token required for this key type	For CPF, CNPJ and EVP types with Web audience, the `token` field with MFA TOTP code is required.
400	MFA not registered.	The user does not have MFA (multi-factor authentication) configured.
400	Account not found	The account identified by branch and number does not exist, is inactive, or the user does not have permission to access it.
400	Account is closed	The account is closed and cannot be used for PIX key registration.
400	Account does not have a document (CPF/CNPJ) registered	For CPF or CNPJ key types, the account must have a registered document.
400	verification_request_id is required when type is EMAIL or CELL_PHONE	For EMAIL and CELL_PHONE keys, the `verification_request_id` field is required (obtained via verification request endpoint).
400	token is required for EMAIL and CELL_PHONE	For EMAIL and CELL_PHONE keys, the `token` field (OTP code) is required.
400	Invalid code	The OTP code provided in the `token` field does not match the code sent by email or SMS.
400	Verification request expired, request a new code	The OTP code has expired. Request a new code through the `/v3/key/verifications/send` endpoint.
401	Unauthorized	Invalid or missing authentication token. Ensure you are sending a valid Bearer token and HMAC signature (when applicable).
404	Verification request not found	The provided `verification_request_id` does not exist or does not belong to the specified account.
409	This PIX key is already registered to this account.	The provided PIX key is already registered for this same account.
409	This PIX key is already registered to another account and cannot be reused.	The provided PIX key is already registered for another account and cannot be reused.
422	Validation error	Request validation failed. Check that all required fields are present and in the correct format.

Business Rules

PIX Key Types:

CPF / CNPJ: The key value is automatically extracted from the document registered in the account (digits only). The token field (Web audience) or hmac (API audience) is required for authentication.
EMAIL / CELL_PHONE: Requires OTP verification flow. Before calling this endpoint, the client must call /v3/key/verifications/send to receive the code. The verification_request_id field and the OTP code in the token field are required.
EVP (random key): Automatically generated by the banking system. Does not require a predefined value. The token field (Web audience) or hmac (API audience) is required for authentication.

EMAIL / CELL_PHONE Registration Flow:

Request OTP code: Call POST /v3/key/verifications/send with the key and receive the verification_request_id.
Receive code: The 6-digit code will be sent by email or SMS.
Register key: Call POST /v3/key sending the verification_request_id and the received code in the token field.

Validations:

The account identified by source_account_branch_identifier and source_account_number must exist, be active, and be accessible by the authenticated user.
The authenticated user must have PIX key creation permission for the specified account.
An active PIX key cannot be registered more than once, even for different accounts (except when it already belongs to the same account).
The OTP code expires after 3 minutes. After expiration, request a new code.
The reason field must have a maximum of 255 characters.

Authentication:

API Audience: The hmac header is required and must sign the raw JSON body of the request using your secret key.
Web Audience (EMAIL/CELL_PHONE types): Only the Bearer token is required. The OTP code in the token field validates key ownership.
Web Audience (CPF/CNPJ/EVP types): The token field must contain the user's MFA TOTP code.

Notes:

For CPF or CNPJ key types, the system automatically uses the document registered in the account — it is not possible to provide a different CPF/CNPJ.
For EVP keys, the final key value (UUID) is generated by the bank and returned in the key field of the response.
PIX key registration in the DICT is performed immediately after successful validation.