Online Payment Integration

​

Overview

Knowlix integrates with online payment processors to accept customer payments through eCommerce checkouts, customer portals, and invoice payment pages. Customers pay sales orders, invoices, and subscriptions using credit cards, digital wallets, bank transfers, and regional payment methods without leaving your digital storefront. Payment provider integrations connect your Knowlix system to third-party payment processors that handle sensitive financial data securely. Your database never stores credit card numbers or banking credentials. Instead, payment providers process transactions on their secure servers and return transaction references to Knowlix for record keeping. Configure multiple payment providers to offer customers payment method choices based on their geographic location, currency, or preferred payment type. Each provider supports different payment methods (cards, bank transfers, digital wallets) with varying features like saved payment methods, manual authorization, partial refunds, and express checkout options. All payment transactions integrate with accounting journals, automatically creating financial entries when payments are confirmed. Track payment status from authorization through settlement, manage refunds directly from Knowlix, and reconcile payments with bank statements through standard accounting workflows. Key capabilities:

• Accept online payments through eCommerce and customer portals
• Support for credit cards, digital wallets, and regional payment methods
• Secure tokenization for saved payment methods and recurring billing
• Manual payment authorization with delayed capture
• Full and partial refund processing
• Multi-currency support with automatic exchange rates
• Integration with accounting for automatic journal entries

Important: Payment processor accounts require separate registration with providers. Each processor has its own pricing, supported countries, currencies, and features. Research provider options before selecting integration partners.

💡 Pro Tip: Ask Your Knowlix for payment operations: “Show me failed payment transactions from last week” or “Enable the credit card payment method for customers”

---

​

Payment Provider Types

Different payment processors serve different markets and use cases.

​

Global Payment Processors

Large international payment providers support businesses worldwide with broad currency and payment method coverage. These processors typically offer:

• Credit and debit card processing (Visa, Mastercard, American Express)
• Digital wallet integration (Apple Pay, Google Pay)
• Advanced features (tokenization, manual capture, express checkout)
• Developer-friendly APIs and webhooks
• Fraud detection and chargeback management

Common global processors: Stripe, PayPal, Adyen, Authorize.Net

​

Regional Payment Processors

Regional providers focus on specific geographic markets, offering payment methods popular in those regions. These processors excel at:

• Local payment method support (bank transfers, cash payment systems)
• Local currency processing
• Regional compliance and regulations
• Market-specific fraud prevention
• Lower processing fees for domestic transactions

Regional processor examples:

• Asia-Pacific: AsiaPay, Xendit, Razorpay (India)
• Latin America: Mercado Pago, Nuvei
• Europe: Worldline, Mollie, Buckaroo
• Middle East/Africa: Amazon Payment Services, Flutterwave

​

Bank-Based Payment Methods

Direct bank payment options don’t require third-party processors but involve manual processing: Wire Transfer: Customers receive bank account details and payment reference codes. They complete bank transfers through their banking interfaces. You manually confirm receipt and reconcile payments. SEPA Direct Debit: European banking system for recurring charges. Customers authorize direct debits from their bank accounts. Requires establishing SEPA mandates with signed customer authorization.

---

​

Payment Provider Configuration

Connect payment processors to accept online payments.

​

Enabling Payment Providers

To activate a payment provider:

1. Navigate to Accounting → Configuration → Payment Providers (or eCommerce → Configuration → Payment Providers)
2. Select the provider from the list
3. Configure the Credentials tab:
   • Enter API keys and credentials from the provider’s dashboard
   • Configure webhook URLs for transaction notifications
   • Set authentication tokens and security keys
4. Configure the Configuration tab:
   • Select supported payment methods
   • Set currency and country restrictions
   • Enable optional features (tokenization, manual capture)
   • Configure payment journal assignment
5. Set State to Enabled
6. Click Save

Provider visibility: Enabled providers automatically publish to eCommerce checkouts and customer portals. Customers see available payment methods during checkout based on transaction currency, customer country, and payment amount. Unpublishing providers: Click the Published toggle to hide payment providers without disabling them. Unpublished providers remain configured but don’t appear in payment forms.

