Emissão de cartão virtual

stable pré pós

Este endpoint permite que o parceiro Bankly ofereça a seus clientes a possibilidade de adquirir um cartão virtual para ser utilizado em compras online.

Limite de emissão

Por padrão, o Bankly permite a emissão mensal de até cinco cartões virtuais por documento (CPF/CNPJ).
Caso seja necessário ajustar essa quantidade, o parceiro poderá entrar em contato com o time Bankly para definir um novo limite de emissão de cartões.

Pré-requisito

Para que seja possível utilizar este endpoint, é necessário que:

• O parceiro defina um programa para seus cartões;
• O cliente do parceiro possua uma conta ativa.

Requisição

Requisição HTTP

HTTP

POST https://api-mtls.sandbox.bankly.com.br/cards/virtual

cURL

--request POST \ 
--url 'https://api-mtls.sandbox.bankly.com.br/cards/virtual' \ 
--header 'Authorization: Bearer {{Token}}' \ 
--header 'accept: application/json' \ 
--header 'api-version: 1' \ 
--header 'content-type: application/json'
--data '{
       "documentNumber": "47742663023",  
       "cardName": "Nísia Floresta",  
       "alias": "Cartão principal",  
       "bankAgency": "0001",  
       "bankAccount": "15164",  
       "programId": "1234",  
       "password": "1234",  
       "address": {  
             "zipCode": "68060100",  
             "address": "Rua 6 de Março",  
             "number": "2500",  
             "neighborhood": "Alter do Chão",  
             "complement": "",  
             "city": "Santarém",  
             "state": "PA",  
             "country": "BR"  
       } 
}

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 a criação de um 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)

Não é necessário enviar parâmetros no path desta requisição.

Corpo da requisição (Body)

No body, envie os seguintes campos em formato JSON:

Nome	Tipo	Descrição	Especificação
documentNumber	string	Obrigatório. Número de documento de CPF ou CNPJ.	Informe somente os números.
cardName	string	Obrigatório. Nome que será impresso no cartão.	Não é permitido o uso de números e caracteres especiais e o tamanho máximo é de 19 caracteres.
alias	string	Obrigatório. Apelido do cartão.	Não é permitido o uso de caracteres especiais e o tamanho máximo é de 16 caracteres.
bankAgency	string	Obrigatório. Número da agência.	—
bankAccount	string	Obrigatório. Número da conta ao qual o cartão será vinculado.	—
programId	string	Obrigatório. Identificador do programa previamente definido.	—
password	string	Obrigatório. Senha do cartão.	Preencha com apenas 4 dígitos, como por exemplo: “4853”.

Opcionalmente, preencha:

Nome	Tipo	Descrição
address	object	Objeto que contém informações sobre o endereço do titular do cartão ao qual deve ser realizado a entrega.
address.zipCode	string	Código postal do endereço.
address.address	string	Logradouro (Nome da rua, avenida etc.).
address.number	string	Número do prédio ou da casa.
address.neighborhood	string	Nome do bairro.
address.complement	string	Complemento do endereço.
address.city	string	Nome da cidade.
address.state	string	Nome do estado.
address.country	string	Nome do país.

JSON

{   
       "documentNumber": "47742663023",  
       "cardName": "Nísia Floresta",  
       "alias": "Cartão principal",  
       "bankAgency": "0001",  
       "bankAccount": "15164",  
       "programId": "1234",  
       "password": "1234",  
       "address": {  
         "zipCode": "68060100",  
         "address": "Rua 6 de Março",  
         "number": "2500",  
         "neighborhood": "Alter do Chão",  
         "complement": "",  
         "city": "Santarém",  
         "state": "PA",  
         "country": "BR"  
       } 
} 

Resposta (Response)

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

JSON

{ 
  "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 não foi informado no programa.
401	---	No authorization to make the request	Sem autorização para realizar a solicitação.
401	115	Program does not belong to lot	O programa não pertence ao lote.
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!	Requisição válida, porém, não foi aceita devido a alguma regra de negócio contratada.
406	102	Program undefined!	Nenhum programa definido para a operação.
406	202	Account does not belong to the customer!	A conta não pertence ao cliente.
406	203	The account is inactive!	Conta inativa.
409	012	It is not possible to create new cards as it has reached the limit configured for this program	A requisição com os dados enviados já foi realizada e está em processamento.
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.
406	DUPLICATE_CARD_NAME	Card already exists for the given name	Nome já cadastrado para o CPF informado. Não é possível ter dois cartões ativos com o mesmo nome para o mesmo CPF.

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.