CreatePixKey

Overview

The CreatePixKey method creates a new PIX key in the system, executing validations in multiple layers:

Input validation
PIX key format validation
Business validation
Key quantity validation
Key creation
Registration in DICT

Complete Codes and Messages

Code	Literal Message	Error Scenario	Recommended Action
Input Validation
`ISE0014`	The input data is invalid. See the Validation property of the json for more details.	JSON model validation failure	Correct JSON payload
PIX Key Format Validation
`EXC0001`	PIX key of type {0} is invalid, verify.	Invalid PIX key format	Correct PIX key format
`EXC0044`	Invalid mobile phone number. Use the format: +55 (##) 9 ####-####	Invalid mobile phone format	Use +5511999999999 format
`EXC0050`	It is not allowed to enter a value for a PIX key when the type is {0}.	Value entered for aleatory key	Remove value from PixKey field
`EXC0067`	Invalid PIX key type.	Invalid PIX key type	Use valid key types
`EXC0076`	For the type of key provided, it is necessary to provide the PIX key value.	PIX key value not provided	Provide PIX key value
Business Validation
`EXC0002`	Person with the provided TaxNumber not found.	Person not registered	Register person in the system
`EXC0002`	Account holder not found	Account holder not found	Check account holder information
`EXC0002`	SPI account not found	SPI account not found	Create SPI account for the holder
`EXC0008`	The BusinessUnit does not allow this action	BusinessUnit does not allow PIX	Enable PIX in the BusinessUnit
`EXC0013`	PIX key creation not authorized	Account on PIX restricted list	Remove account from PIX restricted list
`EXC0015`	PIX key value is divergent from the holder's TaxNumber.	Invalid CPF/CNPJ	Correct PIX key or document
PIX Infrastructure
`ESE0092`	PIX DICT configuration not found for BusinessUnitId 123	PIX DICT configuration not found	Configure PIX parameters
`EXC0012`	The account provided cannot operate with the BusinessUnit's agreement	Incompatible bank	Update banking configuration
`EXC0014`	Maximum number of PIX keys registered.	Maximum key limit exceeded	PF: max 5, PJ: max 20 keys
Success
`INF0001`	Request to register a PIX key of type {0} received successfully.	Key creation successful	Key created successfully

Important Notes

Supported PIX key types: CPF, CNPJ, Email, Phone, Aleatory

Quantity limits: Individual Person (5 keys), Legal Person (20 keys)

Required configurations: CnabConfigPixSPI or CnabConfigPixDICT in the BusinessUnit

SPI account: Necessary to have a SPI account linked to the holder

CPF/CNPJ validation: PIX key must match the holder's CPF/CNPJ

Restricted list: Accounts can be blocked for PIX key creation

GetInfosPixKey

Overview

The GetInfosPixKey method performs validations in multiple layers:

PIX key format validation
BusinessUnit validation
Person validation
DICT query
Limit validation
Return information

Complete Codes and Messages

Code	Literal Message	Error Scenario	Recommended Action
Input Validation
`ISE0014`	Invalid input data. See the Validation property of the json for more details.	JSON model validation failure	Correct JSON payload
PIX Key Format Validation
`ISI0479`	The attribute {0} is invalid for the type {1}	Invalid PIX key format for the specified type	Correct PIX key format
Business Validation
`ISI0088`	Business unit not found	BusinessUnit not found by ID	Verify valid BusinessUnitId
`ISI0467`	No data found for the provided TaxNumber	Person not found by CPF/CNPJ	Verify if the document is registered
PIX Infrastructure
`EXC0011`	No agreement found for this request	PIX agreement not configured for BusinessUnit	Configure PIX agreement in BusinessUnit
`EXC0058`	PIX service unavailable. Try again later	PIX service unavailable or SPI service down	Wait for PIX service normalization or enable parameter
Rate Limiting
`EXC0036`	Couldn't validate the PIX key sent	Rate limit exceeded (BusinessUnit or Person)	Wait for the interval between queries
DICT Query
`EXC0025`	Error in PIX key query	Generic error in PIX key query (Result = Error)	Try again or check logs
`EXC0027`	PIX key not found	PIX key not found in DICT (Result = NotFound)	Verify if the key exists or is correctly typed
Success
`ISI0001`	Method executed successfully	Query successful	Continue with the transaction

Important Notes

Supported PIX key types: CPF (11 digits), CNPJ (14 digits), Email (≤ 77 characters), Phone (+5511999999999), Random (UUID)

Rate Limiting: Applied by BusinessUnit and Person - wait for the interval between queries

Required configurations: PIX agreement configured in the BusinessUnit

Format validation: Each key type has specific regex for validation

DICT timeout: Queries in DICT can fail due to BACEN instability

Query protocol: Always returns a SearchProtocol for traceability

CancelPixKey

Overview

The CancelPixKey method performs the cancellation of PIX keys registered in the system, executing validations in multiple layers:

Input validation
PIX key format validation
Business validation
PIX infrastructure validation
Status verification
Cancellation processing

Complete Codes and Messages

Code	Literal Message	Error Scenario	Recommended Action
Input Validation
`ISE0014`	Invalid input data. See the Validation property of the json for more details.	JSON model validation failure	Correct JSON payload
PIX Key Format Validation
`EXC0001`	Invalid PIX key of type {0}, verify.	Invalid PIX key format	Correct PIX key format
Business Validation
`EXC0001`	EXC0001 - Person not found with the provided data.	TaxNumber not found	Verify provided CPF/CNPJ
`EXC0002`	EXC0002 - Account holder not found	Account holder not found or invalid account	Verify account holder information
`EXC0005`	EXC0005 - Business unit not linked to PIX, verify.	BusinessUnit without SPI configuration	Verify PIX configuration
`EXC0042`	Duplicate cancellation request for the selected infraction report	Duplicate cancellation	Wait for previous cancellation processing
`EXC0051`	Cannot cancel a key in status {0}.	Key status does not allow cancellation	Verify current key status
`EXC0052`	PIX key not found or it is in a status that does not allow cancellation.	PIX key not found or invalid status	Verify if the key exists and its status
`EXC0008`	EXC0008 - Business unit does not allow this action	BusinessUnit without permission	Verify BusinessUnit configuration
PIX Infrastructure
`ESE0092`	PIX configuration error {0} for BusinessUnitId {1}	PIX configuration not found	Configure PIX parameters

ClaimPixKey

Overview

The ClaimPixKey method initiates the process of claiming/portability of a PIX key:

Input Validation
PIX Key Format Validation
Account Validation
Business Validation
Processing

Complete Codes and Messages

Code	Literal Message	Error Scenario	Recommended Action
Input Validation
`ISE0014`	ISE0014 - Input data is invalid. See the Validation property of the json for more details.	JSON model validation failure	Correct JSON payload
PIX Key Format Validation
`EXC0001`	EXC0001 - Invalid CPF key, verify.	Invalid CPF format	Correct CPF format
`EXC0001`	EXC0001 - Invalid CNPJ key, verify.	Invalid CNPJ format	Correct CNPJ format
`EXC0001`	EXC0001 - Invalid Email key, verify.	Invalid email format	Provide valid email
`EXC0001`	EXC0001 - Invalid phone number key, verify.	Invalid phone number format	Provide valid phone number
`EXC0070`	Cannot claim a key of the Random type	Attempt to claim a random key	Random keys cannot be claimed
Business Validation
`EXC0001`	EXC0001 - Person not found with the provided data.	TaxNumber not found in the system	Verify provided CPF/CNPJ titleholder
`EXC0002`	EXC0002 - Account holder not found	AccountHolder not found for the person	Verify account holder association
`EXC0002`	EXC0002 - Account holder not found	Account not found with the provided data	Verify account data
`EXC0043`	PIX key already registered for this account	Key already exists for the user's account	Use the ChangePixKey method or cancel the existing key
`EXC0045`	There is already a binding for this key with the same owner and another account information. Use the ChangePixKey method.	Key already registered for another titleholder with the same account	Use the ChangePixKey method
PIX Infrastructure Validation
`EXC0001`	EXC0001 - Business unit does not allow this action	MatchingBusinessUnit not found for SPI	Verify business unit configuration
`EXC0001`	EXC0001 - Person not found with the provided data.	Person not found in the system	Verify person registration
`EXC0001`	AccountHolder not found	AccountHolder not found	Verify account holder association
`EXC0008`	EXC0008 - Account not found	Account not found with the provided data	Verify account SPI data
`ESE0092`	CNAB PIX SPI configuration error for BusinessUnitId {0}	CNAB PIX configuration not found	Configure CNAB PIX parameter
Business Rules Validation
`EXC0018`	PIX key not registered	Key not found or in an inadequate status for portability	Verify if key exists and its status
`EXC0047`	PIX key status does not match a portability request.	Key status is not ErrorOwnership or ErrorPortability	Key must be in an error status for portability
Success
`INF0006`	PIX key claim/portability request registered successfully.	Claim process initiated successfully	Process initiated - wait for confirmation

ChangePixKey

Overview

The ChangePixKey method changes the data associated with a PIX key, executing validations in multiple layers:

Input Validation
Key and Device Validation
Business Validation
Processing

Complete Codes and Messages

Code	Literal Message	Error Scenario	Recommended Action
Input Validation
`ISE0014`	ISE0014 - Input data is invalid. See the Validation property of the json for more details.	JSON model validation failure	Verify required data and JSON format
Key and Device Validation
`EXC0015`	PIX key value is divergent from the titleholder's TaxNumber.	Attempt to change a random key	Random keys cannot be changed
`ISE0438`	DeviceIdentifier field is required	DeviceIdentifier not provided when validation is enabled	Provide device identifier
`ISE0439`	Device not found	Device not found or removed	Register device in the system
`ISE0441`	Device unavailable for request. Contact the institution	Device blocked for a specific reason	Contact the institution
Business Validation
`EXC0002`	EXC0002 - Person not found with the provided TaxNumber.	TaxNumber not found in the system	Verify provided CPF/CNPJ titleholder
`EXC0001`	EXC0001 - Account holder not found	AccountHolder not found for the person	Verify account holder association
`EXC0001`	EXC0001 - Business unit not found	MatchingBusinessUnit not found for SPI (source or destination)	Verify business unit configuration
`ESE0092`	CNAB PIX SPI configuration error for BusinessUnitId {0}	CNAB PIX configuration not found	Configure CNAB PIX parameter
`EXC0030`	Invalid source or destination account data.	Source or destination account not found	Verify account SPI data
`EXC0020`	Source and destination accounts must be different	Source account equals destination account	Provide different accounts
`EXC0017`	Account not linked to SPI	PIX key not found in the source account with Registered status	Verify if key exists and is registered
Success
`INF0015`	PIX key change request registered successfully.	Change process initiated successfully	Process initiated - wait for confirmation