PayPal and the Road to Adaptive Payments

Introduction

It has been nearly 6 years now since I first started working with PayPal’s web services.  PayPal is actually one of the first web services I ever used and I’ve been able to “grow” right along-side the PayPal platform.

Over the years PayPal has introduced quite a few changes to the system.  Some features have simply been improved along the way while other new ideas have been built and released from the ground up with the help of the developer community.

We’ve seen the acquisition of PayFlow from Verisign and how the system has been somewhat merged into the PayPal platform with Payments Pro.  We’ve seen the expansion of Express Checkout and how it’s grown from a basic sign-in and continue portion of checkout to a full-blow order review page complete with real-time shipping calculators and sales tax updates (Instant Update API) as well as the ability to complete payment and eliminate unnecessary steps within a checkout flow.  We’ve even seen some Standard features enabled within the API like the ability to create buttons in bulk using web services.  PayPal’s latest addition, though, has been a tremendous benefit to me already and I’m excited to see where it leads us all.  Let’s talk a little bit about Adaptive Payments.

What is Adaptive Payments?  How can it help me?

The term Adaptive Payments has been given to the latest set of API’s launched by PayPal.  They provide the ability to transact online in a number of different ways that were not possible with previous API’s; at least not without some creative work-arounds.  As the name implies, Adaptive Payments can be utilized in a variety of different ways.  In fact, it’s tough to put a limit on the possibilities available with the new, open platform.  We’ll review some of the things we can do with the new API’s and how they’ve helped developers and merchants to accomplish tasks that either were not possible or were time-consuming and costly prior to Adaptive Payments.

One thing to keep in mind is that not every new API involves actual payments although they’re still considered part of the Adaptive Payments platform.  For example, the Adaptive Accounts, Authentication, and Permissions API’s do not move any money around, but they are still considered part Adaptive Payments and will follow the same application and approval procedures.

As I mentioned before, Adaptive Payments solutions could branch off in a number of different directions.  I’d like to cover a few scenarios where the platform has improved or eased the ability to accomplish certain tasks in hopes that such samples will help familiarize you with the system and help you think about the types of things you might like to do with it.

The Permissions API

One of the most significant API’s that produced the most immediate impact for me, personally, is the Permissions API.  As noted previously, this particular API does not have anything to do with payments directly, but it saved me literally days, if not weeks of time once I was able to launch it.  Let me explain.

Prior to the Permissions API being launched, the only way for 3rd party users to utilize your application was to either “plug-in” their own API credentials or go through the process of Granting API Permissions for your account within their PayPal profile.  Regardless of the method used this involved providing detailed documentation or direct support for users on how to handle the setup and configuration of your software with their PayPal account.

For example, let’s assume the end user wanted to use their API credentials rather than granting permission.  In order to do so (and this can still be done, of course) they would need to follow these steps.

• Sign in to PayPal and click into your Profile
• Click on Request API Credentials (or API Access depending on their PayPal account version)
• Select the PayPal API Option
• Select the option to generate signature based API credentials
• Accept the agreement.
• Copy/paste the all 3 values (username, password, and signature) into the application’s control panel where applicable.

This series of steps may seem simple, but any of you who’ve tried to provide documentation on the steps to achieve this on your own or who have walked through the steps with a customer over the phone can attest to the fact that it is anything but.   If you have more than just a few customers who need this done, hours can be wasted away supporting your product before your customer has even had a chance to use it.  On top of that, storing all of your user’s API credentials in your database would require additional security as that information could be used by developers to potentially make unauthorized API calls if they got their hands on it.

The other, recommended option is to go through the steps for Grant API Permissions.  This actually requires about the same number of steps as the first method, but eliminates the need to store 3rd party API credentials.  The steps would include…

• Sign in to PayPal and click into your Profile
• Click on Request API Credentials (or API Access depending on their PayPal account version)
• Select the PayPal API Option
• Select Grant API Permission
• Enter the API username of the application’s PayPal account
• Check all of the boxes for permissions that the application requires
• Submit and agree to grant permissions

With this method, your application will make API calls using your own API credentials, but you’ll also include the SUBJECT parameter, which is the email address of the user the call is being made for.  As you can see, though, the number of steps involved is the same as before, and the time involved in helping your customers configure that will be roughly the same.

The Permissions API eliminates the majority of these steps and provides the ability for you to tie this process directly into your application.  With a simple API call the user will be sent over to PayPal where they’ll sign in to their account and be presented with a list of permissions the application requires in order to work. Here they can simply Agree and Continue or Cancel.  That’s it!

Here is a quick PHP sample that would enable a few basic permissions on the user’s account. The sample code is based on my own PHP class that you might be familiar with from other articles of mine.

require_once('../../includes/config.php');
require_once('../../includes/paypa.nvp.class.php');

$paypal_config = array('Sandbox' => $sandbox, 'APIUsername' => $api_username, 'APIPassword' => $api_password, 'APISignature' => $api_signature);
$paypal = new PayPalPro($paypal_config);

