Payment Processing

Table of Contents

1. Overview
2. Key Features
3. How It Works
4. Configuration Types
5. Supported Conditions
6. API Reference
7. Use Cases
8. Best Practices

Overview

Payment Processing provides intelligent payment routing capabilities that allow you to distribute card transactions across multiple Payment Service Providers (PSPs). This enables you to optimize payment processing by routing transactions to the most appropriate gateway based on configurable rules or volume distribution. Under the hood, its handled by our Fluid Orchestration Routing Engine.

Whether you want to split traffic between processors for redundancy, route specific payment types to preferred gateways, or implement geographic routing rules, Payment Processing gives you full control over your payment flow.

Key Features

• Volume-Based Routing: Distribute traffic by percentage across multiple payment accounts (e.g., 60% to one processor, 40% to another)
• Rule-Based Routing: Define conditional rules to route payments to specific gateways based on payment type, country, amount, or currency
• Default Fallback: Priority-ordered list of payment accounts used when no configuration matches
• Auto-Sync: Payment accounts are automatically added to or removed from the fallback list when created, activated, deactivated, or deleted
• Apple Pay & Google Pay Support: Routes digital wallet transactions alongside traditional card payments

How It Works

When a payment is initiated:

1. The routing engine checks for an active configuration
2. If volume-based: Randomly selects a payment account based on configured percentages
3. If rule-based: Evaluates rules in priority order until a match is found
4. If no configuration or no rule matches: Uses the default fallback priority list
5. The selected payment account processes the transaction

Configuration Types

Volume-Based Configuration

Distributes traffic by percentage across multiple payment accounts using weighted random selection. Over time, the distribution converges to your configured percentages.

Example: 60/40 Split

curl -X POST "https://api.fluid.app/api/fluid_orchestration/configurations" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "configuration": {
      "name": "60/40 Traffic Split",
      "configuration_type": "volume_based",
      "description": "Route 60% to primary processor, 40% to secondary",
      "settings": {
        "distributions": [
          { "payment_account_id": 1, "percentage": 60 },
          { "payment_account_id": 2, "percentage": 40 }
        ]
      }
    }
  }'

Important: Percentages must sum to exactly 100.

Rule-Based Configuration

Routes traffic based on conditional rules evaluated in priority order. The first matching rule determines the payment account.

Example: Route Apple Pay to a Specific Processor

curl -X POST "https://api.fluid.app/api/fluid_orchestration/configurations" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "configuration": {
      "name": "Payment Source Routing",
      "configuration_type": "rule_based",
      "description": "Route Apple Pay to NMI, high-value US orders to Stripe",
      "settings": {
        "rules": [
          {
            "name": "Apple Pay to NMI",
            "priority": 1,
            "payment_account_id": 123,
            "conditions": {
              "payment_source": "apple_pay"
            }
          },
          {
            "name": "High Value US Orders",
            "priority": 2,
            "payment_account_id": 456,
            "conditions": {
              "country_iso": ["US"],
              "amount_greater_than": 500
            }
          }
        ]
      }
    }
  }'

Rules are evaluated in order of priority (lowest number first). If no rule matches, the default fallback is used.

Default Fallback

When no active configuration exists or no rules match, the system uses a priority-ordered list of payment accounts. This list is automatically maintained:

• New active payment accounts are added to the end
• Deactivated or deleted accounts are removed
• You can manually reorder the priority

Supported Conditions

Use these conditions in rule-based configurations to control routing:

Combining Conditions: Multiple conditions in a single rule are evaluated with AND logic. All conditions must match for the rule to apply.

API Reference

Base URL

/api/fluid_orchestration

Get Current Configuration

Returns your complete routing configuration including the active configuration, default fallback, and available payment accounts.

GET /status

Response:

{
  "active_configuration": {
    "id": 1,
    "name": "Volume Based Routing",
    "configuration_type": "volume_based",
    "active": true,
    "settings": {
      "distributions": [
        { "payment_account_id": 1, "percentage": 60 },
        { "payment_account_id": 2, "percentage": 40 }
      ]
    }
  },
  "default_fallback": {
    "priority_order": [
      { "payment_account_id": 1, "name": "Braintree", "priority": 1 },
      { "payment_account_id": 2, "name": "NMI", "priority": 2 }
    ]
  },
  "available_payment_accounts": [...],
  "supported_conditions": [...],
  "configuration_types": ["volume_based", "rule_based"]
}

List All Configurations

GET /status

Create Configuration

POST /configurations

See Configuration Types for request body examples.

Update Configuration

PATCH /configurations/:id

Delete Configuration

DELETE /configurations/:id

Note: You cannot delete an active configuration. Deactivate it first.

Activate Configuration

Activates the specified configuration. Any previously active configuration is automatically deactivated.

POST /configurations/:id/activate

Deactivate Configuration

Deactivates the configuration. The default fallback will be used for routing.

POST /configurations/:id/deactivate

Get Default Fallback

GET /default_fallback

Reorder Default Fallback

PATCH /default_fallback

Request:

{
  "priority_order": [
    { "payment_account_id": 2, "priority": 1 },
    { "payment_account_id": 1, "priority": 2 }
  ]
}

Use Cases

Processor Redundancy

Split traffic between two processors to reduce dependency on a single provider:

{
  "configuration_type": "volume_based",
  "settings": {
    "distributions": [
      { "payment_account_id": 1, "percentage": 50 },
      { "payment_account_id": 2, "percentage": 50 }
    ]
  }
}

Payment Type Optimization

Route different payment methods to processors that offer better rates or features:

{
  "configuration_type": "rule_based",
  "settings": {
    "rules": [
      {
        "name": "Apple Pay",
        "priority": 1,
        "payment_account_id": 123,
        "conditions": { "payment_source": "apple_pay" }
      },
      {
        "name": "Google Pay",
        "priority": 2,
        "payment_account_id": 123,
        "conditions": { "payment_source": "google_pay" }
      }
    ]
  }
}

Geographic Routing

Route transactions to region-specific processors for better approval rates:

{
  "configuration_type": "rule_based",
  "settings": {
    "rules": [
      {
        "name": "European Orders",
        "priority": 1,
        "payment_account_id": 456,
        "conditions": { "country_iso": ["GB", "DE", "FR", "ES", "IT"] }
      },
      {
        "name": "North American Orders",
        "priority": 2,
        "payment_account_id": 789,
        "conditions": { "country_iso": ["US", "CA", "MX"] }
      }
    ]
  }
}

High-Value Transaction Routing

Route high-value transactions to processors with better fraud protection:

{
  "configuration_type": "rule_based",
  "settings": {
    "rules": [
      {
        "name": "High Value Orders",
        "priority": 1,
        "payment_account_id": 456,
        "conditions": { "amount_greater_than": 1000 }
      }
    ]
  }
}

Best Practices

3D Secure (3DS) Compatibility

When configuring routing across multiple payment accounts, ensure all accounts in your configuration use the same 3DS provider. Mixing accounts with different 3DS providers (or accounts with and without 3DS) can cause checkout failures.

Recommendation: Group payment accounts by 3DS provider when creating configurations.

Testing Your Configuration

1. Start with a dry run: Create your configuration but don't activate it immediately
2. Verify payment accounts: Ensure all referenced payment account IDs are valid and active
3. Check percentage totals: For volume-based configs, percentages must sum to 100
4. Test rule ordering: For rule-based configs, verify rules are in the correct priority order
5. Monitor after activation: Watch for any payment failures after activating a new configuration

Configuration Management

• One active configuration: Only one configuration can be active at a time
• Fallback safety: The default fallback ensures payments continue even if rules don't match
• Gradual rollout: Consider starting with a conservative split (e.g., 90/10) when adding a new processor
• Documentation: Use descriptive names and descriptions for your configurations and rules