Manual do Dev
InstitucionalBlogService DeskStatus Page

Por PAN

stable pré pós

Este endpoint possibilita que parceiro Bankly consulte os dados de um cartão pelo seu Primary Account Number (PAN) com segurança garantida por comunicação criptografada.

📘

Nota

Para aumentar o nível de segurança da informação, o uso deste serviço é restrito a parceiros previamente homologados pelo time de Segurança da Bankly.

Pré-requisitos

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

  • Durante o desenvolvimento do projeto, o parceiro solicite autorização ao time de Segurança da Bankly para realizar o processo de homologação técnica;
  • Após aprovação e alinhamento prévio com os times de Cartões e Segurança, o parceiro obtenha o certificado de criptografia necessário;
  • O parceiro Bankly possua um PAN de cartão emitido.

🚧

Importante

Esteja atento à data de expiração do certificado de criptografia, para renovações futuras.

Requisição (Request)

Requisição HTTP

POST https://api-mtls.sandbox.bankly.com.br/cards-pci/pan

     --request POST \
     --url https://api-mtls.sandbox.bankly.com.br/cards-pci/pan \
     --header 'Authorization: Bearer {Token}' \
     --header 'accept: application/json' \
     --header 'x-correlation-id: {{GUID}}' \
     --header 'api-version: 1.0' \
     --header 'content-type: application/json' \
     --data '{
          "pan": "TiCEhKL8h7y88y1zhfxs2gnivGlB2Fx/pTlXpv0QtP675ck52uekv71FNl..."
      }'

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.pci.readConcede acesso para consultar dados PCI de um 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.

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 o seguinte campo em formato JSON:

NomeTipoDescriçãoEspecificação
panstringObrigatório. Número (PAN) do cartão.O pan deve ser válido e transmitido criptografado em formato base64. Exemplo: "TiCEhKL8h7y88y1zhfxs2gnivGlB2Fx/pTlXpv0QtP675..."

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:

NomeTipoDescrição
createdstringData de criação do cartão, no formato ISO 8601 - UTC.
companyKeystringChave que identifica o parceiro dentro do Bankly.
holderobjectObjeto que contém informações sobre o titular do cartão.
holder.namestringNome do titular do cartão.
holder.documentobjectObjeto que contém informações sobre o documento do titular do cartão.
holder.document.valuestringNúmero do documento do cliente (11 ou 14 dígitos).
holder.document.typestringTipo do documento do cliente (CPF ou CNPJ).
documentNumberstringObsoleto. Utilize o campo holder.document.value.
activateCodestringCódigo de ativação do cartão.
trackingCodestringCódigo de rastreio do cartão. Campo retornado apenas para cartões físicos.
bankAgencystringNúmero da agência do cliente.
bankAccountstringNúmero da conta do cliente.
lastFourDigitsstringQuatro últimos dígitos do cartão.
proxystringCódigo identificador do cartão.
namestringNome impresso no cartão.
aliasstringApelido dado ao cartão.
cardTypestringTipo do cartão, que pode ser "Physical" ou "Virtual".
statusstringStatus do cartão. Confira a tabela com os possíveis status reversíveis e irreversíveis na página Possíveis status do cartão.
physicalBinds[]array of objectsLista 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".
physicalBinds[].proxystringCódigo identificador do cartão físico.
physicalBinds[].createdstringData de criação do cartão físico, no formato ISO 8601 - UTC.
virtualBindobjectObjeto que contém informações sobre o cartão virtual vinculado ao cartão físico consultado. Esse objeto somente será retornado caso o tipo de cartão (cardType) seja "Physical".
virtualBind.proxystringCódigo identificador do cartão virtual.
virtualBind.createdstringData de criação do cartão virtual, no formato ISO 8601 - UTC.
allowContactlessbooleanIndica se é permitido pagamento por aproximação (true) ou não (false).
addressobjectObjeto que contém informações sobre o endereço do titular do cartão.
address.zipCodestringCódigo postal do endereço.
address.addressstringLogradouro (nome da rua, avenida etc.).
address.numberstringNúmero do imóvel.
address.neighborhoodstringNome do bairro.
address.complementstringComplemento do endereço.
address.citystringNome da cidade.
address.statestringNome do estado.
address.countrystringNome do país.
historyStatus[]array of objectsLista de objetos contendo o histórico de status do cartão desde sua criação.
historyStatus[].modifiedstringData em que o status foi aplicado, no formato ISO 8601 - UTC.
historyStatus[].valuestringNome 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.
wallets[]array of objectsLista 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.
wallets[].statusstringStatus do cartão na carteira, que pode ser "Approved" ou "Denied".
wallets[].walletTypestringIdentificador da carteira à qual o cartão se encontra vinculado.
wallets[].walletFlowAddstringClassificação do fluxo que o cartão recebeu ao entrar na carteira, que pode ser "Undefined", "GreenPatch" ou "YellowPatch".
creditPosobjectObjeto que contém informações sobre o limite de crédito do cartão pós-pago. Esse objeto somente será retornado se o cartão consultado for pós-pago.
creditPos.contractNumberstringNúmero do contrato de crédito do cliente.
creditPos.limitnumberLimite de crédito do cliente.
creditPos.limitActivenumberLimite de crédito ativo do cliente.
functionalities[]array of objectsLista de objetos contendo informações sobre as modalidades do cartão.
functionalities[].typestringTipo de modalidade associada ao cartão, que pode ser “Debit", "Pos" ou "Pre".
functionalities[].programobjectObjeto que contém informações sobre o programa ao qual a modalidade está vinculada.
functionalities[].program.idnumberIdentificador único do programa.
functionalities[].program.binstringO BIN, ou Bank Identification Number, são os seis ou oito primeiros dígitos do cartão, utilizados para identificar a instituição bancária que o emitiu.
functionalities[].program.typestringTipo do programa que define a modalidade do cartão.
functionalities[].program.brandstringBandeira do cartão.
functionalities[].statusstringStatus da modalidade, que pode ser “Enabled" (ativado), "Disabled" (desativado), "Blocked" (bloqueado) e “BlockedByContract" (bloqueado por contrato).
activatedAtstringData da ativação do cartão, no formato ISO 8601 - UTC.
lastUpdatedAtstringData da última atualização do cartão, no formato ISO 8601 - UTC.
isActivatedbooleanIndica se o cartão está ativo.
isLockedbooleanIndica se o cartão está bloqueado.
isCanceledbooleanIndica se o cartão está cancelado.
isBuildingbooleanIndica se o cartão está em construção.
isFirtualbooleanIndica se o cartão é Firtual.
isPrebooleanIndica se o cartão é pré-pago.
isPosbooleanIndica se o cartão é pós-pago.
isCombobooleanIndica se o cartão é combo.

