Payment Method Schema
Credit cards, bank accounts, and payment instruments for transactions
The Payment Method schema defines the structure and properties of payment method objects in the Payload API. Payment methods represent various ways to send and receive payments, including credit/debit cards, bank accounts, and synthetic accounts.
Payment Method Object Properties
Complete reference for all properties available in the Payment Method schema
account_defaultsobject
Configuration for setting this payment method as the default for various transaction types on the associated account. This allows you to specify which payment and funding operations should automatically use this payment method.
fundingenum[string]
Specifies which types of funding transactions this payment method should be used for by default. Set to "deposits" to use for receiving funds into the account, "withdraws" to use for pulling funds from the account, or "all" to use for both funding types.
Values:
all, deposits, withdrawspayingenum[string]
Specifies which types of paying transactions this payment method should be used for by default. Set to "payments" to use for collecting payments from the account holder, "payouts" to use for sending credits or refunds to the account holder, or "all" to use for both payment types. Will be used for any automatic invoice payments if selected as the default for payments.
Values:
all, payments, payoutsaccount_holderstringImmutable
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 Accountstring
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]+$attrsobject
Custom attributes for extending the resource with additional key-value pairs. Maximum length is 255 characters when serialized.
bank_accountobject
Bank account details for this payment method. This object contains the account number, routing number, account type (checking or savings), and other bank-specific information. This field is required when type is "bank_account".
Required if:
type=bank_accountaccount_classenum[string]Immutable
The classification of the bank account ownership, indicating whether this is a personal account owned by an individual or a business account owned by a company.
Values:
personal, businessaccount_numberstringImmutable
The bank account number associated with this payment method. When retrieved, only the last 4 digits will be visible, with the preceding digits masked for security.
Pattern:
^[0-9]+$Max length: 32
account_typeenum[string]Immutable
The type of bank account, either a checking account used for everyday transactions or a savings account used for storing funds.
Values:
checking, savingscurrencyenum[string]Immutable
The currency in which the bank account is denominated. This determines the currency used for transactions with this payment method.
Values:
USD, CADrouting_numberstringImmutable
The 9-digit ABA routing number that identifies the financial institution. When retrieved, only the last 4 digits will be visible for security purposes.
Pattern:
^[0-9]+$Max length: 9
bank_namestringRead-only
The name of the financial institution associated with this payment method. For bank accounts, this is automatically determined from the routing number. For cards, this may be populated based on the BIN lookup.
Max length: 64
billing_addressobject
The billing address associated with this payment method. This is used for address verification (AVS) during payment processing and must match the address on file with the card issuer or bank. The postal code is required for verification purposes.
address_line_1string
Street address of the address
Max length: 128
address_line_2string
Unit number of the address
Max length: 56
citystring
City of the company
country_codestring
Country code of the address
Max length: 2
postal_codestring
Postal code of the address
Max length: 7
state_provincestring
State of the address
Max length: 2
cardobject
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_checkboolean
No description
Visibility: explicit
brandenum[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, discovercard_codestring
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_numberstringImmutable
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=nulltype=cardexpirystring (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]=nulltype=cardtypeenum[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, prepaidcreated_atstring (date-time)Read-only
Timestamp when the resource was created. Automatically set by the system and immutable.
descriptionstring
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.
idstringRead-only
Unique identifier for the resource. Automatically generated upon creation and cannot be modified. (ID prefix: pm)
Pattern:
^pm_[A-Za-z0-9]+$keep_activebooleanImmutable
Determines whether this payment method should remain active after use. Set to false for single-use payment methods that should be automatically deactivated after their first successful transaction.
modified_atstring (date-time)Read-only
Timestamp when the resource was last modified. Automatically updated whenever any field changes.
objectenum[string]Read-only
String representing the object type for this resource.
Values:
payment_methodstatusenum[string]Read-only
The current operational status of the payment method. Active methods can be used for transactions, inactive methods are disabled, and declining methods have failed recent transaction attempts and may need attention.
Values:
active, inactive, decliningsyntheticobject
Information about a synthetic payment method, which is a virtual account balance maintained within the system rather than linked to an external bank account or card. This object contains the available balance that can be used for transactions. This field is only present when type is "synthetic".
balanceobject
Balance information for the synthetic payment method. This contains the available funds that can be used for payments and transfers.
availablenumber (double)
The available balance amount that can be used for transactions. This represents the current funds in the synthetic account that are ready to be spent or transferred.
transfer_typeenum[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_onlytypeenum[string]Required
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, syntheticverification_statusenum[string]Read-only
The current verification status of the payment method. This indicates what level of verification has been performed on the payment method. The end-user or integration can choose how to consume and act on the result.
Values:
not_verified, verified, owner_verified