DICT API (2.1.0)

Download OpenAPI specification:Download

Suporte TI BCB: suporte.ti@bcb.gov.br URL: https://www.bcb.gov.br/estabilidadefinanceira/pagamentosinstantaneos License: Apache 2.0

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.

⚠️ Para perguntas frequentes sobre a versão 2 da API, consulte a página de dúvidas

Segurança

Autenticação

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.

Assinatura digital

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.

Limitação de requisições

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
PERSONS_STATISTICS_READ	PSP	getPersonStatistics	12000/min	36000
POLICIES_READ	PSP	getBucketState	60/min	200
POLICIES_LIST	PSP	listBucketStates	6/min	20

Regras de contagem das políticas

ENTRIES_READ_USER_ANTISCAN
- Aplicável somente para chaves do tipo EMAIL e PHONE
- status 200: subtrai 1
- status 404: subtrai 20
- ordem de pagamento enviada
  - adiciona 1 para categoria Pessoa Física (PF)
  - adiciona 2 para categoria Pessoa Jurídica (PJ)
ENTRIES_READ_USER_ANTISCAN_V2
- Aplicável somente para chaves do tipo CPF, CNPJ e EVP
- status 200: subtrai 1
- status 404: subtrai 20
- ordem de pagamento enviada
  - adiciona 1 para categoria Pessoa Física (PF)
  - adiciona 2 para categoria Pessoa Jurídica (PJ)
(*) 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

Categoria	Taxa de reposição	Tamanho do balde
PF	2/min	100
PJ	20/min	1.000

ENTRIES_READ_PARTICIPANT_ANTISCAN

Aplicável para todos os tipos de chaves (EMAIL, PHONE, CPF, CNPJ e EVP)
status 200: subtrai 1
status 404: subtrai 3
ordem de pagamento enviada: adiciona 1

(**) 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
- Aplicável quando há filtragem por doador/reivindicador
- status diferente de 500: subtrai 1
CLAIMS_LIST_WITHOUT_ROLE
- Aplicável quando não há filtragem por doador/reivindicador
- status diferente de 500: subtrai 1
REFUND_LIST_WITH_ROLE
- Aplicável quando há filtragem por requisitante/contestado
- status diferente de 500: subtrai 1
REFUND_LIST_WITHOUT_ROLE
- Aplicável quando não há filtragem por requisitante/contestado
- status diferente de 500: subtrai 1
Demais políticas
- status diferente de 500: subtrai 1

Violação de limites

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.

Recomendações de desempenho

É 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.

Evolução da API

As seguintes mudanças são esperadas e consideradas compatíveis:

Adição de novos recursos na API.
Adição de novos parâmetros opcionais a requisições.
Adição de novos campos em respostas da API.
Alteração da ordem de campos.
Adição de novos elementos em enumerações

Versionamento

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:

Major: alterações incompatíveis, com quebra de contrato (v1.0.0 → v2.0.0)
Minor: alterações compatíveis, sem quebra de contrato (v1.1.0 → v1.2.0)
Patch: esclarecimentos às especificações, sem alterações funcionais (v1.1.1 → v1.1.2)
Release candidate: versões de pré-lançamento de qualquer patch futuro, minor ou major (v1.0.0-rc1 → v1.0.0-rc2)

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.

Histórico de Mudanças

Os pontos de alteração em relação a cada versão anterior estão disponíveis no changelog

Tratamento de erros

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.
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.
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.

Diretório

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

Criar Vínculo

Cria um novo vínculo de chave com conta transacional.

Idempotência

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.

Request Body schema: application/xml

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" Valores válidos: `USER_REQUESTED` e `RECONCILIATION`
RequestId required	string <uuid> (RequestId) Chave de idempotência da requisição. UUID versão 4.

Responses

Request samples

Payload

Content type

application/xml

<?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>

Response samples

201
400
403
503

Content type

application/xml

<?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>

Consultar Vínculo

Obtém um vínculo contendo os detalhes de conta transacional associados a uma chave de endereçamento.

Limitação de requisições

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.

Cache

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.

Estatísticas

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.

path Parameters

Key

required

string (Key) <= 77 characters

Example: 12345678901

query Parameters

IncludeStatistics

boolean

Default: false

Incluir dados antifraude na resposta.

header Parameters

PI-RequestingParticipant required	string^[0-9]{8}$ Example: 12345678 Identificador único do requisitante, podendo ser: ISPB do participante (direto ou indireto) que faz a requisição OU 8 primeiros dígitos do CNPJ para Iniciadores de Pagamento
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 `EndToEndId` na mensagem pacs.008. Usado para rate-limiting.

Responses

Response samples

200
404
429

Content type

application/xml

Example

entry-include-statistics

<?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>

Atualizar Vínculo

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.

Restrições

As seguintes restrições devem ser obedecidas na atualização de vínculo, de acordo com o tipo de chave:

Chaves EVP (aleatórias) - É permitida a alteração, porém, apenas com os motivos BRANCH_TRANSFER ou RECONCILIATION.
Demais chaves - É permitida a alteração com os motivos USER_REQUESTED, BRANCH_TRANSFER ou RECONCILIATION.

path Parameters

Key

required

string (Key) <= 77 characters

Example: 12345678901

Request Body schema: application/xml

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" Valores válidos: `USER_REQUESTED`, `BRANCH_TRANSFER` e `RECONCILIATION`

Responses

Request samples

Payload

Content type

application/xml

<?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>

Response samples

200
400
403
404
503

Content type

application/xml

<?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>

Remover Vínculo

Remove um vínculo de chave com conta.

path Parameters

Key

required

string (Key) <= 77 characters

Example: 12345678901

Request Body schema: application/xml

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" Valores válidos: `USER_REQUESTED`, `ACCOUNT_CLOSURE`, `RECONCILIATION` e `FRAUD`

Responses

Request samples

Payload

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<DeleteEntryRequest>
    <Signature></Signature>
    <Key>+5561988887777</Key>
    <Participant>12345678</Participant>
    <Reason>ACCOUNT_CLOSURE</Reason>
</DeleteEntryRequest>

Response samples

200
403
404
503

Content type

application/xml

<?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>

Chave

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
EMAIL	^[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])?)$	pix@bcb.gov.br	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.

Verificar existência de chaves

Consulta a existência de um conjunto de chaves no diretório de identificadores.

Request Body schema: application/xml

Keys

required

Array of strings (Key) [ 1 .. 200 ] items [ items <= 77 characters ]

Chaves de endereçamento

Responses

Request samples

Payload

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<CheckKeysRequest>
    <Keys>
        <Key>mail@mail.com</Key>
        <Key>mail2@mail.com</Key>
        <Key>+5561999999999</Key>
        <Key>+5561888888888</Key>
        <Key>99999999999</Key>
        <Key>99999999999999</Key>
    </Keys>
</CheckKeysRequest>

Response samples

200
403
503

Content type

application/xml

<?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">mail@mail.com</Key>
        <Key hasEntry="false">mail2@mail.com</Key>
        <Key hasEntry="true">+5561999999999</Key>
        <Key hasEntry="false">+5561888888888</Key>
        <Key hasEntry="false">99999999999</Key>
        <Key hasEntry="true">99999999999999</Key>
    </Keys>
</CheckKeysResponse>

Reivindicação

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:

Houve troca de posse de uma chave (telefone ou email) e o novo dono deseja criar um vínculo para uma conta sua mas o dono anterior já possui vínculo registrado no DICT com essa chave.
Um usuário deseja mudar a vinculação de uma chave sua para outra conta, que está domiciliada em um participante diferente do atual.

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.

Criar Reivindicação

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	✓	✓
EMAIL	✓	✓
EVP

Request Body schema: application/xml

Signature	object
required	object (Claim)

Responses

Request samples

Payload

Content type

application/xml

<?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>

Response samples

201
400
403
503

Content type

application/xml

<?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>

Listar Reivindicações

Obtém uma lista de reivindicações, ordenada de forma crescente pelo campo LastModified, de acordo com os filtros passados.

Observações:

