The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

PayPal Payments

Recurly supports merchants who want to let customers pay using their PayPal account. To use Recurly to process PayPal payments, you can use either PayPal Business or Braintree as the gateway. Recurly helps you get the most from your PayPal customers by supporting the latest Express Checkout and OneTouch experiences.

Accepting PayPal Payments

In order to accept PayPal payments through Recurly, there are a few steps you will need to take.

Get approved to use Reference Transactions

The first thing you need to do is get approval from PayPal or Braintree (depending on which gateway you use) to use "Reference Transactions." Reference Transactions are how PayPal processes recurring subscription payments. Merchants must typically have some current PayPal operating history in order to be approved to use Reference Transactions. Learn more about Reference Transactions.

If you are using PayPal as your gateway, contact them to get approved and have the feature enabled on your PayPal account:

If you are using Braintree as your gateway, contact them to get approved and have the feature enabled on your Braintree account:

Please note that this feature is different from the similarly named "Recurring Transactions" feature, and that may need to be clarified with your PayPal or Braintree account representative.

Enable Reference Transactions in Recurly

Once approved to use Reference Transactions, add "PayPal Business Account" as a gateway in your Admin Console.

Configure your PayPal API credentials

The final step is to configure your PayPal account with your PayPal API Credentials, using the signature method. This will enable Recurly to connect to your PayPal account for payment processing using your API credentials (API username, password and signature). These credentials are usually found via one of the below paths:

Path 1:

  1. Log in to your PayPal account at paypal.com
  2. On the My Account tab, click on the Profile sub-tab.
  3. Click on API access or Request API credentials, depending on your PayPal account type.
  4. PayPal will present two options: granting API permissions (Option 1) and requesting API credentials (Option 2). Select option 2. It may say View API Signature or View API Credentials.

Path 2:

  1. Log in to your PayPal account at paypal.com
  2. On the top-right, click on the Profile tab.
  3. Click on My selling tools, then "update" next to API Access.
  4. Select "Manage API Credentials".
  5. PayPal will present two options. Select "Request API Signature".
  6. Select Agree and Submit to view the appropriate credentials.

PayPal Express Checkout and One Touch™

Recurly supports the Express Checkout flow and One Touch™ flow for all customers using the latest version of Recurly.js. With Express Checkout and One Touch™, your customers have a more seamless checkout experience. Learn more about Express Checkout and One Touch.

The PayPal Express Checkout experience

On desktop browsers, the PayPal checkout is completed in a modal that appears on top of your checkout page (see screen shot at the top of this page). On tablets and smart phones, buyers access the PayPal payment screens in full-page mode:

The One Touch™ experience

With Express Checkout and One Touch™, customers log into PayPal once, and then can check out without re-entering their password or payment details for up to 6 months.

Billing Agreement Management

At checkout, the customer is redirected to PayPal's website to validate their PayPal account and presented with a billing agreement. After committing to the billing agreement, their subscription will begin and the customer is redirected back to the Recurly confirmation page.

Customers may modify their billing agreement (e.g. if they want to change their payment method) directly inside PayPal or they can use Recurly to cancel their subscription, effectively terminating their billing agreement.

PayPal eChecks

To get the full benefit of PayPal eChecks in Recurly, you need to set up your PayPal account to send "IPNs" (Instant Payment Notifications) to Recurly. Follow these instructions.

**Note: you must enable eChecks within Recurly, on the PayPal gateway config page.

According to PayPal, an eCheck is an electronic payment funded by the buyer’s bank account. 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. Recurly is updating our system to help you manage these aspects, and make sure you are getting the most value from your PayPal customers.

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.
  • As a result, PayPal assigns a "pending" status to the transaction while they wait for the buyer's bank to settle the purchase.
  • 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

  • Step 1: Enable the config option for accepting eChecks within Recurly from your gateway config page. [subdomain].recurly.com/configuration/payment_gateways
  • Step 2: 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.

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

  1. Several days later, PayPal confirms that the payment was declined. Recurly puts the invoice into dunning.

Failed

Declined

Past Due

  1. According to the dunning scheduled configured in Recurly, several days later, Recurly issues a dunning email

No change

No change

No change

  1. 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

  1. Several days later, PayPal confirms that the payment was declined. Recurly confirms that invoice dunning period has not yet ended.

Failed

Declined

Past Due

  1. 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

  1. Several days later, PayPal confirms that the payment was declined. Recurly confirms that invoice dunning period has ended.

Failed

Declined

Failed

