PayPal Complete

PayPal Complete is the newest payment gateway solution from PayPal. PayPal Complete is a convenient way to support multiple payment methods offered by PayPal within one integration. Adding PayPal Complete to your Recurly side can be done in minutes and doesn’t require applying for a merchant account.

Supported payment methods

Credit and Debit Cards
PayPal

If you are interested in other payment methods please contact [email protected]

Supported card schemes

Visa, Mastercard, America Express, Discover, JCB, Diners club.

JCB is only supported for CA merchants.

Supported merchants in countries

United States, Australia, Canada, United Kingdom

Supported currencies

USD, AUD,CAD,CHF, CZK, DKK, EUR, MYR, GBP, HUF, JPY, NOK, NZD, PLN, SEK, SGD, TWD, PHP

Adding gateway on Recurly

To add PayPal complete gateway you can go to the Recurly Admin UI → Configuration → Payment Gateways → Add Payment Gateway. To enable PayPal Complete gateway you need to login to your PayPal account.

After adding a gateway the PayPal account can be verified. You can track the verification status in the admin UI.

If your PayPal Complete application is not immediately approved, your gateway will be in an Incomplete Configuration status and you will be able to see those status messages on the Payment Gateways page. These status messages will update automatically but you may manually request an update on your PayPal Account status by choosing Options → Refresh status.

PayPal status messages can include:

Email confirmation of your PayPal account email
PayPal application is in review
PayPal application requires additional information/needs more details
PayPal account is restricted and you cannot take payments
PayPal application has been denied

You may see one or more messages at the same time depending on the state of your application and PayPal account in general. For example, you may see that PayPal is reviewing your application and that your email address requires confirmation at the same time. These messages will disappear as your application moves through the approval process with PayPal.

If you have already created a PayPal Business account that accepts credit and debit card payments, you will not likely see these messages during onboarding.

In most cases, if you see any of the above alerts, reaching out to PayPal directly through your seller portal is advised as Recurly support team members do not have visibility to additional information regarding your account.

Recurly settings

After adding a gateway please specify the following settings:

Currencies
Card brands

PayPal settings

🚧
Please be sure that the Reference Transaction Flag and "Channel Initiated Billing" toggle is on in your account in order to allow vaulting with this gateway. The Channel Initiated Billing toggle must be enabled by a PayPal representative.

PayPal Payments and Refunds using a Bank Accounts (eCheck)

To get the full benefit of accepting PayPal transactions funded (or refunded) via a bank account (eChecks) in Recurly, you need to set up your PayPal account to send "IPNs" (Instant Payment Notifications) to Recurly. Follow these instructions.

An eCheck is an electronic payment funded by the buyer’s bank account. Conversely, it also applies when a buyer is refunded using funds from a Merchant's bank account attached to PayPal.

With an eCheck, the recipient should receive the money within 3-6 business days. Because of the delayed settlement nature of eChecks, there are some unique aspects to these transactions.

How are eCheck transactions different from other PayPal transactions?

