Member Payments

Instructions

• Before you start taking payments
• Setting up payment buttons
• Setting up the data link with PayPal
• Setting up your payment forms
• Configuring the payment log
• Configuring your dues or subscription payment schedule
• Setting up the “Last Payment Values” fields
• Manual log entries
• Email and Message Value tags
• Email Communications
• Exporting/Importing Payment Logs

Important Note

This plugin is complex and it involves a lot of configuration to get it doing what you need. It is very important to completely test the plugin’s functionality before you start taking payments. I suggest you use the PayPal Sandbox for your testing, it lets you make as many test purchases as you want so you can be certain it’s working as expected. I’ve included a special set of settings just for testing to help you avoid unpleasant surprises after you go live.

I do offer support for configuring the plugin, but I cannot guarantee a timely response. Don’t put yourself in the position of having to make an emergency support request. If you’ve tested the functionality before going live with it, you can be sure that things will go smoothly once you’ve started accepting payments.

How It Works

The plugin works by placing a PayPal payment button in a Participants Database form. When the user clicks on the PayPal payment button, the contents of the form is processed into Participants Database and the user is sent to PayPal to make the payment. When they complete their transaction, a record is made of the payment via PayPal Payment Data Transfer and/or Instant Payment Notification.

To keep a log of member payments, this plugin requires the PayPal account be configured to send Instant Payment Notifications and/or process a Payment Data Transfer.

Configuring the Member Payments Add-On is a bit complex, but these instructions will help you get it all working. These are the main parts, we’ll explain each one in turn.

1. Set up the PayPal payment button
2. Set up to receive PayPal payment data
3. Set up your payment forms
4. Set up payment logging

Configuring PayPal

Everything in this section requires that you be logged in to your PayPal account.

The first thing you will need to set up is the payment button. You may be familiar with this in PayPal, it is a little snippet of HTML that when displayed on a web page, is a clickable way to make a payment at PayPal.  If you are already using an instant payment button, you can use the same code in the Member Payments add-on.

Set Up Your PayPal Button

Log in to PayPal, and go to your Profile page. Click on My Selling Tools, and find PayPal Buttons near the top of the list of items on the right. Click on “update” to the right of “Manage my payment buttons.” That will take you to a list of default and custom buttons. If you already have a button set up, use that one. Otherwise, follow PayPal’s instructions for setting up a payment button.

There will be several button options offered, choose “Buy Now” This is the only button type that is currently supported by Member Payments.

Once you have your button code (you must copy it from the PayPal site) insert that code into the “PayPal Button HTML” setting in the Member Payments setup under the General tab. Now, all your Member Payments shortcodes will include that button in the form.

(Setting this up for PayPal Sandbox is exactly the same, with the important difference being you’ll be logged in to www.sandbox.paypal.com with your sandbox account.)

It’s also possible to use a different button code for each shortcode by including the button code in the “button_html” attribute of the signup, record or member payment shortcodes. More on that in the Product FAQ.

If you use “hosted” buttons (which are a bit more secure), you won’t be able to control the return page from the plugin side. The return page when using a hosted button is set up in the button configuration. If you have more than one payment portal, and want to give each one a different return page, you will need to define a separate hosted button for each one.

“Subscribe” buttons are not supported, the plugin can’t provide a way for the user to manage their subscription.

Logging Payments

There are two ways that PayPal sends transaction information to your website so that the user’s payments can be logged: Instant Payment Notifications (IPN) or Payment Data Transfer (PDT). You can use either or both, but it is recommended you use both so that you have a backup method in case one fails. Using both methods will not result in duplicates in the log, each transaction will only be logged once.

IPN and PDT both supply the same kind of information, but in two different ways:

• IPN is asynchronous, meaning that is it sent in the background independently of the user’s actions, usually within a few seconds. That means that IPN doesn’t rely on the user going back to the site after authorizing the purchase. Their transaction will be logged anyway. In most cases, this method serves as a backup in case something happens and the user doesn’t make it back to the “thanks” page.
• PDT requires the user to return to the “Return URL” so the payment data can be given to the website. The advantage here is that the information is available immediately. If you want your users to return to your site to be thanked and have their payment acknowledged, you must use this method.

More info on the difference between the methods from PayPal: IPN vs. PDT

Setting Up Instant Payment Notifications

1. Under your name (top right corner of the page) find “Account Settings” then “Website Payments”
2. find “Instant payment notifications” and click on “update”
3. click on “Edit Settings”
4. enter your IPN Notification URL: it is the home URL of your WordPress site
5. select “Receive IPN messages”
6. save, and you’re done.

Setting up Payment Data Transfer

1. Under your name (top right corner of the page) find “Account Settings” then “Website Payments”
2. find “Website preferences” click on “update”
3. Auto Return: select “On”
4. for the “Return URL,” put the URL for your “thanks” page (the one with the [[pdb_member_payment_thanks]] shortcode)
5. find Payment Data Transfer, select “On”
6. just below this, you’ll see the “Identity Token” select and copy this token
7. go to the bottom of the page and click on “save”
8. back on your WordPress site, in the Member Payments settings, general tab, paste in the token

