Métodos de pagamento

Um payment_method representa um método de pagamento salvo — hoje, um cartão. Ele guarda só o que é seguro manter 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. Ele fica ligado 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 método — 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 salva.

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_xCUtEgyVfRaycNNA",
  "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_cxpQKg8cbD9264xe",
  "livemode": true,
  "metadata": {},
  "type": "credit_card",
  "updated_at": "2026-05-16T15:02:10Z"
}

string

Identificador do payment method. Usa o prefixo pm_*.

string

Sempre "payment_method".

object

Dados de cobrança associados ao método, derivados do customer de contexto.

Show Campos de billing_details

object | null

Endereço de cobrança. Vem null quando não há endereço no contexto.

Show Campos de address

string | null

Cidade.

string | null

País em código ISO de 2 letras, como BR.

string | null

Rua, número e complemento principal.

string | null

Complemento opcional.

string | null

CEP ou código postal.

string | null

Estado ou província.

string | null

Email associado à cobrança. Vem null quando não há contexto de customer.

string | null

Nome do titular da cobrança. Usa o nome do customer quando disponível e, na falta dele, o nome do portador do cartão. Vem null quando nenhum está presente.

string | null

Telefone associado à cobrança. Vem null quando não há contexto de customer.

object

Dados não sensíveis do cartão. O número completo e o código de segurança nunca são retornados.

Show Campos de card

string | null

Bandeira do cartão, como visa ou mastercard. Vem null quando não identificada.

number | null

Mês de validade (1 a 12). Vem null quando indisponível.

number | null

Ano de validade com quatro dígitos. Vem null quando indisponível.

string | null

Quatro últimos dígitos do cartão. Vem null quando indisponível.

string

Data de criação em ISO 8601.

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.

boolean

true em produção; false em ambiente de teste.

object

Objeto livre para correlacionar o payment method com o seu sistema. Quando vazio, retorna {}.

string

Identificador do método de pagamento. Atualmente sempre "credit_card".

Valor	Descrição
`credit_card`	Cartão de crédito.

string | null

Data da última atualização em ISO 8601. Vem null enquanto o método nunca foi atualizado.

Operações

Eventos

Mudanças nesse objeto disparam os seguintes eventos:

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.

Como se relaciona

Um setup_intent valida e salva o cartão sem cobrar. Quando ele termina em succeeded, o payment_method resultante pode ser usado em um payment_intent para cobrar depois.

Setup Intents

Salve um cartão para uso futuro sem realizar cobrança.

Usar em uma cobrança

Envie customer e payment_method ao criar o Payment Intent.

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Métodos de pagamento

Data Object

Operações

Eventos

Como se relaciona

Setup Intents

Usar em uma cobrança

​Data Object

​Operações

​Eventos

​Como se relaciona

Setup Intents

Usar em uma cobrança

Data Object

Operações

Eventos

Como se relaciona