Smart Routing

PerfectPay evaluates your connected processors in real time and selects the best one for each transaction. Smart routing removes the need for merchants to manage processor selection manually.

Why Smart Routing Matters

• Higher approval rates -- route to the processor most likely to approve each transaction based on card type, BIN, currency, and historical performance
• Lower processing costs -- favor processors with the best interchange and fee structures for each payment profile
• Automatic failover -- if the primary processor declines or times out, PerfectPay retries on the next eligible processor without customer friction

How It Works

1. A payment is created and confirmed
2. PerfectPay evaluates the active routing configuration for the merchant profile
3. The best processor is selected based on the routing strategy
4. If that processor fails, the next eligible processor is tried automatically
5. The payment succeeds on the first processor that approves, or fails after all candidates are exhausted

Routing Strategies

Failover Behavior

When a processor returns a decline, timeout, or error, PerfectPay automatically retries the payment on the next processor in the routing configuration. The customer sees a single payment attempt. Failover happens server-side with no additional client interaction.

You can control failover behavior per routing configuration, including which decline codes trigger a retry and the maximum number of retries.

Configure via Dashboard

1. Open the dashboard at https://app.perfectpay.ai
2. Navigate to Routing
3. Create a new routing configuration and select a strategy
4. Define the rules, priorities, or volume splits
5. Activate the configuration

Configure via API

All routing endpoints use your secret API key.

Create a Routing Configuration

POST /routing

curl https://sandbox.perfectpay.ai/routing \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "US card routing",
    "description": "Priority routing for US card payments",
    "algorithm": {
      "type": "priority",
      "data": [
        { "connector": "stripe", "merchant_connector_id": "mca_abc123" },
        { "connector": "adyen", "merchant_connector_id": "mca_def456" }
      ]
    }
  }'

List Routing Configurations

GET /routing

curl https://sandbox.perfectpay.ai/routing \
  -H "api-key: YOUR_SECRET_API_KEY"

Retrieve a Routing Configuration

GET /routing/{routing_algorithm_id}

curl https://sandbox.perfectpay.ai/routing/routing_abc123 \
  -H "api-key: YOUR_SECRET_API_KEY"

Activate a Routing Configuration

POST /routing/{routing_algorithm_id}/activate

curl https://sandbox.perfectpay.ai/routing/routing_abc123/activate \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Only one routing configuration can be active at a time per profile. Activating a new configuration deactivates the previous one.

Deactivate a Routing Configuration

POST /routing/{routing_algorithm_id}/deactivate

curl https://sandbox.perfectpay.ai/routing/routing_abc123/deactivate \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Volume-Based Example

Split 70% of traffic to Stripe and 30% to Adyen:

curl https://sandbox.perfectpay.ai/routing \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Volume split",
    "algorithm": {
      "type": "volume_split",
      "data": [
        { "connector": "stripe", "merchant_connector_id": "mca_abc123", "split": 70 },
        { "connector": "adyen", "merchant_connector_id": "mca_def456", "split": 30 }
      ]
    }
  }'

Rule-Based Example

Route Visa cards to Stripe and Mastercard to Adyen:

curl https://sandbox.perfectpay.ai/routing \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Card brand routing",
    "algorithm": {
      "type": "rule_based",
      "data": {
        "rules": [
          {
            "condition": [{ "field": "card_network", "operator": "equal", "value": "Visa" }],
            "connectors": [{ "connector": "stripe", "merchant_connector_id": "mca_abc123" }]
          },
          {
            "condition": [{ "field": "card_network", "operator": "equal", "value": "Mastercard" }],
            "connectors": [{ "connector": "adyen", "merchant_connector_id": "mca_def456" }]
          }
        ],
        "default_connectors": [{ "connector": "stripe", "merchant_connector_id": "mca_abc123" }]
      }
    }
  }'

Operational Notes

• Test routing configurations in sandbox before activating in production
• Monitor approval rates per processor in the dashboard after changing routing strategies
• Use the Webhooks guide to track payment outcomes across processors