Skip to main content

Build an offer funnel

This page is for developers who build direct-response offer funnels on a connected store. The usual shape: an ad leads to a one-page checkout for one product. The shopper's card is saved in the browser and charged from your server. A one-click offer follows on the same card and goes on the same store order.

Most of the detail lives on other pages. This page puts the steps in order and links to each one.

StepWhat you doWhere
1Save the card in the browser, with the shopper's agreementSave the card
2Charge the card from your serverCharge it
3Charge a one-click offer onto the same store orderOne-click offers
4Give each campaign its own statement nameStatement names
5Test against your live storeTest

Decide what you will charge later before you build the checkout. The shopper's agreement is recorded when the card is saved. No call adds it afterwards.

Get the agreement in one of two ways: our save-card box, or your own wording next to the order button. Both are described in Collect the buyer's consent.

  • A card saved without the agreement can still be charged while the shopper is on your page, so a one-click offer works. A charge you declare merchant-initiated (mit.initiator: "merchant"), for a shopper who is not there, is refused with payment_method_consent_missing, and the shopper must enter the card again. Declare every such charge merchant-initiated. The full table is in Reuse scope.
  • A subscription starts only on a fresh card. The shopper must have saved it in their own browser in the last 30 minutes, and it must never have been charged without the shopper present. You cannot later start a subscription on an older card, such as one saved for a one-time order. To sell a subscription with the main offer, start it in the same checkout: A main order and a sign-up on the same card.
  • Never pre-tick the box. The card networks do not accept a pre-ticked box as the shopper's agreement. Our save-card box always starts unticked, and no option ticks it.

Charge the card from your server​

Send the saved card's token (vp_pmt_…) from your page to your server. Charge it with POST /v1/payment_intents and payment_method: { id: "vp_pmt_…" }. Leave out the mit block, because the shopper is present. Send the shopper's identity on every charge (why).

The funnel-one-click-node sample is this whole funnel in Node. The shopper agrees with your own wording at the order button, the server creates the order and charges, and a one-click add-on follows on the same card, with one key per order and offer so nothing is charged twice. Its README covers a Next Commerce store and what to check before you go live. The saved-cards-mit sample adds a later renewal with the mit block.

One-click offers on the same order​

Charge the accepted offer to the same token, again with no mit block. The one-click upsell scenario shows the two charges.

On Next Commerce, put the offer on the shopper's order with mirror.parent_order_ref:

  • parent_order_ref takes the order number or the main charge's payment intent id (vpi_…). With the id, send the offer at once. You do not have to wait for the store order.
  • Send an upsell_key for each offer the shopper accepts, and send the same key on every retry. A repeat is refused with 409 upsell_duplicate, and the shopper is not charged again. If the key cannot be checked just then, the charge is refused with 503 service_unavailable and nothing is charged: retry with the same key.

The fields and rules are in Post-purchase upsells.

If your account creates the store order before the charge, the store's total is checked against your amount first. A mismatch is refused with 400 order_first_amount_mismatch, and nothing is charged. Read what created means on those accounts. If you add the offer's line to the order yourself, charge it with settle_only.

On other stores, use the store's own add-on support: Medusa or WooCommerce.

A statement name for each campaign​

On a structured-descriptor connection, Von Payments can set a name pattern on your account, for example ACME {product}. Each charge fills {product} with the value your descriptor rule reads, such as metadata.product_name. Send each campaign's short product name there, and each campaign gets its own statement name.

  • The whole name is at most 20 characters. Only the {product} part is cut.
  • A product name is not used if, after cleaning, it is shorter than 5 characters, or if it is longer than 128 characters or holds an email address, phone number, web address, a payment company's name, or one of < > \ ' " *. Your business name fills the slot instead. Cleaning turns anything that is not a letter, digit or space into a space.

Ask your Von Payments contact to set the pattern. The limits for each connection and the pattern rules are in Statement descriptors.

Test against your live store​

Test from a sandbox account with its test keys. Do not connect your live store to the sandbox. Instead, a team admin or a Subscriptions admin of your live business turns on Test orders on the store's card in the dashboard. On Next Commerce, your sandbox's test charges then create orders in your live store. While it is off, a test payment still goes through and creates no order (details).

A test order:

  • is created unpaid, tagged vonpay-test-payment, and carries vora_test_payment: "true" in its metadata. It is never marked paid.
  • carries the name and address TEST ORDER / DO NOT SHIP in place of the shopper's.
  • on an account that creates the order before the charge, goes through the same steps as a live order, including the check of the store's total against your amount. Von Payments cancels it about a day after the test payment.

While you test:

  • Give the store customer a reserved test address, such as one at example.com (details). Use a new address for each repeat of the same basket. Next Commerce refuses a second order for the same buyer and basket, even after the first order is cancelled.
  • Send each offer in the same mode as its main charge. A test offer is added only to an order that a test charge created.
  • settle_only needs a live key. A test-mode settle_only is refused before the card is charged.
  • Leave the vonpay-test-payment tag out of your fulfillment rules, and never mark a test order paid by hand.
  • A test subscription's later charges (renewals, retries, Bill now) create no order in your live store (details).
  • Only a limited number of test orders can be open at one time. Past the limit, the charge is refused with 429 mirror_test_order_limit_reached and nothing is charged. Cancel your open test orders in the store, or, on an account that creates the order first, wait about a day for them to clear. Then retry. Do not retry in a loop.