Getting started overview

Integrating with the PayPal API involves several foundational steps to ensure secure and functional payment processing capabilities. This guide focuses on the essential actions required to move from initial account setup to making your first successful API call. The process includes creating a developer account, generating API credentials, and understanding the basic authentication flow.

PayPal's API ecosystem supports various payment methods, including credit/debit cards, PayPal balance, and alternative local payment options, enabling businesses to accept payments globally PayPal API documentation. Developers can integrate specific functionalities such as creating orders, processing payments, managing subscriptions, or issuing payouts PayPal REST API reference.

The following table provides a quick reference for the initial setup steps:

Step What to do Where
1. Create Developer Account Register for a PayPal Developer account. PayPal Developer Dashboard
2. Create Sandbox Accounts Set up personal and business Sandbox accounts for testing. PayPal Developer Dashboard
3. Create REST API App Generate API credentials (Client ID and Secret) for your application. My Apps & Credentials
4. Obtain Access Token Make an OAuth 2.0 request to get an access token. Your application's backend or a tool like Postman
5. Make First API Call Use the access token to call a basic API endpoint, e.g., create an order. Your application's backend or a tool like Postman

Create an account and get keys

To begin development with the PayPal API, you need a PayPal Developer account. This account provides access to the Developer Dashboard, where you can manage applications, generate API credentials, and create Sandbox testing accounts.

1. Sign up for a PayPal Developer Account

Navigate to the PayPal Developer website and sign up or log in using an existing PayPal account. If you don't have a PayPal account, you will be prompted to create one.

2. Create Sandbox Accounts

The PayPal Sandbox environment allows you to test your integration without processing live transactions. It is crucial for development and debugging. From your PayPal Developer Dashboard, create two types of Sandbox accounts:

  • Business Account: Simulates a merchant account, used to receive payments.
  • Personal Account: Simulates a buyer account, used to make payments.

These accounts come pre-populated with fictional balances and payment methods, allowing you to simulate various transaction scenarios.

3. Create a REST API App and Get Credentials

API credentials (Client ID and Client Secret) are essential for authenticating your application with PayPal's servers. These credentials are tied to a specific application and environment (Sandbox or Live).

  1. Go to the My Apps & Credentials section in your Developer Dashboard.
  2. Ensure the 'Sandbox' toggle is selected to work in the testing environment.
  3. Click the 'Create App' button.
  4. Provide an 'App Name' (e.g., "My First PayPal App").
  5. Select a 'Sandbox Business Account' to associate with this app.
  6. Click 'Create App'.

Upon creation, PayPal will display your Client ID and Secret for the Sandbox environment. The Client ID is publicly exposed, while the Client Secret must be kept confidential, similar to a password PayPal API Credentials Overview. You will use these credentials to obtain an access token for making API calls.

Your first request

After obtaining your Client ID and Secret, the next step is to make an authenticated API request. PayPal APIs use OAuth 2.0 for authentication. This involves exchanging your Client ID and Secret for an access token, which then authorizes subsequent API calls.

1. Obtain an Access Token

To get an access token, send a POST request to PayPal's OAuth 2.0 token endpoint. This request must include your Client ID and Secret, base64-encoded, in the Authorization header.

Sandbox Token Endpoint: https://api-m.sandbox.paypal.com/v1/oauth2/token

Request Details:

  • Method: POST
  • Headers:
    • Content-Type: application/x-www-form-urlencoded
    • Authorization: Basic <Base64-encoded Client ID:Secret>
  • Body: grant_type=client_credentials

Example using curl:

curl -v -X POST https://api-m.sandbox.paypal.com/v1/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic <Base64-encoded Client ID:Secret>" \
  -d "grant_type=client_credentials"

Replace <Base64-encoded Client ID:Secret> with the base64-encoded string of your actual Client ID and Secret, joined by a colon (e.g., base64(YOUR_CLIENT_ID:YOUR_SECRET)). You can use online tools or programming language functions to perform this encoding.

