Form Feed Settings Reference

This page is the detailed reference to form feed settings. New to feeds? The Form feeds walkthrough builds a form from scratch, step by step, with screenshots.

Every WPdirectdebit form has a feed. The feed is where you tell WPdirectdebit what should happen when someone submits the form: what kind of payment to set up, in which currency, how much, how often, and where to send the customer afterwards. For more about form feeds, check out the Gravity Forms documentation.

If you built your form with one our our form builder wizards, Build Payment or Build Recurring Payment, (available via buttons on the WPdirectdebit dashboard), the feed has already been created for you. It is still worth knowing what is in there, because the feed is where you make adjustments later, and it's the way to add Direct Debit to a Gravity Forms form you already have.

This page walks through the whole feed, section by section. It is best read with the feed open in another tab.

Finding the feed

In WordPress, go to Forms and open your form.
Choose Settings, then WPdirectdebit.
Click Add New to create a feed, or click the name of an existing feed to edit it.

A form can have more than one feed, but we recommend one feed per form wherever you can.

If a feed is switched off, or its conditional logic is not met when someone submits, WPdirectdebit simply does nothing for that submission and the form behaves like any other Gravity Forms form.

Field mapping, in a nutshell

Many settings in the feed have a drop-down menu that lists the fields on your form. Choosing a field from that menu is called mapping. When the customer fills in that field and submits the form, WPdirectdebit reads the value and uses it for that setting. This is how information such as an email address, a start date or the number of payments gets from your form to GoCardless.

What each section does

Section	What it controls	When you see it
Feed Settings	Payment type, currency, mandate description, mandate reuse	Always
Recurring Payment	Amount, schedule, number of payments, start date	Payment type is Recurring Payment
Upfront Fee	A payment taken at sign-up, alongside the mandate	Recurring Payment
One-off Payment	The payment description and how it is collected	Payment type is One-off payment
Customer Prefill	Which form fields fill in the GoCardless page	Always
After payment	Where the customer goes afterwards	Always
Metadata	Custom labels sent to GoCardless	Only if switched on in plugin Settings
Conditional Logic	Whether the feed runs at all	Always

Feed Settings

Feed name

An internal label that only you see. Use something your future self will recognise, for example Monthly membership, Deposit payment or Direct Debit for monthly plans.

Payment type

There are three choices, and this is the most important decision in the feed:

Recurring Payment sets up a mandate and a repeating schedule of payments. Use it for memberships, regular donations, instalment plans and anything else that repeats.
One-off payment takes a single payment. Use it for a deposit, a one-time fee or a single donation.
Mandate only sets up the customer's Direct Debit authority and takes nothing yet. You collect payments later from your GoCardless dashboard or API. Use it when you want the authority in place but will decide the amounts and dates yourself, for example for bookings, variable billing or "pay on the day" arrangements.

If you are not sure which to use, ask yourself whether the customer should be charged now, on a schedule, or later when you say so.

Currency

This sets both the currency and the GoCardless scheme for the feed. Each feed has its own currency, so it does not matter what Gravity Forms' global currency is set to.

Currency	Scheme
GBP	BACS
EUR	SEPA Core
USD	ACH
SEK	Autogiro
DKK	Betalingsservice
AUD	BECS
NZD	BECS NZ
CAD	PAD

The scheme matters more than it first looks. It decides which options are available to you (for example Instant Bank Pay is only offered for some currencies), and it decides which of a customer's existing mandates can be reused, because a mandate on one scheme cannot be used for a payment on another.

Mandate description

Required. This is the text the customer sees in the GoCardless window when they authorise the mandate. It describes the standing authority, not one particular payment, so keep it short and specific so that the customer will recognise it later on their bank statement and in GoCardless's emails. It can be up to 255 characters, but shorter is better.

Good examples:

Monthly membership to ABC Club
Regular donations to Example Charity
Music tuition fees

Descriptions that are too vague to be useful:

Payment
Subscription

Reuse existing mandate

A tick box that lets returning customers skip the GoCardless window. It has its own section below, because it is worth understanding properly: Reusing a customer's mandate.

Recurring Payment

These settings only appear when the payment type is Recurring Payment. For an ordinary monthly payment most of them can stay as they are.

Recurring payment description

The name the subscription is given in GoCardless, and the label that appears in the emails GoCardless sends the customer for each payment. If you leave it blank, the mandate description is used, which is fine whenever that wording already makes sense for a regular payment.

Amount

