Skip to main content
Um payment_method representa um instrumento de pagamento salvo — hoje, um cartão. Ele guarda só o que é seguro reter para cobrar de novo no futuro: a bandeira, os quatro últimos dígitos, o mês e o ano de validade e o nome do portador. O número completo e o código de segurança nunca são armazenados nem retornados; eles existem apenas em trânsito, no momento em que o cartão é tokenizado. É um instrumento que se prende a um customer para ser reaproveitado nas cobranças seguintes, em vez de pedir o cartão de novo a cada compra. O método nasce quando um checkout hospedado ou um fluxo de salvamento tokeniza o cartão, e passa a ficar disponível para anexar a um customer como método padrão. Anexar e desanexar não apagam o instrumento — só mudam se ele está ligado àquele customer. A confirmação e o estado de setup vivem em outro recurso; o payment_method é só a credencial durável.

​
Data Object

Este é o formato completo retornado em get, update, itens de list, nas ações attach e detach e em data.object dos webhooks payment.method.*. 
{
  "id": "pm_123",
  "object": "payment_method",
  "billing_details": {
    "address": {
      "city": "São Paulo",
      "country": "BR",
      "line1": "Rua Exemplo, 100",
      "line2": null,
      "postal_code": "01000-000",
      "state": "SP"
    },
    "email": "nome@email.com",
    "name": "Cliente",
    "phone": "+5511999990000"
  },
  "card": {
    "brand": "visa",
    "exp_month": 12,
    "exp_year": 2030,
    "last4": "4242"
  },
  "created_at": "2026-05-16T14:09:27Z",
  "customer": "cus_123",
  "livemode": true,
  "metadata": {
    "reference_id": "id_456"
  },
  "type": "credit_card",
  "updated_at": "2026-05-16T15:02:10Z"
}
​
id
string
Identificador do payment method. Usa o prefixo pm_*.
​
object
string
Sempre "payment_method".
​
billing_details
object
Dados de cobrança associados ao método, derivados do customer de contexto.
​
card
object
Dados não sensíveis do cartão. O número completo e o código de segurança nunca são retornados.
​
created_at
string
Data de criação em ISO 8601.
​
customer
string | null
ID do customer ao qual o método está anexado. Vem null quando o método não está ligado a nenhum customer.
​
livemode
boolean
true em produção; false em ambiente de teste.
​
metadata
object
Objeto livre para correlacionar o payment method com o seu sistema. Quando vazio, retorna {}.
​
type
string
Identificador do método de pagamento. Atualmente sempre "credit_card".
​
updated_at
string | null
Data da última atualização em ISO 8601. Vem null enquanto o método nunca foi atualizado.

​
Operações

​
Webhooks

Mudanças nesse objeto disparam os seguintes eventos de webhook: O payload sempre carrega o objeto payment_method completo em data.object; eventos de update também incluem data.previous_attributes com os valores anteriores dos campos alterados.