Ao percorrer a lista em intervalos de tempo fechados, recomendável para que não se pule nenhum elemento, alguns elementos retornados poderão se repetir.
O comportamento dos filtros isDonor e isClaimer, quando os valores passados são iguais, é disjuntivo: são retornadas reinvidicações em que o participante é doador OU reivindicador.

query Parameters

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 Restringe a reivindicações em que o participante é doador
IsClaimer	boolean Restringe a reivindicações em que o participante é reivindicador
Status	Array of strings (ClaimStatus) Items Enum: "OPEN" "WAITING_RESOLUTION" "CONFIRMED" "CANCELLED" "COMPLETED" Lista de ClaimStatus a serem pesquisados
Type	string (ClaimType) Enum: "OWNERSHIP" "PORTABILITY" Tipo de reivindicação
ModifiedAfter	string <date-time> Filtra reivindicações com data-hora de modificação maior ou igual a `modifiedAfter`
ModifiedBefore	string <date-time> Filtra reivindicações com data-hora de modificação menor ou igual a `modifiedBefore`
Limit	integer <= 200 Default: 20 Número limite de reivindicações a retornar

Responses

Response samples

200
400
403

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<ListClaimsResponse>
    <Signature></Signature>
    <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime>
    <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId>
    <HasMoreElements>true</HasMoreElements>
    <Claims>
        <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>CANCELLED</Status>
            <ResolutionPeriodEnd>2020-01-17T10:00:00.000Z</ResolutionPeriodEnd>
            <CompletionPeriodEnd>2020-01-17T10:00:00.000Z</CompletionPeriodEnd>
            <LastModified>2020-01-10T10:00:00.000Z</LastModified>
            <ConfirmReason>DEFAULT_OPERATION</ConfirmReason>
            <CancelReason>FRAUD</CancelReason>
            <CancelledBy>DONOR</CancelledBy>
        </Claim>
    </Claims>
</ListClaimsResponse>

Consultar Reivindicação

Obtém detalhes de uma reivindicação.

path Parameters

ClaimId

required

string <uuid>

header Parameters

PI-RequestingParticipant

required

string^[0-9]{8}$

Example: 12345678

Identificador SPB do participante (direto ou indireto) que faz a requisição.

Responses

Response samples

200
404

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<GetClaimResponse>
    <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>
        <ResolutionPeriodEnd>2020-01-17T10:00:00.000Z</ResolutionPeriodEnd>
        <CompletionPeriodEnd>2020-01-17T10:00:00.000Z</CompletionPeriodEnd>
        <LastModified>2020-01-10T10:00:00.000Z</LastModified>
    </Claim>
</GetClaimResponse>

Receber Reivindicação

Notifica recebimento pelo participante doador de reivindicação com status OPEN.

Idempotência

A operação é idempotente. Caso reivindicação já tenha sido recebida e ela esteja ainda com status WAITING_RESOLUTION, será retornada resposta equivalente à primeira requisição.

path Parameters

ClaimId

required

string <uuid>

Request Body schema: application/xml

Signature	object
ClaimId required	string <uuid>
Participant required	string^[0-9]{8}$ Identificador SPB do doador

Responses

Request samples

Payload

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<AcknowledgeClaimRequest>
    <Signature></Signature>
    <ClaimId>123e4567-e89b-12d3-a456-426655440000</ClaimId>
    <Participant>12345678</Participant>
</AcknowledgeClaimRequest>

Response samples

200
403
404
503

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<AcknowledgeClaimResponse>
    <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>WAITING_RESOLUTION</Status>
        <ResolutionPeriodEnd>2020-01-17T10:00:00.000Z</ResolutionPeriodEnd>
        <CompletionPeriodEnd>2020-01-17T10:00:00.000Z</CompletionPeriodEnd>
        <LastModified>2020-01-10T10:00:00.000Z</LastModified>
    </Claim>
</AcknowledgeClaimResponse>

Confirmar Reivindicação

Confirma a operação de reivindicação. Como consequência, vínculo da chave com participante doador é removido.

Status deve estar em WAITING_RESOLUTION.

Para reivindicação de posse, caso razão seja DEFAULT_OPERATION, o prazo de resolução (ResolutionPeriodEnd) deve ter passado. Se a razão informada for USER_REQUESTED, o prazo de encerramento (CompletionPeriodEnd) será adiantado para permitir o encerramento imediato pelo reivindicador.

A tabela abaixo define, a depender da razão e do tipo, quem pode confirmar.

	OWNERSHIP		PORTABILITY
Razão	Doador	Reivindicador	Doador	Reivindicador
USER_REQUESTED	✓		✓
ACCOUNT_CLOSURE			✓
DEFAULT_OPERATION	✓

Idempotência

A operação é idempotente. Caso reivindicação já tenha sido confirmada com os mesmos parâmetros e esteja ainda com status CONFIRMED, será retornada resposta equivalente à primeira requisição.

path Parameters

ClaimId

required

string <uuid>

Request Body schema: application/xml

Signature	object
ClaimId required	string <uuid>
Participant required	string^[0-9]{8}$ Identificador SPB do doador
Reason required	string (ClaimOperationReason) Enum: "USER_REQUESTED" "ACCOUNT_CLOSURE" "FRAUD" "DEFAULT_OPERATION" "RECONCILIATION" Razão da operação

Responses

Request samples

Payload

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<ConfirmClaimRequest>
    <Signature></Signature>
    <ClaimId>123e4567-e89b-12d3-a456-426655440000</ClaimId>
    <Participant>12345678</Participant>
    <Reason>USER_REQUESTED</Reason>
</ConfirmClaimRequest>

Response samples

200
403
404
503

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<ConfirmClaimResponse>
    <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>CONFIRMED</Status>
        <ResolutionPeriodEnd>2020-01-17T10:00:00.000Z</ResolutionPeriodEnd>
        <CompletionPeriodEnd>2020-01-17T10:00:00.000Z</CompletionPeriodEnd>
        <LastModified>2020-01-10T10:00:00.000Z</LastModified>
        <ConfirmReason>USER_REQUESTED</ConfirmReason>
    </Claim>
</ConfirmClaimResponse>

Cancelar Reivindicação

Cancela uma portabilidade ou reivindicação de posse.

Portabilidade

Status deve ser OPEN ou WAITING_RESOLUTION. Ver exceção abaixo

Se razão de cancelamento for DEFAULT_OPERATION, prazo definido pelo campo ResolutionPeriodEnd deve ter passado.

A tabela abaixo define, a depender da razão, quem pode cancelar uma portabilidade.

Razão	Doador	Reivindicador
USER_REQUESTED	✓	✓
ACCOUNT_CLOSURE		✓
DEFAULT_OPERATION	✓
FRAUD	✓	✓

Exceção : Caso razão seja FRAUD, reivindicador poderá adicionalmente cancelar portabilidade com status CONFIRMED.

Reivindicação de posse

Status deve ser OPEN, WAITING_RESOLUTION ou CONFIRMED.

Se razão de cancelamento for DEFAULT_OPERATION, prazo de validação de posse da chave do usuário reivindicador deve ter passado.

Reivindicador é quem pode cancelar uma reivindicação de posse. Ver exceção abaixo

Exceção : Caso razão seja FRAUD, doador poderá adicionalmente cancelar reivindicação de posse.

Idempotência

A operação é idempotente. Caso reivindicação já tenha sido cancelada com os mesmos parâmetros, será retornada resposta equivalente à primeira requisição.

path Parameters

ClaimId

required

string <uuid>

Request Body schema: application/xml

Signature	object
ClaimId required	string <uuid>
Participant required	string^[0-9]{8}$ Identificador SPB do doador ou reivindicador
Reason required	string (ClaimOperationReason) Enum: "USER_REQUESTED" "ACCOUNT_CLOSURE" "FRAUD" "DEFAULT_OPERATION" "RECONCILIATION" Razão da operação

Responses

Request samples

Payload

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<CancelClaimRequest>
    <Signature></Signature>
    <ClaimId>123e4567-e89b-12d3-a456-426655440000</ClaimId>
    <Participant>12345678</Participant>
    <Reason>USER_REQUESTED</Reason>
