Using PayPal with the API

1. Overview
2. Billing Agreements
   1. Create Billing Agreement
      1. Request Billing Agreement Token
      2. Redirect Customer to PayPal With Billing Agreement Token
      3. Finalize Creation of Billing Agreement
   2. Create Customer
   3. Update Customer
3. Legacy Adaptive Payments Preapprovals
   1. Create Customer
   2. Update Customer
   3. Configure Cheddar Product
   4. Checking PayPal Customer Status

1.1 Overview

Cheddar's subscription management and recurring billing enables transacting for potentially variable amounts in a subscription over time. To do this with PayPal, an agreement must be created between you (the merchant) and the PayPal account holder.

Cheddar supports two ways of doing this:

1. Billing Agreements with Reference Transaction (recommended)
   
2. Adaptive Payments Preapprovals

Note that these methodologies are restricted to receiving payments from PayPal accounts. This does not include the "guest" credit card feature of PayPal Pro. If you want to accept direct credit card, you must also have a credit card merchant account and gateway.

As a merchant, you need a Business or Premier PayPal account to take advantage of Cheddar's PayPal account payments support. If you don't have a Business account yet, you can get one or convert a personal account here.

2 Billing Agreements with Reference Transactions

Adding a PayPal Account to a subscription in Cheddar starts with requesting a Billing Agreement from PayPal. This results in a "token" value representing the Billing Agreement request. The token is then used to redirect the customer to PayPal to accept the Billing Agreement. When that process is complete, you will have a Billing Agreement ID which you can use to create or update the subscription in Cheddar. The Billing Agreement ID is referred to as the gatewayToken in Cheddar.

Note that in order to use Billing Agreements, you'll first need to be approved for Reference Transactions by PayPal. Contact PayPal customer support to request this approval.

2.1 Create a Billing Agreement

PayPal's documentation for creating a billing agreement is the best resource for learning about this process.

It's important to note that you should only use the "Setting up a billing agreement before payment" guide of the PayPal documentation.

Here's a summary of the process with minimum requirements:

2.1.1 Request Billing Agreement Token

Using your preferred PayPal Express Checkout endpoint, you may request a Billing Agreement token with these minimum parameters:

The PayPal API response includes a TOKEN value which represents the Billing Agreement request. You'll then using this value to redirect the customer to PayPal.

2.1.2 Redirect Customer to PayPal With Billing Agreement Token

An example of redirecting the customer is in the documentation.

The customer is then presented with the PayPal website where they are prompted to log in if necessary and then to either accept or decline the Billing Agreement.

Upon acceptance of the agreement, the customer is automatically redirected to the RETURNURL set in your original request. Included in the URL query string is the now active Billing Agreement ID. You'll use that value to either create a new customer and subscription or edit an existing subscription in Cheddar.

In the event that the customer explicitly declines the Billing Agreement, they are returned to your CANCELURL.

2.1.3 Finalize Creation of Billing Agreement

Using the token from the SetExpressCheckout response, make a call to the PayPal API to finalize the Billing Agreement using the CreateBillingAgreement API Operation. Here's an example of minimum requirements for this call:

The response to this call includes the active BILLINGAGREEMENTID. You'll use this value as the subscription[gatewayToken] when creating or updating the customer's subscription in Cheddar.

2.2 Create Customers with Billing Agreement

Using the customer's Billing Agreement ID from PayPal, you can create a new customer, update an existing subscription, or update an existing customer and subscription. The Billing Agreement ID is used as the gatewayToken parameter of the subscription. Note that the gatewayToken parameter at the customer level is not used in this scenario.

The following example shows minimum requirements for POST /xml/customers/new with a PayPal Billing Agreement ID. Additional params may be found in the documentation.

When you pass in the Billing Agreement ID, Cheddar validates the Billing Agreement and looks up additional details associated with the PayPal account. Using this method guarantees that the billing information is accurate, so there's no need for your application to pass in the parameters ccFirstName, ccLastName, or ccEmail with the API call. Any additional parameters passed in will override those retrieved from PayPal.

2.3 Update Customers with Billing Agreements

The example shows minimum requirements for POST /xml/customers/edit-subscription/code/[customer code] when updating with a new PayPal Billing Agreement ID. Additional params may be found in the documentation.

3. Legacy Adaptive Payments Preapproval Documentation

If your integration with Cheddar was completed before January 2017, you're using Adaptive Payments Preapproval to get permission from a customer to charge their PayPal account. Preapprovals must be renewed by your customer every 3 years. If you're using Cheddar's customer communications emails, the 'payment method expiring' email notification will go out to customers whose preapproval is expiring soon to prompt them to renew it.

