Include PIX Key

Endpoint

POST /v3/dict/key

Headers

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"
}

Request Examples

Register EMAIL PIX key (with OTP):

POST /v3/dict/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/dict/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:

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

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

Register EVP PIX key (random key):

POST /v3/dict/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": "usuario@exemplo.com",
  "created_at": "2026-05-07T14:30:00Z"
}

Error Responses

Business Rules

PIX Key Types:

• CPF / CNPJ: The key value is automatically extracted from the document registered in the account (digits only). HMAC authentication is required.
• EMAIL / CELL_PHONE: Requires OTP verification flow. Before calling this endpoint, the client must call /v3/dict/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. HMAC authentication is required.

EMAIL / CELL_PHONE Registration Flow:

1. Request OTP code: Call POST /v3/dict/key/verifications/send with the key and receive the verification_request_id.
2. Receive code: The 6-digit code will be sent by email or SMS.
3. Register key: Call POST /v3/dict/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:

• The hmac header is required and must sign the raw JSON body of the request using your secret key.
• For EMAIL and CELL_PHONE types, the OTP code in the token field validates key ownership.

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.