Cartão (Card)
stable
Os eventos referentes a cartão disparam mensagens ao destinatário quando:
- Um cartão é emitido;
- O status de um cartão é alterado;
- Um cartão físico começa a ser confeccionado;
- O status ou histórico de rastreio de um cartão físico é alterado;
- O cartão é adicionado ou removido de uma carteira digital;
- A possibilidade de tokenização de um cartão é bloqueada por um determinado período;
- A data de expiração de um cartão está próxima do vencimento;
- A modalidade de um cartão combo tem seu status alterado.
Para mais informações sobre quando essas mensagens são disparadas e sobre o seu conteúdo, consulte as páginas:
- Emissão de cartão;
- Alteração do status do cartão;
- Rastreio de cartões;
- Carteiras digitais.
- Gestão de data de expiração de cartão.
- Alteração de status de modalidade.
Pré-requisitos
Para receber esses eventos, o parceiro deverá:
- Configurar previamente o recebedor de eventos do webhook.
- Conhecer a estrutura básica dos eventos que acompanha o objeto
data.
Informações sobre os eventos
Contexto e nome do evento
Os campos context e name poderão variar de acordo com a tabela a seguir:
context | name | Descrição |
|---|---|---|
Card | CARD_WAS_ISSUED | O cartão foi emitido. |
Card | CARD_WAS_EMBOSSED | O cartão físico está sendo confeccionado. |
Card | TRACKING_STATUS_CHANGED | Houve uma atualização no status de rastreio. |
Card | TRACKING_STATUS_SEND_HISTORY | Durante o processo de entrega do cartão, o status de rastreamento do cartão emitido é atualizado, acionando o evento TRACKING_STATUS_CHANGED. Em paralelo, o evento TRACKING_STATUS_SEND_HISTORY é disparado para comunicar o histórico completo da situação de rastreio, desde a sua criação até a entrega ao destinatário, organizado do mais recente para o mais antigo. |
Card | CARD_STATUS_WAS_MODIFIED | O status do cartão foi alterado. |
Card | CARD_EXPIRATION_DATE_IS_APPROACHING | O cartão está próximo do vencimento. |
Card | COMPLETE_TOKEN_WAS_PROCESSED | A solicitação de inclusão do cartão na carteira digital foi processada. |
Card | CARD_WAS_ADDED_TO_WALLET | O cartão foi adicionado na carteira digital. |
Card | CARD_WAS_REMOVED_FROM_WALLET | O cartão foi removido da carteira digital. |
Card | CARD_WALLET_TOKENIZATION_WAS_BLOCKED | O cartão foi bloqueado temporariamente para inclusão em carteiras digitais. |
Card | CARD_FUNCTION_WAS_MODIFIED | Um cartão do tipo combo teve o status de uma de suas modalidades (débito ou crédito) alterada. |
Card | CARD_WAS_BINDED_WITH_NEW_ACCOUNT | Um cartão do tipo combo foi vinculado a uma conta bancária. |
Fluxo dos eventos
Os fluxogramas a seguir descrevem a sequência em que os eventos ocorrem com base no contexto em que eles estão inseridos. Clique nas imagens para ampliá-las:
Emissão de cartão físico
NotaO processo de emissão de cartão virtual gera apenas o evento CARD_WAS_ISSUED, pois, além de não precisar ser transportado após sua emissão, o cartão já fica ativado assim que é criado (status "Active").
Adição de cartão (físico ou virtual) à carteira digital
Identificador (entityId)
entityId)O campo entityId é o identificador da entidade emissora do evento e seu valor depende do contexto de sua emissão.
No contexto de Cartão o entityId é o código identificador do cartão (proxy).
NotaNo caso do evento
TRACKING_STATUS_CHANGED, oentityIdé o código de rastreio gerado pelo Bankly para ser utilizado pelo operador logístico. O seu valor não é retornado no objetodatado payload, somente no campoentityIdpresente no cabeçalho do evento.
Dados dos eventos
CARD_WAS_ISSUED
Este evento sinaliza que o cartão foi emitido.
Descrição do objeto data do evento
data do eventoO objeto data traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:
| 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. |
trackingCode | string | Código de rastreio do cartão. Campo retornado apenas para cartões físicos. |
alias | string | Apelido dado ao cartão. |
name | string | Nome gravado no cartão, também conhecido como nome de embossing. |
program | object | Objeto que contém informações sobre o programa escolhido pelo parceiro. |
program.id | string | Identificador do programa, o qual é passado no momento da emissão do cartão. |
program.type | string | Tipo de programa. Para emissão de cartão avulso, os mais comuns são: “PhysicalPre”, “VirtualPre” e "Pos", que dizem respeito ao pré-pago físico/virtual e pós-pago físico, respectivamente. Se a emissão for feita em lote, há mais duas opções disponíveis: "LotPre" e "LotPos". |
program.bin | string | O 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. |
program.brand | string | Bandeira do cartão. |
program.name | string | Nome cadastral do programa definido no Bankly, o qual segue o padrão o qual segue o padrão “COMPANYKEY_PRODUTO_FISICO/VIRTUAL”. |
program.product | object | Objeto que contém informações sobre o tipo de produto do cartão. |
program.product.type | string | Tipo de produto que atribui um conjunto de vantagens de acordo com o perfil do portador. |
program.product.additionalInfo | string | Informações complementares sobre o produto do cartão. Observação: só deve existir se o program.product.type for igual a "OUTROS". |
lastFourDigits | string | Quatro últimos dígitos do cartão. |
cardType | string | Tipo do cartão, que pode ser “Physical” ou “Virtual”. |
status | string | Status do cartão. Exemplos: “Active”, “Building”, “Sleeping”, “Inactive”, dentre outros. Confira a tabela com os possíveis status reversíveis e irreversíveis na página Possíveis status do cartão. |
function | string | Função do cartão, que pode ser “Pre”, “Pos” ou “Debit”. |
allowContactless | boolean | Indica se é permitido pagamento por aproximação. |
isAdditional | boolean | Indica se é um cartão adicional ou não. |
functionalities[] | array of objects | Lista de objetos contendo informações sobre as funcionalidades do cartão. |
functionalities[].type | string | Tipo de funcionalidade 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 funcionalidade está vinculada. |
functionalities[].program.id | number | Identificador único do programa. |
functionalities[].program.bin | string | O 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.type | string | Tipo do programa que define a modalidade do cartão. |
functionalities[].program.brand | string | Bandeira do cartão. |
functionalities[].program.name | string | Nome cadastral do programa definido no Bankly, o qual segue o padrão o qual segue o padrão “COMPANYKEY_PRODUTO_FISICO/VIRTUAL”. |
functionalities[].program.product | Objeto que contém informações sobre o tipo de produto do cartão. | |
functionalities[].program.product.type | string | Tipo de produto que atribui um conjunto de vantagens de acordo com o perfil do portador. |
functionalities[].program.product.additionalInfo | string | Informações complementares sobre o produto do cartão. Observação: só deve existir se o program.product.type for igual a "OUTROS". |
functionalities[].status | string | Status da modalidade, que pode ser “Enabled" (ativado), "Disabled" (desativado), "Blocked" (bloqueado) e “BlockedByContract" (bloqueado por contrato). |
address | object | Objeto que contém informações sobre o endereço comercial ou residencial do titular do cartão. |
address.ziCode | string | Código postal do endereço. |
address.addressLine | 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. |
holder | object | Objeto que contém informações sobre o 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. |
holder.document.type | string | Tipo do documento, que pode ser “CPF” ou “CNPJ”. |
holder.name | string | Nome cadastrado. |
holder.account | object | Objeto que contém informações sobre a conta do titular do cartão. Observação: cartões antigos podem não ter essa informação armazenada em seus dados. |
holder.account.branch | string | Número da agência. |
holder.account.number | string | Número da conta. |
holder.account.bank | object | Objeto que contém informações sobre o banco ao qual a conta do titular do cartão pertence. |
holder.account.bank.ispb | string | ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco. |
holder.account.bank.code | string | Código do banco. |
holder.account.bank.name | string | Nome do banco. |
holder.account.isExternalBankingCore | boolean | Indicador de utilização de core bancário externo, que pode ser true ou false. |
holder.phone | object | Objeto que contém informações sobre o telefone do titular do cartão. |
holder.phone.countryCode | string | Código DDI do país. |
holder.phone.number | string | Número de telefone incluindo DDD. |
credit | object | Objeto que contém informações sobre sobre o contrato de crédito. Campo retornado apenas para cartões do tipo pós, quando já há um contrato. |
credit.contractNumber | string | Número do contrato de crédito. |
credit.limitTotal | object | Objeto que contém informações sobre o limite total disponibilizado no contrato. |
credit.limitTotal.value | number | Valor do total disponibilizado no contrato. |
credit.limitTotal.currency | string | Código da moeda com base na ISO 4217. Exemplo: “BRL”. |
batch | object | Objeto que contém informação sobre o lote que originou o cartão. Esse objeto somente será retornado caso o cartão tenha sido emitido dentro de um lote. |
batch.id | string | Identificador único do lote. |
previousCard | object | Objeto que contém informação sobre a via anterior deste cartão. Esse objeto somente será retornado em caso de segunda via (cartão físico). |
previousCard.proxy | string | Código identificador do cartão da via anterior. |
previousCard.purpose | string | Razão da nova emissão (”Duplicate”). |
previousCard.cancellation | object | Objeto que contém informações sobre o cancelamento da via anterior do cartão. |
previousCard.cancellation.mode | string | Momento de cancelamento da primeira via, que pode ser “Immediately” (cancelamento imediato), “Later” (cancelamento tardio), “CanceledAlready” (cartão já cancelado). |
previousCard.cancellation.proxy | string | Código identificador do cartão a ser cancelado. Importante: caso este campo retorne null ou não seja enviado, considere o valor retornado no campo previousCard.proxy. |
previousCard.cancellation.reason | string | Motivo pelo qual a via anterior do cartão foi ou será cancelada. |
expirationDate | string | Data de expiração do cartão, no formato "yyyy-MM-dd" . |
additional | object | Objeto que contém informações sobre o cartão adicional. Observação: Esse objeto somente será retornado caso seja um cartão adicional. |
additional.holder | object | Objeto que contém informações sobre o portador do cartão adicional. |
additional.holder.name | string | Nome do portador do cartão adicional. |
additional.holder.document | object | Objeto que contém informações sobre o documento do portador do cartão adicional. |
additional.holder.document.value | string | Número do documento do cliente (11 ou 14 dígitos). |
additional.holder.document.type | string | Tipo do documento do cliente (CPF ou CNPJ). |
additional.mainProxy | string | Código identificador do cartão titular associado ao cartão adicional. |
Payload do evento
Os payloads abaixo exemplificam a estrutura do evento que deverá ser recebido pelo parceiro. Clique na seta para expandi-los:
Exemplos de payloads
{
"idempotencyKey": "0c908f19-6a3e-4a0b-90aa-606d9a659dfb",
"context": "Card",
"name": "CARD_WAS_ISSUED",
"timestamp": "2022-04-25T12:27:24.1773777Z",
"entityId": "2500441005128861608",
"companyKey": "COMPANY_KEY",
"correlationId": "496b8b38-c956-415a-8668-c21cd146285b",
"metadata": {
"created": "2022-04-25T12:27:04.294+00:00"
},
"data": {
"proxy": "0000000000000000000",
"activateCode": "A49000000095",
"trackingCode": "JRDRVSQ00000",
"alias": "0422",
"name": "Nísia Floresta",
"program": {
"id": "53",
"type": "Pre",
"bin": "123456",
"brand": "Mastercard",
"name": "COMPANY_KEY - Physical"
},
"lastFourDigits": "0000",
"cardType": "Physical",
"status": "Active",
"function": "Pre",
"allowContactless": true,
"functionalities": [
{
"type": "Pre",
"program": {
"id": 53,
"bin": "234028",
"type": "PhysicalPre",
"brand": "Mastercard",
"name": "COMPANY_KEY - Physical"
},
"status": "ENABLED"
}
],
"address": {
"zipCode": "68060100",
"addressLine": "Rua 6 de Março",
"number": "2500",
"neighborhood": "Alter do Chão",
"complement": "Apartamento",
"city": "Santarém",
"state": "PA",
"country": "BR"
},
"holder": {
"document": {
"value": "47742663023",
"type": "CPF"
},
"name": "Nísia Floresta",
"phone": {
"countryCode": "55",
"number": "23415162342"
}
},
"expirationDate": "2030-03-31"
}
} {
"idempotencyKey": "0c908f19-6a3e-4a0b-90aa-606d9a659dfb",
"context": "Card",
"name": "CARD_WAS_ISSUED",
"timestamp": "2022-04-25T12:27:24.1773777Z",
"entityId": "2500441005128861608",
"companyKey": "COMPANY_KEY",
"correlationId": "496b8b38-c956-415a-8668-c21cd146285b",
"metadata": {
"created": "2022-04-25T12:27:04.294+00:00"
},
"data": {
"proxy": "0000000000000000000",
"activateCode": "A49000000095",
"trackingCode": "JRDRVSQ00000",
"alias": "0422",
"name": "Nísia Floresta",
"program": {
"id": "53",
"type": "Pos",
"bin": "123456",
"brand": "Mastercard",
"name": "COMPANY_KEY - Physical",
"product": {
"type": "PLATINUM"
}
},
"lastFourDigits": "0000",
"cardType": "Physical",
"status": "Active",
"function": "Pos",
"allowContactless": true,
"isAdditional": false,
"functionalities": [
{
"type": "Pos",
"program": {
"id": 53,
"bin": "234028",
"type": "Pos",
"brand": "Mastercard",
"name": "COMPANY_KEY - Physical",
"product": {
"type": "PLATINUM"
}
},
"status": "ENABLED"
}
],
"address": {
"zipCode": "68060100",
"addressLine": "Rua 6 de Março",
"number": "2500",
"neighborhood": "Alter do Chão",
"complement": "Apartamento",
"city": "Santarém",
"state": "PA",
"country": "BR"
},
"holder": {
"document": {
"value": "47742663023",
"type": "CPF"
},
"name": "Nísia Floresta",
"phone": {
"countryCode": "55",
"number": "23415162342"
}
},
"credit": {
"contractNumber": "123458696-",
"limitTotal": {
"value": 123,
"currency": "BRL"
}
},
"expirationDate": "2030-03-31"
}
}{
"idempotencyKey": "0c908f19-6a3e-4a0b-90aa-606d9a659dfb",
"context": "Card",
"name": "CARD_WAS_ISSUED",
"timestamp": "2022-04-25T12:27:24.1773777Z",
"entityId": "2500441005128861608",
"companyKey": "COMPANY_KEY",
"correlationId": "496b8b38-c956-415a-8668-c21cd146285b",
"metadata": {
"created": "2022-04-25T12:27:04.294+00:00"
},
"data": {
"proxy": "0000000000000000000",
"activateCode": "A49000000095",
"trackingCode": "JRDRVSQ00000",
"alias": "0422",
"name": "Nísia Floresta",
"program": {
"id": "53",
"type": "LotPre",
"bin": "123456",
"brand": "Mastercard",
"name": "COMPANY_KEY - Physical"
},
"lastFourDigits": "0000",
"cardType": "Physical",
"status": "Active",
"function": "Pre",
"allowContactless": true,
"functionalities": [
{
"type": "Pre",
"program": {
"id": 53,
"bin": "234028",
"type": "Pre",
"brand": "Mastercard",
"name": "COMPANY_KEY - Physical"
},
"status": "ENABLED"
}
],
"address": {
"zipCode": "68060100",
"addressLine": "Rua 6 de Março",
"number": "2500",
"neighborhood": "Alter do Chão",
"complement": "Apartamento",
"city": "Santarém",
"state": "PA",
"country": "BR"
},
"holder": {
"document": {
"value": "47742663023",
"type": "CPF"
},
"name": "Nísia Floresta",
"phone": {
"countryCode": "55",
"number": "23415162342"
}
},
"batch": {
"id": "LT023432982"
}
},
"expirationDate": "2030-03-31"
}{
"idempotencyKey": "0c908f19-6a3e-4a0b-90aa-606d9a659dfb",
"context": "Card",
"name": "CARD_WAS_ISSUED",
"timestamp": "2022-04-25T12:27:24.1773777Z",
"entityId": "2500441005128861608",
"companyKey": "COMPANY_KEY",
"correlationId": "496b8b38-c956-415a-8668-c21cd146285b",
"metadata": {
"created": "2022-04-25T12:27:04.294+00:00"
},
"data": {
"proxy": "0000000000000000000",
"activateCode": "A49000000095",
"trackingCode": "JRDRVSQ00000",
"alias": "0422",
"name": "Nísia Floresta",
"program": {
"id": "53",
"type": "Pre",
"bin": "123456",
"brand": "Mastercard",
"name": "COMPANY_KEY - Physical"
},
"lastFourDigits": "0000",
"cardType": "Physical",
"status": "Active",
"function": "Pre",
"allowContactless": true,
"functionalities": [
{
"type": "Pre",
"program": {
"id": 53,
"bin": "234028",
"type": "Pre",
"brand": "Mastercard",
"name": "COMPANY_KEY - Physical"
},
"status": "ENABLED"
}
],
"address": {
"zipCode": "68060100",
"addressLine": "Rua 6 de Março",
"number": "2500",
"neighborhood": "Alter do Chão",
"complement": "Apartamento",
"city": "Santarém",
"state": "PA",
"country": "BR"
},
"holder": {
"document": {
"value": "47742663023",
"type": "CPF"
},
"name": "Nísia Floresta",
"phone": {
"countryCode": "55",
"number": "23415162342"
}
},
"previousCard": {
"proxy": "1111111111111111111",
"purpose": "Duplicate",
"cancellation": {
"mode": "Immediately",
"proxy": "1111111111111111111",
"reason": "CardDamagedCanceled"
}
},
"expirationDate": "2030-03-31"
}
}{
"idempotencyKey": "0c908f19-6a3e-4a0b-90aa-606d9a659dfb",
"context": "Card",
"name": "CARD_WAS_ISSUED",
"timestamp": "2022-04-25T12:27:24.1773777Z",
"entityId": "2500441005128861608",
"companyKey": "COMPANY_KEY",
"correlationId": "496b8b38-c956-415a-8668-c21cd146285b",
"metadata": {
"created": "2022-04-25T12:27:04.294+00:00"
},
"data": {
"proxy": "0000000000000000000",
"activateCode": "A49000000095",
"trackingCode": "JRDRVSQ00000",
"alias": "0422",
"name": "Nísia Floresta",
"program": {
"id": "53",
"type": "Pos",
"bin": "123456",
"brand": "Mastercard",
"name": "COMPANY_KEY - Physical",
"product": {
"type": "PLATINUM"
}
},
"lastFourDigits": "0000",
"cardType": "Physical",
"status": "Active",
"function": "Pos",
"allowContactless": true,
"isAdditional": false,
"functionalities": [
{
"type": "Pos",
"program": {
"id": 53,
"bin": "234028",
"type": "Pos",
"brand": "Mastercard",
"name": "COMPANY_KEY - Physical",
"product": {
"type": "PLATINUM"
}
},
"status": "ENABLED"
}
],
"address": {
"zipCode": "68060100",
"addressLine": "Rua 6 de Março",
"number": "2500",
"neighborhood": "Alter do Chão",
"complement": "Apartamento",
"city": "Santarém",
"state": "PA",
"country": "BR"
},
"holder": {
"document": {
"value": "47742663023",
"type": "CPF"
},
"name": "Nísia Floresta",
"phone": {
"countryCode": "55",
"number": "23415162342"
}
},
"credit": {
"contractNumber": "123458696-",
"limitTotal": {
"value": 123,
"currency": "BRL"
}
},
"previousCard": {
"proxy": "1111111111111111111",
"purpose": "Duplicate",
"cancellation": {
"mode": "Immediately",
"proxy": "1111111111111111111",
"reason": "CardDamagedCanceled"
}
},
"expirationDate": "2030-03-31"
}
} {
"idempotencyKey": "0c908f19-6a3e-4a0b-90aa-606d9a659dfb",
"context": "Card",
"name": "CARD_WAS_ISSUED",
"timestamp": "2025-09-10T12:27:24.1773777Z",
"entityId": "2500441005128861608",
"companyKey": "COMPANY_KEY",
"correlationId": "496b8b38-c956-415a-8668-c21cd146285b",
"metadata": {
"created": "2025-09-10T12:27:04.294+00:00"
},
"data": {
"proxy": "0000000000000000000",
"activateCode": "A49000000095",
"trackingCode": "JRDRVSQ00000",
"alias": "0422",
"name": "Nísia Floresta",
"program": {
"id": "53",
"type": "Pos",
"bin": "123456",
"brand": "Mastercard",
"name": "COMPANY_KEY - Physical",
"product": {
"type": "PLATINUM"
}
},
"lastFourDigits": "0000",
"cardType": "Physical",
"status": "Active",
"function": "Pos",
"allowContactless": true,
"isAdditional": true,
"functionalities": [
{
"type": "Pos",
"program": {
"id": 53,
"bin": "234028",
"type": "Pos",
"brand": "Mastercard",
"name": "COMPANY_KEY - Physical",
"product": {
"type": "PLATINUM"
}
},
"status": "ENABLED"
}
],
"address": {
"zipCode": "68060100",
"addressLine": "Rua 6 de Março",
"number": "2500",
"neighborhood": "Alter do Chão",
"complement": "Apartamento",
"city": "Santarém",
"state": "PA",
"country": "BR"
},
"holder": {
"document": {
"value": "47742663023",
"type": "CPF"
},
"name": "Nísia Floresta",
"phone": {
"countryCode": "55",
"number": "23415162342"
}
},
"credit": {
"contractNumber": "123458696-",
"limitTotal": {
"value": 123,
"currency": "BRL"
}
},
"expirationDate": "2030-09-10",
"additional": {
"holder": {
"name": "Ana Floresta",
"document": {
"value": "00000000000",
"type": "CPF"
}
}
}
}
}CARD_WAS_EMBOSSED
Este evento indica que o cartão físico está sendo confeccionado.
Descrição do objeto data do evento
data do eventoO objeto data traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:
| 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. |
trackingCode | string | Código de rastreio do cartão. Campo retornado apenas para cartões físicos. |
alias | string | Apelido definido pelo proprietário para o cartão. |
name | string | Nome gravado no cartão, também conhecido como nome de embossing. |
program | object | Objeto que contém informações sobre o programa escolhido pelo parceiro. |
program.id | number | Identificador do programa, o qual é passado no momento da emissão do cartão. |
program.type | string | Tipo de programa. Para emissão de cartão avulso, os mais comuns são: “PhysicalPre”, “VirtualPre” e "Pos", que dizem respeito ao pré-pago físico/virtual e pós-pago físico, respectivamente. Se a emissão for feita em lote, há mais duas opções disponíveis: "LotPre" e "LotPos". |
program.bin | string | O BIN são os seis ou oito primeiros dígitos do cartão, utilizados para identificar a instituição bancária que o emitiu. |
program.brand | string | Bandeira do cartão. |
program.name | string | Nome cadastral do programa definido no Bankly, o qual segue o padrão “COMPANYKEY_PRODUTO_FISICO/VIRTUAL”. |
lastFourDigits | string | Quatro últimos dígitos do cartão. |
cardType | string | Tipo do cartão, que pode ser “Physical” ou “Virtual”. |
status | string | Status do cartão. Exemplos: “Active”, “Building”, “Sleeping”, “Inactive”, dentre outros. |
function | string | Função do cartão, que pode ser “Pre”, “Pos” ou “Debit”. |
allowContactless | boolean | Indica se é permitido pagamento por aproximação. |
functionalities[] | array of objects | Lista de objetos contendo informações sobre as modalidades do cartão. |
functionalities[].type | number | 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.id | number | Identificador único do programa. |
functionalities[].program.bin | string | O BIN 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.type | string | Tipo do programa que define a modalidade do cartão. |
functionalities[].program.brand | string | Bandeira do cartão. |
functionalities[].program.name | string | Nome cadastral do programa definido no Bankly, o qual segue o padrão “COMPANYKEY_PRODUTO_FISICO/VIRTUAL”. |
functionalities[].status | string | Status da modalidade, que pode ser “Enabled" (ativado), "Disabled" (desativado), "Blocked" (bloqueado) e “BlockedByContract" (bloqueado por contrato). |
address | object | Objeto que contém informações sobre o endereço comercial ou residencial do titular do cartão. |
address.zipCode | string | Código postal do endereço. Dados enviados no momento da emissão do cartão. Quando não informado, serão enviados os dados do cadastro do cliente. |
address.addressLine | string | Logradouro (nome da rua, avenida etc.). Dados enviados no momento da emissão do cartão. Quando não informado, serão enviados os dados do cadastro do cliente. |
address.number | string | Número do imóvel. Dados enviados no momento da emissão do cartão. Quando não informado, serão enviados os dados do cadastro do cliente. |
address.neighborhood | string | Nome do bairro. Dados enviados no momento da emissão do cartão. Quando não informado, serão enviados os dados do cadastro do cliente. |
address.complement | string | Complemento do endereço. Dados enviados no momento da emissão do cartão. Quando não informado, serão enviados os dados do cadastro do cliente. |
address.city | string | Nome da cidade. Dados enviados no momento da emissão do cartão. Quando não informado, serão enviados os dados do cadastro do cliente. |
address.state | string | Nome do estado. Dados enviados no momento da emissão do cartão. Quando não informado, serão enviados os dados do cadastro do cliente. |
address.country | string | Nome do país. Dados enviados no momento da emissão do cartão. Quando não informado, serão enviados os dados do cadastro do cliente. |
holder | object | Objeto que contém informações sobre o 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. |
holder.document.type | string | Tipo do documento, que pode ser “CPF” ou “CNPJ”. |
holder.name | string | Nome cadastrado. |
holder.phone | object | Objeto que contém informações sobre o telefone do titular do cartão. |
holder.phone.countryCode | string | Código DDI do país. |
holder.phone.number | string | Número de telefone incluindo DDD. |
credit | object | Objeto que contém informações sobre sobre o contrato de crédito. Campo retornado apenas para cartões do tipo pós, quando já há um contrato. |
credit.contractNumber | string | Número do contrato de crédito. |
credit.limitTotal | object | Objeto que contém informações sobre o limite total disponibilizado no contrato. |
credit.limitTotal.value | number | Valor do total disponibilizado no contrato. |
credit.limitTotal.currency | string | Código da moeda com base na ISO 4217. Exemplo: “BRL”. |
embosser | object | Objeto que contém informações sobre os dados de envio para confecção. |
embosser.factory | string | Fábrica de confecção do cartão. |
embosser.fileName | string | Nome do arquivo em que o cartão foi enviado para confecção. |
embosser.embossedAt | string | Data e hora do envio, no formato ISO 8601 - UTC. |
embosser.customFields | object | Objeto que contém informações sobre os campos customizados enviados à fábrica. |
embosser.customFields.PlasticCode | string | Código do plástico do cartão. |
batch | object | Objeto que contém informação sobre o lote que originou o cartão. Esse objeto somente será retornado caso o cartão tenha sido emitido dentro de um lote. |
batch.id | string | Identificador único do lote. |
previousCard | object | Objeto que contém informação sobre a via anterior deste cartão. Esse objeto somente será retornado em caso de segunda via (cartão físico). |
previousCard.proxy | string | Código identificador do cartão da via anterior. |
previousCard.purpose | string | Razão da nova emissão (“Duplicate”). |
previousCard.cancellation | object | Objeto que contém informações sobre o cancelamento da via anterior do cartão. |
previousCard.cancellation.mode | string | Momento de cancelamento da primeira via, que pode ser “Immediately” (cancelamento imediato), “Later” (cancelamento tardio), “CanceledAlready” (cartão já cancelado). |
previousCard.cancellation.proxy | string | Código identificador do cartão a ser cancelado. Importante: caso este campo retorne null ou não seja enviado, considere o valor retornado no campo previousCard.proxy. |
previousCard.cancellation.reason | string | Motivo pelo qual a via anterior do cartão foi ou será cancelada. |
expirationDate | string | Data de expiração do cartão, no formato yyyy-MM-dd. |
NotaOs dados de endereço presentes neste evento correspondem às informações fornecidas no momento da emissão do cartão. Quando não informados, serão utilizados os dados do cadastro do cliente. Alterações cadastrais realizadas posteriormente não atualizam os dados deste evento e não alteram o endereço de entrega do cartão.
Payload do evento
Os payloads abaixo exemplificam a estrutura do evento que deverá ser recebido pelo parceiro. Clique na seta para expandi-los:
Exemplos de payload
{
"name":"CARD_WAS_EMBOSSED",
"idempotencyKey":"914e0649-034f-4fb2-b20a-d87422c863cd",
"context":"Card",
"timestamp":"2022-12-30T01:11:07.4151363Z",
"entityId":"2500441000000000001",
"companyKey":"COMPANY_KEY",
"correlationId":"5ba3cd76-53bf-4cc4-8ba2-eea0fb1b1071",
"version": "1",
"metadata":{
"capturedAt":"2022-12-30T01:11:07.4019873Z"
},
"data":{
"proxy":"2500441000000000001",
"activateCode":"A395FFES110C",
"trackingCode": "JRDRVSQ00000",
"alias":"1222",
"name":"Nísia Floresta",
"program":{
"id":"1000",
"name": "COMPANY_KEY - Physical",
"type":"PhysicalPos",
"bin": "234028",
"brand": "Mastercard"
},
"lastFourDigits":"8944",
"cardType":"Physical",
"status":"InTransitLocked",
"function":"Pos",
"allowContactless":true,
"functionalities": [
{
"type": "Pos",
"program": {
"id": 53,
"bin": "234028",
"type": "PhysicalPos",
"brand": "Mastercard",
"name": "COMPANY_KEY - Physical"
},
"status": "ENABLED"
}
],
"address":{
"zipCode":"68060100",
"addressLine":"Rua 6 de Março",
"number":"2500",
"neighborhood":"Alter do Chão",
"complement":"Apartamento",
"city":"Santarém",
"state":"PA",
"country":"BR"
},
"holder":{
"document":{
"value":"47742663023",
"type":"CPF"
},
"name":"Nísia Floresta",
"phone": {
"countryCode": "55",
"number": "23415162342"
}
},
"credit": {
"contractNumber": "123458696-",
"limitTotal": {
"value": 123,
"currency": "BRL"
}
},
"embosser":{
"factory":"TestCard",
"fileName":"ACESSO20221230_275.txt",
"embossedAt":"2022-12-30T01:10:41Z",
"customFields": {
"plasticCode": "0000"
}
},
"expirationDate": "2030-03-31"
}
}{
"name":"CARD_WAS_EMBOSSED",
"idempotencyKey":"914e0649-034f-4fb2-b20a-d87422c863cd",
"context":"Card",
"timestamp":"2022-12-30T01:11:07.4151363Z",
"entityId":"2500441000000000001",
"companyKey":"COMPANY_KEY",
"correlationId":"5ba3cd76-53bf-4cc4-8ba2-eea0fb1b1071",
"version": "1",
"metadata":{
"capturedAt":"2022-12-30T01:11:07.4019873Z"
},
"data":{
"proxy":"2500441000000000001",
"activateCode":"A395FFES110C",
"trackingCode": "JRDRVSQ00000",
"alias":"1222",
"name":"Nísia Floresta",
"program":{
"id":"1000",
"name": "COMPANY_KEY - Physical",
"type":"PhysicalPos",
"bin": "234028",
"brand": "Mastercard"
},
"lastFourDigits":"8944",
"cardType":"Physical",
"status":"InTransitLocked",
"function":"Pos",
"allowContactless":true,
"functionalities": [
{
"type": "Pos",
"program": {
"id": 53,
"bin": "234028",
"type": "PhysicalPos",
"brand": "Mastercard",
"name": "COMPANY_KEY - Physical"
},
"status": "ENABLED"
}
],
"address":{
"zipCode":"68060100",
"addressLine":"Rua 6 de Março",
"number":"2500",
"neighborhood":"Alter do Chão",
"complement":"Apartamento",
"city":"Santarém",
"state":"PA",
"country":"BR"
},
"holder":{
"document":{
"value":"47742663023",
"type":"CPF"
},
"name":"Nísia Floresta",
"phone": {
"countryCode": "55",
"number": "23415162342"
}
},
"credit": {
"contractNumber": "123458696-",
"limitTotal": {
"value": 123,
"currency": "BRL"
}
},
"embosser":{
"factory":"TestCard",
"fileName":"ACESSO20221230_275.txt",
"embossedAt":"2022-12-30T01:10:41Z",
"customFields": {
"plasticCode": "0000"
}
},
"previousCard": {
"proxy": "1111111111111111111",
"purpose": "Duplicate",
"cancellation": {
"mode": "Immediately",
"proxy": "1111111111111111111",
"reason": "CardDamagedCanceled"
}
},
"expirationDate": "2030-03-31"
}
}{
"name":"CARD_WAS_EMBOSSED",
"idempotencyKey":"914e0649-034f-4fb2-b20a-d87422c863cd",
"context":"Card",
"timestamp":"2022-12-30T01:11:07.4151363Z",
"entityId":"2500441000000000001",
"companyKey":"COMPANY_KEY",
"correlationId":"5ba3cd76-53bf-4cc4-8ba2-eea0fb1b1071",
"version": "1",
"metadata":{
"capturedAt":"2022-12-30T01:11:07.4019873Z"
},
"data":{
"proxy":"2500441000000000001",
"activateCode":"A395FFES110C",
"trackingCode": "JRDRVSQ00000",
"alias":"1222",
"name":"Nísia Floresta",
"program":{
"id":"1000",
"name": "COMPANY_KEY - Physical",
"type":"LotPos",
"bin": "234028",
"brand": "Mastercard"
},
"lastFourDigits":"8944",
"cardType":"Physical",
"status":"InTransitLocked",
"function":"Pos",
"allowContactless":true,
"functionalities": [
{
"type": "Pos",
"program": {
"id": 53,
"bin": "234028",
"type": "PhysicalPos",
"brand": "Mastercard",
"name": "COMPANY_KEY - Physical"
},
"status": "ENABLED"
}
],
"address":{
"zipCode":"68060100",
"addressLine":"Rua 6 de Março",
"number":"2500",
"neighborhood":"Alter do Chão",
"complement":"Apartamento",
"city":"Santarém",
"state":"PA",
"country":"BR"
},
"holder":{
"document":{
"value":"47742663023",
"type":"CPF"
},
"name":"Nísia Floresta",
"phone": {
"countryCode": "55",
"number": "23415162342"
}
},
"credit": {
"contractNumber": "123458696-",
"limitTotal": {
"value": 123,
"currency": "BRL"
}
},
"embosser":{
"factory":"TestCard",
"fileName":"ACESSO20221230_275.txt",
"embossedAt":"2022-12-30T01:10:41Z",
"customFields": {
"plasticCode": "0000"
}
},
"batch": {
"id": "LT023432982"
},
"expirationDate": "2030-03-31"
}
}{
"name":"CARD_WAS_EMBOSSED",
"idempotencyKey":"914e0649-034f-4fb2-b20a-d87422c863cd",
"context":"Card",
"timestamp":"2022-12-30T01:11:07.4151363Z",
"entityId":"2500441000000000001",
"companyKey":"COMPANY_KEY",
"correlationId":"5ba3cd76-53bf-4cc4-8ba2-eea0fb1b1071",
"version": "1",
"metadata":{
"capturedAt":"2022-12-30T01:11:07.4019873Z"
},
"data":{
"proxy":"2500441000000000001",
"activateCode":"A395FFES110C",
"alias":"1222",
"name":"Nísia Floresta",
"program":{
"id":"1000",
"name": "COMPANY_KEY - Physical",
"type":"VirtualPre",
"bin": "234028",
"brand": "Mastercard"
},
"lastFourDigits":"8944",
"cardType":"Virtual",
"status":"InTransitLocked",
"function":"Pre",
"allowContactless":true,
"functionalities": [
{
"type": "Pre",
"program": {
"id": 53,
"bin": "234028",
"type": "VirtualPre",
"brand": "Mastercard",
"name": "COMPANY_KEY - Physical"
},
"status": "ENABLED"
}
],
"address":{
"zipCode":"68060100",
"addressLine":"Rua 6 de Março",
"number":"2500",
"neighborhood":"Alter do Chão",
"complement":"Apartamento",
"city":"Santarém",
"state":"PA",
"country":"BR"
},
"holder":{
"document":{
"value":"47742663023",
"type":"CPF"
},
"name":"Nísia Floresta",
"phone": {
"countryCode": "55",
"number": "23415162342"
}
},
"embosser":{
"factory":"TestCard",
"fileName":"ACESSO20221230_275.txt",
"embossedAt":"2022-12-30T01:10:41Z",
"customFields": {
"plasticCode": "0000"
}
},
"expirationDate": "2030-03-31"
}
}{
"name":"CARD_WAS_EMBOSSED",
"idempotencyKey":"914e0649-034f-4fb2-b20a-d87422c863cd",
"context":"Card",
"timestamp":"2022-12-30T01:11:07.4151363Z",
"entityId":"2500441000000000001",
"companyKey":"COMPANY_KEY",
"correlationId":"5ba3cd76-53bf-4cc4-8ba2-eea0fb1b1071",
"version": "1",
"metadata":{
"capturedAt":"2022-12-30T01:11:07.4019873Z"
},
"data":{
"proxy":"2500441000000000001",
"activateCode":"A395FFES110C",
"trackingCode": "JRDRVSQ00000",
"alias":"1222",
"name":"Nísia Floresta",
"program":{
"id":"1000",
"name": "COMPANY_KEY - Physical",
"type":"PhysicalPre",
"bin": "234028",
"brand": "Mastercard"
},
"lastFourDigits":"8944",
"cardType":"Physical",
"status":"InTransitLocked",
"function":"Pre",
"allowContactless":true,
"functionalities": [
{
"type": "Pre",
"program": {
"id": 53,
"bin": "234028",
"type": "PhysicalPre",
"brand": "Mastercard",
"name": "COMPANY_KEY - Physical"
},
"status": "ENABLED"
}
],
"address":{
"zipCode":"68060100",
"addressLine":"Rua 6 de Março",
"number":"2500",
"neighborhood":"Alter do Chão",
"complement":"Apartamento",
"city":"Santarém",
"state":"PA",
"country":"BR"
},
"holder":{
"document":{
"value":"47742663023",
"type":"CPF"
},
"name":"Nísia Floresta",
"phone": {
"countryCode": "55",
"number": "23415162342"
}
},
"embosser":{
"factory":"TestCard",
"fileName":"ACESSO20221230_275.txt",
"embossedAt":"2022-12-30T01:10:41Z",
"customFields": {
"plasticCode": "0000"
}
},
"expirationDate": "2030-03-31"
}
}TRACKING_STATUS_CHANGED
Este evento sinaliza que houve uma atualização no status de rastreio.
Descrição do objeto data do evento
data do eventoO objeto data traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:
| Nome | Tipo | Descrição |
|---|---|---|
card | object | Objeto que contém informações sobre o cartão. |
card.proxy | string | Código identificador do cartão. |
card.alias | string | Apelido definido pelo proprietário do cartão. |
externalTracking | object | Objeto que contém informações sobre a transportadora responsável pela entrega do cartão. Este objeto somente será enviado caso o operador logístico terceirize a entrega do cartão. |
externalTracking.code | string | Código de rastreio proveniente da transportadora. |
externalTracking.partner | string | Nome da transportadora. |
estimatedDeliveryDate | string | Data de entrega estimada, no formato ISO 8601 - UTC. |
status | object | Objeto que contém informações sobre o histórico dos status desde a criação do cartão até a entrega ao destinatário. |
status.type | string | Status de rastreio do cartão . |
status.reason | string | Descrição do status de rastreio. |
finalized | object | Objeto que contém informações sobre quem recebeu o cartão e o número de tentativas de entrega. Objeto retornado apenas após a entrega do cartão (status "Delivered"). |
finalized.recipient | object | Objeto que contém informações sobre quem recebeu o cartão. |
finalized.recipient.name | string | Nome do recebedor do cartão. |
finalized.recipient.kinship | string | Relacionamento do titular do cartão com a pessoa que o recebeu. |
finalized.recipient.document | object | Objeto que contém informações sobre o documento do recebedor do cartão. |
finalized.recipient.document.type | string | Tipo do documento, que pode ser “CPF” ou “CNPJ”. |
finalized.recipient.document.number | string | Número do documento. |
finalized.recipient.attempts | integer | Número de tentativas de entrega realizadas. |
NotaNo caso do evento
TRACKING_STATUS_CHANGED, oentityIdé o código de rastreio gerado pelo Bankly para ser utilizado pelo operador logístico. O seu valor não é retornado no objetodatado payload, somente no campoentityIdpresente no cabeçalho do evento.
Payloads do evento
Os payloads abaixo exemplificam a estrutura do evento que deverá ser recebido pelo parceiro. Clique na seta para expandi-los:
Exemplos de payloads
{
"companyKey": "companyKey",
"context": "Card",
"entityId": "24906A3D54FC",
"name": "TRACKING_STATUS_CHANGED",
"correlationId": "7a1bfc3f-50e6-458c-aa9b-d42a22ddb84d",
"timestamp": "2025-02-06T10:08:38.476Z",
"metadata": {
"created": "2025-02-06T10:08:37.868Z",
"modified": "2025-02-06T10:08:37.868Z"
},
"data": {
"card": {
"proxy": "2229141009436273825",
"alias": "Nísia Floresta"
},
"estimatedDeliveryDate": "2025-02-21T23:59:59.000Z",
"status": {
"reason": "Waiting for post",
"type": "Created"
}
}
}{
"entityId": "24906A3D54FC",
"idempotencyKey": "86447d19-687f-4fa8-80cf-a5aa406457b9",
"companyKey": "companyKey",
"version": "1",
"context": "Card",
"name": "TRACKING_STATUS_CHANGED",
"timestamp": "2021-10-06T13:07:25.3853601Z",
"correlationId": "7a1bfc3f-50e6-458c-aa9b-d42a22ddb84d",
"metadata": {
"created": "2021-11-10T20:40:24.282+00:00",
"modified": "2021-11-18T20:40:24.282+00:00"
},
"data": {
"card": {
"proxy": "2229141009436273825",
"alias": "Nísia Floresta"
},
"externalTracking": {
"code": "111",
"partner": "CORREIOS"
},
"estimatedDeliveryDate": "2021-11-25T23:59:59.282+00:00",
"status": {
"type": "InProgress",
"reason": "Object on the way"
}
}
}{
"entityId": "24906A3D54FC",
"idempotencyKey": "86447d19-687f-4fa8-80cf-a5aa406457b9",
"companyKey": "companyKey",
"version": "1",
"context": "Card",
"name": "TRACKING_STATUS_CHANGED",
"timestamp": "2021-10-06T13:07:25.3853601Z",
"correlationId": "7a1bfc3f-50e6-458c-aa9b-d42a22ddb84d",
"metadata": {
"created": "2021-11-10T20:40:24.282+00:00",
"modified": "2021-11-18T20:40:24.282+00:00"
},
"data": {
"card": {
"proxy": "2229141009436273825",
"alias": "Nísia Floresta"
},
"externalTracking": {
"code": "111",
"partner": "CORREIOS"
},
"estimatedDeliveryDate": "2021-11-25T23:59:59.282+00:00",
"status": {
"type": "Delivered",
"reason": "Object delivered"
},
"finalized": {
"recipient": {
"name": "Maria Quitéria de Jesus",
"kinship": "Mãe",
"document": {
"type": "CPF",
"number": "09992220074"
}
},
"attempts": 1
}
}
}{
"companyKey": "companyKey",
"context": "Card",
"entityId": "24906A3D54FC",
"name": "TRACKING_STATUS_CHANGED",
"correlationId": "7a1bfc3f-50e6-458c-aa9b-d42a22ddb84d",
"timestamp": "2025-02-07T02:18:55.535Z",
"metadata": {
"created": "2025-02-01T14:28:33.071Z",
"modified": "2025-02-06T11:29:50.169Z"
},
"data": {
"card": {
"proxy": "2229141009436273825",
"alias": "Nísia Floresta"
},
"estimatedDeliveryDate": "2025-02-14T23:59:59.000Z",
"status": {
"reason": "Out",
"type": "NotDelivered"
}
}
}{
"companyKey": "companyKey",
"context": "Card",
"entityId": "24906A3D54FC",
"name": "TRACKING_STATUS_CHANGED",
"correlationId": "7a1bfc3f-50e6-458c-aa9b-d42a22ddb84d",
"timestamp": "2025-02-16T02:15:43.209Z",
"metadata": {
"created": "2025-02-10T22:01:35.136Z",
"modified": "2025-02-14T19:41:19.426Z"
},
"data": {
"card": {
"proxy": "2229141009436273825",
"alias": "Nísia Floresta"
},
"estimatedDeliveryDate": "2025-02-21T23:59:59.000Z",
"status": {
"reason": "Waiting action",
"type": "Custody"
}
}
}{
"entityId": "24906A3D54FC",
"idempotencyKey": "86447d19-687f-4fa8-80cf-a5aa406457b9",
"companyKey": "companyKey",
"version": "1",
"context": "Card",
"name": "TRACKING_STATUS_CHANGED",
"timestamp": "2021-10-06T13:07:25.3853601Z",
"correlationId": "7a1bfc3f-50e6-458c-aa9b-d42a22ddb84d",
"metadata": {
"created": "2021-11-10T20:40:24.282+00:00",
"modified": "2021-11-18T20:40:24.282+00:00"
},
"data": {
"card": {
"proxy": "2229141009436273825",
"alias": "Nísia Floresta"
},
"estimatedDeliveryDate": "2021-11-25T23:59:59.282+00:00",
"status": {
"type": "InProgress",
"reason": "Object on the way"
}
}
}{
"entityId": "24906A3D54FC",
"idempotencyKey": "86447d19-687f-4fa8-80cf-a5aa406457b9",
"companyKey": "companyKey",
"version": "1",
"context": "Card",
"name": "TRACKING_STATUS_CHANGED",
"timestamp": "2021-10-06T13:07:25.3853601Z",
"correlationId": "7a1bfc3f-50e6-458c-aa9b-d42a22ddb84d",
"metadata": {
"created": "2021-11-10T20:40:24.282+00:00",
"modified": "2021-11-18T20:40:24.282+00:00"
},
"data": {
"card": {
"proxy": "2229141009436273825",
"alias": "Nísia Floresta"
},
"estimatedDeliveryDate": "2021-11-25T23:59:59.282+00:00",
"status": {
"type": "Delivered",
"reason": "Object delivered"
},
"finalized": {
"recipient": {
"name": "Maria Quitéria de Jesus",
"kinship": "Mãe",
"document": {
"type": "CPF",
"number": "09992220074"
}
},
"attempts": 1
}
}
}{
"companyKey": "BANCO_DIGITAL_BCO_BV",
"context": "Card",
"entityId": "PI000058125BR",
"name": "TRACKING_STATUS_CHANGED",
"correlationId": "d44c8283-1762-4c6b-bbcc-561c1399b3c5",
"timestamp": "2025-03-11T01:02:50.9698317Z",
"metadata": {
"created": "2025-03-10T23:01:40.219Z",
"modified": "2025-03-11T01:02:50.969Z"
},
"data": {
"card": {
"proxy": "2234626770402896338",
"alias": "Cartão corporativo"
},
"estimatedDeliveryDate": "2025-03-27T20:59:59.000Z",
"status": {
"reason": "Waiting for post",
"type": "Building"
}
}
}TRACKING_STATUS_SEND_HISTORY
Este evento é disparado em conjunto com o TRACKING_STATUS_CHANGED, após a atualização do status de rastreio do cartão emitido, e informa detalhes sobre o histórico completo dos seus status, desde a sua criação até a entrega ao destinatário, ordenados do mais recente para o mais antigo.
Descrição do objeto data do evento
O objeto data traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:
| Nome | Tipo | Descrição | Número máximo de caracteres |
|---|---|---|---|
card | object | Objeto que contém informações sobre o cartão que sofreu alteração em seu status de rastreio. | — |
card.proxy | string | Código identificador do cartão. | — |
card.alias | string | Apelido do cartão. | — |
estimateDeliveryDate | string | Data de entrega estimada. Importante: este campo só será retornado quando o cartão ainda não tiver sido entregue. | — |
status[] | array of objects | Lista de objetos com o histórico dos status desde a criação do cartão até a entrega ao destinatário, do mais recente para o mais antigo. | — |
status[].reason | string | Lista de possíveis reasons. | — |
status[].type | string | Tipo ou nome dos status em que se encontra o cartão criado. Consulte a lista de possíveis type para mais detalhes. | — |
address[] | array of objects | Lista de objetos contendo informações sobre os endereços de entrega cadastrados pelo titular do cartão. Importante: ao cadastrar um novo endereço de entrega, ele será exibido nesta lista. | — |
address[].address | string | Logradouro (nome da rua, avenida etc.). | — |
address[].number | string | Número do imóvel. | — |
address[].neighboorhood | string | Nome do bairro. | — |
address[].complement | string | Complemento do endereço (quando houver). | — |
address[].city | string | Nome da cidade. | — |
address[].state | string | Sigla do estado brasileiro conforme a ISO 3166-2:BR. Exemplo: SP. | — |
address[].country | string | Sigla do país (Brasil) conforme a ISO 3166-2. Exemplo: BR. | — |
address[].createdDate | string | Data e hora da inserção do endereço de entrega na base de dados, no formato ISO 8601 - UTC. | — |
address[].isActive | boolean | Indica se o endereço está habilitado para entrega, sendo "true" para ativo e "false" para inativo. | — |
address[].zipCode | string | Código postal do endereço. | — |
Payload do evento
O payload abaixo exemplifica a estrutura do evento que deverá ser recebido pelo parceiro. Clique na seta para expandi-lo:
Exemplo de payload
{
"companyKey": "FLORESTA_ED",
"context": "Card",
"entityId": "RGKXSTS31942",
"name": "TRACKING_STATUS_SEND_HISTORY",
"correlationId": "28cad10c-8b11-4e34-bfdb-467f891bb656",
"idempotencyKey": "bed33c52-716b-4204-9bde-99c0daab1137",
"timestamp": "2024-04-15T12:48:49.149Z",
"metadata": {
"created": "2024-04-12T19:44:45.078Z",
"modified": "2024-04-15T12:48:19.602Z"
},
"data": {
"card": {
"proxy": "2234626776444794789",
"alias": "Gastos corporativos"
},
"estimatedDeliveryDate": "2024-04-26T23:59:59.000Z",
"status": [
{
"reason": "Sent to ship company",
"type": "Building"
},
{
"reason": "Object delivered",
"type": "Delivered"
},
{
"reason": "In route to delivery",
"type": "InProgress"
},
{
"reason": "Received by the shipping company",
"type": "InProgress"
},
{
"reason": "Building completed",
"type": "Building"
},
{
"reason": "Waiting for post",
"type": "Created"
}
],
"address": [
{
"address": "Rua 6 de Março",
"number": "2500",
"neighborhood": "Alter do Chão",
"complement": "",
"city": "Santarém",
"state": "PA",
"country": "BR",
"createdDate": "2024-04-12T19:44:46.026Z",
"isActive": true,
"zipCode": "68060100"
}
]
}
}CARD_STATUS_WAS_MODIFIED
Este evento sinaliza que o status do cartão foi alterado.
Descrição do objeto data do evento
data do eventoO objeto data traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:
| Nome | Tipo | Descrição |
|---|---|---|
proxy | string | Código identificador do cartão. |
status | string | Status atual 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. |
statusPrevious | string | Status anterior 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. |
Payload do evento
O payload abaixo exemplifica a estrutura do evento que deverá ser recebido pelo parceiro. Clique na seta para expandi-lo:
Exemplo de payload
{
"idempotencyKey": "423f240d-539e-4f4c-9f1b-05cb4d7a819a",
"context": "Card",
"name": "CARD_STATUS_WAS_MODIFIED",
"timestamp": "2022-07-11T17:31:21.9632827Z",
"entityId": "234026100039584752",
"companyKey": "companyKey",
"correlationId": "10d5aad9-4de4-4f96-903e-6816d30e043a",
"version": "1",
"metadata": {
"updatedAt": "2022-07-11T17:31:21.5238611Z"
},
"data": {
"proxy": "234026100039584752",
"status": "CanceledByCustomer",
"statusPrevious": "Active"
}
}
ImportanteEste evento não é disparado quando o status do cartão se altera de Building para Active ou de Building para InTransitLocked, pois esses cenários já são contemplados pelo evento de emissão de cartão.
CARD_EXPIRATION_DATE_IS_APPROACHING
Este evento sinaliza a quantidade de dias restantes para um cartão expirar.
Descrição do objeto data do evento
data do eventoO objeto data traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:
| 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. |
trackingCode | string | Código de rastreio do cartão. Campo retornado apenas para cartões físicos. |
alias | string | Apelido dado ao cartão. |
name | string | Nome gravado no cartão, também conhecido como nome de embossing. |
program | object | Objeto que contém informações sobre o programa escolhido pelo parceiro. |
program.id | string | Identificador do programa, o qual é passado no momento da emissão do cartão. |
program.type | string | Tipo de programa. Para emissão de cartão avulso, os mais comuns são: “PhysicalPre”, “VirtualPre” e "Pos", que dizem respeito ao pré-pago físico/virtual e pós-pago físico, respectivamente. Se a emissão for feita em lote, há mais duas opções disponíveis: "LotPre" e "LotPos". |
program.bin | string | O 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. |
program.brand | string | Bandeira do cartão. |
program.name | string | Nome cadastral do programa definido no Bankly, o qual segue o padrão o qual segue o padrão “COMPANYKEY_PRODUTO_FISICO/VIRTUAL”. |
lastFourDigits | string | Quatro últimos dígitos do cartão. |
cardType | string | Tipo do cartão, que pode ser “Physical” ou “Virtual”. |
status | string | Status do cartão. Exemplos: “Active”, “Building”, “Sleeping”, “Inactive”, dentre outros. Confira a tabela com os possíveis status reversíveis e irreversíveis na página Possíveis status do cartão. |
function | string | Função do cartão, que pode ser “Pre”, “Pos” ou “Debit”. |
allowContactless | boolean | Indica se é permitido pagamento por aproximação. |
functionalities[] | array of objects | Lista de objetos contendo informações sobre as funcionalidades do cartão. |
functionalities[].type | string | Tipo de funcionalidade 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 funcionalidade está vinculada. |
functionalities[].program.id | number | Identificador único do programa. |
functionalities[].program.bin | string | O 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.type | string | Tipo do programa que define a modalidade do cartão. |
functionalities[].program.brand | string | Bandeira do cartão. |
functionalities[].program.name | string | Nome cadastral do programa definido no Bankly, o qual segue o padrão o qual segue o padrão “COMPANYKEY_PRODUTO_FISICO/VIRTUAL”. |
functionalities[].status | string | Status da modalidade, que pode ser “Enabled" (ativado), "Disabled" (desativado), "Blocked" (bloqueado) e “BlockedByContract" (bloqueado por contrato). |
address | object | Objeto que contém informações sobre o endereço comercial ou residencial do titular do cartão. |
address.ziCode | string | Código postal do endereço. |
address.addressLine | 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. |
holder | object | Objeto que contém informações sobre o 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. |
holder.document.type | string | Tipo do documento, que pode ser “CPF” ou “CNPJ”. |
holder.name | string | Nome cadastrado. |
holder.phone | object | Objeto que contém informações sobre o telefone do titular do cartão. |
holder.phone.countryCode | string | Código DDI do país. |
holder.phone.number | string | Número de telefone incluindo DDD. |
credit | object | Objeto que contém informações sobre sobre o contrato de crédito. Campo retornado apenas para cartões do tipo pós, quando já há um contrato. |
credit.contractNumber | string | Número do contrato de crédito. |
credit.limitTotal | object | Objeto que contém informações sobre o limite total disponibilizado no contrato. |
credit.limitTotal.value | number | Valor do total disponibilizado no contrato. |
credit.limitTotal.currency | string | Código da moeda com base na ISO 4217. Exemplo: “BRL”. |
batch | object | Objeto que contém informação sobre o lote que originou o cartão. Esse objeto somente será retornado caso o cartão tenha sido emitido dentro de um lote. |
batch.id | string | Identificador único do lote. |
previousCard | object | Objeto que contém informação sobre a via anterior deste cartão. Esse objeto somente será retornado em caso de segunda via (cartão físico). |
previousCard.proxy | string | Código identificador do cartão da via anterior. |
previousCard.purpose | string | Razão da nova emissão (”Duplicate”). |
previousCard.cancellation | object | Objeto que contém informações sobre o cancelamento da via anterior do cartão. |
previousCard.cancellation.mode | string | Momento de cancelamento da primeira via, que pode ser “Immediately” (cancelamento imediato), “Later” (cancelamento tardio), “CanceledAlready” (cartão já cancelado). |
previousCard.cancellation.proxy | string | Código identificador do cartão a ser cancelado. Importante: caso este campo retorne null ou não seja enviado, considere o valor retornado no campo previousCard.proxy. |
previousCard.cancellation.reason | string | Motivo pelo qual a via anterior do cartão foi ou será cancelada. |
expirationDate | string | Data de expiração do cartão, no formato "yyyy-MM-dd" . |
Payload do evento
Os payloads abaixo exemplificam a estrutura do evento que deverá ser recebido pelo parceiro. Clique na seta para expandi-los:
Exemplos de payloads
{
"idempotencyKey": "0c908f19-6a3e-4a0b-90aa-606d9a659dfb",
"context": "Card",
"name": "CARD_WAS_ISSUED",
"timestamp": "2022-04-25T12:27:24.1773777Z",
"entityId": "2500441005128861608",
"companyKey": "COMPANY_KEY",
"correlationId": "496b8b38-c956-415a-8668-c21cd146285b",
"metadata": {
"created": "2022-04-25T12:27:04.294+00:00"
},
"data": {
"proxy": "0000000000000000000",
"activateCode": "A49000000095",
"trackingCode": "JRDRVSQ00000",
"alias": "0422",
"name": "Nísia Floresta",
"program": {
"id": "53",
"type": "Pre",
"bin": "123456",
"brand": "Mastercard",
"name": "COMPANY_KEY - Physical"
},
"lastFourDigits": "0000",
"cardType": "Physical",
"status": "Active",
"function": "Pre",
"allowContactless": true,
"functionalities": [
{
"type": "Pre",
"program": {
"id": 53,
"bin": "234028",
"type": "PhysicalPre",
"brand": "Mastercard",
"name": "COMPANY_KEY - Physical"
},
"status": "ENABLED"
}
],
"address": {
"zipCode": "68060100",
"addressLine": "Rua 6 de Março",
"number": "2500",
"neighborhood": "Alter do Chão",
"complement": "Apartamento",
"city": "Santarém",
"state": "PA",
"country": "BR"
},
"holder": {
"document": {
"value": "47742663023",
"type": "CPF"
},
"name": "Nísia Floresta",
"phone": {
"countryCode": "55",
"number": "23415162342"
}
},
"expirationDate": "2030-03-31"
}
} {
"idempotencyKey": "0c908f19-6a3e-4a0b-90aa-606d9a659dfb",
"context": "Card",
"name": "CARD_WAS_ISSUED",
"timestamp": "2022-04-25T12:27:24.1773777Z",
"entityId": "2500441005128861608",
"companyKey": "COMPANY_KEY",
"correlationId": "496b8b38-c956-415a-8668-c21cd146285b",
"metadata": {
"created": "2022-04-25T12:27:04.294+00:00"
},
"data": {
"proxy": "0000000000000000000",
"activateCode": "A49000000095",
"trackingCode": "JRDRVSQ00000",
"alias": "0422",
"name": "Nísia Floresta",
"program": {
"id": "53",
"type": "Pos",
"bin": "123456",
"brand": "Mastercard",
"name": "COMPANY_KEY - Physical"
},
"lastFourDigits": "0000",
"cardType": "Physical",
"status": "Active",
"function": "Pos",
"allowContactless": true,
"functionalities": [
{
"type": "Pos",
"program": {
"id": 53,
"bin": "234028",
"type": "Pos",
"brand": "Mastercard",
"name": "COMPANY_KEY - Physical"
},
"status": "ENABLED"
}
],
"address": {
"zipCode": "68060100",
"addressLine": "Rua 6 de Março",
"number": "2500",
"neighborhood": "Alter do Chão",
"complement": "Apartamento",
"city": "Santarém",
"state": "PA",
"country": "BR"
},
"holder": {
"document": {
"value": "47742663023",
"type": "CPF"
},
"name": "Nísia Floresta",
"phone": {
"countryCode": "55",
"number": "23415162342"
}
},
"credit": {
"contractNumber": "123458696-",
"limitTotal": {
"value": 123,
"currency": "BRL"
}
},
"expirationDate": "2030-03-31"
}
}{
"idempotencyKey": "0c908f19-6a3e-4a0b-90aa-606d9a659dfb",
"context": "Card",
"name": "CARD_WAS_ISSUED",
"timestamp": "2022-04-25T12:27:24.1773777Z",
"entityId": "2500441005128861608",
"companyKey": "COMPANY_KEY",
"correlationId": "496b8b38-c956-415a-8668-c21cd146285b",
"metadata": {
"created": "2022-04-25T12:27:04.294+00:00"
},
"data": {
"proxy": "0000000000000000000",
"activateCode": "A49000000095",
"trackingCode": "JRDRVSQ00000",
"alias": "0422",
"name": "Nísia Floresta",
"program": {
"id": "53",
"type": "LotPre",
"bin": "123456",
"brand": "Mastercard",
"name": "COMPANY_KEY - Physical"
},
"lastFourDigits": "0000",
"cardType": "Physical",
"status": "Active",
"function": "Pre",
"allowContactless": true,
"functionalities": [
{
"type": "Pre",
"program": {
"id": 53,
"bin": "234028",
"type": "Pre",
"brand": "Mastercard",
"name": "COMPANY_KEY - Physical"
},
"status": "ENABLED"
}
],
"address": {
"zipCode": "68060100",
"addressLine": "Rua 6 de Março",
"number": "2500",
"neighborhood": "Alter do Chão",
"complement": "Apartamento",
"city": "Santarém",
"state": "PA",
"country": "BR"
},
"holder": {
"document": {
"value": "47742663023",
"type": "CPF"
},
"name": "Nísia Floresta",
"phone": {
"countryCode": "55",
"number": "23415162342"
}
},
"batch": {
"id": "LT023432982"
}
},
"expirationDate": "2030-03-31"
}{
"idempotencyKey": "0c908f19-6a3e-4a0b-90aa-606d9a659dfb",
"context": "Card",
"name": "CARD_WAS_ISSUED",
"timestamp": "2022-04-25T12:27:24.1773777Z",
"entityId": "2500441005128861608",
"companyKey": "COMPANY_KEY",
"correlationId": "496b8b38-c956-415a-8668-c21cd146285b",
"metadata": {
"created": "2022-04-25T12:27:04.294+00:00"
},
"data": {
"proxy": "0000000000000000000",
"activateCode": "A49000000095",
"trackingCode": "JRDRVSQ00000",
"alias": "0422",
"name": "Nísia Floresta",
"program": {
"id": "53",
"type": "Pre",
"bin": "123456",
"brand": "Mastercard",
"name": "COMPANY_KEY - Physical"
},
"lastFourDigits": "0000",
"cardType": "Physical",
"status": "Active",
"function": "Pre",
"allowContactless": true,
"functionalities": [
{
"type": "Pre",
"program": {
"id": 53,
"bin": "234028",
"type": "Pre",
"brand": "Mastercard",
"name": "COMPANY_KEY - Physical"
},
"status": "ENABLED"
}
],
"address": {
"zipCode": "68060100",
"addressLine": "Rua 6 de Março",
"number": "2500",
"neighborhood": "Alter do Chão",
"complement": "Apartamento",
"city": "Santarém",
"state": "PA",
"country": "BR"
},
"holder": {
"document": {
"value": "47742663023",
"type": "CPF"
},
"name": "Nísia Floresta",
"phone": {
"countryCode": "55",
"number": "23415162342"
}
},
"previousCard": {
"proxy": "1111111111111111111",
"purpose": "Duplicate",
"cancellation": {
"mode": "Immediately",
"proxy": "1111111111111111111",
"reason": "CardDamagedCanceled"
}
},
"expirationDate": "2030-03-31"
}
}{
"idempotencyKey": "0c908f19-6a3e-4a0b-90aa-606d9a659dfb",
"context": "Card",
"name": "CARD_WAS_ISSUED",
"timestamp": "2022-04-25T12:27:24.1773777Z",
"entityId": "2500441005128861608",
"companyKey": "COMPANY_KEY",
"correlationId": "496b8b38-c956-415a-8668-c21cd146285b",
"metadata": {
"created": "2022-04-25T12:27:04.294+00:00"
},
"data": {
"proxy": "0000000000000000000",
"activateCode": "A49000000095",
"trackingCode": "JRDRVSQ00000",
"alias": "0422",
"name": "Nísia Floresta",
"program": {
"id": "53",
"type": "Pos",
"bin": "123456",
"brand": "Mastercard",
"name": "COMPANY_KEY - Physical"
},
"lastFourDigits": "0000",
"cardType": "Physical",
"status": "Active",
"function": "Pos",
"allowContactless": true,
"functionalities": [
{
"type": "Pos",
"program": {
"id": 53,
"bin": "234028",
"type": "Pos",
"brand": "Mastercard",
"name": "COMPANY_KEY - Physical"
},
"status": "ENABLED"
}
],
"address": {
"zipCode": "68060100",
"addressLine": "Rua 6 de Março",
"number": "2500",
"neighborhood": "Alter do Chão",
"complement": "Apartamento",
"city": "Santarém",
"state": "PA",
"country": "BR"
},
"holder": {
"document": {
"value": "47742663023",
"type": "CPF"
},
"name": "Nísia Floresta",
"phone": {
"countryCode": "55",
"number": "23415162342"
}
},
"credit": {
"contractNumber": "123458696-",
"limitTotal": {
"value": 123,
"currency": "BRL"
}
},
"previousCard": {
"proxy": "1111111111111111111",
"purpose": "Duplicate",
"cancellation": {
"mode": "Immediately",
"proxy": "1111111111111111111",
"reason": "CardDamagedCanceled"
}
},
"expirationDate": "2030-03-31"
}
}
ImportanteEste evento não é disparado quando o cartão é cancelado antes da expiração, ou quando uma nova via já tenha sido solicitada.
COMPLETE_TOKEN_WAS_PROCESSED
Este evento sinaliza que a solicitação de inclusão do cartão na carteira digital foi processada. O evento será enviado para o fluxo InApp para a carteira do Google e para ativação de token via central de atendimento.
Descrição do objeto data do evento
data do eventoO objeto data traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:
| Nome | Tipo | Descrição |
|---|---|---|
proxy | string | Proxy do cartão. |
status | string | Status do processamento do token ("SUCCESS" ou "FAILED"). |
errorCode | string | Código de erro retornado quando o status é "FAILED" (ex: "WALLET_TOKENS_NOT_FOUND"). Presente apenas em caso de falha. |
holder | object | Objeto que contém informações sobre o titular do cartão. |
holder.name | string | Nome do portador do cartão. |
holder.document | object | Objeto que contém informações sobre o documento do titular. |
holder.document.value | string | Número do documento do portador. |
holder.document.type | string | Tipo do documento (ex: "CPF"). |
wallet | object | Objeto que contém informações sobre a carteira digital utilizada. |
wallet.walletType | string | Tipo da carteira digital (ex: "GooglePay"). |
wallet.walletFlow | string | Fluxo da carteira utilizado (ex: "GreenPatch"). |
wallet.tokenId | string | Identificador do token na carteira digital. |
Payload do evento
Os payloads abaixo exemplificam a estrutura do evento que deverá ser recebido pelo parceiro. Clique na seta para expandi-los:
Exemplo de payload
{
"name": "COMPLETE_TOKEN_WAS_PROCESSED",
"context": "Card",
"timestamp": "2026-01-05T15:08:55.1869211Z",
"entityId": "715cd1bc-9e67-4a60-89c4-088e5f3ed702",
"companyKey": "ACESSO",
"correlationId": "de776b39-d798-4ee4-bac7-e85ff1590da9",
"idempotencyKey": "5d33b93d-d018-4895-81f2-48689b46a2cd",
"version": "1",
"data": {
"proxy": "2234626770330213111",
"status": "SUCCESS",
"holder": {
"name": "Nísia Floresta",
"document": {
"value": "47742663023",
"type": "CPF"
}
},
"wallet": {
"walletType": "GooglePay",
"walletFlow": "GreenPatch",
"tokenId": "7891011"
}
}
}{
"name": "COMPLETE_TOKEN_WAS_PROCESSED",
"context": "Card",
"timestamp": "2026-01-05T15:08:55.1869211Z",
"entityId": "715cd1bc-9e67-4a60-89c4-088e5f3ed702",
"companyKey": "ACESSO",
"correlationId": "de776b39-d798-4ee4-bac7-e85ff1590da9",
"idempotencyKey": "5d33b93d-d018-4895-81f2-48689b46a2cd",
"version": "1",
"data": {
"proxy": "2234626770330213111",
"status": "FAILED",
"errorCode": "WALLET_TOKENS_NOT_FOUND",
"holder": {
"name": "Nísia Floresta",
"document": {
"value": "47742663023",
"type": "CPF"
}
},
"wallet": {
"walletType": "GooglePay",
"walletFlow": "GreenPatch",
"tokenId": "7891011"
}
}
}CARD_WAS_ADDED_TO_WALLET
Este evento sinaliza que o cartão foi adicionado na carteira digital.
Descrição do objeto data do evento
data do eventoO objeto data traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:
| Nome | Tipo | Descrição |
|---|---|---|
proxy | string | Proxy do cartão. |
program | object | Objeto que contém informações sobre o programa escolhido pelo parceiro. |
program.id | string | Identificador do programa. |
program.name | string | Nome do programa. |
program.bin | string | BIN do programa. |
program.brand | string | Bandeira do cartão. |
program.type | string | Tipo do programa (ex: "Debit"). |
program.product | object | Objeto que contém informações sobre o produto do programa. |
program.product.type | string | Tipo do produto (ex: "PLATINUM"). |
lastFourDigits | string | Últimos quatro dígitos do cartão. |
cardType | string | Tipo do cartão (ex: "Physical"). |
function | string | Função do cartão (ex: "Combo"). |
allowContactless | boolean | Indica se o cartão permite pagamento por aproximação. |
holder | object | Objeto que contém informações sobre o titular do cartão. |
holder.document | object | Objeto que contém informações sobre o documento do titular. |
holder.document.value | string | Número do documento do portador. |
holder.document.type | string | Tipo do documento (ex: "CPF"). |
holder.name | string | Nome do portador do cartão. |
holder.account | object | Objeto que contém informações sobre a conta do titular do cartão. |
holder.account.branch | string | Agência da conta. |
holder.account.number | string | Número da conta. |
holder.account.bank | object | Objeto que contém informações sobre o banco ao qual a conta pertence. |
holder.account.bank.ispb | string | ISPB do banco. |
holder.account.bank.code | string | Código do banco. |
holder.account.bank.name | string | Nome do banco. |
holder.account.isExternalBankingCore | boolean | Indica se utiliza core bancário externo. |
holder.phone | object | Objeto que contém informações sobre o telefone do titular do cartão. |
holder.phone.countryCode | string | Código do país do telefone. |
holder.phone.number | string | Número de telefone do portador. |
wallet | object | Objeto que contém informações sobre a carteira digital utilizada. |
wallet.walletType | string | Tipo da carteira digital (ex: "GooglePay"). |
wallet.walletFlow | string | Fluxo da carteira utilizado (ex: "GreenPatch"). |
wallet.tokenId | string | Identificador do token na carteira digital. |
wallet.tokenOperational | string | Tipo operacional do token (ex: "TC"). |
wallet.transferToken | boolean | Indica se houve transferência de token. |
DicaPara mais informações sobre o fluxo de adição de cartão à wallet, consulte a documentação Carteiras digitais.
Payload do evento
O payload abaixo exemplifica a estrutura do evento que deverá ser recebido pelo parceiro. Clique na seta para expandi-lo:
Exemplo de payload
{
"name": "CARD_WAS_ADDED_TO_WALLET",
"context": "Card",
"timestamp": "2026-05-14T14:29:58.492235Z",
"entityId": "2307261007671435083",
"companyKey": "ACESSO",
"correlationId": "358f90a6-3aa6-4873-95d8-74f35165e14d",
"idempotencyKey": "25293d90-7b22-420a-851e-d90d2114d734",
"version": "1",
"metadata": {
"created": "2026-05-14T11:29:58.4767769-03:00"
},
"data": {
"proxy": "2307261007671435083",
"program": {
"id": "210",
"name": "Debit Stg",
"bin": "230721",
"brand": "Mastercard",
"type": "Debit",
"product": {
"type": "PLATINUM"
}
},
"lastFourDigits": "7858",
"cardType": "Physical",
"function": "Combo",
"allowContactless": true,
"holder": {
"document": {
"value": "89343243170",
"type": "CPF"
},
"name": "Ana Costa",
"account": {
"branch": "0001",
"number": "1105540690",
"bank": {
"ispb": "13140088",
"code": "332",
"name": "ACESSO SOLUÇÕES DE PAGAMENTO S.A. - INSTITUIÇÃO DE PAGAMENTO"
},
"isExternalBankingCore": true
},
"phone": {
"countryCode": "55",
"number": "11945658877"
}
},
"wallet": {
"walletType": "GooglePay",
"walletFlow": "GreenPatch",
"tokenId": "7891011",
"tokenOperational": "TC",
"transferToken": true
}
}
}CARD_WAS_CHECKED_TO_WALLET`
Este evento sinaliza que a bandeira realizou a validação do cartão que está iniciando o processo de tokenização e identificou que ele está elegível para tokenização.
Descrição do objeto data do evento
O objeto data traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:
| Nome | Tipo | Descrição |
|---|---|---|
proxy | string | Proxy do cartão. |
program | object | Objeto que contém informações sobre o programa escolhido pelo parceiro. |
program.id | string | Identificador do programa. |
program.name | string | Nome do programa. |
program.bin | string | BIN do programa. |
program.brand | string | Bandeira do cartão. |
program.type | string | Tipo do programa (ex: "Debit"). |
lastFourDigits | string | Últimos quatro dígitos do cartão. |
cardType | string | Tipo do cartão (ex: "Physical"). |
function | string | Função do cartão (ex: "Combo"). |
allowContactless | boolean | Indica se o cartão permite pagamento por aproximação. |
holder | object | Objeto que contém informações sobre o titular do cartão. |
holder.document | object | Objeto que contém informações sobre o documento do titular. |
holder.document.value | string | Número do documento do portador. |
holder.document.type | string | Tipo do documento (ex: "CPF"). |
holder.name | string | Nome do portador do cartão. |
holder.account | object | Objeto que contém informações sobre a conta do titular do cartão. |
holder.account.branch | string | Agência da conta. |
holder.account.number | string | Número da conta. |
holder.account.bank | object | Objeto que contém informações sobre o banco ao qual a conta pertence. |
holder.account.bank.ispb | string | ISPB do banco. |
holder.account.bank.code | string | Código do banco. |
holder.account.bank.name | string | Nome do banco. |
holder.account.isExternalBankingCore | boolean | Indica se utiliza core bancário externo. |
holder.phone | object | Objeto que contém informações sobre o telefone do titular do cartão. |
holder.phone.countryCode | string | Código do país do telefone. |
holder.phone.number | string | Número de telefone do portador. |
wallet | object | Objeto que contém informações sobre a carteira digital utilizada. |
wallet.walletType | string | Tipo da carteira digital (ex: "GooglePay"). |
wallet.walletFlow | string | Fluxo da carteira utilizado (ex: "GreenPatch"). |
wallet.tokenId | string | Identificador do token na carteira digital. |
wallet.tokenOperarion ⚠️ | string | Tipo da operação do token (ex: "TE"). Confirmar se não é tokenOperational, como nos eventos irmãos. |
Payload do evento
O payload abaixo exemplifica a estrutura do evento que deverá ser recebido pelo parceiro. Clique na seta para expandi-lo:
Exemplo de payload
{
"name": "CARD_WAS_CHECKED_TO_WALLET",
"context": "Card",
"timestamp": "2026-05-14T14:29:58.492235Z",
"entityId": "2307261007671435083",
"companyKey": "ACESSO",
"correlationId": "358f90a6-3aa6-4873-95d8-74f35165e14d",
"idempotencyKey": "25293d90-7b22-420a-851e-d90d2114d734",
"version": "1",
"metadata": {
"created": "2026-05-14T11:29:58.4767769-03:00"
},
"data": {
"proxy": "2307261007671435083",
"program": {
"id": "210",
"name": "Debit Stg",
"bin": "230721",
"brand": "Mastercard",
"type": "Debit"
},
"lastFourDigits": "7858",
"cardType": "Physical",
"function": "Combo",
"allowContactless": true,
"holder": {
"document": {
"value": "89343243170",
"type": "CPF"
},
"name": "Ana Costa",
"account": {
"branch": "0001",
"number": "1105540690",
"bank": {
"ispb": "13140088",
"code": "332",
"name": "ACESSO SOLUÇÕES DE PAGAMENTO S.A. - INSTITUIÇÃO DE PAGAMENTO"
},
"isExternalBankingCore": true
},
"phone": {
"countryCode": "55",
"number": "11945658877"
}
},
"wallet": {
"walletType": "GooglePay",
"walletFlow": "GreenPatch",
"tokenId": "7891011",
"tokenOperarion": "TE"
}
},
"licenses": [
{
"id": "24ac71da-4309-4348-9cc0-a0c88f867993",
"provider": "ACESSO SOLUÇÕES DE PAGAMENTO S.A. - INSTITUIÇÃO DE PAGAMENTO",
"types": [
"Banking"
]
},
{
"id": "81273063-f558-4cc2-a46f-3d2d245753d8",
"provider": "ACESSO SOLUÇÕES DE PAGAMENTO S.A. - INSTITUIÇÃO DE PAGAMENTO",
"types": [
"Credit"
]
}
]
}CARD_WAS_REMOVED_FROM_WALLET
Este evento sinaliza que o cartão foi removido da carteira digital.
Descrição do objeto data do evento
data do eventoO objeto data traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:
| Nome | Tipo | Descrição |
|---|---|---|
proxy | string | Proxy do cartão. |
program | object | Objeto que contém informações sobre o programa escolhido pelo parceiro. |
program.id | string | Identificador do programa. |
program.name | string | Nome do programa. |
program.bin | string | BIN do programa. |
program.brand | string | Bandeira do cartão. |
program.type | string | Tipo do programa (ex: "Debit"). |
program.product | object | Objeto que contém informações sobre o produto do programa. |
program.product.type | string | Tipo do produto (ex: "PLATINUM"). |
lastFourDigits | string | Últimos quatro dígitos do cartão. |
cardType | string | Tipo do cartão (ex: "Physical"). |
function | string | Função do cartão (ex: "Combo"). |
allowContactless | boolean | Indica se o cartão permite pagamento por aproximação. |
holder | object | Objeto que contém informações sobre o titular do cartão. |
holder.document | object | Objeto que contém informações sobre o documento do titular. |
holder.document.value | string | Número do documento do portador. |
holder.document.type | string | Tipo do documento (ex: "CPF"). |
holder.name | string | Nome do portador do cartão. |
holder.account | object | Objeto que contém informações sobre a conta do titular do cartão. |
holder.account.branch | string | Agência da conta. |
holder.account.number | string | Número da conta. |
holder.account.bank | object | Objeto que contém informações sobre o banco ao qual a conta pertence. |
holder.account.bank.ispb | string | ISPB do banco. |
holder.account.bank.code | string | Código do banco. |
holder.account.bank.name | string | Nome do banco. |
holder.account.isExternalBankingCore | boolean | Indica se utiliza core bancário externo. |
holder.phone | object | Objeto que contém informações sobre o telefone do titular do cartão. |
holder.phone.countryCode | string | Código do país do telefone. |
holder.phone.number | string | Número de telefone do portador. |
wallet | object | Objeto que contém informações sobre a carteira digital utilizada. |
wallet.walletType | string | Tipo da carteira digital (ex: "GooglePay"). |
wallet.walletFlow | string | Fluxo da carteira utilizado (ex: "GreenPatch"). |
wallet.tokenId | string | Identificador do token na carteira digital. |
wallet.status | string | Status do token na carteira ("3" ou "4"). |
wallet.tokenOperational | string | Tipo operacional do token (ex: "TV"). |
Descrição do objeto raiz licenses (fora de data)
| Nome | Tipo | Descrição |
|---|---|---|
licenses | array | Lista de licenças associadas ao evento. |
licenses[].id | string | Identificador da licença (UUID). |
licenses[].provider | string | Nome do provedor da licença. |
licenses[].types | array of strings | Tipos de licença (ex: "Banking", "Credit"). |
Payload do evento
O payload abaixo exemplifica a estrutura do evento que deverá ser recebido pelo parceiro. Clique na seta para expandi-lo:
Exemplo de payload
{
"name": "CARD_WAS_REMOVED_FROM_WALLET",
"context": "Card",
"timestamp": "2026-05-14T14:29:58.492235Z",
"entityId": "2307261007671435083",
"companyKey": "ACESSO",
"correlationId": "358f90a6-3aa6-4873-95d8-74f35165e14d",
"idempotencyKey": "25293d90-7b22-420a-851e-d90d2114d734",
"version": "1",
"metadata": {
"created": "2026-05-14T11:29:58.4767769-03:00"
},
"data": {
"proxy": "2307261007671435083",
"program": {
"id": "210",
"name": "Debit Stg",
"bin": "230721",
"brand": "Mastercard",
"type": "Debit",
"product": {
"type": "PLATINUM"
}
},
"lastFourDigits": "7858",
"cardType": "Physical",
"function": "Combo",
"allowContactless": true,
"holder": {
"document": {
"value": "89343243170",
"type": "CPF"
},
"name": "Ana Costa",
"account": {
"branch": "0001",
"number": "1105540690",
"bank": {
"ispb": "13140088",
"code": "332",
"name": "ACESSO SOLUÇÕES DE PAGAMENTO S.A. - INSTITUIÇÃO DE PAGAMENTO"
},
"isExternalBankingCore": true
},
"phone": {
"countryCode": "55",
"number": "11945658877"
}
},
"wallet": {
"walletType": "GooglePay",
"walletFlow": "GreenPatch",
"tokenId": "7891011",
"status": "3",
"tokenOperational": "TV"
}
},
"licenses": [
{
"id": "24ac71da-4309-4348-9cc0-a0c88f867993",
"provider": "ACESSO SOLUÇÕES DE PAGAMENTO S.A. - INSTITUIÇÃO DE PAGAMENTO",
"types": [
"Banking"
]
},
{
"id": "81273063-f558-4cc2-a46f-3d2d245753d8",
"provider": "ACESSO SOLUÇÕES DE PAGAMENTO S.A. - INSTITUIÇÃO DE PAGAMENTO",
"types": [
"Credit"
]
}
]
}CARD_WALLET_TOKENIZATION_WAS_BLOCKED
Esse evento sinaliza que o cartão foi bloqueado temporariamente para inclusão em carteiras digitais.
Descrição do objeto data do evento
data do eventoO objeto data traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:
| Nome | Tipo | Descrição | Número máximo de caracteres |
|---|---|---|---|
proxy | string | Identificador do cartão. | 31 |
reason | string | Motivo relacionado ao tipo de bloqueio realizado. | — |
startedAt | string | Data e a hora de início do bloqueio, no formato ISO 8601 - UTC. | — |
endsAt | string | Se o motivo do bloqueio for “InvalidCVVLimitExceeded”, esse campo retornará a data e a hora de término do bloqueio, no formato ISO 8601 - UTC. Caso contrário, esse campo virá como null ou não será retornado. | — |
Exemplo de payload
{
"name": "CARD_WALLET_TOKENIZATION_WAS_BLOCKED",
"idempotencyKey": "914e0649-034f-4fb2-b20a-d87422c863cd",
"context": "Card",
"timestamp": "2022-12-30T01:11:07.4151363Z",
"entityId": "2500441000000000001",
"companyKey": "TESTE",
"correlationId": "5ba3cd76-53bf-4cc4-8ba2-eea0fb1b1071",
"version": "1",
"metadata": {
"capturedAt": "2022-12-30T01:11:07.4019873Z"
},
"data": {
"proxy": "2500441000000000001",
"reason": "InvalidCVVLimitExceeded",
"startedAt": "2022-12-30T01:11:07.4019873Z",
"endsAt": "2022-12-30T01:11:07.4019873Z"
}
}CARD_FUNCTION_WAS_MODIFIED
Esse evento sinaliza que um cartão do tipo combo teve o status de uma de suas modalidades (débito ou crédito) alterado.
Descrição do objeto data do evento
data do eventoO objeto data traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:
| Nome | Tipo | Descrição | Número máximo de caracteres |
|---|---|---|---|
type | string | Tipo de modalidade que sofreu alteração de status, que pode ser "Pos" ou "Debit". | — |
program | object | Objeto que contém informações sobre o programa no qual a modalidade do cartão está vinculada. | — |
program.id | int | Identificador do programa. | — |
program.bin | string | O 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. | 8 |
program.name | string | Nome cadastral do programa definido no Bankly, o qual segue o padrão “COMPANYKEY_PRODUTO_FISICO/VIRTUAL”. | — |
program.brand | string | Bandeira do cartão. | — |
program.type | string | Tipo do programa que define a modalidade do cartão. | — |
status | string | Campo que informa o status da modalidade . | — |
Payload do evento
O payload abaixo exemplifica a estrutura do evento que deverá ser recebido pelo parceiro. Clique na seta para expandi-lo:
Exemplo de payload
[
{
"name": "CARD_FUNCTION_WAS_MODIFIED",
"idempotencyKey": "914e0649-034f-4fb2-b20a-d87422c863cd",
"context": "Card",
"timestamp": "2022-12-30T01:11:07.4151363Z",
"entityId": "2500441000000000001",
"companyKey": "TESTE",
"correlationId": "5ba3cd76-53bf-4cc4-8ba2-eea0fb1b1071",
"version": 2,
"metadata": {
"capturedAt": "2022-12-30T01:11:07.4019873Z"
},
"data": {
"type": "Pos",
"program": {
"id": 123,
"bin": "23306100",
"type": "Combo",
"name": "COMPANY_KEY - Physical",
"brand": "Mastercard"
},
"status": "Blocked"
}
}
]CARD_WAS_BINDED_WITH_NEW_ACCOUNT
Esse evento sinaliza que um cartão do tipo combo foi vinculado a uma conta bancária.
Descrição do objeto data do evento
data do eventoO objeto data traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:
| Nome | Tipo | Descrição |
|---|---|---|
proxy | string | Código identificador do cartão. |
proxyAuthorizer | string | Código que reúne proxy, agência e conta, utilizado internamente pelo autorizador. |
activateCode | string | Código atrelado ao cartão no momento de sua emissão. |
trackingCode | string | Código de rastreio do cartão. Campo retornado apenas para cartões físicos. |
alias | string | Apelido definido pelo proprietário para o cartão. |
name | string | Nome gravado no cartão, também conhecido como nome de embossing. |
program | object | Objeto que contém informações sobre o programa escolhido pelo parceiro. |
program.id | string | Identificador do programa, o qual é passado no momento da emissão do cartão. |
program.type | string | Tipo de programa. Para emissão de cartão avulso, os mais comuns são: “PhysicalPre”, “VirtualPre” e "Pos", que dizem respeito ao pré-pago físico/virtual e pós-pago físico, respectivamente. Se a emissão for feita em lote, há mais duas opções disponíveis: "LotPre" e "LotPos". |
program.bin | string | O 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. |
program.brand | string | Bandeira do cartão. |
program.name | string | Nome cadastral do programa definido no Bankly, o qual segue o padrão o qual segue o padrão “COMPANYKEY_PRODUTO_FISICO/VIRTUAL”. |
lastFourDigits | string | Quatro últimos dígitos do cartão. |
cardType | string | Tipo do cartão, que pode ser “Physical” ou “Virtual”. |
status | string | Status do cartão. Exemplos: “Active”, “Building”, “Sleeping”, “Inactive”, dentre outros. Confira a tabela com os possíveis status reversíveis e irreversíveis na página Possíveis status do cartão. |
function | string | Função do cartão, que neste caso, será “Combo”. |
allowContactless | boolean | Indica se é permitido pagamento por aproximação (true) ou não (false). |
functionalities[] | array of objects | Lista de objetos contendo informações sobre as funcionalidades do cartão. |
functionalities[].type | string | Tipo de funcionalidade associada ao cartão, que nesse caso é “Debit e Pos". |
functionalities[].program | object | Objeto que contém informações sobre o programa ao qual a funcionalidade está vinculada. |
functionalities[].program.id | number | Identificador único do programa. |
functionalities[].program.bin | string | O 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.type | string | Tipo do programa que define a modalidade do cartão. |
functionalities[].program.brand | string | Bandeira do cartão. |
functionalities[].program.name | string | Nome cadastral do programa definido no Bankly, o qual segue o padrão o qual segue o padrão “COMPANYKEY_PRODUTO_FISICO/VIRTUAL”. |
functionalities[].status | string | Situação da modalidade, que pode ser “Enabled" (ativado), "Disabled" (desativado), "Blocked" (bloqueado) e “BlockedByContract" (bloqueado por contrato). |
address | object | Objeto que contém informações sobre o endereço comercial ou residencial do titular do cartão. |
address.ziCode | string | Código postal do endereço. |
address.addressLine | 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. |
holder | object | Objeto que contém informações sobre o 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. |
holder.document.type | string | Tipo do documento, que pode ser “CPF” ou “CNPJ”. |
holder.name | string | Nome cadastrado. |
holder.account | object | Objeto que contém informações sobre a conta do titular do cartão. |
holder.account.branch | string | Número da agência. |
holder.account.number | string | Número da conta. |
holder.account.isExternalBankingCode | boolean | Indicador de utilização de core bancário externo. |
holder.account.bank | object | Objeto que contém informações sobre o banco ao qual a conta do titular do cartão pertence. |
holder.account.bank.ispb | string | ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco. |
holder.account.bank.code | string | Código do banco. |
holder.account.bank.name | string | Nome do banco. |
holder.phone | object | Objeto que contém informações sobre o telefone do titular do cartão. |
holder.phone.countryCode | string | Código DDI do país. |
holder.phone.number | string | Número de telefone incluindo DDD. |
credit | object | Objeto que contém informações sobre sobre o contrato de crédito. Campo retornado apenas para cartões do tipo pós, quando já há um contrato. |
credit.contractNumber | string | Número do contrato de crédito. |
credit.limitTotal | object | Objeto que contém informações sobre o limite total disponibilizado no contrato. |
credit.limitTotal.value | number | Valor do total disponibilizado no contrato. |
credit.limitTotal.currency | string | Código da moeda com base na ISO 4217. Exemplos: “BRL”. |
previousCard | object | Objeto que contém informação sobre a via anterior deste cartão. Esse objeto somente será retornado em caso de segunda via (cartão físico). |
previousCard.proxy | string | Código identificador do cartão da via anterior. |
previousCard.purpose | string | Razão da nova emissão (”Duplicate”). |
previousCard.cancellation | object | Objeto que contém informações sobre o cancelamento da via anterior do cartão. |
previousCard.cancellation.mode | string | Momento de cancelamento da primeira via, que pode ser “Immediately” (cancelamento imediato), “Later” (cancelamento tardio), “CanceledAlready” (cartão já cancelado). |
previousCard.cancellation.proxy | string | Código identificador do cartão a ser cancelado. Importante: caso este campo retorne null ou não seja enviado, considere o valor retornado no campo previousCard.proxy. |
previousCard.cancellation.reason | string | Motivo pelo qual a via anterior do cartão foi ou será cancelada. |
expirationDate | string | Data de expiração do cartão, no formato "yyyy-MM-dd" . |
Exemplo de payload
{
"name": "CARD_WAS_BINDED_WITH_NEW_ACCOUNT",
"context": "Card",
"timestamp": "2025-12-08T18:33:26.580858Z",
"entityId": "2234626783306571343",
"companyKey": "SDB_BV",
"correlationId": "6309846d-2025-4c4c-89de-07b8e4b5829d",
"idempotencyKey": "c29e94ec-9b78-4ede-93ff-244e87d0ba13",
"version": "1",
"licenseUuid": "b4f5f6d3-5f4e-4c2a-9f7e-1d2c3b4a5e6f",
"licenses": [
{
"id": "b4f5f6d3-5f4e-4c2a-9f7e-1d2c3b4a5e6f",
"provider": "BANCO BV S.A",
"types": [
"Credit",
"Banking",
"Investment",
"Funding"
]
}
],
"metadata": {
"updateBinded": "2025-12-08T18:33:26.5205932Z"
},
"data": {
"proxy": "2234626783306571343",
"proxyAuthorizer": "2234626783306571343_0001_621500754",
"activateCode": "3017D1202F24",
"trackingCode": "PI000003673BR",
"alias": "CARD NAME TESTE",
"name": "CARD NAME TESTE",
"program": {
"id": "833",
"name": "Teste_BV_MAIS_COMBO_",
"bin": "22346267",
"brand": "Mastercard",
"type": "Combo",
"product": {
"type": "BLACK",
"additionalInfo": ""
}
},
"lastFourDigits": "8818",
"cardType": "Physical",
"status": "InTransitLocked",
"function": "Combo",
"allowContactless": true,
"isAdditional": false,
"address": {
"zipCode": "04236094",
"addressLine": "Rua 2 de Fevereiro",
"number": "20",
"neighborhood": "Cidade Nova Heliópol",
"complement": "casa 1",
"city": "São Paulo",
"state": "SP",
"country": "BR"
},
"holder": {
"document": {
"value": "72426454334",
"type": "CPF"
},
"name": "CARD NAME TESTE",
"account": {
"branch": "0001",
"number": "621500754",
"status": "Active",
"bank": {
"ispb": "13140088",
"code": "332",
"name": "ACESSO SOLUÇÕES DE PAGAMENTO S.A. - INSTITUIÇÃO DE PAGAMENTO"
},
"isExternalBankingCore": true
},
"phone": {
"countryCode": "55",
"number": "11999777024"
}
},
"credit": {
"contractNumber": "995236",
"limitTotal": {
"value": 1000.0,
"currency": "BRL"
}
},
"embosser": {
"factory": "Valid",
"fileName": "ACESSO20250915193849_00016287.txt",
"embossedAt": "2025-09-15T19:39:04Z",
"customFields": {
"plasticCode": "1060"
}
},
"batch": {
"id": "BATCH_001"
},
"functionalities": [
{
"type": "Pos",
"program": {
"id": "833",
"name": "Teste_BV_MAIS_COMBO_",
"bin": "22346267",
"brand": "Mastercard",
"type": "Combo",
"product": {
"type": "BLACK",
"additionalInfo": ""
}
},
"status": "Enabled"
},
{
"type": "Debit",
"program": {
"id": "831",
"name": "Teste_BV_MAIS_DÉBITO_",
"bin": "22346267",
"brand": "Mastercard",
"type": "Debit",
"product": {
"type": "BLACK",
"additionalInfo": ""
}
},
"status": "Enabled"
}
],
"expirationDate": "2030-04-30",
"previousCard": {
"proxy": "2234626783306571342",
"purpose": "Duplicate",
"cancellation": {
"mode": "Default",
"proxy": "2234626783306571334",
"cardStatus": "UseFraudCanceled"
}
}
}
}
CARD_LIMIT_ACTIVE_WAS_MODIFIED
Esse evento sinaliza que o limite de crédito ativo de um cartão foi alterado.
Descrição do objeto data do evento
data do eventoO objeto data traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:
| Nome | Tipo | Descrição |
|---|---|---|
proxy | string | Código identificador do cartão. |
contract | string | Número do contrato de crédito associado ao cartão. |
limit | object | Objeto que contém informações sobre o limite de crédito do cartão. |
total | object | Objeto que contém informações sobre o limite de crédito total autorizado para o cartão. |
value | string | Valor do limite de crédito total autorizado para o cartão. |
currency | string | Código da moeda com base na ISO 4217. Exemplo: “BRL”. |
previousActive | object | Objeto que contém informações sobre o limite de crédito ativo do cartão antes da alteração. |
value | string | Valor do limite de crédito ativo do cartão antes da alteração. |
currency | string | Código da moeda com base na ISO 4217. Exemplo: “BRL”. |
active | object | Objeto que contém informações sobre o limite de crédito ativo do cartão após a alteração. |
value | string | Valor do limite de crédito ativo do cartão após a alteração. |
currency | string | Código da moeda com base na ISO 4217. Exemplo: “BRL”. |
changeOrigin | string | Origem da alteração do limite de crédito ativo, que pode ser ByContract (situação em que a alteração do limite de crédito total autorizado impactou o limite de crédito ativo) ou ByCustomer (situação em que o portador do cartão solicitou alteração em seu limite de crédito ativo). |
Payload do evento
O payload abaixo exemplifica a estrutura do evento que deverá ser recebido pelo parceiro. Clique na seta para expandi-lo:
Exemplo de payload
{
"name": "CARD_LIMIT_ACTIVE_WAS_MODIFIED",
"context": "Card",
"timestamp": "2026-01-28T14:57:31.888048Z",
"entityId": "2307261009073348600",
"companyKey": "ACESSO",
"correlationId": "9c777cb7-c411-4ea5-bf81-8b11a6835893",
"idempotencyKey": "914db9f5-c609-45fe-98f8-7cfa906fae76",
"version": "1",
"metadata": {
"updatedAt": "2026-01-28T11:26:13.817-03:00"
},
"data": {
"proxy": "2307261009073348600",
"contract": "1015130",
"limit": {
"total": {
"value": 3000.0,
"currency": "BRL"
},
"previousActive": {
"value": 2219.0,
"currency": "BRL"
},
"active": {
"value": 3000.0,
"currency": "BRL"
},
"changeOrigin": "ByContract"
}
},
} Tabelas para consulta
Tipos de carteiras
| Código | Descrição |
|---|---|
| 101 | MasterpassByMastercard |
| 103 | ApplePay |
| 216 | GooglePay |
| 217 | SamsungPay |
| 327 | MerchantTokenizationProgram |
| 0 | Unknown |
| 00 | Unknown |
Tipos de bloqueio para inclusão em carteiras digitais
reason | Descrição |
|---|---|
| InvalidCVVLimitExceeded | O valor do CVV foi informado pelo cliente incorretamente por cinco vezes consecutivas. |
Status da modalidade
| Status | Descrição |
|---|---|
| Enabled | Habilitada. |
| Disabled | Modalidade desabilitada definitivamente. Ela não pode ser ativada pelo endpoint de alteração de status modalidade. Sua desativação acontece por meio de processos automatizados, como o cancelamento de contrato de crédito. |
| Blocked | Modalidade bloqueada temporariamente por meio do endpoint de Alteração de status modalidade. |
| BlockedByContract | A modalidade está bloqueada temporariamente por conta de um bloqueio no contrato. |
productType
productType- CLASSIC_NACIONAL
- CLASSIC_INTERNACIONAL
- GOLD
- PLATINUM
- INFINITE
- ELECTRON
- STANDARD_NACIONAL
- STANDARD_INTERNACIONAL
- ELETRONIC
- BLACK
- REDESHOP
- MAESTRO_MASTERCARD_MAESTRO
- GREEN
- BLUE
- BLUEBOX
- PROFISSIONAL_LIBERAL
- CHEQUE_ELETRONICO
- CORPORATIVO
- EMPRESARIAL
- COMPRAS
- BASICO_NACIONAL
- BASICO_INTERNACIONAL
- NANQUIM
- GRAFITE
- MAIS
- OUTROS
Updated 11 days ago
Did this page help you?