Cartão (Card)

Os eventos referentes à cartão disparam mensagens ao destinatário quando:

O cartão é emitido;
O status de rastreio do cartão é alterado;
O status do cartão é alterado;
O cartão é adicionado ou removido da carteira;

Para mais informações sobre quando essas mensagens são disparadas e sobre o seu conteúdo, consulte as páginas:

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`	`TRACKING_STATUS_CHANGED`	Houve uma atualização no status de rastreio.
`Card`	`CARD_STATUS_WAS_MODIFIED`	O status do cartão foi alterado.
`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.

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:

📘
Nota
O 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").

Identificador (`entityId`)

O campo entityId é o identificador da entidade emissora do evento e seu valor depende do contexto de sua emissão, conforme a tabela a seguir:

Evento	Identificador (entityId )	Descrição
`CARD_WAS_ISSUED`	`proxy`	Código identificador do cartão.
`TRACKING_STATUS_CHANGED`	---	Código de rastreio do cartão.
`CARD_STATUS_WAS_MODIFIED`	`proxy`	Código identificador do cartão.
`CARD_WAS_ADDED_TO_WALLET`	`proxy`	Código identificador do cartão.
`CARD_WAS_REMOVED_FROM_WALLET`	`proxy`	Código identificador do cartão.

📘
Nota
No caso do evento TRACKING_STATUS_CHANGED, o entityId é o código de rastreio gerado pelo Bankly para ser utilizado pelo operador logístico. O seu valor não é retornado no objeto data do payload, somente no campo entityId presente 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

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`	Código identificador do cartão.
`proxyAuthorizer`	`string`	Junção de 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.
`alias`	`string`	Apelido definido pelo proprietário do 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.name`	`string`	Nome do programa, o qual segue o padrão “COMPANYKEY_PRODUTO_FISICO/VIRTUAL”.
`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`	Número de identificação bancária, que corresponde aos seis ou oito primeiros dígitos do cartão.
`lastFourDigits`	`string`	Quatro últimos dígitos do cartão.
`cardType`	`string`	Tipo do cartão, o qual pode ser “Physical” ou “Virtual”.
`status`	`string`	Situação 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, a qual pode ser: “Pre”, “Pos” ou “Debit”.
`allowContactless`	`boolean`	Indica se é permitido pagamento por aproximação.
`functionalities[]`	`array of objects`	Lista de objetos contendo todas as funcionalidades do cartão emitido.
`functionalities[].type`	`string`	Função associada ao cartão, a qual pode ser: “Pre”, “Pos” ou “Debit”.
`functionalities[].program`	`object`	Objeto que contém informações sobre o programa ao qual a funcionalidade está vinculada.
`functionalities[].program.id`	`string`	Identificador do programa.
`functionalities[].program.bin`	`string`	Número de identificação bancária, que corresponde aos seis ou oito primeiros dígitos do cartão.
`functionalities[].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".
`functionalities[].status`	`string`	Situação da função, a qual pode ser “Enabled” (Habilitada), “Disabled” (Desabilitada) e “Blocked” (Bloqueada).
`address`	`object`	Objeto que contém os dados do 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 prédio ou da casa.
`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, o qual pode ser “CPF” ou “CNPJ”.
`holder.name`	`string`	Nome cadastrado.
`holder.account`	`object`	Objeto que contém os dados da conta do titular do cartão. Ele somente será retornado em caso de emissão de cartão avulso, sendo ele 1ª ou 2ª via.
`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 os dados do banco ao qual a conta 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`	Identificador internacional (DDI).
`holder.phone.number`	`string`	Número do telefone (incluindo DDD).
`credit`	`object`	Objeto que contém informações sobre o contrato de crédito. Ele somente será retornado em caso de emissão de cartão avulso pós-pago, sendo ele 1ª ou 2ª via.
`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 total disponibilizado no contrato.
`credit.limitTotal.currency`	`string`	Sigla da moeda utilizada com base na ISO-4217.
`batch`	`object`	Objeto que contém informação sobre o lote que originou o cartão. Ele 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 o cartão da via anterior. Ele somente será retornado em caso de emissão de segunda via.
`previousCard.proxy`	`string`	Código identificador do cartão da via anterior.

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 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",
         "proxyAuthorizer": "0000000000000000000_0000_000000000",
         "activateCode": "A49000000095",
         "trackingCode": "YHITCTK45852",
         "alias": "0422",
         "name": "Nísia Floresta",
         "program": {
            "id": "53",
            "name": "COMPANY_KEY - Virtual",
            "bin": "234260",
            "type": "Pre"
         },
         "lastFourDigits": "0000",
         "cardType": "Physical",
         "status": "Active",
         "function": "Pre",
         "allowContactless": true,
         "functionalities": [
          {
          	"type": "Pre",
            "program": {
              "id": 53,
              "bin": "234260",
              "type": "PhysicalPre"
            },
            "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",
            "account": {
               "branch": "0001",
               "number": "15164",
               "bank": {
                    "ispb": "13140088",
                    "code": "332",
                    "name": "ACESSO SOLUÇÕES DE PAGAMENTO S.A. - INSTITUIÇÃO DE PAGAMENTO"
                }
            },
            "phone": {
              "countryCode": "55",
              "number": "11956583971"
            }
         }
      }
   }
]

[
  {
    "idempotencyKey": "0c908f9-6a3e-4a0b-90aa-606d9a659dfb",
    "context": "Card",
    "name": "CARD_WAS_ISSUED",
    "timestamp": "2022-04-25T12:27:24.1773777Z",
    "entityId": "250044100128861608",
    "companyKey": "COMPANY_KEY",
    "correlationId": "496b8b38-c956-415a-8668-c21cd146285b",
    "metadata": {
      "created": "2022-04-25T12:27:04.294+00:00"
    },
    "data": {
      "proxy": "0000000000000000000",
      "proxyAuthorizer": "0000000000000000000_0000_000000000",
      "activateCode": "A4900000095",
      "trackingCode": "JRDRVSQ00000",
      "alias": "0422",
      "name": "Nísia Floresta",
      "program": {
        "id": "53",
        "name": "COMPANY_KEY - Fisico",
        "type": "Pos",
        "bin": "234028"
      },
      "lastFourDigits": "0000",
      "cardType": "Physical",
      "status": "Active",
      "function": "Pos",
      "allowContactless": true,
      "functionalities": [
        {
	      "type": "Pos",
          "program": {
            "id": 53,
            "bin": "234260",
            "type": "Pos"
          },
          "status": "ENABLED"
        }
      ],
      "address": {
        "zipCode": "05037001",
        "addressLine": "Rua 6 de Março",
        "number": "2500",
        "neighborhood": "Alter do Chão",
        "complement": "",
        "city": "Santarém",
        "state": "PA",
        "country": "BR"
      },
      "holder": {
        "document": {
          "value": "00000000000",
          "type": "CPF"
        },
        "name": "Nísia Floresta",
        "account": {
          "branch": "0001",
          "number": "15XYZ",
          "bank": {
            "ispb": "13140088",
            "code": "332",
            "name": "ACESSO SOLUÇÕES DE PAGAMENTO S.A. - INSTITUIÇÃO DE PAGAMENTO"
          }
        },
        "phone": {
	      	"countryCode": "55",
		  		"number": "11956583971"
        }
      },
      "credit": {
        "contractNumber": string,
        "limitTotal": {
          "value": 150.00,
          "currency": string
        }
      }
    }
  }
]

[
 {
	"name": "CARD_WAS_ISSUED",
	"idempotencyKey": "1647fe9d-c70c-46f0-84c8-fcc6fcdd55d4",
	"context": "Card",
	"timestamp": "2023-11-09T01:29:15.5601596Z",
	"entityId": "1369321000051271873",
	"companyKey": "COMPANY_KEY",
	"correlationId": "d1032a24-ef7e-44d0-805c-8136dac85068",
	"version": "1",
	"metadata": {
		"created": "2023-11-09T01:28:56.792+00:00"
	},
	"data": {
		"proxy": "1369321000051271873",
		"activateCode": "0088D97D817A",
		"trackingCode": "YHRMQLX15136",
		"alias": "N9HS2E58",
		"name": "Customer No Name",
		"program": {
			"id": "165",
			"name": "AUTOMATED_TESTS_LotPre",
			"bin": "136932",
			"type": "LotPre"
		},
		"lastFourDigits": "3397",
		"cardType": "Physical",
		"status": "Sleeping",
		"function": "Pre",
		"allowContactless": true,
		"address": {
			"zipCode": "08285080",
			"addressLine": "Rua Rafael Fernandes",
			"number": "123",
			"neighborhood": "asdf",
			"city": "Sao Paulo",
			"state": "SP",
			"country": "Brasil"
		},
		"holder": {
			"document": {
				"value": "00000000000",
				"type": "CPF"
			},
			"name": "Customer No Name",
			"phone": {
				"countryCode": "55",
				"number": "1138942300"
			}
		},
		"batch": {
			"id": "LT393"
		},
		"functionalities": [
			{
				"type": "Pre",
				"program": {
					"id": "165",
					"bin": "136932",
					"type": "LotPre"
				},
				"status": "Enabled"
			}
		]
	}
 }
]

[
   {
      "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",
         "proxyAuthorizer": "0000000000000000000_0000_000000000",
         "activateCode": "A49000000095",
         "trackingCode": "YHITCTK45852",
         "alias": "0422",
         "name": "Nísia Floresta",
         "program": {
            "id": "53",
            "name": "COMPANY_KEY - Físico",
            "bin": "234260",
            "type": "PhysicalPre"
         },
         "lastFourDigits": "0000",
         "cardType": "Pysical",
         "status": "Active",
         "function": "Pre",
         "allowContactless": true,
         "functionalities": [
          {
          	"type": "Pre",
            "program": {
              "id": 53,
              "bin": "234260",
              "type": "PhysicalPre"
            },
            "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",
            "account": {
               "branch": "0001",
               "number": "15164",
               "bank": {
                    "ispb": "13140088",
                    "code": "332",
                    "name": "ACESSO SOLUÇÕES DE PAGAMENTO S.A. - INSTITUIÇÃO DE PAGAMENTO"
                }
            },
            "phone": {
              "countryCode": "55",
              "number": "11956583971"
            }
         },
         "previousCard": {
            "proxy": "1111111111111111111"
         }
      }
   }
]

[
   {
      "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",
         "proxyAuthorizer": "0000000000000000000_0000_000000000",
         "activateCode": "A49000000095",
         "trackingCode": "YHITCTK45852",
         "alias": "0422",
         "name": "Nísia Floresta",
         "program": {
            "id": "53",
            "name": "COMPANY_KEY - Físico",
            "bin": "234260",
            "type": "Pos"
         },
         "lastFourDigits": "0000",
         "cardType": "Pysical",
         "status": "Active",
         "function": "Pos",
         "allowContactless": true,
         "functionalities": [
          {
          	"type": "Pos",
            "program": {
              "id": 53,
              "bin": "234260",
              "type": "Pos"
            },
            "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",
            "account": {
               "branch": "0001",
               "number": "15164",
               "bank": {
                    "ispb": "13140088",
                    "code": "332",
                    "name": "ACESSO SOLUÇÕES DE PAGAMENTO S.A. - INSTITUIÇÃO DE PAGAMENTO"
                }
            },
            "phone": {
              "countryCode": "55",
              "number": "11956583971"
            }
         },
         "credit": {
        	 "contractNumber": string,
        	 "limitTotal": {
          	 "value": 150.00,
          	 "currency": string
           }
         },
         "previousCard": {
            "proxy": "1111111111111111111"
         }
      }
   }
]

TRACKING_STATUS_CHANGED

Este evento sinaliza que houve uma atualização no status de rastreio.

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
`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 yyyy-MM-dd'T'HH:mm:ss.SSS.
`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`	Situação do transporte do cartão. Consulte a lista completa dos status de rastreio no final da página.
`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, o qual pode ser “CPF” ou “CNPJ”.
`finalized.recipient.document.number`	`string`	Número do documento.
`finalized.recipient.attempts`	`int`	Número de tentativas de entrega realizadas.

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 payloads

[
   {
      "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
         }
      }
   }
]

[
   {
      "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
         }
      }
   }
]

CARD_STATUS_WAS_MODIFIED

Este evento sinaliza que o status do cartão foi alterado.

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`	Código identificador do cartão.
`status`	`string`	Situação 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`	Situação prévia 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"
      }
   }
]

⚠️
Importante
Este 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_WAS_ADDED_TO_WALLET

Este evento sinaliza que o cartão foi adicionado na carteira digital.

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`	Código identificador do cartão.
`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. Os mais comuns são: “PhysicalPre” e “VirtualPre”, que dizem respeito ao pré-pago físico e virtual, respectivamente.
`lastFourDigits`	`string`	Quatro últimos dígitos do cartão.
`cardType`	`string`	Tipo do cartão, o qual pode ser “Physical” ou “Virtual”.
`function`	`string`	Função do cartão, a qual pode ser: “Pre”, “Pos” ou “Debit”.
`allowContactless`	`boolean`	Indica se é permitido 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 do cartão.
`holder.document.value`	`string`	Número do documento.
`holder.document.type`	`string`	Tipo de documento, o qual pode ser “CPF ou “CNPJ”.
`holder.name`	`string`	Nome cadastrado.
`holder.account`	`object`	Objeto que contém informações sobre a conta bancária do titular do cartão.
`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 os dados do banco ao qual a conta 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.
`wallet`	`object`	Objeto que contém informações sobre a carteira na qual o cartão foi adicionado.
`wallet.walletType`	`string`	Tipo de carteira. Consulte a tabela com os tipos de carteiras no final da página.
`wallet.walletFlow`	`string`	Classificação do fluxo utilizado para colocar o cartão na wallet. Os fluxos são: YellowPatch (o cliente adiciona o cartão pela própria carteira da Google, Apple, Samsung etc.) e GreenPatch (o cliente usa o aplicativo do parceiro para iniciar a tokenização do cartão na carteira).

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",
      "idempotencyKey": "6706ad77-1993-4d2a-8ccf-b270aa650131",
      "context": "Card",
      "timestamp": "2022-11-30T19:42:26.0102699Z",
      "entityId": "2500011000044122120",
      "companyKey": "companyKey",
      "correlationId": "e08de8bf-b2c8-4616-9255-63e5bf84dff3",
      "version": 1,
      "metadata": {
         "created": "2022-11-30T19:42:21.394653+00:00"
      },
      "data": {
         "proxy": "2500011000044122120",
         "program": {
            "id": "92",
            "type": "LotPre"
         },
         "lastFourDigits": "7288",
         "cardType": "Physical",
         "function": "Pre",
         "allowContactless": true,
         "holder": {
            "document": {
               "value": "47742663023",
               "type": "CPF"
            },
            "name": "Nísia Floresta",
            "account": {
               "branch": "0001",
               "number": "15164",
               "bank": {
                    "ispb": "13140088",
                    "code": "332",
                    "name": "ACESSO SOLUÇÕES DE PAGAMENTO S.A. - INSTITUIÇÃO DE PAGAMENTO"
                }
            }
         },
         "wallet": {
            "walletType": "GooglePay",
            "walletFlow": "GreenPatch"
         }
      }
   }
]

