PaymentMethod (v1.0.0)
Represents a payment instrument a customer can use, like a credit card or bank account.
Overview
The PaymentMethod entity represents a specific payment instrument registered by a customer, such as a credit card or a linked bank account. It stores necessary (non-sensitive) details required to initiate payments and links to the associated customer and billing address.
Security Note: Sensitive details like full card numbers or bank account numbers should never be stored directly. Rely on tokenization provided by payment gateways.
Entity Properties
| Name | Type | Required | Description |
|---|---|---|---|
paymentMethodId | UUID | Required | Unique identifier for the payment method. |
customerId | UUID | Required | Identifier of the customer who owns this payment method. |
type | string | Required | The type of payment method. |
details | object | Required | Contains type-specific, often sensitive details (e.g., last 4 digits of card, card brand, bank name, account type, token). **Never store raw PANs or sensitive data.** |
isDefault | boolean | Required | Indicates if this is the customer's default payment method. |
billingAddressId | UUID | Required | Identifier for the billing address verified for this payment method. |
status | string | Required | Current status of the payment method. |
createdAt | DateTime | Required | Timestamp when the payment method was added. |
updatedAt | DateTime | Required | Timestamp when the payment method was last updated. |
Relationships
- Customer: A payment method belongs to one
Customer. - Address: Linked to a specific billing
Address. - Payment: Used to make
Paymenttransactions. - Subscription: May be designated as the payment method for a
Subscription.
Examples
- Jane Doe’s default Visa card ending in 1234, expiring 12/2025, status Active.
- John Smith’s linked bank account (Chase, Checking), status Active.
- An old MasterCard ending in 5678 belonging to Jane Doe, status Expired.