eCheck transactions are like direct debits - they take 3-6 days for the funds to be settled into your PayPal account. Conversely, if you refund a customer using your bank account (for example, if you don't maintain a Balance in your PayPal account), this may also take 3-6 days or longer for them to see a credit on their original payment form.
As a result, PayPal assigns a "pending" status to the transaction while they wait for the buyer's or merchant's bank to settle the purchase/refund.
When the funds have actually settled, PayPal issues an "Instant Payment Notification" (aka webhook) to notify you that the transaction has been completed. If the funds are not received, they do the same, although the subject of the Instant Payment Notification confirms that the transaction was declined.

How are eCheck transactions reflected in Recurly?

Processing status:
- When PayPal confirms that the transaction request has been received and they have started processing it, they will return a "pending" status to Recurly. We set the status of the transaction in our system as well as the status of the related invoice to "processing". You can see this new transaction status in the Recurly App, our exports, and in the API.
- At the same time, Recurly will issue a "processing payment" webhook to any endpoints you have configured in Recurly.
- At the same time, Recurly will also issue a "payment processing" email to your customer (if you have enabled that email).
Status updates:
- PayPal issues status updates when the transaction status changes - e.g. when they have received funds, they will issue a notification to Recurly that the transaction has been completed successfully. At that time, Recurly will update the status of the transaction in our system with the appropriate status (e.g. if PayPal IPN says that the transaction was completed, we mark the transaction as "successful" and the invoice as "paid" in our system).
- At that time, Recurly will issue you the appropriate webhook (e.g. successful payment & closed invoice, or failed payment and past due invoice).
- At that time, Recurly will also issue the appropriate email to your customer (if you have enabled the email) (e.g. payment confirmation, or payment declined).

Configuring PayPal to send Recurly the status updates

In order to correctly reflect the PayPal transaction status in Recurly, you need to follow these instructions (more detailed instructions are available at PayPal ):
- Log in to your PayPal merchant account at www.paypal.com.
- Click the profile icon (Profile menu) on the top right side of the page. From the Business Profile menu, select Profile and Settings, then select My selling tools. Note: If you do not see the profile icon on the top right, navigate to My Account → Profile → My Selling Tools.
- Click the Update link in the Instant payment notifications row, in the Getting paid and managing my risk section.
- Click Choose IPN Settings to specify your listener's URL and activate the listener. Set the url to https://callbacks.recurly.com/paypal/_recurly_subdomain_here_ (for example https://callbacks.recurly.com/paypal/kalekrate)
- Click Receive IPN messages (Enabled) to enable your listener.
- Click Save.
- Click Back to Profile Summary to return to the Profile after activating your listener.

📘
Note: If your Recurly site is hosted in our European Union (EU) data centers you will need to use callbacks.eu.recurly.com instead of callbacks.recurly.com (e.g. https://callbacks.eu.recurly.com/paypal/kalekrate)

PayPal eChecks and Recurly Dunning and Retries

Because PayPal eChecks are asynchronous (i.e. it takes several days for the transaction to be confirmed as successful or declined) we handle related invoices that are in dunning slightly differently from invoices where the payment method is synchronous (like credit cards). When an invoice is in dunning, the status of the invoice is "past due". If the payment method is a PayPal eCheck, when Recurly then initiates an automatic retry attempt to try to collect payment on the invoice, we will change the status of the invoice back to "processing" until we hear back from PayPal whether the retry attempt was successful or declined. When we get the final status from PayPal, we will move the invoice back to "past due" if there is still time left in the dunning cycle for that invoice, or we'll move to "failed" if the dunning cycle has ended.

Here is how the transaction and invoice statuses update in one hypothetical scenario:

Event	Transaction status in PayPal	Transaction status in Recurly	Invoice status in Recurly
1. Recurly requests the initial payment, PayPal confirms that they got the request & processed.	Pending	Processing	Processing
2. Several days later, PayPal confirms that the payment was declined. Recurly puts the invoice into dunning.	Failed	Declined	Past Due
3. According to the dunning scheduled configured in Recurly, several days later, Recurly issues a dunning email	No change	No change	No change
4. Retry #1: According to the Recurly retry logic, several days later, Recurly initiates a new payment with PayPal to attempt to collect on the past due invoice.	Pending	Processing	Processing
5. Several days later, PayPal confirms that the payment was declined. Recurly confirms that invoice dunning period has not yet ended.	Failed	Declined	Past Due
6. Retry #2 According to the Recurly retry logic, several days later, Recurly initiates a new payment with PayPal to attempt to collect on the past due invoice.	Pending	Processing	Processing
7. Several days later, PayPal confirms that the payment was declined. Recurly confirms that invoice dunning period has ended.	Failed	Declined	Failed

Limitations

PayPal payment method is not supported on Hosted Payment Pages (HPP) with PayPal Complete gateway.
If moving subscriptions from PayPal Business Account to PayPal Complete gateway, existing Billing Agreement IDs will function properly.
When moving from PayPal Business to PayPal Complete, to allow existing subscriptions to keep running properly, the same credentials must be used.
Subscriptions that were created on PayPal Business can be moved to PayPal Complete and will continue to use Billing Agreement IDs, however subscriptions that are created on PayPal Complete cannot be moved back to PayPal Business. New subscriptions created on PayPal Complete will use PayPal’s vaulting features rather than Billing Agreement IDs.