​

Test Mode

Try payment integrations without processing real transactions. To enable test mode:

1. Register for the provider’s sandbox or test account
2. Obtain test-mode API credentials
3. In Knowlix, set the provider’s State to Test Mode
4. Enter test credentials in the Credentials tab
5. Process test transactions using provider-supplied test card numbers

Test mode transactions create transaction records in Knowlix but don’t charge real payment methods or appear on actual bank statements.

Testing best practice: Use test mode on duplicate databases or staging environments to avoid confusion with production transaction numbering and accounting sequences.

💡 Your Knowlix: “Switch Stripe to test mode” or “Show me test payment transactions”

---

​

Payment Methods

Individual payment methods connect to payment providers.

​

Payment Method Management

Payment providers support various payment methods (credit cards, bank transfers, digital wallets). Configure which methods are available to customers:

1. Navigate to Accounting → Configuration → Payment Providers
2. Select a provider
3. In the Configuration tab, click Enable Payment Methods
4. Toggle individual payment methods on or off
5. Drag and drop methods to reorder their display sequence

Payment method visibility: Customers see only payment methods that meet all criteria:

• Method is enabled for the provider
• Provider supports customer’s currency
• Provider supports customer’s country
• Transaction amount is within method limits

​

Payment Method Icons

Customize payment method branding displayed during checkout. To modify method icons:

1. Navigate to Accounting → Configuration → Payment Methods
2. Select the payment method
3. Hover over the icon image and click the edit icon
4. Upload a new image
5. Save

Brand icons: Payment methods like “Credit Card” show logos for supported card brands (Visa, Mastercard, Amex). Configure brand icons in the Brands tab of the payment method form.

---

​

Tokenization (Saved Payment Methods)

Allow customers to save payment details for future purchases.

​

How Tokenization Works

When tokenization is enabled, customers can opt to save their payment information during checkout. The payment provider creates a secure token representing the payment method. Knowlix stores this token reference (not actual card numbers) for future use. Benefits:

• Faster checkout for returning customers
• Enables recurring subscription payments
• Improves conversion rates
• Maintains PCI compliance (no card data storage)

Customer control: Customers manage saved payment methods through the customer portal. They can add new payment methods, delete saved methods, or assign saved methods to subscriptions.

​

Enabling Tokenization

To allow saved payment methods:

1. Navigate to Accounting → Configuration → Payment Providers
2. Select a provider that supports tokenization
3. Open the Configuration tab
4. Enable Allow Saving Payment Methods
5. Save

Provider support: Not all payment providers support tokenization. Check provider documentation for availability and requirements.

💡 Subscription Integration: Tokenized payment methods are essential for recurring subscription billing. Customers authorize one-time, and subscriptions charge automatically without manual payment each billing cycle.

---

​

Manual Payment Capture

Authorize payments separately from capturing funds.

​

Two-Step Payment Processing

Manual capture splits payment processing into authorization and capture phases: Authorization: Verifies payment method validity and reserves funds. The customer’s available credit decreases, but no money transfers yet. Capture: Actually charges the payment method and transfers funds. Can be done hours or days after authorization. Use cases:

• Pre-shipment verification: Authorize at order placement, capture at shipment
• Fraud review: Authorize payment, review order legitimacy, then capture
• Refund cost avoidance: Void authorizations instead of refunding captured payments (many providers don’t charge fees for voiding)
• Deposit holds: Authorize larger amounts, capture actual charges, void the remainder

​

Enabling Manual Capture

To activate manual capture:

1. Navigate to Accounting → Configuration → Payment Providers
2. Select a provider that supports manual capture
3. Open the Configuration tab
4. Enable Capture Amount Manually
5. Save

​

Capturing Authorized Payments

To capture payment:

1. Navigate to the sales order or invoice
2. Locate the Capture Transaction button
3. Verify the capture amount
4. Click Capture Transaction

