Skip to main content

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, except one-click add-ons, which your upsell code calls.

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 cards, and Apple Pay and Google Pay once they are turned on for your account.

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.

From 0.5.31 the plugin also refuses an update notice older than one it has already accepted, and checks a second signed notice that Von Payments renews every few hours, so an old notice cannot be served again to hide a newer release. A store that cannot confirm its update information is current takes no update and keeps taking payments as normal; after a week it shows the usual warning that it has not been able to check for plugin updates.

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.

Once saved, a secret key or signing secret is not shown again: its field reads Saved. Leave blank to keep it. Leave the field empty to keep it; to remove it, tick Remove the saved value when I save under it.

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

Receive payment updates​

Von Payments tells the store when a payment settles, fails, or is refunded. Test payments run on your sandbox and live payments on your live business, and each sends these updates only to its own endpoint, which has its own signing secret. The plugin keeps a signing secret for each mode and checks every update with the one for the mode the store is in. Set up the sandbox's endpoint now; the live one is part of going live.

  1. In the plugin settings, under Webhooks, copy the endpoint URL shown.
  2. In your Von Payments dashboard, in your sandbox, 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). Chargeback notifications need no subscription: Von Payments sends them to every endpoint.
  3. Copy the signing secret shown when the endpoint is created and paste it into Test webhook signing secret. Save.

Recommended, not required: also subscribe the endpoint to payment_method.attached. A card a shopper chose to save is then saved as soon as Von Payments links it to their payment; without it, the store checks again over the following day.

Upgrading from 0.5.29: the signing secret you already saved keeps working. On a store in Test mode it moves to Test webhook signing secret; on a store in Live mode it stays in Live webhook signing secret.

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.

From plugin version 0.5.23, a test notification sent from your Von Payments dashboard never changes an order, whether Test mode is on or off; the log records that it arrived.

Test a payment​

With Test mode ticked, place an order at a test-mode total. 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.

Go live​

Live payment updates go to an endpoint on your live business, not to the sandbox one, and that endpoint has its own signing secret. Switch the secret when you switch the mode:

  1. In your Von Payments dashboard, switch to your live business and open Webhooks. Add an endpoint at the URL the plugin shows under Webhooks, with the same seven events. Copy from sandbox does this in one step; check the address before you copy.
  2. Copy the new endpoint's signing secret. It is shown once.
  3. In the plugin settings, paste that secret into Live webhook signing secret, untick Test mode, and Save changes. The store now uses your live keys.
  4. Saving checks your live keys and your live webhook setup. Webhook delivery reads verified once a test event has reached your store; otherwise its message says what to fix, such as no endpoint on your live business or a signing secret that does not match. Check webhook delivery runs the check again.

Your test signing secret stays saved, so switching back to Test mode needs nothing new. If the mode you switch to has no signing secret saved, Webhook delivery says so.

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 on a card payment, the shopper is sent to their bank's page, for a saved card too, confirms there, and comes back to your store. On Apple Pay or Google Pay the bank's page opens in a pop-up on your checkout instead, and the shopper only leaves the checkout when the pop-up cannot open. Either way the plugin asks Von Payments what happened before it marks anything paid. There is nothing to set up.

  • If the bank has not answered yet when the shopper comes back, the order page says Payment not confirmed yet and keeps checking by itself.
  • Once Von Payments confirms the check did not pass, or that the shopper cancelled it, the order is marked Failed and the shopper is taken back to the checkout with the same items, told: "Your bank's security check didn't go through, so you have not been charged. Please try again or use another card."
  • If the shopper leaves during the check, the order waits. WooCommerce does not cancel the unpaid order for a day, so a payment the bank approves late still completes it. The order is marked Failed only once Von Payments confirms nothing can be charged.

A shopper who closes the bank's page. From 0.5.31, where Von Payments has switched this on for your store, a shopper who closes the bank's page or walks away from it can pay again straight away, with the same card or another one: the store first has Von Payments close the unfinished check, so the shopper is never charged twice. If they change their basket and place a new order, the earlier order is marked Failed with a note. Where it is not switched on, a new order from the same shopper is not charged while their earlier check is still open at their bank.

