Von Payments for WooCommerce

Take card payments inside your own WooCommerce checkout. The shopper types their card into a secure field served by the payment processor inside your checkout page, and the card is charged when they place the order. The card number never reaches your store or Von Payments, which is what keeps your store in the lightest PCI category (SAQ-A).

This page is for the person setting the store up. Nothing here needs code.

Before you install

• WordPress 6.4 or newer, WooCommerce 8.3 or newer, PHP 7.4 or newer.
• Your checkout page served over HTTPS. The card field will not load on a page that is not.
• Your Von Payments API keys: a publishable key and a secret key for test, and the same pair for live.

The plugin takes card payments. The Apple Pay row on its settings page is not in use in this version.

Install

The plugin is not in the WordPress plugin directory, so searching for it in your admin will not find it. Download it from www.vonpay.com/woocommerce instead, then upload that file:

1. Download the plugin from www.vonpay.com/woocommerce. That page always gives you the current release, so there is no version to pick.
2. In WordPress, go to Plugins → Add New → Upload Plugin.
3. Choose the .zip you just downloaded, then Install Now.
4. Activate it.

That same address is the plugin's home page, so it is also where the View details link on your Plugins screen goes.

Keeping the plugin up to date

Leave WordPress's auto-update toggle on for this plugin. Because it does not come from the WordPress directory, it brings its own update channel: it asks Von Payments what the current version is, and WordPress then offers or installs it exactly as it would any other plugin. This is how a fix reaches your store, so turning auto-updates off means watching for them yourself.

You do not have to trust that channel blindly, and neither does the plugin. Before anything is installed it checks two things: that the update notice really came from Von Payments, and that the downloaded file is byte-for-byte the one that notice described. If either check does not pass, the update is refused and your store keeps running the version it already has.

Connect your keys

Go to WooCommerce → Settings → Payments and open Von Payments.

1. Tick Enable Von Payments.
2. Paste your test publishable key and test secret key.
3. Paste your live publishable key and live secret key.
4. Save changes.

Each key is checked as you save. A key carries its own type and mode in its name, so a mix-up is refused rather than stored: a secret key pasted into a publishable field is not saved (the publishable key is sent to every shopper's browser, so a secret key there would be visible to anyone), a publishable key in a secret field is not saved, and a test key in a live field is not saved. The plugin then confirms the keys with Von Payments. If Von Payments rejects them, the payment method is taken off your checkout until you fix them, so a shopper is never asked for a card the store cannot charge.

Test mode is on when you install. The store uses your test keys, and no real card is charged, until you untick Test mode and save.

Receive payment updates

Von Payments tells the store when a payment settles, fails, or is refunded. Set this up once:

1. In the plugin settings, under Webhooks, copy the endpoint URL shown.
2. In your Von Payments dashboard, create a webhook endpoint at that URL, subscribed to these seven events: charge.succeeded, charge.failed, charge.refunded, refund.failed, payment_intent.succeeded, payment_intent.failed, payment_intent.cancelled (the plugin uses refund.failed to prove delivery).
3. Add the three dispute events to the same endpoint (dispute.created, dispute.won, dispute.lost). The dashboard's picker does not list them yet, so add them with PATCH /v1/webhook_subscriptions/{id}. Until they are on the subscription the settings page reports the endpoint as unverified, even though nothing else is affected: dispute events reach your store either way, because they are delivered to every active subscription.
4. Copy the signing secret shown when the endpoint is created and paste it into Webhook signing secret. Save.

The Webhook delivery row on the settings page reports verified only once Von Payments has sent a test event and your store received it. Until then the checkout still works, but two things depend on this step: an order whose payment takes a moment to settle waits on hold until the update arrives, and a refund issued from the Von Payments dashboard reaches the order only through it.

Test a payment

With Test mode ticked, place an order on your store with a test card. A successful payment marks the order paid, and the shopper's card brand and last four digits appear on the order.

The order is created before the card is charged, so a payment always has an order to land on. A card that clears in one step is confirmed in the same visit.

When you are ready to take real payments, untick Test mode and save.

When a shopper's bank asks for extra verification

Some banks ask the shopper to confirm a payment before approving it (3-D Secure). When that happens the shopper is sent to their bank's page, confirms there, and comes back to your store's order confirmation; the plugin then asks Von Payments what happened before it marks anything paid. There is nothing to set up and nothing for you to do when it happens. If the shopper leaves the bank's page without confirming, no money moves: the order stays Pending payment, the plugin keeps checking it for a day, and then marks it Failed with a note.

Both checkouts are supported

The block checkout and the classic (shortcode) checkout both show the same card field and use the same settings.

Saved cards

A signed-in shopper sees a tick box, Save this card for future purchases in this store, which starts unticked. Tick it and the card is kept when the payment completes without a bank verification step; leave it unticked and the card is not kept. Guests are never offered it. A saved card is listed under the shopper's My Account → Payment methods and can be chosen at their next checkout.

Cards are saved only as part of a purchase. The Add payment method screen in My Account does not offer Von Payments, because there is no way to save a card there without charging it.

Refunds

Refund from the order screen as you would with any gateway: Refund, enter the amount (the full order or part of it), then Refund via Von Payments. The refund is sent to Von Payments and the money goes back to the shopper's card.

A refund is refused until the order has a confirmed payment. A refund you issue from the Von Payments dashboard instead shows up on the order through the payment updates above.

Troubleshooting

What you see	Why	What to do
The card field is not on the checkout	The payment method is disabled, a key is missing, Von Payments rejected the keys, your account cannot settle the store's currency, or the checkout page is not HTTPS	Open the settings: check Enable, that all four keys are saved, and any message shown under the keys. Confirm the checkout page loads over HTTPS.
A shopper's card is declined	The bank or Von Payments refused the charge. The shopper sees what they can do about it and can try another card on the same order, which stays Pending payment	Look the attempt up in your Von Payments dashboard for the reason. A typo (wrong security code, wrong postcode) is the shopper's to fix; a final decline needs another card. When a saved card is declined, the reason is also written as a note on the order.
An order sits Pending payment or On hold	Pending payment: the order was created and the charge has not been confirmed yet (the shopper may still be at their bank). On hold: the payment is settling and the update has not reached the store yet	Check payment updates are set up. The plugin also re-checks such orders itself every 15 minutes, starting 10 minutes after the order, for 24 hours. If it gives up, the order is marked Failed and a note explains why: look the payment up in your Von Payments dashboard and settle or refund it there.
A shopper disputes a payment with their bank (a chargeback)	Disputes are handled in your Von Payments dashboard. The order keeps its paid status: the plugin never refunds or restocks it for a dispute, and a lost dispute is not always for the full order amount	Respond to the dispute, and reconcile the order, in the Von Payments dashboard rather than from the order screen.
A shopper sees "This payment needs an extra verification step that this store cannot complete yet"	The bank asked for a verification step and no usable address for its page came back, so the store could not send the shopper there. Rare. The shopper has not been charged	The shopper tries again or pays another way. If it repeats, contact Von Payments with the order number.
Von Payments is not offered for a subscription product	The plugin does not take subscription payments, so WooCommerce does not list it for one	Use another method for subscriptions.

The Debug log option in the settings writes gateway events to WooCommerce → Status → Logs. It never logs card data or secret keys.