Connectors

Connectors are how PerfectPay talks to payment processors, acquirers, PSPs, and alternative payment providers. Each connector maps to one external provider and carries the credentials, configuration, and capability metadata needed to route transactions through it.

PerfectPay supports 140+ connectors out of the box. You can enable as many as you need per merchant account and use smart routing to distribute traffic across them.

What Counts as a Connector

A connector is any external payment service that PerfectPay can send transactions to:

• Card processors -- Stripe, Adyen, Checkout.com, Worldpay, NMI, and others
• Bank transfer providers -- Plaid, GoCardless, SEPA-capable acquirers
• Wallet providers -- PayPal, Apple Pay, Google Pay (via processor integrations)
• Alternative payment methods -- Klarna, Affirm, Afterpay, Boleto, iDEAL, UPI
• Real-time payment networks -- FedNow and RTP-capable providers
• Crypto on-ramps -- stablecoin and crypto settlement providers

Adding a Connector

Via the Dashboard

1. Open Connectors in the sidebar
2. Click Add Connector
3. Select the provider from the list
4. Enter the credentials the provider gave you (API key, merchant ID, terminal ID, etc.)
5. Choose which payment methods this connector should handle
6. Save

Via the API

POST /account/{account_id}/connectors

curl https://sandbox.perfectpay.ai/account/acct_abc123/connectors \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connector_type": "fiz_operations",
    "connector_name": "stripe",
    "connector_account_details": {
      "auth_type": "HeaderKey",
      "api_key": "sk_test_..."
    },
    "payment_methods_enabled": [
      {
        "payment_method": "card",
        "payment_method_types": [
          { "payment_method_type": "credit" },
          { "payment_method_type": "debit" }
        ]
      }
    ],
    "test_mode": true
  }'

Multiple Connectors per Merchant

You are not limited to one connector. Most production setups use two or more to get:

• Failover -- if one processor is down or declines a transaction, PerfectPay retries on the next eligible connector automatically
• Cost optimization -- route domestic transactions to the cheapest acquirer for that region
• Method coverage -- one processor handles cards while another handles bank transfers or wallets
• Redundancy for restricted industries -- maintain backup processors so a single provider pulling support does not stop your business

See the smart routing guide for how to configure routing rules across connectors.

Connector Account Configuration

Each connector stores:

Credential shapes vary. Some connectors need a single API key (HeaderKey), others need a key pair (BodyKey), and some need a full certificate chain for mTLS.

Supported Connector Types

PerfectPay groups connectors by function:

• fiz_operations -- standard payment processing (authorize, capture, void, refund)
• payout_processor -- outbound disbursements and payouts
• three_ds_authenticator -- external 3DS authentication providers

A single provider can appear as more than one type if it supports both payment processing and payouts.

Testing with Sandbox Connectors

Every connector supports a sandbox mode. Set "test_mode": true when adding the connector and use the provider's test credentials.

Sandbox connectors:

• Process against the provider's test environment
• Accept test card numbers and test bank accounts
• Do not move real money
• Return the same response shapes as production

Use https://sandbox.perfectpay.ai as your API base during development. See the testing guide for test card numbers and sandbox behavior.

Managing Connectors

List all connectors for a merchant:

curl https://sandbox.perfectpay.ai/account/acct_abc123/connectors \
  -H "api-key: YOUR_SECRET_API_KEY"

Update a connector's credentials or enabled methods:

curl https://sandbox.perfectpay.ai/account/acct_abc123/connectors/{connector_id} \
  -X PUT \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connector_account_details": {
      "auth_type": "HeaderKey",
      "api_key": "sk_live_new_key..."
    }
  }'

Delete a connector:

curl https://sandbox.perfectpay.ai/account/acct_abc123/connectors/{connector_id} \
  -X DELETE \
  -H "api-key: YOUR_SECRET_API_KEY"

Next Steps

• Smart Routing -- configure rules for distributing traffic across connectors
• Payment Rails -- understand which rails are available
• Payments -- create and confirm payments through your connectors