Download OpenAPI specification:Download
O Diretório de Identificadores de Contas Transacionais - DICT - é o serviço do arranjo Pix que permite buscar detalhes de contas transacionais com chaves de endereçamento mais convenientes para quem faz um pagamento. Entre os tipos de chave atualmente disponíveis estão CPF, CNPJ, telefone, e-mail e EVP. As informações retornadas pelo DICT permitem ao pagador confirmar a identidade do recebedor, proporcionando uma experiência mais fácil e segura. Permitem também ao PSP do pagador criar a mensagem de instrução de pagamento a ser enviada para o sistema de liquidação com os detalhes de conta do recebedor.
Para informações adicionais, consulte a página do Pix.
O DICT utiliza autenticação mútua TLS.
As definições de autenticação para essa API estão especificadas no manual de segurança do Pix.
Requisições que incluam ou alterem informações no DICT devem ser assinadas com XML Digital Signature pelo participante que envia a requisição. Requisições de consulta não precisam ser assinadas. Respostas retornadas pelo DICT serão assinadas digitalmente. As assinaturas devem ser validadas pelos clientes da API.
A assinatura será colocada no elemento Signature
das requisições e respostas.
O Signature
será envelopado pelo XML que está
sendo assinado (assinatura é um elemento filho).
Para mais detalhes sobre a forma de construir a assinatura, consulte o manual de segurança do Pix.
Para preservar a estabilidade do serviço, as operações da API do DICT estão sujeitas a políticas de limitação de requisições. Especificamente para a operação de consulta de vínculo, há também limitação de requisições com a finalidade de prevenir ataques de varredura de dados. O algoritmo usado para implementar as políticas de limitação é o token bucket.
Uma política de limitação tem associado a ela um escopo, que pode ser o usuário final ou o participante. Cada política possui uma taxa de reposição de "fichas", um tamanho de "balde" e uma regra de contagem. A tabela abaixo define as políticas aplicáveis a cada operação da API.
Política | Escopo | Operações | Taxa de reposição | Tamanho do balde |
---|---|---|---|---|
ENTRIES_READ_USER_ANTISCAN | USER | getEntry | (*) | (*) |
ENTRIES_READ_USER_ANTISCAN_V2 | USER | getEntry | (*) | (*) |
ENTRIES_READ_PARTICIPANT_ANTISCAN | PSP | getEntry | (**) | (**) |
ENTRIES_STATISTICS_READ | PSP | getEntryStatistics | (**) | (**) |
ENTRIES_WRITE | PSP | createEntry, deleteEntry | 1200/min | 36000 |
ENTRIES_UPDATE | PSP | updateEntry | 600/min | 600 |
CLAIMS_READ | PSP | getClaim | 600/min | 18000 |
CLAIMS_WRITE | PSP | createClaim, acknowledgeClaim, cancelClaim, confirmClaim, completeClaim | 1200/min | 36000 |
CLAIMS_LIST_WITH_ROLE | PSP | listClaims | 40/min | 200 |
CLAIMS_LIST_WITHOUT_ROLE | PSP | listClaims | 10/min | 50 |
SYNC_VERIFICATIONS_WRITE | PSP | createSyncVerification | 10/min | 50 |
CIDS_FILES_WRITE | PSP | createCidSetFile | 40/dia | 200 |
CIDS_FILES_READ | PSP | getCidSetFile | 10/min | 50 |
CIDS_EVENTS_LIST | PSP | listCidSetEvents | 20/min | 100 |
CIDS_ENTRIES_READ | PSP | getEntryByCid | 1200/min | 36000 |
INFRACTION_REPORTS_READ | PSP | getInfractionReport | 600/min | 18000 |
INFRACTION_REPORTS_WRITE | PSP | createInfractionReport, acknowledgeInfractionReport, cancelInfractionReport, closeInfractionReport | 1200/min | 36000 |
INFRACTION_REPORTS_LIST_WITH_ROLE | PSP | listInfractionReports | 40/min | 200 |
INFRACTION_REPORTS_LIST_WITHOUT_ROLE | PSP | listInfractionReports | 10/min | 50 |
KEYS_CHECK | PSP | checkKeys | 70/min | 70 |
REFUNDS_READ | PSP | getRefund | 1200/min | 36000 |
REFUNDS_WRITE | PSP | createRefund, cancelRefund, closeRefund | 2400/min | 72000 |
REFUND_LIST_WITH_ROLE | PSP | listRefunds | 40/min | 200 |
REFUND_LIST_WITHOUT_ROLE | PSP | listRefunds | 10/min | 50 |
FRAUD_MARKERS_READ | PSP | getFraudMarker | 600/min | 18000 |
FRAUD_MARKERS_WRITE | PSP | createFraudMarker, cancelFraudMarker | 1200/min | 36000 |
FRAUD_MARKERS_LIST | PSP | listPersonFraudMarkers, listEntryFraudMarkers | 1200/min | 36000 |
PERSONS_STATISTICS_READ | PSP | getPersonStatistics | 12000/min | 36000 |
POLICIES_READ | PSP | getBucketState | 60/min | 200 |
POLICIES_LIST | PSP | listBucketStates | 6/min | 20 |
ENTRIES_READ_USER_ANTISCAN
ENTRIES_READ_USER_ANTISCAN_V2
(*) O tamanho do balde das políticas ENTRIES_READ_USER_ANTISCAN e ENTRIES_READ_USER_ANTISCAN_V2 é categorizado de acordo com o tipo de usuário final realizando a consulta, Pessoa Física (PF) ou Pessoa Jurídica (PJ):
Categoria | Taxa de reposição | Tamanho do balde |
---|---|---|
PF | 2/min | 100 |
PJ | 20/min | 1.000 |
ENTRIES_READ_PARTICIPANT_ANTISCAN
(**) O tamanho do balde nesta política depende da categoria em que se enquadra do participante. As seguintes categorias são possíveis:
Categoria | Taxa de reposição | Tamanho do balde |
---|---|---|
A | 25.000/min | 50.000 |
B | 20.000/min | 40.000 |
C | 15.000/min | 30.000 |
D | 8.000/min | 16.000 |
E | 2.500/min | 5.000 |
F | 250/min | 500 |
G | 25/min | 250 |
H | 2/min | 50 |
CLAIMS_LIST_WITH_ROLE
CLAIMS_LIST_WITHOUT_ROLE
REFUND_LIST_WITH_ROLE
REFUND_LIST_WITHOUT_ROLE
Demais políticas
Caso o limite de uma política seja excedido, o que acontece quando a quantidade de fichas chega
a zero, será retornada uma resposta de erro com status 429
.
É altamente recomendável que as conexões HTTP para a comunicação com a API sejam reutilizadas, pois o custo de
estabelecimento de uma conexão mTLS é muito alto em termos de latência. O uso de um pool de conexões HTTP
é uma alternativa efetiva para reutilização de conexões. A API retorna o header Keep-Alive
com o parâmetro timeout
. Nele é informado o tempo em segundos que o servidor esperará antes de fechar a conexão caso não ocorram
requisições adicionais.
É recomendável também que se utilize compressão. Para que as respostas da API utilizem compressão, adicione nas
requisições o header Accept-Encoding: gzip
. O envio de requisições com compressão não é suportado.
As seguintes mudanças são esperadas e consideradas compatíveis:
A versão da API é composta por 4 elementos: major, minor, patch e release candidate.
A versão que consta no path da URL é o elemento major da versão da API.
A evolução da versão se dá seguinte forma:
Não serão feitas mais que uma evolução major em um período de 6 meses, ressalvado motivo de força maior. Quando houver uma evolução major, a versão anterior ficará disponível por no mínimo 1 mês.
Alterações sem quebra de contrato e esclarecimentos às especificações podem ocorrer a qualquer momento. Clientes devem estar preparados para lidar com essas mudanças sem quebrar.
Os pontos de alteração em relação a cada versão anterior estão disponíveis no changelog
O DICT retorna códigos de status HTTP para indicar sucesso ou falhas das requisições. Códigos 2xx indicam sucesso. Códigos 4xx indicam falhas causadas pelas informações enviadas pelo cliente ou pelo estado atual das entidades. Códigos 5xx indicam problemas no serviço no lado do DICT.
As respostas de erro incluem no corpo detalhes do erro seguindo o schema da RFC
Problem Details for HTTP APIs.
O campo type
identifica o tipo de erro e no DICT segue o padrão:
https://dict.pi.rsfn.net.br/api/v2/error/<TipoErro>
Abaixo estão listados os tipos de erro do DICT.
Tipo de erro | Código | Descrição |
---|---|---|
Geral | ||
Forbidden
|
403 | Requisição de participante autenticado viola alguma regra de autorização |
BadRequest
|
400 | Requisição com formato inválido |
NotFound
|
404 | Entidade não encontrada |
Gone
|
410 | Recurso não está mais disponível |
RateLimited
|
429 |
Limite de requisições foi atingido Ver seção sobre limitação de requisições |
InternalServerError
|
500 | Condição inesperada ao processar requisição. |
ServiceUnavailable
|
503 |
Serviço não está disponível no momento. Pode estar em manutenção ou fora da janela de funcionamento. |
RequestSignatureInvalid
|
400 | Assinatura digital da requisição enviada é inválida. |
RequestIdAlreadyUsed
|
400 |
Requisição foi feita com mesmo `RequestId` de requisição feita anteriormente, mas com parâmetros diferentes. |
InvalidReason
|
400 | Requisição foi feita com uma razão inválida para a operação |
ParticipantInvalid
|
400 |
O participante não pode participar na operação solicitada. |
TaxIdNumberBlocked
|
400 |
O CPF/CNPJ encontra-se bloqueado por ordem judicial. |
Vínculo | ||
EntryInvalid
|
400 | Existem campos inválidos ao tentar criar ou atualizar vínculo |
EntryLimitExceeded
|
400 | Número de vínculos associados a conta transacional excedeu o limite máximo |
EntryAlreadyExists
|
400 | Já existe vínculo para essa chave com o mesmo participante e dono |
EntryCannotBeQueriedForBookTransfer
|
400 | Vínculo consultado está custodiado no mesmo PSP do usuário pagador para quem está sendo feita a consulta. Quando o pagador e o recebedor estão no mesmo PSP, não deve ser feita consulta ao DICT. |
EntryKeyOwnedByDifferentPerson
|
400 |
Já existe vínculo para essa chave mas ela é possuída por outra pessoa. Indica-se que seja feita uma reivindicação de posse. |
EntryKeyInCustodyOfDifferentParticipant
|
400 | Já existe vínculo para essa chave com o mesmo dono, mas ela encontra-se associada a outro participante. Indica-se que seja feita uma reivindicação de portabilidade. |
EntryLockedByClaim
|
400 | Existe uma reivindicação com status diferente de concluída ou cancelada para a chave do vínculo. Enquanto estiver nessa situação, o vínculo não pode ser excluído. |
EntryTaxIdNumberByDifferentOwner
|
400 | CPF/CNPJ do vínculo diferente do CPF/CNPJ do dono da chave |
EntryBlocked
|
400 | O vínculo encontra-se bloqueado por ordem judicial e não pode ser consultado |
Reivindicação | ||
ClaimInvalid
|
400 | Existem campos inválidos ao tentar criar ou atualizar reivindicação |
ClaimTypeInconsistent
|
400 | Tipo de reivindicação pedida é inconsistente. Esse erro ocorre nas situações em que se tenta criar a) reivindicação de posse, mas vínculo existente tem como dona a mesma pessoa que reivindica ou b) reinvidicação de portabilidade, mas vínculo existente tem como dona pessoa diferente da que reivindica. |
ClaimKeyNotFound
|
404 | Não existe vínculo registrado com a chave que está sendo reivindicada. |
ClaimAlreadyExistsForKey
|
400 | Existe uma reivindicação com status diferente de concluída ou cancelada para a chave reivindicada. Nova reivindicação para a chave só pode ser criada se a atual foi concluída ou cancelada. |
ClaimResultingEntryAlreadyExists
|
400 | Vínculo que resultaria ao processar reivindicação já existe, com mesma chave, participante e dono. |
ClaimOperationInvalid
|
400 | Status atual da reivindicação não permite que operação seja feita. |
ClaimResolutionPeriodNotEnded
|
400 | Para reivindicação de posse, PSP doador não pode confirmar antes do término do período resolução. Para portabilidade, PSP doador não pode cancelar por fim de prazo antes do término do período resolução. |
ClaimCompletionPeriodNotEnded
|
400 | Para reivindicação de posse, se PSP reivindicador tenta encerrar antes do término do período encerramento. |
Notificação de infração | ||
InfractionReportInvalid
|
400 | Existem campos inválidos ao tentar criar ou atualizar a notificação de infração. |
InfractionReportOperationInvalid
|
400 | Status atual da notificação de infração não permite que operação seja feita. |
InfractionReportTransactionNotFound
|
400 | A transação definida na notificação de infração não foi encontrada. |
InfractionReportTransactionNotSettled
|
400 | A transação definida na notificação de infração não foi liquidada. |
InfractionReportAlreadyBeingProcessedForTransaction
|
400 | Já existe uma notificação de infração em andamento para a transação informada. |
InfractionReportAlreadyProcessedForTransaction
|
400 | Já existe uma notificação de infração fechado para a transação informada. |
InfractionReportPeriodExpired
|
400 | O prazo para a notificação de infração sobre a transação expirou. |
Marcação de fraude | ||
FraudMarkerInvalid
|
400 | Existem campos inválidos ao tentar criar a marcação de fraude. |
Solicitação de Devolução | ||
RefundInvalid
|
400 | Existem campos inválidos ao tentar criar ou atualizar a solicitação de devolução. |
RefundOperationInvalid
|
400 | Status atual da solicitação de devolução não permite que operação seja feita. |
RefundTransactionNotFound
|
400 | A transação definida na solicitação de devolução não foi encontrada. |
RefundTransactionNotSettled
|
400 | A transação definida na solicitação de devolução não foi liquidada. |
RefundAlreadyProcessedForTransaction
|
400 | Já existe uma solicitação de devolução processada para a transação informada. |
RefundAlreadyBeingProcessedForTransaction
|
400 | Já existe uma solicitação de devolução em processamento para a transação informada. |
RefundPeriodExpired
|
400 | O prazo para solicitar devolução para a transação expirou. |
TransactionNotRefundable
|
400 | A transação informada na requisição não permite devolução. |
RefundInfractionReportNotFound
|
400 | Uma notificação de infração correspondente à transação informada não foi encontrada. |
TransactionRefundable
|
400 |
Transação informada permite devolução. |
O diretório de identificadores de contas transacionais é um conjunto de vínculos. Um vínculo é uma associação entre uma chave de endereçamento, uma conta transacional e seu dono. O dono pode ser uma pessoa física ou uma pessoa jurídica. A chave de endereçamento é usada para identificar unicamente um vínculo.
Exemplo de vínculo:
Chave | Conta | Dono |
---|---|---|
+5510998765432 | Banco Fictício/Ag.7263-4/Cc.748627-1 | José João da Silva |
Cria um novo vínculo de chave com conta transacional.
A operação de criação de vínculo é idempotente. Isso significa que é seguro realizar uma nova tentativa em caso de falhas temporárias, como erros de conexão ou término abrupto de processos. A resposta retornada para uma requisição repetida é equivalente à resposta dada à primeira requisição processada.
Para garantir a idempotência da operação, a requisição tem um campo RequestId
. Esse campo é um
UUID versão 4 e deve ser único no contexto de um mesmo participante.
O RequestId
fica associado ao vínculo criado e é usado no cálculo do seu CID (ver seção de reconciliação).
Uma requisição de criação é considerada repetida quando o CID do vínculo contido na requisição já existe no DICT.
Caso seja feita uma requisição com um RequestId
previamente usado, mas com parâmetros diferentes para o vínculo,
será retornado o erro RequestIdAlreadyUsed
.
Signature | object |
required | object (Entry) Vínculo entre uma chave de endereçamento, conta transacional e seu dono. |
Reason required | string Enum: "USER_REQUESTED" "ACCOUNT_CLOSURE" "BRANCH_TRANSFER" "RECONCILIATION" "FRAUD" "RFB_VALIDATION" Valores válidos: |
RequestId required | string <uuid> (RequestId) Chave de idempotência da requisição. UUID versão 4. |
<?xml version="1.0" encoding="UTF-8" ?> <CreateEntryRequest> <Signature></Signature> <Entry> <Key>+5561988880000</Key> <KeyType>PHONE</KeyType> <Account> <Participant>12345678</Participant> <Branch>0001</Branch> <AccountNumber>0007654321</AccountNumber> <AccountType>CACC</AccountType> <OpeningDate>2010-01-10T03:00:00Z</OpeningDate> </Account> <Owner> <Type>NATURAL_PERSON</Type> <TaxIdNumber>11122233300</TaxIdNumber> <Name>João Silva</Name> </Owner> </Entry> <Reason>USER_REQUESTED</Reason> <RequestId>a946d533-7f22-42a5-9a9b-e87cd55c0f4d</RequestId> </CreateEntryRequest>
<?xml version="1.0" encoding="UTF-8" ?> <CreateEntryResponse> <Signature></Signature> <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime> <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId> <Entry> <Key>11122233300</Key> <KeyType>CPF</KeyType> <Account> <Participant>12345678</Participant> <Branch>0001</Branch> <AccountNumber>0007654321</AccountNumber> <AccountType>CACC</AccountType> <OpeningDate>2010-01-10T03:00:00.000Z</OpeningDate> </Account> <Owner> <Type>NATURAL_PERSON</Type> <TaxIdNumber>11122233300</TaxIdNumber> <Name>João Silva</Name> </Owner> <CreationDate>2019-11-18T03:00:00.000Z</CreationDate> <KeyOwnershipDate>2019-11-18T03:00:00.000Z</KeyOwnershipDate> </Entry> </CreateEntryResponse>
Obtém um vínculo contendo os detalhes de conta transacional associados a uma chave de endereçamento.
A consulta a chaves está sujeita à política de limitação (rate-limiting) de requisições. A limitação funciona com base em cabeçalhos enviados na requisição. Os cabeçalhos de requisição são obrigatórios para todos os tipos de chaves.
O parâmetro PI-PayerId
é o identificador do usuário final e é usado para aplicar as políticas de
limitação com escopo de usuário. Deve ser preenchido com o CPF ou CNPJ (apenas dígitos), a depender
do tipo da entidade titular da conta pagadora.
Consultas a vínculos podem ter suas respostas cacheadas no PSP, devendo seguir as
diretivas contidas no header Cache-Control
.
Importante: Para fazer uso de cache, clientes HTTP geralmente precisam ser configurados. Não é comum que tenham essa funcionalidade habilitada por padrão.
Através do parâmetro opcional IncludeStatistics
, é possível indicar se as informações de contadores antifraude
devem ou não ser incluídas na resposta.
Key required | string (Key) <= 77 characters Example: 12345678901 |
IncludeStatistics | boolean Default: false Incluir dados antifraude na resposta. |
PI-RequestingParticipant required | string^[0-9]{8}$ Example: 12345678 Identificador único do requisitante, podendo ser:
|
PI-PayerId required | string^([0-9]{11}|[0-9]{14})$ Identificador do pagador que originou a requisição. Usado para rate-limiting. |
PI-EndToEndId required | string Identificador fim-a-fim do pagamento associado a essa requisição. Corresponde ao campo |
<?xml version="1.0" encoding="UTF-8" ?> <GetEntryResponse> <Signature></Signature> <ResponseTime>2020-01-10T10:00:00Z</ResponseTime> <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId> <Entry> <Key>11122233300</Key> <KeyType>CPF</KeyType> <Account> <Participant>12345678</Participant> <Branch>0001</Branch> <AccountNumber>0007654321</AccountNumber> <AccountType>CACC</AccountType> <OpeningDate>2010-01-10T03:00:00Z</OpeningDate> </Account> <Owner> <Type>NATURAL_PERSON</Type> <TaxIdNumber>11122233300</TaxIdNumber> <Name>João Silva</Name> </Owner> <CreationDate>2019-11-18T03:00:00Z</CreationDate> <KeyOwnershipDate>2019-11-18T03:00:00Z</KeyOwnershipDate> <OpenClaimCreationDate>2019-11-19T03:00:00Z</OpenClaimCreationDate> </Entry> <OwnerStatistics> <Spi> <Watermark>2023-01-01T10:00:00.000Z</Watermark> <Settlements d90="0" m12="0" m60="0"/> </Spi> <FraudMarkers> <Watermark>2023-01-01T10:00:00.000Z</Watermark> <ApplicationFrauds d90="0" m12="0" m60="0"/> <MuleAccounts d90="0" m12="0" m60="0"/> <ScammerAccounts d90="0" m12="0" m60="0"/> <OtherFrauds d90="0" m12="0" m60="0"/> <UnknownFrauds d90="0" m12="0" m60="0"/> <TotalFraudTransactionAmount d90="0" m12="0" m60="0"/> <DistinctFraudReporters d90="0" m12="0" m60="0"/> </FraudMarkers> <InfractionReports> <Watermark>2023-01-01T10:00:00.000Z</Watermark> <OpenReports>0</OpenReports> <OpenReportsDistinctReporters>0</OpenReportsDistinctReporters> <RejectedReports d90="0" m12="0" m60="0"/> </InfractionReports> <Entries> <Watermark>2023-01-01T10:00:00.000Z</Watermark> <RegisteredAccounts>0</RegisteredAccounts> </Entries> </OwnerStatistics> <KeyStatistics> <Spi> <Watermark>2023-01-01T10:00:00.000Z</Watermark> <Settlements d90="0" m12="0" m60="0"/> </Spi> <FraudMarkers> <Watermark>2023-01-01T10:00:00.000Z</Watermark> <ApplicationFrauds d90="0" m12="0" m60="0"/> <MuleAccounts d90="0" m12="0" m60="0"/> <ScammerAccounts d90="0" m12="0" m60="0"/> <OtherFrauds d90="0" m12="0" m60="0"/> <UnknownFrauds d90="0" m12="0" m60="0"/> <TotalFraudTransactionAmount d90="0" m12="0" m60="0"/> <DistinctFraudReporters d90="0" m12="0" m60="0"/> </FraudMarkers> <InfractionReports> <Watermark>2023-01-01T10:00:00.000Z</Watermark> <OpenReports>0</OpenReports> <OpenReportsDistinctReporters>0</OpenReportsDistinctReporters> <RejectedReports d90="0" m12="0" m60="0"/> </InfractionReports> <Entries> <Watermark>2023-01-01T10:00:00.000Z</Watermark> <DistinctAccounts d90="0" m12="0" m60="0"/> </Entries> </KeyStatistics> </GetEntryResponse>
Atualiza um vínculo.
A ser utilizado no cenário de atualização da informação da conta, nome e nome fantasia de um cliente, permanecendo este no mesmo PSP. Somente podem ser atualizadas as informações de conta do vínculo, nome e nome fantasia do cliente. Outras atualizações do vínculo devem ser feitas por exclusão/inclusão do vínculo, portabilidade ou reivindicação de posse, a depender da situação.
As seguintes restrições devem ser obedecidas na atualização de vínculo, de acordo com o tipo de chave:
EVP
(aleatórias) - Não é permitida a alteração.USER_REQUESTED
, BRANCH_TRANSFER
ou RECONCILIATION
.Key required | string (Key) <= 77 characters Example: 12345678901 |
Signature | object |
Key required | string (Key) <= 77 characters |
object (BrazilianAccount) Dados de conta transacional no Brasil. | |
NATURAL_PERSON (object) or LEGAL_PERSON (object) (Person) Dados de pessoa física ou jurídica | |
Reason required | string Enum: "USER_REQUESTED" "ACCOUNT_CLOSURE" "BRANCH_TRANSFER" "RECONCILIATION" "FRAUD" "RFB_VALIDATION" Valores válidos: |
<?xml version="1.0" encoding="UTF-8" ?> <UpdateEntryRequest> <Signature></Signature> <Key>+5561988887777</Key> <Account> <Participant>12345678</Participant> <Branch>0001</Branch> <AccountNumber>0007654321</AccountNumber> <AccountType>CACC</AccountType> <OpeningDate>2010-01-10T03:00:00Z</OpeningDate> </Account> <Owner> <Type>NATURAL_PERSON</Type> <TaxIdNumber>11122233300</TaxIdNumber> <Name>João Silva</Name> </Owner> <Reason>USER_REQUESTED</Reason> </UpdateEntryRequest>
<?xml version="1.0" encoding="UTF-8" ?> <UpdateEntryResponse> <Signature></Signature> <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime> <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId> <Entry> <Key>11122233300</Key> <KeyType>CPF</KeyType> <Account> <Participant>12345678</Participant> <Branch>0001</Branch> <AccountNumber>0007654321</AccountNumber> <AccountType>CACC</AccountType> <OpeningDate>2010-01-10T03:00:00.000Z</OpeningDate> </Account> <Owner> <Type>NATURAL_PERSON</Type> <TaxIdNumber>11122233300</TaxIdNumber> <Name>João Silva</Name> </Owner> <CreationDate>2019-11-18T03:00:00.000Z</CreationDate> <KeyOwnershipDate>2019-11-18T03:00:00.000Z</KeyOwnershipDate> </Entry> </UpdateEntryResponse>
Remove um vínculo de chave com conta.
Key required | string (Key) <= 77 characters Example: 12345678901 |
Signature | object |
Key required | string (Key) <= 77 characters |
Participant required | string^[0-9]{8}$ Identificador SPB do provedor da conta ao qual a chave está vinculada |
Reason required | string Enum: "USER_REQUESTED" "ACCOUNT_CLOSURE" "BRANCH_TRANSFER" "RECONCILIATION" "FRAUD" "RFB_VALIDATION" Valores válidos: |
<?xml version="1.0" encoding="UTF-8" ?> <DeleteEntryRequest> <Signature></Signature> <Key>+5561988887777</Key> <Participant>12345678</Participant> <Reason>ACCOUNT_CLOSURE</Reason> </DeleteEntryRequest>
<?xml version="1.0" encoding="UTF-8" ?> <DeleteEntryResponse> <Signature></Signature> <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime> <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId> <Key>+5561988887777</Key> </DeleteEntryResponse>
Uma chave é uma string que identifica um vínculo de forma única no diretório de identificadores. A existência de uma chave no diretório implica a existência de um vínculo.
Os tipos de chave suportadas atualmente são as seguintes:
Tipo | Exp. regular | Exemplo | Comentário |
---|---|---|---|
CPF | ^[0-9]{11}$ | 12345678901 | |
CNPJ | ^[0-9]{14}$ | 12345678901234 | |
PHONE | ^\+[1-9]\d{1,14}$ | +5510998765432 | |
^[a-z0-9.!#$&'*+\/=?^_`{|}~-]+@[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$ | [email protected] | E-mail deve possuir no máximo 77 caracteres e deve ser em minúsculo | |
EVP | ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ | 123e4567-e89b-12d3-a456-426655440000 | Endereço Virtual de Pagamento é um tipo de chave é gerado pelo DICT |
Novos tipos de chave poderão vir a ser adicionados no futuro. Logo, é importante que a implementação de clientes seja flexível, permitindo a adição de novos tipos de chave.
Consulta a existência de um conjunto de chaves no diretório de identificadores.
Keys required | Array of strings (Key) [ 1 .. 200 ] items [ items <= 77 characters ] Chaves de endereçamento |
<?xml version="1.0" encoding="UTF-8" ?> <CheckKeysRequest> <Keys> <Key>[email protected]</Key> <Key>[email protected]</Key> <Key>+5561999999999</Key> <Key>+5561888888888</Key> <Key>99999999999</Key> <Key>99999999999999</Key> </Keys> </CheckKeysRequest>
<?xml version="1.0" encoding="UTF-8" ?> <CheckKeysResponse> <Signature></Signature> <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime> <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId> <Keys> <Key hasEntry="true">[email protected]</Key> <Key hasEntry="false">[email protected]</Key> <Key hasEntry="true">+5561999999999</Key> <Key hasEntry="false">+5561888888888</Key> <Key hasEntry="false">99999999999</Key> <Key hasEntry="true">99999999999999</Key> </Keys> </CheckKeysResponse>
Conforme as chaves mudem de dono ou os usuários finais criem contas transacionais em outros PSPs, os seguintes cenários precisarão ser tratados:
Para o cenário 1, deve ser criada uma reivindicação de posse. Já para o cenário 2, uma portabilidade. Em ambos cenários existirá a figura do PSP que irá ceder a chave (PSP Doador), e o PSP que irá receber a chave (PSP Reivindicador). No cenário de reivindicação de posse, o PSP doador e o reivindicador podem ser o mesmo.
Nessa especificação, reivindicação sem qualificador é usado como termo mais genérico para se referir tanto à reivindicação de posse quanto à (reivindicação de) portabilidade.
Os processos de reivindicação são sempre iniciados pelo PSP reivindicador. Uma reivindicação tem as seguintes situações:
OPEN
- Aberta pelo reivindicador, mas ainda não recebida pelo doador.WAITING_RESOLUTION
- Já foi recebida pelo doador e está aguardando a resolução. Os critérios confirmação
ou cancelamento da reivindicação seguem normas específicas a depender do tipo (posse ou portabilidade).CONFIRMED
- O doador confirmou a reivindicação. Isso implica a remoção da chave do DICT e da base interna
do PSP doador. Está aguardando o reivindicador encerrar o processo.CANCELLED
- O doador ou reivindicador cancelou a reivindicação.COMPLETED
- Tanto o DICT quanto o reivindicador atualizaram suas bases com o novo vínculo.Diagrama de estados
( OPEN )------->( WAITING_RESOLUTION )------->( CONFIRMED )------->( COMPLETED )
\ | /
\ | /
\ | /
\ | /
\ v /
v---------->( CANCELLED )<-----------v
Importante! Os participantes deverão monitorar as reivindicações fazendo polling períodico no endpoint de listar reivindicações. A periodicidade adequada dependerá das definições de nível de serviço. Consulte o Manual de Tempos do Pix.
Cria uma nova reivindicação.
Essa operação é feita pelo participante reivindicador a pedido do usuário final. O vínculo atual permanece inalterado, até que haja a confirmação pelo PSP doador.
Nem todo tipo de chave pode ser reivindicado ou portado. A tabela abaixo define as possibilidades:
compatível? | OWNERSHIP | PORTABILITY |
---|---|---|
CPF | ✓ | |
CNPJ | ✓ | |
PHONE | ✓ | ✓ |
✓ | ||
EVP |
Signature | object |
required | object (Claim) |
<?xml version="1.0" encoding="UTF-8" ?> <CreateClaimRequest> <Signature></Signature> <Claim> <Type>OWNERSHIP</Type> <Key>+5561988887777</Key> <KeyType>PHONE</KeyType> <ClaimerAccount> <Participant>12345678</Participant> <Branch>0001</Branch> <AccountNumber>0007654321</AccountNumber> <AccountType>CACC</AccountType> <OpeningDate>2010-01-10T03:00:00Z</OpeningDate> </ClaimerAccount> <Claimer> <Type>NATURAL_PERSON</Type> <TaxIdNumber>11122233300</TaxIdNumber> <Name>João Silva</Name> </Claimer> </Claim> </CreateClaimRequest>
<?xml version="1.0" encoding="UTF-8" ?> <CreateClaimResponse> <Signature></Signature> <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime> <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId> <Claim> <Type>OWNERSHIP</Type> <Key>+5561988887777</Key> <KeyType>PHONE</KeyType> <ClaimerAccount> <Participant>12345678</Participant> <Branch>0001</Branch> <AccountNumber>0007654321</AccountNumber> <AccountType>CACC</AccountType> <OpeningDate>2010-01-10T03:00:00.000Z</OpeningDate> </ClaimerAccount> <Claimer> <Type>NATURAL_PERSON</Type> <TaxIdNumber>11122233300</TaxIdNumber> <Name>João Silva</Name> </Claimer> <DonorParticipant>87654321</DonorParticipant> <Id>123e4567-e89b-12d3-a456-426655440000</Id> <Status>OPEN</Status> <CompletionPeriodEnd>2020-01-17T10:00:00.000Z</CompletionPeriodEnd> <ResolutionPeriodEnd>2020-01-17T10:00:00.000Z</ResolutionPeriodEnd> <LastModified>2020-01-10T10:00:00.000Z</LastModified> </Claim> </CreateClaimResponse>
Obtém uma lista de reivindicações, ordenada de forma crescente pelo campo LastModified
, de acordo com os filtros passados.
Observações:
isDonor
e isClaimer
, quando os valores passados são iguais, é disjuntivo: são retornadas reinvidicações em que
o participante é doador OU reivindicador.Participant required | string^[0-9]{8} ISPB do partipante direto ou indireto interessado |
IncludeIndirectParticipants | boolean Default: false Inclui adicionalmente as reivindicações de participantes indiretos |
IsDonor | boolean |