PIX - DICT

Nesta seção estão descritas as APIs que gerenciam o ciclo de vida do produto PIX - DICT de banking.

A rota da API para sandbox é: https://apigw-sandbox.zoop.ws/v2

As Funcionalidades de PIX estão liberadas em sandbox. Todos os endpoints citados abaixo são para fim de teste e documentação.

DICT

O Diretório de Identificadores de Contas Transacionais (DICT) é o componente do PIX que armazenará as informações das chaves ou apelidos que servem para identificar as contas transacionais dos usuários recebedores de maneira intuitiva e simplificada, permitindo que o usuário pagador utilize informações que ele já possui sobre o usuário recebedor para iniciar o pagamento.

post
Criar chave de endereçamento

https://api-beta.zoop.ws/v3/marketplaces/{marketplace_id}/banking/dict/holders/{holder_id}/accounts/{account_id}/entries
Request
Response
Request
Path Parameters
marketplace_id
required
string
Id do marketplace
holder_id
required
string
Id do holder
account_id
required
string
Id da conta
Body Parameters
type
required
string
Representa o tipo de chave de endereçamento. Campo enumerado com os valores: phone; email; evp; national_registration
value
optional
string
Representa o valor da chave de endereçamento. Seu formato e tamanho variam conforme o tipo escolhido anteriormente. Para phone a mascara é +9999999999999. Para email a mascara é xxxxxxxxxx@xxxxxxx.xx.xx com máximo de 77 caracteres. Para evp, não deve ser informado nenhum valor. Para national_registration, não deve ser informado nenhum valor.
Response
200: OK
A chave de endereçamento foi incluída com sucesso e está pronta para o uso.
{
"id":"29b0000cb501400ea6c3f21b24ef251c",
"status":"active",
"created_at":"2020-04-17 15:28:56.747Z",
"updated_at":"2020-04-17 15:28:56.747Z",
"key":{
"value":"33580667033",
"type":"national_registration"
},
"account":{
"id":"cf27477574e04d4584ac75ef6ca5ec3f",
"marketplace_id":"6c237bf9932840ccada92ac629a05d39",
"holder_id":"d83a1a81caa243d2a10bc414ae406bd3",
"owner":{
"name":"João da Silva",
"national_registration":"33580667033",
"type":"individual"
},
"routing_number":"001",
"number":"456123",
"type":"cacc"
},
"psp":{
"code":"3001155",
"name":"Zoop"
}
}
202: Accepted
Indica que a requisição de criação de chave foi recebida com sucesso, porém ela necessita de intervenção do usuário para sua conclusão ou não pode ser concluída imediatamente. Quando for necessária a intervenção do usuário, ela se dará dependendo do status da entry. 1- inclusion_scheduled : Indica que a solicitação de inclusão foi agendada para ser concluída em outro momento devido ao encerramento da janela de funcionamento do DICT. 2- waiting_ownership_verification : Indica que a chave necessita de uma verificação de propriedade. Chaves do tipo phone e email necessitam deste fluxo. 3- waiting_ownership_claiming : Indica que a chave necessita de um pedido de reivindicação de posse, pois ela já existe no DICT pertencendo a outro pessoa. 4- waiting_portability_claiming : Indica que a chave necessita de um pedido de portabilidade, pois ela já existe no DICT para a mesma pessoa em outro PSP.
{
"id":"29b0000cb501400ea6c3f21b24ef251c",
"status":"waiting_ownership_verification",
"created_at":"2020-04-17 15:28:56.747Z",
"updated_at":"2020-04-17 15:28:56.747Z",
"key":{
"value":"fulano@gmail.com",
"type":"email"
},
"account":{
"id":"cf27477574e04d4584ac75ef6ca5ec3f",
"marketplace_id":"6c237bf9932840ccada92ac629a05d39",
"holder_id":"d83a1a81caa243d2a10bc414ae406bd3",
"owner":{
"name":"João da Silva",
"national_registration":"33580667033",
"type":"individual"
},
"routing_number":"001",
"number":"456123",
"type":"cacc"
},
"psp":{
"code":"3001155",
"name":"Zoop"
}
}
400: Bad Request
Respostas geradas por passagem de parâmetro incorreto. A lista abaixo indica o motivo dos responses de exemplo: 1 - Campo obrigatório não informado 2 - Campo com o formato incorreto 3 - Campo com a quantidade de caracteres inválidos 4 - Campo obrigatório para chave de endereçamento do tipo phone ou email. 5 - Tipo de chave de endereçamento não permitido para o tipo de reinvindicação. 6 - Campo key value não deve ser informado para evp e national_registration
{
"code":1000,
"message": "Account Id is required"
}
{
"code":1001,
"message": "Key value is not a valid email format"
}
{
"code":1002,
"message": "Key of type phone must have 14 characters for its value"
}
{
"code":1003,
"message": "Key value is required for phone or email types"
}
{
"code":1004,
"message": "Key type is no compatible with claim type"
}
{
"code":1005,
"message": "Key value must not be informed for national_registration or evp types"
}
404: Not Found
Respostas geradas por parâmetros não encontrados pela API: 1 - Marketplace não encontrado 2 - Holder não encontrado 3 - Conta não encontrada 4 - Vinculo da chave de endereçamento não encontrada 5 - Claim não encontrada 6 - PSP não encontrado
{
"code":3000,
"message": "Marketplace not found"
}
{
"code":3001,
"message": "Holder not found"
}
{
"code":3002,
"message": "Account not found"
}
{
"code":3003,
"message": "Entry not found"
}
{
"code":3004,
"message": "Claim not found"
}
{
"code":3005,
"message": "PSP not found"
}
412: Precondition Failed
Respostas geradas por falhas em pré-condições não atendidas: 1 - Número máximo de entradas alcançados (5 para individual e 20 para business) 2 - Chave de endereçamento já existe para o entry, owner e conta digital 3 - Entry em estado que não permite a operação alvo 4 - Entry não possui um tipo de chave de endereçamento que não permite a operação de propriedade 5 - Código de confirmação de propriedade expirado para a entry alvo 6 - Claim em estado que não permita a operação alvo 7 - Papel do holder para a reinvindicação alvo não permite o tipo de operação solicitada 8 - Indica que já existe um PSP com o CNPJ informado
{
"code":4000,
"message": "Maximum entry count allowed reached"
}
{
"code":4001,
"message": "Entry already exists"
}
{
"code":4002,
"message": "Current entry status does not allow this operation"
}
{
"code":4003,
"message": "Target entry key type does not allow ownership confirmation"
}
{
"code":4004,
"message": "Ownership confirmation code is expired"
}
{
"code":4005,
"message": "Current claim status does not allow this operation"
}
{
"code":4006,
"message": "Claim holder role type does not allow the target operation"
}
{
"code":4007,
"message": "There is already a PSP with same national registration"
}
{
"value":"fulano@gmail.com",
"type":"EMAIL"
}

