Por proxy

Este endpoint possibilita que o cliente do parceiro Hiperbanco consulte os dados de um cartão pelo seu proxy.

Pré-requisito

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

O cliente do parceiro Hiperbanco possua um proxy de cartão emitido.

Requisição (Request)

Requisição HTTP

GET https://sandbox.hiperbanco.com.br/Cards/proxy{proxy}

--request GET 'https://sandbox.hiperbanco.com.br/Cards/proxy/{proxy}' \
--header 'version: cutting-edge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}'

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)

No path desta requisição envie os seguintes campos:

Nome	Tipo	Descrição	Especificação
`proxy`	`path`	Obrigatório. Código identificador do cartão.	Insira somente números, sem caracteres especiais.

Corpo da requisição (Body)

Não é necessário enviar campos no body desta requisição.

Resposta (Response)

O status code 200 indicará que a solicitação foi aceita com sucesso e trará um objeto contendo as informações do cartão.

Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:

**Alterar descrição dos campos ( em andamento) **

Campo	Tipo	Descrição
`created`	`string`	Data de criação do cartão, no formato ISO 8601 - UTC.
`companyKey`	`string`	Chave que identifica o parceiro dentro do Banco Liquidante.
`documentNumber`	`string`	Obsoleto. Utilize o campo holder.document.value.
`activateCode`	`string`	Código de ativação do cartão.
`trackingCode`	`string`	Código de rastreio do cartão. Campo retornado apenas para cartões físicos.
`holder`	`object`	Objeto que contém informações sobre o titular do cartão.
`holder.name`	`string`	Nome do titular do cartão.
`holder.document`	`object`	Objeto que contém informações sobre o documento do titular do cartão.
`holder.document.value`	`string`	Número do documento do cliente (11 ou 14 dígitos).
`holder.document.type`	`string`	Tipo do documento do cliente (CPF ou CNPJ).
`bankAgency`	`string`	Número da agência do cliente.
`bankAccount`	`string`	Número da conta do cliente.
`bank`	`object`	Informações sobre o banco emissor.
`bank.ispb`	`string`	Código ISPB do banco.
`bank.code`	`string`	Código do banco.
`bank.name`	`string`	Nome completo do banco.
`lastFourDigits`	`string`	Quatro últimos dígitos do cartão.
`proxy`	`string`	Código identificador do cartão.
`name`	`string`	Nome impresso no cartão.
`alias`	`string`	Apelido dado ao cartão.
`cardType`	`string`	Tipo do cartão, que pode ser "Physical" ou "Virtual".
`status`	`string`	Status atual do cartão.
`physicalBinds`	`array`	Lista de objetos contendo informações sobre os cartões físicos vinculados ao cartão virtual consultado. Essa lista somente será retornada caso o tipo de cartão (cardType) seja "Virtual".
`allowContactless`	`boolean`	Indica se é permitido pagamento por aproximação (true) ou não (false).
`address`	`object`	Objeto que contém informações sobre o endereço do titular do cartão.
`address.zipCode`	`string`	Código postal do endereço.
`address.address`	`string`	Logradouro (nome da rua, avenida etc.).
`address.number`	`string`	Número do imóvel.
`address.neighborhood`	`string`	Nome do bairro.
`address.complement`	`string`	Complemento do endereço.
`address.city`	`string`	Nome da cidade.
`address.state`	`string`	Nome do estado.
`address.country`	`string`	Nome do país.
`historyStatus`	`array`	Lista de objetos contendo o histórico de status do cartão desde sua criação.
`historyStatus.modified`	`string`	Data em que o status foi aplicado, no formato ISO 8601 - UTC.
`historyStatus.value`	`string`	Nome do status aplicado. Confira a tabela com os possíveis status reversíveis e irreversíveis na página Possíveis status do cartão.
`activatedAt`	`string`	Data da ativação do cartão, no formato ISO 8601 - UTC.
`lastUpdatedAt`	`string`	Data da última atualização do cartão, no formato ISO 8601 - UTC.
`isActivated`	`boolean`	Indica se o cartão está ativo.
`isAdditional`	`boolean`	Indica se o cartão é adicional.
`isLocked`	`boolean`	Indica se o cartão está bloqueado.
`isCanceled`	`boolean`	Indica se o cartão está cancelado.
`isBuilding`	`boolean`	Indica se o cartão está em construção.
`isvirtual`	`boolean`	Indica se o cartão é virtual.
`isPre`	`boolean`	Indica se o cartão é pré-pago.
`isPos`	`boolean`	Indica se o cartão é pós-pago.
`isDebit`	`boolean`	Indica se o cartão é de débito.
`paymentDay`	`number`	Dia do vencimento do pagamento.
`functionalities`	`array`	Lista de objetos contendo informações sobre as modalidades do cartão.
`functionalities.type`	`string`	Tipo de modalidade associada ao cartão, que pode ser “Debit", "Pos" ou "Pre".
`functionalities.program`	`object`	Objeto que contém informações sobre o programa ao qual a modalidade está vinculada.
`functionalities.program.programId`	`number`	Identificador do programa.
`functionalities.status`	`string`	Status da funcionalidade.
`wallets`	`array`	Lista de objetos contendo informações sobre a identificação das carteiras digitais às quais o cartão se encontra vinculado. Essa lista somente será retornada se o cartão estiver inserido em uma carteira digital.
`expirationDate`	`string`	Data de expiração do cartão.