Form total (the default) takes the amount from your form: a product field, a total field, or a calculation. Choose this when the customer's choices decide the price, for example a membership level, a donation amount they type in, or a calculated price.
Fixed amount lets you type one amount that applies to everyone. Enter it in the main currency unit, such as 29.99 for £29.99.

A fixed amount does not need any product or Total field on the form, so it is often the simplest route for a plain membership form. Form total is different: it needs a product or Total field to read the amount from. If the form has none, the amount comes out as zero and the sign-up cannot go ahead.

Day of month

The preferred day of the month for collection, from 1 to 28. WPdirectdebit sets the start date to the next available occurrence of that day that leaves enough notice for the scheme (for BACS, that is the working days GoCardless needs). Leave it on No preference to let GoCardless choose, which is a good default if you do not mind exactly which day the money moves.

Pick a fixed day when your business needs one, for example "all members pay on the 1st". You can also map a form field if you want customers to choose their own day. This setting is not available with a free trial, because the length of the trial decides the start date instead.

Every, and Interval unit

Together these set how often a payment is taken. Every is a number, and Interval unit is weeks, months or years. Some examples:

1 month is a monthly payment
3 months is quarterly
2 weeks is fortnightly
1 year is annual

The allowed ranges are 1 to 104 for weeks and 1 to 24 for months. For years the number is always 1, so you have a payment once a year.

If customers should pick between, say, monthly and annual, set the unit to Map field and choose the form field that holds their answer. The values the field sends should be words such as weekly, monthly or yearly (capital letters do not matter, and "annually" is understood too). Keep mapped choices simple and obvious on the form, and make it clear what the customer is committing to.

Month of year

Only used for yearly payments, and for most forms it is best left on No preference. It pins the annual payment to a particular month, which is useful when everyone should pay in the same month, for example a club whose subscriptions all fall due in January.

Here is how it works with a start date of As soon as possible: the first payment is taken on the next occurrence of that month (on the 1st, or on the Day of month you chose), not at the earliest date GoCardless could collect. So a customer who signs up on 3 November and whose feed is set to December pays on 1 December. One who signs up on 3 November with the feed set to October pays on 1 October the following year, nearly a year later, with nothing collected in between. That is correct behaviour, but it can surprise customers, so make sure your form says when the first payment will be taken.

Only use Month of year with As soon as possible. With the other start date options (After one billing cycle, or a date from a field), the start date is already decided and, for BACS (GBP) payments, the month is ignored. This setting is not available with a free trial.

Number of payments

Until further notice keeps collecting until the subscription is cancelled. This is right for most memberships and regular giving.
Fixed number stops after that many payments. Use it for a 12-month payment plan or a six-instalment course fee.
Map field lets the customer say how many payments they want. If you use this you can also set a minimum and maximum, and WPdirectdebit checks the number they enter before the form submits, so they see a clear message instead of a failed payment.

Start date

As soon as possible is the right choice most of the time.
After one billing cycle deliberately delays the first payment by one interval, for example so a monthly member's first payment is a month away.
Free trial (number of days) delays the first payment by the number of days you enter, after the mandate is set up.
Map field takes a date from your form. WPdirectdebit checks that it is a real date no more than a year ahead, and shows the customer a message if it is not.

If you map the start date to a field, a few habits will save you trouble:

Use a Gravity Forms Date field, not a plain text field, so Gravity Forms handles the date format for you.
Set a minimum date on the field so customers cannot pick today or a date in the past. GoCardless needs time to set up a mandate, so WPdirectdebit quietly moves any date that is too early forward to the earliest date GoCardless allows, and adds a note to the entry. That keeps the subscription from failing, but a customer who chose a date will not be told it changed.
Set a maximum date of no more than a year ahead.
Leaving the field blank is fine. The subscription then starts as soon as GoCardless allows.

Upfront Fee

Shown only for Recurring Payment feeds. An upfront fee is a one-off payment taken at the same moment as the mandate is set up, for instance a registration or joining fee alongside a monthly membership. If you do not need one, leave it set to None, because a simpler flow is usually better for the customer.

Upfront payment can be None, Fixed (you enter the amount) or Map field. Map field is for fees that are set by a sign-up link made with the plugin's link generator: the fee travels in a signed token held in a hidden field on the form, and Map field points at that field. Forms made with the Build wizard already include that hidden field. It is not meant for an ordinary Number or Total field. If the mapped field does not hold a valid token, no upfront fee is taken, and nothing warns you, so use Fixed for a fee that is the same for everyone.
Upfront payment description is the wording for the fee in GoCardless's emails. It uses the mandate description if you leave it blank.
Collection method is either Direct Debit, which collects the fee through the new mandate once it is authorised and works in every currency, or Instant payment, which takes the fee immediately at sign-up. Instant payment means Instant Bank Pay for GBP and EUR, and PayTo for AUD. For other currencies Direct Debit is used whatever you choose.