If you do not want to accept PayPal eChecks

  1. Go to the PayPal website and log-in to your account
  2. Click the Profile icon at the top of the page (it’s shaped like a person)
  3. Click “Profile and settings” (right next to the gear icon)
  4. Make sure you are on the “My selling tools” page
  5. Click Update next to “Block Payments”
  6. Review your payment settings and disable the appropriate payment types (eChecks).
  7. Click Save

Collect PayPal Shipping and Billing Addresses

New feature: Collect PayPal Shipping and Billing Address

PayPal users can enter their shipping and billing addresses into their PayPal profile, and Recurly can obtain that information from PayPal. If we collect that address information, then you don't have separately ask your customers to provide that information during the checkout flow. This allows you to simplify the checkout flow for PayPal users, resulting in higher conversion and more revenue. PayPal calls this feature the "Express Checkout Shortcut" ... read on to learn more.

PayPal Express Checkout Shortcut

With the Express Checkout Shortcut, buyers skip the pages on your website that gather shipping and payment details. Instead, the buyer is redirected to PayPal from the shopping cart page. There is no need to collect the buyer's shipping information; Recurly captures the buyer's shipping (and billing, if configured to do so) address, so there is no need to ask the buyer to provide it.

The normal PayPal checkout flow:

The PayPal Express Checkout Shortcut flow:

Learn more about the PayPal Express Checkout Shortcut and the PayPal UI Requirements.

Configuring PayPal Express Checkout Shortcut in Recurly

On the gateway configuration page, there are 3 configuration options:

  • Obtain billing address: this instructs Recurly to ask PayPal / Braintree to send us the billing address on file for the customer.
  • Overwrite billing address: if the first option is selected, you'll then be able to select another option that tells Recurly to overwrite the billing address on file with whatever billing address we get from PayPal. Note that if we don't get a new billing address from PayPal, and there is already a billing address on file for the account, we will not erase what's currently there.
  • Obtain shipping address: this instructs Recurly to ask PayPal / Braintree to send us the shipping address on file for the customer, and associate the address with the subscription being purchased. Note, that if the shipping address already exists on the account, we won't create a new one ... but we will associate it with the subscription being purchased.

Recommended API Integration Flow for Express Checkout Shortcut

If you are having Recurly collect shipping address from PayPal, we recommend that you follow this API integration

  • Perform a normal checkout flow to PayPal Express Checkout where the customer selects the shipping address
  • After a successful PayPal authorization, Recurly.js returns the token to the checkout form as normal.
  • Perform an API request to Recurly to add (or update) the customer’s account using the token.
  • If the customer has a saved shipping address with PayPal, Recurly will at this time fetch it and assign it to the account according the configured settings in Recurly.
  • Assuming you are using the version 2.4 or greater of the the Recurly API, you will need to retrieve the shipping address for the new or updated account (using the list shipping address endpoint). Note that accounts can have more than 1 shipping address in Recurly, so pick the most recently created address.
  • Then use this shipping address to continue the customer through the rest of the checkout process.
  • After the checkout is complete, perform another API call to create the desired subscription(s) that was purchased, being sure to assign the shipping address to the purchased subscription(s) using the shipping_address_id that corresponds to the address.

Additional notes about collecting PayPal Shipping Address

  • To get access to the feature, please contact Recurly Support.
  • This functionality is available through both PayPal and Braintree.

Additional notes about collecting Billing Address

Recurly can also collect your customer's billing address during the Express Checkout flow. To do so requires some additional configuration in your PayPal account.

  • To have PayPal send Recurly the billing address, please contact PayPal and ask them to to enable the "PayPal Billing Address Request" feature on your account.
  • This functionality is available through both PayPal and Braintree.

Limitations of PayPal payments in Recurly

  • PayPal payments are only available with the Recurly Hosted Payment Pages and Recurly.js. Customers will not be able to checkout using PayPal payments when using the Recurly API.
  • Custom Hosted Payment Pages parameters (such as account code) will not be stored if the customer cancels at any point in the process and attempts a new signup.
  • Approval for Reference Transactions is usually reserved for merchants with current PayPal operating history.
  • For more information on collecting VAT with PayPal payments, please visit our VAT documentation.
  • Unless you are using the "Collect PayPal Shipping Address" feature, Recurly currently does not receive address information from PayPal. If address information is needed for taxing purposes, please collect that outside of the PayPal checkout form. Recurly will use the address stored internally for tax calculations, while Paypal will use any billing address information stored within their systems for payment processing.