With these configurations, logging of PayPal transactions can begin.

Payment Forms

There are two different ways to implement the Participants Database payment button. You can use one or both of them. You’ll need to decide which is right for your situation.

Once you have chosen the method or methods you want to use, you must either change your existing Participants Database forms shortcodes or place new shortcodes. You will need to place new shortcodes if this is a new installation or you want to use the “Member Payment” form.

The shortcodes provided by this plugin use all the same attributes of the regular Participants Database form shortcodes. The [pdb_signup_member_payment] shortcode shows a signup form with a PayPal payment button so that a new record is created when the form is submitted. The [pdb_member_payment] shortcode gives members an easy way to make a payment on their account.

If you are using custom templates, you must alter those templates to include the payment button. By inspecting the templates provided by this add-on and comparing to your custom template it’s easy to add the code needed to show the payment button.

Setting Up the “Thanks” Page

Each of the payment forms can be configured to take the user to a “thanks” page after the payment is made.

The way this works by default is a little different for each one. In all cases, after the user makes a PayPal payment, the user is returned to the “Return URL” as configured at PayPal. They will also be returned to this page if they cancel the transaction, and the plugin will show the “Cancel Return Message.”

For the Signup Payment form, when an offline payment is made, the thanks page will be the “Signup Thanks Page” as configured in the main Participants Database settings.

All of these behaviors can be modified in the shortcode. For the Signup Payment, the page the user is returned to after making an offline payment can be determined by the “action” attribute in the shortcode, for instance: [pdb_signup_member_payment action="offline-payment-thanks"] will send the user to a page named offline-payment-thanks after selecting an offline payment and submitting the form.

(Please note: for any thanks page that is designed to work with the Signup Payment form, you must use the [pdb_signup_member_payment_thanks] shortcode.)

For PayPal payments, the “return_url” and “cancel_return” attributes can be used to set what happens when making a PayPal payment…for example:

[pdb_signup_member_payment return_url="member-payment-thanks"]

This will return the user to the page named “member-payment-thanks” after making their PayPal payment, overriding the “Return URL” setting. When setting up a thanks page for the Member Payment form you must use the [pdb_member_payment_thanks] shortcode on that page.

All of the payment forms will work as their own thanks page: if the user goes back to the form page after making a payment or submitting the form, it will show the appropriate thanks message.

Configuring the Payment Log

The user’s payment is logged to a special field in Participants Database that is automatically set up by the Member Payments plugin. The new field will appear in an admin field group (if you have one, in the first field group if you don’t). After activating the plugin, go to the “Manage Database Fields” page in the admin, click on the tab for an admin field group (the default is “Administrative Info”), and look for a field named “Payment Log” That is your log field and you can change it’s configuration there, including changing it’s title or moving it to another group if you like.

Configuring the Log Fields

When a user makes a payment, PayPal sends a packet of data back to the site. There are lots of pieces of information in that packet, but only a few of them will need to be logged. The plugin pre-configures the log fields, and for most installs, that will be all you need. If you need, you can change which data fields you are logging in the log field configuration: Advanced Log Field Configuration

Configuring a Dues or Payment Schedule

For many situations, you will want members to make payments on a regular basis, such as for a dues payment. The plugin can tell you what each member’s payment status is, but in order to do that, you have to configure your payment schedule.

There are two kinds of payment schedule: fixed date and period. A fixed date schedule is for dues that are always due on a specific date or dates of the year. For instance a biennial schedule could be: January 1st and July 1st. The user’s payment becomes due on those dates. The period schedule is more like a subscription payment: the payment is for a set period of time, beginning the date the payment was made. The next payment will be due when that period is over.

See the “Settings” tab for details on configuring the payment schedule.

Member Payment Status

Each member has a payment status based on the payment schedule and when the last payment was made. Those statuses are:

• paid (the member is current with payments)
• payable (it is time to make a payment)
• due (the payment due date is past)
• past due (the member is late on their payment)

The “payable” and “past due” dates are configurable relative to the due date. For instance, you can set it up so that the payment becomes past due 7 days after the due date.

When the member’s payment status changes, an event for that change is triggered. When the Email Expansion Kit is installed, it is possible to set up an email that will be automatically sent on the status change. For instance, you can set up an email to go out when the member’s payment is due, and a different one that goes out when the member’s payment is past due.

Setting Up the Last Value Fields

In most cases, it’s the values in the last log entry that carry the most relevant values. You can create what are called “last value fields” that hold the last value of any of the log fields. One useful application of these fields is for showing information to the user: while the log itself is usually only visible to administrators, it may be useful for the regular user to know when the last payment was, for instance.

Last Value Fields are set up by creating a new field with the same name as the log field you want it to mirror. For instance, there is a log field named “payment_date” which holds the date of the payment. By creating a date field named “payment_date” you will set up a field that will always contain the date of the last payment in the log.