</CancelClaimRequest>

Response samples

200
403
404
503

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<CancelClaimResponse>
    <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>CANCELLED</Status>
        <ResolutionPeriodEnd>2020-01-17T10:00:00.000Z</ResolutionPeriodEnd>
        <CompletionPeriodEnd>2020-01-17T10:00:00.000Z</CompletionPeriodEnd>
        <LastModified>2020-01-10T10:00:00.000Z</LastModified>
        <CancelReason>FRAUD</CancelReason>
        <CancelledBy>CLAIMER</CancelledBy>
    </Claim>
</CancelClaimResponse>

Concluir Reivindicação

Conclui reivindicação pelo reivindicador. Como consequência, vínculo da chave com participante reivindicador é criado.

Para reivindicação de posse, status deve ser CONFIRMED e prazo definido pelo campo CompletionPeriodEnd deve ter passado.

Para portabilidade, status deve ser CONFIRMED.

Idempotência

A operação de conclusão de reivindicação é idempotente. Valem aqui as mesmas considerações feitas sobre esse tema na operação de Criar Vínculo.

path Parameters

ClaimId

required

string <uuid>

Request Body schema: application/xml

Signature	object
ClaimId required	string <uuid>
Participant required	string^[0-9]{8}$ Identificador SPB do reivindicador
RequestId required	string <uuid> (RequestId) Chave de idempotência da requisição. UUID versão 4.

Responses

Request samples

Payload

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<CompleteClaimRequest>
    <Signature></Signature>
    <ClaimId>123e4567-e89b-12d3-a456-426655440000</ClaimId>
    <Participant>12345678</Participant>
    <RequestId>a946d533-7f22-42a5-9a9b-e87cd55c0f4d</RequestId>
</CompleteClaimRequest>

Response samples

200
403
404
503

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<CompleteClaimResponse>
    <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>COMPLETED</Status>
        <ResolutionPeriodEnd>2020-01-17T10:00:00.000Z</ResolutionPeriodEnd>
        <CompletionPeriodEnd>2020-01-17T10:00:00.000Z</CompletionPeriodEnd>
        <LastModified>2020-01-10T10:00:00.000Z</LastModified>
        <ConfirmReason>DEFAULT_OPERATION</ConfirmReason>
    </Claim>
    <EntryCreationDate>2020-01-10T10:00:00.000Z</EntryCreationDate>
    <KeyOwnershipDate>2019-11-18T03:00:00.000Z</KeyOwnershipDate>
</CompleteClaimResponse>

Reconciliação

A reconciliação permite que o participante identifique inconsistências nos vínculos da sua base de dados interna e o DICT. É possível fazer a verificação de forma agregada, sobre todo o conjunto de vínculos, e a verificação de um vínculo individual.

Para permitir que a reconciliação seja feita de forma eficiente e segura, toda operação realizada em cima de um vínculo gera um identificador de conteúdo, ou CID (content identifier). O CID é um número de 256 bits que identifica de forma única o vínculo e todos os seus atributos essenciais (ver seção sobre cálculo do CID). Modifições dos dados essenciais do vínculo implicam na modificação do CID associado a ele.

A verificação agregada dos vínculos é feita com base no verificador de sincronismo (VSync). O participante pode aferir a igualdade do conjunto de vínculos em seu domínio gerando o VSync (ver seção sobre cálculo do VSync) da sua base e criando uma verificação de sincronismo. A igualdade dos VSyncs do DICT e do PSP implica, com altíssima probabilidade, que o conjunto de CIDs é igual. Caso os VSyncs sejam diferentes, o conjunto de CIDs é necessariamente diferente, o que significa que há divergências no conjunto de dados de vínculos naquele momento.

Ao identificar divergências, PSP poderá consultar pelo CID, alterar, remover ou criar vínculos colocando no campo Reason das requisições o valor RECONCILIATION.

As operações feitas no conjunto de vínculos sob domínio do PSP podem ser acompanhadas de forma contínua no log de eventos de CIDs.

Para obter uma lista completa dos CIDs no DICT relativos a um tipo de chave, um PSP poderá solicitar a criação de um arquivo de CIDs.

Cálculo de CID

O CID é calculado da seguinte forma:

entryAttributes = keyType "&" key "&" ownerTaxIdNumber "&" ownerName "&" ownerTradeName "&" participant "&" branch "&" accountNumber "&" accountType
cidBytes = hmacSha256(requestIdBytes, entryAttributes)
cid = lowercase-hexadecimal(cidBytes)

Observações:

entryAttributes é uma string construída pela junção dos atributos essenciais do vínculo, separados por &. Todos atributos são strings codificadas em UTF-8. Atributos nulos são codificados com string em branco, "".
hmacSha256 é a função HMAC baseada na função de hash SHA-256.
requestIdBytes são 16 bytes aleatórios, gerados para identificar a requisição que cria o vínculo, usado como chave na função hmacSha256.
cid é a representação hexadecimal, em lowercase, do resultado da função hmacSha256.

Exemplo:

entryAttributes = 'PHONE&+5511987654321&11122233300&João Silva&&12345678&00001&0007654321&CACC'
requestIdBytes = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]
cid = '28c06eb41c4dc9c3ae114831efcac7446c8747777fca8b145ecd31ff8480ae88'

Cálculo do VSync

O VSync é resultado da aplicação de bitwise-XOR ('OU' exclusivo bit-a-bit) sobre todos os CIDs de um determinado tipo de chave.

Exemplo:

cids = ['28c06eb41c4dc9c3ae114831efcac7446c8747777fca8b145ecd31ff8480ae88',
        '4d4abb9168114e349672b934d16ed201a919cb49e28b7f66a240e62c92ee007f',
        'fce514f84f37934bc8aa0f861e4f7392273d71b9d18e8209d21e4192a7842058']

vsync = xor(xor(cids[0], cids[1]), cids[2])  = '996fc1dd3b6b14bcf0c9fe8320eb66d7e2a3fd874ccf767b2e939641b1ea8eaf'

Observações:

VSync para um conjunto vazio de CIDs é definido como '0000000000000000000000000000000000000000000000000000000000000000'.
Há três CIDs no exemplo acima, representados em hexadecimal. A operação bitwise-XOR é feita com os CIDs em formato binário.
bitwise-XOR é comutativo, não importa a ordem da sua aplicação.
Para calcular o novo VSync resultante da adição de um CID ao conjunto, basta calcular o XOR desse CID com o VSync atual. O novo VSync resultante da remoção de um CID é calculado da mesma forma.

Verificar Sincronismo

Cria uma verificação de sincronismo para um partipante e tipo de chave.

Request Body schema: application/xml

Signature	object
required	object (SyncVerification)

Responses

Request samples

Payload

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<CreateSyncVerificationRequest>
    <Signature></Signature>
    <SyncVerification>
        <Participant>12345678</Participant>
        <KeyType>CPF</KeyType>
        <ParticipantSyncVerifier>e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855</ParticipantSyncVerifier>
    </SyncVerification>
</CreateSyncVerificationRequest>

Response samples

201
400
403
503

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<CreateSyncVerificationResponse>
    <Signature></Signature>
    <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime>
    <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId>
    <SyncVerification>
        <Participant>12345678</Participant>
        <KeyType>CPF</KeyType>
        <ParticipantSyncVerifier>e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855</ParticipantSyncVerifier>
        <Id>1234</Id>
        <Result>OK</Result>
    </SyncVerification>
</CreateSyncVerificationResponse>

Criar Arquivo de CIDs

Cria um arquivo contendo todos os CIDs de um determinado tipo de chave do participante. O formato do arquivo é um CID por linha ('\n' como EOL), sem ordem definida.

Geração do arquivo é feita assincronamente.

Request Body schema: application/xml

Signature	object
Participant required	string^[0-9]{8}$ Identificador SPB do participante custodiante das chaves.
KeyType required	string (KeyType) Enum: "CPF" "CNPJ" "PHONE" "EMAIL" "EVP" Tipo de chave. Novos tipos podem surgir.

Responses

Request samples