Exemplo - Cartão físico

{
  "created": "2020-07-20T22:53:12",
  "companyKey": "ACESSO",
  "holder": {
    "name": "Nísia Floresta da Silva",
    "document": {
      "value": "47742663023",
      "type": "CPF"
    }
  },  
  "documentNumber": "47742663023",
  "activateCode": "A9991B2E491D",
  "trackingCode": "4717AEWATCTQ",
  "bankAgency": "0001",
  "bankAccount": "0001",
  "lastFourDigits": "4321",
  "proxy": "22999903520114195",
  "name": "Nísia Floresta",
  "alias": "Meu Cartão",
  "cardType": "Physical",
  "status": "InTransitLocked",
  "virtualBind": {
    "proxy": "22999903520114195",
    "created": "2020-07-20T22:55:12"
  },
  "allowContactless": true,
  "address": {
    "zipCode": "05402100",
    "address": "Rua 6 de Março",
    "number": "2500",
    "neighborhood": "Alter do Chão",
    "complement": "",
    "city": "Santarém ",
    "state": "PA",
    "country": "Brasil"
  },
  "historyStatus": [
    {
      "modified": "2020-07-20T22:53:12",
      "value": "Building"
    },
    {
      "modified": "2020-07-20T22:55:12",
      "value": "InTransitLocked"
    }
  ],
  "creditPos": {
    "contractNumber": "54684325763",
    "limit": 3000,
    "limitActive": 1000
  },
  "functionalities": [
    {
      "type": "Pos",
      "program": {
        "id": 53,
        "bin": "234028",
        "type": "Pos",
        "brand": "Mastercard"
      },
      "status": "Enabled"
    }
  ],
  "activatedAt": null,
  "lastUpdatedAt": "2020-07-20T22:55:12",
  "isActivated": false,
  "isLocked": true,
  "isCanceled": false,
  "isBuilding": false,
  "isFirtual": true,
  "isPre": false,
  "isPos": true,
  "isCombo": false
}

