Introduction

PayPal now offers a vast array of payment processing options to both consumers and merchants.  Outside of Payments Pro, though, users must have a PayPal account before they can do much of anything with the platform.

Like anything else, this process involves a registration form where one provides all of the information necessary to create a new PayPal account.  PayPal has done an excellent job of providing plenty of resources to accomplish this task, but according to the Google AdWords Keyword Finder Tool there are millions of people searching for “how do I get PayPal” or “what is PayPal” every single month.  This evidence shows that there is still quite a bit of confusion out there surrounding the payment system we’ve all grown to love.

Since the release of the Adaptive API’s PayPal has opened up the ability for developers to integrate this process of creating accounts and preparing to use PayPal into their own applications.  Similar to Express Checkout, Adaptive Payments, and Permissions, the Adaptive Accounts API allows us to gather everything we need from the user in our own creative way.  We can then simply redirect the user over to PayPal to create their password and accept the PayPal user agreement, at which point they’ll be returned back to the application.

In this article I’ll walk you through API’s that allow you to complete each of the main steps necessary for a user to get up-and-running smoothly with PayPal.

• Create an account.
• Add a bank account for verification.
• Add a credit card for address confirmation.

As usual, I’ll be using my PHP class library for PayPal in these examples, so it will be helpful if you’re familiar with that, but it’s not required to follow along.

CreateAccount API

The first thing we’ll cover is creating a new PayPal account using the CreateAccount API.  I’ll leave the creativity and user input design up to you so we can get straight to the technical guts of this thing.

There are lots of optional request parameters we can use when creating new accounts via web services.  For a basic, personal account you might only include the user’s name and address information.  With a business account, though, you’ll provide additional information about the business itself, and you can even go as far as providing details about individual stakeholders within the business.

Let’s take a look at some sample code for CreateAccount using the PHP library.

<?php
// Include required library files.
require_once('../includes/config.php');
require_once('../includes/paypal.class.php');

// Create PayPal object.
$PayPalConfig = array(
	'Sandbox' => $sandbox,
	'DeveloperAccountEmail' => $developer_account_email,
	'ApplicationID' => $application_id,
	'DeviceID' => '',
	'IPAddress' => $_SERVER['REMOTE_ADDR'],
	'APIUsername' => $api_username,
	'APIPassword' => $api_password,
	'APISignature' => $api_signature,
	'APISubject' => $api_subject
);

$PayPal = new PayPal_Adaptive($PayPalConfig);

// Prepare request arrays
$CreateAccountFields = array(
	'AccountType' => 'Premier', // Required. The type of account to be created. Personal or Premier
	'CitizenshipCountryCode' => 'US', // Required. The code of the country to be associated with the business account. This field does not apply to personal or premier accounts.
	'ContactPhoneNumber' => '555-555-5555', // Required. The phone number associated with the new account.
	'HomePhoneNumber' => '555-555-5555', // Home phone number associated with the account.
	'MobilePhoneNumber' => '555-555-4444', // Mobile phone number associated with the account.
	'ReturnURL' => $domain.'return.php', // Required. URL to redirect the user to after leaving PayPal pages.
	'ShowAddCreditCard' => 'true', // Whether or not to show the Add Credit Card option. Values: true/false
	'ShowMobileConfirm' => '', // Whether or not to show the mobile confirmation option. Values: true/false
	'ReturnURLDescription' => 'Home Page', // A description of the Return URL.
	'UseMiniBrowser' => 'false', // Whether or not to use the minibrowser flow. Values: true/false Note: If you specify true here, do not specify values for ReturnURL or ReturnURLDescription
	'CurrencyCode' => 'USD', // Required. Currency code associated with the new account.
	'DateOfBirth' => '1982-04-09Z', // Date of birth of the account holder. YYYY-MM-DDZ format. For example, 1970-01-01Z
	'EmailAddress' => 'sandbox2@angelleye.com', // Required. Email address.
	'Saluation' => '', // A saluation for the account holder.
	'FirstName' => 'Tester', // Required. First name of the account holder.
	'MiddleName' => '', // Middle name of the account holder.
	'LastName' => 'Testerson', // Required. Last name of the account holder.
	'Suffix' => '', // Suffix name for the account holder.
	'NotificationURL' => $domain.'paypal/ipn/ipn-listener.php', // URL for IPN
	'PreferredLanguageCode' => '', // Required. The code indicating the language to be associated with the new account.
	'RegistrationType' => 'Web', // Required. Whether the PayPal user will use a mobile device or the web to complete registration. This determins whether a key or a URL is returned for the redirect URL. Allowable values are: Web
	'SuppressWelcomeEmail' => '', // Whether or not to suppress the PayPal welcome email. Values: true/false
	'PerformExtraVettingOnThisAccount' => '', // Whether to subject the account to extra vetting by PayPal before the account can be used. Values: true/false
	'TaxID' => ''	// Tax ID equivalent to US SSN number. Note: Currently only supported in Brazil, which uses tax ID numbers such as CPF and CNPJ.
);

