Kindly EditDocumentationTry the editor

Payments

Take one-time payments, subscriptions and donations with nine ways to pay, coupons, receipts and refunds.

Kindly Forms can take one-time payments, subscriptions and donations with nine ways to pay, apply coupons, keep every payment with its entry, send receipts and refund. Every payment feature is available on every site.

The browser shows totals as people choose, but the site never trusts them. When a form is sent, the server works the order out again from the form and the answers, and asks the payment service itself before anything is marked paid.

Turn payments on#

  1. Open Kindly Edit > Forms > Settings > Payments and turn on Take payments with forms.
  2. Set the Currency (three letters, like USD), where the Symbol goes, the Decimal mark and the Thousands separator.
  3. Fill in Your business on receipts and, optionally, a Receipt page and a Page where people manage payments. See Receipts and the customer page.
  4. Under Payment services, turn on Take payments with each service you want, choose its Mode (Test or Live) and enter its keys. Each service keeps separate keys for test and live. A service turned on without its keys says Keys missing.
  5. Copy the service's Webhook address (the Copy button) into its dashboard, with the events listed under it. Each service has a link to its setup guide.
  6. Save changes.

While payments are off, payment fields stay in the builder with the note "Payments are off for this site (Forms settings, Payments). Visitors don't see this field." Visitors don't see them, and nothing is charged or required.

Keys are never shown again after saving: a saved key shows "Saved. Type to replace it.", and Remove the saved value clears it. Secret keys never reach the browser. Every call to a payment service is logged with its keys hidden.

Ways to pay#

Way to pay What visitors see Subscriptions Keys it needs
Stripe Card on the page, or Stripe's own page. Optionally Apple Pay, Google Pay and more Yes Publishable key, Secret key (or a restricted key), Webhook signing secret
PayPal PayPal buttons on the page, or PayPal's page Yes Client id, Secret, Webhook id
Square Card (Square) on the page, or Square's page No Application id, Location id, Access token, Webhook signature key
Mollie Card, iDEAL, Bancontact and more (Mollie) on Mollie's page Yes API key
Razorpay Card, UPI, netbanking or wallet (Razorpay) in a window over the form, or on Razorpay's page No Key id, Key secret, Webhook secret
Paystack Card, bank or mobile money (Paystack) on Paystack's page Yes Public key, Secret key (also signs webhooks)
Paddle Card or PayPal (Paddle) in Paddle's checkout window Yes Client-side token, API key, Notification secret key
Authorize.Net Card (Authorize.Net) on the page Yes API login id, Public client key, Transaction key, Signature key
Offline payment Pay later (check, bank transfer or in person) No None. How to pay is shown with the choice and in {payment.instructions}

All of them can refund. Card numbers typed on the page go straight to the payment service in the visitor's browser and never reach your site. A service's script loads only when a visitor chooses that way to pay; if it can't load, the visitor is told and can choose another.

Razorpay also has Where people pay (In a window over the form or On Razorpay's page) and Checkout color. Paddle has Prices and tax (Paddle adds tax on top, the default, or Prices include tax) and a Tax category.

Webhooks#

Each service tells your site about later changes (a payment that clears, a refund made in its dashboard, a subscription renewal) through a webhook. Add this address in the service's dashboard, ending in the service's key, for example stripe, paypal or square:

https://your-site.example/wp-json/kindly-forms/v1/payments/webhook/stripe

Every webhook is checked with the service's signature (PayPal's through PayPal itself), and the payment is then asked about again with your site's own keys, before anything changes. PayPal's older instant payment notifications (IPN) are not accepted: set up a webhook and its Webhook id. Without the webhook secret, payments still work on the page, but changes made later in the service's dashboard don't reach the site.

Payment fields#

Payment fields are in the builder's Payments group. Add a Payment method field to let people choose how to pay; without one, the first way to pay switched on is used. If the Payment method field is hidden by its conditions, no payment is taken.

Field What it does Main settings
Product or service One price, or choices with prices Show as (One price, Choose one, Choose several, Drop-down), Price, Words before the price, Choices and prices (the number of each choice is its price), Show prices with the choices, Layout, stock
Amount to pay An amount the visitor types, for donations or pay what you like. It can be calculated Smallest amount, Largest amount, Before the input
Quantity How many of a product or subscription Quantity of (the priced field it multiplies), Fewest, Most
Subscription A recurring plan, or plans to choose from Show as (One plan, Choose one, Drop-down), Plans and prices (price per period), Charged every (Day, Week, Month, Year), Number of periods between charges, Number of payments (0 or empty: until canceled), Free trial days, Signup fee, Visitors choose the amount with Smallest amount
Coupon A box for a discount code with an apply button Button words
Discount An amount off, shown as it applies; its conditions decide when Discount by (Percent or Amount), Discount, Items (none: every item)
Tax Tax on the items, shown as it applies Rate (%), Taxed items (none: every item)
Payment method How to pay, from the ways switched on See below
Order summary The order as a table, kept current as people choose Words when nothing is chosen
Total The total due now