A successful response will return a JSON object containing your access_token, its token_type (which will be Bearer), and an expires_in value indicating its validity period.

{
  "scope": "https://api-m.paypal.com/v1/payments/.* https://api-m.paypal.com/v1/vault/.*",
  "access_token": "A21AAI_...",
  "token_type": "Bearer",
  "app_id": "APP-80W284485P519543T",
  "expires_in": 3600,
  "nonce": "2023-11-20T12:00:00Z"
}

2. Make a Simple API Call (e.g., Create an Order)

With your access token, you can now make calls to other PayPal API endpoints. A common first step is to create an order. This example uses the Orders API.

Sandbox Create Order Endpoint: https://api-m.sandbox.paypal.com/v2/checkout/orders

Request Details:

  • Method: POST
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer <Your_Access_Token>
  • Body: (JSON payload for the order)

Example using curl to create a simple order:

curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -d '{
    "intent": "CAPTURE",
    "purchase_units": [
      {
        "amount": {
          "currency_code": "USD",
          "value": "100.00"
        }
      }
    ]
  }'

Replace <YOUR_ACCESS_TOKEN> with the access token you received in the previous step.

A successful response will return a JSON object containing the order details, including an id for the created order and various links for actions like approving or capturing the payment.

{
  "id": "89Y460612W698144R",
  "status": "CREATED",
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/89Y460612W698144R",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://www.sandbox.paypal.com/checkoutnow?token=89Y460612W698144R",
      "rel": "approve",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/89Y460612W698144R/capture",
      "rel": "capture",
      "method": "POST"
    }
  ]
}

Common next steps

Once you've successfully made your first API call, consider these common next steps to further your PayPal integration:

  • Explore SDKs: PayPal provides official SDKs for Node.js, Python, Java, Ruby, .NET, and PHP PayPal SDKs overview. Using an SDK can simplify API interactions by handling authentication, request formatting, and response parsing.
  • Implement Webhooks: Set up webhooks to receive real-time notifications about events in your PayPal account, such as payment authorizations, captures, or disputes PayPal Webhooks documentation. This is crucial for building reactive applications.
  • Handle Payments Lifecycle: Understand the full payment flow, including authorizing payments, capturing funds, issuing refunds, and managing disputes.
  • Integrate PayPal Checkout: For a complete user experience, integrate the PayPal Checkout button on your website. This guides users through the PayPal payment flow and returns them to your site PayPal Checkout integration guide.
  • Move to Live: Once testing is complete, switch your application to use your live API credentials and endpoints. This involves creating a new REST API app in the 'Live' environment of your Developer Dashboard.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips:

  • Invalid Client ID or Secret: Double-check that you are using the correct Client ID and Secret for the Sandbox environment. Ensure they are base64-encoded correctly for the access token request.
  • Incorrect Authorization Header: Verify the Authorization header format. For token requests, it should be Basic <Base64-encoded Client ID:Secret>. For subsequent API calls, it should be Bearer <Access_Token>.
  • Expired Access Token: Access tokens have a limited lifespan (e.g., 3600 seconds). If your token has expired, you'll need to request a new one before making further API calls. Implement logic to refresh tokens automatically.
  • Incorrect Endpoint: Ensure you are using the correct Sandbox API endpoints (e.g., api-m.sandbox.paypal.com). Using live endpoints with Sandbox credentials (or vice-versa) will result in authentication failures.
  • Missing Content-Type Header: Many API calls require a specific Content-Type header, such as application/x-www-form-urlencoded for token requests or application/json for most REST API calls.
  • Firewall or Network Issues: If you are making calls from a restricted network, ensure that outbound connections to PayPal's API endpoints are not blocked.
  • Review Error Messages: PayPal API responses include detailed error messages. Carefully read the error_description or message fields in the JSON response to understand the specific issue. For example, a 401 Unauthorized typically points to authentication issues, while a 400 Bad Request might indicate an issue with the request body.
  • Consult Documentation: The PayPal API error codes documentation provides explanations for common errors and suggested resolutions.