{
    "created": "2025-04-30T13:11:29.568+00:00",
    "companyKey": "SDB2_HIPERBANCO",
    "documentNumber": "60216418000162",
    "activateCode": "AF1A6824F405",
    "trackingCode": "AF1A6824F405",
    "holder": {
        "name": "Pescarias SA",
        "document": {
            "value": "60216418000162",
            "type": "CNPJ"
        }
    },
    "bankAgency": "0001",
    "bankAccount": "1101263307",
    "bank": {
        "ispb": "13140088",
        "code": "332",
        "name": "ACESSO SOLUÇÕES DE PAGAMENTO S.A. - INSTITUIÇÃO DE PAGAMENTO"
    },
    "lastFourDigits": "3884",
    "proxy": "7912821000000948787",
    "name": "Testando CardS ",
    "alias": "testando",
    "cardType": "Virtual",
    "status": "Active",
    "physicalBinds": [],
    "allowContactless": true,
    "address": {
        "zipCode": "72236000",
        "address": "Quadra QNP 30 Conjunto F",
        "number": "12",
        "neighborhood": "Cajazeiras XI",
        "complement": "1 andar",
        "city": "Salvador",
        "state": "BA",
        "country": "BR"
    },
    "historyStatus": [
        {
            "modified": "2025-04-30T13:11:29.568+00:00",
            "value": "Building"
        },
        {
            "modified": "2025-04-30T13:11:39.162+00:00",
            "value": "Active"
        }
    ],
    "activatedAt": "2025-04-30T13:11:39.162+00:00",
    "lastUpdatedAt": "2025-04-30T13:11:39.162+00:00",
    "isActivated": true,
    "isAdditional": false,
    "isLocked": false,
    "isCanceled": false,
    "isBuilding": false,
    "isFirtual": false,
    "isPre": true,
    "isPos": false,
    "isDebit": false,
    "paymentDay": 1,
    "functionalities": [
        {
            "type": "Pre",
            "program": {
                "programId": 880
            },
            "status": "Enabled"
        }
    ],
    "wallets": [],
    "expirationDate": "2030-04-30T00:00:00"
}

{
    "created": "2025-10-14T01:06:32.942+00:00",
    "companyKey": "SDB2_HIPERBANCO",
    "documentNumber": "84329329174008",
    "activateCode": "D9390F9D56C2",
    "trackingCode": "29020UHVVJXQ",
    "holder": {
        "name": "Global Labs LTDA",
        "document": {
            "value": "84329329174008",
            "type": "CNPJ"
        }
    },
    "bankAgency": "0001",
    "bankAccount": "1105139953",
    "bank": {
        "ispb": "13140088",
        "code": "332",
        "name": "ACESSO SOLUÇÕES DE PAGAMENTO S.A. - INSTITUIÇÃO DE PAGAMENTO"
    },
    "lastFourDigits": "4179",
    "proxy": "5125911000000445331",
    "name": "Testando Card",
    "alias": "testando",
    "cardType": "Physical",
    "status": "InTransitLocked",
    "physicalBinds": [],
    "allowContactless": true,
    "address": {
        "zipCode": "72236000",
        "address": "Quadra QNP 30 Conjunto F",
        "number": "6",
        "neighborhood": "Algum Lugar",
        "complement": "aqui",
        "city": "Salvador",
        "state": "BA",
        "country": "BR"
    },
    "historyStatus": [
        {
            "modified": "2025-10-14T01:06:32.942+00:00",
            "value": "Building"
        },
        {
            "modified": "2025-10-14T01:06:48.31+00:00",
            "value": "InTransitLocked"
        }
    ],
    "lastUpdatedAt": "2025-10-14T01:06:48.31+00:00",
    "isActivated": false,
    "isAdditional": false,
    "isLocked": true,
    "isCanceled": false,
    "isBuilding": false,
    "isFirtual": false,
    "isPre": true,
    "isPos": false,
    "isDebit": false,
    "paymentDay": 1,
    "functionalities": [
        {
            "type": "Pre",
            "program": {
                "programId": 881
            },
            "status": "Enabled"
        }
    ],
    "wallets": [],
    "expirationDate": "2030-10-31T00:00:00"
}

Erros

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

Status Code	Código	Mensagem	Descrição
`404`	`CARD_NOT_FOUND`	Card Not Found	Cartão não encontrado.

Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints que acompanham os erros 400 (se houver).

Eventos

Este endpoint não possui eventos relacionados a ele.