Integrating PayPal - Some Things To Remember

Around August, I began implementing a full PayPal integration for our merchants, allowing any of them to beign accepting PayPal payments, in the exact same way as any of our other payment providers. This project actually went rather smoothly, and much better than my initial expections. Our requirements prevented us from using their newer REST API, however after spending a day getting familiar with their SOAP API, and writing a small wrapper lib for the functionality we needed, it was no longer a concern.

With that being said, there are a few things that I wish I knew previously, that could have prevented some headaches. These points are mostly from the perspective of a SaaS/Marketplace-type, however some are also relevant to a regular ecommerce storefront. As well, I recognize that some of them seem fairly obvious in hindsight, but I think they are still good to point out.

1. Your User Experience is PayPal dependent

When you are facilitating your merchants (those selling products through your service) to accept PayPal, your Merchant’s experience with PayPal is a reflection on you. This means that if PayPal treats your customer, or they have a bad experience, it will reflect badly on you. Unfortunately there is not much you can do about this other than be aware of it, and attempt to proactively address issues that are likely to pop up. This can help you limit the issues that a customer will have to reach out to PayPal about, and reduce the number of interactions that you do not have control over. I’ll talk about a few of these that we have already seen.

It is important to remember that even if your experience with PayPal (from your marketplace’s point of view) is largely positive, there is no way to guarantee that your individual merchants will have a similar experience.

New Merchant Account Limits

By default, PayPal applies limits to the amount of incoming funds a new-ish PayPal account can accept, after which funds are frozen for 21 days. The cap amount is reportedly based on industry and company information, however in practice we have seen a relatively standard 6k/month cap on incoming funds for new Merchant PayPal accounts.

Note that while this is a perfectly reasonable limit for a new merchant, existing merchants with existing, and thriving, businesses can very quickly hit this limit. Depending on the business model, this can have serious affects on their cash-flow. We saw this with a few existing merchants who decided to begin accepting PayPal as an option. For these merchants we were able to address this by working with PayPal, however we were caught off-guard when our merchants began to receive warnings that they were approaching their limit. Had we been aware of this early we definitately would have set expections around it, as well as proactively worked with merchants who were likely to very quickly hit this cap.

Aggressive Chargeback Response

When PayPal receives a complaint, they will almost always side with the end customer. The notices that are sent to the merchant presents very limited options, do not give a clear way to defend themselves or fight the charge, and instructs the merchant to take action directly inside of PayPal. Depending on how tighly PayPal with integrated with your service (ie, do you sync back from PayPal?), that may have negative consequences to your data integrity. It is important to be aware of how PayPal responds to situations like this, as well as having the resources and knowledge available to your merchants to respond and take appropriate action.

2. PayPal Transaction Fee Refunds

Most current payment processors refund their entire transaction fee in the event of a refunded transaction. PayPal however, does not. PayPal’s transaction fee is typically split into two components; a 30 cent base transaction fee, followed by a percentage of the order total. On a partial refund, the percentage component is adjusted accordingly, and on a full refund the percentage component is adjusted to 0. PayPal however does not refund the base 30 cent transaction fee. This is not typically a huge deal to most businesses, however when integrating it into your platform it creates some situations you will have to deal with.

Firstly, communicating this to your merchants is very important. They will expect all payment processors to behave the same when it comes to moving money, and it is important to highlight the differences, especially when it is not something that they would typically expect.

Secondly, it can lead to unexpected conditions that your system will have to deal with. For instance, when we were testing our system we discovered that a payment to an empty merchant account (that did not have a payment source attached, or could not be charged against) could not be refunded. The reasoning is clear; without refunding the 30 cent base transaction fee, there was insufficient funds in the account to cover the refund, however if not considered it can lead to some rather confusing error messages.

If it seems as if that would never happen, we have many merchants who like to make ‘real’ payments to themselves in order to see that everything works as expected, and then refund themselves. Since this would be against a new account, that they have not taken real payments into yet, and often not fully set up, it is entirely possible for a refund to fail with insufficient funds. Even if it does not fail, we worried about merchants questioning why we did not refund the entire transaction fee. For this reason we made sure to clearly communicate this fact to our merchants in multiple places.

3. Specifying Options with Billing Agreement

We use what is known as a ‘Channel-Initiated Billing Agreement’ in order to accept PayPal payments. It is similar to a Stripe token, allowing us to initiate a charge against a PayPal account. There are many options which can be set on the Billing Agreement on creation, some of which we learned later must also be specified each time the Billing Agreement is charged against.

The one that got us here is the ‘PaymentType’ option, which we set to ‘InstantOnly’ on creation. What this means, is that we want to only accept ‘Instant’ payment types, and reject delayed funding sources (such as eCheck). We made the decision to reject delayed funding sources in order to simplify our itegration, however did not realize that we would need to re-specify the PaymentType option on each transaction. Without also including the option on the individual chargs, we would accept anything (and not respect the options declared on the Billing Agreement). Again, it is possible that this is specified in documentation somewhere, however was not the expected behaviour, and is an easy enough mistake to make.

Note that in hindsight I recognize that this was a perfect example of something that definitely should have had it’s own tests.

4. Sandbox vs Live Environment

Many ecommerce solutions, ours included, provide a way for users to process ‘test’ transactions. Unlike other payment processors, PayPal’s sandbox and live are completely separate environments, and do not provide a way to easy force specific responses (such as how Stripe provides test card numbers). We chose to prevent test transactions through PayPal for the following reasons. It would be completely possible to do,

In order for us to support proper test transactions with PayPal, we would have to:

• dynamically switch the environment we are targeting
• dynamically switch which merchant PayPal account we need to charge from
• allow our merchants to connect multiple PayPal accounts (one test and one live)

The biggest problem however would be designing a good experience for our merchants to manage multiple merchant and user accounts within different environments. Our User Experience here was a high priority, and we did not feel that we would be able to produce a good enough experience.

5. ‘Collusion’ is a Thing

If you’re testing in a live environment at all (which is probably a good idea to do at least once), ‘collusion’ is something you will likely find yourself dealing with. In this situation, ‘collusion’ is an act of an individual using multiple accounts in order to make payments to themselves. This is counted as fraudulent activity, and is often automatically detected and blocked. Unfortunately, this situation uses the same error code as other common user-based payment errors, so is very difficult to identify if you are not aware of it. The only way we were able to track down why all of our test transactions were failing was to have our integration engineering contact at PayPal trace through on PayPal’s end, talk to their fraud team, and get back to us with an answer. Unfortunately this ended up taking several days, which we could have avoided had we been aware of this potential issue in the first place. Note that PayPal does have the ability to deactivate this temporarily, and they likely have a better, recommended solution as well.

6. PayPal is not just for International Users

If you’re a US based company, and anything like us, you probably assumed that the majority of PayPal usage these days is international. We had that same assumption, and we were wrong. Currently, on any given day the US accounts for approximately 85% of our total PayPal transactions. The assumption that integrating PayPal would have the biggest effect on international merchants caused us to partially consider PayPal support as an internationalization feature, and I believe we would have addressed it sooner had we not considered it in this manner.

Overall, PayPal was a great addition to the options that we offer our merchants. Being aware of the mentioned issues would have smoothed the road getting here, and hopefully some of these tips can help others with their own PayPal integrations.

Hopefully this works out for you, or was at least helpful. If you have any questions, don’t hesitate to shoot me an email, or follow me on twitter @nrmitchi.