Skip to main content

One-click add-ons on WooCommerce

For developers writing a post-purchase upsell on a WooCommerce store that takes Von Payments, by hand or through a funnel plugin such as CartFlows or FunnelKit. From plugin version 0.5.30, one PHP call charges an accepted offer to the card the shopper just paid with, with no card form. Store setup is on the WooCommerce page.

One order, several payments. An accepted offer is its own payment on the order the shopper already paid. Its products are added once that payment is proven taken, so the order total is always its own payment plus the offers actually paid. No second order is made: if your funnel plugin can put an offer in a separate order, set it to add offers to the main order.

Turn it on​

In WooCommerce → Settings → Payments → Von Payments, tick One-click add-ons (off by default). The upsell functions work only while both Von Payments and this setting are on. With it on:

  • Every checkout tells Von Payments the card is kept for offers at no set time. An accepted offer is sent as the shopper's own later payment on that card, linked to the order's payment. The shopper's bank can still ask for its security check on an offer.
  • A signed-in shopper's card is kept by their account. A guest's card is kept by their email, whether they type it before or after their card: the email is added to the payment already open. If it cannot be added before the shopper presses Place order, the card is not kept, and an upsell on that order returns failure.
  • A card the shopper did not tick to save is not listed in their saved cards. It is recorded on the order instead.
  • The card form tells the shopper: "Your card is kept securely for a short time, only for offers on this order while you are here. It is not added to your saved cards." The second sentence is dropped once a signed-in shopper ticks the box to save their card.

Get a token on the thank-you page​

