Eventos de Cartão

Todos os eventos de cartão entregam o mesmo objeto data — a representação segura do cartão. O número completo (PAN) e o CVV nunca são enviados.

Campo	Tipo	Descrição
`id`	string	UUID do cartão
`card_token`	string	Identificador do cartão salvo — enviado em `payment.card.card_token` ao cobrar
`first_six_digits`	string	Seis primeiros dígitos (BIN)
`last_four_digits`	string	Quatro últimos dígitos
`brand`	string	Bandeira do cartão
`holder_name`	string	Nome do portador
`exp_month`	integer	Mês de validade (1–12)
`exp_year`	integer	Ano de validade (YYYY)
`type`	string	Tipo do cartão (`credit`, `debit`)
`status`	string	Situação do cartão (`active`, `deleted`)
`tokenization_status`	string	Situação da tokenização (`pending`, `tokenized`, `failed`)
`created_at`	string	Data de criação (ISO 8601)
`updated_at`	string	Data da última atualização (ISO 8601)
`deleted_at`	string	Data de exclusão (ISO 8601) — presente apenas em `card.deleted`

Ciclo de vida da tokenização

Ao salvar um cartão, a tokenização acontece em segundo plano. Acompanhe-a por estes eventos, na ordem esperada:

card.created

O cartão foi salvo. tokenization_status começa como pending.

card.token_pending

A tokenização foi iniciada.

card.token_created ou card.token_failed

card.token_created quando o cartão está pronto para cobranças; card.token_failed quando não foi possível tokenizá-lo.

Aguarde o card.token_created antes de usar o cartão em uma cobrança. Enquanto o tokenization_status for pending, o cartão ainda está sendo preparado.

card.created

Disparado quando um cartão é salvo.

Payload

{
  "type": "card.created",
  "id": "hook_a1b2c3d4e5f6",
  "webhook_version": "v1",
  "data": {
    "id": "9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f",
    "card_token": "9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f",
    "first_six_digits": "542501",
    "last_four_digits": "7793",
    "brand": "mastercard",
    "holder_name": "Tony Stark",
    "exp_month": 1,
    "exp_year": 2030,
    "type": "credit",
    "status": "active",
    "tokenization_status": "pending",
    "created_at": "2026-05-27T10:00:00-03:00",
    "updated_at": "2026-05-27T10:00:00-03:00"
  }
}

card.token_pending

Disparado quando a tokenização do cartão é iniciada.

Payload

{
  "type": "card.token_pending",
  "id": "hook_b2c3d4e5f6a1",
  "webhook_version": "v1",
  "data": {
    "id": "9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f",
    "card_token": "9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f",
    "first_six_digits": "542501",
    "last_four_digits": "7793",
    "brand": "mastercard",
    "holder_name": "Tony Stark",
    "exp_month": 1,
    "exp_year": 2030,
    "type": "credit",
    "status": "active",
    "tokenization_status": "pending",
    "created_at": "2026-05-27T10:00:00-03:00",
    "updated_at": "2026-05-27T10:00:00-03:00"
  }
}

card.token_created

Disparado quando o cartão foi tokenizado e está pronto para cobranças.

Payload

{
  "type": "card.token_created",
  "id": "hook_c3d4e5f6a1b2",
  "webhook_version": "v1",
  "data": {
    "id": "9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f",
    "card_token": "9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f",
    "first_six_digits": "542501",
    "last_four_digits": "7793",
    "brand": "mastercard",
    "holder_name": "Tony Stark",
    "exp_month": 1,
    "exp_year": 2030,
    "type": "credit",
    "status": "active",
    "tokenization_status": "tokenized",
    "created_at": "2026-05-27T10:00:00-03:00",
    "updated_at": "2026-05-27T10:00:05-03:00"
  }
}

Use o card_token deste evento em payment.card.card_token ao cobrar o cartão salvo. O billing address não é tokenizado — informe client.address na cobrança.

card.token_failed

Disparado quando não foi possível tokenizar o cartão.

Payload

{
  "type": "card.token_failed",
  "id": "hook_d4e5f6a1b2c3",
  "webhook_version": "v1",
  "data": {
    "id": "9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f",
    "card_token": "9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f",
    "first_six_digits": "542501",
    "last_four_digits": "7793",
    "brand": "mastercard",
    "holder_name": "Tony Stark",
    "exp_month": 1,
    "exp_year": 2030,
    "type": "credit",
    "status": "active",
    "tokenization_status": "failed",
    "created_at": "2026-05-27T10:00:00-03:00",
    "updated_at": "2026-05-27T10:00:05-03:00"
  }
}

card.updated

Disparado quando um cartão é atualizado.

Payload

{
  "type": "card.updated",
  "id": "hook_e5f6a1b2c3d4",
  "webhook_version": "v1",
  "data": {
    "id": "9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f",
    "card_token": "9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f",
    "first_six_digits": "542501",
    "last_four_digits": "7793",
    "brand": "mastercard",
    "holder_name": "Peter Parker",
    "exp_month": 12,
    "exp_year": 2030,
    "type": "credit",
    "status": "active",
    "tokenization_status": "tokenized",
    "created_at": "2026-05-27T10:00:00-03:00",
    "updated_at": "2026-05-28T09:15:00-03:00"
  }
}

card.deleted

Disparado quando um cartão é removido.

Payload

{
  "type": "card.deleted",
  "id": "hook_f6a1b2c3d4e5",
  "webhook_version": "v1",
  "data": {
    "id": "9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f",
    "card_token": "9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f",
    "first_six_digits": "542501",
    "last_four_digits": "7793",
    "brand": "mastercard",
    "holder_name": "Tony Stark",
    "exp_month": 1,
    "exp_year": 2030,
    "type": "credit",
    "status": "deleted",
    "tokenization_status": "tokenized",
    "created_at": "2026-05-27T10:00:00-03:00",
    "updated_at": "2026-06-01T14:00:00-03:00",
    "deleted_at": "2026-06-01T14:00:00-03:00"
  }
}

card.expired

Disparado quando um cartão salvo atinge o fim de sua validade.

Payload

{
  "type": "card.expired",
  "id": "hook_a1b2c3d4e5f7",
  "webhook_version": "v1",
  "data": {
    "id": "9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f",
    "card_token": "9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f",
    "first_six_digits": "542501",
    "last_four_digits": "7793",
    "brand": "mastercard",
    "holder_name": "Tony Stark",
    "exp_month": 1,
    "exp_year": 2026,
    "type": "credit",
    "status": "active",
    "tokenization_status": "tokenized",
    "created_at": "2024-05-27T10:00:00-03:00",
    "updated_at": "2024-05-27T10:00:00-03:00"
  }
}

card.expired é disparado uma única vez por cartão, no dia seguinte ao término do mês de validade.

​Ciclo de vida da tokenização

​card.created

​card.token_pending

​card.token_created

​card.token_failed

​card.updated

​card.deleted

​card.expired

Ciclo de vida da tokenização

card.created

card.token_pending

card.token_created

card.token_failed

card.updated

card.deleted

card.expired