Pay
Payment Method Types
Card
Open in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this page

Card Payment Methods

Learn about card payment methods for accepting credit and debit cards, brand and issuer detection, tokenization, and secure storage

Card payment methods represent credit and debit cards as tokenized payment methods within the Payload system. A card can be used for a single one-time payment, or stored for reuse across recurring billing, autopay, and future transactions without re-collecting card details. Payload handles brand and issuer detection, tokenization, verification, and secure storage so you never have to persist raw card data.

What Are Card Payment Methods?

Card payment methods store a customer's credit or debit card as a tokenized payment instrument that can be charged now or reused later.

When you create a card payment method, Payload:

  • Tokenizes the card: Raw card data is exchanged for a secure token; your systems only ever handle the resulting payment method ID.
  • Detects the brand, issuer, and type: The card brand (Visa, Mastercard, American Express, Discover, and others), the issuing bank, and whether the card is credit, debit, or prepaid are determined automatically from the card number.
  • Masks sensitive details: Responses include only the last four digits and expiry, never the full card number or security code.
  • Verifies the card: When a security code (CVV) or billing address is provided, Payload runs CVV and AVS checks to help confirm the cardholder.
  • Stores it for reuse: The payment method is stored and can be charged again without re-collecting details, for as long as keep_active is true (the default). Associating it with a customer account is optional.

Key Characteristics

  • Reusable: Charge a stored card across multiple transactions, including subscriptions and autopay
  • Auto-Updating: Account Updater keeps stored cards current when they expire or are reissued, so recurring payments keep working
  • Verified: AVS and CVV checks help confirm the cardholder
  • Secure: Sensitive card data is tokenized and never stored on your systems

Common Use Cases

One-Time Payments

Charge a card a single time for a purchase or invoice. You can include the card inline with the transaction, or create the payment method first and process a transaction against it.

Recurring Payments and Autopay

Store a card once and charge it on a schedule for subscriptions, memberships, or automatic invoice payment. See Billing Schedules and Autopay for recurring collection.

Saved Cards for Faster Checkout

Associate cards with a customer account so returning customers can pay without re-entering card details, improving conversion and reducing friction.

Funding Synthetic Accounts

Charge a card to fund synthetic account balances, such as letting customers top up a wallet with a card.

Security and Verification

Card data is collected and protected for a compliant integration, then verified to confirm the cardholder and reduce declines and fraud.

  • Card Number & Expiration: Validated at creation to confirm the card is legitimate and not expired.
  • CVV/CVC: Provide the security code at creation to validate card-not-present transactions; it is never stored.
  • Address Verification (AVS): Match the billing address against the card issuer's records. See Address Verification for details and response handling.

Testing

Use test cards to exercise approvals, declines, and edge cases before going live. See Test Cards for card numbers covering common scenarios.

Schema Reference

Complete card payment method schema:

type
enum[string]
The type of payment method being created or referenced. This determines which additional fields are required and how the payment method can be used.
Values: card, bank_account, synthetic
card
object
Credit or debit card details for this payment method. This object contains the card number, expiration date, card code (CVV/CVC), card type, and brand information. This field is required when type is "card".
Required if:
type=card
_card_number_check
boolean
No description
Visibility: explicit
brand
enum[string]Read-only
The card brand or network, automatically determined from the card number. This field cannot be set directly.
Values: visa, mastercard, american_express, discover
card_code
string
The card verification value (CVV/CVC) code, typically found on the back of the card. This is required for security verification of card-not-present transactions.
Pattern: ^[0-9]+$
card_number
stringImmutable
The full credit or debit card number. When retrieved, only the last 4 digits will be visible, with the first 12 digits masked for security.
Pattern: ^[0-9]+$
Max length: 19
Required if:
track1=null
type=card
expiry
string (date-time)
The expiration date of the card in MM/YY format. The card must not be expired at the time of submission.
Pattern: ^(0[1-9]|1[0-2])([0-9]{2}|[0-9]{4})$
Required if:
card[track1]=null
type=card
type
enum[string]
The type of card being used for the payment method. This determines how the card can be used for transactions. Can be provided to enforce the card type. If provided, an error or decline will throw if the card does not match type.
Values: credit, debit, prepaid
transfer_type
enum[string]Immutable
Specifies the allowed transfer directions for this payment method. This controls whether the payment method can be used to send funds, receive funds, or both.
Values: two_way, send_only, receive_only
account_holder
stringImmutable
The name of the business or individual who owns this payment method. For cards, this is the cardholder name. For bank accounts, this is the account holder name.
Max length: 128
account_id ID of Account
string
The unique identifier of the account that owns this payment method. This determines which account has access to use this payment method for transactions and defines the ownership and permissions associated with it. (ID prefix: acct)
Pattern: ^acct_[A-Za-z0-9]+$
description
string
A human-readable description or label for the payment method. This can be used to help identify the payment method in lists or for display purposes. This is typically autogenerated but can be provided to override the default.

For complete field documentation, see:

Next Steps

Start accepting and storing cards across one-time and recurring payments

Create and Store Cards

Create cards via the Payment Method API, collect them securely with a Payment Form, and store them for reuse, optionally associating them with customer accounts.

Verify and Protect Payments

Confirm cardholders with Address Verification and validate integrations using Test Cards.

Process Transactions

Use the Payment API to charge stored cards, and the Transaction API Reference to manage the full payment lifecycle.

Related Articles

Payment Method TypesBank Account