{
  "created": "2020-07-20T22:53:12",
  "companyKey": "ACESSO",
  "holder": {
    "name": "Nísia Floresta da Silva",
    "document": {
      "value": "47742663023",
      "type": "CPF"
    }
  },
  "documentNumber": "47742663023",
  "activateCode": "A9991B2E491D",
  "trackingCode": "4717AEWATCTQ",
  "bankAgency": "0001",
  "bankAccount": "0001",
  "lastFourDigits": "4321",
  "proxy": "22999903520114195",
  "name": "Nísia Floresta",
  "alias": "Meu Cartão",
  "cardType": "Physical",
  "status": "InTransitLocked",
  "virtualBind": {
    "proxy": "22999903520114195",
    "created": "2020-07-20T22:55:12"
  },
  "allowContactless": true,
  "address": {
    "zipCode": "05402100",
    "address": "Rua 6 de Março",
    "number": "2500",
    "neighborhood": "Alter do Chão",
    "complement": "",
    "city": "Santarém ",
    "state": "PA",
    "country": "Brasil"
  },
  "historyStatus": [
    {
      "modified": "2020-07-20T22:53:12",
      "value": "Building"
    },
    {
      "modified": "2020-07-20T22:55:12",
      "value": "InTransitLocked"
    }
  ],
  "wallets": [
    {
      "status": "Approved",
      "walletType": "GooglePay",
      "walletFlowAdd": "YellowPatch"
    }
  ],
  "creditPos": {
    "contractNumber": "54684325763",
    "limit": 3000,
    "limitActive": 1000
  },
  "functionalities": [
    {
      "type": "Pos",
      "program": {
        "id": 53,
        "bin": "234028",
        "type": "Pos",
        "brand": "Mastercard"
      },
      "status": "Enabled"
    }
  ],
  "activatedAt": null,
  "lastUpdatedAt": "2020-07-20T22:55:12",
  "isActivated": false,
  "isLocked": true,
  "isCanceled": false,
  "isBuilding": false,
  "isFirtual": true,
  "isPre": false,
  "isPos": true,
  "isCombo": false
}

{
  "created": "2020-07-20T22:53:12",
  "companyKey": "ACESSO",
  "holder": {
    "name": "Nísia Floresta da Silva",
    "document": {
      "value": "47742663023",
      "type": "CPF"
    }
  },
  "documentNumber": "47742663023",
  "activateCode": "A9991B2E491D",
  "trackingCode": "4717AEWATCTQ",
  "bankAgency": "0001",
  "bankAccount": "0001",
  "lastFourDigits": "4321",
  "proxy": "22999903520114195",
  "name": "Nísia Floresta",
  "alias": "Meu Cartão",
  "cardType": "Physical",
  "status": "InTransitLocked",
  "allowContactless": true,
  "address": {
   "zipCode": "05402100",
    "address": "Rua 6 de Março",
    "number": "2500",
    "neighborhood": "Alter do Chão",
    "complement": "",
    "city": "Santarém ",
    "state": "PA",
    "country": "Brasil"
  },
  "historyStatus": [
    {
      "modified": "2020-07-20T22:53:12",
      "value": "Building"
    },
    {
      "modified": "2020-07-20T22:55:12",
      "value": "InTransitLocked"
    }
  ],
  "functionalities": [
    {
      "type": "Pre",
      "program": {
        "id": 53,
        "bin": "234028",
        "type": "Pre",
        "brand": "Mastercard"
      },
      "status": "Enabled"
    }
  ],
  "activatedAt": null,
  "lastUpdatedAt": "2020-07-20T22:55:12",
  "isActivated": false,
  "isLocked": true,
  "isCanceled": false,
  "isBuilding": false,
  "isFirtual": false,
  "isPre": true,
  "isPos": false,
  "isCombo": false
}

{
  "created": "2020-07-20T22:53:12",
  "companyKey": "ACESSO",
  "holder": {
    "name": "Nísia Floresta da Silva",
    "document": {
      "value": "47742663023",
      "type": "CPF"
    }
  },
  "documentNumber": "47742663023",
  "activateCode": "A9991B2E491D",
  "trackingCode": "4717AEWATCTQ",
  "bankAgency": "0001",
  "bankAccount": "0001",
  "lastFourDigits": "4321",
  "proxy": "22999903520114195",
  "name": "Nísia Floresta",
  "alias": "Meu Cartão",
  "cardType": "Physical",
  "status": "InTransitLocked",
  "allowContactless": true,
  "address": {
    "zipCode": "05402100",
    "address": "Rua 6 de Março",
    "number": "2500",
    "neighborhood": "Alter do Chão",
    "complement": "",
    "city": "Santarém ",
    "state": "PA",
    "country": "Brasil"
  },
  "historyStatus": [
    {
      "modified": "2020-07-20T22:53:12",
      "value": "Building"
    },
    {
      "modified": "2020-07-20T22:55:12",
      "value": "InTransitLocked"
    }
  ],
  "wallets": [
    {
      "status": "Approved",
      "walletType": "GooglePay",
      "walletFlowAdd": "YellowPatch"
    }
  ],
  "functionalities": [
    {
      "type": "Pre",
      "program": {
        "id": 53,
        "bin": "234028",
        "type": "Pre",
        "brand": "Mastercard"
      },
      "status": "Enabled"
    }
  ],
  "activatedAt": null,
  "lastUpdatedAt": "2020-07-20T22:55:12",
  "isActivated": false,
  "isLocked": true,
  "isCanceled": false,
  "isBuilding": false,
  "isFirtual": false,
  "isPre": true,
  "isPos": false,
  "isCombo": false
}