Payload

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<CreateCidSetFileRequest>
    <Signature></Signature>
    <Participant>12345678</Participant>
    <KeyType>PHONE</KeyType>
</CreateCidSetFileRequest>

Response samples

201
400
403
503

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<CreateCidSetFileResponse>
    <Signature></Signature>
    <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime>
    <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId>
    <CidSetFile>
        <Id>1234</Id>
        <Status>REQUESTED</Status>
        <Participant>12345678</Participant>
        <KeyType>PHONE</KeyType>
        <RequestTime>2020-01-10T10:00:00.000Z</RequestTime>
    </CidSetFile>
</CreateCidSetFileResponse>

Consultar Arquivo de CIDs

Obtém detalhes do arquivo de CIDs requisitado

path Parameters

Id

required

integer

header Parameters

PI-RequestingParticipant

required

string^[0-9]{8}$

Example: 12345678

Identificador SPB do participante (direto ou indireto) que faz a requisição.

Responses

Response samples

200
403
404

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<GetCidSetFileResponse>
    <Signature></Signature>
    <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime>
    <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId>
    <CidSetFile>
        <Id>1234</Id>
        <Status>AVAILABLE</Status>
        <Participant>12345678</Participant>
        <KeyType>PHONE</KeyType>
        <RequestTime>2020-01-10T10:00:00.000Z</RequestTime>
        <CreationTime>2020-01-10T10:00:10.000Z</CreationTime>
        <Url>https://some_download_url/apath/12345678/dict_file_name.cids</Url>
        <Bytes>3200000</Bytes>
        <Sha256>f0e4c2f76c58916ec258f246851bea091d14d4247a2fc3e18694461b1816e13b</Sha256>
    </CidSetFile>
</GetCidSetFileResponse>

Listar Eventos de CIDs

Lista os eventos de CIDs para um tipo de chave do participante, ordenados de forma crescente por Timestamp.

A tabela abaixo resume os eventos de CIDs gerados como conseqüência de cada operação.

Operação	Eventos de CID
Criar Vínculo	adiciona
Remover Vínculo	remove
Atualizar Vínculo	remove e adiciona
Confirmar Reivindicação	remove (PSP doador)
Concluir Reivindicação	adiciona (PSP reivindicador)

query Parameters

Participant required	string^[0-9]{8} ISPB do partipante direto ou indireto interessado
KeyType required	string (KeyType) Enum: "CPF" "CNPJ" "PHONE" "EMAIL" "EVP" Example: KeyType=CPF Tipo de chave
StartTime	string <date-time> Filtra eventos com data-hora maior ou igual a `StartTime`
EndTime	string <date-time> Filtra eventos com data-hora menor ou igual a `EndTime`
Limit	integer <= 200 Default: 100 Número limite de eventos a retornar

Responses

Response samples

200
400
403

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<ListCidSetEventsResponse>
    <Signature></Signature>
    <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime>
    <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId>
    <HasMoreElements>true</HasMoreElements>
    <Participant>12345678</Participant>
    <KeyType>CPF</KeyType>
    <StartTime>2020-01-10T10:00:00.000Z</StartTime>
    <EndTime>2020-01-10T11:00:00.000Z</EndTime>
    <SyncVerifierStart>ed02457b5c41d964dbd2f2a609d63fe1bb7528dbe55e1abf5b52c249cd735797</SyncVerifierStart>
    <SyncVerifierEnd>a592f5fb5bef95a3ec8431ebaf609e1af1e4c1b46edb0475394c5595988c748c</SyncVerifierEnd>
    <CidSetEvents>
        <CidSetEvent>
            <Type>ADDED</Type>
            <Cid>ca978112ca1bbdcafac231b39a23dc4da786eff8147c4e72b9807785afee48bb</Cid>
            <Timestamp>2020-01-10T10:00:00.000Z</Timestamp>
        </CidSetEvent>
        <CidSetEvent>
            <Type>REMOVED</Type>
            <Cid>961b6dd3ede3cb8ecbaacbd68de040cd78eb2ed5889130cceb4c49268ea4d506</Cid>
            <Timestamp>2020-01-10T11:11:11.000Z</Timestamp>
        </CidSetEvent>
    </CidSetEvents>
</ListCidSetEventsResponse>

Consultar Vínculo por CID

Obtém detalhes de um vínculo ativo identificado pelo CID

path Parameters

Cid

required

string (Cid) ^[0-9a-fA-F]{64}$

Identificador de conteúdo

header Parameters

PI-RequestingParticipant

required

string^[0-9]{8}$

Example: 12345678

Identificador SPB do participante (direto ou indireto) que faz a requisição.

Responses

Response samples

200
403
404

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<GetEntryByCidResponse>
    <Signature></Signature>
    <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime>
    <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId>
    <Cid>ca978112ca1bbdcafac231b39a23dc4da786eff8147c4e72b9807785afee48bb</Cid>
    <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>
    <RequestId>a946d533-7f22-42a5-9a9b-e87cd55c0f4d</RequestId>
</GetEntryByCidResponse>

Notificação de Infração

Uma notificação de infração deve ser criada quando existir fundada suspeita de fraude em uma transação liquidada no SPI.

A notificação de infração pode ser criada com objetivo de solicitar ou cancelar uma devolução. Quando o objetivo for solicitação de devolução (REFUND_REQUEST), quem deve criar a notificação é o PSP do pagador. Quando o objetivo for cancelamento de uma devolução (REFUND_CANCELLED), quem deve criar é o PSP do recebedor da transação original.

Uma notificação de infração pode estar em um dos seguintes estados:

OPEN - a notificação foi criada.
ACKNOWLEDGED - a notificação foi recebida pelo PSP contraparte.
CLOSED - a notificação foi analisada pelo PSP e o resultado está disponível.
CANCELLED - a notificação foi cancelada pelo PSP que a criou.

Após aberta (OPEN), a notificação de infração deve ser recebida (ACKNOWLEDGED) pelo PSP contraparte. Este fará uma análise e a fechará (CLOSED), concordando ou discordando com a notificação de infração.

O fechamento da notificação com concordância do PSP contraparte é pré-condição para que se possa criar uma solicitação de devolução. Adicionalmente, o fechamento da notificação com concordância criará uma marcação de fraude associada ao usuário infrator e à chave. Essa marcação de fraude pode ser cancelada pelo PSP contraparte.

A notificação de infração pode ser cancelada (CANCELLED) apenas pelo PSP que a abriu, a qualquer momento. O cancelamento da notificação de infração cancelará automaticamente a marcação de fraude associada, caso exista.

Notificações de infração são criadas a partir do identificador da transação realizada no SPI (EndToEndId). O prazo máximo para reportar infração em uma transação está no Manual Operacional do DICT.

Cada participante deve realizar polling periódico na lista de notificações para verificar se existem novas notificações em que é parte. O recebimento da notificação não implica em concordância. Os níveis de serviço exigidos para as operações com notificações de infração estão definidos no Manual de Tempos do Pix.

🛈 Nota

As notificações de infração do tipo FRAUD criadas na api v1 não estão mais acessíveis na api v2 nos endpoints de notificação de infração. Caso essas notificações sejam acessadas na api v2, será retornado erro Gone com status 410. Durante o período de convivência da api v1 e v2, essas notificações deverão ser fechadas ou canceladas via api v1. Na api v2, essas notificações podem ser consultadas ou canceladas como marcações de fraude. Para isso, basta utilizar o id da notificação de infração.

Criar Notificação de Infração

Cria uma notificação de infração.

Quando o objetivo da notificação de infração for solicitação de devolução, quem deve criar a notificação é o PSP do pagador da transação original. Para o cancelamento de devolução, quem deve criar é o PSP do recebedor da transação original.

Request Body schema: application/xml

Signature	object
Participant required	string^[0-9]{8}$ Identificador SPB do participante criador da notificação de infração
required	object (InfractionReport) Notificação de infração para uma transação liquidada no SPI.

Responses

Request samples

