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

# PaymentMethod

> Método de pagamento disponível para um customer, projetado a partir do gateway

`PaymentMethod` representa uma opção de pagamento associada ao [Customer](/data-modelling/identity/customer). Ele funciona como proxy local do gateway: cartões podem ter referência externa persistida, enquanto `PIX` e `CASH` representam opções disponíveis para uso no checkout ou POS.

## Campos

| Campo                | Tipo                 | Descrição                                              |
| -------------------- | -------------------- | ------------------------------------------------------ |
| `paymentMethodId`    | `UUID`               | Identificador único                                    |
| `customerId`         | `UUID`               | Customer dono do método                                |
| `externalProvider`   | `String?`            | Nome do provedor de pagamento, quando aplicável        |
| `externalProviderId` | `String?`            | ID do método no provedor, quando houver método salvo   |
| `type`               | `PaymentMethodType`  | Tipo do método                                         |
| `card`               | `PaymentMethodCard?` | Dados do cartão, quando o tipo for cartão              |
| `isDefault`          | `Boolean`            | Indica se é o método padrão do customer                |
| `createdBy`          | `UUID?`              | Usuário que criou o registro, quando aplicável         |
| `createdAt`          | `DateTime`           | Data de criação                                        |
| `updatedBy`          | `UUID?`              | Usuário que fez a última atualização, quando aplicável |
| `updatedAt`          | `DateTime`           | Data da última atualização                             |

### PaymentMethodCard

| Campo   | Tipo     | Descrição                                                  |
| ------- | -------- | ---------------------------------------------------------- |
| `brand` | `String` | Bandeira do cartão (normalizada em maiúsculas, ex: `VISA`) |
| `last4` | `String` | Últimos 4 dígitos do cartão                                |

## Armazenamento

<Warning>
  O provider de billing mantém os dados sensíveis do cartão. O DEVMOB trabalha com referências, bandeira e últimos 4 dígitos.
</Warning>

## Relacionamentos

* Relaciona-se com [Customer](/data-modelling/identity/customer).

## Regras de Negócio

* `PaymentMethod` pertence a um `Customer`, não diretamente ao `User`.
* A criação de cartão recebe um `cardToken` gerado no cliente.
* O número do cartão nunca trafega nem é armazenado pelo DEVMOB.
* `externalProviderId` é obrigatório para cartões salvos no gateway.
* `PIX` e `CASH` podem existir sem `externalProviderId`, pois representam opções habilitadas ou preferidas para o customer.
* O campo `card` só deve ser preenchido para `CREDIT_CARD` ou `DEBIT_CARD`.
* Métodos de pagamento externos são acessados pelo contrato genérico de [Billing Provider](/domain/billing/billing-provider).

## Enums

### PaymentMethodType

| Valor         | Descrição                     |
| ------------- | ----------------------------- |
| `CASH`        | Dinheiro                      |
| `PIX`         | Pagamento instantâneo via PIX |
| `CREDIT_CARD` | Cartão de crédito             |
| `DEBIT_CARD`  | Cartão de débito              |

## Example

```json theme={null}
{
  "paymentMethodId": "0197a816-aec9-71f9-801f-9ce13ff707ae",
  "customerId": "0197a7f6-4d36-7c0a-a7cb-54fcb33a3148",
  "externalProvider": "billing_interface",
  "externalProviderId": "pm_7df4a219",
  "type": "CREDIT_CARD",
  "card": {
    "brand": "VISA",
    "last4": "4242"
  },
  "isDefault": true,
  "createdBy": "0197a805-0910-7eb2-bae7-90a13df2a9b2",
  "createdAt": "2026-07-03T15:50:00.000Z",
  "updatedBy": "0197a805-0910-7eb2-bae7-90a13df2a9b2",
  "updatedAt": "2026-07-03T15:50:00.000Z"
}
```