Exemplo - Cartão virtual

{
  "created": "2020-07-20T22:53:12",
  "companyKey": "ACESSO",
  "holder": {
    "name": "Nísia Floresta da Silva",
    "document": {
      "value": "47742663023",
      "type": "CPF"
    }
  },  
  "documentNumber": "47742663023",
  "activateCode": "A9991B2E491D",
  "bankAgency": "0001",
  "bankAccount": "0001",
  "lastFourDigits": "4321",
  "proxy": "22999903520114195",
  "name": "Nísia Floresta",
  "alias": "Meu Cartão",
  "cardType": "Virtual",
  "status": "Active",
  "physicalBinds": [
    {
      "proxy": "2300199994444111999",
      "created": "2020-07-20T22:54:03"
    }
  ],
  "allowContactless": false,
  "address": {
   "zipCode": "05402100",
    "address": "Rua 6 de Março",
    "number": "2500",
    "neighborhood": "Alter do Chão",
    "complement": "",
    "city": "Santarém ",
    "state": "PA",
    "country": "Brasil"
  },
  "historyStatus": [
    {
      "modified": "2020-07-20T22:53:12",
      "value": "WithoutMovementLocked"
    },
    {
      "modified": "2020-07-20T22:55:12",
      "value": "Active"
    }
  ],
  "creditPos": {
    "contractNumber": "54684325763",
    "limit": 3000,
    "limitActive": 1000
  },
  "functionalities": [
    {
      "type": "Pos",
      "program": {
        "id": 53,
        "bin": "234028",
        "type": "Pos",
        "brand": "Mastercard"
      },
      "status": "Enabled"
    }
  ],
  "activatedAt": null,
  "lastUpdatedAt": "2020-07-20T22:55:12",
  "isActivated": true,
  "isLocked": false,
  "isCanceled": false,
  "isBuilding": false,
  "isFirtual": true,
  "isPre": false,
  "isPos": true,
  "isCombo": false
}

{
  "created": "2020-07-20T22:53:12",
  "companyKey": "ACESSO",
  "holder": {
    "name": "Nísia Floresta da Silva",
    "document": {
      "value": "47742663023",
      "type": "CPF"
    }
  },
  "documentNumber": "47742663023",
  "activateCode": "A9991B2E491D",
  "bankAgency": "0001",
  "bankAccount": "0001",
  "lastFourDigits": "4321",
  "proxy": "22999903520114195",
  "name": "Nísia Floresta",
  "alias": "Meu Cartão",
  "cardType": "Virtual",
  "status": "Active",
  "physicalBinds": [
    {
      "proxy": "2300199994444111999",
      "created": "2020-07-20T22:54:03"
    }
  ],
  "allowContactless": false,
  "address": {
    "zipCode": "05402100",
    "address": "Rua 6 de Março",
    "number": "2500",
    "neighborhood": "Alter do Chão",
    "complement": "",
    "city": "Santarém ",
    "state": "PA",
    "country": "Brasil"
  },
  "historyStatus": [
    {
      "modified": "2020-07-20T22:53:12",
      "value": "WithoutMovementLocked"
    },
    {
      "modified": "2020-07-20T22:55:12",
      "value": "Active"
    }
  ],
  "wallets": [
    {
      "status": "Approved",
      "walletType": "GooglePay",
      "walletFlowAdd": "YellowPatch"
    }
  ],
  "creditPos": {
    "contractNumber": "54684325763",
    "limit": 3000,
    "limitActive": 1000
  },
  "functionalities": [
    {
      "type": "Pos",
      "program": {
        "id": 53,
        "bin": "234028",
        "type": "Pos",
        "brand": "Mastercard"
      },
      "status": "Enabled"
    }
  ],
  "activatedAt": null,
  "lastUpdatedAt": "2020-07-20T22:55:12",
  "isActivated": true,
  "isLocked": false,
  "isCanceled": false,
  "isBuilding": false,
  "isFirtual": true,
  "isPre": false,
  "isPos": true,
  "isCombo": false
}