Discount, Tax and Price when are in Kindly Edit 0.12.0 and later. A product's Price when (under Conditions) changes its price: add a price, choose the choice it is for when the product has choices, and set the conditions; the first price whose conditions hold is used, otherwise the product's own price. The page shows the price as it changes, and the server works it out again from the answers.

A quantity field left hidden by a condition counts as one; an empty one counts as none. A Slider or Number field can also be the quantity of a product. Choices of a Product or service can limit stock like any choice.

The Payment method field#

  • Ways to pay: which ways this form offers. None ticked offers every way switched on in Settings.
  • Chosen at the start: The first, or a particular way.
  • Words for each way, to rename it on this form.

Under its advanced settings:

  • Currency for this form, and These are donations.
  • Customer email from (empty: the first email field), Customer name from and Billing address from, sent to the payment service.
  • Words on the card statement (up to 22 characters).
  • The gateway emails its own receipt (on).
  • Details sent with the payment: lines of key: {inputs.field} stored with the payment at the service.
  • Stripe: pay on Stripe's page, Stripe: offer Apple Pay, Google Pay and more, Stripe: ask for the postal code, Stripe: ask for the billing address, Stripe: ask for a shipping address.
  • PayPal: buttons on the page (on) and PayPal: ask for a shipping address.
  • Square: pay on Square's page.

The form templates Order form and Donation start with payment fields; see Templates.

How the total is worked out#

All amounts are kept in the currency's smallest unit (cents, or yen for JPY).

  1. Each product or typed amount, times its quantity.
  2. At most one subscription, times its quantity. With a free trial the signup fee is dropped. A subscription with one payment and no trial is charged like a product.
  3. Discount fields that are showing, in form order, off the items they name: a percentage of each item, or a fixed amount spread over them, never below zero.
  4. Coupons, in the order they were applied. A percentage comes off the one-time part and off the recurring amount. A fixed amount comes off the one-time part, down to zero at most.
  5. Tax fields that are showing: their rate on the items they name after discounts, less those items' share of what coupons took off. Subscriptions aren't taxed.
  6. Due now: the one-time part after coupons, plus tax, plus the first recurring charge (none during a trial).

Products use the price their Price when rules give. The entry keeps each discount and tax amount, and receipts and {payment.summary} list them.

A free order (a total of zero, with no subscription) is marked paid without a payment service.

What happens when someone pays#

  1. The form is checked, the order is worked out and the entry is kept with its payment waiting.
  2. The visitor pays: a card is confirmed on the page, a window opens, or they go to the service's page and come back. Offline payments stop here and wait.
  3. The site asks the service about the payment and marks it paid, failed or still processing.
  4. When it is paid, emails and connections set to run When payment succeeds go out, and used coupons are counted. See After sending.

Authorize.Net subscriptions (Kindly Edit 0.12.0 and later) are billed by Authorize.Net's Automated Recurring Billing: the first payment (or, with a free trial, only the card) is taken on the page, the card is kept as an Authorize.Net customer profile, and the subscription starts one period later (or when the trial ends). Authorize.Net bills every 7 to 365 days, every 1 to 12 months, or once a year; other plans are refused before anything is charged. Tick its subscription events in Authorize.Net's webhooks so renewals, failures and cancellations show here.

Since 0.12.0, Authorize.Net handles a few situations on its own:

  • Authorize.Net sometimes isn't ready to bill a card it stored moments earlier (its error E00040). The subscription stays active (or in its free trial) and is set up a few minutes later. Staff are told only if it still can't be set up after about half an hour, when it becomes Payment failing with the reason in the entry's log.
  • When a subscription's first payment is held for review in Authorize.Net, no card is kept at first. Once you approve the payment there, the card is kept from that payment and the subscription is set up.
  • Each payment lists its products, a subscription's plan and signup fee, and the tax on Authorize.Net's record of it, so the transaction details there show what was bought.
  • Refunding a payment that hadn't settled yet cancels it at Authorize.Net (a void). The payment stays Refunded here; Authorize.Net's own report of that void no longer turns it into Canceled.