To set up a field that shows the last amount paid, you can create a field named “mc_gross” (this is the name of the payment amount field PayPal uses) and it will be filled in with the last amount paid, including manual payments. Once you have created the field, you can change the title of the field to anything you want.

Last Value Fields can use other field types, as well. For instance, with the “payment status” field there is a limited set of possible values (as defined in the IPN/PDT variables), which means it would work well as a dropdown field.

Note that the last value field must appear in the payment log for the value to be transferred to the last value field. This means that the field must be listed in the “options” of the Payment Log field.

If you are planning to offer options for your payments (such as different price options) you can track the user’s selection using a last value field. The instructions for configuring that are in this article: Setting up payment options in Member Payments.

Manual Log Entries

If the “Payment Log Edit Lock” setting is unchecked, it becomes possible to add a new entry to the edit log. When the new entry is added, it is placed in the log according to the payment date.

The manual log entry uses text fields to enter values unless a last value field has been defined for that log field. In that case, the last value field definition is used to define the input control used for the new log entry.

For instance, if you set up a dropdown field (as suggested above) for the “payment_status” log field, when adding a new log entry, the payment status field will be set using a dropdown control.

Value Tags

User feedback and emails use a templating system like the one in Participants Database that allows you to use “value tags” in your messaging. These value tags will include all the fields defined in Participants Database, all the data fields in the PayPal transaction, and several payment status fields if you are using the Payment Status module of the add-on. A value tag is simple the name of the field whose value you want to show in brackets like this [txn_id].

A list of useful tags is as follows.

• [txn_id] – the transaction ID from the PayPal purchase
• [txn_amount] – the transaction amount
• [payment_status] – the current payment status of the account… like “paid,” “past due,” etc.
• [last_payment_date] – the date of the last payment
• [next_due_date] – the date the next payment will be due
• [option_selection1] – if your payment button has options, the selected option will be in a field like this (the name may vary, look at your payment button code for the name you need to use)

Advanced Setup

Here are some instructions for getting deeper into the configuration of this plugin. Instructions in this section are optional, you don’t need to do anything here, they are additional capabilities you can access if you need.

Email Communications

This add-on works with the built-in email functionality of Participants Database: when the signup payment form is used, the person signing up gets the usual receipt email, and the administrator gets their notification (if configured to do so). The same is true of the “Profile Payment” form: as in Participants Database, there is no user email for updating their profile, but there is an administrator notification for that.

The built-in emails can all use the “value tags” from this add-on as described above.

Advanced Email Configuration

With the addition of the Email Expansion Kit, many more possibilities become available for email communications. Custom emails can be triggered on a number of events generated by this add-on:

• Signup Payment Return
• Member Payment Return
• Profile Payment Return
• Cancel Payment Return
• PayPal IPN Recieved

Status Change Emails

When using the Payment Status module, events are generated when the member’s payment status changes. For instance, when a member’s uses payment becomes due. These status change events are triggered automatically in the background according to the date, and also when the payment log is updated with a new payment. There are four status change events that you can use:

• Status Change to Paid
• Status Change to Payable
• Status Change to Payment Due
• Status Change to Past Due

Advanced Payment Log Field Configuration

The payment log is pre-configured to include the most important fields of information. There is more information available, however, and this is how you can change which fields are logged.

Looking at the “Payment Log” field, in the “values” area, you’ll see the log columns defined as a comma-separated list of name::title definitions. For instance, the first one is payment_date::Date that means that the name of the data field is “payment_date” and the title of the field (or column) is “Date” You can change the title to anything you want at any time. Be careful about changing the name of the data field because that corresponds to a data filed in the packet the site receives from PayPal.

A full list of the data fields can be found here: IPN and PDT variables Much of that is pretty technical, and it may take a little research to understand what info you need to log. The default columns that are pre-set by the plugin will give you most of the important stuff, so you can just leave the default setting for the log fields in most cases.

Exporting and Importing Payment Logs

As of version 2.7, Member Payments has the ability to export and import payment logs with the record. If the “pdbmps_payment_log” field is configured to be included in the CSV, when records are exported (on the Participants Database admin List Participants page), the value for the Payment Log field will be a human-readable block of text with all the record’s payment logs.

This string has a very specific format so that it will work with most data sets and fit within the CSV file format. In the log value, each log entry is separated from the others with a “pipe” | character. Within each entry, each field of data is separated from the others with a double semicolon ;;. And then each data field is devided between the field’s name and its value with an “equals arrow” character =>.

If you follow this specific format when importing the record, you can add new payment entries with a CSV import. This include adding a payment to new records. To update or change an existing log entry, you must include the entry_id field. Be careful with this, you can end up with garbled data if it is done wrong. If you don’t want to change anything in the payment log it is best to remove the payment_log field from the CSV before you import it.

Jan 1
April 1
July 1
November 1