Payload

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<CreateInfractionReportRequest>
    <Signature></Signature>
    <Participant>99999010</Participant>
    <InfractionReport>
        <TransactionId>E9999901012341234123412345678900</TransactionId>
        <Reason>REFUND_REQUEST</Reason>
        <SituationType>SCAM</SituationType>
        <ReportDetails>Transação feita através de QR Code falso em boleto</ReportDetails>
    </InfractionReport>
</CreateInfractionReportRequest>

Response samples

201
400
403
503

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<CreateInfractionReportResponse>
    <Signature></Signature>
    <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime>
    <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId>
    <InfractionReport>
        <TransactionId>E9999901012341234123412345678900</TransactionId>
        <Reason>REFUND_REQUEST</Reason>
        <SituationType>SCAM</SituationType>
        <ReportDetails>Transação feita através de QR Code falso em boleto</ReportDetails>
        <Id>91d65e98-97c0-4b0f-b577-73625da1f9fc</Id>
        <Status>OPEN</Status>
        <ReporterParticipant>99999010</ReporterParticipant>
        <CounterpartyParticipant>99999011</CounterpartyParticipant>
        <CreationTime>2020-01-17T10:00:00.000Z</CreationTime>
        <LastModified>2020-01-17T10:00:00.000Z</LastModified>
    </InfractionReport>
</CreateInfractionReportResponse>

Listar Notificações de Infração

Obtém lista de notificações de infração em que o participante é parte.

Lista de notificações é ordenada de forma crescente pelo campo LastModified.

query Parameters

Participant required	string^[0-9]{8}$ ISPB do partipante direto ou indireto interessado
IncludeIndirectParticipants	boolean Default: false Inclui adicionalmente as notificações de infração de participantes indiretos
IsReporter	boolean Restringe a notificações em que o participante é o criador
IsCounterparty	boolean Restringe a notificações em que o participante é contraparte
Status	Array of strings (InfractionReportStatus) Items Enum: "OPEN" "ACKNOWLEDGED" "CLOSED" "CANCELLED" Lista de Status a serem pesquisados
IncludeDetails	boolean Default: false Inclui os detalhes da notificação (campos Details)
ModifiedAfter	string <date-time> Filtra notificações com data-hora de modificação maior ou igual a `modifiedAfter`
ModifiedBefore	string <date-time> Filtra notificações com data-hora de modificação menor ou igual a `modifiedBefore`
Limit	integer <= 200 Default: 20 Número limite de notificações a retornar

Responses

Response samples

200
400
403

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<ListInfractionReportsResponse>
    <Signature></Signature>
    <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime>
    <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId>
    <HasMoreElements>true</HasMoreElements>
    <InfractionReports>
        <InfractionReport>
            <TransactionId>E9999901012341234123412345678900</TransactionId>
            <Reason>REFUND_REQUEST</Reason>
            <SituationType>SCAM</SituationType>
            <ReportDetails>Transação feita através de QR Code falso em boleto</ReportDetails>
            <Id>91d65e98-97c0-4b0f-b577-73625da1f9fc</Id>
            <Status>CLOSED</Status>
            <ReporterParticipant>99999010</ReporterParticipant>
            <CounterpartyParticipant>99999011</CounterpartyParticipant>
            <FraudMarkerId>91d65e98-97c0-4b0f-b577-73625da1f9fc</FraudMarkerId>
            <AnalysisResult>AGREED</AnalysisResult>
            <AnalysisDetails>
                Valor bloqueado. Para mais informações, contactar central antifraude em 
                11 3000-00000, informando ID 9999.
            </AnalysisDetails>
            <CreationTime>2020-01-17T10:00:00.000Z</CreationTime>
            <LastModified>2020-01-17T10:00:00.000Z</LastModified>
        </InfractionReport>
    </InfractionReports>
</ListInfractionReportsResponse>

Consultar Notificação de Infração

Obtém detalhes de uma notificação de infração.

path Parameters

InfractionReportId

required

string <uuid>

header Parameters

PI-RequestingParticipant

required

string^[0-9]{8}$

Example: 12345678

Identificador SPB do participante (direto ou indireto) que faz a requisição.

Responses

Response samples

200
404

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<GetInfractionReportResponse>
    <Signature></Signature>
    <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime>
    <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId>
    <InfractionReport>
        <TransactionId>E9999901012341234123412345678900</TransactionId>
        <Reason>REFUND_REQUEST</Reason>
        <SituationType>SCAM</SituationType>
        <ReportDetails>Transação feita através de QR Code falso em boleto</ReportDetails>
        <Id>91d65e98-97c0-4b0f-b577-73625da1f9fc</Id>
        <Status>ACKNOWLEDGED</Status>
        <ReporterParticipant>99999010</ReporterParticipant>
        <CounterpartyParticipant>99999011</CounterpartyParticipant>
        <CreationTime>2020-01-17T10:00:00.000Z</CreationTime>
        <LastModified>2020-01-17T10:00:00.000Z</LastModified>
    </InfractionReport>
</GetInfractionReportResponse>

Receber Notificação de Infração

Notifica recebimento da notificação pelo participante contraparte.

Idempotência

A operação é idempotente. Caso a notificação já tenha sido recebida e esteja ainda com status ACKNOWLEDGED, será retornada resposta equivalente à primeira requisição.

path Parameters

InfractionReportId

required

string <uuid>

Request Body schema: application/xml

Signature	object
InfractionReportId required	string <uuid> ID da notificação de infração
Participant required	string^[0-9]{8}$ Identificador SPB do participante realizando o ACK

Responses

Request samples

Payload

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<AcknowledgeInfractionReportRequest>
    <Signature></Signature>
    <InfractionReportId>91d65e98-97c0-4b0f-b577-73625da1f9fc</InfractionReportId>
    <Participant>12345678</Participant>
</AcknowledgeInfractionReportRequest>

Response samples

200
403
404
503

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<AcknowledgeInfractionReportResponse>
    <Signature></Signature>
    <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime>
    <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId>
    <InfractionReport>
        <TransactionId>E9999901012341234123412345678900</TransactionId>
        <Reason>REFUND_REQUEST</Reason>
        <SituationType>SCAM</SituationType>
        <ReportDetails>Transação feita através de QR Code falso em boleto</ReportDetails>
        <Id>91d65e98-97c0-4b0f-b577-73625da1f9fc</Id>
        <Status>CLOSED</Status>
        <ReporterParticipant>99999010</ReporterParticipant>
        <CounterpartyParticipant>99999011</CounterpartyParticipant>
        <CreationTime>2020-01-17T10:00:00.000Z</CreationTime>
        <LastModified>2020-01-17T10:00:00.000Z</LastModified>
    </InfractionReport>
</AcknowledgeInfractionReportResponse>

Cancelar Notificação de Infração

Cancela a notificação de infração. Só pode ser realizada pelo participante que criou a notificação.

O cancelamento de uma notificação de infração fechada com concordância cancelará também a marcação de fraude associada.

Idempotência

A operação é idempotente. Caso a notificação já tenha sido cancelada com os mesmos parâmetros, será retornada resposta equivalente à primeira requisição.

path Parameters

InfractionReportId

required

string <uuid>

Request Body schema: application/xml

Signature	object
InfractionReportId required	string <uuid> ID da notificação de infração
Participant required	string^[0-9]{8}$ Identificador SPB do participante que criou a notificação de infração

Responses

Request samples

Payload

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<CancelInfractionReportRequest>
    <Signature></Signature>
    <InfractionReportId>91d65e98-97c0-4b0f-b577-73625da1f9fc</InfractionReportId>
    <Participant>12345678</Participant>
</CancelInfractionReportRequest>

Response samples

200
403
404
503

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<CancelInfractionReportResponse>
    <Signature></Signature>
    <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime>
    <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId>
    <InfractionReport>
        <TransactionId>E9999901012341234123412345678900</TransactionId>
        <Reason>REFUND_REQUEST</Reason>
        <SituationType>SCAM</SituationType>
        <ReportDetails>Transação feita através de QR Code falso em boleto</ReportDetails>
        <Id>91d65e98-97c0-4b0f-b577-73625da1f9fc</Id>
        <Status>CANCELLED</Status>
        <ReporterParticipant>99999010</ReporterParticipant>
        <CounterpartyParticipant>99999011</CounterpartyParticipant>
        <CreationTime>2020-01-17T10:00:00.000Z</CreationTime>
        <LastModified>2020-01-17T10:00:00.000Z</LastModified>
    </InfractionReport>