{
  "created": "2020-07-20T22:53:12",
  "companyKey": "ACESSO",
  "holder": {
    "name": "Nísia Floresta da Silva",
    "document": {
      "value": "47742663023",
      "type": "CPF"
    }
  }, 
  "documentNumber": "47742663023",
  "activateCode": "A9991B2E491D",
  "bankAgency": "0001",
  "bankAccount": "0001",
  "lastFourDigits": "4321",
  "proxy": "22999903520114195",
  "name": "Nísia Floresta",
  "alias": "Meu Cartão",
  "cardType": "Virtual",
  "status": "Active",
  "allowContactless": false,
  "address": {
    "zipCode": "05402100",
    "address": "Rua 6 de Março",
    "number": "2500",
    "neighborhood": "Alter do Chão",
    "complement": "",
    "city": "Santarém ",
    "state": "PA",
    "country": "Brasil"
  },
  "historyStatus": [
    {
      "modified": "2020-07-20T22:53:12",
      "value": "WithoutMovementLocked"
    },
    {
      "modified": "2020-07-20T22:55:12",
      "value": "Active"
    }
  ],
  "functionalities": [
    {
      "type": "Pre",
      "program": {
        "id": 53,
        "bin": "234028",
        "type": "Pre",
        "brand": "Mastercard"
      },
      "status": "Enabled"
    }
  ],
  "activatedAt": null,
  "lastUpdatedAt": "2020-07-20T22:55:12",
  "isActivated": true,
  "isLocked": true,
  "isCanceled": false,
  "isBuilding": false,
  "isFirtual": false,
  "isPre": true,
  "isPos": false,
  "isCombo": false
}

{
  "created": "2020-07-20T22:53:12",
  "companyKey": "ACESSO",
  "holder": {
    "name": "Nísia Floresta da Silva",
    "document": {
      "value": "47742663023",
      "type": "CPF"
    }
  },
  "documentNumber": "47742663023",
  "activateCode": "A9991B2E491D",
  "bankAgency": "0001",
  "bankAccount": "0001",
  "lastFourDigits": "4321",
  "proxy": "22999903520114195",
  "name": "Nísia Floresta",
  "alias": "Meu Cartão",
  "cardType": "Virtual",
  "status": "Active",
  "allowContactless": false,
  "address": {
    "zipCode": "05402100",
    "address": "Rua 6 de Março",
    "number": "2500",
    "neighborhood": "Alter do Chão",
    "complement": "",
    "city": "Santarém ",
    "state": "PA",
    "country": "Brasil"
  },
  "historyStatus": [
    {
      "modified": "2020-07-20T22:53:12",
      "value": "Building"
    },
    {
      "modified": "2020-07-20T22:55:12",
      "value": "InTransitLocked"
    }
  ],
  "wallets": [
    {
      "status": "Approved",
      "walletType": "GooglePay",
      "walletFlowAdd": "YellowPatch"
    }
  ],
  "functionalities": [
    {
      "type": "Pre",
      "program": {
        "id": 53,
        "bin": "234028",
        "type": "Pre",
        "brand": "Mastercard"
      },
      "status": "Enabled"
    }
  ],
  "activatedAt": null,
  "lastUpdatedAt": "2020-07-20T22:55:12",
  "isActivated": true,
  "isLocked": true,
  "isCanceled": false,
  "isBuilding": false,
  "isFirtual": false,
  "isPre": true,
  "isPos": false,
  "isCombo": false
}

👍

Dica

Para simular uma requisição nesse endpoint, acesse o API Reference.

🚧

Importante

Somente será retornada alguma informação, caso o cartão localizado (se localizado) pertença à company key vinculada ao token de acesso. Caso contrário, será retornado erro 404.

Erros

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

Status CodeCódigoMensagemDescrição
403CERTIFICATE_NOTFOUNDCertificate not found for partner.Não foi encontrado um certificado válido configurado para o parceiro.
404002Card Not FoundCartão não encontrado.

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

Este endpoint não possui eventos relacionados a ele.

Updated 1 day ago

Copyright © 2021 Acesso Soluções de Pagamento S.A - Todos os direitos reservados