While the shopper who just paid is in front of you (the thank-you page, or your funnel's next step), take a token for the order and keep it with the offer:

$token = vonpay_upsell_token( $order->get_id() ); // '' when this order cannot take upsells

The token is signed with your site's WordPress secret keys, and it:

  • names one order, and is issued only in the first 30 minutes after that order was paid;
  • works only for whoever it was issued to: the signed-in customer the order belongs to (nobody else is issued one), or a guest's own store session;
  • for a guest order requested with no store session (a REST or Store API call, a funnel page built on the server), is bound to the order's key and the shopper's email instead, so it works from any browser that holds it, like the thank-you link. Issue it from the shopper's own page view when you can;
  • pays for one offer, the first reference it is accepted with. Asking again for that offer is fine; take a new token for the next one (a downsell, a second upsell);
  • expires one hour after it was issued.

It returns '' when the order was not paid with Von Payments, is not paid, was paid more than 30 minutes ago, or belongs to an account other than the signed-in user's, and while Von Payments or one-click add-ons are off.

Without a valid token the upsell is refused, so code that only knows an order number cannot charge that order's card. Treat the token like a password for its hour: send it in a form POST body, never in a link or query string (addresses end up in server logs and Referer headers), and make sure no page cache or CDN stores the thank-you page.

Charge an offer​

When the shopper accepts:

$result = vonpay_charge_upsell(
$paid_order_id, // the order the shopper just paid with Von Payments
array(
array( 'product_id' => 123, 'quantity' => 1 ),
array( 'product_id' => 456, 'variation_id' => 789, 'quantity' => 2, 'total' => 19.98 ),
),
'offer-1', // your reference for this offer
$token, // from vonpay_upsell_token() on the thank-you page
home_url( '/offer/next/' ) // optional: where the bank sends the shopper back
);

Line items. Up to 20 lines, each with product_id (or variation_id), quantity (default 1), and an optional total: the line's price before tax, in the order's currency. Without total the product's own price is used. Tax is added for the order's tax address the way WooCommerce adds it at checkout, and the amount charged (returned as amount) is exactly what the order total grows by. total is charged as given, so set it from your own server-side offer settings, never from anything the browser sends.

Reference. Letters, digits and _ - . :, up to 64 characters, different for each distinct offer. An order takes at most 20 offers.

Products. Anything published, purchasable and in stock for the quantity, at a price of its own: a simple product, one option of a product with options (pass variation_id), and product types other extensions add. Refused before the card is charged: an unpublished product, an out-of-stock product, any subscription, a product with options and none chosen, a grouped product, and an external product.

A bundle or composite product is added as one line. Its contents are not added as lines of their own and their stock is not reduced. If your fulfillment needs the contents listed, offer them as separate lines.

What the call does​

  • Charges the card the paid order's own payment saved, as the shopper's own later payment on a card they agreed to keep, linked to the order's payment, under a duplicate-charge key of its own.
  • Once that payment is proven taken, adds the offer's lines to the order, grows its total by the amount charged, reduces stock, and writes an order note naming the offer, its payment and the new total.
  • Never changes the order's status and sends the shopper no email. Each outcome is a private order note; your funnel decides what confirmation the shopper gets.
  • Charges at most once per order and reference. Called again with the same reference (a double click, a retry, a reload) while the token is valid, it returns the outcome already recorded, including a decline, without asking the bank again. After the token's hour, read the outcome with vonpay_offer_result() instead: a call with an expired token is refused as expired, even for an offer that was paid.
  • Keeps an offer as first made. Called again with the same reference but different items, it answers for the original offer. Use a new reference for anything different.

The result​

Every answer about an offer carries order_id, offer (your reference), amount (minor units, for example cents) and currency. A refusal before any charge carries only result and message.

resultMeaningAlso returned
successPaid, and added to the order.
requires_actionThe bank wants to check the shopper. Send them to redirect (or open it in your own pop-up); the plugin never redirects for you. Nothing is taken or added until they finish.redirect
pendingAccepted, not confirmed yet. The offer is added when the payment is.message
failureNot added.message (safe to show); on a decline also decline_code and action; unconfirmed: true when the charge's answer was lost, or money moved that could not be added

A requires_action or pending offer finishes on its own, by whichever comes first: the shopper's return from their bank, the payment notification from Von Payments, or the plugin's check every 15 minutes. An offer still waiting on the bank after a day is treated as not charged, and is added if that check is ever completed. The order is never put on hold.

Two requests landing on the same order at the same moment: one returns failure with "Please try again in a moment", nothing charged, and the next attempt answers from what the first recorded.

Allow about 30 seconds. The call waits up to 5 seconds for the order to be free, looks up the card on an order's first offer, and gives the charge up to 12 seconds. If your own request times out first, the charge may still have gone through: call again with the same reference, which never charges twice. Never treat a timeout as a decline, and never retry under a new reference.

The same holds after a failure with unconfirmed: true. The plugin's 15 minute check sends a charge whose answer was lost again, exactly as stored and under the same duplicate-charge key, for up to a week; after that the offer stays unconfirmed for a person to look at. A refusal of the request sent again (your secret key was changed, too many requests) keeps it unconfirmed, never "not charged".

A failure with no decline_code was stopped before reaching the card, the bank check was not completed, or the outcome could not be confirmed. It is not a decline: show message, and do not tell the shopper their card failed.

action on a decline. Never retry automatically.

actionMeaning
softMay work another day (for example insufficient funds). Do not retry in this visit; move the funnel on.
hardDo not try this card again.
genericNo detail. Treat it as hard.

fix_and_retry is never returned for an upsell: with no card form to fix, those codes (an expired card, a wrong security code) come back as hard.

Coming back from a bank check​

The optional fifth argument is a page on this store (for example your funnel's next step) where the bank sends the shopper afterwards. Without it, or for an address on another site, they return to the order's thank-you page.

The plugin adds four signed query arguments to that address, honoured for one hour. When the shopper arrives, the offer is settled from its payment record early in template_redirect (priority 5), before your page renders, so the page can move the funnel on:

$back = vonpay_offer_return(); // null unless this request is a verified return
if ( $back && 'succeeded' === $back['result'] ) {
// show the next offer
} elseif ( $back && 'not_charged' === $back['result'] ) {
// show a downsell, or go to the thank-you page
}

$back carries order_id, offer, result (the words vonpay_offer_result() uses) and message. On the thank-you page, the plugin also adds "You have not been charged for this offer." to WooCommerce's order-received message for an offer that was not charged, or "Your payment for the offer is still being confirmed." while it is pending.

Asking where an offer stands​

$state = vonpay_offer_result( $order_id, 'offer-1', $order->get_order_key() );
// $state['result']: 'succeeded' | 'not_charged' | 'pending' | 'unconfirmed' | 'none'

The first argument is the order or its id. The order's key (the secret in its thank-you page address) is required: without it, or with a wrong one, the answer is none, as it is for a reference the order does not have. unconfirmed means nobody can say yet, or a person must look: accept again with the same reference, or ask the shopper to contact the store. Every answer also carries amount, currency and a message safe to show.

Refused before any charge​

Each returns failure with a message and no decline_code:

  • No valid token: missing, for another order, older than an hour, altered, issued to someone else, or already used for a different offer.
  • Von Payments or one-click add-ons are switched off.
  • The reference is malformed, there are no lines or more than 20, a product does not exist or cannot be sold, or the order already has 20 offers.
  • The lines add up to nothing (every total is 0). Add a free gift without this call.
  • The order was not paid with Von Payments, has since been cancelled, failed or refunded, or any of its payments is disputed.
  • The order kept no card (for example a guest whose email could not be added to the payment before they pressed Place order).
  • The shopper did not agree to keep their card at that checkout, so it was removed. This holds even if add-ons are turned on later.

Hook​

do_action( 'vonpay_upsell_charged', $order_id, $offer_ref, $amount_minor ) fires once when an offer's payment is taken and its lines are added, whichever route settled it.

Refunds, money given back, and disputes​

  • An offer payment that went through but could not be added is given back automatically, in full: one for an amount that is not the offer's, or one that landed after the order was cancelled or refunded. An order note says when. If giving it back fails or cannot be confirmed after several tries, the note says so and the payment is counted in the store's warning about payments no order accounts for.
  • Money only held on the card for an offer, still not taken after a day, is released.
  • A WooCommerce refund is split across the order's payments. Refunding an offer's lines (tick them in the refund form) refunds that offer's payment. The rest comes from the order's own payment first, then the offers in the order they were accepted. No payment gives back more than it took; a refund they cannot cover between them is refused, with the most that can still be refunded.
  • If one part of a split refund goes through and another fails, WooCommerce removes the refund. The part that went back is recorded in an order note and booked into WooCommerce's refunds by the refund notification or the 15 minute check; a part with no answer is looked up by its refund key before anything is sent again. Until then, a new refund on the order is refused. A part that cannot be confirmed for a day is handed to you in an order note and stops holding refunds back.
  • A refund while another request is updating the order is refused; nothing is refunded.
  • Refunds and disputes on an offer's payment are recorded on the order, naming the offer. A dispute on any payment stops further offers. Respond to a dispute in your payment processor's own dashboard.

Records on the order​

For support: the order keeps the card offers are charged to (vp_pmt_…) under the meta key _vonpay_addon_card, and each line an offer added carries the item meta _vonpay_offer with the offer's reference. The plugin's other order records are internal and can change between versions; charging an offer needs none of them.

Example: a minimal upsell​

// Thank-you page: show the offer with the token in the form, and what happened
// to it if the shopper is back from their bank.
add_action( 'woocommerce_thankyou', function ( $order_id ) {
$back = vonpay_offer_return();
if ( $back ) {
echo esc_html( $back['message'] );
}
$token = vonpay_upsell_token( (int) $order_id );
if ( '' === $token ) {
return; // not a Von Payments order, or upsells are off
}
printf(
'<form method="post"><input type="hidden" name="order_id" value="%d"><input type="hidden" name="vonpay_token" value="%s"><input type="hidden" name="_my_upsell_nonce" value="%s"><button name="my_accept_upsell" value="1">Add for $12</button></form>',
(int) $order_id,
esc_attr( $token ),
esc_attr( wp_create_nonce( 'my_accept_upsell_' . (int) $order_id ) )
);
} );

// Accept: charge with the token the page carried.
add_action( 'template_redirect', function () {
if ( empty( $_POST['my_accept_upsell'] ) ) {
return;
}
$order_id = absint( $_POST['order_id'] ?? 0 );
// WordPress's standard check that the form was submitted from your page.
if ( ! wp_verify_nonce( sanitize_text_field( wp_unslash( $_POST['_my_upsell_nonce'] ?? '' ) ), 'my_accept_upsell_' . $order_id ) ) {
return;
}
$result = vonpay_charge_upsell(
$order_id,
array( array( 'product_id' => 123, 'quantity' => 1 ) ),
'thank-you-offer-1',
sanitize_text_field( wp_unslash( $_POST['vonpay_token'] ?? '' ) )
);
if ( 'requires_action' === $result['result'] ) {
wp_redirect( $result['redirect'] ); // to the bank, which sends the shopper back
exit;
}
// 'success', 'pending' or 'failure': show $result['message'] or a thank-you.
} );

The token proves the request comes from the shopper who just paid; an order id alone is not enough. The nonce is WordPress's usual check that the form came from your own page. Keep both: neither replaces the other.