The payment processes immediately and funds transfer to your account. To void authorization: Click Void Transaction instead of capturing. Funds release back to the customer’s payment method without charging. Partial capture: Some providers allow capturing only part of the authorized amount. For example, authorize $500, capture$450, void the remaining $50. Partial capture availability depends on provider capabilities.

Authorization expiration: Payment providers automatically void authorizations after a timeout period (typically 7-30 days depending on provider). Capture payments before expiration or authorizations cancel automatically.

💡 Your Knowlix: “Capture payment for sales order SO025” or “Show me pending authorized payments”

---

​

Refund Processing

Return payments to customers directly from Knowlix.

​

Issuing Refunds

For supported providers, process refunds without accessing provider dashboards:

1. Navigate to the payment transaction
2. Click Refund
3. Enter the refund amount (full or partial based on provider support)
4. Add a refund reason (internal reference)
5. Click Confirm Refund

The refund processes immediately through the payment provider. Funds typically return to customer payment methods within 5-10 business days depending on banking institutions. Refund capabilities:

• Full refunds: Return entire transaction amount
• Partial refunds: Return portion of transaction (if provider supports partial refunds)
• Multiple partial refunds: Issue several partial refunds until full amount is refunded

Accounting integration: Refunds automatically create accounting journal entries to reverse the original payment entry and adjust revenue accounts.

---

​

Express Checkout

Enable one-click payments with digital wallets.

​

Express Checkout Options

Express checkout allows customers to skip checkout form fields by using saved payment information from digital wallet providers: Apple Pay: iPhone and Mac users authenticate with Touch ID or Face ID Google Pay: Android users and desktop Chrome users authenticate with saved Google payment methods Customer experience:

1. Customer clicks express checkout button (Apple Pay or Google Pay) on the cart page
2. Payment provider displays payment confirmation dialog with shipping and billing addresses from the wallet
3. Customer authenticates (fingerprint, face scan, or PIN)
4. Payment processes and order confirms immediately

​

Enabling Express Checkout

To activate express checkout:

1. Navigate to Accounting → Configuration → Payment Providers
2. Select a provider that supports express checkout (Stripe, Adyen)
3. Open the Configuration tab
4. Enable Allow Express Checkout
5. Configure required provider-specific settings
6. Save

Pricing note: Express checkout payment forms always display prices including taxes regardless of your standard tax display settings.

---

​

Payment Availability Restrictions

Control when payment providers are available to customers.

​

Currency Restrictions

Payment providers support different currency lists. Configure the Currencies field to limit availability:

• Specified currencies: Provider only appears for transactions in listed currencies
• Empty currency list: Provider available for all currencies (some providers may decline unsupported currencies during processing)

​

Country Restrictions

Limit providers based on customer billing country: Configure the Countries field to restrict availability:

• Specified countries: Provider only appears for customers in listed countries
• Empty country list: Provider available for all countries

​

Maximum Amount Limits

Set transaction amount maximums for payment methods:

1. Navigate to Accounting → Configuration → Payment Providers
2. Select the provider
3. In the Configuration tab, set Maximum Amount
4. Save

Providers with maximum amounts only appear for transactions below the threshold. Set to 0.00 for no limit. Use case: Restrict high-risk or low-margin payment methods (like American Express with higher fees) to smaller transactions.

---

​

Payment Journal Configuration

Connect payment providers to accounting journals.

​

Journal Assignment

Payment providers must link to accounting journals to create financial entries:

1. Navigate to Accounting → Configuration → Payment Providers
2. Select the provider
3. Open the Configuration tab
4. Select a Payment Journal (must be Bank journal type)
5. Save

Default behavior: By default, all payment providers use the primary “Bank” journal. For better transaction tracking, create dedicated journals for each provider:

1. Navigate to Accounting → Configuration → Journals
2. Click New
3. Select Bank journal type
4. Name it after the provider (e.g., “Stripe Payments”)
5. Configure the bank account
6. Save
7. Assign this journal to the payment provider

​

Outstanding Accounts

Payments from third-party processors may not deposit immediately into your bank account. Configure outstanding accounts for cleaner accounting:

1. Open the payment provider
2. Configure an Outstanding Account separate from your bank account
3. Save

Accounting workflow with outstanding accounts:

1. Customer pays online → Creates entry crediting Outstanding Account
2. Provider deposits funds to bank → Manual journal entry moves from Outstanding to Bank Account
3. Bank statement reconciliation → Confirms the deposit

This workflow separates provider settlements from customer payments for clearer cash flow tracking.

---

​

Security and Compliance

​

PCI Compliance

Payment provider integrations keep Knowlix PCI compliant by design:

• No card storage: Credit card numbers never touch Knowlix servers
• Tokenized references: Only secure provider-issued tokens store in the database
• Minimal PCI scope: Your PCI compliance requirements reduce to provider selection and basic security practices

Compliance documentation: Most payment providers offer PCI compliance attestation documents upon request. Consult providers for Self-Assessment Questionnaires (SAQ) relevant to your implementation.

​

Webhook Security

Payment providers send transaction updates via webhooks (HTTP callbacks to your Knowlix server). Knowlix validates webhook authenticity using:

• Signature verification: Cryptographic signatures prove messages originate from the provider
• Secret keys: Shared secrets known only to you and the provider
• HTTPS encryption: All webhook traffic uses encrypted connections

Never disable webhook signature validation or expose webhook secrets.

---

​

Payment Transaction Management

​

Viewing Transactions

To access payment transactions: Navigate to Accounting → Configuration → Payment Transactions (Requires developer mode) Transaction information:

• Reference: Internal transaction identifier
• Provider: Which payment provider processed the transaction
• Amount: Transaction value and currency
• State: Current transaction status
• Customer: Who made the payment
• Payment Method: How they paid
• Tokenization Status: Whether payment method was saved

​

Transaction States

Draft: Transaction created but not yet submitted to provider Pending: Awaiting confirmation from payment provider Authorized: Payment method verified, funds reserved, not yet captured Confirmed: Payment successfully processed and captured Cancelled: Transaction cancelled before completion Error: Payment processing failed

​

Transaction Troubleshooting

To diagnose payment issues:

1. Enable developer mode
2. Navigate to Accounting → Configuration → Payment Transactions
3. Open the failed transaction
4. Review the State Message field for provider error details
5. Check Provider Reference for provider-side transaction ID
6. Consult provider dashboard for additional error details

Common failure causes:

• Invalid or expired credentials
• Insufficient customer funds
• Bank decline (fraud prevention)
• Currency or country restrictions
• Provider service outages

💡 Your Knowlix: “Show me failed transactions from this month” or “Find transactions for customer ABC Corp”

---

​

Best Practices

​

Offer Multiple Payment Methods

Different customers prefer different payment methods. Provide at least one card processor and one alternative (PayPal, digital wallets, or regional methods) to maximize conversion.

​

Test Before Going Live

Always test payment flows in test mode before enabling production credentials. Verify successful payments, refunds, and failure scenarios with test card numbers.

​

Monitor Failed Transactions

Review failed payment reports weekly. High failure rates indicate configuration issues, customer friction, or fraud problems requiring attention.

​

Keep Credentials Secure

Payment provider API keys grant access to financial transactions. Store credentials securely, limit access to authorized administrators, and rotate keys if compromise is suspected.

​

Configure Appropriate Availability Restrictions

Don’t enable payment providers for unsupported currencies or countries. Customers experience poor experience when payment methods appear but fail during processing.

​

Use Webhooks for Real-Time Updates

Configure webhooks properly so transaction status updates immediately. Without webhooks, status updates delay until customer returns to confirmation pages.

​

Set Up Dedicated Payment Journals

Create separate accounting journals for each major payment provider. This simplifies reconciliation, fee tracking, and financial reporting.

​

Review Provider Fee Structures

Payment processing fees vary significantly between providers and payment methods. Understand the total cost (transaction fees, currency conversion, monthly minimums) before selecting providers.

​

Keep Provider Integrations Updated