Real examples are a £20 joining fee and then £12 a month, or a £50 deposit today followed by monthly instalments.

One-off Payment

Shown only for One-off payment feeds.

Payment description is the wording on the payment in GoCardless's emails. It uses the mandate description if blank, and it is worth setting if the payment should read more specifically, for example Event deposit or Course fee.
Payment method (for GBP feeds) lets you choose how the money is collected:
- Direct Debit (BACS) takes the payment via the mandate, usually within three to five days.
- Instant Bank Pay (Faster Payments) takes the payment immediately and does not create a reusable mandate.
- Instant Bank Pay + mandate takes an instant payment now and also sets up a mandate for future use, which is handy if you will want to collect renewals or extras later.

For other currencies, Direct Debit is used.

Customer Prefill

This section tells WPdirectdebit which of your form fields should fill in the customer's details on the GoCardless page, so they are not asked to type them twice. You can map given name, family name, email, company name and the address fields (two address lines, city, region, postal code and country). There is also a phone number setting, but see the note below: it does not currently do anything.

When you open a new feed, WPdirectdebit looks at your form and fills in sensible defaults, using the first Name, Email, Phone and Address fields it finds. For a Name field it maps the first and last name boxes, and for an Address field it maps both address lines, city, region, postal code and country. Check that these are what you want, and change any you do not.

The section is technically optional, but it is rarely worth skipping. A well-prefilled page means fewer corrections and fewer people giving up. At the very least, map name, email and address.

A few details worth knowing:

Phone numbers are not passed on. GoCardless's payment page does not accept a pre-filled phone number, so mapping a phone field has no effect on what the customer sees. If you want phone numbers, collect them on your form as usual and they will be in the Gravity Forms entry.
If you do not map a country field, the Default country from the plugin Settings is used on the GoCardless page, so make sure that is the country most of your customers live in.
The email field also drives mandate reuse, so it matters even if you do not care about prefilling.
Customers can change what is prefilled. They can edit any detail in the GoCardless window, so what GoCardless ends up holding may differ from what is on your form entry. That is expected: prefilling is a convenience, not a guarantee.
Odd values are skipped, not fatal. If a mapped field holds something GoCardless would not accept, or something far too long, WPdirectdebit leaves that detail out. The payment still goes ahead and the customer simply types that detail in themselves.

A tip: if your customers have accounts on your site and are likely to be logged in, Gravity Forms can fill in name and email from their profile automatically, so they do not even have to type those on your form. See the Gravity Forms documentation on dynamic population.

After payment

Success page is where the customer goes after they finish setting up their payment. It is optional, and you only need it if you want a different outcome for Direct Debit than the form's normal confirmation.
- If you leave it blank, WPdirectdebit uses whatever confirmation is set up on the form in Gravity Forms: a text message shown on the page, or the page or address you chose.
- If you set a Success page, it takes priority over the form's confirmation for Direct Debit sign-ups only. This is most useful when the form offers more than one way to pay, for example a Direct Debit feed alongside a card payment feed, and you want each to end on a different page.
Exit page is where the customer goes if they close or cancel the GoCardless window before finishing. Leave it blank to keep them on the same page, or point it at a calmer page that explains what happened and what to do next, perhaps offering another way to pay or your customer service details. Gravity Forms has no confirmation for a cancelled payment, so this is the only place to set that up.
Pass field data via query string adds form values to the end of the Success page and Exit page addresses, so you can use them on those pages, for example to personalise a thank-you page or pass data to analytics. Use Gravity Forms merge tags, for example first_name=&email= (use the merge tags for your own fields). The result looks like https://example.com/thank-you/?first_name=Jane&email=jane@example.com. If you are relying on the form's own confirmation instead of a Success page, use Gravity Forms' merge tag support in that confirmation's redirect address.

Metadata

Metadata lets you attach your own labels (a key and a value) to the mandate, subscription and payments in GoCardless, for example to flag which campaign a donation came from. It is an advanced feature, so the section is hidden unless you switch it on in the plugin's Settings. Keys can be up to 50 characters, values up to 500, and values can use merge tags.

Conditional Logic

The feed has the usual Gravity Forms conditional logic. You can set it to run only when a certain choice has been made on the form, and WPdirectdebit will leave the submission alone otherwise.

