Using PayPal with the API

  1. Overview
  2. Billing Agreements
    1. Create Billing Agreement
    2. Create Customer
    3. Update Customer
    4. Configure CheddarGetter Product
  3. Legacy Adaptive Payments Preapprovals
    1. Create Customer
    2. Update Customer
    3. Configure CheddarGetter Product
    4. Checking PayPal Customer Status

1.1 Overview

To use PayPal Standard for recurring payments with CheddarGetter, PayPal requires that you're given permission by your customers to automatically charge their PayPal accounts through a billing agreement. This gives CheddarGetter the ability to execute recurring and one-time transactions according to your specifications throughout your relationship with your customer. CheddarGetter's integration with PayPal standard allows you to do this via Billing Agreements with Reference Transaction. This article will walk you through the process of setting up a Billing Agreement with your application.

Billing Agreements with reference transactions is a new feature as of January 2017, so if your integration was set-up before then, you're using a different methodology called Adaptive Payments Preapproval API with Third Party Permissions. If you're looking for legacy documentation about preapprovals for an existing integration you can find them here. Although we'll continue to support preapprovals, the billing agreements methodology is recommended for all new CheddarGetter integrations. If you're currently using preapprovals, but would like to switch to billing agreements, our support team can help you set-up a migration. Contact us here.

Note that CheddarGetter PayPal support currently only works with PayPal accounts, not the "guest" credit card feature of PayPal. If you want to accept direct credit card, you must also have a credit card merchant account and gateway.

As a merchant, you simply need a Business or Premier PayPal account to take advantage of CheddarGetter's PayPal 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

If you're using CG's API to create and update customers, a billing agreement is the simplest way get permission from a customer to charge their PayPal account. Once created, a billing agreement doesn't expire until it's explicitly canceled by the customer. In order to use billing agreements, you'll first need to be approved for reference transactions by PayPal. Contact PayPal customer support here to start the approval process.

2.1 Create a Billing Agreement

Once you've been approved for reference transactions, you'll configure your application to request a billing agreement when a customer signs-up or edits their subscription with PayPal as their payment method. You'll find the information you need to do that in PayPal documentation on creating a billing agreements workflow here.

It's important to note that you should only use the "Setting up a billing agreement before payment" guide of this documentation. This guide will walk you through the process of re-directing your customers to PayPal to accept the billing agreement. The customer must accept the billing agreement before a customer record is created for them in CheddarGetter. If the customer should be billed on sign-up, CG will initiate the transaction after the Billing Agreement has been accepted and the customer record has been created.

2.2 Create Customers with Billing Agreement

After you receive the customer's billing agreement token (or billing agreement ID) from PayPal, you'll pass that into CheddarGetter when you create a new customer, update an existing subscription, or update an existing customer and subscription. The following example shows minimum requirements for POST /xml/customers/new with a PayPal Billing Agreement token. Additional params may be found in the documentation.

Name Description Sample
code Your code for this customer. Limited to 255 characters. If not specified defaults to email address 3j2l6n2e8s
firstName Customer's first name. Limited to 20 characters. Daphne
lastName Customer's last name. Limited to 20 characters. Blake
email Valid email address. Limited to 20 characters. daphne@example.com
subscription[planCode] Your code for the subscribed pricing plan. PRO
subscription[method] Customer's payment method. Paypal
subscription[gatewayToken] PayPal billing agreement ID. B%2d7FB31251F28061234

When you pass in the billing agreement ID, CheddarGetter validates the billing agreement and looks up the first name, last name, and email address 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.

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 token. Additional params may be found in the documentation.

Name Description Sample
subscription[method] Customer's payment method, cc or paypal. paypal
subscription[gatewayToken] PayPal billing agreement ID. B%2d7FB31251F28061234

2.4 Configure Your CheddarGetter Account

The last step is to configure your CheddarGetter account to use PayPal with billing agreements. On the billing solution page simply select PayPal, check the box next to "Use peer-to-peer PayPal account payments", and select "Use Billing Agreements with Reference Transactions". When you convert to paid plan on the Go Live page, you'll be prompted to enter your PayPal business account details.

3. Legacy Adaptive Payments Preapproval Documentation

If your integration with CG 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 CheddarGetter'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 CheddarGetter 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 CheddarGetter using the PayPal preapproval method:

Name Description Sample
code Your code for this customer. Limited to 255 characters. If not specified defaults to email address 3j2l6n2e8s
firstName Customer's first name. Limited to 20 characters. Daphne
lastName Customer's last name. Limited to 20 characters. Blake
email Valid email address. Limited to 20 characters. daphne@example.com
subscription[planCode] Your code for the subscribed pricing plan. PRO
subscription[ccFirstName] Billing contact first name. Limited to 20 characters. Daphne
subscription[ccLastName] Billing contact last name. Limited to 20 characters. Blake
subscription[method] This customer's payment method. Credit Card or PayPal. paypal
subscription[returnUrl] Must be a valid URL. This is the location where subscriber is returned from PayPal after accepting a preapproval. http://mywebapp.com/login?paypalAccepted
subscription[cancelUrl] Must be a valid URL. This is the location where subscriber is returned from paypal after canceling a preapproval. http://mywebapp.com/login?paypalCanceled

CheddarGetter 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:

Name Description Sample
code Your code for this customer. Limited to 255 characters. If not specified defaults to email address 3j2l6n2e8s
subscription[method] This customer's payment method. Credit Card or PayPal. paypal
subscription[returnUrl] Must be a valid URL. This is the location where subscriber is returned from PayPal after accepting a preapproval. http://mywebapp.com/login?paypalAccepted
subscription[cancelUrl] Must be a valid URL. This is the location where subscriber is returned from paypal after canceling a preapproval. http://mywebapp.com/login?paypalCanceled

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 CheddarGetter Account

To configure your CheddarGetter account to use PayPal with preapprovals, on the billing solution page simply select PayPal, check the box next to "Use peer-to-peer PayPal account payments", and select "Use Adaptive Payments Preapprovals". When you convert to paid plan on the Go Live page, you'll be prompted to enter your PayPal business account details.

3.4 Checking Customer Status

When you're checking customer status from CheddarGetter 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 CheddarGetter now →