3.1 Create Customers with Preapprovals

Using a signup form, create a new user in your system with a unique ID. Once you've created a user in your system, you'll make a Create a New Customer call to the Cheddar API. You'll pass the code, firstName, lastName, email, and subscription data: planCode, ccFirstName, ccLastName, method, returnUrl, and cancelUrl. These are the minimum required parameters for sending a new customer to Cheddar using the PayPal preapproval method:

Cheddar will return a customer XML file with a 'redirectUrl' and 'redirectUrlMobile' contained within the customer > subscriptions > subscription node like so:

<customers>
  <customer id="89fdd0e4-c775-11de-8728-40407c9117fd" code="test_customer">
    <firstName>Joe</firstName>
    <lastName>Schmoe</lastName>
    <email>joe.schmoe@example.com</email>
    .
    .
    .
    <subscriptions>
      <subscription id="7fc2f2e6-3e47-11df-8728-40407c9117fd">
        <plans>
          <plan id="e6eac5ee-e5e9-11df-86d5-40407c9117fd" code="PAID">
            <name>Paid</name>
            .
            .
            .
          </plan>
        </plans>
        <ccFirstName>Joe</ccFirstName>
        <ccLastName>Schmoe</ccLastName>
        .
        .
        .
        <redirectUrl>https://www.paypal.com/cgi-bin/webscr?cmd=_ap-preapproval&preapprovalkey=AP_3d3d3d3d3d3d3d3d</returnUrl>
        <redirectUrlMobil>https://www.paypal.com/webapps/adaptivepayment/flow/preapproval?expType=mini&preapprovalKey=AP_3d3d3d3d3d3d3d3d</returnUrlMobile>

      </subscription>
    </subscriptions>
  </customer>
</customers>

Redirect customer to redirectUrl or redirectUrlMobile

You must immediately redirect your customer to the provided 'redirectUrl' or 'redirectUrlMobile'. There are other ways, but we recommend doing so through a HTTP response location header:

HTTP/1.1 302 Found
Location: [redirectUrl]

This can be done using PHP like so:

<?php header('Location: ' . $redirectUrl); ?>

The customer is then prompted to log into their PayPal account and accept the terms of the preapproval.

Simulation Mode

While in development, the returned redirectUrl will take you to a simulated PayPal experience with simple "accept" and "cancel" links. Once your account is in Live mode, the redirectUrl will take your customers to PayPal to complete the authorization.

3.2 Updating Customers with Preapprovals

The process for updating a PayPal customer is very similar. Use the Update Customer Subscription API call in much the same way as when creating a customer. The minimum required fields are code, and subscription params: method, returnUrl and cancelUrl:

Redirect customer to redirectUrl or redirectUrlMobile

You must immediately redirect your customer to the provided 'redirectUrl' or 'redirectUrlMobile'. There are other ways, but we recommend doing so through a HTTP response location header:

HTTP/1.1 302 Found
Location: [redirectUrl]

This can be done using PHP like so:

<?php header('Location: ' . $redirectUrl); ?>

The customer is then prompted to log into their PayPal account and accept the terms of the preapproval.

Simulation Mode

While in development, the returned redirectUrl will take you to a simulated PayPal experience with simple "accept" and "cancel" links. Once your account is in Live mode, the redirectUrl will take your customers to PayPal to complete the authorization.

3.3 Configure Your Cheddar Account

To configure your Cheddar account to use PayPal with preapprovals, on the payment processor page of the Quick Setup simply select PayPal, check the box next to "Use peer-to-peer PayPal account payments", and select "Use Adaptive Payments Preapprovals". After you enter your payment information on the Go Live page of the Quick Setup, you'll be prompted to enter your PayPal business account details.

3.4 Checking Customer Status

When you're checking customer status from Cheddar during a customer's login, PayPal customers created with a preapproval can return a special type of "canceled" status. All PayPal customers begin in a "canceled" state because of the delay between sending PayPal their information, and PayPal returning us their status. This asynchronous process is usually very short (5 seconds), but long enough to warrant a special status called paypal-wait.

When in this status, you will receive a cancelType of "paypal-wait" from the Get a Single Customer API call. This lets you know that post-signup, during billing authorization, we do not know if the customer is valid. We suggest that if this is returned, you do not grant access and let your customer know why: "Your payment is being validated, please try again in a few minutes."

View Plans and Pricing   or   Get Started with Cheddar now →