API docs by Redocly

DICT API (2.4.1)

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.

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

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

  • 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.
TaxIdNumberBlocked 400 O CPF/CNPJ encontra-se bloqueado por ordem judicial.
Vínculo
EntryInvalid 400 Existem campos inválidos ao tentar criar ou atualizar vínculo
EntryLimitExceeded 400 Número de vínculos associados a conta transacional excedeu o limite máximo
EntryAlreadyExists 400 Já existe vínculo para essa chave com o mesmo participante e dono
EntryCannotBeQueriedForBookTransfer 400 Vínculo consultado está custodiado no mesmo PSP do usuário pagador para quem está sendo feita a consulta. Quando o pagador e o recebedor estão no mesmo PSP, não deve ser feita consulta ao DICT.
EntryKeyOwnedByDifferentPerson 400 Já existe vínculo para essa chave mas ela é possuída por outra pessoa.
Indica-se que seja feita uma reivindicação de posse.
EntryKeyInCustodyOfDifferentParticipant 400 Já existe vínculo para essa chave com o mesmo dono, mas ela encontra-se associada a outro participante. Indica-se que seja feita uma reivindicação de portabilidade.
EntryLockedByClaim 400 Existe uma reivindicação com status diferente de concluída ou cancelada para a chave do vínculo. Enquanto estiver nessa situação, o vínculo não pode ser excluído.
EntryTaxIdNumberByDifferentOwner 400 CPF/CNPJ do vínculo diferente do CPF/CNPJ do dono da chave
EntryBlocked 400 O vínculo encontra-se bloqueado por ordem judicial e não pode ser consultado
Reivindicação
ClaimInvalid 400 Existem campos inválidos ao tentar criar ou atualizar reivindicação
ClaimTypeInconsistent 400 Tipo de reivindicação pedida é inconsistente. Esse erro ocorre nas situações em que se tenta criar a) reivindicação de posse, mas vínculo existente tem como dona a mesma pessoa que reivindica ou b) reinvidicação de portabilidade, mas vínculo existente tem como dona pessoa diferente da que reivindica.
ClaimKeyNotFound 404 Não existe vínculo registrado com a chave que está sendo reivindicada.
ClaimAlreadyExistsForKey 400 Existe uma reivindicação com status diferente de concluída ou cancelada para a chave reivindicada. Nova reivindicação para a chave só pode ser criada se a atual foi concluída ou cancelada.
ClaimResultingEntryAlreadyExists 400 Vínculo que resultaria ao processar reivindicação já existe, com mesma chave, participante e dono.
ClaimOperationInvalid 400 Status atual da reivindicação não permite que operação seja feita.
ClaimResolutionPeriodNotEnded 400 Para reivindicação de posse, PSP doador não pode confirmar antes do término do período resolução. Para portabilidade, PSP doador não pode cancelar por fim de prazo antes do término do período resolução.
ClaimCompletionPeriodNotEnded 400 Para reivindicação de posse, se PSP reivindicador tenta encerrar antes do término do período encerramento.
Notificação de infração
InfractionReportInvalid 400 Existem campos inválidos ao tentar criar ou atualizar a notificação de infração.
InfractionReportOperationInvalid 400 Status atual da notificação de infração não permite que operação seja feita.
InfractionReportTransactionNotFound 400 A transação definida na notificação de infração não foi encontrada.
InfractionReportTransactionNotSettled 400 A transação definida na notificação de infração não foi liquidada.
InfractionReportAlreadyBeingProcessedForTransaction 400 Já existe uma notificação de infração em andamento para a transação informada.
InfractionReportAlreadyProcessedForTransaction 400 Já existe uma notificação de infração fechado para a transação informada.
InfractionReportPeriodExpired 400 O prazo para a notificação de infração sobre a transação expirou.
Marcação de fraude
FraudMarkerInvalid 400 Existem campos inválidos ao tentar criar a marcação de fraude.
Solicitação de Devolução
RefundInvalid 400 Existem campos inválidos ao tentar criar ou atualizar a solicitação de devolução.
RefundOperationInvalid 400 Status atual da solicitação de devolução não permite que operação seja feita.
RefundTransactionNotFound 400 A transação definida na solicitação de devolução não foi encontrada.
RefundTransactionNotSettled 400 A transação definida na solicitação de devolução não foi liquidada.
RefundAlreadyProcessedForTransaction 400 Já existe uma solicitação de devolução processada para a transação informada.
RefundAlreadyBeingProcessedForTransaction 400 Já existe uma solicitação de devolução em processamento para a transação informada.
RefundPeriodExpired 400 O prazo para solicitar devolução para a transação expirou.
TransactionNotRefundable 400 A transação informada na requisição não permite devolução.
RefundInfractionReportNotFound 400 Uma notificação de infração correspondente à transação informada não foi encontrada.
TransactionRefundable 400 Transação informada permite devolução.

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

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

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

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

