---
updatedAt: 2025-09-29T22:40:11.000Z
agentTools:
projectIndex: https://docs.bankly.com.br/llms.txt
---
# Emissão de cartão múltiplo
stable pré pós
Este *endpoint* permite que o parceiro Bankly ofereça a seus clientes a possibilidade de adquirir um [cartão múltiplo](https://docs.bankly.com.br/docs/definicoes).
> 📘 Nota
>
> Recordamos que o cartão múltiplo tem como principal característica a coexistência de dois números (um para pré-pago e outro para pós-pago e débito) no mesmo plástico. Porém, um dos números ficará inativo enquanto o outro estiver ativo.
## Pré-requisitos
Para que seja possível utilizar este *endpoint*, é necessário que:
* O parceiro defina um [programa](https://docs.bankly.com.br/docs/emissao-de-cartao) para seus cartões;
* O cliente do parceiro possua uma [conta ativa](https://docs.bankly.com.br/docs/gestao-de-conta-visao-geral).
## Requisição (Request)
### Requisição HTTP
```http
POST https://api-mtls.sandbox.bankly.com.br/cards/multiple
```
```curl
--request POST \
--url 'https://api-mtls.sandbox.bankly.com.br/cards/multiple' \
--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"
}
}'
```
### Autorização
Para garantir a segurança nas requisições, todos os *endpoints* do Bankly utilizam [*scopes*](https://docs.bankly.com.br/docs/scopes) como parte do seu [fluxo de autorização](https://docs.bankly.com.br/docs/fluxos-autorizacao).
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** | **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. |
| `x-bkly-license` | Identificador 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:
| Nome | Tipo | Descrição | Especificação |
| ---------------- | -------- | ----------------------------------------------------------------- | :-------------------------------------------------------------------------------- |
| `documentNumber` | `string` | **Obrigatório**. Número do documento do cliente (CPF ou CNPJ). | Informe somente números. |
| `cardName` | `string` | **Obrigatório**. Nome que será impresso no cartão. | Não é permitido o uso de números e caracteres especiais. Máximo de 19 caracteres. |
| `alias` | `string` | **Obrigatório**. Apelido do cartão. | Não é permitido o uso de caracteres especiais. 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. Exemplo: “4853”. |
Caso o cliente **não** tenha informado o endereço de entrega no momento do cadastro, preencha:
| Nome | Tipo | Descrição | Especificação |
| ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------- |
| `address` | `object` | Objeto que deverá conter informações sobre o endereço do titular do cartão ao qual deve ser realizado a entrega. | — |
| `address.zipCode` | `string` | **Obrigatório**. Código postal do endereço. | Informe somente números. O CEP deve ser nacional e conter oito dígitos. |
| `address.address` | `string` | **Obrigatório**. Logradouro (nome da rua, avenida etc.). | Máximo de 256 caracteres. |
| `address.number` | `string` | **Obrigatório**. Número do imóvel. | — |
| `address.neighborhood` | `string` | **Obrigatório**. Nome do bairro. | Máximo de 256 caracteres. |
| `address.complement` | `string` | Complemento do endereço. | — |
| `address.city` | `string` | **Obrigatório**. Nome da cidade. | Máximo de 256 caracteres. Devem-se evitar acentos e outros caracteres especiais. |
| `address.state` | `string` | **Obrigatório**. Nome do estado. | Formato ISO 3166-2:BR. |
| `address.country` | `string` | **Obrigató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.
```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 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:
| Nome | Tipo | Descrição | Número máximo de caracteres |
| -------------- | -------- | ---------------------------------------------------- | :-------------------------- |
| `proxy` | `string` | Código identificador do cartão. | 31 |
| `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](https://docs.bankly.com.br/reference/cartao-fisico-multiplo).
## Erros
Este *endpoint* pode retornar alguns erros específicos, conforme a tabela a seguir:
| Status Code | Código | Descrição |
| ----------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| 400 | 110 | O dia de pagamento não foi informado no programa. |
| 401 | — | Sem autorização para realizar a solicitação. |
| 401 | 115 | O programa não pertence ao lote. |
| 406 | 013 | O cartão físico necessita de um endereço para entrega. |
| 406 | 101 | Requisição válida, porém, não foi aceita devido a alguma regra de negócio contratada. |
| 406 | 102 | Nenhum programa definido para a operação. |
| 406 | 202 | A conta não pertence ao cliente. |
| 406 | 203 | Conta inativa. |
| 406 | DUPLICATE\_CARD\_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. |
| 409 | 012 | A requisição com os dados enviados já foi realizada e está em processamento. |
| 409 | ANALYSIS\_CREDIT\_NOTFOUND | 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](https://docs.bankly.com.br/docs/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](https://docs.bankly.com.br/docs/configuracao-webhooks). Os eventos são:
| Nome do evento | Descrição |
| ------------------------------------------------------------------------------------ | --------------------- |
| [`CARD_WAS_ISSUED`](https://docs.bankly.com.br/docs/eventos-cartoes#card_was_issued) | O cartão foi emitido. |