</CancelInfractionReportResponse>

Fechar Notificação de Infração

Fecha a notificação de infração.

A notificação deve ser fechada pelo participante contraparte. Para fechamento, o status deve ser ACKNOWLEDGED.

Caso o fechamento seja com o resultado de análise AGREED, será gerada automaticamente uma marcação de fraude. O id da marcação constará no campo FraudMarkerId da resposta. Nestes casos, o participante deve obrigatoriamente informar o campo 'FraudType'. Os valores válidos são APPLICATION_FRAUD, MULE_ACCOUNT, SCAMMER_ACCOUNT e OTHER.

ATENÇÃO: o tipo UNKNOWN não é válido para a API v2. Ele é usado apenas como valor descritivo nas notificações de infração criadas ainda na API v1, quando o tipo de fraude não fazia parte dos dados na notificação.

A marcação de fraude gerada pode ser cancelada pelo participante contraparte, responsável pelo fechamento da notificação de infração.

Idempotência

A operação é idempotente. Caso a notificação já tenha sido fechado com os mesmos parâmetros, será retornada resposta equivalente à primeira requisição.

path Parameters

InfractionReportId

required

string <uuid>

Request Body schema: application/xml

Signature	object
InfractionReportId required	string <uuid> ID da notificação de infração
Participant required	string^[0-9]{8}$ Identificador SPB do participante.
FraudType	string Enum: "APPLICATION_FRAUD" "MULE_ACCOUNT" "SCAMMER_ACCOUNT" "OTHER" "UNKNOWN" Tipo de fraude verificada. Obrigatório caso AnalysisResult = AGREED
AnalysisResult required	string (AnalysisResult) Enum: "AGREED" "DISAGREED" Resultado da análise da infração.
AnalysisDetails	string (AnalysisDetails) <= 2000 characters Detalhes da análise da notificação de infração.

Responses

Request samples

Payload

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<CloseInfractionReportRequest>
    <Signature></Signature>
    <InfractionReportId>91d65e98-97c0-4b0f-b577-73625da1f9fc</InfractionReportId>
    <Participant>12345678</Participant>
    <FraudType>SCAMMER_ACCOUNT</FraudType>
    <AnalysisResult>AGREED</AnalysisResult>
    <AnalysisDetails>
        Valor bloqueado. Para mais informações, contactar central antifraude em 
        11 3000-00000, informando ID 9999.
    </AnalysisDetails>
</CloseInfractionReportRequest>

Response samples

200
403
404
503

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<CloseInfractionReportResponse>
    <Signature></Signature>
    <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime>
    <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId>
    <InfractionReport>
        <TransactionId>E9999901012341234123412345678900</TransactionId>
        <Reason>REFUND_REQUEST</Reason>
        <SituationType>SCAM</SituationType>
        <ReportDetails>Transação feita através de QR Code falso em boleto</ReportDetails>
        <Id>91d65e98-97c0-4b0f-b577-73625da1f9fc</Id>
        <Status>CLOSED</Status>
        <ReporterParticipant>99999010</ReporterParticipant>
        <CounterpartyParticipant>99999011</CounterpartyParticipant>
        <FraudMarkerId>91d65e98-97c0-4b0f-b577-73625da1f9fc</FraudMarkerId>
        <CreationTime>2020-01-17T10:00:00.000Z</CreationTime>
        <LastModified>2020-01-17T10:00:00.000Z</LastModified>
        <AnalysisResult>AGREED</AnalysisResult>
        <AnalysisDetails>
            Valor bloqueado. Para mais informações, contactar central antifraude em 
            11 3000-00000, informando ID 9999.
        </AnalysisDetails>
    </InfractionReport>
</CloseInfractionReportResponse>

Devolução

A solicitação de devolução pode ser criada pelo PSP do usuário pagador nos casos em que exista fundada suspeita de fraude e naqueles em que se verifique falha operacional no sistema de quaisquer dos participantes envolvidos na transação.

Uma solicitação de devolução pode ter os seguintes estados:

OPEN - a solicitação foi criada pelo PSP do usuário pagador
CLOSED - a solicitação foi analisada pelo PSP do usuário recebedor
CANCELLED - a solicitação foi cancelada pelo PSP do pagador

Criar Solicitação de Devolução

Cria uma solicitação de devolução.

Apenas o participante debitado pode criar uma solicitação de devolução.

Request Body schema: application/xml

Signature	object
Participant required	string^[0-9]{8}$ Identificador SPB do participante que está solicitando a devolução.
required	object (Refund) Solicitação de devolução de uma transação.

Responses

Request samples

Payload

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<CreateRefundRequest>
    <Signature></Signature>
    <Participant>99999010</Participant>
    <Refund>
        <TransactionId>E9999901012341234123412345678900</TransactionId>
        <RefundReason>FRAUD</RefundReason>
        <RefundAmount>100.00</RefundAmount>
        <RefundDetails>Houve fraude confirmada na transação.</RefundDetails>
    </Refund>
</CreateRefundRequest>

Response samples

201
400
403
503

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<CreateRefundResponse>
    <Signature></Signature>
    <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime>
    <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId>
    <Refund>
        <TransactionId>E9999901012341234123412345678900</TransactionId>
        <RefundReason>FRAUD</RefundReason>
        <RefundAmount>200.00</RefundAmount>
        <RefundDetails>Transação feita através de QR Code falso em boleto</RefundDetails>
        <Id>91d65e98-97c0-4b0f-b577-73625da1f9fc</Id>
        <Status>OPEN</Status>
        <ContestedParticipant>99999010</ContestedParticipant>
        <RequestingParticipant>99999011</RequestingParticipant>
        <CreationTime>2020-01-17T10:00:00.000Z</CreationTime>
        <LastModified>2020-01-17T10:00:00.000Z</LastModified>
    </Refund>
</CreateRefundResponse>

Listar Solicitações de Devolução

Obtém lista de solicitações de devolução em que o participante é parte.

Lista é ordenada de forma crescente pelo campo LastModified.

query Parameters

Participant required	string^[0-9]{8}$ ISPB do partipante direto ou indireto responsável
IncludeIndirectParticipants	boolean Default: false Inclui adicionalmente as devoluções de participantes indiretos
ParticipantRole required	string (RefundRequestRole) Enum: "REQUESTING" "CONTESTED" Papel do participante na devolução
Status	Array of strings (RefundStatus) Items Enum: "OPEN" "CLOSED" "CANCELLED" Lista de Status a serem pesquisados
IncludeDetails	boolean Default: false Inclui os detalhes da devolução (campos Details)
ModifiedAfter	string <date-time> Filtra devoluções com data-hora de modificação maior ou igual a `modifiedAfter`
ModifiedBefore	string <date-time> Filtra devoluções com data-hora de modificação menor ou igual a `modifiedBefore`
Limit	integer <= 200 Default: 20 Número limite de devoluções a retornar

Responses

Response samples

200
400
403

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<ListRefundsResponse>
    <Signature></Signature>
    <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime>
    <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId>
    <HasMoreElements>true</HasMoreElements>
    <Refunds>
        <Refund>
            <TransactionId>E9999901012341234123412345678900</TransactionId>
            <RefundReason>FRAUD</RefundReason>
            <RefundAmount>200.00</RefundAmount>
            <RefundDetails>Transação feita através de QR Code falso em boleto</RefundDetails>
            <Id>91d65e98-97c0-4b0f-b577-73625da1f9fc</Id>
            <Status>CLOSED</Status>
            <ContestedParticipant>99999010</ContestedParticipant>
            <RequestingParticipant>99999011</RequestingParticipant>
            <CreationTime>2020-01-17T10:00:00.000Z</CreationTime>
            <LastModified>2020-01-17T10:00:00.000Z</LastModified>
            <AnalysisResult>TOTALLY_ACCEPTED</AnalysisResult>
            <AnalysisDetails>
                Valor totalmente extornado.
            </AnalysisDetails>
            <RefundTransactionId>D9999901012341234123412345678900</RefundTransactionId>
        </Refund>
    </Refunds>
