Many products, many APIs
With their inconsistent information (and user experience) all over their dozens of different domains, PayPal miserably fails to deliver a clear message to developers.
is a nice attempt (by PayPal) to consolidate some typical use cases so you can decide better which product is suitable for you, but you might get lost without some basic understanding of terms like “Express Checkout”, “Adaptive Payments”, “Classic APIs” etc.
And so we try to shed some light on the general usage of PayPal’s products and APIs. Leave a comment and we’ll consider elaborating on other stuff as well. This document is still in the process of writing. Feel free to comment with feedback and suggestions.
PayPal NVP (Name-Value Pair) API
PayPal exist for many years, so they host a few families of APIs you can use. The newest are their REST APIs. In this section however we focus on the NVP API, which is considered as one of their “Classic APIs”.
The “Name-Value” simply means that we’re passing information using the format “NAME=value”, for example
Our page will send such a formatted request to the PayPal API Server
, which will return a response:
There’s a specific way to build the request. For example, you need to specify the
(the required API operation
to perform), and you need to provide some API Credentials
: Either a signature or a certificate (but not both). For example, the “signature” option is merely some “
” (together with the
as well as other request-specific details. The response is also formatted in a specified way, and both response and request should be UTF-8-encoded. But it may help to first understand the types of requests (“API operation”
s) you can make, so read on! (and later feel free to dwell into the boring details in the original documentation
Note: Some of the features, like Express Checkout
, require your process to perform multiple operations in order to complete. For example, first call
, as illustrated here:
The API operations
are divided in the documentation
into 6 categories:
- Adaptive Accounts: Create PayPal accounts and handle account management. Example requests:
- Adaptive Payments: Manage payments, payment preapprovals, and refunds. Example requests:
- Button Manager: Manage your buttons!
BMGetButtonDetails, … See also the image reference here.
- Merchant APIs: Some useful operations here! E.g.
RequestPermissions, … Handle permissions associated with an access token, e.g. to execute operations on behalf of the buyer.
The typical use case: When you want to allow one-time payment (as opposed to recurring payments), for example to support shopping carts on your site. The buyer clicks a button at your site, redirected to PayPal to fill in some payment details and confirm, and then redirected back to your site. You must have a PayPal merchant account
to allow this.
Below is a summary of the getting started guide
- The typical checkout flow, without Express Checkout, is the following:
- The payor (buyer) clicks the checkout button in his shopping cart page,
- Provide shipping info,
- Select payment method,
- Review summary for approval,
- Sees a confirmation of the transaction.
- The “Express Checkout” way skips the “shipping info” and “payment method” steps. The image below neatly summarizes the process together with the 3 API calls your applications needs to make:
The relevant API for working with Express Checkout
A good and detailed documentation about actually implementing it is here
For the more serious applications that want full control on the process: To host the checkout pages, manage security for sales and authorizations. You need an “Internet Merchant Account” for that (which is a different thing from being simply a “merchant”, i.e. there’s a special application form you have to fill and it gets processed within a few days).
Quoting the documentation
Payflow is secure, open payment gateway. It is available in two versions: Payflow Link, which requires the use of hosted payment pages, and Payflow Pro, which gives merchants total control over the payment process. Payflow allows merchants to choose any Internet Merchant Account to accept debit or credit card payments and connect to any major processor. It also lets merchants accept PayPal and Bill Me Later payments.
PayPal Payments Pro (Direct Integration), Website Payments Pro
Enables merchants and developers to accept credit cards, debit cards, and PayPal payments directly on their website. PayPal Payments Pro also includes Express Checkout and Virtual Terminal. Add-on services like Recurring Billing are also available.
recurring payment profile
: Every time someone is charged in a recurring manner (subscription), in PayPal terms this means she has a recurring payment profile. This “profile” instance includes all the payments details and is maintained at PayPal’s side.