$Address = array(
	'Line1' => '1503 Main St.',
	'Line2' => '376',
	'City' => 'Kansas City',
	'State' => 'MO',
	'PostalCode' => '64111',
	'CountryCode' => 'US'
);

$BusinessAddress = array(
	'Line1' => '123 Test Ave.', 
	'Line2' => '',
	'City' => 'Grandview',
	'State' => 'MO',
	'PostalCode' => '64030',
	'CountryCode' => 'US'
);

$PrinciplePlaceOfBusinessAddress = array(
	'Line1' => '1503 Main St.',
	'Line2' => '376',
	'City' => 'Kansas City',
	'State' => 'MO',
	'PostalCode' => '64111',
	'CountryCode' => 'US'
);

$BusinessStakeHolder = array(
	'DateOfBirth' => '1982-04-09Z', //YYYY-MM-DDZ (ie. 1970-01-01Z)
	'FullLegalName' => 'Tester Testerson',
	'Salutation' => '', 
	'FirstName' => 'Tester', 
	'MiddleName' => '',
	'LastName' => 'Testerson',
	'Suffix' => '',
	'Role' => 'CHAIRMAN', 
	'CountryCode' => 'US'
);

$BusinessStakeHolderAddress = array(
	'Line1' => '1503 Main St.', // Required. Street address.
	'Line2' => '376', // Street address 2.
	'City' => 'Kansas City', // Required. City
	'State' => 'MO', // State or Province
	'PostalCode' => '64111', // Postal code
	'CountryCode' => 'US'	// Required. The country code.
);

$PayPalRequestData = array(
	'CreateAccountFields' => $CreateAccountFields,
	'Address' => $Address,
	'BusinessAddress' => $BusinessAddress,
	'PrinciplePlaceOfBusinessAddress' => $PrinciplePlaceOfBusinessAddress,
	'BusinessStakeHolder' => $BusinessStakeHolder,
	'BusinessStakeHolderAddress' => $BusinessStakeHolderAddress
);

// Pass data into class for processing with PayPal and load the response array into $PayPalResult
$PayPalResult = $PayPal->CreateAccount($PayPalRequestData);

header('Location: '.$PayPalResult['RedirectURL']);
?>

We can see the request parameters are split into separate sections the same way PayPal separates them in their documentation.

• CreateAccountFields – These are general fields that do not fit within any other specific group.
• Address – The user’s personal address should go here.
• BusinessAddress – The business address information goes here.
• PrinciplePlaceofBusinessAddress – In many cases, this would be the same as BusinessAddress.  If the user has a primary headquarters, though, that would be an example of something to use here.
• BusinessStakeHolder – This is the personal information of a stakeholder in the business that you are including with the account.
• BusinessStakeHolderAddress – The address of the business stakeholder that you’ve included.

If you study the parameters in each section you’ll find it’s all pretty straight forward.  The request is then passed through the library where it’s processed accordingly.  A return URL is provided in the library result which is used to send the user over to PayPal to complete the process, at which time they’ll be presented with the following screen.

Once the user has completed this process they will be returned back to the ReturnURL specified in the request and you can allow the user to complete a payment with their new account or proceed with further actions on the account.

AddBankAccount API

In order for a user to become verified with PayPal and have access to more features they must add a bank account to their newly created PayPal account.  This can be achieved through the PayPal.com website after signing in to the new account, or you can also tie this directly into your application using the AddBankAccount web service.  Here’s a sample of doing exactly that with our PHP library.

<?php
// Include required library files.
require_once('../includes/config.php');
require_once('../includes/paypal.class.php');

// Create PayPal object.
$PayPalConfig = array(
	'Sandbox' => $sandbox,
	'DeveloperAccountEmail' => $developer_account_email,
	'ApplicationID' => $application_id,
	'DeviceID' => '',
	'IPAddress' => $_SERVER['REMOTE_ADDR'],
	'APIUsername' => $api_username,
	'APIPassword' => $api_password,
	'APISignature' => $api_signature,
	'APISubject' => $api_subject
);