This is how you offer a mix of options on one form. For example, a booking form might let customers choose between a monthly plan and a one-off booking. Set the feed's condition to "plan is monthly", and the one-off bookings will submit normally without a Direct Debit step.

Another common use is offering more than one way to pay, such as Direct Debit, credit card or PayPal. Add a payment method field to your form, so the customer can say how they would like to pay, and use conditional logic on each feed to test that field. Then only the feed for the chosen method runs. This avoids any chance of the customer paying more than once.

Good to know:

On multi-page forms the feed runs once, when the customer submits the final page, and the conditions are checked then.
If you need two different payment outcomes, you can use two feeds with different conditions, each with its own payment type. Keep the conditions clear and make sure only one of them can be true for any given submission.

Reusing a customer's mandate

In short: if Reuse existing mandate is ticked, a customer who is logged in to WordPress and already has a usable mandate from an earlier submission of the same form can skip the GoCardless window. Anyone who is not logged in goes through the normal GoCardless flow every time.

What it does

Normally every submission sends the customer through the GoCardless window (the "drop-in") to authorise a new mandate. With reuse switched on, WPdirectdebit first checks whether this customer already has a mandate it can use. If they do, the window is skipped, and the form simply carries on with what the feed is set up to do:

Recurring Payment: the new subscription is created on the existing mandate.
One-off payment (Direct Debit): the payment is created on the existing mandate.
Mandate only: nothing more needs setting up, and the "mandate ready" notification (if you have one switched on) is sent straight away.
Instant Bank Pay options cannot use a Direct Debit mandate, so those still go through the normal flow.

The customer then sees your normal confirmation or success page.

When it applies

All of these have to be true for a mandate to be reused:

The customer is logged in to WordPress.
The email address on the form matches their WordPress account email.
They have submitted this same form before while logged in, and that earlier sign-up was completed with reuse switched on.
Their mandate is on the same scheme as this feed (so a GBP feed will not reuse a SEPA mandate), and it is active or still being set up.

If any of those is not true, the customer goes through the normal GoCardless window, which is always a safe fallback.

An email address typed into a form proves nothing about who is typing it. If reuse worked on a typed email alone, anyone who knew a returning customer's address could set up a payment on that customer's bank mandate without them knowing. Requiring a logged-in account that matches the email means the person at the keyboard has already proved who they are.

Is it right for your form?

Reuse is a good fit when:

members log in to a members' area and use a form there to renew, top up or add something
a school, club or service has customer accounts and the same people submit the form more than once

It is not useful, and you may as well switch it off, when:

the form is public and nobody logs in, such as a one-off campaign or donation form (it will simply never apply)
you want every submission to create a fresh mandate on purpose

Forms made with the Build wizard have it switched off. If your form is for logged-in customers, switch it on in the feed.

Things worth knowing

The first sign-up always goes through GoCardless. WPdirectdebit can only reuse a mandate that it recorded from an earlier submission, so customers who signed up before you switched reuse on, or while logged out, will go through the normal flow once. After that sign-up, as long as they were logged in, they are recognised.
Upfront fees are not collected again. An upfront fee is part of the GoCardless sign-up, so a customer whose mandate is reused is not charged it a second time. That is usually what you want for a joining or registration fee, but bear it in mind if your fee is meant to be charged on every submission.
It only looks at the same form. A mandate set up through a different form is not reused.
It keeps very little data. The customer's email and GoCardless customer ID are only saved on the entry when reuse is switched on, and only for this purpose.
Email field is needed. Map the Email field in Customer Prefill, as reuse uses it.
Tell returning customers what to expect. They may be expecting to authorise the payment or enter their bank details, and when a mandate is reused they will not be asked for either. It is good practice to say on the form that if they already have an active mandate with you, no further action is needed on their part.
Which notification to use. A reused mandate has no GoCardless webhook, so the Mandate active notification is never sent for it. Mandate ready is sent in both cases, so use that one for your customer's confirmation email. More in Notifications.
Telling customers it happened. On a success page you can show different wording to customers whose mandate was reused. Wrap text in [wpdd_mandate_reused]...[/wpdd_mandate_reused] to show it only to them, or in [wpdd_mandate_not_reused]...[/wpdd_mandate_not_reused] to show it only to everyone else. This works when the customer is sent to a page after the form, for example your Success page.

Confirmations