post
Confirmar propriedade de chave de endereçamento

https://api-beta.zoop.ws/v3/marketplaces/{marketplace_id}/banking/dict/holders/{holder_id}/accounts/{account_id}/entries/{entry_id}/ownership
Request
Response
Request
Path Parameters
marketplace_id
required
string
Id do marketplace
holder_id
required
string
Id do holder
account_id
required
string
Id da conta
entry_id
required
string
Id da chave de endereçamento
Body Parameters
code
required
string
Código de verificação de propriedade enviado para o usuário de acordo com o tipo de chave escolhido. Campo alfanumérico de 4 caracteres.
Response
200: OK
400: Bad Request
Respostas geradas por passagem de parâmetro incorreto. A lista abaixo indica o motivo dos responses de exemplo: 1 - Campo obrigatório não informado 2 - Campo com o formato incorreto 3 - Campo com a quantidade de caracteres inválidos
{
"code":1000,
"message": "Account Id is required"
}
{
"code":1001,
"message": "Key value is not a valid email format"
}
{
"code":1002,
"message": "Key of type phone must have 14 characters for its value"
}
404: Not Found
Respostas geradas por parâmetros não encontrados pela API: 1 - Marketplace não encontrado 2 - Holder não encontrado 3 - Conta não encontrada 4 - Vinculo da chave de endereçamento não encontrada
{
"code":3000,
"message": "Marketplace not found"
}
{
"code":3001,
"message": "Holder not found"
}
{
"code":3002,
"message": "Account not found"
}
{
"code":3003,
"message": "Entry not found"
}
412: Precondition Failed
Respostas geradas por falhas em pré-condições não atendidas: 1 - Entry em estado que não permite a operação alvo 2 - Entry não possui um tipo de chave de endereçamento que não permite a operação de propriedade 3 - Código de confirmação de propriedade expirado para a entry alvo
{
"code":4002,
"message": "Current entry status does not allow this operation"
}
{
"code":4003,
"message": "Target entry key type does not allow ownership confirmation"
}
{
"code":4004,
"message": "Ownership confirmation code is expired"
}
{
"code":"4040"
}

