Table of Contents
- Getting your PayPal API Credentials
- PayPal Settings
- Accepting Payments on your Form
- Accepting Static Payments
- Accepting Calculated Payments
- Tracking your PayPal Transactions
[Jump to top]
Getting your PayPal API Credentials
PayPal Express requires no setup cost or monthly fees. You are only charged normal transaction fees based on a small percentage of the transaction amount. In order to use PayPal Express you will need your own API credentials but don’t worry, they’re easy to get.
Getting Live Credentials for PayPal Express
Simply visit the PayPal Express Checkout page and click Sign Up Now.
Once you’re account is set up you are ready to get your PayPal API credentials.
- Log into your PayPal account
- Under My Account click on Profile
- In the left sidebar select My selling tools
- Under the Selling online section you will see an item called API access. Click on the update link to the far right.
- Select Option 3 (NVP/SOAP API integration)
- Here you can create, remove, or access current Live API Credentials.
Once you have these you will add them to the PayPal Settings page.
Getting Testing Credentials for PayPal Express
Testing is a crucial part of accepting payments online. You want to make sure that the flow your user experience is exactly what you intend. In order to accomplish this you’ll want to be able to go through the entire payment process. You don’t want to have to send real money to accomplish this and that’s where testing API credentials comes into play.
- First create a developer account at https://developer.paypal.com. Don’t worry. It’s not as scary as it sounds.
- Once created and logged in click on the Dashboard link in the main menu.
- Click on Accounts under the Sandbox heading accounts in the left sidebar.
- Here you will create two accounts, Personal and Business.
- The business account will provide your Test API credentials. You will save these under the PayPal settings page under the Test API credentials.
- The personal account is what you will use to act as a customer to complete a transaction.
That’s it. You are now ready to test your Ninja Forms payment form.
[Jump to top]
The Ninja Forms PayPal Express Extension is meant to be very simple to set-up but extremely powerful in application. When you install and activate the PayPal Express extension there are two new settings areas created within Ninja Forms. A main extension settings page and a per form settings section.
These settings can be accessed by visiting Forms > PayPal. On this page you will see two sections.
- Transaction Currency – Select the currency type you want to handle all transactions with.
Live API Credentials
- Live API Username – Your Live API username as provided by PayPal.
- Live API Password – Your Live API password as provided by PayPal.
- Live Signature – Your Live signature as provided by PayPal.
Sandbox (Test Mode) API Credentials
- Sandbox API Username – Your Test API username as provided by PayPal.
- Sandbox API Password – Your Test API password as provided by PayPal.
- Sandbox Signature – Your Test signature as provided by PayPal.
Per Form Settings
These settings can be accessed on the Form Settings tab of any form you are editing. On this tab you will see a section entitled PayPal Settings.
- Use PayPal Express – Checking this option will tell Ninja Forms to send all complete submission through PayPal for payment.
- Run in sandbox (test) mode – When this option is check Ninja Forms will connect to PayPal only with your test credentials so you can see how the flow will work before turning it live. If unchecked Ninja Forms will use your live PayPal credentials.
- Default Product Name – If you do not plan on using calculation fields to adjust the total amount to be submitted to PayPal then this will act as the name for the product or service you are providing.
- Default Product Description – If you do not plan on using calculation fields to adjust the total amount to be submitted to PayPal then this will act as the description for the product or service you are providing.
- Default Total – If you do not plan on using calculation fields to adjust the total amount to be submitted to PayPal then this will act as the price for the product or service you are providing.
[Jump to top]
Accepting Payments on your Form
To Calculate or Not to Calculate,
that is the question. When you want to create a form to accept payments using Ninja Forms and PayPal Express, you should first decide whether or not you want to use calculation fields in your form. Using calculation fields in your form allows you to give the user a dynamic total, based upon their form selections. You should choose this method if you are creating a form in which the user’s selections changes the amount they should pay. If your form total doesn’t need to change, you just need to collect data from the user, then you don’t need to use calculation fields at all. Just to recap:
Use calculation fields if you want to:
- Customize the total
- Add product details that change the price
- Add a Tax Field or Subtotal
You don’t need to use calculation fields to create forms like:
- Event signups
- Basically anytime everyone pays the same price.
Now that you know what type of form you need to build, we’ll talk about how to set each up.
**Please note that NO form using PayPal Express should be set to submit via AJAX, as that setting is not compatible with PayPal Express.
[Jump to top]
Accepting Static Payments
Forms Without Calculation Fields
In this example, we’ll pretend that we’re creating a sign-up form for our pool party. This pool party is going to cost everyone who attends $25, so we don’t need any calculation fields.
These basic settings aren’t really particular to using PayPal, but I wanted to show the success message. If you notice, we’re using the shortcode ninja_forms_paypal_transaction_id. As the name suggests, upon a successful payment, this will show our user the PayPal Transaction ID. (You can use this shortcode regardless of whether or not you’re using calculation fields
The next setting area is specific to PayPal Express.
Here we set up a few important things:
- We tell Ninja Forms that we want to use PayPal Express with this form. If this is unchecked, PayPal won’t do anything.
- By running this in “Sandbox (test) mode” we’re not actually spending any money while we test.
- The default product name is required, since we aren’t using a calculation field. This is the text that will be shown to the user when they land on PayPal’s site. It’s what they’re paying for.
- The default product description is optional, but if you add some text, it will be shown on the PayPal site as well. (See below for screenshots).
- The default total is required, since we aren’t using a calculation field. This is what our user will be charged. It is very important.
After we’ve saved these settings, we’ll add our fields to collect our user’s information. It doesn’t matter what fields we put in the form. Again, because we aren’t using calculation fields, these fields are just for capturing information. None of our payment process is actually based on these fields. For our Pool Party Registration example, I’ve added several fields having to do with user’s contact information
Alright. Now we have a form, and we’ve set it up to use PayPal, let’s take a look at it and what it will do.
Notice that the user doesn’t actually have to click “Checkout” or “Buy Now.” The PayPal processing is integrated with the regular Ninja Forms submit button. (If you wanted, you could add a PayPal logo to your form using a text layout element)
Once the user clicks submit, they’re taken to PayPal to enter their payment details. Notice that the default product name and description we entered earlier can be seen on this page
Here your user would login or create a PayPal account to complete their payment. Once that payment is completed, they will be redirected to your form. If they have paid successfully, they will see the success message. If their payment fails, they will be presented with the form and an error message telling them that their payment failed.
Thankfully, we’ve got enough left on our credit card to pay the $25 pool party registration fee. Since we’ve completed the payment successfully, we’re greeted with this screen
[Jump to top]
Accepting Calculated Payments
Forms With Calculation Fields
Before beginning this documentation, it might be helpful to start with our primer on Basic Calculations as well as a review of the documentation on static payments with PayPal to better understand the settings we will be discussing here. Remember if you are making a form for dynamic payments, do not fill out the default “Product Name”, “Product Description”, or “Product Total” fields.
First, we need to add a field to let the user decide what they want to purchase. In the example below, I have taken a very simple list field and added three options to it, each costing a different amount.
Three options in this field are key to dynamic PayPal payments:
- With the PayPal Express API, all items contributing to the total must have the option “Consider this an item for PayPal purposes” checked, so make sure to check that setting as below.
- If you like, you can also add this field to your auto total. In this example, we will check the auto total option as well.
- Checking Use List Label for PayPal Product Name will carry the label to PayPal to be added as a visual aid to the customer as they check out. If this is not checked, all that will show in PayPal is a generic label, like “Total1.”
An important thing to remember is that you MUST have exactly one “Total” type field. You must use the “Total” field built in to Ninja Forms and not a normal calc or subtotal field. See the screenshot below.
The last step before adding a submit button is to configure your Total field to include automatically calculated values (any values checked with the auto total.) Do not add the total field itself to the auto total, and also do not mark the total field “Consider this an item for PayPal purposes” as it IS the total and is not contributing to the total.
That’s it for a simple dynamic payment form! Add a submit button, and you are good to go!
Forms With Calculation Fields And Quantities
Sometimes you may want to allow users to order more than one item at a time. Because of the PayPal API requiring your total to match the sum of all items marked “Consider this an item for PayPal purposes,” an extra step is needed. We will continue the example above to allow our users to add a quantity field to purchase T-Shirts of multiple sizes. The same principles we will be applying here will also apply to adding things such as taxes and other fees.
First, we will need to add a number box to the form created above to indicate how many T-Shirts the user wants to order. Because this is a quantity and not an amount contributing directly to the total, we will NOT mark the option “Consider this an item for PayPal purposes.” Make a special note of the Field ID of this quantity field, as well as the field ID of your list field.
Next, make a Number field for number of shirts ordered. Then add a Calculation field; configure it so the shirt quantity (Field ID 281 here) multiplies by the shirt options (Field ID 279 here). Your equation will look like this:" field_281 * field_279." This Calculation field ID will later be used in your total.
Now, your calculation field amount is the actual amount which will be added into the total. This means that you must now uncheck “Consider this an item for PayPal purposes” in your list field, and check it instead in your calculation field. This option is often overlooked and will cause your PayPal transaction to fail if not done properly. If you are using the auto total, you will no longer want to include your list field. You may include the calculation in the auto total if you like, but since our form is becoming a bit more complex it might be best to use manual formulas instead of the auto-total from this point.
Lastly, let’s say that you need to add tax onto the purchase. You would need one more calc field with an equation like below. There is a tax field included with Ninja Forms, but I am going to show you how to do this manually with a calc field. In Tennessee, the state sales tax is 9.75%. I have created a calc field to collect Tennessee tax below. Remember, because the tax also adds to the final total, we will also choose the “Consider this an item for PayPal purposes” option.
Our last step is to change our Total Field to use a calculation instead of the auto total (you can use the auto total, but for sake of this tutorial we will do this manually). It will need to contain the sum of the order as well as the tax, so all we need to do is add both of those fields to our total by adding them in the calculation method box in our total field.
That’s all there is to it! Add a submit button, and you are ready to accept payments on your WordPress site! To recap, these are the most important things to remember:
- The value in your total field must be the same as the sum of all fields marked “Consider this an item for PayPal purposes.” If fields are marked with this that are not contributing to your total, or fields that are contributing to your total are not marked with this option, the transaction will be rejected by PayPal.
- Use calculation fields to add complex features like quantities, and subtotal fields to add simple, final adjustments like taxes to your form.
- Make sure your form has exactly ONE “Total” field, as that is where PayPal pulls the total from.
[Jump to top]
Tracking your PayPal Transactions
When a user submits a form that is setup to use PayPal Express, the results of the payment are recorded in the same record as the submission.
There are three different status messages that PayPal Express will automatically assign to submissions:
- Pending – The submission has been saved and the user has been sent to PayPal to complete their transaction. This status means that the user either hasn’t completed their visit to PayPal or they have abandoned their form submission by not returning from PayPal.
- Cancelled – The user submitted the form, but either clicked the Back button in their browser or the Cancel link on the PayPal site.
- Completed – The user has successfully submitted the form and paid with PayPal.
In addition to these payment statuses, you can assign a status of “refund” by editing a submission using the Ninja Forms submissions viewer.
When you view a list of form submissions within Ninja Forms, you’ll see a column for both PayPal status and Transaction ID.
PayPal Transaction ID
If a payment is successful, Ninja Forms will store the transaction ID that it receives from PayPal. This can be found by viewing the submissions in the Ninja Forms submission viewer.
More to Come
With the changes to submission storage that will be coming to Ninja Forms over the next several months, more reporting options will become available to the PayPal Express extension.