Processing Settings Schema
Payment processing configuration including fraud protection and funding options
The Processing Settings schema defines the structure and properties of processing settings objects in the Payload API. Processing settings contain comprehensive configuration for payment processing, including card and bank account processing settings, billing preferences, funding options, fraud protection features, and detailed Level 3 transaction defaults for enhanced processing capabilities.
Processing Settings Object Properties
Complete reference for all properties available in the Processing Settings schema
account_idstringImmutable
The unique identifier of the account or organization that owns and controls these processing settings. Links the settings to a specific account. This field is immutable after creation and determines which merchant these settings apply to. (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_account_processingobject
Configuration for bank account payment processing. This object controls whether bank payments are enabled, which processor is used, transaction limits, verification features, and duplicate transaction prevention. Essential for processing accounts that want to accept bank-to-bank payments in addition to or instead of card payments.
default_pricingobject
Default pricing structure for bank account transactions. Defines the percentage rate, fixed cost per transaction, maximum fee cap, and convenience fee allocation. These defaults apply unless overridden by a processing rule. Most pricing fields are read-only except for administrators on updates.
conv_fee_allocnumber (double)
Convenience fee allocation for bank account transactions. Specifies what percentage of the processing fee should be passed to the customer as a convenience fee rather than absorbed by the processing account. For example, a value of 1 means the entire fee is passed to the customer, while 0 means the processing account absorbs all fees. This allows processing accounts to offset processing costs while staying compliant with card brand rules.
trans_costnumber (double)
Fixed cost charged per bank account transaction, regardless of the transaction amount. This flat fee is added to the percentage-based rate (trans_rate) to calculate the total transaction fee. For example, a cost of 0.25 means $0.25 is charged per transaction. Total fee = (amount × trans_rate%) + trans_cost. Read-only except for administrators on updates.
Read-only permissions:
"Undocumented"trans_fee_capnumber (double)
Maximum fee cap for bank account transactions. This value limits the total fee charged on high-value transactions, preventing fees from becoming excessive on large payment amounts. For example, if trans_rate is 1% and trans_fee_cap is 10.00, a $5,000 transaction would be capped at $10.00 instead of $50.00. Must be non-zero if set. Read-only except for administrators on updates.
Read-only permissions:
"Undocumented"trans_ratenumber (double)
Percentage rate charged per bank account transaction. This rate is applied to the transaction amount to calculate the percentage-based portion of the fee. For example, a rate of 0.0125 means 1.25% of the transaction amount. Combined with the fixed cost (trans_cost) to determine total transaction fees. Read-only except for administrators on updates.
Read-only permissions:
"Undocumented"enabledboolean
Controls whether bank account payments are allowed on this processing account. When enabled, customers can pay using their bank accounts. When disabled, only other payment methods (if configured) will be available. Read-only except for administrators on updates.
Read-only permissions:
"Undocumented"featuresobject
Advanced features and capabilities for bank account processing. These features enhance security, reduce fraud, and improve success rates by providing account verification and balance checking before processing payments.
ach_verifyobject
Instant bank account verification feature. When enabled, provides real-time validation of bank account information to ensure accounts are valid and open before processing transactions. This reduces failed payments and fraud risk.
enabledboolean
Enable enhanced instant account verification. This provides real-time bank account validation. Not available for sandbox/test accounts.
balance_checkobject
Balance checking configuration to verify sufficient funds before processing bank account transactions. Helps reduce failed payments and NSF fees.
enabledboolean
Enable balance checking before processing transactions. When enabled, the system checks if sufficient funds are available before attempting to process the payment, reducing NSF (non-sufficient funds) failures.
servicesobject
Configuration for balance check service providers. Specify which third-party services to use for checking account balances before processing.
plaidboolean
Enable Plaid for real-time balance checks. Plaid provides instant account balance verification through secure bank connections, helping reduce failed transactions due to insufficient funds.
enhanced_account_verifyobject
Micro-deposit account verification feature. When enabled, bank accounts are verified by sending two small deposits (typically less than $1 each) that the customer must confirm. This traditional verification method ensures the customer has access to the bank account and that it is active.
enabledboolean
Enable ACH account verification through micro-deposits. When enabled, bank accounts are verified by sending small deposits ensuring the account is open and valid.
limitsobject
Transaction limits for bank account payments. Controls the maximum amount that can be processed in a single transaction. Used for risk management and fraud prevention.
trans_limitnumber (double)
Maximum transaction amount allowed for a single bank account payment. Transactions exceeding this limit will be declined. Used for risk management and fraud prevention. Read-only except for administrators on updates.
Read-only permissions:
"Undocumented"billingobject
Billing configuration for this processing account, including how fees are collected, when they are charged, and the monthly account fee. These settings determine the billing cycle and payment method for processing fees. Most billing fields are read-only or admin-only.
flowstring
The billing flow configuration for this processing account. Determines if this account should be billed with account-level billing or profile-level billing. This field is read-only and can only be modified by administrators.
Max length: 10
Read-only permissions:
"Undocumented"monthly_account_feenumber (double)
Fixed monthly fee charged for maintaining this processing account. This is a flat recurring charge that applies regardless of transaction volume. The fee is typically billed according to the billing preference (netted daily or billed monthly). Read-only except for administrators on updates.
Read-only permissions:
"Undocumented"preferenceenum[string]
The billing preference indicating how processing fees are charged. Possible values: "netted_daily" (fees are deducted from daily funding), or "billed_monthly" (fees are invoiced monthly).
Values:
netted_daily, billed_monthlysetupstring
The billing setup method for processing fees. Values can be either "externally_billed" (fees billed by processor) or "auto_draft" (fees automatically drafted by provider). Read-only except for administrators on updates.
Max length: 9
Read-only permissions:
"Undocumented"card_processingobject
Configuration for credit and debit card payment processing. This object controls whether card payments are enabled, which card types are accepted, which processor is used, transaction limits, fraud prevention features, and Level 3 processing defaults. Essential for processing accounts that want to accept card payments.
allowed_card_brandsobject
Controls which card brands (payment networks) are accepted for card transactions. Processing accounts can selectively enable or disable specific card brands. At least one card brand must be enabled when card processing is active.
american_expressboolean
Enable or disable acceptance of American Express branded cards. When disabled, transactions attempted with American Express cards will be declined.
discoverboolean
Enable or disable acceptance of Discover branded cards. When disabled, transactions attempted with Discover cards will be declined.
mastercardboolean
Enable or disable acceptance of Mastercard branded cards. When disabled, transactions attempted with Mastercard cards will be declined.
visaboolean
Enable or disable acceptance of Visa branded cards. When disabled, transactions attempted with Visa cards will be declined.
allowed_card_typesobject
Controls which types of payment cards are accepted. Processing accounts can selectively enable or disable credit, debit, and prepaid cards based on business needs, risk tolerance, use-case restrictions, pricing sensitivity, and target customers. At least one card type must be enabled when card processing is active.
creditboolean
Enable or disable acceptance of credit cards. In some use-cases, payments made with credit are not allowed. Also, the pricing impact of credit cards may be a factor in if a business accepts credit card payments.
debitboolean
Enable or disable acceptance of debit cards. Debit cards withdraw funds directly from the customer's bank account.
prepaidboolean
Enable or disable acceptance of prepaid cards. Prepaid cards are pre-loaded with funds and not connected to a bank account or credit line. Some businesses choose to not accept prepaid card payments for fraud prevention or business policy reasons.
default_pricingobject
Default pricing structure for card transactions. Defines the percentage rate, fixed cost per transaction, maximum fee cap, and convenience fee allocation. These defaults apply unless overridden by a processing rule. Most pricing fields are read-only except for administrators on updates.
conv_fee_allocnumber (double)
Convenience fee allocation for card transactions. Specifies what percentage of the processing fee should be passed to the customer as a convenience fee rather than absorbed by the processing account. For example, a value of 1 means the entire fee is passed to the customer, while 0 means the processing account absorbs all fees. Note that card brand rules and regulations may restrict convenience fee usage, particularly for credit cards. Always ensure compliance with applicable card network rules.
trans_costnumber (double)
Fixed cost charged per card transaction, regardless of the transaction amount. This flat fee is added to the percentage-based rate (trans_rate) to calculate the total transaction fee. For example, a cost of 0.30 means $0.30 is charged per transaction. Total fee = (amount × trans_rate%) + trans_cost. This fixed cost helps cover gateway and authorization fees. Read-only except for administrators on updates.
Read-only permissions:
"Undocumented"trans_fee_capnumber (double)
Maximum fee cap for card transactions. This value limits the total fee charged on high-value card transactions, preventing fees from becoming excessive on large payment amounts. For example, if trans_rate is 2.9% and trans_fee_cap is 25.00, a $2,000 transaction would be capped at $25.00 instead of $58.00. Must be non-zero if set. Read-only except for administrators on updates.
Read-only permissions:
"Undocumented"trans_ratenumber (double)
Percentage rate charged per card transaction. This rate is applied to the transaction amount to calculate the percentage-based portion of the fee. For example, a rate of 0.0275 means 2.75% of the transaction amount. Combined with the fixed cost (trans_cost) to determine total transaction fees. Card rates are typically higher than bank account rates due to interchange fees. Read-only except for administrators on updates.
Read-only permissions:
"Undocumented"enabledboolean
Controls whether credit and debit card payments are allowed on this processing account. When enabled, customers can pay using their payment cards. When disabled, only other payment methods (if configured) will be available. Read-only except for administrators on updates.
Read-only permissions:
"Undocumented"featuresobject
Advanced features and fraud prevention tools for card processing. These features enhance security and reduce chargebacks by validating cardholder information before approving transactions.
avsobject
Address Verification Service (AVS) configuration for fraud prevention. AVS validates that the billing address provided matches the cardholder's address on file, helping reduce fraudulent card-not-present transactions.
enabledboolean
Enable Address Verification Service (AVS) for card transactions. AVS compares the billing address provided by the customer with the address on file with the card issuer to help prevent fraud.
nonparticipating_regionsenum[string]
Action to take for cards from regions that don't participate in AVS. Set to "approve" to allow these transactions or "decline" to reject them. Some international cards may not support AVS verification.
Values:
approve, declinethresholdstring
The AVS match threshold required to approve transactions. Defines which level of address matching is acceptable (e.g., street address match, zip code match, etc.) before approving a payment.
limitsobject
Transaction limits for card payments. Controls the maximum amount that can be processed in a single card transaction. Used for risk management and fraud prevention.
trans_limitnumber (double)
Maximum transaction amount allowed for a single card payment. Transactions exceeding this limit will be declined. Used for risk management and fraud prevention. Read-only except for administrators on updates.
Read-only permissions:
"Undocumented"created_atstring (date-time)Read-only
Timestamp when the resource was created. Automatically set by the system and immutable.
descriptionstring
Optional description of this processing settings configuration. Useful for identifying the purpose or characteristics of these settings, especially when multiple configurations exist.
Max length: 48
Required if:
is_template=truefundingobject
Funding configuration for this processing account, including funding style, delay, default currency, and transaction descriptor. These settings control how and when funds are disbursed to the processing account and what information appears on bank statements.
default_currencyenum[string]
The default currency for all transactions and funding for this processing account. Supported values are "USD" (US Dollars) or "CAD" (Canadian Dollars). This determines the currency for settlements and must match the account's operating region. Read-only except for administrators on updates.
Values:
USD, CADRead-only permissions:
"Undocumented"default_descriptorstring
The default text descriptor that appears on the customer's bank or card statement for transactions. This helps customers identify the merchant on their statements. Typically includes the business name or recognizable identifier. Maximum length varies by processor.
Max length: 128
delaynumber (double)
Number of days to delay funding after transaction settlement. Valid range is 0-10 days. For example, a delay of 2 means funds are deposited 2 business days after settlement. Used for risk management and reserve requirements. Read-only except for administrators on updates.
Read-only permissions:
"Undocumented"styleenum[string]
The funding style that determines how funds are disbursed to the merchant. Possible values: "gross" (all debits amounts in a single deposit and all credit amounts split into a separate single wihtdraw), "itemized" (separate deposits for each transaction), "netted" (debit amounts minus any credits in a single deposit or withdraw), "manual" (funds held until manually released), or null. Required for payfac processing, cannot be null for those accounts.
Values:
gross, itemized, netted, manualidstringRead-only
Unique identifier for the resource. Automatically generated upon creation and cannot be modified. (ID prefix: ps)
Pattern:
^ps_[A-Za-z0-9]+$limitsobject
Global transaction limits and restrictions for this processing account. Controls duplicate transaction detection and other transaction-level restrictions to prevent fraud and accidental duplicate charges.
duplicate_limitstring
Time-based limit to prevent duplicate bank account transactions. Specify the duration window (e.g., "1 day", "24 hours") during which duplicate transactions with the same account number, routing number, and amount will be rejected. Helps prevent accidental double-charges and certain types of fraud.
Max length: 16
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:
processing_settingsrulesProcessingRulearray
Processing rules that apply to this account. Rules define conditional pricing, funding delays, and other processing behavior based on transaction characteristics like amount, payment method, card type, or currency. Rules are evaluated by priority and the first matching rule is applied to each transaction.