PaymentMethod representa uma opção de pagamento associada ao 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
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.
Relacionamentos
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.
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
{
"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"
}
