PayPal API Essential Guide

Aug 2, 2024 • 6 minute read

What type of API does PayPal provide?

PayPal offers a REST API for developers to integrate PayPal payments and other functionality into their applications.

Type of API

PayPal uses a REST (Representational State Transfer) API.

Key Characteristics

Uses REST architectural style
Authenticates with OAuth 2.0 access tokens
Returns HTTP response codes
Responses are encoded in JSON format

Authentication

Requires a client ID and client secret to authenticate API calls
Client ID and secret are exchanged for an OAuth 2.0 access token
Access token is used to authenticate subsequent API requests

API Documentation

Comprehensive API reference documentation available
Includes OpenAPI specifications
Code generation tools available for API clients

Does the PayPal API have webhooks?

Yes, the official PayPal API does have webhooks. Here are the key points about PayPal webhooks:

Webhook Support

PayPal's REST API supports webhooks for receiving notifications about events related to PayPal transactions and resources.
Webhooks allow your application to receive real-time notifications from PayPal when specific events occur, rather than having to poll for updates.

Event Types

You can subscribe to various types of webhook events, including:

Payment events (e.g. PAYMENT.SALE.COMPLETED, PAYMENT.CAPTURE.COMPLETED)
Billing agreement events (e.g. BILLING.SUBSCRIPTION.CREATED, BILLING.SUBSCRIPTION.CANCELLED)
Dispute events
Payout events
And many more

Key Points

To use webhooks, you need to create a webhook listener URL in your application that can receive POST requests from PayPal.
You then configure the webhook in your PayPal developer account, specifying the listener URL and which event types you want to subscribe to.
When an event occurs, PayPal will send a POST request to your listener URL with details about the event.
It's important to verify the authenticity of received webhook messages to ensure they are actually from PayPal.

Best Practices

Use HTTPS for your webhook listener URL for security.
Implement proper error handling and retries in your webhook listener.
Store and process webhook data asynchronously to avoid timeouts.
Test thoroughly using PayPal's sandbox environment before going live.

In summary, PayPal's REST API provides robust webhook support, allowing you to receive notifications for a wide variety of events related to payments, subscriptions, disputes, and more. This enables real-time updates and automation in your application based on PayPal transaction activity.

Rate Limits and other limitations

Here are the key points about PayPal API rate limits based on the search results:

Rate Limit Policy

PayPal does not publish a specific rate limiting policy.
They may temporarily rate limit if they identify traffic that appears to be abusive.
Rate limiting is done to ensure site stability and security.

Rate Limit Indicators

If you receive an HTTP 429 "RATE_LIMIT_REACHED" error, it means too many requests were sent in a short time period.
This may indicate anomalous traffic, triggering rate limiting.

Known Limits

The rate limit for Payouts API POST calls is 400.
One user reported hitting rate limits after about 100 requests in 1 minute from the same IP address.

Tips to Avoid Rate Limiting

Use webhooks or IPN instead of polling.
Cache OAuth 2.0 access tokens rather than generating a new one for each request.
Spread out requests over time rather than sending many at once.

What to Do if Rate Limited

If rate limiting negatively impacts your integration, contact PayPal Merchant Technical Support.
There may be a "cooling period" of several minutes before requests are allowed again.

Key Takeaways

PayPal does not publish exact rate limits, but does employ rate limiting.
Use best practices like webhooks and token caching to reduce API calls.
Spread out requests over time to avoid hitting limits.
Contact PayPal support if rate limiting causes issues for your integration.

While specific limits are not published, following these guidelines should help avoid most rate limiting issues with the PayPal API. The dynamic nature of their rate limiting means exact numbers are not available, but the tips provided can help optimize API usage.

Latest API Version

Based on the search results provided, here is the most up-to-date information about the PayPal API version:

The most recent version of the PayPal API is 106.0.

Key points to consider:

PayPal has moved away from using small version numbers like 2.3 to using larger version numbers like 65, 68, 81, 82, 83, etc.
The integration wizard that generates code for version 2.3 is outdated.
You can find the latest available API version by checking the WSDL at https://www.paypalobjects.com/wsdl/PayPalSvc.wsdl and looking at the ns:version.
New API versions may introduce new functionality, but core functionality generally remains the same across versions.
Older versions of the API may lack newer features like parallel payments, support for digital goods, and line item details.

It's worth noting that while an answer from 2014 stated the version was 114.0, the more recent information from the accepted answer indicates 106.0 is the current latest version. To get the most up-to-date version number, it's best to check the WSDL directly as mentioned above.

When integrating with PayPal, it's generally recommended to use the latest stable version of the API to ensure access to all current features and security updates. However, if you're using an older version that meets all your needs, it may not be necessary to update unless you require newer functionality.

How to get a PayPal developer account and API Keys?

Here's how to get a developer account for PayPal to create an API integration:

Create a PayPal Business account

To get started with PayPal's APIs, you first need to create a PayPal Business account if you don't already have one. This can be done on the PayPal website.

Once you have a Business account, go to the PayPal Developer Portal (developer.paypal.com) and sign in using your PayPal Business account credentials.

Get API credentials

To create an API integration, you'll need to get API credentials:

On the Developer Portal, go to "My Apps & Credentials"
Click "Create App" to generate a new set of API credentials
You'll receive a Client ID and Secret, which are used to authenticate API calls

Set up Sandbox accounts

PayPal provides a Sandbox environment for testing:

Go to "Accounts" in the Developer Portal
You'll see preconfigured Sandbox accounts for testing
You can create additional Sandbox accounts as needed

Choose APIs and get access token

Decide which PayPal APIs you want to use (e.g. Payments, Subscriptions, etc.)
Use your Client ID and Secret to get an access token for making API calls

What can you do with the PayPal API?

Based on the information provided in the search results, here's a list of data models you can interact with using the PayPal API, along with what is possible for each:

Orders

Create, update, and manage orders for payments
Capture payments for orders
Authorize payments for orders
Show order details

Payments

Process payments
Refund payments
Authorize and capture payments
View payment details

Invoicing

Create, send, and manage invoices
Update invoice status
Search for invoices

Catalog Products

Create and manage product catalogs
Add, update, and delete products

Disputes

Manage customer disputes
Read buyer and seller dispute information
Update seller dispute information

Subscriptions

Create and manage recurring payment plans
Update subscription status
Process subscription payments

Payouts

Send batch and single payouts
Check payout status

Identity

Retrieve user information (with user consent)
Authenticate users using PayPal credentials

Payment Method Tokens

Create and manage payment method tokens for future use

Transaction Search

Search for transactions
Retrieve transaction details

Webhooks

Set up and manage webhooks for real-time notifications
Receive event notifications for various PayPal activities

Payment Experience

Customize checkout flow and appearance

Partner Referrals

Manage partner referral programs

Add Tracking

Add tracking information to transactions

Referenced Payouts

Process payouts referencing previous transactions

Vault

Store and manage credit card information securely

Each of these data models allows for various operations such as creating, reading, updating, and deleting (CRUD) the respective entities, as well as performing specific actions related to each model. The exact capabilities may vary depending on the specific API endpoints and your integration needs.