> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> O objeto Payment Method

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.*`.

```json theme={}
{
  "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"
}
```

<ResponseField name="id" type="string">
  Identificador do payment method. Usa o prefixo `pm_*`.
</ResponseField>

<ResponseField name="object" type="string">
  Sempre `"payment_method"`.
</ResponseField>

<ResponseField name="billing_details" type="object">
  Dados de cobrança associados ao método, derivados do customer de contexto.

  <Expandable title="Campos de billing_details">
    <ResponseField name="address" type="object | null">
      Endereço de cobrança. Vem `null` quando não há endereço no contexto.

      <Expandable title="Campos de address">
        <ResponseField name="city" type="string | null">
          Cidade.
        </ResponseField>

        <ResponseField name="country" type="string | null">
          País em código ISO de 2 letras, como `BR`.
        </ResponseField>

        <ResponseField name="line1" type="string | null">
          Rua, número e complemento principal.
        </ResponseField>

        <ResponseField name="line2" type="string | null">
          Complemento opcional.
        </ResponseField>

        <ResponseField name="postal_code" type="string | null">
          CEP ou código postal.
        </ResponseField>

        <ResponseField name="state" type="string | null">
          Estado ou província.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="email" type="string | null">
      Email associado à cobrança. Vem `null` quando não há contexto de customer.
    </ResponseField>

    <ResponseField name="name" type="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.
    </ResponseField>

    <ResponseField name="phone" type="string | null">
      Telefone associado à cobrança. Vem `null` quando não há contexto de customer.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="card" type="object">
  Dados não sensíveis do cartão. O número completo e o código de segurança
  nunca são retornados.

  <Expandable title="Campos de card">
    <ResponseField name="brand" type="string | null">
      Bandeira do cartão, como `visa` ou `mastercard`. Vem `null` quando não
      identificada.
    </ResponseField>

    <ResponseField name="exp_month" type="number | null">
      Mês de validade (1 a 12). Vem `null` quando indisponível.
    </ResponseField>

    <ResponseField name="exp_year" type="number | null">
      Ano de validade com quatro dígitos. Vem `null` quando indisponível.
    </ResponseField>

    <ResponseField name="last4" type="string | null">
      Quatro últimos dígitos do cartão. Vem `null` quando indisponível.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string">
  Data de criação em ISO 8601.
</ResponseField>

<ResponseField name="customer" type="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.
</ResponseField>

<ResponseField name="livemode" type="boolean">
  `true` em produção; `false` em ambiente de teste.
</ResponseField>

<ResponseField name="metadata" type="object">
  Objeto livre para correlacionar o payment method com o seu sistema. Quando
  vazio, retorna `{}`.
</ResponseField>

<ResponseField name="type" type="string">
  Identificador do método de pagamento. Atualmente sempre `"credit_card"`.
</ResponseField>

<ResponseField name="updated_at" type="string | null">
  Data da última atualização em ISO 8601. Vem `null` enquanto o método nunca
  foi atualizado.
</ResponseField>

## Operações

* [Listar payment methods](/api-reference/payment-methods/list)
* [Consultar payment method](/api-reference/payment-methods/get)
* [Atualizar payment method](/api-reference/payment-methods/update)
* [Anexar payment method](/api-reference/payment-methods/attach)
* [Desanexar payment method](/api-reference/payment-methods/detach)

## Webhooks

Mudanças nesse objeto disparam os seguintes eventos de webhook:

* [`payment.method.created`](/api-reference/webhooks/payment.method.created)
* [`payment.method.attached`](/api-reference/webhooks/payment.method.attached)
* [`payment.method.updated`](/api-reference/webhooks/payment.method.updated)
* [`payment.method.detached`](/api-reference/webhooks/payment.method.detached)

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.