Our integration topics for accepting and making payments contain the information you need to complete those specific tasks. This section contains items you should consider as you build out your complete PayPal integration.
- Design guidelines
- Error handling
- Rate limits
- Domains and IP addresses
- Policies and compliance
- Next steps
To create an optimal payment experience, make sure that your integration meets our design guidelines.
Determine if and how you want to use webhook notifications. Most PayPal REST API calls trigger a webhook notification, and you can create server-side code to listen for and respond to these notifications. In some cases, responding to webhook notifications can save you resources as you'll receive the notification rather than having to send requests to the PayPal servers for information.
Your REST API integration might encounter errors that you need to handle.
4XXerror codes - These indicate something is wrong with the request. Correct the error described in the message and retry the call.
5XXerror codes - These indicate a network or services issue. Requests that return a
5XXerror code might have created a PayPal transaction, but an order ID or other positive feedback won't be returned in the response. To account for this type of issue, use the
PayPal-Request-Idheader in requests that create transactions. This header makes the request idempotent and you can safely retry the request without duplicating the action.
PayPal’s primary focus is site availability and security in support of merchants.
While we do not publish a rate limiting policy, we might temporarily rate limit if we identify traffic that appears to be abusive. We rate limit until we are confident that the activity is not problematic for PayPal, merchants, or customers.
To ensure maximum protection for the site, we constantly evaluate traffic as it surges and subsides to adjust our policies. If you or your customers receive the HTTP
429 Unprocessable Entity - RATE_LIMIT_REACHED status code, which indicates too many requests and might indicate anomalous traffic, we rate limit to ensure site stability.
If this policy negatively affects your integration, contact Merchant Technical Support.
Some tips to avoid rate limiting:
- Do not poll; use webhooks instead.
- Rather than generate an OAuth 2.0 access token for each transaction, cache tokens. See OAuth 2.0 authorization protocol.
When you make API calls, use Domain Name Service (DNS) results with the default Time To Live (TTL) values, to determine the IP addresses of our servers.
- Make sure you always ship to an address entered and confirmed in the Checkout flow to preserve that requirement of PayPal Seller Protection.
- If you accept payments in Europe, make sure you follow the authentication requirements outlined by PSD2.
Test and go live — After you've completed your coding tasks and considered the information on this page, you can test your integration and go live with your code.