Tim Messerschmidt
February 27th 2014
Version 0.4
- Introduction
- Express Checkout
- Adaptive Payments
- PayPal Button
- REST API
- Mobile Payments
- Log In with PayPal
This guide shall provide a brief overview over the different PayPal products that allow to process payments in (web-)applications. It will be updated over time to allow a quickstart using our products.
Please always make sure to check with the documentation as this guide doesn't try to be complete.
Express Checkout is the most famous and most important PayPal API so far. It allows for one time purchases, subscriptions, billing agreements and parallel payments. When accessing Express Checkout on mobile provides a mobile flow which we call Mobile Express Checkout (MEC). MEC can be used in combination with WebViews in native mobile applications to implement PayPal payments.
Traditional eCommerce one time purchases get implemented by utilizing 3 simple API calls:
- SetExpressCheckout
- creates the payment itself
- redirects the user to PayPal's login page to authenticate
- (Optional) GetExpressCheckoutDetails
- allows to get user details before the actual pamyent happens
- DoExpressCheckoutPayment
- this API call actually executes the created & authenticated payment using a token
Shortcut is a way of implementing PayPal Express Checkout that allows skipping the actual registration process at the merchant's page and provides a callback that provides user details after the checkout itself. This is an amazing feature that provides great conversion rates as the user is not require to enter tons of details while the merchant still is able to access needed information like the customer's name, shipping address and Email.
Creating billing agreements using Reference Transaction requires a special permission that must be obtained during the onboarding process with PayPal or through PayPal's Merchant Technical Service. MTS is also able to enable this feature for our test environment called Sandbox.
The flow is pretty easy and powerful as it allows to create One Click Payment experiences.
- SetExpressCheckout
- define the amount as 0 as we don't create a particular payment yet
- CreateBillingAgreement
- this returns a billing agreement id that will be used for future transactions
- DoReferenceTransaction
- provide the billing agreement id that was obtained via CreateBillingAgreement
- BAUpdate
- set
BillingAgreementStatus
toCanceled
- set
This is pretty similar to a regular Express Checkout call except this time you'll be able to define multiple Payment Requests with multiple Receivers:
- SetExpressCheckout
- details for multiple payments here
- (Optional) GetExpressCheckoutDetails
- DoExpressCheckoutPayment
- please see the �DoExpressCheckoutPayment for details about defining multiple Payments
Express Checkout allows to create subscriptions via creating a so called recurring payments profile. The flow is relatively similar to Reference Transactions but this time you'll need to define an amount.
PayPal allows to create up to 10 different recurring payments with just one API call. Each of these recurring payments need an assigned recurring payments profile that needs to be created seperately:
- SetExpressCheckout
- set the field
L_BILLINGTYPEn
for each of n (0 up to 9) toRecurringPayments
- set
L_BILLINGAGREEMENTDESCRIPTIONn
(n being 0 up to 9) to your subscription's description - set
PAYMENTREQUEST_0_AMT
to0
if there is no associated purchase - your amount otherwise.
- set the field
- (Optional) GetExpressCheckoutDetails
- allows to get some user details if needed
- CreateRecurringPaymentsProfile
- this is where you define how often you want to charge the user (daily, weekly, monthly, annual), how much and if it's a digital or physical good.
Please check out the documentation for further details.
Adaptive Payments is PayPal's number one API when it comes to marketplaces. Next to regular 1:1 payments (Simple Payments) it allows to create Parallel Payments (1:n - n being maximum 6 receivers) and Chained Payments (1:1:n - n being max. 5).
Payments can be delayed up to 90 days in order to allow working with the received money. Furthermore payments may be preauthorized and executed later - this is handy for scenarios like pay at delivery.
Payments being made with Adaptive Payments are NOT mobile optimized. We strongly encoure using our Mobile SDKs for this.
The developer can define who pays the PayPal's fee. The 4 different setups are:
- Sender (customer) pays the fee
- Receiver pays the fee in a Parallel Payment
- Each receiver pays a part of the fee in a Chained Payment
- Primary receiver pays the fee in a Chained Payment
More information regarding fees can be found in the documentation.
In case you want to build a crowdfunding platform this guide might come in handy: Crowdfunding Application Guidelines.
Adaptive Payments used to be the base for PayPal's Mobile Payments Library and still powers the PayPal payments in the new PayPal Mobile SDK for Android and �iOS.
The most basic usage of Adaptive Payments is creating a Simple Payment between a sender (your user) and a receiver (that doesn't have to be you):
- Pay
- (Optional) PaymentDetails
You will need to pass a list of receivers with only one receiver specified as documented here.
In the Pay and ExecutePayment call a list of receivers needs to be provided as following:
- Pay
- set
receiverList.receiver(0).amount=first_amount
,receiverList.receiver(0).email=first_receiver_email
and the other attributes - same applies to the other (up to 5 additional) receivers
- set
- (Optional) PaymentDetails
More details over here.
Chained payments are similar to parallel payments except this time one receivers needs to be declared as primary receiver which will declare all other receivers as secondary receivers.
- Pay
- (Optional) PaymentDetails
Chained Payments can be delayed in order to allow the primary receiver to keep the money for up to 90 days.
- Pay
- (Optional) PaymentDetails
- ExecutePayment
The documentation provides a step-by-step guide that helps implementing this.
Preapproved payments can be created up to a total amount and a number of transactions and executed afterwards. The parameters specifying these limitations are:
maxAmountPerPayment
maxNumberOfPayments
maxTotalAmountOfAllPayments
startingDate
endingDate
Instead of providing the payment command the preapproval command must be specified when redirecting to PayPal:
_ap-payment
changes to _ap-preapproval
as documented in the APCommands.
- Preapproval
- response will contain a preapproval key
- Redirect the user to:
.../cgi-bin/webscr?cmd=_ap-preapproval&preapprovalkey=yourKey
- (Optional) PreapprovalDetails
- allows to query for details for the specified preapproval
- Pay
- include the preapproval key that was obtained earlier
A complete guide on implementing Payment Preapproval can be found here.
WPS is the traditional way to create a frontend PayPal implementation using HTML forms. The main functionality is allowing one time purchases marked as Buy now or Donate button and subscriptions.
The new JavaScript Buttons started in 2013 and add a layer on top of WPS that allows a much faster integration of the PayPal button. On top of the regular Buy now button and Subscriptions a QRCode button got implemented that allows to complete the checkout process using a smartphone.
The new REST API got launched at SXSW in March 2013 and aims for a great developer experience using modern standards like a REST interface, OAuth 2.0 for user authentication and JSON as data format.
The API allows to process credit cards directly via an API call (which we call DCC - Direct Credit Card) if the merchant is �PCI compliant. On top of that a feature called vault allows to store credit card and receive them tokenized.
Also so called EC payments using PayPal accounts is being supported. This is the regular PayPal flow that requires users to log in with their PayPal username and password to confirm the payment.
There are SDKs for most modern (web-)languages like Ruby, Node.js, Python, PHP, .NET and Java. All documentation for these SDKs can be found in the REST API Reference.
In case you're missing your favourite language: There are cURL samples that help you creating your own wrapper.
The REST API is using HATEOAS (Hypermedia as the Engine of Application State) which basically means: our API is smart and will tell you what to do next with the result of your request. This allows avoiding hardcoded API endpoints and is pure awesome ;-).
The flow is pretty similar to the Express Checkout API:
- Create a payment:
POST payments/payment
- redirect the user to PayPal and get his approval
- Execute the authorized payment:
POST payments/payment/{id}/execute
For direct processing of credit cards it's even easier:
- Create the payment:
POST payments/payment
- provide the credit card details as funding instrument or use a tokenized credit card
The vault API is a comfortable solution that returns a tokenized credit card instead of forcing the developer to provide all credit card details for each payment API call. Basically the API has 3 functionalities: storing a card, deleting a card and returnign all stored cards.
- Store the card:
POST vault/credit-card
- Look up a card:
GET vault/credit-card/{credit-card-id}
- Delete a card:
DELETE vault/credit-card/{credit-card-id}
This mechanism allows to put a hold on somebody's credit card or PayPal account and charge later. The final amount that is being charged in the capture call doesn't have to be as high as the preauthorized amount (captured <= preauthorized
).
- Create an authorization
POST payments/payment
- the intent must be
authorize
instead ofsale
- the intent must be
- Capture the preauthorized payment
POST payments/authorization/{authorization_id}/capture
- pass the
authorization_id
that was obtained in the first call - if not charging the total amount & not planning to charge the left amount: set
is_final_capture
totrue
- pass the
You can look up existing authorizations. This returns useful information like the amount, current state and how long the authorization is valid:
GET payments/authorization/{id}
- The id was passed as response after creating the authorization
Also you're able to void the authorization if you're not going to capture it:
- Void the authorization:
POST /payments/authorization/{authorization_id}/void
- Again you'll need to pass the id that was passed when creating the authorization
When charging against a PayPal account you can reauthorize the authorization. This should be done after the initial 3-day honor period. You can reauthorize once between 4 and 29 days. The reauthorized payment can be either 115% or up to 75$ higher than the original amount (whatever applies first).
- Reauthorize an existant authorization:
POST payments/authorization/{authorization_id}/reauthorize
A secret and id that identify your client against our server can be obtained in the Applications section of our Developer Portal.
As stated in the Express Checkout part PayPal Payments can be received via the Mobile Express Checkout. In case you're looking for a native integration the best way to do so is using the Mobile SDKs for Android and iOS. In countries that are not supported by the new SDK yet or if additional features are needed the Mobile Payments Library is helpful.
The Mobile SDK for iOS got released in March 2013 and the Android library in May 2013. It allows for accepting both PayPal payments and credit card payments (without requiring PCI compliance).
The credit card flow can be either supercharged with credit card scannign via card.io or entering the card's details manually.
On February 24th version 2 of the mSDK got released and brought support for Future Payments and Authorizations. Authorizations are working exactly like described under the REST section of this guide. Future Payments is a feature that enables repeating payments without requiring the user to authorize a payment via logging in.
The newest versions of the SDK and sample apps can be found at GitHub: iOS & Android
The Mobile Payments Library allows payments based on Adaptive Payments and is ideal for marketplaces and P2P (peer to peer) applications. There is a version for Android and iOS but we don't plan to release additional feature updates.
This API launched in 2011 an is known as PayPal Access. Access used OAuth 1.0a and OpenID to allow authenticating users via their existing PayPal accounts. Furthermore some profile information like the main shipping address and date of birth can be obtained in order to provide a nice onboarding experience for users.
In April 2013 Access got was relaunched as Log In with PayPal and enables a feature called Seamless Checkout which uses an obtained token that allows skipping logging again after using LIWPP. The seamless checkoht works with Express Checkout version 94+ and the new REST API. Instead of sticking with OAuth 1.0a LIWPP uses OpenID Connect which uses OAuth 2.0 for user authentication.
One of the greatest features that LIWPP enables is called Seamless Checkout. In a timeframe of 1 hour after the last login with PayPal a token can be used once to skip the authorization part of PayPal payments. This feature is available with Express Checkout version 94 and above and is documented over here.