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 on-line.

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é-requisitos

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

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:

ScopeDescrição
card.createConcede acesso para emitir um novo cartão

Cabeçalhos (Headers)

NomeDescrição
api-versionObrigatório. Versão da API. Atualmente estamos na versão 1.0.
AuthorizationObrigatório. Token de autorização do tipo Bearer.
x-bkly-licenseIdentificador da licença bancária utilizada pelo parceiro. Observação: caso esse header não seja enviado, será considerada a licença do Bankly na requisição.

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:

NomeTipoDescriçãoEspecificação
documentNumberstringObrigatório. Número de documento (CPF ou CNPJ).Informe somente números. Máximo de 14 caracteres.
cardNamestringObrigatório. Nome que será impresso no cartão.Não é permitido o uso de números e caracteres especiais. Máximo de 19 caracteres.
aliasstringObrigatório. Apelido do cartão.Não é permitido o uso de caracteres especiais. Máximo de 16 caracteres.
bankAgencystringObrigatório. Número da agência.
bankAccountstringObrigatório. Número da conta ao qual o cartão será vinculado.
programIdstringObrigatório. Identificador do programa previamente definido.
passwordstringObrigatório. Senha do cartão. Importante: dependendo da configuração do programa, o envio deste campo pode ser opcional. Neste caso, a senha é gerada randomicamente.Preencha com apenas 4 dígitos. Exemplo: “4853”.
metadataobjectObjeto 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 a opção de senha randômica, é 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.

Opcionalmente, preencha:

NomeTipoDescriçãoEspecificação
addressobjectObjeto que deverá conter informações sobre o endereço do titular do cartão ao qual deve ser realizado a entrega.
address.zipCodestringObrigatório. Código postal do endereço.Informe somente números. O CEP deve ser nacional e conter oito dígitos.
address.addressstringObrigatório. Logradouro (nome da rua, avenida etc.).Máximo de 256 caracteres.
address.numberstringObrigatório. Número do imóvel.
address.neighborhoodstringObrigatório. Nome do bairro.Máximo de 256 caracteres.
address.complementstringComplemento do endereço.
address.citystringObrigatório. Nome da cidade.Máximo de 256 caracteres. Devem-se evitar acentos e outros caracteres especiais.
address.statestringObrigatório. Nome do estado.Formato ISO 3166-2:BR.
address.countrystringObrigatório. Nome do país.Formato ISO 3166-2:BR.
{
      "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"
      }
}
NomeTipoDescriçãoEspecificação
addressobjectObjeto que deverá conter informações sobre o endereço do titular do cartão ao qual deve ser realizado a entrega.
address.zipCodestringObrigatório. Código postal do endereço.
address.addressstringObrigatório. Logradouro (nome da rua, avenida etc.).Máximo de 256 caracteres.
address.numberstringObrigatório. Número do imóvel.
address.neighborhoodstringObrigatório. Nome do bairro.Máximo de 256 caracteres.
address.complementstringComplemento do endereço.
address.citystringObrigatório. Nome da cidade.Máximo de 256 caracteres. Devem-se evitar acentos e outros caracteres especiais.
address.statestringObrigatório. Nome do estado.Formato ISO 3166-2:BR.
address.countrystringObrigatório. Nome do país.Formato ISO 3166-2:BR.

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:

NomeTipoDescriçãoNúmero máximo de caracteres
proxystringCódigo identificador do cartão.31
activateCodestringCó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 CodeCódigoDescrição
400110O dia de pagamento não foi informado no programa.
400MAXIMUN_CARD_REACHEDA quantidade máxima de cartões virtuais emitidos para o período foi atingida.
401Sem autorização para realizar a solicitação.
401115O programa não pertence ao lote.
406013O cartão físico necessita de um endereço para entrega.
406101Requisição válida, porém, não foi aceita devido a alguma regra de negócio contratada.
406102Nenhum programa definido para a operação.
406202A conta não pertence ao cliente.
406203Conta inativa.
409012A requisição com os dados enviados já foi realizada e está em processamento.
409ANALYSIS_CREDIT_NOTFOUNDAnálise de crédito não encontrada para o documento e o programa informado.

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 eventoDescrição
CARD_WAS_ISSUEDO cartão foi emitido.

Copyright © 2021 Acesso Soluções de Pagamento S.A - Todos os direitos reservados