Handling API responses when integrating with PayPal APIs

Correctly processing API responses ensures that your application can gracefully manage successful payments, declines, errors, and edge cases. This improves user experience, reduces failed transactions, and helps maintain compliance with PCI DSS, the security standards for handling credit card data.

This guide provides software developers with best practices, tools, and integration details for handling PayPal API responses. It includes tips for both back-end and front-end environments.

When integrating with PayPal, keep these principles in mind:

• Always check and handle API responses and errors to ensure a secure and reliable integration.
• Use PayPal's official SDKs and follow documented response handling patterns for server-side and client-side environments.
• Implement strong error handling, logging, and user feedback for all payment flows. Use PayPal's sandbox tools to test error scenarios.

Requirements and guidelines

• Check the HTTP status code and response body for every API call.
• Handle all possible error codes and messages.
• Log errors and unexpected responses for troubleshooting.
• Avoid exposing sensitive error details to users.
• Use PayPal's sandbox tools to simulate errors.
• Provide clear feedback to users for payment declines or failures.
• Follow PayPal's API Response Guidelines.

Response handling flow

This image shows the basic flow for handling API responses:

Understanding response types

PayPal API responses generally fall into two categories:

Successful responses

A successful response has a status code between 200 and 299 and includes the requested data:

{
  "id": "PAY-1234567890ABCDEF",
  "status": "COMPLETED", 
  "amount": {
    "currency": "USD",
    "value": "15.00"
  }
}

Error responses

Error responses have status codes outside the 200-299 range and include error details:

{
  "name": "VALIDATION_ERROR",
  "message": "Invalid request - see details",
  "debug_id": "9adb23571c146",
  "details": [
    {
      "field": "amount",
      "issue": "cannot be negative"
    }
  ]
}

HTTP status codes and error handling

The following table shows common HTTP status codes from PayPal APIs and what they mean:

For more details, see the Common errors page.

Tools, integrations, and features

How REST API responses work

PayPal APIs send back structured JSON answers when you make requests about payments, orders, and accounts. These answers include status codes, results, and error details. Always check the status code and read the full response to handle both successes and errors well. Learn more in the REST API responses guide.

Error handling

PayPal gives you specific error codes and messages to help you fix issues. By checking these codes and showing helpful messages to users, your app can guide people through problems and make payments easier.

Common PayPal API error codes

Here are the most common error codes you'll see and how to fix them:

These guides have more details about handling errors:

• Common errors
• Rest API errors
• Payflow transaction responses

Testing your error handling

PayPal offers tools to test how your app handles errors. These tools let you create test errors and declined payments without real problems. Use special headers and settings to test your error handling.

You can create specific test errors by adding a header to your test API requests:

PayPal-Mock-Response: {"mock_application_codes":"INSTRUMENT_DECLINED"}

This lets you test error handling without causing real errors.

Learn more about testing from these guides:

• Negative testing with request headers
• Sandbox error conditions

Handling card declines

When a card is declined or payment fails, your app needs to handle it smoothly. Your system should spot these issues and give users clear feedback and options to try again. This helps them understand what went wrong and how to fix it.

Learn more about handling payment problems:

• Card decline errors
• Handle funding failures

Integration

This section explains how to handle PayPal API responses and errors in both back-end and front-end environments.

Back-end

The back end handles secure tasks like creating payments, checking transactions, and storing API keys. It talks directly to PayPal's APIs, processes responses, handles errors, and keeps sensitive data safe.

Code examples in various programming languages show how to get access tokens and handle API responses securely. These examples show the right patterns to follow in your back-end code.

curl -X POST https://api-m.sandbox.paypal.com/v1/payments/payment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -d '{...}'

Front-end

The front end interacts with users, starts payments, and shows feedback based on API responses. Good response handling ensures users know the payment status, can retry if needed, and get clear guidance when something goes wrong.

Important: Never send your API keys or tokens from front-end code. The front-end should talk to your secure back end, which then talks to PayPal.

Code examples show how to handle responses and errors in various front-end frameworks. These examples help you create user-friendly payment flows.

// paypal.js
export async function createPayment() {
  const response = await fetch('https://api-m.sandbox.paypal.com/v1/payments/payment', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer ACCESS_TOKEN'
    },
    body: JSON.stringify({...})
  });
  const data = await response.json();
  if (response.status === 201) {
    alert('Payment created!');
  } else {
    alert('Error: ' + response.status);
  }
}

// index.html
<script type="module">
  import { createPayment } from './paypal.js';
  document.getElementById('pay-btn').addEventListener('click', createPayment);
</script>
<button id="pay-btn">Pay with PayPal</button>

Security testing tips

Testing your security setup is vital to protect against threats. Consider these key tests:

Auth testing

• Test with expired tokens to make sure your refresh system works.
• Try operations with limited permissions to test your access controls.
• Check that webhook security properly rejects unsigned events.

Data protection testing

• Make sure sensitive data isn't saved in your logs.
• Check that error messages don't show sensitive details to users.
• Test that front-end code never sees or handles secure data.

Integration security testing

• Use PayPal's testing tools to create security-related errors.
• Test with poor network conditions, like timeouts and drops.
• Check that your security settings meet PayPal's requirements.

For complete testing info, see the Testing your response handling guide.

Testing your response handling

Follow these steps to test how your app handles PayPal responses:

1. Set up test accounts:
   • Create test merchant and buyer accounts.
   • Save the test login details.
2. Test successful payments:
   • Complete a test payment.
   • Check that your code handles success correctly.
3. Test error scenarios:
   • Use PayPal's tools to create test errors.
   • Add special headers to trigger specific errors.
   • Example: PayPal-Mock-Response: {"mock_application_codes":"INSTRUMENT_DECLINED"}.
4. Test recovery flows:
   • Make sure users can recover from errors.
   • Check that error messages are clear.
   • Test that retry options work correctly.

Common problems and solutions

You might face these common issues:

Mobile app tips

When building mobile apps with PayPal:

• Use native SDKs when possible for a better user experience.
• Add extra error handling for spotty mobile connections.
• Plan for offline scenarios when the app loses connection.
• Add clear visual feedback during payment processing.

References

• Rest API responses
• Rest API overview
• Rest API requests
• Payflow transaction responses
• Negative testing with request headers
• Sandbox error conditions
• Card decline errors
• Handle funding failures