The shopper is not emailed about a failed payment, and WooCommerce's on-hold email is not sent while the bank has not answered. WooCommerce's failed-order email to you is unchanged.

Both checkouts are supported​

The block checkout and the classic (shortcode) checkout both show the same card field and use the same settings. A shopper can also pay with a new card on an order's Pay for order page, for example from a payment link you send. Wallet buttons are not offered there. If the bank declines the payment, the shopper returns to the same page to try again.

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 once the payment completes, after a bank verification step too; leave it unticked and the card is not kept. The order notes say whether the card was saved. 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.

Apple Pay and Google Pay​

The Apple Pay and Google Pay buttons appear on both checkouts, but only for a wallet your store's domain is verified for in your Von Payments account; with none verified, no buttons show. Apple Pay also needs one small file served from your store's address, and the plugin serves it: the Apple Pay row on the settings page shows whether Apple can reach it, and Check Apple Pay setup checks again.

The shopper's approval reserves the money on their card, and it is taken once the order is placed. A payment that cannot become an order is released, not refunded. If the store misses the moment to take a reserved payment, the plugin's regular check finds it and puts the order On hold with a note: choose Take the held wallet payment from Order actions to take it, or cancel the order to give the money back. Changing the status by hand does not take the payment.

One-click add-ons​

One-click add-ons, off by default, lets an offer made after the order be paid with the card the shopper just used, without typing it again. It needs upsell code on your store: on the thank-you page it gets a token with vonpay_upsell_token(), charges the offer with vonpay_charge_upsell(), and reads where an offer stands with vonpay_offer_result(). An accepted offer is a payment of its own on the same order, and its products are added once that payment is taken. A card kept only for add-ons is not saved to the shopper's account, and the card form tells the shopper an accepted add-on is charged to that card. For the developer calls, the result, bank checks and refunds, see One-click add-ons on WooCommerce.

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 seeWhyWhat to do
The card field is not on the checkoutThe 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 HTTPSOpen 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 declinedThe bank or Von Payments refused the charge. The shopper is told the reason only when they can fix it: an expired card or insufficient funds ("Please use another card"), or, for a typed card, a wrong security code or card details the bank could not match ("Please check … and try again"). Every other decline reads "Your payment was declined by your bank. Please try again, or use another card." Apple Pay and Google Pay keep their own message. The shopper can type another card on the same order, which stays Pending payment. They can pay with another card, or a saved card, straight away in almost every caseLook 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. A declined saved card, or a decline after the bank's check, marks the order Failed with one note giving the reason. The order keeps the declined payment's Von Payments reference in its own field, so you can look it up; the order is never treated as paid because of it. If the note says the order may or may not have been charged, check your Von Payments dashboard for a payment against it before you retry or refund.
An order sits Pending payment or On holdPending 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, or the amount paid does not match the order total; the order note says whichCheck payment updates are set up, on your live business too (Go live). The plugin also re-checks such orders itself every 15 minutes, starting 10 minutes after the order. An On hold order it still cannot confirm after 24 hours is marked Failed with a note: look the payment up in your Von Payments dashboard and settle or refund it there. A Pending payment order is left as it is unless the payment goes through.
A shopper sees "Your order total changed. Please review it and place your order again."The order total changed after the card form loaded, for example a shipping choice. Nothing was chargedNothing; the shopper places the order again. If the same order is refused twice, a plugin that changes the total as the order is created (a fee, a currency switch) is the cause, and a warning appears in your WordPress admin until card totals match again.
A shopper disputes a payment with their bank (a chargeback)Disputes are answered in your payment processor's own dashboard, not in Von Payments or WooCommerce. 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 amountRespond to the dispute in your payment processor's dashboard before its deadline. Once it is decided, update the order by hand if you need to; the plugin does not change it.
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 chargedThe 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 productThe plugin does not take subscription payments, so WooCommerce does not list it for oneUse another method for subscriptions.

Warnings and errors always go to WooCommerce → Status → Logs; the Debug log option in the settings adds the routine gateway events. It never logs card data or secret keys.