$SetAccessPermissionsFields = array(
	'ReturnURL' => 'http://www.domain.com/paypal/set-access-permissions/return.php', // URL to return the browser to after authorizing permissions.
	'CancelURL' => 'http://www.domain.com/paypal/set-access-permissions/cancel.php', // URL to return if the customer cancels authorization
	'LogoutURL' => 'http://www.domain.com/paypal/logout.php', // URL to return to on logout from PayPal
	'HDRIMG' => 'https://www.domain.com/images/cpp-header-image.jpg'
);

$RequiredPermissions = array(
	'RefundTransaction',
	'DoAuthorization',
	'DoVoid',
	'DoDirectPayment'
);

$PayPalRequestData = array(
	'SetAccessPermissionsFields' => $SetAccessPermissionsFields,
	'RequiredPermissions' => $RequiredPermissions
);

$PayPalResult = $paypal -> SetAccessPermissions($PayPalRequestData);

if(count($PayPalResult['ERRORS']) > 0)
	$_SESSION['PayPalErrors'] = $PayPalResult['ERRORS'];

if(strtoupper($PayPalResult['ACK']) == 'SUCCESS' || strtoupper($PayPalResult['ACK']) == 'SUCCESSWITHWARNING')
{
	header('Location: ' . $PayPalResult['REDIRECTURL']);
	exit();
}
else
{
	header('Location: ../../paypal-error.php');
	exit();
}

This sample simply sets some basic fields very similar to Express Checkout in order to receive a token and redirect the user to PayPal. It also includes four permissions that it’s requesting access to: RefundTransaction, DoAuthorization, DoVoid, and DoDirectPayment. The user will sign in and see the following:

Once they’ve agreed your application will be ready to rock! This feature alone saved us hours of time helping users get up-and-running with USBSwiper and has allowed me to do the same within applications we build for other clients.  I’ve never felt a more immediate impact from a new API as I did from this one.  Thank you PayPal!

Pay – Split Payments

While the Permissions API is great, much of the buzz and excitement has revolved around new Pay API and the ability to split payments in real-time within a single checkout.  There is a plethora of ways to use the split payment feature in new and creative fashions, but I’d like to cover a couple of basic payment flows that the new API’s have greatly simplified for developers and merchants together.

Web site owners often sell a variety of products but don’t actually stock a single item.  Instead, everything they sell is drop-shipped from a separate location.  The site owner keeps a commission and forwards the order on to the actual product distributor.  It’s a simple business model, but automating the payment processing for such a situation would generally involve some time-consuming procedures.

In most cases, the best practice would be to develop an IPN solution to process the orders.  This would typically involve utilizing the MassPay API to send payment to the distributor’s PayPal account as well as generating custom email notifications for the merchant, the buyer, and the distributor.  I’ve written articles in the past on IPN alone and the intricacies of making it work correctly.  It can be a difficult thing to troubleshoot and get working correctly and often end up costing the merchant quite a bit in development cost.  On top of that, handling the fees could be a tricky task because the site owner would essentially be eating all of the fee unless some calculations were included to pass some of that on to the distributor within the MassPay calls.  Confused yet?  Well don’t worry about that because Adaptive Payments helps to clean up this mess.

Using the new Pay API, developers can split payments up in real-time during the checkout flow.  No longer must we handle splitting up payments and processing it after-the-fact.  Instead, we can make it all happen immediately within the original payment.

The Pay API provides the ability to include multiple recipients on any given payment.  As such, we can easily calculate the amounts the site owner should receive and the distributor should receive and include both of them in a single transaction.  We can choose to show the split to the buyer (Parallel Payments) or hide it so they only see a single receiver even though it’s getting split after that (Chained Payments.)  Also, we can specify exactly who should pay the fee; the seller, the distributor, or split it between the two.  Back-end processing via IPN is no longer required but could still be utilized for other tasks that suit IPN well as Adaptive Payments are completely compatible with IPN.  This generally cuts a large chunk out of development time and reduces the up-front cost for the merchant.

Pay – Preapproved Payments

Another scenario that comes up often when dealing with payments is the ability to collect a lump sum of money and then disperse the funds out to a number of different recipients at a later date.  This is considered payment aggregation and is not something that credit card companies or other payment processors take lightly.  In fact, in my experience, it’s nearly impossible to get approved for such an application without a tremendous business and credit history.  Even then it can be extremely difficult and has always been something that’s been tough to do for clients…until now.  The new Preapproval API that’s included with Adaptive Payments resolves these issues.

Rather than collect funds up-front and disperse them accordingly at a later date, (for example, a donation system that doesn’t pay out until an overall goal is met) users can preapprove a given amount of money to be paid within a particular period of time.  This allows the application to submit payments on their behalf with further approval, and the money does not leave the payer’s account until the actual payments are to be made (the goal is met.)  Also, the funds can be moved directly to the account they’re intended to instead of funneling through an intermediary.  This is just one very simple example of the way the Preapproval API can be utilized.

Summary

The new Adaptive Payments API’s provide an entirely new perspective on payment processing and managing accounts within web sites or applications.  They save time and headaches which in turn saves money for merchants and allows developers to complete tasks without any creative work-arounds or additional, unnecessary API calls.

I hope some of the scenarios I’ve mentioned here can help you with future projects of your own.  Happy adaptive development!