$PayPal = new PayPal_Adaptive($PayPalConfig);

// Prepare request arrays
$AddBankAccountFields = array(
	'AccountHolderDateOfBirth' => '', // The date of birth of the account holder. Format: YYYY-MM-DDZ (ie. 1970-01-01Z)
	'AccountID' => '', // The ID number of the PayPal account for which a bank account is added. You must specify either AccountID or EmailAddress for this request.
	'AgencyNumber' => '', // For the Brazil Agency Number
	'BankAccountNumber' => '23421341234', // The account number (BBAN) of the bank account to be added.
	'BankAccountType' => 'CHECKING', // The type of bank account to be added. Values are: CHECKING, SAVINGS, BUSINESS_SAVINGS, BUSINESS_CHECKING, NORMAL, UNKNOWN
	'BankCode' => '', // The code that identifies the bank where the account is held.
	'BankCountryCode' => 'US', // Required. The country code of the bank.
	'BankName' => 'Bank of America', // The name of the bank.
	'BankTransitNumber' => '', // The transit number of the bank.
	'BranchCode' => '', // The branch code for the bank.
	'BranchLocation' => '', // The branch location.
	'BSBNumber' => '', // The Bank/State/Branch number for the bank.
	'CLABE' => '', // CLABE represents the bank information for countries like Mexico.
	'ConfirmationType' => 'WEB', // Required. Whether PayPal account holders are redirected to PayPal.com to confirm the bank account addition.
	'ControlDigit' => '', // The control digits for the bank.
	'EmailAddress' => 'sandbo_1204199080_biz@angelleye.com', // The email address of the PayPal account holder. You must specify either AccountID or EmailAddress.
	'IBAN' => '', // The IBAN for the bank.
	'InstitutionNumber' => '', // The institution number for the bank.
	'PartnerInfo' => '', // The partner informatoin for the bank.
	'RibKey' => '', // The RIB Key for the bank
	'RoutingNumber' => '101000010', // The bank's routing number.
	'SortCode' => '', // The branch sort code.
	'TaxIDType' => '', // Tax ID type of CNPJ or CPF, only supported for Brazil
	'TaxIDNumber' => '' // Tax ID number for Brazil
);

$WebOptions = array(
	'CancelURL' => $domain.'cancel.php', // The URL to which the user is returned when they cancel the flow at PayPal.com
	'CancelURLDescription' => 'Angell EYE Demo', // A description for the CancelURL
	'ReturnURL' => $domain.'return.php', // The URL to which the user is returned when they complete the process.
	'ReturnURLDescription' => 'Angell EYE Demo' // A description for the ReturnURL
);

$PayPalRequestData = array(
	'AddBankAccountFields' => $AddBankAccountFields,
	'WebOptions' => $WebOptions
);

// Pass data into class for processing with PayPal and load the response array into $PayPalResult
$PayPalResult = $PayPal->AddBankAccount($PayPalRequestData);

header('Location: '.$PayPalResult['RedirectURL']);
?>

Once again, the request is split up into different sections based on the way PayPal separates them in their documentation.

• AddBankAccountFields – General fields not specific to any other section.
• WebOptions – Placeholders for the Return URL and Cancel URL that the user should be returned to under each circumstance.

All of the request parameters are then passed into the library and we simply redirect the user to the returned URL where they will sign in to their PayPal account and see the following screen.

Upon reviewing the information and clicking the Continue button the user will be presented with this next screen.

This informs the user of the verification process and provides a link to return your application.

AddPaymentCard API

The final step in creating a new account and preparing it for use is adding a credit card to the account.  This allows PayPal to confirm that the address the user has on file matches the billing address of the credit card on file.  If it matches, the risk involved with shipping items to this address goes down drastically, and sellers are better protected.

Once again, this can be done via the PayPal.com account interface or directly from the application using the API.  The exact same procedure will be used, but this time we’ll use the AddPaymentCard web service.  Here’s a sample of that.

<?php
// Include required library files.
require_once('../includes/config.php');
require_once('../includes/paypal.class.php');

// Create PayPal object.
$PayPalConfig = array(
	'Sandbox' => $sandbox,
	'DeveloperAccountEmail' => $developer_account_email,
	'ApplicationID' => $application_id,
	'DeviceID' => '',
	'IPAddress' => $_SERVER['REMOTE_ADDR'],
	'APIUsername' => $api_username,
	'APIPassword' => $api_password,
	'APISignature' => $api_signature,
	'APISubject' => $api_subject
);

