Processing Rules

Apply conditional pricing and funding behavior based on transaction characteristics

Processing rules enable dynamic pricing and funding configuration by applying conditional overrides based on transaction characteristics like amount, payment method, card type, or card brand. Rules are evaluated by priority, and the first matching rule's settings override the default processing settings for that transaction.

Prerequisites

Before working with processing rules, it's helpful to learn about the following topics.

What are Processing Rules

Processing rules define conditional overrides for pricing and funding behavior based on transaction characteristics. When a transaction matches a rule's conditions, that rule's pricing or funding settings are applied instead of the default processing settings.

Rules are evaluated by priority (highest to lowest), and the first matching rule is applied. If no rules match, the default processing settings are used.

Common use cases

• Tiered Pricing: Apply different rates based on transaction amount (e.g., lower rate for high-value transactions)
• Card Brand Pricing: Set specific pricing for different card brands (Visa, Mastercard, Amex, Discover) to match interchange rates
• Card Type Pricing: Differentiate pricing between credit, debit, and prepaid cards
• Payment Method Pricing: Apply different rates for card vs. bank account payments
• Instant Funding Surcharge: Add fees for instant funding transactions
• High-Value Transaction Delays: Apply longer funding delays for high-value transactions to manage risk
• Payment Source Pricing: Set different pricing based on transaction source (API, keyed, mobile wallets)

How Processing Rules Work

When a transaction is created, Payload evaluates all processing rules scoped to that account or profile in priority order. The evaluation follows these steps:

Rule Conditions

Conditions determine which transactions a rule applies to. Multiple conditions can be combined, and all specified conditions must match for the rule to apply.

Amount Conditions

Match transactions by amount using comparison operators:

Payment Method Conditions

Match by payment method type:

Card Conditions

Match card transactions by card brand or card type:

Card Brand:

Card Type:

Transaction Type Conditions

Match by transaction direction:

Funding Timing Conditions

Match by funding speed:

Currency Conditions

Match by transaction currency:

Source Conditions

Match by transaction source:

Rule Pricing Configuration

When a rule matches a transaction, its pricing configuration overrides the default processing settings pricing for that transaction.

Rule Funding Configuration

Rules can override funding delay for matching transactions.

Common use cases:

• Longer delay for high-value transactions
• Immediate funding (0 days) for trusted payment sources
• Extended delay for new account transactions

Processing Rule Examples

Processing rules are configured administratively and cannot be created or modified through the API. Below are examples of common rule configurations to illustrate how rules work.

• Tiered Pricing
• Card Brand Pricing
• Payment Method Pricing
• Funding Delay

// Example rule configuration (admin-configured)
{
    scope: {
        type: "account",
        object_id: "acct_processing123"
    },
    priority: 90,
    conditions: {
        amount: {
            ge: 1000.00
        }
    },
    pricing: {
        trans_rate: {
            default: 0.020  // 2.0% for large transactions
        },
        trans_cost: {
            default: 0.30
        }
    }
}

// Example Visa rule (admin-configured)
{
    priority: 80,
    conditions: {
        card_brand: {
            eq: "visa"
        }
    },
    pricing: {
        trans_rate: {
            default: 0.0275  // 2.75% for Visa
        },
        trans_cost: {
            default: 0.10
        }
    }
}
 
// Example Amex rule (admin-configured)
{
    priority: 80,
    conditions: {
        card_brand: {
            eq: "american_express"
        }
    },
    pricing: {
        trans_rate: {
            default: 0.0349  // 3.49% for Amex
        },
        trans_cost: {
            default: 0.10
        }
    }
}

// Example bank account rule (admin-configured)
{
    priority: 85,
    conditions: {
        payment_method_type: {
            eq: "bank_account"
        }
    },
    pricing: {
        trans_rate: {
            default: 0.008  // 0.8% for bank accounts
        },
        trans_cost: {
            default: 0.25
        },
        trans_fee_cap: 5.00
    }
}

// Example funding delay rule (admin-configured)
{
    priority: 95,
    conditions: {
        amount: {
            ge: 5000.00
        }
    },
    funding: {
        delay: {
            default: 5  // 5 day delay for transactions >= $5000
        }
    }
}

Rule Priority and Evaluation Order

Priority determines the order in which rules are evaluated. Higher priority numbers are evaluated first.

Setting Priority

• Priority range: 0 to 100
• Higher numbers = higher priority
• First matching rule wins

Priority Guidelines

• 90-100: Highly specific rules (multiple conditions, narrow scope)
• 70-89: Card brand or card type rules
• 50-69: Payment method type rules
• 30-49: Amount-based tiered pricing
• 0-29: Broad fallback rules

Example Priority Strategy

// Priority 95: Very specific - High-value Amex
{
    priority: 95,
    conditions: {
        amount: { ge: 1000.00 },
        card_brand: { eq: "american_express" }
    }
}
 
// Priority 80: Card brand specific
{
    priority: 80,
    conditions: {
        card_brand: { eq: "visa" }
    }
}
 
// Priority 50: Payment method type
{
    priority: 50,
    conditions: {
        payment_method_type: { eq: "bank_account" }
    }
}
 
// Priority 30: Amount-based
{
    priority: 30,
    conditions: {
        amount: { ge: 500.00 }
    }
}

Rule Scope

Rules can be scoped at the profile level or account level.

Account-Level Rules

Apply to a specific processing account:

scope: {
    type: "account",
    object_id: "acct_processing123"
}

Profile-Level Rules

Apply to all accounts within a profile:

scope: {
    type: "profile",
    object_id: "acct_profile456"
}

Viewing Processing Rules

You can query processing rules to understand which rules are configured for an account and how they will affect transaction pricing and funding.

Query Rules for an Account

Retrieve all rules scoped to a specific account:

import payload
 
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
# Query rules for a specific account
rules = pl.ProcessingRule.filter_by(
    scope={
        "object_id": "acct_processing123",
        "type": "account",
    }
).all()
 
# Sort by priority to see evaluation order
rules.sort(key=lambda r: r.priority, reverse=True)
 
# Display rule details
for rule in rules:
    print(f"Priority {rule.priority}:", rule.conditions)
    print(f"Pricing:", rule.pricing)
    print(f"Funding:", rule.funding)
    print("---")

This example queries all processing rules for a specific account and displays them sorted by priority. The output shows each rule's conditions, pricing overrides, and funding configuration.

Get a Specific Rule

Retrieve details of a specific rule by ID:

rule = pl.ProcessingRule.get("prule_abc123")
 
print("Rule conditions:", rule.conditions)
print("Rule pricing:", rule.pricing)
print("Rule priority:", rule.priority)

Schema Reference

The following fields define processing rule configuration:

ProcessingRule Schema

Complete configuration object for conditional processing overrides:

Next Steps

Understand default settings, monitor rule application, and analyze transaction pricing

Configure Processing Settings

Set up processing settings to define default pricing and configuration that rules will override for matching transactions.

Configure Automated Funding

Set up automated funding to understand how funding delays configured in rules affect fund disbursement timing.

Monitor Transaction Fees

Track transaction fees and rule performance to optimize pricing strategies and identify opportunities for rule refinement.