Emissão de segunda via
stable pré pós
Este endpoint permite que o parceiro Bankly ofereça a seus clientes a possibilidade de emitir uma segunda via do cartão físico ou virtual, caso seja atrelado a um físico, com as mesmas características da primeira via.
Importante
A primeira via do cartão físico será cancelada automaticamente após a emissão da segunda via.
Requisição (Request)
Requisição HTTP
POST https://api-mtls.sandbox.bankly.com.br/cards/{proxy}/duplicate
--request POST \
--url 'https://api-mtls.sandbox.bankly.com.br/cards/{proxy}/duplicate' \
--header 'Authorization: Bearer {{Token}}' \
--header 'accept: application/json' \
--header 'api-version: 1.0' \
--header 'content-type: application/json'
--data '{
"status": "CardWasStolen",
"documentNumber": "47742663023",
"password": "1234",
"resetPassword": true,
"description": "Lorem ipsum",
"address": {
"zipCode": "68060100",
"address": "Rua 6 de Março",
"number": "2500",
"neighborhood": "Alter do Chão",
"complement": "",
"city": "Santarém",
"state": "PA",
"country": "BR"
},
"metadata":{
"updatedAt": "2022-12-30T01:11:07.4019873Z",
"versao": "1.0"
}
}'
Autorização
Para garantir a segurança nas requisições, todos os endpoints do Bankly utilizam scopes como parte do seu fluxo de autorização.
Esta requisição requer o scope descrito a seguir:
Scope | Descrição |
---|---|
card.create | Concede acesso para emitir um novo cartão. |
Cabeçalhos (Headers)
Nome | Descrição |
---|---|
api-version | Obrigatório. Versão da API. Atualmente estamos na versão 1.0. |
Authorization | Obrigatório. Token de autorização do tipo Bearer. |
Parâmetros da rota (Path)
No path desta requisição, envie os seguintes campos:
Nome | Tipo | Descrição |
---|---|---|
proxy | path | Obrigatório. Código identificador do cartão. |
Corpo da requisição (Body)
No body, envie os seguintes campos em formato JSON:
Nome | Tipo | Descrição | Especificação |
---|---|---|---|
status | string | Obrigatório. Motivo da solicitação de segunda via. | — |
documentNumber | string | Obrigatório. Número de documento de CPF ou CNPJ. | Informe somente os números. |
password | string | Obrigatório. Senha do cartão atual (primeira via) para realizar transações. Importante: este campo pode ser opcional caso o parâmetro que remove essa obrigatoriedade esteja habilitado no programa. | Preencha com apenas 4 dígitos, como por exemplo: “4853”. |
resetPassword | boolean | Indica se o sistema deve gerar uma nova senha aleatória para o cartão durante a solicitação de segunda via (true) ou se deve manter a senha atual (false). Importante: caso este campo não seja preenchido, será adotado o valor padrão false. | — |
description | string | Obrigatório. Detalhes do cancelamento com qualquer informação considerada como relevante. | — |
metadata | object | Objeto que deverá conter informações adicionais pertinentes ao contexto, representadas por meio de pares de chave e valor. | — |
Nota
Para que o parceiro possa utilizar o campo
resetPassword
, é necessário que seja feita uma avaliação pelo time de segurança do Bankly e que o usuário tenha acesso à senha, seja pelo kit enviado, seja pelo endpoint de consulta de senhas.
Caso o cliente não possua um endereço cadastrado, preencha:
Nome | Tipo | Descrição |
---|---|---|
address | object | Objeto que deverá conter informações sobre o endereço do titular do cartão onde deve ser realizada a entrega. |
address.zipCode | string | Obrigatório. Código postal do endereço. |
address.address | string | Obrigatório. Logradouro (nome da rua, avenida etc.). |
address.number | string | Obrigatório. Número do imóvel. |
address.neighborhood | string | Obrigatório. Nome do bairro. |
address.complement | string | Complemento do endereço. |
address.city | string | Obrigatório. Nome da cidade. |
address.state | string | Obrigatório. Nome do estado. |
address.country | string | Obrigatório. Nome do país. |
Entretanto, caso o cliente já possua um endereço cadastrado, o preenchimento do campo address
é opcional.
Atenção
Para evitar problemas na entrega devido à desatualização do endereço cadastrado, recomendamos que o campo
address
seja preenchido mesmo que o cliente já tenha informado um endereço previamente.
{
"status": "CardWasStolen",
"documentNumber": "47742663023",
"password": "1234",
"resetPassword": true,
"description": "Lorem ipsum",
"address": {
"zipCode": "68060100",
"address": "Rua 6 de Março",
"number": "2500",
"neighborhood": "Alter do Chão",
"complement": "",
"city": "Santarém",
"state": "PA",
"country": "BR"
},
"metadata":{
"updatedAt": "2022-12-30T01:11:07.4019873Z",
"versao": "1.0"
}
}
Motivos de solicitação de segunda via do cartão
Após realizar a requisição, o status do cartão antigo será atualizado de acordo com o motivo informado no campo status
descrito acima. Os valores correspondentes podem ser visualizados na tabela abaixo:
Motivo | Descrição | Status que o cartão antigo passará a ter |
---|---|---|
"LostMyCard" | Perda de cartão. | LostOrTheftCanceled |
"CardWasStolen" | Cartão roubado. | LostOrTheftCanceled |
"CardWasDamaged" | Cartão danificado. | LostOrTheftCanceled |
"CardNotDelivered" | Cartão não entregue. | StrayedCanceled |
"UnrecognizedOnlinePurchase" | Cartão não solicitado. | UnrecognizedOnlinePurchase |
Resposta (Response)
Os status code 202 indica que a solicitação foi aceita e o cartão está sendo criado.
Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:
Nome | Tipo | Descrição |
---|---|---|
proxy | string | Código identificador do cartão. |
activateCode | string | Código atrelado ao cartão no momento de sua emissão. |
{
"proxy": "2370021007715002820",
"activateCode": "A0DDDC0951D1"
}
Dica
Para simular uma requisição nesse endpoint, acesse o API Reference.
Erros
Este endpoint pode retornar alguns erros específicos, conforme a tabela a seguir:
Status Code | Código | Mensagem | Descrição |
---|---|---|---|
400 | 110 | Program does not have the informed payment day | O dia de pagamento informado é diferente dos possíveis dias de pagamento cadastrados no programa. |
400 | WRONG_PASSWORD_ATTEMPT_LOCKED | Wrong Password Attempt Locked | Tentativa de senha errada bloqueada. |
400 | DUPLICATE_CARD_AWAIT_BUILDING | Duplicate Card Await Building | A segunda via do cartão está em construção. |
400 | GET_BANKLYTOKEN_ERROR | Error while getting Bankly's token | Erro ao obter o token do Bankly. |
401 | — | No authorization to make the request | Sem autorização para realizar a solicitação. |
406 | 008 | Card does not belong to this customer! | O cartão informado não pertence a este documento. |
406 | 011 | Invalid password! | Senha inválida. |
406 | 013 | Delivery address must be informed when requesting the physical card | O cartão físico necessita de um endereço para entrega. |
406 | 101 | Program disable! | O programa informado na criação do cartão está desabilitado. |
406 | 102 | Program undefined! | O programa não existe para esta companyKey . |
406 | 202 | Account does not belong to the customer! | O número de documento (documentNumber ) informado na requisição está incorreto. |
406 | 203 | The account is inactive! | Conta inativa. |
406 | DUPLICATE_CARD_NAME | Card already exists for the given name | Já existe um cartão com o mesmo nome cadastrado. Não é possível ter dois cartões físicos ativos com o mesmo nome para o mesmo CPF. |
409 | 012 | It is not possible to create new cards as it has reached the limit configured for this program | O limite configurável no programa para emissões de cartões por documento foi atingido. |
409 | ANALYSIS_CREDIT_NOTFOUND | Credit analysis not found for document and program informed | Análise de crédito não encontrada para o documento e o programa informado. |
409 | 024 | No duplicate for canceled card | Não é possível gerar uma segunda via de um cartão cancelado. |
409 | 025 | No duplicate for card under construction | Não é possível gerar uma segunda via de um cartão em construção. |
503 | 302 | Client is unavailable | O cliente não está disponível. |
Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints. Portanto, recomendamos a consulta da documentação de erros, onde é possível encontrar as mensagens comuns em inglês que acompanham os erros 400 (se houver).
Eventos
Caso o parceiro deseje receber mensagens referentes aos eventos relacionados a esse endpoint, é preciso configurar o webhook. Os eventos são:
Nome do evento | Descrição |
---|---|
CARD_WAS_ISSUED | O cartão foi emitido. |
Updated about 1 month ago