Download OpenAPI specification:Download
O Diretório de Identificadores de Contas Transacionais - DICT - é o serviço do arranjo Pix que permite buscar detalhes de contas transacionais com chaves de endereçamento mais convenientes para quem faz um pagamento. Entre os tipos de chave atualmente disponíveis estão CPF, CNPJ, telefone, e-mail e EVP. As informações retornadas pelo DICT permitem ao pagador confirmar a identidade do recebedor, proporcionando uma experiência mais fácil e segura. Permitem também ao PSP do pagador criar a mensagem de instrução de pagamento a ser enviada para o sistema de liquidação com os detalhes de conta do recebedor.
Para informações adicionais, consulte a página do Pix.
⚠️ Versão 2 da API
- 05/11/2023 - ativação da v2 - especificação v2.0.1
- 04/02/2024 - desativação da v1
O DICT utiliza autenticação mútua TLS.
As definições de autenticação para essa API estão especificadas no manual de segurança do Pix.
Requisições que incluam ou alterem informações no DICT devem ser assinadas com XML Digital Signature pelo participante que envia a requisição. Requisições de consulta não precisam ser assinadas. Respostas retornadas pelo DICT serão assinadas digitalmente. As assinaturas devem ser validadas pelos clientes da API.
A assinatura será colocada no elemento Signature
das requisições e respostas.
O Signature
será envelopado pelo XML que está
sendo assinado (assinatura é um elemento filho).
Para mais detalhes sobre a forma de construir a assinatura, consulte o manual de segurança do Pix.
Para preservar a estabilidade do serviço, as operações da API do DICT estão sujeitas a políticas de limitação de requisições. Especificamente para a operação de consulta de vínculo, há também limitação de requisições com a finalidade de prevenir ataques de varredura de dados. O algoritmo usado para implementar as políticas de limitação é o token bucket.
Uma política de limitação tem associado a ela um escopo, que pode ser o usuário final ou o participante. Cada política possui uma taxa de reposição de "fichas", um tamanho de "balde" e uma regra de contagem. A tabela abaixo define as políticas aplicáveis a cada operação da API.
Política | Escopo | Operações | Taxa de reposição | Tamanho do balde |
---|---|---|---|---|
ENTRIES_READ_USER_ANTISCAN | USER | getEntry | 2/min | (*) |
ENTRIES_READ_USER_ANTISCAN_V2 | USER | getEntry | 2/min | (*) |
ENTRIES_READ_PARTICIPANT_ANTISCAN | PSP | getEntry | (**) | (**) |
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 |
STATISTICS_READ | PSP | getOwnerStatistics | 500/min | 500 |
POLICIES_READ | PSP | getBucketState | 60/min | 200 |
POLICIES_LIST | PSP | listBucketStates | 6/min | 20 |
ENTRIES_READ_USER_ANTISCAN
ENTRIES_READ_USER_ANTISCAN_V2
(*) O tamanho do balde das políticas ENTRIES_READ_USER_ANTISCAN e ENTRIES_READ_USER_ANTISCAN_V2 é categorizado de acordo com o tipo de usuário final realizando a consulta, Pessoa Física (PF) ou Pessoa Jurídica (PJ):
Categoria | Tamanho do balde |
---|---|
PF | 100 |
PJ | 1.000 |
ENTRIES_READ_PARTICIPANT_ANTISCAN
(**) O tamanho do balde nesta política depende da categoria em que se enquadra do participante. As seguintes categorias são possíveis:
Categoria | Taxa de reposição | Tamanho do balde |
---|---|---|
A | 25.000/min | 50.000 |
B | 20.000/min | 40.000 |
C | 15.000/min | 30.000 |
D | 8.000/min | 16.000 |
E | 2.500/min | 5.000 |
F | 250/min | 500 |
G | 25/min | 250 |
H | 2/min | 50 |
CLAIMS_LIST_WITH_ROLE
CLAIMS_LIST_WITHOUT_ROLE
REFUND_LIST_WITH_ROLE
REFUND_LIST_WITHOUT_ROLE
Demais políticas
Caso o limite de uma política seja excedido, o que acontece quando a quantidade de fichas chega
a zero, será retornada uma resposta de erro com status 429
.
É altamente recomendável que as conexões HTTP para a comunicação com a API sejam reutilizadas, pois o custo de
estabelecimento de uma conexão mTLS é muito alto em termos de latência. O uso de um pool de conexões HTTP
é uma alternativa efetiva para reutilização de conexões. A API retorna o header Keep-Alive
com o parâmetro timeout
. Nele é informado o tempo em segundos que o servidor esperará antes de fechar a conexão caso não ocorram
requisições adicionais.
É recomendável também que se utilize compressão. Para que as respostas da API utilizem compressão, adicione nas
requisições o header Accept-Encoding: gzip
. O envio de requisições com compressão não é suportado.
As seguintes mudanças são esperadas e consideradas compatíveis:
A versão da API é composta por 4 elementos: major, minor, patch e release candidate.
A versão que consta no path da URL é o elemento major da versão da API.
A evolução da versão se dá seguinte forma:
Não serão feitas mais que uma evolução major em um período de 6 meses, ressalvado motivo de força maior. Quando houver uma evolução major, a versão anterior ficará disponível por no mínimo 1 mês.
Alterações sem quebra de contrato e esclarecimentos às especificações podem ocorrer a qualquer momento. Clientes devem estar preparados para lidar com essas mudanças sem quebrar.
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/v1/error/<TipoErro>
Abaixo estão listados os tipos de erro do DICT.
Gerais
Forbidden
BadRequest
NotFound
RateLimited
InternalServerError
ServiceUnavailable
RequestSignatureInvalid
RequestIdAlreadyUsed
RequestId
de requisição feita anteriormente, mas com parâmetros diferentes.InvalidReason
ParticipantInvalid
Vínculos
EntryInvalid
EntryLimitExceeded
EntryAlreadyExists
EntryCannotBeQueriedForBookTransfer
EntryKeyOwnedByDifferentPerson
EntryKeyInCustodyOfDifferentParticipant
EntryLockedByClaim
EntryTaxIdNumberByDifferentOwner
EntryBlocked
Reivindicações
ClaimInvalid
ClaimTypeInconsistent
ClaimKeyNotFound
ClaimAlreadyExistsForKey
ClaimResultingEntryAlreadyExists
ClaimOperationInvalid
ClaimResolutionPeriodNotEnded
ClaimCompletionPeriodNotEnded
Relatos de Infração
InfractionReportInvalid
InfractionReportOperationInvalid
InfractionReportTransactionNotFound
InfractionReportTransactionNotSettled
InfractionReportAlreadyBeingProcessedForTransaction
InfractionReportAlreadyProcessedForTransaction
InfractionReportPeriodExpired
Devoluções
RefundOperationInvalid
RefundTransactionNotFound
RefundTransactionNotSettled
RefundAlreadyProcessedForTransaction
RefundAlreadyBeingProcessedForTransaction
RefundPeriodExpired
TransactionNotRefundable
RefundInfractionReportNotFound
O diretório de identificadores de contas transacionais é um conjunto de vínculos. Um vínculo é uma associação entre uma chave de endereçamento, uma conta transacional e seu dono. O dono pode ser uma pessoa física ou uma pessoa jurídica. A chave de endereçamento é usada para identificar unicamente um vínculo.
Exemplo de vínculo:
Chave | Conta | Dono |
---|---|---|
+5510998765432 | Banco Fictício/Ag.7263-4/Cc.748627-1 | José João da Silva |
Cria um novo vínculo de chave com conta transacional.
A operação de criação de vínculo é idempotente. Isso significa que é seguro realizar uma nova tentativa em caso de falhas temporárias, como erros de conexão ou término abrupto de processos. A resposta retornada para uma requisição repetida é equivalente à resposta dada à primeira requisição processada.
Para garantir a idempotência da operação, a requisição tem um campo RequestId
. Esse campo é um
UUID versão 4 e deve ser único no contexto de um mesmo participante.
O RequestId
fica associado ao vínculo criado e é usado no cálculo do seu CID (ver seção de reconciliação).
Uma requisição de criação é considerada repetida quando o CID do vínculo contido na requisição já existe no DICT.
Caso seja feita uma requisição com um RequestId
previamente usado, mas com parâmetros diferentes para o vínculo,
será retornado o erro RequestIdAlreadyUsed
.
Signature | object |
required | object (Entry) Vínculo entre uma chave de endereçamento, conta transacional e seu dono. |
Reason required | string Enum: "USER_REQUESTED" "ACCOUNT_CLOSURE" "BRANCH_TRANSFER" "RECONCILIATION" "FRAUD" Valores válidos: |
RequestId required | string <uuid> (RequestId) Chave de idempotência da requisição. UUID versão 4. |
<?xml version="1.0" encoding="UTF-8" ?> <CreateEntryRequest> <Signature></Signature> <Entry> <Key>+5561988880000</Key> <KeyType>PHONE</KeyType> <Account> <Participant>12345678</Participant> <Branch>0001</Branch> <AccountNumber>0007654321</AccountNumber> <AccountType>CACC</AccountType> <OpeningDate>2010-01-10T03:00:00Z</OpeningDate> </Account> <Owner> <Type>NATURAL_PERSON</Type> <TaxIdNumber>11122233300</TaxIdNumber> <Name>João Silva</Name> </Owner> </Entry> <Reason>USER_REQUESTED</Reason> <RequestId>a946d533-7f22-42a5-9a9b-e87cd55c0f4d</RequestId> </CreateEntryRequest>
<?xml version="1.0" encoding="UTF-8" ?> <CreateEntryResponse> <Signature></Signature> <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime> <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId> <Entry> <Key>11122233300</Key> <KeyType>CPF</KeyType> <Account> <Participant>12345678</Participant> <Branch>0001</Branch> <AccountNumber>0007654321</AccountNumber> <AccountType>CACC</AccountType> <OpeningDate>2010-01-10T03:00:00.000Z</OpeningDate> </Account> <Owner> <Type>NATURAL_PERSON</Type> <TaxIdNumber>11122233300</TaxIdNumber> <Name>João Silva</Name> </Owner> <CreationDate>2019-11-18T03:00:00.000Z</CreationDate> <KeyOwnershipDate>2019-11-18T03:00:00.000Z</KeyOwnershipDate> </Entry> </CreateEntryResponse>
Obtém um vínculo contendo os detalhes de conta transacional associados a uma chave de endereçamento.
A fim de permitir avaliação de risco de fraude, na consulta de vínculos são fornecidos contadores dos seguintes eventos:
Os eventos são agregados por chave, titular (cpf ou cnpj) e conta transacional em 3 janelas temporais:
Esses contadores tem ciclo de vida independente do vínculo. Eles não são zerados, mesmo que haja desativação da chave ou da conta. Se houver troca de titularidade, ou portabilidade, os dados são herdados pelo novo registro no que couber (titular, chave, ou conta).
Os contadores de transações realizadas são quantizados. A escala usada é 0, 1, 5, 10, 50, 100, 500, 1000, 5000... Arrendonda-se o número para cima, por exemplo: 3 → 5, 190 → 500 .
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 único do usuário final, vinculado a um participante.
Requisições vindas de um mesmo usuário, para um mesmo participante, devem usar o mesmo identificador.
A partir da versão 1.5.0
da API DICT, este parâmetro deverá ser preenchido com o CPF do usuário final
(11 dígitos), no caso de pessoa física, ou com o CNPJ (14 dígitos), no caso de pessoa jurídica.
O valor não deve ser pseudonimizado, pois a informação passará a ser considerada no rastreamento
de possíveis violações de limites.
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.
Key required | string (Key) <= 77 characters Example: 12345678901 Chave de endereçamento |
PI-RequestingParticipant required | string^[0-9]{8}$ Example: 12345678 Identificador único do requisitante, podendo ser:
|
PI-PayerId required | string^([0-9]{11}|[0-9]{14})$ Identificador do pagador que originou a requisição. Usado para rate-limiting. |
PI-EndToEndId required | string Identificador fim-a-fim do pagamento associado a essa requisição. Corresponde ao campo |
<?xml version="1.0" encoding="UTF-8" ?> <GetEntryResponse> <Signature></Signature> <ResponseTime>2020-01-10T10:00:00Z</ResponseTime> <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId> <Entry> <Key>11122233300</Key> <KeyType>CPF</KeyType> <Account> <Participant>12345678</Participant> <Branch>0001</Branch> <AccountNumber>0007654321</AccountNumber> <AccountType>CACC</AccountType> <OpeningDate>2010-01-10T03:00:00Z</OpeningDate> </Account> <Owner> <Type>NATURAL_PERSON</Type> <TaxIdNumber>11122233300</TaxIdNumber> <Name>João Silva</Name> </Owner> <CreationDate>2019-11-18T03:00:00Z</CreationDate> <KeyOwnershipDate>2019-11-18T03:00:00Z</KeyOwnershipDate> <OpenClaimCreationDate>2019-11-19T03:00:00Z</OpenClaimCreationDate> </Entry> <Statistics> <LastUpdated>2020-01-17T10:00:00Z</LastUpdated> <Counters> <Counter type="SETTLEMENTS" by="KEY" d3="0" d30="5" m6="30"/> <Counter type="SETTLEMENTS" by="OWNER" d3="0" d30="5" m6="30"/> <Counter type="SETTLEMENTS" by="ACCOUNT" d3="0" d30="5" m6="30"/> <Counter type="REPORTED_FRAUDS" by="KEY" d3="0" d30="5" m6="30"/> <Counter type="REPORTED_FRAUDS" by="OWNER" d3="0" d30="5" m6="30"/> <Counter type="REPORTED_FRAUDS" by="ACCOUNT" d3="0" d30="5" m6="30"/> <Counter type="CONFIRMED_FRAUDS" by="KEY" d3="0" d30="5" m6="30"/> <Counter type="CONFIRMED_FRAUDS" by="OWNER" d3="0" d30="5" m6="30"/> <Counter type="CONFIRMED_FRAUDS" by="ACCOUNT" d3="0" d30="5" m6="30"/> <Counter type="REJECTED" by="KEY" d3="0" d30="5" m6="30"/> <Counter type="REJECTED" by="OWNER" d3="0" d30="5" m6="30"/> <Counter type="REJECTED" by="ACCOUNT" d3="0" d30="5" m6="30"/> </Counters> </Statistics> </GetEntryResponse>
Atualiza um vínculo.
A ser utilizado no cenário de atualização da informação da conta, nome e nome fantasia de um cliente, permanecendo este no mesmo PSP. Somente podem ser atualizadas as informações de conta do vínculo, nome e nome fantasia do cliente. Outras atualizações do vínculo devem ser feitas por exclusão/inclusão do vínculo, portabilidade ou reivindicação de posse, a depender da situação.
As seguintes restrições devem ser obedecidas na atualização de vínculo, de acordo com o tipo de chave:
EVP
(aleatórias) - É permitida a alteração, porém, apenas com os motivos BRANCH_TRANSFER
ou RECONCILIATION
.USER_REQUESTED
, BRANCH_TRANSFER
ou RECONCILIATION
.Key required | string (Key) <= 77 characters Example: 12345678901 Chave de endereçamento |
Signature | object |
Key required | string (Key) <= 77 characters Chave de endereçamento |
object (BrazilianAccount) Dados de conta transacional no Brasil. | |
NATURAL_PERSON (object) or LEGAL_PERSON (object) (Person) Dados de pessoa física ou jurídica | |
Reason required | string Enum: "USER_REQUESTED" "ACCOUNT_CLOSURE" "BRANCH_TRANSFER" "RECONCILIATION" "FRAUD" Valores válidos: |
<?xml version="1.0" encoding="UTF-8" ?> <UpdateEntryRequest> <Signature></Signature> <Key>+5561988887777</Key> <Account> <Participant>12345678</Participant> <Branch>0001</Branch> <AccountNumber>0007654321</AccountNumber> <AccountType>CACC</AccountType> <OpeningDate>2010-01-10T03:00:00Z</OpeningDate> </Account> <Owner> <Type>NATURAL_PERSON</Type> <TaxIdNumber>11122233300</TaxIdNumber> <Name>João Silva</Name> </Owner> <Reason>USER_REQUESTED</Reason> </UpdateEntryRequest>
<?xml version="1.0" encoding="UTF-8" ?> <UpdateEntryResponse> <Signature></Signature> <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime> <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId> <Entry> <Key>11122233300</Key> <KeyType>CPF</KeyType> <Account> <Participant>12345678</Participant> <Branch>0001</Branch> <AccountNumber>0007654321</AccountNumber> <AccountType>CACC</AccountType> <OpeningDate>2010-01-10T03:00:00.000Z</OpeningDate> </Account> <Owner> <Type>NATURAL_PERSON</Type> <TaxIdNumber>11122233300</TaxIdNumber> <Name>João Silva</Name> </Owner> <CreationDate>2019-11-18T03:00:00.000Z</CreationDate> <KeyOwnershipDate>2019-11-18T03:00:00.000Z</KeyOwnershipDate> </Entry> </UpdateEntryResponse>
Somente para PSPs iniciadores.
Obtém um vínculo contendo os detalhes de conta transacional associados a uma chave de endereçamento.
Aplica-se as mesmas regras da seção "Dados anti-fraude" de consultar vínculo.
Assim como na consulta geral de chaves descrita na seção consultar vínculo, a consulta a chaves do tipo EMAIL e PHONE para PSP's iniciadores também 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, obrigatórios para todos os tipos de chaves, porém, diferentemente das políticas anti scan aplicadas à consulta geral de chaves, as "fichas" não são repostas nos "baldes" quando as ordens de pagamento são enviadas. Os baldes possuem apenas a reposição periódica, como descrito na seção segurança.
Aplica-se as mesmas recomendações da seção "Cache" de consultar vínculo.
Key required | string (Key) <= 77 characters Example: 12345678901 Chave de endereçamento |
PI-RequestingParticipant required | string^[0-9]{8}$ Example: 12345678 Identificador SPB do participante (direto ou indireto) que faz a requisição. |
PI-PayerId required | string^([0-9]{11}|[0-9]{14})$ Identificador do pagador que originou a requisição. Usado para rate-limiting. |
<?xml version="1.0" encoding="UTF-8" ?> <GetEntryResponse> <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> <OpenClaimCreationDate>2019-11-19T03:00:00.000Z</OpenClaimCreationDate> </Entry> <Statistics> <LastUpdated>2020-01-17T10:00:00.000Z</LastUpdated> <Counters> <Counter type="SETTLEMENTS" by="KEY" d3="0" d30="5" m6="30"/> <Counter type="SETTLEMENTS" by="OWNER" d3="0" d30="5" m6="30"/> <Counter type="SETTLEMENTS" by="ACCOUNT" d3="0" d30="5" m6="30"/> <Counter type="REPORTED_FRAUDS" by="KEY" d3="0" d30="5" m6="30"/> <Counter type="REPORTED_FRAUDS" by="OWNER" d3="0" d30="5" m6="30"/> <Counter type="REPORTED_FRAUDS" by="ACCOUNT" d3="0" d30="5" m6="30"/> <Counter type="CONFIRMED_FRAUDS" by="KEY" d3="0" d30="5" m6="30"/> <Counter type="CONFIRMED_FRAUDS" by="OWNER" d3="0" d30="5" m6="30"/> <Counter type="CONFIRMED_FRAUDS" by="ACCOUNT" d3="0" d30="5" m6="30"/> </Counters> </Statistics> </GetEntryResponse>
Remove um vínculo de chave com conta.
Key required | string (Key) <= 77 characters Example: 12345678901 Chave de endereçamento |
Signature | object |
Key required | string (Key) <= 77 characters Chave de endereçamento |
Participant required | string^[0-9]{8}$ Identificador SPB do provedor da conta ao qual a chave está vinculada |
Reason required | string Enum: "USER_REQUESTED" "ACCOUNT_CLOSURE" "BRANCH_TRANSFER" "RECONCILIATION" "FRAUD" Valores válidos: |
<?xml version="1.0" encoding="UTF-8" ?> <DeleteEntryRequest> <Signature></Signature> <Key>+5561988887777</Key> <Participant>12345678</Participant> <Reason>ACCOUNT_CLOSURE</Reason> </DeleteEntryRequest>
<?xml version="1.0" encoding="UTF-8" ?> <DeleteEntryResponse> <Signature></Signature> <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime> <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId> <Key>+5561988887777</Key> </DeleteEntryResponse>
Uma chave transacional é uma sequência de caracteres que identifica um vínculo de forma única no diretório de identificadores. A existência de uma determinada chave no diretório implica diretamente na 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][0-9]\d{1,14}$ | +5510998765432 | |
^[a-z0-9.!#$&'*+\/=?^_`{ | }~-]+@a-z0-9?(?:\.a-z0-9?)*$ | pix@bcb.gov.br | |
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.
Apesar da existência de uma chave estar sempre relacionada a um vínculo, é possível a realização de consultas de existência de chaves.
Consulta a existência de um conjunto de chaves no diretório de identificadores.
Keys required | Array of strings (Key) [ 1 .. 200 ] items Chaves de endereçamento |
<?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>
<?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>
Conforme as chaves mudem de dono ou os usuários finais criem contas transacionais em outros PSPs, os seguintes cenários precisarão ser tratados:
Para o cenário 1, deve ser criada uma reivindicação de posse. Já para o cenário 2, uma portabilidade. Em ambos cenários existirá a figura do PSP que irá ceder a chave (PSP Doador), e o PSP que irá receber a chave (PSP Reivindicador). No cenário de reivindicação de posse, o PSP doador e o reivindicador podem ser o mesmo.
Nessa especificação, reivindicação sem qualificador é usado como termo mais genérico para se referir tanto à reivindicação de posse quanto à (reivindicação de) portabilidade.
Os processos de reivindicação são sempre iniciados pelo PSP reivindicador. Uma reivindicação tem as seguintes situações:
OPEN
- Aberta pelo reivindicador, mas ainda não recebida pelo doador.WAITING_RESOLUTION
- Já foi recebida pelo doador e está aguardando a resolução. Os critérios confirmação
ou cancelamento da reivindicação seguem normas específicas a depender do tipo (posse ou portabilidade).CONFIRMED
- O doador confirmou a reivindicação. Isso implica a remoção da chave do DICT e da base interna
do PSP doador. Está aguardando o reivindicador encerrar o processo.CANCELLED
- O doador ou reivindicador cancelou a reivindicação.COMPLETED
- Tanto o DICT quanto o reivindicador atualizaram suas bases com o novo vínculo.Diagrama de estados
( OPEN )------->( WAITING_RESOLUTION )------->( CONFIRMED )------->( COMPLETED )
| /
| /
| /
| /
v /
( CANCELLED )<------------v
Importante! Os participantes deverão monitorar as reivindicações fazendo polling períodico no endpoint de listar reivindicações. A periodicidade adequada dependerá das definições de nível de serviço. Consulte o Manual de Tempos do Pix.
Cria uma nova reivindicação.
Essa operação é feita pelo participante reivindicador a pedido do usuário final. O vínculo atual permanece inalterado, até que haja a confirmação pelo PSP doador.
Nem todo tipo de chave pode ser reivindicado ou portado. A tabela abaixo define as possibilidades:
compatível? | OWNERSHIP | PORTABILITY |
---|---|---|
CPF | ✓ | |
CNPJ | ✓ | |
PHONE | ✓ | ✓ |
✓ | ✓ | |
EVP |
Signature | object |
required | object (Claim) |
<?xml version="1.0" encoding="UTF-8" ?> <CreateClaimRequest> <Signature></Signature> <Claim> <Type>OWNERSHIP</Type> <Key>+5561988887777</Key> <KeyType>PHONE</KeyType> <ClaimerAccount> <Participant>12345678</Participant> <Branch>0001</Branch> <AccountNumber>0007654321</AccountNumber> <AccountType>CACC</AccountType> <OpeningDate>2010-01-10T03:00:00Z</OpeningDate> </ClaimerAccount> <Claimer> <Type>NATURAL_PERSON</Type> <TaxIdNumber>11122233300</TaxIdNumber> <Name>João Silva</Name> </Claimer> </Claim> </CreateClaimRequest>
<?xml version="1.0" encoding="UTF-8" ?> <CreateClaimResponse> <Signature></Signature> <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime> <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId> <Claim> <Type>OWNERSHIP</Type> <Key>+5561988887777</Key> <KeyType>PHONE</KeyType> <ClaimerAccount> <Participant>12345678</Participant> <Branch>0001</Branch> <AccountNumber>0007654321</AccountNumber> <AccountType>CACC</AccountType> <OpeningDate>2010-01-10T03:00:00.000Z</OpeningDate> </ClaimerAccount> <Claimer> <Type>NATURAL_PERSON</Type> <TaxIdNumber>11122233300</TaxIdNumber> <Name>João Silva</Name> </Claimer> <DonorParticipant>87654321</DonorParticipant> <Id>123e4567-e89b-12d3-a456-426655440000</Id> <Status>OPEN</Status> <CompletionPeriodEnd>2020-01-17T10:00:00.000Z</CompletionPeriodEnd> <ResolutionPeriodEnd>2020-01-17T10:00:00.000Z</ResolutionPeriodEnd> <LastModified>2020-01-10T10:00:00.000Z</LastModified> </Claim> </CreateClaimResponse>
Obtém uma lista de reivindicações, ordenada de forma crescente pelo campo LastModified
, de acordo com os filtros passados.
Observações:
isDonor
e isClaimer
, quando os valores passados são iguais, é disjuntivo: são retornadas reinvidicações em que
o participante é doador OU reivindicador.Participant required | string^[0-9]{8} ISPB do partipante direto ou indireto interessado |
IncludeIndirectParticipants | boolean Default: false Inclui adicionalmente as reivindicações de participantes indiretos |
IsDonor | boolean 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 |
ModifiedBefore | string <date-time> Filtra reivindicações com data-hora de modificação menor ou igual a |
Limit | integer <= 200 Default: 20 Número limite de reivindicações a retornar |
<?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>
Obtém detalhes de uma reivindicação.
ClaimId required | string <uuid> |
PI-RequestingParticipant required | string^[0-9]{8}$ Example: 12345678 Identificador SPB do participante (direto ou indireto) que faz a requisição. |
<?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>
Notifica recebimento pelo participante doador de reivindicação com status OPEN
.
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.
ClaimId required | string <uuid> |
Signature | object |
ClaimId required | string <uuid> |
Participant required | string^[0-9]{8}$ Identificador SPB do doador |
<?xml version="1.0" encoding="UTF-8" ?> <AcknowledgeClaimRequest> <Signature></Signature> <ClaimId>123e4567-e89b-12d3-a456-426655440000</ClaimId> <Participant>12345678</Participant> </AcknowledgeClaimRequest>
<?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>
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 | ✓ |
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.
ClaimId required | string <uuid> |
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 |
<?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>
<?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>
Cancela reivindicação.
Para reivindicação de posse, status deve ser 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.
Para portabilidade, status também deve ser WAITING_RESOLUTION
ou CONFIRMED
. 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 e do tipo, quem pode cancelar.
WAIT_RES = WAITING_RESOLUTION
CONFIRM = CONFIRMED
OWNERSHIP | PORTABILITY | |||||||
---|---|---|---|---|---|---|---|---|
Razão | Doador | Reivindicador | Doador | Reivindicador | ||||
WAIT_RES | CONFIRM | |||||||
USER_REQUESTED | ✓ | ✓ | ✓ | |||||
ACCOUNT_CLOSURE | ✓ | ✓ | ||||||
FRAUD | ✓ | ✓ | ✓ | ✓ | ✓ | |||
DEFAULT_OPERATION | ✓ | ✓ | ||||||
RECONCILIATION | ✓ |
A operação é idempotente. Caso reivindicação já tenha sido cancelada com os mesmos parâmetros, será retornada resposta equivalente à primeira requisição.
ClaimId required | string <uuid> |
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 |
<?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>
<?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>
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
.
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.
ClaimId required | string <uuid> |
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. |
<?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>
<?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>
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.
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'
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:
Cria uma verificação de sincronismo para um partipante e tipo de chave.
Signature | object |
required | object (SyncVerification) |
<?xml version="1.0" encoding="UTF-8" ?> <CreateSyncVerificationRequest> <Signature></Signature> <SyncVerification> <Participant>12345678</Participant> <KeyType>CPF</KeyType> <ParticipantSyncVerifier>e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855</ParticipantSyncVerifier> </SyncVerification> </CreateSyncVerificationRequest>
<?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>
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.
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. |
<?xml version="1.0" encoding="UTF-8" ?> <CreateCidSetFileRequest> <Signature></Signature> <Participant>12345678</Participant> <KeyType>PHONE</KeyType> </CreateCidSetFileRequest>
<?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>
Obtém detalhes do arquivo de CIDs requisitado
Id required | integer |
PI-RequestingParticipant required | string^[0-9]{8}$ Example: 12345678 Identificador SPB do participante (direto ou indireto) que faz a requisição. |
<?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>
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) |
Observação:
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 |
EndTime | string <date-time> Filtra eventos com data-hora menor ou igual a |
Limit | integer <= 200 Default: 100 Número limite de eventos a retornar |
<?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>
Obtém detalhes de um vínculo ativo identificado pelo CID
Cid required | string (Cid) ^[0-9a-fA-F]{64}$ Identificador de conteúdo |
PI-RequestingParticipant required | string^[0-9]{8}$ Example: 12345678 Identificador SPB do participante (direto ou indireto) que faz a requisição. |
<?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>
Relatos de infração servem para reportar transações sob suspeita de fraude (FRAUD). Podem ser feitas tanto pelo participante debitado quanto pelo creditado na transação.
Depois de criado, o relato deve ser reconhecido pela outra parte da transação (acknowledge) e, após análise, fechado (close) concordando (AGREED) ou discordando (DISAGREED) da infração.
O criador do relato pode cancelá-lo a qualquer momento, mesmo depois de fechado.
Relatos de infração são criados a partir do identificador da transação realizada no SPI (EndToEndId). O prazo máximo para relatar infração em uma transação está no Manual Operacional do DICT
Cada participante deve realizar polling periódico na lista de relatos para verificar se existem novos relatos em que é parte. O recebimento do relato não implica em concordância. Os níveis de serviço exigidos para as operações com relatos de infração estão definidos no Manual de Tempos do Pix.
Os relatos por motivo de fraude são contabilizados e retornados ao consultar vínculo. Se for cancelado, o relato deixa de ser contabilizado em REPORTED_FRAUDS durante a consulta de vínculos.
Cria um relato de infração. Tanto o participante debitado quanto o creditado podem criar um relato de infração.
Signature | object |
Participant required | string^[0-9]{8}$ Identificador SPB do participante que identificou a infração |
required | object (InfractionReport) Relato de infração sobre uma transação |
<?xml version="1.0" encoding="UTF-8" ?> <CreateInfractionReportRequest> <Signature></Signature> <Participant>99999010</Participant> <InfractionReport> <TransactionId>E9999901012341234123412345678900</TransactionId> <InfractionType>FRAUD</InfractionType> <ReportDetails>Transação feita através de QR Code falso em boleto</ReportDetails> </InfractionReport> </CreateInfractionReportRequest>
<?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> <InfractionType>FRAUD</InfractionType> <ReportedBy>DEBITED_PARTICIPANT</ReportedBy> <ReportDetails>Transação feita através de QR Code falso em boleto</ReportDetails> <Id>91d65e98-97c0-4b0f-b577-73625da1f9fc</Id> <Status>OPEN</Status> <DebitedParticipant>99999010</DebitedParticipant> <CreditedParticipant>99999011</CreditedParticipant> <CreationTime>2020-01-17T10:00:00.000Z</CreationTime> <LastModified>2020-01-17T10:00:00.000Z</LastModified> </InfractionReport> </CreateInfractionReportResponse>
Obtém lista de relatos de infração em que o participante é parte.
Lista de relatos é ordenada de forma crescente pelo campo LastModified
.
Observação:
Participant required | string^[0-9]{8}$ ISPB do partipante direto ou indireto interessado |
IncludeIndirectParticipants | boolean Default: false Inclui adicionalmente os relatos de infração de participantes indiretos |
IsDebited | boolean Restringe a relatos em que o participante é o debitado |
IsCredited | boolean Restringe a relatos em que o participante é o creditado |
Status | Array of strings (InfractionReportStatus) Items Enum: "OPEN" "ACKNOWLEDGED" "CLOSED" "CANCELLED" Lista de Status a serem pesquisados |
IncludeDetails | boolean Default: false Inclui os detalhes do relato (campos Details) |
ModifiedAfter | string <date-time> Filtra relatos com data-hora de modificação maior ou igual a |
ModifiedBefore | string <date-time> Filtra relatos com data-hora de modificação menor ou igual a |
Limit | integer <= 200 Default: 20 Número limite de relatos a retornar |
<?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> <InfractionType>FRAUD</InfractionType> <ReportedBy>DEBITED_PARTICIPANT</ReportedBy> <ReportDetails>Transação feita através de QR Code falso em boleto</ReportDetails> <Id>91d65e98-97c0-4b0f-b577-73625da1f9fc</Id> <Status>CLOSED</Status> <DebitedParticipant>99999010</DebitedParticipant> <CreditedParticipant>99999011</CreditedParticipant> <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> </InfractionReports> </ListInfractionReportsResponse>
Obtém detalhes de um relato de infração.
InfractionReportId required | string <uuid> |
PI-RequestingParticipant required | string^[0-9]{8}$ Example: 12345678 Identificador SPB do participante (direto ou indireto) que faz a requisição. |
<?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> <InfractionType>FRAUD</InfractionType> <ReportedBy>DEBITED_PARTICIPANT</ReportedBy> <ReportDetails>Transação feita através de QR Code falso em boleto</ReportDetails> <Id>91d65e98-97c0-4b0f-b577-73625da1f9fc</Id> <Status>ACKNOWLEDGED</Status> <DebitedParticipant>99999010</DebitedParticipant> <CreditedParticipant>99999011</CreditedParticipant> <CreationTime>2020-01-17T10:00:00.000Z</CreationTime> <LastModified>2020-01-17T10:00:00.000Z</LastModified> </InfractionReport> </GetInfractionReportResponse>
Notifica recebimento pelo participante. Se o relato foi criado pelo participante debitado, o creditado deve realizar o recebimento. Por outro lado, se o relato foi criado pelo creditado, o debitado deve realizar o recebimento.
A operação é idempotente. Caso o relato já tenha sido recebido e esteja ainda com
status ACKNOWLEDGED
, será retornada resposta equivalente à primeira requisição.
InfractionReportId required | string <uuid> |
Signature | object |
InfractionReportId required | string <uuid> ID do relato de infração |
Participant required | string^[0-9]{8}$ Identificador SPB do participante realizando o ACK |
<?xml version="1.0" encoding="UTF-8" ?> <AcknowledgeInfractionReportRequest> <Signature></Signature> <InfractionReportId>91d65e98-97c0-4b0f-b577-73625da1f9fc</InfractionReportId> <Participant>12345678</Participant> </AcknowledgeInfractionReportRequest>
<?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> <InfractionType>FRAUD</InfractionType> <ReportedBy>DEBITED_PARTICIPANT</ReportedBy> <ReportDetails>Transação feita através de QR Code falso em boleto</ReportDetails> <Id>91d65e98-97c0-4b0f-b577-73625da1f9fc</Id> <Status>CLOSED</Status> <DebitedParticipant>99999010</DebitedParticipant> <CreditedParticipant>99999011</CreditedParticipant> <CreationTime>2020-01-17T10:00:00.000Z</CreationTime> <LastModified>2020-01-17T10:00:00.000Z</LastModified> </InfractionReport> </AcknowledgeInfractionReportResponse>
Cancela o relato de infração. Só pode ser realizada pelo participante que criou o relato.
A operação é idempotente. Caso o relato já tenha sido cancelado com os mesmos parâmetros, será retornada resposta equivalente à primeira requisição.
InfractionReportId required | string <uuid> |
Signature | object |
InfractionReportId required | string <uuid> ID do relato de infração |
Participant required | string^[0-9]{8}$ Identificador SPB do participante que reportou a infração |
<?xml version="1.0" encoding="UTF-8" ?> <CancelInfractionReportRequest> <Signature></Signature> <InfractionReportId>91d65e98-97c0-4b0f-b577-73625da1f9fc</InfractionReportId> <Participant>12345678</Participant> </CancelInfractionReportRequest>
<?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> <InfractionType>FRAUD</InfractionType> <ReportedBy>DEBITED_PARTICIPANT</ReportedBy> <ReportDetails>Transação feita através de QR Code falso em boleto</ReportDetails> <Id>91d65e98-97c0-4b0f-b577-73625da1f9fc</Id> <Status>CANCELLED</Status> <DebitedParticipant>99999010</DebitedParticipant> <CreditedParticipant>99999011</CreditedParticipant> <CreationTime>2020-01-17T10:00:00.000Z</CreationTime> <LastModified>2020-01-17T10:00:00.000Z</LastModified> </InfractionReport> </CancelInfractionReportResponse>
Fecha o relato de infração. Se o relato foi criado pelo participante debitado, o creditado deve realizar o fechamento. Por outro lado, se o relato foi criado pelo creditado, o debitado deve realizar o fechamento.
Para fechamento, o status deve ser ACKNOWLEDGED
.
A operação é idempotente. Caso o relato já tenha sido fechado com os mesmos parâmetros, será retornada resposta equivalente à primeira requisição.
InfractionReportId required | string <uuid> |
Signature | object |
InfractionReportId required | string <uuid> ID do relato de infração |
Participant required | string^[0-9]{8}$ Identificador SPB do participante. |
AnalysisResult required | string (AnalysisResult) Enum: "AGREED" "DISAGREED" Resultado da análise da infração. |
AnalysisDetails | string (AnalysisDetails) <= 2000 characters Detalhes da análise da infração, que possam orientar o pagador dos próximos passos. |
<?xml version="1.0" encoding="UTF-8" ?> <CloseInfractionReportRequest> <Signature></Signature> <InfractionReportId>91d65e98-97c0-4b0f-b577-73625da1f9fc</InfractionReportId> <Participant>12345678</Participant> <AnalysisResult>AGREED</AnalysisResult> <AnalysisDetails> Valor bloqueado. Para mais informações, contactar central antifraude em 11 3000-00000, informando ID 9999. </AnalysisDetails> </CloseInfractionReportRequest>
<?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> <InfractionType>FRAUD</InfractionType> <ReportedBy>DEBITED_PARTICIPANT</ReportedBy> <ReportDetails>Transação feita através de QR Code falso em boleto</ReportDetails> <Id>91d65e98-97c0-4b0f-b577-73625da1f9fc</Id> <Status>CLOSED</Status> <DebitedParticipant>99999010</DebitedParticipant> <CreditedParticipant>99999011</CreditedParticipant> <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>
A solicitação de devolução pode ser realizada pelo PSP do usuário pagador, por iniciativa própria ou a pedido do usuário, nos casos em que exista fundada suspeita do uso do arranjo para a prática de fraude e naqueles em que se verifique falha operacional no sistema de tecnologia da informação de qualquer dos participantes envolvidos na transação. Uma solicitação de devolução pode ter os seguintes estados no DICT:
Cria uma Solicitação de devolução. Apenas o participante debitado pode criar uma Solicitação de devolução.
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. |
<?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>
<?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>
Obtém lista de requisições de devolução em que o participante é parte.
Lista de devoluções é ordenada de forma crescente pelo campo LastModified
.
Observação:
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 |
ModifiedBefore | string <date-time> Filtra devoluções com data-hora de modificação menor ou igual a |
Limit | integer <= 200 Default: 20 Número limite de devoluções a retornar |
<?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>
Obtém detalhes de uma solicitação de devolução.
RefundId required | string <uuid> |
PI-RequestingParticipant required | string^[0-9]{8}$ Example: 12345678 Identificador SPB do participante (direto ou indireto) que faz a requisição. |
<?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>
Cancela a Solicitação de devolução. Só pode ser realizada pelo participante que criou a solicitação.
A operação é idempotente. Caso a solicitação já tenha sido cancelada com os mesmos parâmetros, será retornada resposta equivalente à primeira requisição.
RefundId required | string <uuid> |
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 |
<?xml version="1.0" encoding="UTF-8" ?> <CancelRefundRequest> <Signature></Signature> <RefundId>91d65e98-97c0-4b0f-b577-73625da1f9fc</RefundId> <Participant>12345678</Participant> </CancelRefundRequest>
<?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>
Fecha a solicitação de devolução. A solicitação só pode ser fechada pelo participante contestado.
Para fechamento, o status deve ser OPEN
.
A operação é idempotente. Caso a solicitação já tenha sido fechada com os mesmos parâmetros, será retornada resposta equivalente à primeira requisição.
RefundId required | string <uuid> |
Signature | object |
RefundId required | string <uuid> ID da solicitação de devolução |
Participant required | string^[0-9]{8}$ Identificador SPB do participante contestado |
RefundAnalysisResult required | string (RefundAnalysisResult) Enum: "TOTALLY_ACCEPTED" "PARTIALLY_ACCEPTED" "REJECTED" Resultado da análise da requisição de devolução pelo constestado. |
RefundAnalysisDetails | string (RefundAnalysisDetails) <= 2000 characters Detalhes da análise da requisição de devolução indicando a motivação do resultado. |
RefundRejectionReason | string (RefundRejectionReason) Enum: "NO_BALANCE" "ACCOUNT_CLOSURE" "OTHER" Razão da rejeição da solicitação de devolução. |
RefundTransactionId | string\w{32} Transação de devolução (completa ou parcial) |
<?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>
<?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>
O DICT fornece dados estatísticos de usuários finais, que podem ser consultados através do TaxIdNumber
(CPF ou CNPJ). As informações
providas detalham o total de liquidações, fraudes reportadas e fraudes confirmadas do respectivo usuário consultado.
Assim como nos dados estatísticos de chaves, esses totais são consolidados para os últimos 3 dias, 30 dias e 6 meses anteriores ao
momento da consulta.
Obtém dados estatísticos de perfil de uso do usuário (liquidações, fraudes reportadas e fraudes confirmadas)
TaxIdNumber required | string^[0-9]{11,14}$ Example: 12345678901 |
PI-RequestingParticipant required | string^[0-9]{8}$ Example: 12345678 Identificador SPB do participante (direto ou indireto) que faz a requisição. |
<?xml version="1.0" encoding="UTF-8" ?> <GetOwnerStatisticsResponse> <Signature></Signature> <ResponseTime>2020-01-10T10:00:00.000Z</ResponseTime> <CorrelationId>a9f13566e19f5ca51329479a5bae60c5</CorrelationId> <OwnerStatistics> <TaxIdNumber>12345678901</TaxIdNumber> <LastUpdated>2020-01-17T10:00:00.000Z</LastUpdated> <Counters> <Counter type="SETTLEMENTS" d3="0" d30="20" m6="60"/> <Counter type="REPORTED_FRAUDS" d3="0" d30="10" m6="40"/> <Counter type="CONFIRMED_FRAUDS" d3="0" d30="5" m6="30"/> <Counter type="REJECTED" d3="0" d30="5" m6="30"/> </Counters> </OwnerStatistics> </GetOwnerStatisticsResponse>
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.
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.
PI-RequestingParticipant required | string^[0-9]{8}$ Example: 12345678 Identificador SPB do participante (direto ou indireto) que faz a requisição. |
<?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>
Obtém o estado atual do balde do participante para a política informada.
Policy required | string Example: ENTRIES_READ_PARTICIPANT_ANTISCAN |
PI-RequestingParticipant required | string^[0-9]{8}$ Example: 12345678 Identificador SPB do participante (direto ou indireto) que faz a requisição. |
<?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>