Recurring Payments with Drupal Commerce and PayPal

by Andrew Boag

During the build of one our Catalyst as-a-Service offerings – CourseBank – we implemented a recurring credit card billing solution, which allows customers to fully provision a premium account.

Catalyst has been involved in a number of credit card and mobile payment solutions over the last 15 years. Best practices have changed a lot, and there are now many more payment gateways on the market.

It has always been considered a dangerous practice to retain a copy of a client's credit card details in your own application database. It makes you, the provider of the solution, potentially liable for the wholesale theft of credit card details.  In the past, it wasn't unheard of to implement recurring payments by simply storing the credit card details inside your application and firing off an API call with a payment request every month. Not something that Catalyst recommends.

These days, the Payment Card Industry Data Security Standard (implemented in 2004) means there are concrete rules systems need to comply with for the protection of cardholder data. For the most part, these initiatives benefit both retailer and customer, reducing the overall risk of credit card theft and fraudulent transactions.

The safest and most usual model when integrating credit card payments into your online store is to not “see” or process the credit card details at all. Instead, integrate with an external payment gateway that processes the entire transaction in a workflow.

We suggest this method:

  1. After the customer has selected their product in your web store they click on “Proceed to Checkout” link. This takes them to the external payment gateway.
  2. At this point the customer has left the web store application. They're now located at a payment gateway (e.g. PayPal) and see the items they are purchasing again, with a total cost.
  3. The customer enters their credit card details and confirms the purchase. This may include some identity validation via their bank such as an SMS being sent to the card holder with a code that they must enter.
  4. Once payment is completed, the customer is forwarded back to the online store with a “Payment Successful” message.
  5. The customer may also receive payment notifications by email after the transaction.

Catalyst's Recurring Payment Requirements

Our CourseBank product is a traditional online service offering. Customers provide their credit card details only once during sign up. Then they are billed every month until they cancel the service.

Catalyst chose PayPal as our payment gateway partner.

Why PayPal?

Catalyst made this choice based on investigations, experimentation and experience. The PayPal service offering gave us a suitable feature set to implement recurring payments, and to integrate this with our Drupal 7 application. We use Drupal as the gateway for subscription, payment workflow and ongoing account management.

Conveniently, it is PayPal that schedules and handles the recurring payments, notifying us after each payment success or failure via a PayPal IPN message. Drupal does not trigger any payment via a monthly cron job or script.

If you are considering PayPal, you should work out whether you'll need to set up a PayPal Business account in order to accept payments for your business. These are sometimes referred to as Merchant Accounts. You will also need to make sure that you have everything in place to clear funds from your PayPal account into your bank account, and to adhere to all taxation requirements. Talk to your accountant or finance team and make sure you test things thoroughly (see 'Testing' section below). The rules for this will vary from country to country and are beyond the scope of this article.

PayPal's Instant Payment Notification (IPN) system is an excellent feature. We like it because:

  • IPNs facilitate 'reporting home' to our Drupal application about scheduled payments
  • IPN notification web service receipt was already implemented in the Drupal Commerce module. This made it easy to implement application-specific hooks based on events, e.g. restricting access to premium when a failed payment IPN was received
  • IPN notifications include all of the required success and failure payment events
  • IPN notifications have a robust retry architecture, so if our application is offline or unavailable for any period of time, notifications from PayPal don't get lost or discarded
  • PayPal's web interface allows us to easily investigate payment events. If we need to investigate a payment event, we have all the information at our fingertips.

Drupal – Commerce PayPal

The great thing about Drupal is the number of contrib modules already published for our use. This means we can concentrate our efforts on building the innovative and bespoke functionality our project needs, and not reinvent the integration wheel. The Drupal Commerce module already has integration with PayPal for payment processing, and already includes an IPN listener to catch asynchronous payment messages.

QA and Testing – This Time For Cash

We all know the value of incorporating proper Quality Assurance (QA) and testing into the build cycle of any enterprise application. This is the best way to reduce painful cleanup and issue resolution of functional bugs making their way to production.

But where automated payments are involved, the potential risks and implications around implementation bugs are considerably further reaching.

As well as all the standard functional testing and unit testing, Catalyst have some additional best practices that we have included when we are working with Payment System integrations:

  • Be aware that test payment gateways provided by providers (including PayPal) are not enough to test the end-to-end behaviour of all functionality. Of course developers and QA should make use of them, but part of the application testing needs to involve real payments in sandboxed environments. This is a little non-intuitive
  • We advise getting some pre-paid credit or debit cards for testing purposes. These can be used to trigger real transactions as part of the QA phase to trigger expected events such as insufficient funds and cancellation of transaction after the event (via phone call)
  • Involve the whole dev and infrastructure team in discussions to make sure that there is no chance that non-production environments can ever trigger real payments.


We hope you find this information useful. If you have further questions, please reach out.

NOTE: Please do not consider this article as an endorsement for PayPal above all other payment gateways. Catalyst has no commercial commitment to PayPal other than as a standard customer. There are a number of considerations around the selection of credit card payment facilities that are outside the scope of this blog.