Emissão de cartão físico

stable pré pós

Este endpoint permite que o parceiro Bankly ofereça a seus clientes a possibilidade de adquirir um cartão físico.

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.

📘

Nota

Para realizar a emissão de cartões do tipo Panless, o parceiro deve obter a certificação Digital First.

Requisição (Request)

Requisição HTTP

POST https://api-mtls.sandbox.bankly.com.br/cards/physical
--request POST \ 
--url 'https://api-mtls.sandbox.bankly.com.br/cards/physical' \ 
--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.

Caso o cliente não tenha informado o endereço de entrega no momento do cadastro, 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.

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 objeto address seja preenchido mesmo que o cliente já tenha informado um endereço previamente.

{
      "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"
      }
}

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ódigoMensagemDescrição
400110Program does not have the informed payment day.O dia de pagamento não foi informado no programa.
401Sem autorização para realizar a solicitação.
401115Program does not belong to lot.O programa não pertence ao lote.
406013Delivery address must be informed when requesting the physical card.O cartão físico necessita de um endereço para entrega.
406101Program disable!Requisição válida, porém, não foi aceita devido a alguma regra de negócio contratada.
406102Program undefined!Nenhum programa definido para a operação.
406202Account does not belong to the customer!A conta não pertence ao cliente.
406203The account is inactive!Conta inativa.
406DUPLICATE_CARD_NAMECard already exists for the given name.Nome já cadastrado para o CPF informado. Não é possível ter dois cartões físicos ativos com o mesmo nome para o mesmo CPF.
409012It 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.
409ANALYSIS_CREDIT_NOTFOUNDCredit analysis not found for document and program informed.Aná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