</ListRefundsResponse>

Consultar Solicitação de Devolução

Obtém detalhes de uma solicitação de devolução.

path Parameters

RefundId

required

string <uuid>

header Parameters

PI-RequestingParticipant

required

string^[0-9]{8}$

Example: 12345678

Identificador SPB do participante (direto ou indireto) que faz a requisição.

Responses

Response samples

200
404

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<GetRefundResponse>
    <Signature></Signature>
    <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime>
    <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId>
    <Refund>
        <TransactionId>E9999901012341234123412345678900</TransactionId>
        <RefundReason>FRAUD</RefundReason>
        <RefundAmount>200.00</RefundAmount>
        <RefundDetails>Transação feita através de QR Code falso em boleto</RefundDetails>
        <Id>91d65e98-97c0-4b0f-b577-73625da1f9fc</Id>
        <Status>OPEN</Status>
        <ContestedParticipant>99999010</ContestedParticipant>
        <RequestingParticipant>99999011</RequestingParticipant>
        <CreationTime>2020-01-17T10:00:00.000Z</CreationTime>
        <LastModified>2020-01-17T10:00:00.000Z</LastModified>
    </Refund>
</GetRefundResponse>

Cancelar Solicitação de Devolução

Cancela a Solicitação de devolução.

Só pode ser realizada pelo participante que criou a solicitação.

Idempotência

A operação é idempotente. Caso a solicitação já tenha sido cancelada com os mesmos parâmetros, será retornada resposta equivalente à primeira requisição.

path Parameters

RefundId

required

string <uuid>

Request Body schema: application/xml

Signature	object
RefundId required	string <uuid> ID da solicitação de devolução
Participant required	string^[0-9]{8}$ Identificador SPB do participante que abriu a solicitação

Responses

Request samples

Payload

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<CancelRefundRequest>
    <Signature></Signature>
    <RefundId>91d65e98-97c0-4b0f-b577-73625da1f9fc</RefundId>
    <Participant>12345678</Participant>
</CancelRefundRequest>

Response samples

200
403
404
503

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<CancelRefundResponse>
    <Signature></Signature>
    <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime>
    <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId>
    <Refund>
        <TransactionId>E9999901012341234123412345678900</TransactionId>
        <RefundReason>FRAUD</RefundReason>
        <RefundAmount>200.00</RefundAmount>
        <RefundDetails>Transação feita através de QR Code falso em boleto</RefundDetails>
        <Id>91d65e98-97c0-4b0f-b577-73625da1f9fc</Id>
        <Status>CANCELLED</Status>
        <ContestedParticipant>99999010</ContestedParticipant>
        <RequestingParticipant>99999011</RequestingParticipant>
        <CreationTime>2020-01-17T10:00:00.000Z</CreationTime>
        <LastModified>2020-01-17T10:00:00.000Z</LastModified>
    </Refund>
</CancelRefundResponse>

Fechar Solicitação de Devolução

Fecha a solicitação de devolução.

A solicitação só pode ser fechada pelo participante contestado.

Para fechamento, o status deve ser OPEN.

Idempotência

A operação é idempotente. Caso a solicitação já tenha sido fechada com os mesmos parâmetros, será retornada resposta equivalente à primeira requisição.

path Parameters

RefundId

required

string <uuid>

Request Body schema: application/xml

Signature	object
RefundId required	string <uuid> ID da solicitação de devolução
Participant required	string^[0-9]{8}$ Identificador SPB do participante contestado
RefundAnalysisResult required	string (RefundAnalysisResult) Enum: "TOTALLY_ACCEPTED" "PARTIALLY_ACCEPTED" "REJECTED" Resultado da análise da requisição de devolução pelo constestado.
RefundAnalysisDetails	string (RefundAnalysisDetails) <= 2000 characters Detalhes da análise da requisição de devolução indicando a motivação do resultado.
RefundRejectionReason	string (RefundRejectionReason) Enum: "NO_BALANCE" "ACCOUNT_CLOSURE" "OTHER" Razão da rejeição da solicitação de devolução.
RefundTransactionId	string\w{32} Transação de devolução (completa ou parcial)

Responses

Request samples

Payload

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<CloseRefundRequest>
    <Signature></Signature>
    <RefundId>91d65e98-97c0-4b0f-b577-73625da1f9fc</RefundId>
    <Participant>12345678</Participant>
    <RefundAnalysisResult>TOTALLY_ACCEPTED</RefundAnalysisResult>
    <RefundAnalysisDetails>
        Valor totalmente extornado ao demandante.
    </RefundAnalysisDetails>
    <RefundTransactionId>D9999901012341234123412345678900</RefundTransactionId>
</CloseRefundRequest>

Response samples

200
403
404
503

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<CloseRefundResponse>
    <Signature></Signature>
    <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime>
    <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId>
    <Refund>
        <TransactionId>E9999901012341234123412345678900</TransactionId>
        <RefundReason>FRAUD</RefundReason>
        <RefundAmount>200.00</RefundAmount>
        <RefundDetails>Transação feita através de QR Code falso em boleto</RefundDetails>
        <Id>91d65e98-97c0-4b0f-b577-73625da1f9fc</Id>
        <Status>CLOSED</Status>
        <ContestedParticipant>99999010</ContestedParticipant>
        <RequestingParticipant>99999011</RequestingParticipant>
        <CreationTime>2020-01-17T10:00:00.000Z</CreationTime>
        <LastModified>2020-01-17T10:00:00.000Z</LastModified>
        <AnalysisResult>TOTALLY_ACCEPTED</AnalysisResult>
        <AnalysisDetails>
            Valor totalmente extornado ao demandante.
        </AnalysisDetails>
    </Refund>
</CloseRefundResponse>

Antifraude

Marcação de Fraude

A marcação de fraude deve ser criada pelo PSP quando há fundada suspeita de cometimento de fraude por um usuário seu em transações Pix liquidadas fora do SPI ou que tenham sido rejeitadas no SPI ou fora do SPI.

Quando a intenção for marcar um usuário de outro PSP e recuperar os recursos liquidados no SPI, deve ser criada uma notificação de infração. O fechamento da notificação com concordância da contraparte gera automaticamente uma marcação de fraude.

As marcações de fraude sensibilizam contadores que compõem as informações para fins de segurança do Pix.

O criador da marcação de fraude pode cancelá-la a qualquer momento após sua criação. O cancelamento da marcação de fraude sensibiliza os contadores associados ao usuário, diminuindo-os.

Todas as marcações de fraude criadas são contabilizadas e retornadas ao consultar estatísticas.

Estatísticas

O DICT fornece dados estatísticos que podem ser usados pelos participantes em seus processos antifraude.

É possível consultar os dados de chaves registradas e de usuários.

Os contadores agregados em janelas consideram três períodos:

d90 : últimos 89 dias, incluindo o dia corrente
m12 : últimos 12 meses, sem incluir o mês corrente
m60 : últimos 60 meses, sem incluir o mês corrente

Exemplo

No dia 17/11/2023 às 17:00:00Z, as janelas são definidas pelos seguintes intervalos:

d90 : 20/08/2023 03:00:00Z → 17/11/2023 17:00:00Z
m12 : 01/11/2022 03:00:00Z → 01/11/2023 03:00:00Z
m60 : 01/11/2018 03:00:00Z → 01/11/2023 03:00:00Z

🛈 Nota

As janelas dos contadores de liquidação possuem uma data de corte de início. Apenas eventos após a data de ativação da API v2 (05/11/2023 03:00:00Z) são considerados.

Criar Marcação de Fraude

Cria uma marcação de fraude.

Idempotência

A operação de criação de marcação de fraude é idempotente. Para garantir a idempotência da operação, a requisição tem um campo RequestId, que deve ser único no contexto de um mesmo participante.

Request Body schema: application/xml

