--- title: "Payment Gateways" description: "Configure and manage payment gateways to process transactions in Spark CRM." --- > Documentation Index > Fetch the complete documentation index at: https://docs.sparkcrm.io/llms.txt > Use this file to discover all available pages before exploring further. # Payment Gateways Payment gateways connect Spark CRM to payment processors, enabling you to accept credit card payments from your customers. **Navigation**: Sidebar > Payments > Gateways ![screenshot of gateways list page](/assets/gateways/spark_gw_1.png) --- ## Supported Gateway Types Spark CRM supports the following payment processors: | Gateway | Description | Use Case | |---------|-------------|----------| | **NMI (Network Merchants)** | Popular payment gateway with extensive features | High-volume merchants, subscription billing | | **Stripe** | Modern payment platform with global coverage | Startups, SaaS, international sales | | **Authorize.net** | Established gateway with broad compatibility | Traditional e-commerce, existing integrations | | **Finix** | Payment infrastructure platform | Enterprise, custom payment flows | | **Breeze** | Merchant-of-record card processor with built-in 3D Secure, tokenization, and subscriptions | Card payments that require 3DS authentication | | **ConvesioPay** | Card processor with signed webhook notifications | Merchants on ConvesioPay's platform | | **PayNetWorx** | Token-authenticated card processor | Merchants on PayNetWorx | | **Highwire Payments** | Card processor with sandbox support | Existing Highwire merchants | | **Highwire Payments V2** | Current-generation Highwire integration | New Highwire merchants | | **Big Dogs Payments** | Card processor with a configurable endpoint | Merchants on Big Dogs | | **Swiparas** | Card processor with optional server-side Adyen CSE card encryption and optional HMAC-signed webhooks | Merchants on Swiparas | | **BridgePay** | Card processor addressed by merchant account code | Merchants on BridgePay | | **Bulletproof Checkout** | Card processor with key and credential pair authentication | Merchants on Bulletproof | | **Sandbox (Testing)** | Testing gateway for development | Testing and development only | --- ## Adding a Gateway ### Step 1: Navigate to Gateways 1. Go to **Payments > Gateways** in the sidebar 2. Click the **New Gateway** button (top right of the Gateways page) ![screenshot of New Gateway button location](/assets/gateways/spark_gw_2.png) ### Step 2: Configure Basic Information Enter the gateway details: - **Name**: A descriptive name for this gateway (e.g., "Production Stripe", "NMI Sandbox") - **Gateway**: Select your payment processor (the dropdown is sorted alphabetically) - **Status**: Active, Inactive, Pending, Error or Suspended. Only **Active** gateways are used for new transactions, rebills, salvage and cascade routing — any other status stops processing. - **Category**: Optional grouping for organization > **Required to save**: Name, Gateway, Status, Accepted Currencies (Step 6), Accepted Card Brands (Step 4), Timezone (Step 6) and Monthly Processing Limit (Step 5). Currencies default to USD, card brands to all four and Timezone to UTC — at least one card brand must stay selected — but Monthly Processing Limit starts blank — the gateway will not save until you enter a value (enter 0 if you don't want to track a ceiling). ![screenshot of gateway form - basic information section](/assets/gateways/spark_gw_3.png) ### Step 3: Enter Credentials Each gateway type requires specific credentials: #### NMI Credentials Choose one authentication method: **Security Key Method:** - Security Key **Username/Password Method:** - Username - Password ![screenshot of NMI credentials form](/assets/gateways/spark_gw_4.png) #### Stripe Credentials - **Publishable Key**: Your Stripe publishable key (starts with `pk_`) - **Secret Key**: Your Stripe secret key (starts with `sk_`) - **Webhook Secret**: Optional, for webhook verification ![screenshot of Stripe credentials form](/assets/gateways/spark_gw_5.png) #### Authorize.net Credentials - **API Login ID**: Your Authorize.net API login - **Transaction Key**: Your transaction key - **Signature Key**: Optional, for response verification ![screenshot of Authorize.net credentials form](/assets/gateways/spark_gw_6.png) #### Finix Credentials - **Username**: Finix API username - **Password**: Finix API password - **Merchant ID**: Your Finix merchant identifier - **Test Mode**: Optional. Enable to route through Finix's sandbox/QA environment. New Finix gateways are created with Test Mode **off** (production). #### Sandbox (Testing) Credentials - **Mode**: Choose behavior - `always_approve` - All transactions succeed - `always_decline` - All transactions fail - `random` - Random success/failure based on decline percentage - **Decline Percentage**: When mode is `random`, percentage of transactions to decline (0-100) #### Breeze Credentials - **API Key**: Your Breeze secret API key — starts with `sk_test_` for sandbox or `sk_live_` for production - **Webhook Secret**: Optional. The webhook signing secret from your Breeze dashboard, used to verify incoming payment notifications - **Risk SDK Key**: Optional in Spark CRM, but Breeze expects a risk session on customer-initiated card payments. Your checkout page uses this key to load Breeze's Risk JS SDK and pass `payment.risk_session_id` on the order. Merchant-initiated charges — subscription rebills and saved-card upsells — omit the risk object entirely. - **Test Mode**: Routes through Breeze's sandbox environment. Defaults to **on** for this gateway type. > **Test Mode starts ON for this gateway type.** Selecting Breeze automatically switches Test Mode on and charges post to Breeze's sandbox host (`secure-sandbox.breeze.cash`). Turn Test Mode **off** and save before you send live traffic — live credentials with Test Mode on take no real money. > **Webhook setup**: After you select Breeze, the credentials form displays a **webhook URL**. Copy it into your Breeze dashboard's webhook settings so Spark CRM receives payment status updates (successful payments, refunds, expirations). > **Important — 3D Secure is required**: Breeze authenticates every **customer-initiated** card payment with 3D Secure — new *and* saved cards. Your checkout must complete a short customer redirect before the payment is captured. Wire your funnel using [Breeze 3D Secure Checkout](/payment-processing/breeze-3ds-checkout). Subscription rebills **and one-click upsells that reuse a card already on file** are sent as merchant-initiated stored-credential charges: they skip 3DS and the risk session, and process with no redirect. #### ConvesioPay Credentials - **Secret Key**: Your ConvesioPay secret key - **API Key**: Your ConvesioPay API key - **Integration Name**: The integration identifier issued by ConvesioPay - **Webhook Signature Key**: Used to verify inbound payment notifications - **Test Mode**: Enable to route through the sandbox environment #### PayNetWorx Credentials - **Access Token User**: Your PayNetWorx access token user - **Access Token Password**: Your PayNetWorx access token password - **Test Mode**: Enable to route through the sandbox environment #### Highwire Payments Credentials - **Merchant Username**: Your Highwire merchant username - **Merchant Password**: Your Highwire merchant password - **Test Mode**: Enable to route through Highwire's sandbox environment Highwire Payments V2 takes the same three fields. > **Test Mode starts ON for this gateway type.** Selecting Highwire Payments V2 automatically switches Test Mode on and charges post to Highwire's staging host (`api-payments-staging.highwirepayments.com`). Turn Test Mode **off** and save before you send live traffic — live credentials with Test Mode on take no real money. V2 is a separate gateway type rather than an upgrade in place, so existing **Highwire Payments** gateways keep processing unchanged. To move over: create a new V2 gateway, **turn Test Mode off**, test the connection, then switch your orchestrator over to it. #### Big Dogs Payments Credentials - **Base URL**: The processing endpoint issued to your account - **Username**: Your Big Dogs username - **Password**: Your Big Dogs password - **Test Mode**: Recorded but **not used** by the Big Dogs integration. Sandbox versus production is decided entirely by the **Base URL** above - point it at the sandbox endpoint Big Dogs issued you for testing, and change it to the production URL when you go live. #### Swiparas Credentials - **API Key**: Your Swiparas API key - **Merchant Account**: Your Swiparas merchant account identifier - **Store ID**: Optional store identifier, when your account is split across stores - **CSE Public Key**: Optional. When supplied, Spark CRM encrypts the card into an Adyen CSE blob on the server before sending it to Swiparas, so raw card data never reaches the processor. (Checkouts that already send a client-side pre-encrypted card are passed through unchanged and do not use this key.) - **Webhook HMAC Key**: Optional. Verifies inbound payment notifications - **Base URL**: Optional override for the processing endpoint - **Test Mode**: Routes through the sandbox environment. Defaults to **on** for this gateway type. > **Test Mode starts ON for this gateway type.** Selecting Swiparas automatically switches Test Mode on and charges post to the Adyen test host (`checkout-test.adyen.com`). Turn Test Mode **off** and save before you send live traffic — live credentials with Test Mode on take no real money. #### BridgePay Credentials - **Username**: Your BridgePay username - **Password**: Your BridgePay password - **Merchant Account Code**: The merchant account code issued by BridgePay - **Test Mode**: Routes through the sandbox environment. Defaults to **on** for this gateway type. > **Test Mode starts ON for this gateway type.** Selecting BridgePay automatically switches Test Mode on and charges post to BridgePay's test host (`bridgepaynetsecuretest.com`). Turn Test Mode **off** and save before you send live traffic — live credentials with Test Mode on take no real money. #### Bulletproof Checkout Credentials - **API Key**: Your Bulletproof API key - **API Secret**: Your Bulletproof API secret - **Username**: Your Bulletproof username - **Password**: Your Bulletproof password - **Test Mode**: Enable to route through the sandbox environment ### Step 4: Configure Card Processing Settings ![screenshot of card processing settings section](/assets/gateways/spark_gw_7.png) **Accepted Card Brands:** - Visa - Mastercard - Discover - American Express **Card Options:** - **Accept Prepaid Cards**: Allow prepaid/gift cards - **Accept Virtual Cards**: Recorded for reference only. Spark CRM stores this flag and shows it on the gateway's orchestrator panel, but it does not currently block virtual card numbers. (Only **Accept Prepaid Cards** is enforced during routing.) - **Accept International Cards**: Defaults to **off** for gateways created in the UI, and is currently informational only — Spark CRM records the flag but does not block foreign-issued cards either way. - **Use Dynamic Descriptors**: Stored for reference only. Spark CRM does not vary the descriptor it sends to the processor, so toggling this changes nothing in the outbound request. ### Step 5: Configure Financial Settings ![screenshot of financial settings section](/assets/gateways/spark_gw_8.png) - **Monthly Processing Limit** (required): Your monthly volume ceiling. Drives the usage bar on the gateway list and the capacity alert notifications — it does not block transactions on its own. The gateway will not save while this is blank; enter 0 if you do not want to track a ceiling. - **Daily Processing Limit**: Optional. When set, new sales stop routing to this gateway once that day's approved volume plus the pending charge would exceed it; subscription rebills are excluded from this check during normal gateway selection and their volume does not count toward the day's total. Counters reset at midnight in the gateway's Timezone (Step 6). - **Monthly Fee**: Gateway monthly fee (for cost tracking) - **Reserve Rate**: Percentage held in reserve - **Discount Rate**: Processing discount rate - **Transaction Fee**: Per-transaction fee - **Reserve Term Days**: Days funds held in reserve - **Support URL**: Link to your support page (this field sits with the fee fields, not with the other support fields) ### Step 6: Configure Regional Settings - **Accepted Currencies**: Which currencies this gateway can process (e.g., USD, EUR, GBP) - **Timezone**: The timezone whose midnight resets this gateway's daily and monthly processing counters (required; defaults to UTC). The gateway list shows it as *Resets at midnight · ``*. ### Step 7: Configure Statement Descriptor Record the descriptor your processor is configured to show on customer statements: - **Statement Descriptor**: The descriptor your processor shows on customer card statements. Spark CRM records it for reference — it appears in receipt emails and is returned as `gateway_descriptor` in DTC API responses, but it is **not sent to the processor**, so the real descriptor must be set with your processor. Accepts up to 255 characters without truncation, but most card networks cut the descriptor at roughly 22 characters — keep it short. - **Statement Descriptor Phone**: Support phone number on statements ### Step 8: Configure Support Information Contact information for customer support: - **Support Phone**: Customer support phone number - **Support Email**: Customer support email ### Step 9: Save and Test 1. Click **Create Gateway** to create the gateway 2. After saving, find the gateway in the list, open the **three-dot menu (...)** > **Connection Status**, then click **Test Now** to verify the credentials ![screenshot of Test Connection button and success message](/assets/gateways/spark_gw_9.png) --- ## Managing Gateways ### Gateway List View The gateway list displays: | Column | Description | |--------|-------------| | **ID** | The gateway's internal ID (default sort, newest first) | | **Name** | Gateway display name — click it to edit | | **Gateway** | Gateway processor type | | **Monthly Limit** | Month-to-date approved volume against the monthly limit, with a progress bar; adds a second daily bar when a Daily Processing Limit is set, and shows the timezone the counters reset in. Displays a **No Limit** badge when neither limit is configured | | **Discount Rate** | The gateway's processing discount rate | | **Category** | Optional grouping | | **Status** | Active, Inactive, Pending Configuration, Connection Error or Suspended (only **Active** processes transactions) | | **Last Transaction** | Most recent successful transaction | | **Actions** | Three-dot menu (...): Edit, Connection Status, Duplicate, Delete | ![screenshot of gateway list with all columns visible](/assets/gateways/spark_gw_10.png) ### Filtering and Searching - **Search**: Filter by gateway name - **Category Filter**: Filter by gateway category ### Gateway Categories Organize gateways into categories for easier management: 1. On the Gateways page, click **Add Category** (or, while creating or editing a gateway, click **New Category** beside the Category field) 2. Enter category name 3. Click **Create Category** (or **Create & Assign** if you opened the modal from inside the gateway form). Category names must be at least 2 characters and unique within your team. Assign gateways to categories when creating or editing them. --- ## Testing Gateway Connections ### Connection Test Verify your gateway credentials work correctly: 1. Locate the gateway in the list 2. Click the **three-dot menu** (...) 3. Select **Connection Status** **Successful Test:** - Green success message - `last_connection_test_at` updated - Gateway ready for transactions **Failed Test:** - Red error message with details - Check credentials and try again - Verify IP allowlists on processor side ![screenshot of connection test success message](/assets/gateways/spark_gw_11.png) ### Connection Details Modal View detailed connection information: 1. View connection status and history 2. Click **Test Now** to run a new test ![screenshot of connection test success message](/assets/gateways/spark_gw_12.png) --- ## Editing a Gateway 1. Find the gateway in the list 2. Click the **three-dot menu** (...) 3. Select **Edit** 4. Modify settings as needed 5. Click **Update Gateway** **Note**: Changing credentials requires retesting the connection. --- ## Deleting a Gateway **Warning**: Deleting a gateway removes it from your list and stops it processing immediately. Ensure no active campaigns or orchestrators reference it. The record is archived rather than erased — creating a new gateway with the **same name** restores the archived record (keeping its internal ID and any payment-router attachments) and overwrites it with your new settings, so use a different name if you want a genuinely fresh gateway. 1. Find the gateway in the list 2. Click the **three-dot menu** (...) 3. Select **Delete** 4. Type the gateway name to confirm 5. Click **Delete Gateway** ![screenshot of delete confirmation modal](/assets/gateways/spark_gw_13.png) --- ## Gateway Status These are the labels shown in the list's Status column; the Status dropdown on the gateway form lists the same five as Active, Inactive, Pending, Error and Suspended. | Status | Description | |--------|-------------| | **Active** | The only status that processes. Available for new sales, rebills, salvage and cascade routing | | **Inactive** | Disabled; not used for any new transactions | | **Pending Configuration** | Not used for any new transactions. Gateways created through the API start here | | **Connection Error** | Not used for any new transactions | | **Suspended** | Not used for any new transactions | Only **Active** gateways process. Setting any other status stops new charges, subscription rebills, decline salvage and cascade retries on that gateway immediately, without further warning. Set a gateway to Inactive to temporarily disable it without deleting configuration. --- ## Sandbox vs Production ### Testing with Sandbox For development and testing: 1. Create a gateway with type **Sandbox (Testing)** 2. Configure the mode (always approve, always decline, or random) 3. Process test transactions **Test Card Numbers (Sandbox):** - Any valid card format will work - Use `4111111111111111` as a standard test number - Expiry: Any future date - CVV: Any 3 digits ### Going to Production When ready for real transactions: 1. Create a **new** gateway with production credentials 2. Test the connection 3. Update campaigns to use the production gateway 4. Keep sandbox gateway for future testing **Important**: Never delete your sandbox gateway - keep it for testing new features. --- ## Best Practices ### Gateway Naming Use clear, descriptive names: - `Production - Stripe USD` - `NMI - High Risk` - `Sandbox - Testing` ### Multiple Gateways Set up multiple gateways for: - **Redundancy**: Backup if primary fails - **Optimization**: Route by card type or region - **Testing**: Separate sandbox from production ### Monitoring Regularly check: - Connection test status - Monthly processing vs limits - Transaction success rates (via Payment Report) ### Security - Use unique credentials per gateway - Rotate keys periodically - Monitor for unauthorized access --- ## Troubleshooting ### Connection Test Fails **Check:** - Credentials are correct - Gateway account is active - IP allowlist includes Spark CRM servers - Sandbox vs production mode matches credentials ### Transactions Declined **Check:** - Gateway status is Active - Card brand is in accepted list - Currency is supported - The gateway's **Daily Processing Limit** has not been reached, and the gateway's monthly cap on the payment orchestrator has not been reached. (The gateway's own **Monthly Processing Limit** is for tracking and capacity alerts only — it never blocks a charge.) ### Gateway Not Appearing **Check:** - Gateway was saved successfully - You're viewing the correct team - Search/filters are cleared --- ## Related Topics - [Payment Orchestrators](/payment-processing/orchestrators) - Route transactions across multiple gateways - [Cascade Profiles](/payment-processing/cascade-profiles) - Retry declines on backup gateways immediately - [Decline Mappings](/payment-processing/decline-mappings) - Standardize decline codes - [Decline Salvage](/payment-processing/decline-salvage) - Recover failed transactions Source: https://docs.sparkcrm.io/payment-processing/gateways/index.mdx