Develop

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.

On this page

Design guidelines

To create an optimal payment experience, make sure that your integration meets our design guidelines.

Webhooks

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.

See also

Webhooks

Error handling

Your REST API integration might encounter errors that you need to handle.

  • 4XX error codes - These indicate something is wrong with the request. Correct the error described in the message and retry the call.
  • 5XX error codes - These indicate a network or services issue. Requests that return a 5XX error 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-Id header in requests that create transactions. This header makes the request idempotent and you can safely retry the request without duplicating the action.

See also

Rate limits

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:

Domains and IP addresses

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.

Domains:

  • api.paypal.com
  • api.sandbox.paypal.com

Policies and compliance

  • 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.

Next steps

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.