$PayPal = new PayPal_Adaptive($PayPalConfig);

// Prepare request arrays
$AddPaymentCardFields = array(
	'AccountID' => '', // The ID number of the PayPal account for which the payment card is being added. You must specify either AccountID or EmailAdddress
	'CardNumber' => '4356803931287360', // Required. The credit card number.
	'CardOwnerDateOfBirth' => '', // The date of birth of the card holder.
	'CardType' => 'Visa', // Required. The type of card being added. Values are: Visa, MasterCard, AmericanExpress, Discover, SwitchMaestro, Solo, CarteAurore, CarteBleue, Cofinoga, 4etoiles, CarteAura, TarjetaAurora, JCB
	'CardVerificationNumber' => '', // The verification code for the card. Generally required for calls where ConfirmationType is set to NONE. With the appropriate account review, this param is optional.
	'ConfirmationType' => 'WEB', // Required. Whether the account holder is redirected to PayPal.com to confirm the card addition. Values are: WEB, NONE
	'CreateAccountKey' => '', // The key returned in a CreateAccount response. Required for calls where the ConfirmationType is NONE.
	'EmailAddress' => 'sandbo_1204199080_biz@angelleye.com', // Email address of the account holder adding the card. Must specify either AccountID or EmailAddress.
	'IssueNumber' => '', // The 2-digit issue number for Switch, Maestro, and Solo cards.
	'StartDate' => '' // The element containing the start date for the payment card.
);

$NameOnCard = array(
	'Salutation' => '', // A salutation for the card owner.
	'FirstName' => 'Tester', // Required. First name of the card holder.
	'MiddleName' => '', // Middle name of the card holder.
	'LastName' => 'Testerson', // Required. Last name of the card holder.
	'Suffix' => '' // A suffix for the card holder.
);

$BillingAddress = array(
	'Line1' => '123 Test Ave.', // Required. Billing street address.
	'Line2' => '', // Billing street address 2
	'City' => 'Grandview', // Required. Billing city.
	'State' => 'MO', // Billing state.
	'PostalCode' => '64030', // Billing postal code
	'CountryCode' => 'US' // Required. Billing country code.
);

$ExpirationDate = array(
	'Month' => '12', // Expiration month.
	'Year' => '2015' // Required. Expiration Year.
);

$WebOptions = array(
	'CancelURL' => $domain.'cancel.php', // The URL to which the user is returned when they cancel the flow at PayPal.com
	'CancelURLDescription' => 'Cancel and return to Angell EYE Demo.', // A description for the CancelURL
	'ReturnURL' => $domain.'return.php', // The URL to which the user is returned when they complete the process.
	'ReturnURLDescription' => 'Return to Angell EYE Demo.' // A description for the ReturnURL
);

$PayPalRequestData = array(
	'AddPaymentCardFields' => $AddPaymentCardFields,
	'NameOnCard' => $NameOnCard,
	'BillingAddress' => $BillingAddress,
	'ExpirationDate' => $ExpirationDate,
	'WebOptions' => $WebOptions
);

// Pass data into class for processing with PayPal and load the response array into $PayPalResult
$PayPalResult = $PayPal->AddPaymentCard($PayPalRequestData);

header('Location: '.$PayPalResult['RedirectURL']);
?>

Once again, our request parameters are split up based on the PayPal documentation just to keep things in order.

• AddPaymentCardFields – General fields that do not fit under any other group.
• NameOnCard – The name of the person associated with the credit card.
• BillingAddress – The address on file with the credit card company.
• ExpirationDate – The expiration date of the credit card.
• WebOptions – Information about where to return the user should they cancel or complete the process.

Just like with CreateAccount and AddBankAccount we’ll simply redirect the user over to PayPal using the returned URL.  Once they sign in they’ll be presented with the following screen.

Upon clicking the Add Card button, they will see the following screen.

Here, they can continue within their PayPal account or they can click the link to return to your application.

Conclusion

Once these steps have each been completed the user will be ready to send and receive payments on the PayPal platform without running into any limitations due to a non-verified or un-confirmed account.

The ability to handle each task from directly within your application allows you to streamline this process and make it as simple as possible on the end user.

You may download the stand-alone PHP library and you may also download the specific samples used within the article in order to study everything a little bit more closely and get started on your own.

Have fun, and happy coding!