Account Schema
Customer, processing entity, and account holder objects with contact information and payment settings
The Account schema defines the structure and properties of account objects in the Payload API. Accounts represent customers, processing entities, or generic account holders within the system, containing contact information, processing settings, and associated payment methods.
Account Object Properties
Complete reference for all properties available in the Account schema
additional_emailsobject
Additional email addresses for receiving communications, statements, and notifications. Provided as a list of valid email addresses.
attrsobject
Custom attributes for extending the resource with additional key-value pairs. Maximum length is 255 characters when serialized.
contact_detailsobject
Contact information for the account including email, phone, website, and physical address. This information is used for communication, verification, and compliance purposes.
additional_emailsobject
Additional email addresses for receiving communications, statements, and notifications. Provided as a list of valid email addresses.
addressobject
The physical address associated with the account. Used for receipts, invoices, and statements, and as part of identity verification for processing accounts.
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
Max length: 56
country_codestring
Country code of the address
postal_codestring
Postal code of the address
Max length: 7
state_provincestring
State of the address
Max length: 2
emailstring (email)
Primary email address for contacting this account. Used for notifications, statements, and general communication.
Max length: 64
phone_numberstring
Primary phone number for the account. Used for verification, support, and important account communications.
Pattern:
^[0-9]{10}$Max length: 16
websitestring
Website URL associated with the account. For processing accounts, this is typically the business website used for validation and compliance checks.
Max length: 56
created_atstring (date-time)Read-only
Timestamp when the resource was created. Automatically set by the system and immutable.
descriptionstring
Optional free-form text description providing additional context or notes about the account. This can be used to store internal notes, account purpose, or other identifying information for reference.
Max length: 56
entityEntityobject
The expanded legal entity object associated with this account. When included, this provides the full entity details including business information, ownership, tax details, and compliance information. Required for processing accounts.
entity_id ID of Entitystring
ID of the associated entity object. (ID prefix: ent)
Pattern:
^ent_[A-Za-z0-9]+$Required if:
entity=nulltype=processingexternal_uidstring
Optional unique external identifier for this account from an external system. Maximum length of 64 characters. When provided, this can be used to look up the account or perform upsert operations (update if exists, create if not). Useful for maintaining consistency with external CRM, ERP, or accounting systems.
Max length: 64
idstringRead-only
Unique identifier for the resource. Automatically generated upon creation and cannot be modified. (ID prefix: acct)
Pattern:
^acct_[A-Za-z0-9]+$keep_activebooleanImmutable
Controls account retention behavior. When set to false, indicates this is a one-time or temporary customer that should not be retained long-term. When true (default), the account will remain active for ongoing use. This field is immutable and must be set at account creation.
modified_atstring (date-time)Read-only
Timestamp when the resource was last modified. Automatically updated whenever any field changes.
namestringRequired
Display name for the account. For processing accounts, this is typically the business or company name. For customer accounts, this can be either a person or company name. This name is used throughout the platform for identification and may appear on invoices and payment pages.
Max length: 72
objectenum[string]Read-only
String representing the object type for this resource.
Values:
accountprocessingobject
Processing-specific configuration and status for processing accounts. This object contains settings, agreements, and status information required for accounts that accept and process payments. Only applicable to accounts with type "processing".
Required if:
type=processingagreementProcessingAgreementobject
The expanded processing agreement object that defines the terms and conditions for this processing account. When included, this provides the full agreement details including terms and conditions.
agreement_id ID of ProcessingAgreementstringImmutable
ID of the associated processing agreement that was acknowledged during enrollment. (ID prefix: agg)
Pattern:
^agg_[A-Za-z0-9]+$default_categoryenum[string]
The primary industry or business category for this processing account. This helps determine risk assessment, fees, and available processing features. Must be one of the supported industry categories.
Values:
computer_network_services, utilities, bakeries, food_stores_misc, apparel_accessory_shops, real_estate, sporting_recreation_camps, trailer_parks_campgrounds, general_services_misc, landscaping_services, legal_services, dance_schools, theatrical_ticket_agencies, bands_orchestras, sports_clubs_fields, country_clubs, courier_services, recreation_services_misc, doctors, medical_services, schools_elementary_secondary, colleges_universities, vocational_trade_schools, educational_services, child_care_services, charitable_organizations_fundraising, charitable_fundraising, civic_social_associations, political_organizations, religious_organizations, membership_organizations, professional_services, court_costs_alimony_child_support, fines_government_entities, bail_bond_payments, government_services_misc, insurance_sales_underwriting, shoe_stores, software_services, electrical_parts_equipment, restaurants_eating_places, general_contractors, business_services_misc, travel_tour_companies, publishing_printing_miscsettingsProcessingSettingsobject
The expanded processing settings object that configures how this account processes transactions. When included, this provides the full configuration including payment types, features, limits, funding, and billing settings.
settings_id ID of ProcessingSettingsstringImmutable
The unique ID of the associated processing settings. (ID prefix: ps)
Pattern:
^ps_[A-Za-z0-9]+$statusobject
Status information for this processing account, including both paying (ability to accept payments) and funding (ability to receive disbursements) capabilities.
fundingenum[string]
Indicates the status of funding capabilities for this account. Possible values: pending (account is under review or incomplete), active (account can receive funds), disabled (account cannot receive funds), or on_hold (funding temporarily suspended).
Values:
pending, active, disabled, on_holdpayingenum[string]Read-only
Indicates whether this account can accept payments from customers. Returns active when the account is operational, or disabled when the account is incomplete, rejected, or inactive.
Values:
active, disabledprofile_idstringRead-only
The unique identifier of the parent profile (organization) that owns this account. This establishes the account hierarchy and determines access permissions, settings inheritance, and billing relationships. (ID prefix: acct)
Pattern:
^acct_[A-Za-z0-9]+$typeenum[string]Required
The type of account. Possible values are: processing (primary account that can receive payments or send payouts), or customer (sub account that can send payments or receive payouts). Processing accounts require additional information and onboarding.
Values:
processing, customer