Emissão de cartão virtual

Emite um cartão virtual para o cliente do parceiro usar em compras on-line.

Limite de emissão

Por padrão, o Bankly permite emitir até 5 cartões virtuais por mês por documento (CPF/CNPJ). Para ajustar esse limite, fale com o time Bankly.

Autenticação

Scope	Descrição
`card.create`	Concede acesso para emitir um novo cartão.

Pré-requisitos

O parceiro deve ter um programa definido para os cartões.

📘
Nota
A vinculação de uma conta não é obrigatória para a emissão de um cartão virtual. Caso os campos bankAgency e bankAccount não sejam informados em cartões combo, apenas a modalidade crédito será habilitada.

Requisição (Request)

Requisição HTTP

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

--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 'x-bkly-license: f64197e4-80b3-4820-bfae-1419049b15b5'\
--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"  
      },
      "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	Obrigatório	Descrição
`api-version`	Sim	Versão da API. Atualmente, `1.0`.
`Authorization`	Sim	Token Bearer.
`x-bkly-license`	Não	Identificador da licença bancária do parceiro. Se omitido, usa-se a licença do Bankly.

Parâmetros da rota (Path)

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

Corpo da requisição (Body)

Campo	Tipo	Obrigatório	Descrição
`documentNumber`	string	Sim	CPF ou CNPJ (só números, até 14 caracteres).
`cardName`	string	Sim	Nome impresso no cartão (sem números/caracteres especiais, até 19 caracteres).
`alias`	string	Sim	Apelido do cartão (sem caracteres especiais, até 16 caracteres).
`programId`	string	Sim	Identificador do programa previamente definido.
`password`	string	Condicional	Senha de 4 dígitos. Pode ser opcional conforme o programa (gerada aleatoriamente nesse caso).
`bankAgency`	string	Não	Agência. Em cartões combo, se omitido, só a modalidade crédito é habilitada.
`bankAccount`	string	Não	Conta vinculada. Em cartões combo, se omitido, só a modalidade crédito é habilitada.
`address`	object	Não	Endereço do titular (`zipCode`, `address`, `number`, `neighborhood`, `city`, `state`, `country`).
`metadata`	object	Não	Pares chave/valor com informações adicionais.

📘
Nota
Para usar senha aleatória, é necessária avaliação do time de segurança do Bankly, e o cliente deve conseguir acessar a senha (pelo kit ou pela consulta de senha).

Os campos do objeto address tornam-se obrigatórios quando o objeto address é informado na requisição. Opcionalmente, preencha:

Campo	Tipo	Obrigatório	Descrição
`address`	string	Não	Logradouro (rua, avenida etc.), até 256 caracteres.
`zipCode`	string	Sim*	CEP com 8 dígitos, informando apenas números.
`number`	string	Sim*	Número do imóvel.
`neighborhood`	string	Sim*	Bairro, até 256 caracteres.
`complement`	string	Não	Complemento do endereço.
`city`	string	Sim*	Cidade, até 256 caracteres. Evite acentos e caracteres especiais.
`state`	string	Sim*	Estado no formato ISO 3166-2:BR (ex.: `SP`, `RJ`).
`country`	string	Sim*	País no formato ISO 3166-2:BR (ex.: `BR`).

{
  "documentNumber": "47742663023",
  "cardName": "Nisia Floresta",
  "alias": "Cartao principal",
  "programId": "1234",
  "password": "1234",
  "address": {
    "zipCode": "68060100", 
    "address": "Rua 6 de Marco",
    "number": "2500",
    "neighborhood": "Alter do Chao",
    "complement": "",
    "city": "Santarem",
    "state": "PA", 
    "country": "BR"
  },
  "metadata": { "updatedAt": "2022-12-30T01:11:07.401Z", "versao": "1.0" }
}

Resposta

Status: 202 Accepted — solicitação aceita; o cartão está sendo criado.

Campo	Tipo	Descrição
`proxy`	string	Código identificador do cartão (até 31 caracteres).
`activateCode`	string	Código atrelado ao cartão no momento da emissão.

{ "proxy": "2370021007715002820", "activateCode": "A0DDDC0951D1" }

👍
Dica
Para simular uma requisição nesse endpoint, acesse o API Reference.

Erros

Além dos erros comuns a todos os endpoints:

Status	Código	Descrição
400	`MAXIMUN_CARD_REACHED`	Quantidade máxima de cartões virtuais do período atingida.
400	`110`	O dia de pagamento não foi informado no programa.
401	`115`	O programa não pertence ao lote.
406	`101`	Requisição válida, mas barrada por regra de negócio contratada.
406	`102`	Nenhum programa definido para a operação.
409	`012`	Requisição com os mesmos dados já está em processamento.
409	`ANALYSIS_CREDIT_NOTFOUND`	Análise de crédito não encontrada para o documento e o programa.

Eventos

Configure os webhooks para receber:

Evento	Descrição
`CARD_WAS_ISSUED`	O cartão foi emitido.

Limite de emissão

Autenticação

Pré-requisitos

Nota

Requisição (Request)

Requisição HTTP

Autorização

Cabeçalhos (Headers)

Parâmetros da rota (Path)

Corpo da requisição (Body)

Nota

Resposta

Dica

Erros

Eventos

Artigos relacionados