Signature	object
Participant required	string^[0-9]{8}$ Identificador SPB do participante criador da marcação de fraude
required	object (FraudMarker) Marcação de fraude transacional.
RequestId required	string <uuid> (RequestId) Chave de idempotência da requisição. UUID versão 4.

Responses

Request samples

Payload

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<CreateFraudMarkerRequest>
    <Signature></Signature>
    <Participant>99999010</Participant>
    <FraudMarker>
        <TaxIdNumber>01234567890</TaxIdNumber>
        <FraudType>MULE_ACCOUNT</FraudType>
        <Key>abc@pix.br</Key>
    </FraudMarker>
    <RequestId>a946d533-7f22-42a5-9a9b-e87cd55c0f4d</RequestId>
</CreateFraudMarkerRequest>

Response samples

201
400
403
503

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<CreateFraudMarkerResponse>
    <Signature></Signature>
    <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime>
    <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId>
    <FraudMarker>
        <Id>91d65e98-97c0-4b0f-b577-73625da1f9fc</Id>
        <Status>REGISTERED</Status>
        <TaxIdNumber>01234567890</TaxIdNumber>
        <FraudType>MULE_ACCOUNT</FraudType>
        <Key>abc@pix.br</Key>
        <CreationTime>2020-01-17T10:00:00.000Z</CreationTime>
        <LastModified>2020-01-17T10:00:00.000Z</LastModified>
    </FraudMarker>
</CreateFraudMarkerResponse>

Consultar Marcação de Fraude

Obtém detalhes de uma marcação de fraude.

path Parameters

FraudMarkerId

required

string <uuid>

header Parameters

PI-RequestingParticipant

required

string^[0-9]{8}$

Example: 12345678

Identificador SPB do participante (direto ou indireto) que faz a requisição.

Responses

Response samples

200
404

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<GetFraudMarkerResponse>
    <Signature></Signature>
    <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime>
    <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId>
    <FraudMarker>
        <Id>91d65e98-97c0-4b0f-b577-73625da1f9fc</Id>
        <Status>REGISTERED</Status>
        <TaxIdNumber>01234567890</TaxIdNumber>
        <FraudType>MULE_ACCOUNT</FraudType>
        <Key>abc@pix.br</Key>
        <CreationTime>2020-01-17T10:00:00.000Z</CreationTime>
        <LastModified>2020-01-17T10:00:00.000Z</LastModified>
    </FraudMarker>
</GetFraudMarkerResponse>

Cancelar Marcação de Fraude

Cancela uma marcação de fraude.

Pode ser realizada pelo participante que criou a marcação de fraude.

Uma marcação de fraude criada como consequência do fechamento de uma notificação de infração pode ser cancelada pelo participante contraparte, que fez o fechamento da notificação.

Idempotência

A operação é idempotente. Caso o registro já tenha sido cancelado com os mesmos parâmetros, será retornada resposta equivalente à primeira requisição.

path Parameters

FraudMarkerId

required

string <uuid>

Request Body schema: application/xml

Signature	object
FraudMarkerId required	string <uuid> ID da notificação de infração
Participant required	string^[0-9]{8}$ Identificador SPB do participante que solicita cancelamento

Responses

Request samples

Payload

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<CancelFraudMarkerRequest>
    <Signature></Signature>
    <FraudMarkerId>91d65e98-97c0-4b0f-b577-73625da1f9fc</FraudMarkerId>
    <Participant>12345678</Participant>
</CancelFraudMarkerRequest>

Response samples

200
403
404
503

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<CancelFraudMarkerResponse>
    <Signature></Signature>
    <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime>
    <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId>
    <FraudMarker>
        <Id>91d65e98-97c0-4b0f-b577-73625da1f9fc</Id>
        <Status>CANCELLED</Status>
        <TaxIdNumber>01234567890</TaxIdNumber>
        <FraudType>MULE_ACCOUNT</FraudType>
        <Key>abc@pix.br</Key>
        <CreationTime>2020-01-17T10:00:00.000Z</CreationTime>
        <LastModified>2023-01-17T10:00:00.000Z</LastModified>
    </FraudMarker>
</CancelFraudMarkerResponse>

Consultar Estatísticas de Pessoa

Obtém dados estatísticos de um usuário final

path Parameters

TaxIdNumber

required

string^[0-9]{11,14}$

Example: 12345678901

header Parameters

PI-RequestingParticipant

required

string^[0-9]{8}$

Example: 12345678

Identificador SPB do participante (direto ou indireto) que faz a requisição.

Responses

Response samples

200
403
503

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<GetPersonStatisticsResponse>
    <Signature></Signature>
    <ResponseTime>2023-01-01T10:00:00.000Z</ResponseTime>
    <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId>
    <TaxIdNumber>12345678901</TaxIdNumber>
    <PersonStatistics>
        <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>
    </PersonStatistics>
</GetPersonStatisticsResponse>

Consultar Estatísticas de Chave Registrada

Obtém dados estatísticos relacionados a uma chave registrada

path Parameters

Key

required

string (Key) <= 77 characters

Example: 12345678901

header Parameters

PI-RequestingParticipant

required

string^[0-9]{8}$

Example: 12345678

Identificador SPB do participante (direto ou indireto) que faz a requisição.

Responses

Response samples

200
403
503

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<GetEntryStatisticsResponse>
    <Signature></Signature>
    <ResponseTime>2023-01-01T10:00:00.000Z</ResponseTime>
    <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId>
    <Key>11122233300</Key>
    <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>
</GetEntryStatisticsResponse>

Política de Limitação

O controle do fluxo de acesso aos serviços do DICT é realizado por meio de políticas de limitação de requisições, utilizando o algoritmo de token bucket. Para cada política de limitação, existe um balde com configurações específicas, de acordo com a seção limitação de requisições.

É possível, a qualquer momento, consultar da lista de políticas de limitação e o estado dos baldes.

Listar Políticas

Obtém a lista de políticas de limitação de acesso ao DICT para o participante requisitante.

Além da lista de políticas, o serviço informa também a categoria em que o participante se encontra, de acordo com a tabela presente no item ENTRIES_READ_PARTICIPANT_ANTISCAN da seção limitação de requisições.

Cada item da lista detém informações do estado do balde correspondente no momento da consulta.

header Parameters

PI-RequestingParticipant

required

string^[0-9]{8}$

Example: 12345678

Identificador SPB do participante (direto ou indireto) que faz a requisição.

Responses

Response samples

200
403
503

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<ListPoliciesResponse>
    <Signature></Signature>
    <CorrelationId>B20220902101925801123456781A6998</CorrelationId>
    <ResponseTime>2022-09-02T13:19:25.833Z</ResponseTime>
    <Category>A</Category>
    <Policies>
        <Policy>
            <AvailableTokens>0</AvailableTokens>
            <Capacity>0</Capacity>
            <RefillTokens>0</RefillTokens>
            <RefillPeriodSec>0</RefillPeriodSec>
            <Name>ENTRIES_READ_PARTICIPANT_ANTISCAN</Name>
        </Policy>
    </Policies>
</ListPoliciesResponse>

Consultar Política

Obtém o estado atual do balde do participante para a política informada.

path Parameters

Policy

required

string

Example: ENTRIES_READ_PARTICIPANT_ANTISCAN

header Parameters

PI-RequestingParticipant

required

string^[0-9]{8}$

Example: 12345678

Identificador SPB do participante (direto ou indireto) que faz a requisição.

Responses

Response samples

200
403
503

Content type

application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<GetPolicyResponse>
    <Signature></Signature>
    <CorrelationId>B20220902102129115123456788B2B22</CorrelationId>
    <ResponseTime>2022-09-02T13:21:29.110Z</ResponseTime>
    <Category>A</Category>
    <Policy>
        <AvailableTokens>0</AvailableTokens>
        <Capacity>0</Capacity>
        <RefillTokens>0</RefillTokens>
        <RefillPeriodSec>0</RefillPeriodSec>
        <Name>ENTRIES_READ_PARTICIPANT_ANTISCAN</Name>
    </Policy>
</GetPolicyResponse>