Payment providers occasionally update APIs or security requirements. Monitor provider communications for mandatory updates and apply them promptly.

​

Document Provider Credentials

Maintain secure documentation of which team members have provider dashboard access, where credentials are stored, and how to recover access if needed.

​

Plan for Provider Downtime

Payment processors occasionally experience outages. Have backup providers configured or alternative payment methods (like wire transfer) available during primary provider downtime.

​

Comply with Regional Regulations

Different countries have different payment processing regulations (PSD2 in Europe, PCI DSS globally). Ensure your provider selection and configuration comply with applicable laws.

---

​

Troubleshooting Common Issues

​

Provider Won’t Enable

Possible causes:

• Missing required credentials
• Invalid API keys (typos, wrong environment keys)
• Webhook URL not accessible from provider servers
• Provider account not fully activated

Resolution: Double-check credentials match provider dashboard exactly. Ensure your Knowlix installation is publicly accessible (not localhost). Verify provider account is active and verified.

​

Payment Methods Don’t Appear at Checkout

Possible causes:

• Provider not published
• Currency restrictions exclude transaction currency
• Country restrictions exclude customer location
• Amount exceeds maximum limit
• Payment method not enabled for provider

Resolution: Review availability restrictions in provider configuration. Enable developer mode and use the payment form diagnostics tool (bug icon on payment form) to see exact availability reasons.

​

Customers Can’t Save Payment Methods

Possible causes:

• Tokenization not enabled on provider
• Provider doesn’t support tokenization feature
• Customer payment method type doesn’t support tokenization

Resolution: Enable “Allow Saving Payment Methods” on provider configuration. Verify the provider supports tokenization in their documentation.

​

Webhooks Not Working

Possible causes:

• Webhook URL incorrect in provider dashboard
• Webhook signature validation failing (wrong secret key)
• Firewall blocking provider webhook IPs
• HTTPS certificate invalid

Resolution: Verify webhook URL in provider dashboard matches exactly. Check webhook secret keys. Review server logs for incoming webhook requests. Confirm SSL certificate is valid and trusted.

​

Refunds Failing

Possible causes:

• Provider account lacks refund permissions
• Original transaction too old (some providers limit refund windows)
• Insufficient funds in provider account
• API credentials lack refund capability

Resolution: Check provider dashboard permissions. Verify transaction is within refund window. Some providers require manual refund processing through their dashboard.

​

Test Mode Transactions Appearing in Production

Possible causes:

• Provider state set to “Enabled” instead of “Test Mode”
• Using production credentials in test environment
• Test transactions not properly flagged

Resolution: Verify provider state is “Test Mode” when testing. Use test environment credentials, not production keys. Keep test and production databases separate.

---

​

Related Documentation

• Accounting - Journal configuration and financial entries
• eCommerce - Online payment checkout flows
• Subscriptions - Recurring payment configuration
• Customer Portal - Online invoice payment

---

​

Need Help?

Ask Your Knowlix:

• “Enable Stripe payment provider”
• “Show me pending payment authorizations”
• “Which payment methods are available for EUR transactions?”
• “Refund transaction PAY-12345”
• “Show failed payments from last week”
• “Configure tokenization for credit cards”

Contact Support: For questions about payment provider selection, API credential configuration, webhook troubleshooting, or PCI compliance requirements, contact Knowlix support through the Help menu or consult your payment provider’s technical documentation.

---

​

Provider-Specific Notes

Knowlix supports integration with numerous payment processors. Each provider has unique configuration requirements, supported features, and geographic availability. Consult provider documentation and support resources for detailed setup instructions specific to your chosen providers. When selecting providers, consider:

• Geographic coverage (supported countries)
• Currency support
• Payment method availability
• Transaction fees and pricing
• Settlement timing (how quickly funds reach your account)
• Feature support (tokenization, manual capture, refunds)
• Technical support quality
• Compliance and certification

Implementation Support: For detailed provider-specific configuration guidance, consult payment provider documentation, contact provider support teams, or work with your Knowlix implementation partner for setup assistance.