Virtual Terminal

Take credit card payments straight from your Kantivo desktop accounting software. Useful for phone payments, counter charges, and any time a self-serve checkout link isn't the right fit.

Gateway Setup

Kantivo's virtual terminal runs on top of your active Stripe gateway. If you haven't connected one yet:

1. Go to Settings → Payment Gateway Settings
2. Click Add Gateway and pick Stripe
3. Paste in your Stripe Publishable Key and Secret Key from dashboard.stripe.com/apikeys
   • Start with test keys (pk_test_… / sk_test_…) while you get familiar with the workflow
   • Switch to live keys (pk_live_… / sk_live_…) only when you're ready for real charges
4. Click Test Connection to confirm Kantivo can talk to Stripe
5. Map a deposit account (where net proceeds land) and a fee expense account (where merchant fees post)
6. Save the gateway

Once the gateway is active, you'll see a Virtual Terminal entry under the Payments menu in the Kantivo desktop app.

Opening the Terminal

Inside Kantivo, navigate to Payments → Virtual Terminal. The terminal screen has three areas:

• Charge form — customer, invoice, amount, card fields, fee preview
• Fee preview panel — calculated from your gateway's percent + flat fee settings
• Recent payments feed — live list of recent charges, refunds, and voids

Charging a Card

To run a card through the virtual terminal:

1. Pick a customer from the dropdown (or leave blank for a one-off charge)
2. Optionally pick an invoice to apply the payment to
3. Enter the amount (auto-filled when an invoice is selected)
4. Enter the card details — number, expiry, CVC. These fields are Stripe Elements, which means the card data goes straight to Stripe and never touches Kantivo
5. Glance at the fee preview to confirm the merchant fee and net deposit
6. Click Charge

Kantivo sends the card token to Stripe, Stripe runs the charge, and the result comes back to Kantivo within a second or two. On success, the payment is recorded, the invoice (if selected) is marked paid, and the fee expense is posted automatically.

Applying to an Invoice

Linking the charge to an invoice keeps your accounts receivable accurate:

• The invoice dropdown shows the selected customer's unpaid and partially-paid invoices
• Selecting an invoice auto-fills the amount with the remaining balance
• You can override the amount to take a partial payment
• On success, the invoice status flips to Paid or Partially Paid and the payment record is linked to the invoice

Charging Without an Invoice

If there's no invoice to apply to, leave the invoice field blank. The payment is recorded against the customer as a credit on account, which you can later apply manually or use to issue a refund. This is common for:

• Booking deposits taken before the invoice is created
• Retainers and prepayments
• Walk-in, one-off transactions with no customer record

Fees & GL Posting

The fee preview shows three numbers:

When the charge succeeds, Kantivo posts the following journal entry automatically:

• Debit your mapped deposit (bank) account — the net amount
• Debit your mapped fee expense account — the fee amount
• Credit accounts receivable (if applied to an invoice) or the customer credit account (otherwise) — the gross amount

Charge History

The Recent Payments feed on the terminal screen records every charge you've put through. Each row shows:

• Timestamp
• Customer name (or "ad-hoc" for unattached charges)
• Gross amount, fee, net amount
• Stripe charge ID (links back to the Stripe dashboard)
• Status: succeeded, declined, refunded, voided

Clicking any row opens the full payment detail, including the linked journal entry and (if applicable) the invoice it was applied to.

Refunds & Voids

Open a successful charge from Recent Payments and use Refund (after Stripe has settled) or Void (before settlement). Kantivo will:

• Issue the refund/void through the Stripe API
• Reverse the original journal entry on success
• Reopen the invoice if the original charge was applied to one
• Record the reversal as its own line in the Recent Payments feed

Troubleshooting

"No gateway configured"

If the terminal screen shows this message, the gateway either isn't saved, isn't active, or the API keys aren't valid:

1. Open Settings → Payment Gateway Settings
2. Confirm at least one Stripe gateway exists and is marked Active
3. Click Test Connection. A green check means the keys are valid; a red message means double-check them against your Stripe dashboard

Charge Declined

When a card is declined, Stripe returns a reason and Kantivo surfaces it on the terminal screen. The most common reasons:

• insufficient_funds — card doesn't have enough available balance
• incorrect_cvc — the security code didn't match
• expired_card — expiry date has passed
• card_declined — issuing bank rejected the charge (customer should call their bank)
• processing_error — Stripe-side hiccup, usually safe to retry in a minute

No journal entry is created for declined charges — there's nothing to clean up.