post
Reenvio de código de verificação de propriedade de chave de endereçamento

https://api-beta.zoop.ws/v3/marketplaces/{marketplace_id}/banking/dict/holders/{holder_id}/accounts/{account_id}/entries/{entry_id}/ownership/resend
Request
Response
Request
Path Parameters
marketplace_id
required
string
Id do marketplace
holder_id
required
string
Id do holder
account_id
required
string
Id da conta
entry_id
required
string
Id da chave de endereçamento
Response
200: OK
{
"message":"Ownership verification code recreated and sent successfully"
}
400: Bad Request
Respostas geradas por passagem de parâmetro incorreto. A lista abaixo indica o motivo dos responses de exemplo: 1 - Campo obrigatório não informado 2 - Campo com o formato incorreto
{
"code":1000,
"message": "Account Id is required"
}
{
"code":1001,
"message": "Key value is not a valid email format"
}
404: Not Found
Resposta geradas por parâmetros não encontrados pela API: 1 - Marketplace não encontrado 2 - Holder não encontrado 3 - Conta não encontrada 4 - Vinculo da chave de endereçamento não encontrado
{
"code":3000,
"message": "Marketplace not found"
}
{
"code":3001,
"message": "Holder not found"
}
{
"code":3002,
"message": "Account not found"
}
{
"code":3003,
"message": "Entry not found"
}
412: Precondition Failed
Respostas geradas por falhas em pré-condições não atendidas: 1 - Entry em estado que não permite a operação alvo 2 - Entry não possui um tipo de chave de endereçamento que não permite em a operação de propriedade
{
"code":4002,
"message": "Current entry status does not allow this operation"
}
{
"code":4003,
"message": "Target entry key type does not allow ownership confirmation"
}

get
Buscar vinculo com chave de endereçamento

https://api-beta.zoop.ws/v2/marketplaces/{marketplace_id}/banking/dict/holders/{holder_id}/accounts/{account_id}/entries/{entry_id}
Request
Response
Request
Path Parameters
marketplace_id
required
string
Id do marketplace
holder_id
required
string
Id do holder
account_id
required
string
Id da conta
entry_id
required
string
Id da chave de endereçamento
Response
200: OK
Vinculo com a chave de endereçamento encontrado.
400: Bad Request
Respostas geradas por passagem de parâmetro incorreto. A lista abaixo indica o motivo dos responses de exemplo: 1 - Campo obrigatório não informado 2 - Campo com o formato incorreto
{
"code":1000,
"message": "Account Id is required"
}
{
"code":1001,
"message": "Key value is not a valid email format"
}
404: Not Found
Resposta gerada por parâmetro não encontrado pela API: 1 - Vinculo com a chave de endereçamento não encontrado
{
"code":3003,
"message": "Entry not found"
}

get
Listar vínculos com chaves de endereçamento