CARD_WAS_REMOVED_FROM_WALLET

Este evento sinaliza que o cartão foi removido da carteira digital.

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`	Código identificador do cartão.
`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. Os mais comuns são: “PhysicalPre” e “VirtualPre”, que dizem respeito ao pré-pago físico e virtual, respectivamente.
`lastFourDigits`	`string`	Quatro últimos dígitos do cartão.
`cardType`	`string`	Tipo do cartão, o qual pode ser: “Physical” ou “Virtual”.
`function`	`string`	Função do cartão, a qual pode ser: “Pre”, “Pos” ou “Debit”.
`allowContactless`	`boolean`	Informa se é permitido pagamento por aproximação.
`holder`	`object`	Objeto que contém informações do titular da fatura.
`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 de documento, o qual pode ser “CPF ou “CNPJ”.
`holder.name`	`string`	Nome cadastrado.
`holder.account`	`object`	Objeto que contém informações sobre a conta bancária do titular.
`holder.account.branch`	`string`	Número da agência.
`holder.account.number`	`string`	Número da conta.
`wallet`	`object`	Objeto que contém informações sobre a carteira na qual o cartão foi adicionado.
`wallet.walletType`	`string`	Tipo de carteira. Consulte a tabela com os tipos de carteiras no final da página.
`wallet.walletFlow`	`string`	Classificação do fluxo utilizado para colocar o cartão na wallet. Os fluxos são: YellowPatch (o cliente adiciona o cartão pela própria carteira da Google, Apple, Samsung etc.) e GreenPatch (o cliente usa o aplicativo do parceiro para iniciar a tokenização do cartão na carteira).

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",
      "idempotencyKey": "be214c89-354e-424b-8c27-fb482a969105",
      "context": "Card",
      "timestamp": "2022-11-30T19:41:23.3574876Z",
      "entityId": "2500011000044122120",
      "companyKey": "companyKey",
      "correlationId": "e08de8bf-b2c8-4616-9255-63e5bf84dff3",
      "version": 1,
      "metadata": {
         "created": "2022-11-30T19:41:10.1212513+00:00"
      },
      "data": {
         "proxy": "2500011000044122120",
         "program": {
            "id": "92",
            "type": "LotPre"
         },
         "lastFourDigits": "7288",
         "cardType": "Physical",
         "function": "Pre",
         "allowContactless": true,
         "holder": {
            "document": {
               "value": "47742663023",
               "type": "CPF"
            },
            "name": "Nísia Floresta",
            "account": {
               "branch": "0001",
               "number": "15164"
            }
         },
         "wallet": {
            "walletType": "GooglePay",
            "walletFlow": "GreenPatch"
         }
      }
   }
]

Tabelas para consulta

Status de rastreio de cartão

Status	Descrição
Created	Primeiro registro do cartão.
Building	O cartão está sendo confeccionado.
InProgress	O cartão está sendo transferido de local.
Delivered	O cartão foi entregue. Este é um status final, portanto, não são necessárias novas consultas.
Cancelled	Dentre outros motivos, este status é exibido quando o cartão foi extraviado ou quando entrou em processo de custódia, porém, o prazo para tomar uma ação a respeito expirou.
NotDelivered	Status relacionado a cartão não entregue, seja por endereço incorreto, seja por ter sido recusado, ou então porque o número máximo de tentativas de entregas foi excedido.
Custody	Situação em que o cartão retornou ao Bankly e será necessário atualizar o endereço de entrega.

Tipos de carteiras

Código	Descrição
101	MasterpassByMastercard
103	ApplePay
216	GooglePay
217	SamsungPay
327	MerchantTokenizationProgram
0	Unknown
00	Unknown

Pré-requisitos

Informações sobre os eventos

Contexto e nome do evento

Fluxo dos eventos

Identificador (entityId)

Dados dos eventos

CARD_WAS_ISSUED

Descrição do objeto data do evento

Payload do evento

TRACKING_STATUS_CHANGED

Descrição do objeto data do evento

Payload do evento

CARD_STATUS_WAS_MODIFIED

Descrição do objeto data do evento

Payload do evento

CARD_WAS_ADDED_TO_WALLET

Descrição do objeto data do evento

Payload do evento

CARD_WAS_REMOVED_FROM_WALLET

Descrição do objeto data do evento

Payload do evento

Tabelas para consulta

Status de rastreio de cartão

Tipos de carteiras

Identificador (`entityId`)

Descrição do objeto `data` do evento

Descrição do objeto `data` do evento

Descrição do objeto `data` do evento

Descrição do objeto `data` do evento

Descrição do objeto `data` do evento