A card the payment service refuses in the browser before charging (for example a mistyped number or expiry date) shows the reason under the card. Since 0.12.0 the reason stays there after Send and goes once the card is changed. A card typed on the page with Square or Authorize.Net that is declined says "The card was declined. Try another card." The card box stays, and another card pays the same entry without sending the form again (up to 5 cards for one entry, and 10 cards an hour from one network address). If what was chosen sold out meanwhile, the visitor is told and nothing is charged. When the service doesn't answer at all, the payment stays Processing and no second card is offered, because the first may have gone through: the site looks it up with the service after a day and marks it Expired after two days if a full search still can't find it (otherwise it stays Processing and is looked up again each day), with a note to check the service's dashboard. A payment the service reports later still counts.

A form that asks senders to confirm their email or waits for admin approval still takes the payment when the form is sent, then shows its waiting message. Its When payment succeeds emails and connections wait until the entry is confirmed or approved, and never go for a declined entry.

Payments left unfinished at a checkout for 24 hours are marked expired (developers can change the time with the kindly_forms_payment_abandon_hours filter). A failed or expired payment gives back any stock the entry held; if it is paid later after all, the stock is taken again.

Payment statuses: Waiting, Processing, Unpaid (something was owed but the Payment method field was hidden by its conditions, so nothing was charged), Authorized, not captured, Paid, Failed, Expired, Canceled, Refunded and Partly refunded. Subscriptions can also be Active, In a free trial, Payment failing or Finished. Refunded, partly refunded and canceled are final: a late "paid" message from a service never overwrites them.

Deleting entries with payments#

Deleting an entry never deletes its payments or cancels a subscription with the payment service. The payment and subscription stay in Payments, where the entry column says Entry deleted, and refunds and renewals keep working. Deleting an entry (alone or in bulk) whose subscription is still running warns first: cancel the subscription before deleting if it should stop. The daily task that removes entries after a form's or the site's days keeps any entry whose payment is waiting, processing, paid or partly refunded, or whose subscription hasn't finished.

Payments in the hub#

Kindly Edit > Forms > Payments needs the Payments permission (administrators, or managers given it). It has three tabs.

  • Payments: every payment with who paid, the amount, the way to pay, the form, the entry and when. Search by name, email or charge, and filter by form and status. Test-mode payments are marked (test).
  • Subscriptions: each plan, how often it charges, how many times it has been paid, when it started and its status.
  • Coupons: see below.

On an entry, the Payment panel shows the payment, its card or account, and its refunds. Refund asks for the Amount (up to what is left) and an optional Reason, then refunds through the service. Change status sets a payment's status by hand, for example to mark an offline payment paid. A subscription has Cancel subscription, which first shows the plan, amount, payments so far, start date and payment service; Keep it leaves it running. Refunds made in a service's own dashboard also appear when its webhook is set up. Paddle refunds are approved by Paddle later and are recorded when Paddle says so.

The hub's Reports show payment counts and totals by status for each form.

Coupons#

Open Payments > Coupons and New coupon.

Setting What it does
Name Only you see this
Code What people type. Letters, numbers, dashes
Takes off and How much A percentage or An amount
Smallest total it works on The order must reach this before the coupon applies
Uses in all and Uses per person 0 for no limit
Starts and Ends Dates the coupon works between
Forms it works on None chosen means every payment form
Works with other coupons Whether it can be combined
On Turn it off without deleting it

Coupons are checked when they are applied and again when the form is sent. A coupon is counted as used once the payment goes through. Until then, an order that has started holds its use, so a coupon with one use left can't go to two orders; a failed, expired or canceled order gives it back, and so does deleting the entry of a payment still waiting. Delete asks first; people can no longer use a deleted coupon.

Receipts and the customer page#

  • Use {payment.receipt} in a confirmation or email for the full receipt, or the smaller codes such as {payment.summary}, {payment.total}, {payment.payment_status}, {payment.method}, {payment.transaction_id}, {payment.coupon}, {payment.instructions} and {payment.receipt_url}. The smartcode reference lists them all.
  • Receipt page: a page with the [kindly_forms_receipt] shortcode where receipt links open. Without one, the receipt shows on its own simple page. Receipt links are signed, so only someone with the link can open it.
  • Page where people manage payments: a page with the [kindly_forms_payments] shortcode. Signed-in people see their own payments with receipt links and their subscriptions, and can cancel a subscription when the service allows it. Signed-out people are asked to sign in.

Testing#

Use each service's test mode and test cards. Test payments are marked (test) in the hub. Switch to live only after a complete test: send the form, pay, check the entry's Payment panel, the receipt, the emails set to When payment succeeds, a refund, and the webhook (in Logs, payment calls appear with their keys hidden).

About this page

Documents Kindly Edit 0.9.16. Source: includes/forms/payments/*.php, assets/forms/payments.js, assets/forms/admin.js. Theme choices and account permissions can change which controls appear.

Type a word or phrase to search the full documentation.