Criação de cartão Físico / Virtual

Este endpoint permite que o parceiro Hiperbanco 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.

Requisição (Request)

Requisição HTTP

POST https://sandbox.hiperbanco.com.br/Cards/create/[typeCard}

--request POST 'https://sandbox.hiperbanco.com.br/Cards/create/Physical' \
--header 'version: cutting-edge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' \
--data-raw '{
  "documentNumber": "11122233344",
  "cardName": "Testando Card",
  "alias": "testando",
  "bankAgency": "0001",
  "bankAccount": "00012345",
  "programId": 111,
  "password": "1111",
  "address": {
    "address": "Av. Sete de Setembro",
    "zipCode": "40060000",
    "city": "Salvador",
    "state": "BA",
    "country": "BR",
    "neighborhood": "Campo Grande",
    "number": "100",
    "complement": "Apto 101"
  }
}'

--request POST 'https://sandbox.hiperbanco.com.br/Cards/create/Virtual' \
--header 'version: cutting-edge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' \
--data-raw '{
  "documentNumber": "12345678909",
  "cardName": "Netflix",
  "alias": "Netflix 01",
  "bankAgency": "0001",
  "bankAccount": "123456",
  "programId": 111,
  "password": "1111"
}'

Cabeçalhos (Headers)

Nome	Propriedade	Descrição
`version`	`cutting-edge`	Obrigatório. Essa propriedade garante que o response da API seja retornado no formato JSON
`Authorization`	`Bearer token`	Obrigatório. Token de autorização do tipo Bearer.

Parâmetros da rota (Path)

Nome	Tipo	Descrição	Especificação
`typeCard`	path	Obrigatório. Tipo do cartão	Os cartões podem ser do tipo Virtual (para a emissão de cartão virtual) ou Physical (para a emissão de cartão físico).

Corpo da requisição (Body)

No body, envie os seguintes campos em formato JSON:

Campo	Tipo	Descrição	Especificação
`documentNumber`	`string`	Obrigatório. Número do documento do titular.	Informe somente números. Máximo de 14 caracteres.
`cardName`	`string`	Obrigatório. Nome impresso no cartão.	Não é permitido o uso de números e caracteres especiais. Máximo de 19 caracteres.
`alias`	`string`	Obrigatório. Nome de identificação 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 bancária.	—
`programId`	`number`	Obrigatório. Identificador do programa previamente definido.	—
`password`	`string`	Obrigatório. Senha do cartão.	Preencha com apenas 4 dígitos. Exemplo: “4853”.
`address`	`object`	Objeto que deverá conter informações sobre o endereço do titular do cartão ao qual deve ser realizado a entrega.	Máximo de 255 caracteres.
`address.address`	`string`	Logradouro (nome da rua, avenida etc.).	Máximo de 255 caracteres.
`address.zipCode`	`string`	Código postal do endereço.	Informe somente números. O CEP deve ser nacional e conter oito dígitos.
`address.city`	`string`	Nome da cidade.	Máximo de 255 caracteres. Devem-se evitar acentos e outros caracteres especiais.
`address.state`	`string`	Nome do estado.	Formato ISO 3166-2:BR.
`address.country`	`string`	País.	Formato ISO 3166-2:BR.
`address.neighborhood`	`string`	Bairro.	Máximo de 255 caracteres.
`address.number`	`string`	Número do endereço.
`address.complement`	`string`	Complemento do endereço.	Máximo de 255 caracteres.

⚠️
Importante
O objeto address é obrigatório na emissão de cartões físicos, pois representa o endereço de entrega do cartão.

{
  "documentNumber": "12345678909",
  "cardName": "Netflix",
  "alias": "Netflix 01",
  "bankAgency": "0001",
  "bankAccount": "123456",
  "programId": 111,
  "password": "1111"
}

{
  "documentNumber": "11122233344",
  "cardName": "Testando Card",
  "alias": "testando",
  "bankAgency": "0001",
  "bankAccount": "00012345",
  "programId": 111,
  "password": "1111",
  "address": {
    "address": "Av. Sete de Setembro",
    "zipCode": "40060000",
    "city": "Salvador",
    "state": "BA",
    "country": "BR",
    "neighborhood": "Campo Grande",
    "number": "100",
    "complement": "Apto 101"
  }
}

Resposta (Response)

Os status code 200 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:

Cartão Virtual

Nome	Tipo	Descrição
`proxy`	`string`	Código identificador do cartão.
`activateCode`	`string`	Código atrelado ao cartão no momento de sua emissão.

{
    "proxy": "7912821000000718668",
    "activateCode": "C96024295843"
}

Cartão Físico

Nome	Tipo	Descrição
`data`	`string`	Mensagem informando que o cartão foi enviado para análise.

{
    "data": "Card sent for analysis."
}

Erros

Este endpoint pode retornar alguns erros específicos, conforme a tabela a seguir:

Status Code	Código	Mensagem	Descrição
`401`	`PROGRAM_NOT_IN_LOT`	Program does not belong to lot.	O programa não pertence ao lote.
`406`	`DELIVERY_ADDRESS_REQUIRED_FOR_PHYSICAL_CARD`	Delivery address must be informed when requesting the physical card.	O cartão físico necessita de um endereço para entrega.
`406`	`PROGRAM_DISABLED`	Program disable!	Requisição válida, porém, não foi aceita devido a alguma regra de negócio contratada.
`406`	`PROGRAM_UNDEFINED`	Program undefined!	Nenhum programa definido para a operação.
`406`	`ACCOUNT_NOT_OWNED_BY_CUSTOMER`	Account does not belong to the customer!	A conta não pertence ao cliente.
`406`	`ACCOUNT_INACTIVE`	The account is inactive!	Conta inativa.
`406`	`DUPLICATE_CARD_NAME`	Card 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.
`409`	`CARD_LIMIT_REACHED_FOR_PROGRAM`	It 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.
`422`	`ACCOUNT_ALREADY_HAS_PHYSICAL_CARD`	The account already has an active physical card or it is to be approved.	A conta já possui um cartão físico ativo ou está pendente de aprovação.
`404`	`ONBOARDING_NOT_FOUND`	Onboarding not found searching by number and branch	Onboarding não encontrado.
`404`	`ACCOUNT_NOT_FOUND`	Account not found searching by number and branch	Conta não encontrada.

Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints 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 evento	Descrição
`CARD_WAS_ISSUED`	O cartão foi emitido.