The confirmation is what Gravity Forms shows or does once a form has been submitted: a text message, a page, or a redirect to another address. You can use whichever you prefer. With a Direct Debit feed, the GoCardless window opens first, and when the customer has finished, WPdirectdebit shows your text message or sends them to your page or address. If you have set a Success page in the feed, that takes priority for Direct Debit sign-ups (see After payment).

A short, warm text message is a good place to start. Remember that at this point the customer has set up their payment but nothing has been collected yet, so it is worth saying when to expect the first payment.

Notifications

Notifications are emails sent automatically when something happens. Gravity Forms sends them, and WPdirectdebit adds its own events to the Event drop-down for any form that has an active WPdirectdebit feed.

By default Gravity Forms sends the site administrator an email when the form is submitted. You will probably also want a separate notification for the customer, confirming what they have agreed to and including anything they need at this stage: your refunds policy, your customer service contact details, and how to opt out of any marketing emails they have signed up for.

Choosing the right event

Event	When it is sent
Mandate ready (created or reused)	A Direct Debit mandate is in place: either GoCardless has just created it, or a returning customer's existing mandate has been reused.
Mandate active	GoCardless has confirmed the mandate is active, so payments can be collected. Not sent when a mandate is reused.
Recurring payment created	A recurring payment has been created on the mandate.
Recurring payment create failed	The mandate was set up but creating the recurring payment failed, so it needs your attention.
Payment confirmed	A payment has been confirmed by the banking system.
Payment paid out	A payment has been paid out to your bank account.
Payment failed	A payment attempt has failed.
Mandate cancelled	The mandate has been cancelled.

For a welcome or confirmation email to the customer, use Mandate ready. It is sent on a GoCardless webhook rather than when the customer simply submits the form, so you can be confident the mandate really exists, and it is also sent for returning customers whose mandate is reused. If your form sets up a recurring payment, you may also want Recurring payment created, and you can send both.

Please do not use the standard Gravity Forms "Form is submitted" event for payment confirmation emails. It is sent as soon as the form is submitted, before the customer has finished in the GoCardless window and before GoCardless has confirmed anything.

Payment confirmed and Payment paid out suit receipts and other transactional emails better than the welcome email. Bear in mind that for Direct Debit the first payment typically arrives several days after the mandate is set up.

Payment failed and Recurring payment create failed are worth setting up as notifications to yourself (and, for failed payments, perhaps to the customer too), so that nothing is missed.

Merge tags

Use Gravity Forms merge tags in the message to personalise the email with the customer's name, the amount, or anything else from the form.

A word on compliance

Check the legislation in your own country about the emails you send to customers. Requirements vary, and may cover information the email must contain, when you may send it, and how people can opt out of marketing. Any examples in this documentation are illustrations only and may not meet your legal obligations.

What happens after someone submits

For a bit of reassurance about what is going on behind the scenes, here is the usual order of events:

The customer completes the form. On multi-page forms this is the final page.
WPdirectdebit checks the conditional logic. If it is not met, nothing more happens.
WPdirectdebit creates the request with GoCardless, using your feed settings and the details from the customer prefill, and opens the GoCardless window. (Or skips it, if a mandate is being reused.)
The customer authorises the mandate. For recurring payments the subscription is created once the mandate is in place, and any one-off payment or upfront fee is created too.
The customer lands on your success page or the form's confirmation, and GoCardless's webhooks keep the entry's status up to date as the mandate and payments progress.

You can see each entry's status, and a log of what happened, on the entry itself in Gravity Forms.

Tips for a smooth setup

Use one feed per form unless you have a clear reason not to

WPdirectdebit can run more than one feed on a form, but documentation and support are much simpler when a form has one clear payment outcome. If you need several different payment journeys, it is usually cleaner to use separate forms. Conditional logic is a good fit when the difference is small, such as "monthly plan or no Direct Debit at all".

Keep customer-driven schedules constrained

If you let customers choose the interval, the number of payments or the start date from fields, validate those fields and keep the form obvious. "How often?" with Monthly and Annually is clear. A box that asks for an "interval unit" is not.

Test in sandbox first

Switch the plugin to sandbox mode, submit the form as a customer would, and check the entry in Gravity Forms and the customer, mandate and subscription in your GoCardless sandbox dashboard before you go live.

If nothing seems to happen

Check the feed is switched on.
Check the conditional logic, and that the choice you made on the form meets it.
Check you are connected to GoCardless in the right mode (sandbox or live).
Open the entry in Gravity Forms. WPdirectdebit records what it did, and why it stopped if something went wrong, for example a missing mandate description or an amount of zero on a payment type that needs one.