Content type
application/xml
Example
<?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) - Não é permitida a alteração.
  • 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" "RFB_VALIDATION"

Valores válidos: USER_REQUESTED, BRANCH_TRANSFER e RECONCILIATION

Responses

Request samples

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

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

Valores válidos: USER_REQUESTED, ACCOUNT_CLOSURE, RECONCILIATION, FRAUD e RFB_VALIDATION

Responses

Request samples

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

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

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

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:

  1. Houve troca de posse de uma chave (telefone, por exemplo) 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.
  2. 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Response samples

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

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

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

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

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>
        <ContactInformation>
            <Email>abc@pix.br</Email>
            <Phone>+5561988887777</Phone>
        </ContactInformation>
    </InfractionReport>
</CreateInfractionReportRequest>

Response samples

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>
        <ContactInformation>
            <Email>abc@pix.br</Email>
            <Phone>+5561988887777</Phone>
        </ContactInformation>
        <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

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>
            <ContactInformation>
                <Email>abc@pix.br</Email>
                <Phone>+5561988887777</Phone>
            </ContactInformation>
            <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

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>
        <ContactInformation>
            <Email>abc@pix.br</Email>
            <Phone>+5561988887777</Phone>
        </ContactInformation>
        <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

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

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>
        <ContactInformation>
            <Email>abc@pix.br</Email>
            <Phone>+5561988887777</Phone>
        </ContactInformation>
        <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

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

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>
        <ContactInformation>
            <Email>abc@pix.br</Email>
            <Phone>+5561988887777</Phone>
        </ContactInformation>
        <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

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

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>
        <ContactInformation>
            <Email>abc@pix.br</Email>
            <Phone>+5561988887777</Phone>
        </ContactInformation>
        <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>

Solicitação de 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

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

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

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

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.

Uma solicitação de devolução não pode ser cancelada após ter sido fechada.

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

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

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 <= 2000 characters

Detalhes da análise da requisição de devolução indicando a motivação do resultado.

RefundRejectionReason
string
Enum: "NO_BALANCE" "ACCOUNT_CLOSURE" "INVALID_REQUEST" "OTHER"

Razão da rejeição da solicitação de devolução. INVALID_REQUEST só pode ser usada quando RefundReason for OPERATIONAL_FLAW .

RefundTransactionId
string\w{32}

Transação de devolução (completa ou parcial)

Responses

Request samples

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

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

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

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

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

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

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

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>

Listar Marcações de Fraude de Pessoa

Obtém a lista das marcações de fraude registradas 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

Content type
application/xml
<?xml version="1.0" encoding="UTF-8" ?>
<ListPersonFraudMarkersResponse>
    <Signature></Signature>
    <ResponseTime>2023-01-01T10:00:00.000Z</ResponseTime>
    <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId>
    <TaxIdNumber>12345678901</TaxIdNumber>
    <PersonFraudMarkers>
        <FraudMarker>
            <Id>91d65e98-97c0-4b0f-b577-73625da1f9fc</Id>
            <FraudType>MULE_ACCOUNT</FraudType>
            <RegistrantParticipant>99999011</RegistrantParticipant>
            <InfractionReport>
                <Id>91d65e98-97c0-4b0f-b577-73625da1f9fc</Id>
                <ReporterParticipant>99999010</ReporterParticipant>
            </InfractionReport>
        </FraudMarker>
    </PersonFraudMarkers>
</ListPersonFraudMarkersResponse>

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

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>

Listar Marcações de Fraude de Chave Registrada

Obtém a lista das marcações de fraude registradas de 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

Content type
application/xml
<?xml version="1.0" encoding="UTF-8" ?>
<ListEntryFraudMarkersResponse>
    <Signature></Signature>
    <ResponseTime>2023-01-01T10:00:00.000Z</ResponseTime>
    <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId>
    <Key>11122233300</Key>
    <OwnerFraudMarkers>
        <FraudMarker>
            <Id>91d65e98-97c0-4b0f-b577-73625da1f9fc</Id>
            <FraudType>MULE_ACCOUNT</FraudType>
            <RegistrantParticipant>99999011</RegistrantParticipant>
            <InfractionReport>
                <Id>91d65e98-97c0-4b0f-b577-73625da1f9fc</Id>
                <ReporterParticipant>99999010</ReporterParticipant>
            </InfractionReport>
        </FraudMarker>
    </OwnerFraudMarkers>
    <KeyFraudMarkers>
        <FraudMarker>
            <Id>c52cbf2c-99a0-42c1-8504-fb6cbae1db44</Id>
            <FraudType>MULE_ACCOUNT</FraudType>
            <RegistrantParticipant>99999011</RegistrantParticipant>
        </FraudMarker>
    </KeyFraudMarkers>
</ListEntryFraudMarkersResponse>

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

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

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>