Using PayPal with the API

  1. Overview
  2. New PayPal Customer
  3. Update PayPal Customer
  4. Checking PayPal Customer Status

1.1 Overview

Using PayPal via the CheddarGetter API allows you to redirect your customers to the PayPal interface to authorize recurring payments from their PayPal account.

To use PayPal for recurring payments with CheddarGetter, we need to create a "preapproval". A preapproval is a set of parameters which are accepted (or rejected) by the PayPal account holder (the sender, your customer).

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.

The following is a brief walkthrough of how you can use the CheddarGetter API to interact with PayPal.

2.1 New PayPal Customer

Create a new user in your system

Using a signup form, create a new user in your system with a unique ID.

Submit User Data to CheddarGetter

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 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.1 Updating PayPal Customers

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.

4.1 Checking Customer Status

When you're checking customer status from CheddarGetter during a customer's login, PayPal customers 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 →