PaymentMethod

Represents a payment method that can be used for billing and payments, storing secure payment instrument details while maintaining PCI compliance through tokenization and masking. This entity is a reusable support type that can be owned by tenants, organizations, or persons. It supports multiple payment types including credit cards, debit cards, bank accounts, digital wallets, and alternative payment methods. It stores only non-sensitive tokenized data and masked details for display purposes, never storing full card numbers or sensitive banking information. The entity tracks payment method verification, expiration, primary designation, and billing address associations. It enables scenarios such as multiple payment methods per entity, backup payment methods for failed charges, payment method updates, and payment method verification workflows. The entity serves as a secure payment instrument registry for subscription billing, one-time payments, and recurring charges across B2B SaaS platforms, e-commerce systems, and financial applications.

16 properties
Schema

Properties

PropertyTypeModeDescriptionRequired
typestring
stored

Type of payment method

Values: credit-card, debit-card, bank-account, digital-wallet, invoice, wire-transfer

Example: "credit-card"

Required
providerstring
stored

Payment processor or provider handling this payment method

Example: "stripe"

Optional
providerTokenstring
stored

Tokenized payment method identifier from the payment provider (never store raw card data)

Example: "pm_1A2B3C4D5E6F7G8H"

Optional
last4string
stored

Last 4 digits of card number or account number (for display purposes)

Example: "4242"

Optional
brandstring
stored

Card brand or bank name

Example: "Visa"

Optional
expiryMonthnumber
stored

Expiration month for cards (1-12)

Example: 12

Optional
expiryYearnumber
stored

Expiration year for cards (4-digit year)

Example: 2025

Optional
holderNamestring
stored

Name on the card or account holder name

Example: "JOHN DOE"

Optional
billingAddressPostalAddress
stored

Billing address associated with this payment method

Optional
isPrimaryboolean
stored

Whether this is the primary/default payment method for the tenant

Example: true

Required
isVerifiedboolean
stored

Whether this payment method has been verified (e.g., via micro-deposits for bank accounts)

Example: true

Optional
verifiedAtdatetime
stored

Date/time when the payment method was verified

Example: "2024-01-15T10:30:00Z"

Optional
fingerprintstring
stored

Unique fingerprint to detect duplicate payment methods

Example: "fp_1A2B3C4D5E6F"

Optional
metadatajson
stored

Additional payment method metadata (provider-specific data, fraud detection info)

Optional
isExpiredboolean
calculated

Whether this payment method has expired (based on expiryMonth/expiryYear for cards)

Optional
expiresInDaysnumber
calculated

Number of days until this payment method expires (null if no expiration)

Optional

Examples

Example 1

{
  "@type": "PaymentMethod",
  "tenant": {
    "@type": "Tenant",
    "slug": "acme-corp",
    "name": "ACME Corporation"
  },
  "type": "credit-card",
  "provider": "stripe",
  "providerToken": "pm_1A2B3C4D5E6F7G8H",
  "last4": "4242",
  "brand": "Visa",
  "expiryMonth": 12,
  "expiryYear": 2026,
  "holderName": "JOHN DOE",
  "isPrimary": true,
  "isVerified": true,
  "verifiedAt": "2024-01-15T10:30:00Z"
}

Example 2

{
  "@type": "PaymentMethod",
  "tenant": {
    "@type": "Tenant",
    "slug": "techstart",
    "name": "TechStart Inc"
  },
  "type": "credit-card",
  "provider": "stripe",
  "providerToken": "pm_9Z8Y7X6W5V4U3T2S",
  "last4": "5555",
  "brand": "Mastercard",
  "expiryMonth": 6,
  "expiryYear": 2025,
  "holderName": "JANE SMITH",
  "isPrimary": true,
  "isVerified": true,
  "verifiedAt": "2024-11-15T09:00:00Z"
}

Example 3

{
  "@type": "PaymentMethod",
  "tenant": {
    "@type": "Tenant",
    "slug": "small-biz",
    "name": "Small Business Co"
  },
  "type": "bank-account",
  "provider": "stripe",
  "providerToken": "ba_1K2L3M4N5O6P7Q8R",
  "last4": "6789",
  "brand": "Chase Bank",
  "holderName": "Small Business Co",
  "isPrimary": true,
  "isVerified": true,
  "verifiedAt": "2024-06-10T14:00:00Z"
}

Example 4

{
  "@type": "PaymentMethod",
  "tenant": {
    "@type": "Tenant",
    "slug": "consulting-partners",
    "name": "Consulting Partners LLC"
  },
  "type": "invoice",
  "isPrimary": true,
  "isVerified": true,
  "metadata": {
    "paymentTerms": "NET30",
    "invoiceEmail": "billing@consultingpartners.com"
  }
}