https://api-beta.zoop.ws/v2/marketplaces/{marketplace_id}/banking/dict/holders/{holder_id}/accounts/{accounts_id}/entries
Request
Response
Request
Path Parameters
marketplace_id
required
string
Id do marketplace
holder_id
required
string
Id do holder
account_id
required
string
Id da conta
offset
optional
number
Indica o início da exibição dos registros retornados
size
optional
number
Quantidade de registros retornados por consulta. Máximo de 100 registros
Response
200: OK
Vínculos com chave de endereçamento listados
{
"items":[
{
"id":"29b0000cb501400ea6c3f21b24ef251c",
"status":"waiting_ownership_verification",
"created_at":"2020-04-17 15:28:56.747Z",
"updated_at":"2020-04-17 15:28:56.747Z",
"key":{
"value":"fulano@gmail.com",
"type":"email"
},
"account":{
"id":"cf27477574e04d4584ac75ef6ca5ec3f",
"marketplace_id":"6c237bf9932840ccada92ac629a05d39",
"holder_id":"d83a1a81caa243d2a10bc414ae406bd3",
"owner":{
"name":"João da Silva",
"national_registration":"33580667033",
"type":"individual"
},
"routing_number":"001",
"number":"456123",
"type":"cacc"
},
"psp":{
"code":"3001155",
"name":"Zoop"
}
}
],
"has_more":false,
"limit":1,
"total_pages":1,
"page":1,
"offset":0,
"total":"1",
"query_count":"1"
}
400: Bad Request
Respostas geradas por passagem de parâmetro incorreto. A lista abaixo indica o motivo dos responses de exemplo: 1 - Campo obrigatório não informado 2 - Campo com o formato incorreto
{
"code":1000,
"message": "Account Id is required"
}
{
"code":1001,
"message": "Key value is not a valid email format"
}

put
Alterar vínculo da chave de endereçamento

https://api-beta.zoop.ws/v3/marketplaces/{marketplace_id}/banking/dict/holders/{holder_id}/accounts/{account_id}/entries/{entry_id}
Request
Response
Request
Path Parameters
marketplace_id
required
string
Id do marketplace
holder_id
required
string
Id do holder
account_id
required
string
Id da conta
entry_id
required
string
Id da chave de endereçamento
Response
200: OK
A conta informada foi vinculada a chave de endereçamento alvo com sucesso. A conta antiga foi desvinculada no processo.
400: Bad Request
Respostas geradas por passagem de parâmetro incorreto. A lista abaixo indica o motivo dos responses de exemplo: 1 - Campo obrigatório não encontrado 2 - Campo com o formato
{
"code":1000,
"message": "Account Id is required"
}
{
"code":1001,
"message": "Key value is not a valid email format"
}
404: Not Found
Respostas geradas por parâmetros não encontrados pela API: 1 - Marketplace não encontrado 2 - Holder não encontrado 3 - Vinculo com a chave de endereçamento não encontrado
{
"code":3000,
"message": "Marketplace not found"
}
{
"code":3001,
"message": "Holder not found"
}
{
"code":3003,
"message": "Entry not found"
}
412: Precondition Failed
Resposta gerada por falhas em pré-condição não atendidas: 1 - Entry em estado que não permite a operação alvo
{
"code":4002,
"message": "Current entry status does not allow this operation"
}

delete
Excluir vínculo com chave de endereçamento

https://api-beta.zoop.ws/v3/marketplaces/{marketplace_id}/banking/dict/holders/{holder_id}/accounts/{account_id}/entries/{entry_id}
Request
Response
Request
Path Parameters
marketplace_id
required
string
Id do marketplace
holder_id
required
string
Id do holder
account_id
required
string
Id da conta
entry_id
optional
string
Id da chave de endereçamento
Response
200: OK
O vínculo entre a chave de endereçamento e a conta digital foi desfeito com sucesso.
{
"message":"Entry removed successfully"
}
202: Accepted
Indica que a solicitação foi aceita mas só será concluída em outro momento devido ao encerramento de funcionamento do DICT.
{
"message":"Entry removal scheduled successfully"
}
400: Bad Request
Respostas geradas por passagem de parâmetro incorreto. A lista abaixo indica o motivo dos responses de exemplo: 1 - Campo obrigatório não informado 2 - Campo com o formato incorreto
{
"code":1000,
"message": "Account Id is required"
}
{
"code":1001,
"message": "Key value is not a valid email format"
}
404: Not Found
Respostas geradas por parâmetros não encontrados pela API: 1 - Marketplace não encontrado 2 - Holder não encontrado 3 - Entry não encontrado
{
"code":3000,
"message": "Marketplace not found"
}
{
"code":3001,
"message": "Holder not found"
}
{
"code":3003,
"message": "Entry not found"
}
412: Precondition Failed
Resposta gerada por falhas em pré-condições não atendidas: 1 - Entry em estado que não permite a operação alvo
{
"code":4002,
"message": "Current entry status does not allow this operation"
}