Emissão de cartão adicional

Este endpoint permite que o parceiro Bankly ofereça a seus clientes a possibilidade de solicitar um cartão adicional.

📘

Nota

Todo cartão adicional será do tipo pós-pago, mesmo quando vinculado a um cartão titular do tipo Combo.

👍

Dica

As regras específicas relacionadas à ativação, alteração de status e operações não permitidas para cartões adicionais estão documentadas em uma página dedicada. Consulte Gestão de cartão Adicional para mais detalhes.

Pré-requisitos

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

• O cartão titular seja do tipo pós-pago, incluindo cartão combo com a modalidade pós ativa;
• O cartão titular seja físico; cartões virtuais não são compatíveis;
• O programa vinculado ao cartão titular esteja devidamente configurado.

🚧

Importante

Para realizar a configuração do programa do cartão, o parceiro deve procurar o time de Operações da Bankly.

Requisição (Request)

Requisição HTTP

POST https://api-mtls.sandbox.bankly.com.br/cards-pci/{{proxy}}/additional

--request POST \ 
--url 'https://api-mtls.sandbox.bankly.com.br/cards-pci/{{proxy}}/additional' \ 
--header 'accept: application/json' \ 
--header 'content-type: application/json'\
--header 'Authorization: Bearer {{Token}}'\ 
--header 'api-version: 1' \
--header 'x-correlation-id: {{GUID}}' \
--data '{ 
      "cardName": "Marco M Sandbox",
      "alias": "Marco Sandbox",
      "password": "{{senha criptografada}}",
      "additional": {
          "holder": {
              "name": "Marco Minas Sandbox",
              "document": {
                  "value": "{{número do documento}}",
                  "type": "{{tipo do documento}}" //CPF ou CNPJ
              }
          }
      },
      "holder": {
          "document": {
              "value": "{{número do documento}}",
              "type": "{{tipo do documento}}" //CPF ou CNPJ
          },
          "password": "{{senha criptografada}}"
      },
      "address": {
          "zipCode": "03276010",
          "address": "Rua Correia da Camara",
          "number": "452",
          "complement": "Apto 801",
          "neighborhood": "Vila Tolstoi",
          "city": "São Paulo",
          "state": "SP",
          "country": "BR"
      },
      "metadata": {
    			"metadataProp1": "string",
   				"metadataProp2": "string"
      }
}'

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:

Cabeçalhos (Headers)

Parâmetros da rota (Path)

Corpo da requisição (Body)

No body, envie os seguintes campos em formato JSON:

🚧

Importante

Para que o parceiro possa utilizar a opção de senha randômica, é necessário:

• Avaliação prévia pelo time de Segurança da Informação da Bankly.
• Que o usuário tenha acesso à senha, seja pelo kit enviado ou pelo endpoint de consulta de senhas.

O objeto address é opcional.

• Se não for informado, o endereço de entrega do cartão adicional será o mesmo do titular do cartão.
• Se informado, é necessário preencher os campos obrigatórios conforme indicado na tabela a seguir:

❗️

Atenção

Para evitar problemas de entrega devido ao endereço cadastrado do titular desatualizado, recomendamos que o objeto address seja devidamente preenchido.

{
    "cardName": "Marco M Sandbox",
    "alias": "Marco Sandbox",
    "password": "TiCEhKL8h7y88...",
    "additional": {
        "holder": {
            "name": "Marco Minas Sandbox",
            "document": {
                "value": "00000000000",
                "type": "CPF"
            }
        }
    },
    "holder": {
        "document": {
            "value": "11111111111",
            "type": "CPF"
        },
        "password": "AiHJpKM2w4w31..."
    },
    "address": {
        "zipCode": "03276010",
        "address": "Rua Correia da Camara",
        "number": "452",
        "complement": "Apto 801",
        "neighborhood": "Vila Tolstoi",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR"
    },
    "metadata": {
        "metadataProp1": "2025-10-01T1224:07.4019873Z",
        "metadataProp2": "1.0"
    }
}

🚧

Importante

Além dos campos descritos acima, o parceiro pode enviar o objeto embossing e suas propriedades. Mais detalhes na documentação Embossing.

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:

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

Informamos 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: