# Get started with PayPal REST APIs
Source: https://docs.paypal.ai/developer/how-to/api/get-started



Current PayPal APIs use REST, authenticate with OAuth 2.0 access tokens, and return HTTP response codes and JSON responses. You can test US integrations with a <a href="https://developer.paypal.com/home/">PayPal Developer</a>  account.

To try these REST APIs without a PayPal Developer account, you can use Postman. Learn more about this in our <a href="https://developer.paypal.com/api/rest/postman">Postman guide</a>.

To explore PayPal's REST API descriptions, generate code for your API clients, and import OpenAPI documents into compatible third-party tools, see the <a href="https://github.com/paypal/paypal-rest-api-specifications">PayPal REST API specifications on GitHub</a>.

<br />

> **Important:** You need a <a href="https://www.paypal.com/business/open-business-account">PayPal Business account</a> to:<br />
>
> * Go live with integrations.<br />
> * Test integrations outside of the US.

<br />

## 1. Get your client ID and client secret

PayPal integrations use a client ID and client secret to authenticate API calls:

* A client ID identifies an app. You need a client ID to get a PayPal payment button and standard credit and debit card fields.

* A client secret authenticates a client ID. To call PayPal APIs, you exchange your client ID and client secret for an access token. Keep your client secret safe.

Here's how to get your client ID and client secret:

1. Select <a href="https://developer.paypal.com/dashboard/">Log in to Dashboard</a> and log in to your account or sign up for a new account.
2. Select **Apps & Credentials**.
3. New accounts come with a default application in the **REST API apps** section. To create a new project, select **Create App**.
4. Copy the client ID and client secret for your app.

<br />

## 2. Get an access token

You exchange your client ID and client secret for an access token, which you use for authentication when calling PayPal REST APIs.

You can call the PayPal OAuth API in any language. The following examples show you how to get your access token using cURL or Postman.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -v -X POST "https://api-m.sandbox.paypal.com/v1/oauth2/token" \
    -u "CLIENT_ID:CLIENT_SECRET" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=client_credentials" 
    ```
  </Tab>

  <Tab title="Postman">
    In the Postman app:

    1. Set the verb to **POST**.
    2. Enter [https://api-m.sandbox.paypal.com/v1/oauth2/token](https://api-m.sandbox.paypal.com/v1/oauth2/token) as the request URL.
    3. On the **Authorization** tab, set up authorization:
       1. For **TYPE**, select **Basic Auth**.
       2. In **Username**, enter your client ID.
       3. In **Password**, enter your client secret.
    4. On the **Body** tab, complete these settings:
       1. Select the **x-www-form-urlencoded** option.
       2. In the **KEY** field, enter grant\_type.
       3. In the **VALUE** field, enter. **client\_credentials**.
    5. Select **Send**.
  </Tab>
</Tabs>

### Sample response

PayPal returns an access token and the number of seconds for which the access token is valid, as shown in the following example.

```bash theme={null}
{
  "scope": "https://uri.paypal.com/services/invoicing https://uri.paypal.com/services/disputes/read-buyer https://uri.paypal.com/services/payments/realtimepayment https://uri.paypal.com/services/disputes/update-seller https://uri.paypal.com/services/payments/payment/authcapture openid https://uri.paypal.com/services/disputes/read-seller https://uri.paypal.com/services/payments/refund https://api-m.paypal.com/v1/vault/credit-card https://api-m.paypal.com/v1/payments/.* https://uri.paypal.com/payments/payouts https://api-m.paypal.com/v1/vault/credit-card/.* https://uri.paypal.com/services/subscriptions https://uri.paypal.com/services/applications/webhooks",
  "access_token": "A21AAFEpH4PsADK7qSS7pSRsgzfENtu-Q1ysgEDVDESseMHBYXVJYE8ovjj68elIDy8nF26AwPhfXTIeWAZHSLIsQkSYz9ifg",
  "token_type": "Bearer",
  "app_id": "APP-80W284485P519543T",
  "expires_in": 31668,
  "nonce": "2020-04-03T15:35:36ZaYZlGvEkV4yVSz8g6bAKFoGSEzuy3CQcz3ljhibkOHg"
}
```

### Make API calls

When you make API calls, replace `ACCESS-TOKEN` with your access token in the authorization header: `-H Authorization: Bearer ACCESS-TOKEN`. When your access token expires, call `/v1/oauth2/token` again to request a new access token.

## 3. Get sandbox account credentials

The PayPal sandbox is a test environment that mirrors real-world transactions. By default, PayPal developer accounts have 2 sandbox accounts: a personal account for buying and a business account for selling. You'll get the login information for both accounts. Watch sandbox money move between accounts to test API calls.

Take the following steps to get sandbox login information for business and personal accounts:

1. Log into the  <a href="https://developer.paypal.com/dashboard/">Developer Dashboard</a>.
2. Select **Testing Tools** > **Sandbox Accounts**. To create more sandbox accounts, you can select **Create account**.
3. Locate the account for which you want to get credentials, and select `⋮`.
4. To see mock information, such as the account email address and a system-generated password, select **View/Edit Account**.
5. Go to `sandbox.paypal.com/signin/`, and sign in with the personal sandbox credentials. In a separate browser, sign in with the business sandbox credentials.
6. Make API calls with your app's access token to see sandbox money move between the personal and business accounts.

## See also

* <a href="https://developer.paypal.com/tools/sandbox/">Sandbox testing guide</a>
* <a href="https://developer.paypal.com/docs/multiparty/">Multiparty payment solutions</a>
* <a href="https://developer.paypal.com/api/rest/webhooks/">Webhooks</a>


# Handling API responses when integrating with PayPal APIs
Source: https://docs.paypal.ai/developer/how-to/api/handling-api-responses



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](https://developer.paypal.com/api/rest/responses/).

## Response handling flow

This image shows the basic flow for handling API responses:

```mermaid theme={null}
flowchart TD
    A[API Request] -->|Check HTTP Status Code| B{Success:
     200-299?}
    B -->|Yes| C[Process Data] --> E
    B -->|No| D[Handle Error] --> E
   E[Provide User Feedback]
```

## 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

| HTTP status code            | Error name               | What it means                      | What to do                 |
| --------------------------- | ------------------------ | ---------------------------------- | -------------------------- |
| `400 Bad Request`           | `INVALID_REQUEST`        | Formatting errors in your request. | Check your JSON structure. |
| `401 Unauthorized`          | `AUTHENTICATION_FAILURE` | Missing or expired access token.   | Get a new access token.    |
| `403 Forbidden`             | `NOT_AUTHORIZED`         | No permission for this action.     | Check account permissions. |
| `404 Not Found`             | `RESOURCE_NOT_FOUND`     | Resource doesn't exist.            | Verify the ID or URL.      |
| `422 Unprocessable Entity`  | `UNPROCESSABLE_ENTITY`   | Business rule errors.              | Check error details.       |
| `500 Internal Server Error` | `INTERNAL_SERVER_ERROR`  | PayPal server issue.               | Try again later.           |

For more details, see the [Common errors](/developer/how-to/api/troubleshooting/common-errors) page.

## Tools, integrations, and features

| Name                                      | Purpose                                        | Integration location             |
| ----------------------------------------- | ---------------------------------------------- | -------------------------------- |
| Rest API response handling                | Get formatted answers for payments and orders. | Back-end and front-end           |
| Error handling and codes                  | Find and fix errors and warnings.              | Back-end and front-end           |
| Negative testing tools                    | Create test errors and declined payments.      | Sandbox (back-end and front-end) |
| Card decline and funding failure handling | Help users when cards are declined.            | Back-end and front-end           |

### 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](https://developer.paypal.com/api/rest/responses/).

### 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:

| Error                    | What it means                                         | What to do                                                                                                                      |
| ------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `VALIDATION_ERROR`       | Required fields are missing or have incorrect values. | Check the [validation error page](/developer/how-to/api/troubleshooting/common-errors/validation-error) for field requirements. |
| `DUPLICATE_INVOICE_ID`   | You used the same invoice ID more than once.          | Use a unique invoice ID for each transaction.                                                                                   |
| `CARD_EXPIRED`           | Customer's card is expired.                           | Ask them to use a different card.                                                                                               |
| `ORDER_ALREADY_CAPTURED` | The payment was already processed.                    | Check your records for the original payment.                                                                                    |
| `PAYER_ACTION_REQUIRED`  | The customer needs to do something.                   | Redirect the customer to the `rel:'payer-action` HATEOAS link in the response.                                                  |

These guides have more details about handling errors:

* [Common errors](/developer/how-to/api/troubleshooting/common-errors)
* [Rest API errors](https://developer.paypal.com/api/rest/responses/)
* [Payflow transaction responses](https://developer.paypal.com/api/nvp-soap/payflow/integration-guide/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:

```bash theme={null}
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](https://developer.paypal.com/tools/sandbox/negative-testing/request-headers/)
* [Sandbox error conditions](https://developer.paypal.com/tools/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](https://developer.paypal.com/docs/checkout/advanced/card-decline-errors/)
* [Handle funding failures](https://developer.paypal.com/docs/checkout/standard/customize/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.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api-m.sandbox.paypal.com/v1/payments/payment \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer ACCESS_TOKEN" \
      -d '{...}'
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import java.net.*;
    import java.io.*;

    public class PayPalApiExample {
        public static void main(String[] args) throws Exception {
            URL url = new URL("https://api-m.sandbox.paypal.com/v1/payments/payment");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Authorization", "Bearer ACCESS_TOKEN");
            conn.setDoOutput(true);

            String jsonInputString = "{...}";
            try(OutputStream os = conn.getOutputStream()) {
                byte[] input = jsonInputString.getBytes("utf-8");
                os.write(input, 0, input.length);
            }

            int code = conn.getResponseCode();
            BufferedReader br = new BufferedReader(new InputStreamReader(
                code == 201 ? conn.getInputStream() : conn.getErrorStream(), "utf-8"));
            StringBuilder response = new StringBuilder();
            String responseLine;
            while ((responseLine = br.readLine()) != null) {
                response.append(responseLine.trim());
            }
            System.out.println("Status: " + code + ", Response: " + response.toString());
        }
    }
    ```
  </Tab>

  <Tab title="JavaScript (Node.js)">
    ```javascript theme={null}
    const fetch = require('node-fetch');

    fetch('https://api-m.sandbox.paypal.com/v1/payments/payment', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer ACCESS_TOKEN'
      },
      body: JSON.stringify({...})
    })
      .then(res => res.json().then(data => ({ status: res.status, body: data })))
      .then(({ status, body }) => {
        if (status === 201) {
          console.log('Payment created:', body);
        } else {
          console.error('Error:', status, body);
        }
      });
    ```
  </Tab>

  <Tab title=".NET (C#)">
    ```dotnet theme={null}
    using System;
    using System.Net.Http;
    using System.Text;
    using System.Threading.Tasks;

    class Program {
        static async Task Main() {
            var client = new HttpClient();
            client.DefaultRequestHeaders.Add("Authorization", "Bearer ACCESS_TOKEN");
            var content = new StringContent("{...}", Encoding.UTF8, "application/json");
            var response = await client.PostAsync("https://api-m.sandbox.paypal.com/v1/payments/payment", content);
            var result = await response.Content.ReadAsStringAsync();
            if (response.IsSuccessStatusCode) {
                Console.WriteLine("Payment created: " + result);
            } else {
                Console.WriteLine("Error: " + response.StatusCode + " " + result);
            }
        }
    }
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    <?php
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, "https://api-m.sandbox.paypal.com/v1/payments/payment");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([...]));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Content-Type: application/json",
        "Authorization: Bearer ACCESS_TOKEN"
    ]);
    $result = curl_exec($ch);
    $httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpcode == 201) {
        echo "Payment created: $result";
    } else {
        echo "Error: $httpcode $result";
    }
    ?>
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    url = "https://api-m.sandbox.paypal.com/v1/payments/payment"
    headers = {
        "Content-Type": "application/json",
        "Authorization": "Bearer ACCESS_TOKEN"
    }
    data = {...}

    response = requests.post(url, json=data, headers=headers)
    if response.status_code == 201:
        print("Payment created:", response.json())
    else:
        print("Error:", response.status_code, response.json())
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    require 'net/http'
    require 'uri'
    require 'json'

    uri = URI('https://api-m.sandbox.paypal.com/v1/payments/payment')
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true
    request = Net::HTTP::Post.new(uri.path, {
      'Content-Type' => 'application/json',
      'Authorization' => 'Bearer ACCESS_TOKEN'
    })
    request.body = {...}.to_json

    response = http.request(request)
    if response.code == "201"
      puts "Payment created: #{response.body}"
    else
      puts "Error: #{response.code} #{response.body}"
    end
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import fetch from 'node-fetch';

    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) {
        console.log('Payment created:', data);
      } else {
        console.error('Error:', response.status, data);
      }
    }
    ```
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="ECMAScript (ES Modules)">
    ```javascript theme={null}
    // 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>
    ```
  </Tab>

  <Tab title="JavaScript (React)">
    ```javascript theme={null}
    import React from 'react';

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

    export default function PayPalButton() {
      return <button onClick={createPayment}>Pay with PayPal</button>;
    }
    ```
  </Tab>

  <Tab title="JavaScript (Vanilla)">
    ```javascript theme={null}
    <script>
    fetch('https://api-m.sandbox.paypal.com/v1/payments/payment', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer ACCESS_TOKEN'
      },
      body: JSON.stringify({...})
    })
      .then(res => res.json().then(data => ({ status: res.status, body: data })))
      .then(({ status, body }) => {
        if (status === 201) {
          alert('Payment created!');
        } else {
          alert('Error: ' + status);
        }
      });
    </script>
    ```
  </Tab>

  <Tab title="TypeScript (React)">
    ```typescript theme={null}
    import React from 'react';

    const createPayment = async () => {
      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);
      }
    };

    const PayPalButton: React.FC = () => (
      <button onClick={createPayment}>Pay with PayPal</button>
    );

    export default PayPalButton;
    ```
  </Tab>
</Tabs>

## 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](https://developer.paypal.com/tools/sandbox/negative-testing/request-headers/) 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](/developer/how-to/api/handling-api-responses#testing-your-response-handling).

## 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:

| Problem                        | Solution                                                      |
| ------------------------------ | ------------------------------------------------------------- |
| Getting `401` errors regularly | Set up token refresh before tokens expire.                    |
| Webhooks not working           | Make sure your webhook URL is public and events are verified. |
| Can't process refunds          | Use the correct transaction ID from the original payment.     |
| Test payments always fail      | Check if your test buyer account has enough funds.            |

## Mobile app tips

When building mobile apps with PayPal:

* Use native SDKs when possible for 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](https://developer.paypal.com/api/rest/responses/)
* [Rest API overview](https://developer.paypal.com/api/rest/)
* [Rest API requests](https://developer.paypal.com/api/rest/requests/)
* [Payflow transaction responses](https://developer.paypal.com/api/nvp-soap/payflow/integration-guide/transaction-responses/)
* [Negative testing with request headers](https://developer.paypal.com/tools/sandbox/negative-testing/request-headers/)
* [Sandbox error conditions](https://developer.paypal.com/tools/sandbox/error-conditions/)
* [Card decline errors](https://developer.paypal.com/docs/checkout/advanced/card-decline-errors/)
* [Handle funding failures](https://developer.paypal.com/docs/checkout/standard/customize/handle-funding-failures/)


# Making PayPal REST API requests
Source: https://docs.paypal.ai/developer/how-to/api/make-api-requests



Build proper API requests with the correct headers and parameters to ensure successful communication with PayPal's REST APIs.

PayPal REST APIs authenticate with OAuth 2.0 access tokens, and return HTTP response codes with JSON-encoded responses.

> **Important:** Before making REST API calls, you'll need to [get credentials](developer/how-to/apps-scopes-credentials).

## Base URLs

All PayPal REST API requests target one of two base URLs:

* Sandbox for testing: `https://api-m.sandbox.paypal.com`
* Live for production: `https://api-m.paypal.com`

## 1st-party and 3rd-party calls

When you make REST API calls to PayPal, you can make first-party or third-party calls.

* **First-party calls:** API calls made to PayPal on behalf of your business. This method is also called a direct merchant integration.
* **Third-party calls:** API calls made to PayPal on behalf of another merchant. This is common when building marketplaces, platforms, or large enterprise solutions. This method is also called a multiparty or partner integration. Third-party calls require additional HTTP headers:
  * [`PayPal-Auth-Assertion`](#paypal-auth-assertion): Identifies the merchant you're making a call for.
  * [`PayPal-Partner-Attribution-Id`](#paypal-partner-attribution-id): Identifies your platform to PayPal.

## Important HTTP headers

The following is a list of all PayPal-specific HTTP request headers.

### PayPal-Auth-Assertion

> **Optional:** For platforms and marketplaces only.

This header is for platforms, marketplaces, large companies, and service providers that handle payments for more than one merchant. Examples include Square, eBay, Shopify, and other payment processors.

#### Purpose

Generating and storing separate access tokens for each merchant can be complex and costly. You can use the `PayPal-Auth-Assertion` header as one set of platform credentials for all merchants.

The `PayPal-Auth-Assertion` header is a <a href="https://tools.ietf.org/html/rfc7519">JSON Web Token (JWT)</a> that identifies which merchant each API call is for. This header requires explicit consent from each merchant you represent.

#### Build the JWT

PayPal recommends using an unsigned JWT, because the information passed with the JWT is not sensitive. Build the JWT with 3 parts:

* **Header:** For an unsigned JWT, set algorithm to `"alg": "none"`.
* **Payload:** Include the following fields:
  * `iss`: The platform's `client_id` (issuer).
  * `payer_id`: The specific merchant's PayPal payer ID.
* **Signature:** Use an empty string `""` for unsigned JWTs. If you prefer a signed JWT for security reasons, you can sign it with your secret from your API credentials.

Base64 encode each part separately, then concatenate with periods:

```
[encoded_header].[encoded_payload].[encoded_signature]
```

Example HTTP header:

```http theme={null}
PayPal-Auth-Assertion: eyJhbGciOiJub25lIn0.eyJpc3MiOiJZT1VSX1BMQVRGT1JNX0NMSUVOVF9JRCIsInBheWVyX2lkIjoiTUVSQ0hBTlRfUEFZRVJfSUQifQ.
```

Include the resulting JWT string in the `PayPal-Auth-Assertion` header when making API calls on behalf of that merchant.

```json theme={null}
{
  "iss": "your_platform_client_id",
  "payer_id": "merchant_payer_id_here"
}
```

### PayPal-Partner-Attribution-Id

> **Required:** For platforms and marketplaces only.

This header does two things:

* Identifies your platform to PayPal.
* Tracks all transactions associated with your platform.

The header value is your unique Build Notation (BN) code. Take the following steps to find your BN code:

1. From your developer dashboard, select **Apps & Credentials**.
2. Select the app you're using.
3. Under **App Settings**, scroll to **Reports**.
4. Your BN code appears on the last line of the Reports section.

### PayPal-Mock-Response

> **Optional.**

Use this header to simulate errors by passing an error code through the `mock_application_codes` parameter. For example, `"mock_application_codes": "DUPLICATE_INVOICE_ID"` to simulate two invoices sent with the same ID:

```bash theme={null}
curl -X POST \
https://api-m.sandbox.paypal.com/v2/checkout/orders/YOUR-ORDER-ID/capture \
  -H 'Authorization: Bearer YOUR-ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'PayPal-Mock-Response: {"mock_application_codes": "DUPLICATE_INVOICE_ID"}'
```

For more information, see:

* [Payment API error messages](https://developer.paypal.com/docs/api/payments/v2/#errors)
* [Orders API error messages](https://developer.paypal.com/api/rest/reference/orders/v2/errors/)
* [Simulate negative responses with request headers](https://developer.paypal.com/tools/sandbox/negative-testing/request-headers/#test-api-error-handling-routines)

### PayPal-Request-Id

> **Important:** Recommended for all `POST` and `PUT` calls.

The `PayPal-Request-Id` contains a unique user-generated ID that prevents duplicate transactions. PayPal recommends including this header in any API call that creates or modifies data.

PayPal uses the `PayPal-Request-Id` to enforce **idempotency**. Idempotency means you can retry an API call multiple times without duplicating actions. For example, if a user presses a buy button multiple times, they aren't charged for each button press.

With this header, you can retry calls knowing that PayPal won't process the same action for as long as the server stores the ID. PayPal stores the ID for up to 45 days. If you retry a call with the same `PayPal-Request-Id`, PayPal recognizes it as a duplicate and returns the result of the original call.

```bash theme={null}
curl -v -X POST https://api-m.sandbox.paypal.com/v2/payments/authorizations/YOUR-ORDER-ID/capture \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
  -H "PayPal-Request-Id: 123e4567-e89b-12d3-a456-426655440010" \
  -d '{
    "amount": {
      "value": "10.99",
      "currency_code": "USD"
    },
    "invoice_id": "INVOICE-123",
    "final_capture": true
    }'
```

## Common authentication errors

When using PayPal HTTP headers, you might encounter these issues:

* **401 Unauthorized**: Check that your platform credentials are valid and that you have permission to act on behalf of the merchant.
* **400 Bad Request**: Verify the JWT format is correct and all required fields are present.
* **403 Forbidden**: Ensure the merchant has granted your platform appropriate permissions.

For detailed error troubleshooting, check the response body. Find an error code, message, and debug ID to reference when contacting PayPal support. You can also refer to our [common errors](/developer/how-to/api/troubleshooting/common-errors/).

## Query PayPal REST APIs

When making a REST API request to PayPal, append query parameters to the endpoint URL using the following format:

```http theme={null}
https://api-m.sandbox.paypal.com/{resource}?parameter1=value1&parameter2=value2
```

* Separate each query parameter with an ampersand `&`.
* Introduce the first query parameter with a question mark `?`.
* URL-encode parameter names and values if they contain special characters.

### Example: list invoices

This example returns details for four invoices, starting from the third invoice, and includes the total invoice count.

```bash theme={null}
curl -v -X GET https://api-m.sandbox.paypal.com/v1/invoicing/invoices?page=3&page_size=4&total_count_required=true\
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer ACCESS-TOKEN"
```

* `page=3` requests the third page of results.
* `page_size=4` limits the response to 4 items per page.
* `total_count_required=true` asks PayPal to include the total count of items in the response.

### Query parameters

> **Note:** Not all pagination parameters are available for all APIs.

| Parameter              | Type    | Description                                                                                                                                                                                                                                         |
| ---------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `count`                | integer | The number of items to list in the response.                                                                                                                                                                                                        |
| `end_time`             | integer | The end date and time for the range to show in the response, in <a href="https://tools.ietf.org/html/rfc3339#section-5.6">Internet date and time format</a>. For example, `end_time=2025-03-07T11:00:00Z`.                                          |
| `page`                 | integer | The page number indicating which set of items will be returned in the response. For example, the combination of `page=1` and `page_size=20` returns the first 20 items. The combination of `page=2` and `page_size=20` returns items 21 through 40. |
| `page_size`            | integer | The number of items to return in the response.                                                                                                                                                                                                      |
| `total_count_required` | boolean | Indicates whether to show the total count in the response.                                                                                                                                                                                          |
| `sort_by`              | string  | Sorts the payments in the response by a specified value, such as the create time or update time.                                                                                                                                                    |
| `sort_order`           | string  | Sorts the items in the response in ascending or descending order.                                                                                                                                                                                   |
| `start_id`             | string  | The ID of the starting resource in the response. When results are paged, you can use the `next_id` value as the `start_id` to continue with the next set of results.                                                                                |
| `start_index`          | integer | The `start_index` parameter lets you specify the position in the list where results should begin. For example, setting `start_index=2` skips the first item and shows results from the second item onward.                                          |
| `start_time`           | string  | The start date and time for the range to show in the response, in Internet date and time format. For example, `start_time=2025-03-06T11:00:00Z`.                                                                                                    |

## Example request: create invoice

PayPal's REST APIs support standard HTTP methods - `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.

> **Important**: Include a `PayPal-Request-Id` header in all `POST` and `PUT` requests to prevent duplicate actions.

The following request creates an invoice as a direct merchant:

* From sender David Larusso, including address, email address, and phone number.
* To recipient Stephanie Meyers, including address, email address, and phone number.
* For one \$50 yoga mat including sales tax.
* For one \$10 t-shirt including sales tax.
* With \$20 minimum partial payments enabled.
* With an optional tip.
* With $10 packing charges and $10 shipping charges, including sales tax.
* With a 5% invoice discount.

```bash theme={null}
curl -v -X POST 'https://api-m.sandbox.paypal.com/v2/invoicing/invoices' \
 -H 'Content-Type: application/json' \
 -H 'Authorization: Bearer YOUR-ACCESS-TOKEN' \
 -H 'PayPal-Request-Id: YOUR-REQUEST-ID' \
 -d '{
  "detail": {
    "invoice_number": "123",
    "reference": "deal-ref",
    "invoice_date": "2028-11-22",
    "currency_code": "USD",
    "note": "Thank you for your business.",
    "term": "No refunds after 30 days.",
    "memo": "This is a long contract",
    "payment_term": {
      "term_type": "NET_10",
      "due_date": "2028-11-22"
    }
  },
  "invoicer": {
    "name": {
      "given_name": "David",
      "surname": "Larusso"
    },
    "address": {
      "address_line_1": "1234 First Street",
      "address_line_2": "337673 Hillside Court",
      "admin_area_2": "Anytown",
      "admin_area_1": "CA",
      "postal_code": "98765",
      "country_code": "US"
    },
    "email_address": "merchant@example.com",
    "phones": [
      {
        "country_code": "001",
        "national_number": "4085551234",
        "phone_type": "MOBILE"
      }
    ],
    "website": "www.test.com",
    "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g",
    "logo_url": "https://example.com/logo.PNG",
    "additional_notes": "2-4"
  },
  "primary_recipients": [
    {
      "billing_info": {
        "name": {
          "given_name": "Stephanie",
          "surname": "Meyers"
        },
        "address": {
          "address_line_1": "1234 Main Street",
          "admin_area_2": "Anytown",
          "admin_area_1": "CA",
          "postal_code": "98765",
          "country_code": "US"
        },
        "email_address": "buyer@example.com",
        "phones": [
          {
            "country_code": "001",
            "national_number": "4884551234",
            "phone_type": "HOME"
          }
        ]
      },
      "shipping_info": {
        "name": {
          "given_name": "Earl",
          "surname": "Gray"
        },
        "address": {
          "address_line_1": "1234 Main Street",
          "admin_area_2": "Anytown",
          "admin_area_1": "CA",
          "postal_code": "98765",
          "country_code": "US"
        }
      }
    }
  ],
  "items": [
    {
      "name": "Yoga mat",
      "description": "Elastic mat to practice yoga.",
      "quantity": "1",
      "unit_amount": {
        "currency_code": "USD",
        "value": "50.00"
      },
      "tax": {
        "name": "Sales Tax",
        "percent": "7.25"
      },
      "discount": {
        "percent": "5"
      },
      "unit_of_measure": "QUANTITY"
    },
    {
      "name": "Yoga t-shirt",
      "quantity": "1",
      "unit_amount": {
        "currency_code": "USD",
        "value": "10.00"
      },
      "tax": {
        "name": "Sales Tax",
        "percent": "7.25"
      },
      "unit_of_measure": "QUANTITY"
    }
  ]
}'
```


# Rate limiting with PayPal REST APIs
Source: https://docs.paypal.ai/developer/how-to/api/rate-limiting



Rate limiting restricts the number of API requests you can make in a specific time frame. When you exceed this limit, PayPal's servers may deny further requests until your usage drops below the limit. This protects the system from overload.

If you or your customers receive a `429` status code, too many requests were sent, which might indicate anomalous traffic. PayPal uses rate limits to ensure stability.

Understanding rate limiting can help you avoid disruptions when building or scaling your app.

PayPal may enforce rate limits for several reasons:

* **Excessive polling:** Making too many requests instead of using webhooks.
* **Traffic spikes:** A sudden increase in requests due to user activity or system events.
* **Token misuse:** Failing to reuse OAuth 2.0 tokens and repeatedly fetching new ones.
* **Suspicious patterns:** Behavior flagged as atypical or potentially harmful.

> **Note:** PayPal doesn't publish exact rate limits because they vary depending on the API, environment, and circumstances. By keeping these limits flexible, PayPal can scale services to match demand while preventing abuse.

## How to prepare for rate limiting

Here's what you can do to reduce the chances of hitting a rate limit:

* **Use webhooks instead of polling:** [Webhooks](https://developer.paypal.com/api/rest/webhooks/) let PayPal send updates directly to your system, so you don't need to keep requesting information.
* **Cache OAuth 2.0 tokens:** Instead of creating new tokens for every request, securely store and reuse tokens until they expire.
* **Optimize your requests:** Minimize unnecessary calls, and don't request data more often than needed. Combine requests whenever possible.
* **Plan for scale:** If you expect high traffic, test your system to ensure it works efficiently under heavy load.

## What to do if you hit a rate limit

If your API requests start failing due to rate limiting, follow these steps:

* **Diagnose the issue:** Check your API logs to understand why the limit was triggered. Look for patterns in request frequency or behavior.
* **Reduce request frequency:** Slow down request rates or spread them out over time to stay within limits.
* **Retry with exponential backoff:** Increase the delay between requests each time a request fails.
* **Use webhooks instead of polling:** If you're polling for updates, switch to PayPal's webhooks to receive alerts automatically.
* **Implement error handling**: Implement error handling as in the following example code.

In a production environment, you'd want to:

* Use a more robust storage mechanism.
* Implement proper secure token management.
* Use a production-grade logging system.
* Consider more sophisticated retry strategies with maximum retry limits.
* Add additional error handling for different types of API responses.

```javascript theme={null}
// Example error handling for rate limits
function apiRequest(endpoint, data) {
  return fetch(endpoint, {
    method: 'POST',
    body: JSON.stringify(data),
    headers: { 'Content-Type': 'application/json' }
  })
  .then(response => {
    if (response.status === 429) {
      // Extract retry-after header if available
      const retryAfter = response.headers.get('Retry-After') || 30;
      
      // Log the rate limiting event
      console.log(`Rate limited. Retrying in ${retryAfter} seconds`);
      
      // Implement exponential backoff
      return new Promise(resolve => {
        setTimeout(() => resolve(apiRequest(endpoint, data)), retryAfter * 1000);
      });
    }
    
    return response.json();
  })
  .catch(error => {
    // Log the error for debugging
    console.error('API request failed:', error);
    
    // Determine if retry is appropriate
    if (isRetryableError(error)) {
      return retryWithBackoff(apiRequest, [endpoint, data]);
    }
    
    throw error;
  });
}
```

If you need further assistance, reach out to [Merchant Technical Support](https://www.paypal.com/mts?_ga=2.12095284.1829917444.1751296466-935108042.1736183519&_gac=1.90987240.1749058302.CjwKCAjw3f_BBhAPEiwAaA3K5GZi7UMt1wQxD_c8GrhAiGQRTsNsuH7lglTyr9KlGTH_zQ73HWpLtBoCtrsQAvD_BwE).


# Agreement already canceled
Source: https://docs.paypal.ai/developer/how-to/api/troubleshooting/common-errors/agreement-already-cancelled



Returns from the Orders V2 API.

`AGREEMENT_ALREADY_CANCELLED` indicates that an operation is trying to execute on an already-canceled billing agreement.

| Cause                                                                                                                                                                                                                                                                                                                                           | Impact                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Resolution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Manually canceled: The merchant or payer manually canceled the agreement. <br /> - Automatically canceled: Certain conditions automatically canceled the agreement, such as payment failures or account issues. <br /> - Logic error: The application implemented faulty logic that tried to modify an agreement without checking its status. | - Transaction failure: Transactions for the canceled agreement cannot proceed, potentially leading to failed payments and disrupted user subscriptions or services. <br /> - Integration failures: Recurring logic based on this agreement might break, causing administrators or payers to make multiple calls attempting to resolve actions on a non-existent agreement. <br /> - Customer dissatisfaction: Users affected by the cancellation might experience service interruption, thereby reducing trust and satisfaction. | - Check the agreement status: Ensure that you check the status of a billing agreement before beginning operations, such as by retrieving agreement details and verifying the cancellation status. <br /> - Implement error handling: Manage errors by informing the payer or system about the current status of the billing agreement and providing appropriate options or messages. <br /> - Update business logic: Ensure that your application logic correctly tracks the status of an agreement and attempts only valid operations. |


# Cannot pay self
Source: https://docs.paypal.ai/developer/how-to/api/troubleshooting/common-errors/cannot-pay-self



Returns from the Payments V1 API.

`CANNOT_PAY_SELF` indicates that the payment request is attempting to send money to the same account initiating the transaction.

| Cause                                                                                                                                                      | Impact                                                                                                                                        | Resolution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| :--------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Duplicate reference: The transaction or billing agreement attempts to reference the sender and receiver of payment as the same entity, which is invalid. | - Disrupted transactions: PayPal prevents the transaction from being processed to avoid misuse or fraud stemming from potential self-payment. | - Confirm separation: Ensure that the sender and receiver are different entities. <br /> - Review API request: Ensure you use distinct PayPal account IDs or email addresses for the sender and receiver. <br /> - Implement validation checks: Ensure that your application checks to prevent users from setting up billing agreements with duplicate entities. <br /> - Debug application code: Review and debug the code to correct issues leading to payer and payee using the same account. |


# Currency mismatch
Source: https://docs.paypal.ai/developer/how-to/api/troubleshooting/common-errors/currency-mismatch



Returns from the Payments V2 API.

`CURRENCY_MISMATCH` indicates a discrepancy between the currencies specified within different components in the transaction request. Typically, that means the currency used in the payment request does not match the currency expected or configured in the transaction.

| Cause                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Impact                                                                                                                                                                                                                                                                                                      | Resolution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Mismatch in account: The currency specified in the transaction request does not match the currency configured for the merchant account or the payment method. <br /> - Mismatch in transaction: The currency used in the transaction does not match the currency settings of the payer or payee accounts. <br /> - Mismatch in request: The currency specified in one field of the API request does not match another field in the API request, such as between the payment amount and the transaction currency. | - Failed payment attempt: The transaction cannot be processed, leading to a failed payment attempt. <br /> - Payer dissatisfaction: Failed payment attempts can cause delays and inconvenience for the payer and the merchant as PayPal does not complete the payment until you resolve the currency issue. | - Verify fields: Check the API request to ensure that all relevant fields consistently use the same currency. <br /> - Verify configuration: Ensure that you configure the merchant account to accept payments in the specified currency and adjust settings as necessary. <br /> - Match between accounts: Ensure that the currency settings align between payer and payee accounts. <br /> - Verify payment method support: Confirm that the payment method [supports the specified currency](https://developer.paypal.com/docs/reports/reference/paypal-supported-currencies/). <br /> - Verify transaction match: Ensure that the currency used in the transaction matches the currency expected by the payment method. |


# Currency not allowed
Source: https://docs.paypal.ai/developer/how-to/api/troubleshooting/common-errors/currency-not-allowed



Returns from the Payments V1 API.

`CURRENCY_NOT_ALLOWED` indicates that PayPal does not support the currency specified in the transaction request.

| Cause                                                                                                                                                                                                                                                                                                                                                                                                                                         | Impact                                                                                                                                                                                                                                                                                            | Resolution                                                                                                                                                                                                                                                                                                                                                     |
| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Unsupported currency: PayPal does not support the specified currency for the transaction. <br /> - Unconfigured account: The merchant's PayPal account is not configured to accept payments in the specified currency. <br /> - Region restrictions: The region or transaction type may have restrictions on certain currencies. <br /> - Disabled currency: PayPal may support the currency but the account or payment method disabled it. | - Failed payment attempt: PayPal cannot process the transaction with the specified currency. <br /> - Inconvenience: Failed payment attempts using an unsupported currency can cause inconvenience for the merchant and the payer, especially if the payer prefers to pay in a specific currency. | - Verify supported currencies: Change the currency code in your API request to a [supported currency](https://developer.paypal.com/docs/reports/reference/paypal-supported-currencies/) for your location or account. <br /> - Configure account: Ensure that you have configured or enabled your PayPal account to accept payments in the desired currencies. |


# Duplicate transactions
Source: https://docs.paypal.ai/developer/how-to/api/troubleshooting/common-errors/duplicate-transaction



Returns from the Payments V2 API.

`DUPLICATE_TRANSACTION` indicates that a transaction with identical details has already been processed, and has been flagged to prevent duplicate charges.

| Cause                                                                                                                                                                                                                                                                                                                                                                                               | Impact                                                                                                                                                                                               | Resolution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| - Network latency or delays: Issues in network or server communication could result in a resending of the transaction request. <br /> - Payer actions: A payer might inadvertently submit the payment information multiple times, such as by clicking the payment button more than once. <br /> - Server error: The client-side application did not receive a response and retried the transaction. | - Customer dissatisfaction: Needing to perform additional steps to confirm the transaction status, or being unsure whether the transaction succeeded, can lead to customer confusion or frustration. | - Check transaction status: Verify whether the original transaction succeeded by checking the transaction history in your PayPal account or through the API. <br /> - Implement idempotency: Use unique identifiers, such as an idempotency key, for each transaction request to ensure that retries do not result in duplicate transactions. <br /> - Improve user feedback: Provide clear feedback to payers about their transaction status to prevent them from resubmitting the payment. <br /> - Implement error handling: Implement error handling and network retry logic to manage connectivity issues without resubmitting identical requests. |


# Merchant not enabled for reference transaction
Source: https://docs.paypal.ai/developer/how-to/api/troubleshooting/common-errors/merchant-not-enabled-for-reference-transaction



Returns from the Payments V1 API.

`MERCHANT_NOT_ENABLED_FOR_REFERENCE_TRANSACTION` indicates that the merchant account is not configured to perform reference transactions.

| Cause                                                                                                                                                                                                                                                                                                                                                                                | Impact                                                                                                                                                                                                                                           | Resolution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| - Unconfigured account: The merchant account is not configured or approved to handle reference transactions. Reference transactions require specific permissions and account settings that PayPal does not enable by default on all accounts. <br /> - Failed attempt: The merchant attempts a reference transaction without enabling the necessary permissions or account settings. | - Failed payment attempt: The merchant cannot process reference transactions for recurring billing, subscriptions, or other post-payment transactions. <br /> - Business disruptions: Services that depend on automated billing fail to operate. | - [Contact customer support](https://www.paypal.com/us/cshelp/contact-us): Send a request to customer support to enable reference transactions for your account. Enabling reference transactions may require you to provide additional information about your account. <br /> - Review account settings: Configure your account settings to support reference transactions. <br /> - For more information, see [Initiate future transactions](https://developer.paypal.com/docs/checkout/advanced/customize/reference-transactions/). |


# Not authorized
Source: https://docs.paypal.ai/developer/how-to/api/troubleshooting/common-errors/not-authorized



The Orders v2 API returns a `403 Not Authorized` error when the API caller or the payee does not have permission. Review the common causes and how to fix them.

If an issue persists or you have further questions, contact [PayPal Support](https://www.paypal.com/us/cshelp/technical).

<Heading>
  PAYEE\_ACCOUNT\_NOT\_VERIFIED
</Heading>

| Cause                                                                                                                                                              | Impact                                                                        | Resolution                                                                                                                                                                                                                                                                                             |
| :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - The payee did not verify their PayPal account. <br /> - The payee ignored account restrictions or limits. <br /> - The payee did not verify their email address. | PayPal stops the payment and blocks the transaction. This slows the purchase. | <br /> - Tell the payee to check their email, link and confirm a bank account or card, and send required documents. <br /> - Help them remove account restrictions or limits. Have them resolve any issues or contact PayPal support. <br /> - Tell the payee to follow the steps in the PayPal email. |

<Heading>
  PAYEE\_NOT\_CONSENTED
</Heading>

| Cause                                                                                                                                                                                                       | Impact                                                                                                                                  | Resolution                                                                                                                                                                                                                                                                                                                                                                                            |
| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - The payee did not give permission to the API caller. <br /> - Another account used its info to make the request for the payee. <br /> - The payee did not agree to let the API caller finish the payment. | <br /> - The payee blocks the helper account from processing payments. <br /> - Customers cannot finish PayPal payments on the website. | - Enter the payee account in the `payee` field in the `purchase_units` object of the Orders API request. Enter correct info and give the API caller permission. <br /> - For PayPal Complete Payments, give the API caller consent to collect partner fees for the payee. Add `PARTNER_FEE` during sign-up.  <br /> - If you already added permission or this issue persists, contact PayPal support. |

<Heading>
  PERMISSION\_DENIED
</Heading>

| Cause                                                                                                                                                                                                                                                                                                                                                                                                   | Impact                                                                                  | Resolution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - The API caller skipped required permissions. <br /> - The PayPal account doesn't have the permission you need. <br /> - The API caller used expired or invalid OAuth access tokens. <br /> - The account tries things it is not allowed to do, like a personal account using business tools. <br /> - The API caller uses the wrong sandbox login info in a live environment or the other way around. | The payment stops, and the customer cannot finish the order. This can cause lost sales. | - Make sure the resource ID belongs to the PayPal account making the API call. If not, give the right permission. <br /> - Use login info for the correct sandbox or live environment and get it from the PayPal Developer Dashboard. <br /> - Ask for the right access when making tokens. <br /> - Renew access tokens often and handle token expiration in the PayPal Developer Dashboard. <br /> - Use the correct API endpoints for your environment. For sandbox, use `https://api.sandbox.paypal.com`. For live, use `https://api.paypal.com`. <br /> - Make sure the PayPal account supports the requested API operations. Some features only work for business accounts or special integrations, like payouts. |


# Common errors overview
Source: https://docs.paypal.ai/developer/how-to/api/troubleshooting/common-errors/overview



Troubleshooting is an important part of integrating with the PayPal Orders API. The following provides explanations and solutions to help you quickly find and fix issues in your integration.

| Issue                                     | Action                                                                                                                                                                                                                                                                                                                                                                   |
| :---------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AMOUNT_MISMATCH`                         | Ensure the total amount equals the sum of line items, taxes, and discounts. The API returns this error if the sale amounts are not reflected in the request.                                                                                                                                                                                                             |
| `CARD_EXPIRED`                            | Show the error to the payer and ask them to use a different card.                                                                                                                                                                                                                                                                                                        |
| `CANNOT_BE_NEGATIVE`                      | Enter a positive amount with no more than two decimal places.                                                                                                                                                                                                                                                                                                            |
| `CANNOT_BE_ZERO_OR_NEGATIVE`              | Enter a positive, non-zero amount with no more than two decimal places.                                                                                                                                                                                                                                                                                                  |
| `CURRENCY_NOT_SUPPORTED`                  | Use a PayPal-supported currency. Make sure the receiving PayPal account accepts the currency. For a list of supported currencies, see [Currency codes](https://developer.paypal.com/docs/api/rest/reference/currency-codes/currency-codes/).                                                                                                                             |
| `DECIMAL_PRECISION`                       | Round the amount to 2 decimal places and try again. If the issue persists, contact [PayPal support](https://www.paypal.com/us/cshelp/technical) and provide the `debug_id` from the API response.                                                                                                                                                                        |
| `DECIMALS_NOT_SUPPORTED`                  | Adjust the amount to match the number of decimal places the currency supports.                                                                                                                                                                                                                                                                                           |
| `DUPLICATE_INVOICE_ID`                    | Use a different `invoice_id`. If you must reuse the same `invoice_id` and the issue persists, contact [PayPal support](https://www.paypal.com/us/cshelp/technical).                                                                                                                                                                                                      |
| `INCOMPATIBLE_PARAMETER_VALUE`            | Make sure the parameters in the API request match the expected data types. For more information, see [Authentication](https://developer.paypal.com/api/rest/authentication/).                                                                                                                                                                                            |
| `INVALID_PARAMETER_SYNTAX`                | Make sure the API request JSON is correct and follows the PayPal API request format. If the issue persists, contact [PayPal support](https://www.paypal.com/us/cshelp/technical) and provide the `debug_id` from the API response.                                                                                                                                       |
| `INVALID_PARAMETER_VALUE`                 | Enter a valid parameter value.                                                                                                                                                                                                                                                                                                                                           |
| `INVALID_RESOURCE_ID`                     | Check the resource ID and try again. If the resource ID belongs to a different PayPal account, check the scopes and permissions for the receiving account.                                                                                                                                                                                                               |
| `INVALID_STRING_LENGTH`                   | Make sure text fields are not too long and include all required data. For string length requirements, see the [Orders API](https://developer.paypal.com/docs/api/orders/v2/#orders_create).                                                                                                                                                                              |
| `ITEM_TOTAL_MISMATCH`                     | Make sure the item totals match the quantity total.                                                                                                                                                                                                                                                                                                                      |
| `MAX_NUMBER_OF_PAYMENT_ATTEMPTS_EXCEEDED` | Ask the payer to use a different payment method.                                                                                                                                                                                                                                                                                                                         |
| `MISSING_REQUIRED_PARAMETER`              | Make sure the JSON follows the PayPal API request format and includes all [required parameters](https://developer.paypal.com/docs/api/orders/v2/#orders_create). If the issue persists, contact [PayPal support](https://www.paypal.com/us/cshelp/technical) and provide the `debug_id` from the API response.                                                           |
| `ORDER_ALREADY_AUTHORIZED`                | To proceed, [call capture](https://developer.paypal.com/docs/api/orders/v2/#orders_capture) because the funds are authorized. If the authorization is more than 3 days old, reauthorize the funds before capturing.                                                                                                                                                      |
| `ORDER_ALREADY_CAPTURED`                  | No action needed. Use a `GET` call on the order ID to get the capture ID or PayPal transaction ID. For multi-capture or split shipments, use `intent=AUTHORIZE`. See [Capture authorized payment](https://developer.paypal.com/docs/api/payments/v2/#authorizations_capture) for more information.                                                                       |
| `ORDER_NOT_APPROVED`                      | Ask the payer to complete PayPal checkout again to approve the order. Redirect them to the `'rel':'approve'` URL in the HATEOAS links from the create order call or provide a valid `payment_source` in the request.                                                                                                                                                     |
| `PAYEE_ACCOUNT_RESTRICTED`                | Contact PayPal customer support to lift restrictions on the receiving account. If you are a marketplace, ask the seller to resolve restrictions with PayPal.                                                                                                                                                                                                             |
| `PAYEE_NOT_CONSENTED`                     | Make sure the API caller has consent to collect partner fees for the payee. Add `PARTNER_FEE` to the capabilities during [signup](https://developer.paypal.com/docs/multiparty/seller-onboarding/before-payment/#generate-a-signup-link). If `PARTNER_FEE` is already added or the issue persists, contact [PayPal support](https://www.paypal.com/us/cshelp/technical). |
| `PAYEE_NOT_ENABLED_FOR_CARD_PROCESSING`   | Contact [PayPal support](https://www.paypal.com/us/cshelp/technical) to check the merchant or payee account configuration.                                                                                                                                                                                                                                               |
| `PAYER_ACTION_REQUIRED`                   | Redirect the payer to the `'rel':'payer-action'` HATEOAS link before authorizing or capturing the order. Some payment methods require a webhook subscription to notify you of background payer actions before capture succeeds.                                                                                                                                          |
| `PERMISSION_DENIED`                       | Make sure you have the correct permissions and scopes for the resource. If the resource ID belongs to another account, grant the necessary permissions.                                                                                                                                                                                                                  |
| `POSTAL_CODE_REQUIRED`                    | Add a postal code to the request and try again.                                                                                                                                                                                                                                                                                                                          |
| `REDIRECT_PAYER_FOR_ALTERNATE_FUNDING`    | Redirect the payer to choose a different payment method. In PayPal, the payer can add a new payment method to their wallet or use a different card.                                                                                                                                                                                                                      |
| `REFERENCED_CARD_EXPIRED`                 | Ask the payer to update their card information. Otherwise, future attempts will fail.                                                                                                                                                                                                                                                                                    |
| `SHIPPING_ADDRESS_INVALID`                | Fix the shipping address and try again. If using saved payment details, ask the payer for the correct shipping address.                                                                                                                                                                                                                                                  |
| `TOKEN_ID_NOT_FOUND`                      | Validate the payment token. If your PayPal account is making API calls for another account, make sure the recipient account grants the necessary permissions.                                                                                                                                                                                                            |
| `UNPROCESSABLE_ENTITY`                    | Contact [PayPal support](https://www.paypal.com/us/cshelp/technical) with the `debug_id` or `correlation_id` from the response header. For legacy integrations, check the body or response parameters.                                                                                                                                                                   |
| `VALIDATION_ERROR`                        | Tell the payer the card number is incorrect and ask them to enter the correct number.                                                                                                                                                                                                                                                                                    |

## HTTP status codes and error messages

The following table lists the most common HTTP status codes and error messages returned by the [Orders v2 API](https://developer.paypal.com/docs/api/orders/v2/#errors).

| HTTP status code            | Error message                                                                                        | Error code               |
| :-------------------------- | :--------------------------------------------------------------------------------------------------- | :----------------------- |
| `400 Bad Request`           | The request has the wrong format.                                                                    | `INVALID_REQUEST`        |
| `401 Unauthorized`          | Authentication failed because the authorization header is missing, or the credentials are not valid. | `AUTHENTICATION_FAILURE` |
| `403 Forbidden`             | Authorization failed because of lack of permissions.                                                 | `NOT_AUTHORIZED`         |
| `404 Not Found`             | The specified resource does not exist.                                                               | `RESOURCE_NOT_FOUND`     |
| `422 Unprocessable Entity`  | The requested action could not be performed, won't work, or failed business rules.                   | `UNPROCESSABLE_ENTITY`   |
| `500 Internal Server Error` | An internal server error occurred.                                                                   | `INTERNAL_SERVER_ERROR`  |
| `503 Service Unavailable`   | The service is unavailable.                                                                          | `SERVICE_UNAVAILABLE`    |

## Error samples

The following examples show common error scenarios for the Orders v2 API. Each sample includes a request and the corresponding error response.

### Internal server error (500)

The Orders v2 API returns a `500` status code when the server encounters an unexpected condition. The following sample shows a response when the server has an underlying issue or does not handle an internal exception.

#### Create order request

```bash theme={null}
curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/ \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-d '{
    "intent": "CAPTURE",
    "purchase_units": [
        {
            "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f7b",
            "amount": {
                "currency_code": "USD",
                "value": "10.00"
            }
        }
    ],
    "payment_source": {
        "paypal": {
            "address": {
                "address_line_1": "2211 N First Street",
                "address_line_2": "17.3.160",
                "admin_area_1": "CA",
                "admin_area_2": "San Jose",
                "postal_code": "95131",
                "country_code": "US"
            },
            "email_address": "johndoe@paypal.com",
            "payment_method_preference": "IMMEDIATE_PAYMENT_REQUIRED",
            "experience_context": {
                "return_url": "https://example.com/returnUrl",
                "cancel_url": "https://example.com/cancelUrl"
            }
        }
    }
}'
```

#### Error response

```json theme={null}
{
  "name": "INTERNAL_SERVER_ERROR",
  "message": "An internal server error has occurred.",
  "debug_id": "90957fca61718",
  "links": [
    {
      "href": "https://developer.paypal.com/api/orders/v2/#error-INTERNAL_SERVER_ERROR",
      "rel": "information_link",
      "method": "GET"
    }
  ]
}
```

### Unprocessable entity error (422)

The Orders v2 API returns a `422` status code when an order fails business validation. For example, this can happen if the payer uses an expired payment card.

The following sample shows a create order request with an expired card and the resulting error response.

#### Create order request

```bash theme={null}
curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/ \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-d '{
    "intent": "AUTHORIZE",
    "purchase_units": [
        {
            "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
            "amount": {
                "currency_code": "USD",
                "value": "100.00"
            }
        }
    ],
    "payment_source": {
        "card": {
            "number": "4111111111111111",
            "expiry": "2010-02",
            "name": "John Doe",
            "billing_address": {
                "address_line_1": "2211 N First Street",
                "address_line_2": "17.3.160",
                "admin_area_1": "CA",
                "admin_area_2": "San Jose",
                "postal_code": "95131",
                "country_code": "US"
            },
            "stored_credential": {
                "payment_initiator": "MERCHANT",
                "payment_type": "ONE_TIME",
                "usage": "SUBSEQUENT"
            }
        }
    }
}'
```

#### Error response

```json theme={null}
{
    "name": "UNPROCESSABLE_ENTITY",
    "details": [
        {
            "field": "/payment_source/card/expiry",
            "location": "body",
            "issue": "CARD_EXPIRED",
            "description": "The card is expired."
        }
    ],
    "message": "The requested action could not be performed, semantically incorrect, or failed business validation.",
    "debug_id": "866780170332c",
    "links": [
        {
            "href": "https://developer.paypal.com/docs/api/orders/v2/#error-CARD_EXPIRED",
            "rel": "information_link",
            "method": "GET"
        }
    ]
}
```

### Bad request (400)

The Orders v2 API returns a `400` status code when a request includes an incorrect or unsupported value. The following sample shows a create order request with an invalid `usage_pattern` and the resulting error response.

#### Create order request

```bash theme={null}
curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/ \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-d '{
    "intent": "CAPTURE",
    "purchase_units": [
        {
            "reference_id": "PUHF",
            "amount": {
                "currency_code": "USD",
                "value": "10.00"
            }
        }
    ],
    "payment_source": {
        "paypal": {
            "attributes": {
                "customer": {
                    "id": "jd120252fg4dm"
                },
                "vault": {
                    "confirm_payment_token": "ON_ORDER_COMPLETION",
                    "usage_type": "MERCHANT",
                    "usage_pattern": "IMM3DI4T3"
                }
            }
        }
    }
}'
```

#### Error response

```json theme={null}
{
  "name": "INVALID_REQUEST",
  "message": "Request is not well-formed, syntactically incorrect, or violates schema.",
  "debug_id": "10398537340c8",
  "details": [
    {
      "field": "/payment_source/paypal/attributes/vault/usage_pattern",
      "value": "IMM3DI4T3",
      "location": "body",
      "issue": "INVALID_PARAMETER_VALUE",
      "description": "A parameter value is not valid."
    }
  ],
  "links": [
    {
      "href": "https://developer.paypal.com/docs/api/orders/v2/#error-INVALID_PARAMETER_VALUE",
      "rel": "information_link"
    }
  ]
}
```

### Forbidden (403)

The Orders v2 API returns a `403` status code when the API caller or payee does not have the required permissions for the request. The following sample shows a create order request that sets `items.category` to `DONATION` without the necessary permissions.

#### Create order request

```bash theme={null}
curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/ \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-d '{
    "intent": "CAPTURE",
    "purchase_units": [
        {
            "amount": {
                "currency_code": "USD",
                "value": "5.00",
                "breakdown": {
                    "item_total": {
                        "currency_code": "USD",
                        "value": "5.00"
                    }
                }
            },
            "items": [
                {
                    "name": "Donation to WWF",
                    "unit_amount": {
                        "currency_code": "USD",
                        "value": "5.00"
                    },
                    "quantity": "1",
                    "category": "DONATION"
                }
            ]
        }
    ]
}'
```

#### Error response

```json theme={null}
{
  "name": "NOT_AUTHORIZED",
  "details": [
    {
      "issue": "PERMISSION_DENIED_FOR_DONATION_ITEMS",
      "description": "The API Caller or Payee have not been granted appropriate permissions to send 'items.category' as 'DONATION'. Please speak to your account manager if you want to process these type of items."
    }
  ],
  "message": "Authorization failed due to insufficient permissions.",
  "debug_id": "90957fca61718",
  "links": [
    {
      "href": "https://developer.paypal.com/api/orders/v2/#error-PERMISSION_DENIED_FOR_DONATION_ITEMS",
      "rel": "information_link",
      "method": "GET"
    }
  ]
}
```


# Resource not found
Source: https://docs.paypal.ai/developer/how-to/api/troubleshooting/common-errors/resource-not-found



A `RESOURCE_NOT_FOUND` error occurs when the specified resource does not exist. The following issues can cause this error.
If an issue persists or you have further questions, contact [PayPal Support](https://www.paypal.com/us/cshelp/technical).

<Heading>
  INVALID\_RESOURCE\_ID
</Heading>

Returns from the Payments v1 or Orders v2 APIs.

| Cause                                                                                                                                                                                                                                                       | Impact                                                                                 | Resolution                                                                                                                                                                                                             |
| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - You entered an incorrect or malformed resource ID, so the system cannot find the resource. <br /> - You used a resource ID in the API request that does not exist in the system. <br /> - The API caller does not have permission to access the resource. | PayPal stops the payment and does not process the order. This slows down the purchase. | - Check that the resource ID in the API request is correct and exists in the system. Fix any typos or mistakes. <br /> - Make sure the API caller has permission to access the resource. Update permissions if needed. |


# Unprocessable entity
Source: https://docs.paypal.ai/developer/how-to/api/troubleshooting/common-errors/unprocessable-entity



PayPal cannot process your request because it is incorrect or fails business rules. The issues below can cause an `UNPROCESSABLE_ENTITY` error.

If an issue persists or you have further questions, contact [PayPal support](https://www.paypal.com/us/cshelp/technical).

<Heading>
  AGREEMENT\_ALREADY\_CANCELLED
</Heading>

Returns from the Billing Agreements API.

| Cause                                                                                                                                                                                                                                                                                                                                                                    | Impact                                                                                                                                                                                                                                                                                                                                                                                    | Resolution                                                                                                                                                                                                                                                                                                                                                                 |
| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Previously canceled: The payer performed an API call to modify, execute, or otherwise interact with a previously canceled billing agreement. <br /> - Oversight: The payer misunderstood the current agreement status. <br /> - Business logic error: The system that is integrated with the API improperly checked the agreement status before attempting operations. | - Operations failure: The payer potentially cannot perform operations, such as processing payments, on the canceled agreement. <br /> - Service disruption: Unintended or improperly communicated canceled billing agreements can disrupt service or billing processes. <br /> - Payer dissatisfaction: Repeated transaction failures can lead to frustration and confusion among payers. | - Verify agreement status: Confirm the canceled status of the billing agreement. <br /> - Review business logic: Ensure that the integrated system properly checks the status before attempting operations. <br /> - Communicate with payers: Inform the payer about the unintended canceled billing agreement to resolve issues. <br /> - Create a new billing agreement. |

<Heading>
  BILLING\_AGREEMENT\_NOT\_FOUND
</Heading>

Returns from the Billing Agreements API.

| Cause                                                                                                                                                                                                                                                                        | Impact                                                                                                                                               | Resolution                                                                                                                                                                                                                                                                                                                                       |
| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Incorrect billing agreement ID: The ID in the API request is incorrect. <br /> - Improper billing agreement: The API request uses a missing billing agreement. <br /> - Permission issue: The requesting account lacks permissions to manage the billing agreement. <br /> | - Disrupted workflows: Workflows that use the billing agreement ID can be disrupted, which can lead to failures in other business operations. <br /> | - Verify billing agreement ID: Ensure the accuracy of the billing agreement ID in the API request. <br /> - Check agreement status: Confirm that the billing agreement ID belongs to an active billing agreement. <br /> - Elevate permission: Ensure that the requesting account holds appropriate permissions to manage the billing agreement. |

<Heading>
  CANNOT\_PAY\_SELF
</Heading>

Returns from the Billing Agreements API.

| Cause                                                                                                                                                      | Impact                                                                                                                                                                                                                                                                             | Resolution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| :--------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Duplicate reference: The transaction or billing agreement attempts to reference the sender and receiver of payment as the same entity, which is invalid. | - Disrupted workflows: Intended payments or subscription setup fail, leading to unprocessable billing agreements and transactions. <br /> - Disrupted revenue: Failed processes can lead to disruption of automated systems that use billing agreements and ongoing subscriptions. | - Confirm separation: Ensure that the sender and receiver are different entities. <br /> - Review API request: Ensure you use distinct PayPal account IDs or email addresses for the sender and receiver. <br /> - Implement validation checks: Ensure that your application checks to prevent users from setting up billing agreements with duplicate entities. <br /> - Verify account details: Ensure that your application uses the correct account details for transactions and billing agreements. <br /> - Implement retry mechanism: Develop business logic that waits a short period before attempting the request again, gradually increasing the wait time with each attempt. |

<Heading>
  CARD\_EXPIRED
</Heading>

Returns from the PayPal Orders v2 or Payments v1 APIs.

| Cause                                                                                                                                                          | Impact                                                                                     | Resolution                                                                                                                                                                                 |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - You tried to pay with an expired card. <br /> - An expired card cannot be used for payments. <br /> - The payer must use a different card or payment method. | PayPal stops the payment. The payer cannot finish the purchase. This can cause lost sales. | - Show an error message that the card is expired. <br /> - Ask the payer to use a different card or payment method. <br /> - Help the payer switch payment methods and finish the payment. |

<Heading>
  CURRENCY\_NOT\_SUPPORTED
</Heading>

Returns from the Billing Agreements API.

| Cause                                                                                                                                                                                                                                                                                                           | Impact                                                                                                                                                                                                                        | Resolution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Unsupported code: PayPal does not support the currency code in the API request. <br /> - Region limitations: The region from which the API was initiated may not support the currency code. <br /> - Account restrictions: The merchant account may have restrictions or limitations on supported currencies. | - Process failure: The billing agreement fails due to the use of unsupported currencies. <br /> - Revenue loss: Subscriptions or recurring payments do not proceed due to this error, causing delays or issues for the payer. | - Verify currency support: Confirm that PayPal supports the currency code. <br /> - Verify currency settings: Confirm that your PayPal business account can use the necessary [currencies](https://developer.paypal.com/docs/reports/reference/paypal-supported-currencies/). <br /> - Cross-check regional restrictions: Ensure that your region does not restrict the currency used in your transaction or billing agreement. <br /> - Change currency codes: Change the currency code used in your API request to a supported currency for your location or account. |

<Heading>
  DUPLICATE\_INVOICE\_ID
</Heading>

Returns from the Billing Agreements API.

| Cause                                                                                                                                                                                                                                                                                                         | Impact                                                                                                                                 | Resolution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Duplicate invoice ID: The API request uses a duplicate invoice ID. All transactions and billing agreements require a unique `invoice_id`. <br /> - Reused invoice ID: The transaction or billing agreement uses a processed invoice ID typically due to a logic error or failure to manually update the ID. | - Rejected requests: The system prevents the completion of billing operations, potentially affecting liquidity and payer satisfaction. | - [Contact customer support](https://www.paypal.com/us/cshelp/contact-us): If your workflow requires duplicate invoice IDs, contact customer support. <br /> - Confirm invoice usage: Confirm the use of unique invoice IDs in your billing agreements and transactions. <br /> - Implement invoice ID mechanisms: Develop logic that generates a unique invoice ID for each transaction and billing agreement. <br /> - Incorporate logs: Track and verify invoice IDs in the application to prevent reuse and assist with future debugging. |

<Heading>
  INSTRUMENT\_DECLINED
</Heading>

Returns from the Billing Agreements API.

| Cause                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Impact                                                                                                                                                                                                                                                                                                                            | Resolution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Billing address issues: PayPal could not confirm the billing address for the payment method. <br /> - Expired card: The payer used an expired or canceled payment instrument, such as a credit card. <br /> - Declined transaction: The bank or card issuer declined the transaction due to reasons such as suspected fraud or account restrictions. <br /> - Potential risk: The payer account may have insufficient funds, may pose a risk, or may have encountered a compliance issue. <br /> - Incorrect billing information: The user entered incorrect information, such as CVV, expiration date, or account number. | - Payment failure: The payer cannot complete the payment, potentially affecting their access to services or products. <br /> - Payer dissatisfaction: Repeated transaction failures can lead to frustration among payers. <br /> - Revenue loss: The merchant may experience a loss of revenue due to unsuccessful transactions.​ | - Verify payment method: Ensure that the payer uses a valid, active, and sufficiently funded payment method. <br /> - Fund availability: Confirm with the payer that their account holds sufficient funds or is within their credit limit. <br /> - Contact financial institution: Encourage payers to contact their bank or card issuer to resolve any temporary holds or restrictions. <br /> - Update billing instrument: If the payer used an expired or invalid instrument, ask the payer to update their payment information. |

<Heading>
  MERCHANT\_NOT\_ENABLED\_FOR\_REFERENCE\_TRANSACTION
</Heading>

Returns from the Billing Agreements API.

| Cause                                                                                                                                                                                                                    | Impact                                                                                                                                                                                                                                    | Resolution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Improper configuration: The merchant account did not enable or properly configure reference transactions. <br /> - Permission issue: The requesting account lacks permissions to manage reference transactions. <br /> | - Disrupted workflows: The merchant cannot process future payments from the payer without manually acquiring authorization again. <br /> - Disrupted revenue: Additional authorization requests can impact post-purchase revenue streams. | - Contact customer support: Send a request to customer support to enable reference transactions for your account. Enabling reference transactions may require you to provide additional information about your account. For more information, see [Initiate future transactions](https://developer.paypal.com/docs/checkout/advanced/customize/reference-transactions/). <br /> - Verify configurations: Ensure that you configured your account settings to support reference transactions. PayPal may request additional information regarding your account to enable this feature. For more information, see [Initiate future transactions](https://developer.paypal.com/docs/checkout/advanced/customize/reference-transactions/). |

<Heading>
  NOT\_ENABLED\_FOR\_CHANNEL\_INITIATED\_BILLING
</Heading>

Returns from the Billing Agreements API.

| Cause                                                                                                                                                                                                                                                                                                                                                                           | Impact                                                                                                                                                                                                                                   | Resolution                                                                                                                                                                                                                                            |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - No approval: The merchant did not request or was not approved for channel-initiated billing. <br /> - Improper configuration: The merchant account settings do not include necessary features, configurations, or permissions. <br /> - Account restrictions or limitations: The merchant account may have restrictions or limitations based on their account type or region. | - Process failure: The merchant cannot create or manage their billing agreement. <br /> - Revenue loss: Subscriptions, recurring payments, or other functionality reliant on channel-initiated billing do not proceed due to this error. | - Contact customer support: Work with customer support or your account manager to inquire about enabling channel-initiated billing support. <br /> - Review account settings: Ensure that your account settings support the desired billing features. |

<Heading>
  ORDER\_ALREADY\_AUTHORIZED
</Heading>

Returns from the Payments v2 or Orders v2 APIs.

| Cause                                                                                                                                                                                                                                                       | Impact                                                                                   | Resolution                                                                                                                                                                                                                                                                              |
| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - You already authorized this PayPal order. <br /> - You can only authorize an order once with `intent="AUTHORIZE"`. <br /> - Duplicate requests may happen if you missed the first response. <br /> - Network issues or delays may cause missed responses. | PayPal declines the second authorization. You cannot split the authorization into parts. | - Authorize the full order amount in one request, then make multiple captures if needed. <br /> - Set `final_capture="false"` in capture requests for split shipments. <br /> - Use PayPal webhooks to track order status. <br /> - If your API call times out, contact PayPal support. |

<Heading>
  ORDER\_ALREADY\_CAPTURED
</Heading>

Returns from the Orders v2 API.

| Cause                                                                                                                                                                                                      | Impact                                                                                                                                                               | Resolution                                                                                                                                                                                                     |
| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - You already captured this order. Payment is complete. <br /> - You can only capture an order once with `intent="SALE"`. <br /> - Duplicate requests may happen if you missed the first capture response. | If you only captured part of the amount, you cannot capture the rest unless you create a new order. <br /> - If you meant to capture once, there is no payer impact. | - Use `intent="AUTHORIZE"` if you need to capture more than once. <br /> - For single captures, make sure you record the API response to avoid duplicates.<br />- Use PayPal webhooks to track payment status. |

<Heading>
  ORDER\_NOT\_APPROVED
</Heading>

Returns from the Payments v1 or Orders v2 APIs.

| Cause                                                                                                   | Impact                                                                                     | Resolution                                                                                                                                         |
| :------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- |
| - The payer did not approve the payment. <br /> - The request may not include a valid `payment_source`. | PayPal declines the payment. The payment does not go through. This can delay the purchase. | - Send the payer to the approval URL (`rel:approve`) from the Create Order call. <br /> - Make sure the request includes a valid `payment_source`. |

<Heading>
  PAYER\_ACCOUNT\_LOCKED\_OR\_CLOSED
</Heading>

Returns from the Billing Agreements API.

| Cause                                                                                                                                                                                                                                                                                                                                 | Impact                                                                                                                                                                                                                                                 | Resolution                                                                                                                                                                                                                                                |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Account lock: Violation of [PayPal’s Acceptable Use Policy](https://www.paypal.com/us/legalhub/paypal/acceptableuse-full) due to suspicious activities can lead to an account lock or security concerns. <br /> - Account closure: The payer or PayPal closed the account due to policy violations or other administrative reasons. | - Billing agreement failure: This error prevents payers from creating or processing billing agreements and their associated transactions. <br /> - Service operations: Merchants and payers can experience service loss, which can cause revenue loss. | - [Contact customer support](https://www.paypal.com/us/cshelp/contact-us): Work with customer support to resolve the issue. <br /> - Settle account: Resolve debts or disputes that led to the account lock or closure, then retry the billing agreement. |

<Heading>
  PAYER\_CANNOT\_PAY
</Heading>

Returns from the Billing Agreements API.

| Cause                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Impact                                                                                                                                                                                                                                                                                                                           | Resolution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Insufficient funds: The payer does not have enough available funds or credit. <br /> - Account limitations: The payer's account may have limitations or restrictions. <br /> - Unverified account: The payer uses an unverified account or did not perform required updates, which prevents payments. <br /> - Payment method issue: The payer used an expired or canceled payment instrument, such as a credit card. <br /> - Account restrictions: The payer account encounters a compliance issue or external issue that restricts payment processing. | - Payment failure: The payer cannot complete the payment, potentially affecting their access to services or products. <br /> - Payer dissatisfaction: Repeated transaction failures can lead to frustration among payers. <br /> - Revenue loss: The merchant may experience a loss of revenue due to unsuccessful transactions. | - Check account status: Verify that both the payer's and merchant's PayPal accounts are in good standing without any limitations or restrictions. <br /> - Verify payment method: Ensure that the payer uses a valid, active, and sufficiently funded payment method. <br /> - Configure alternative payment options: Suggest that the payer use a different payment method. <br /> Update account info: Ensure that the payer includes up-to-date account information, such as billing address and linked payment methods. |

<Heading>
  PAYEE\_NOT\_ENABLED\_FOR\_CARD\_PROCESSING
</Heading>

Returns from the Orders v2 API.

| Cause                                                                                                                                   | Impact                                                                                                                                                       | Resolution                                                                                                                                                          |
| :-------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| - The payee's account is not set up to take card payments. <br /> - The payee has not finished onboarding for PayPal Complete Payments. | PayPal stops the payment. The payer cannot finish the purchase. This can cause lost sales. <br /> - All payers trying to pay this payee will see this error. | - Make sure the payee finished onboarding and enabled card payments. <br /> - If the payee manages onboarding, ask them to contact PayPal to turn on card payments. |

<Heading>
  PREVIOUS\_REQUEST\_IN\_PROGRESS
</Heading>

Returns from the Billing Agreements API.

| Cause                                                                                                                                                                                 | Impact                                                                                                                                                                                                                                                 | Resolution                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Request conflict: Multiple requests conflict for the same resource, such as a billing agreement. PayPal requires the initial request to complete before processing another request. | - Operation hold: Multiple requests cause a halt on new operations on the affected resource until the resource processes the original request. <br /> - Processing delay: Multiple requests can delay planned modifications or renewals of a resource. | - Verify request status: Check the status of the previous request to ensure its completion before initiating a new request. <br /> - Queue requests: Process requests sequentially in a queue, allowing each request to complete before initiating the next request. <br /> - Implement error handling: Develop business logic to handle this error and respond appropriately, such as notifying users of the delay or logging the error for further analysis. |

<Heading>
  REDIRECT\_PAYER\_FOR\_ALTERNATE\_FUNDING
</Heading>

Returns from the Payments v1, and Orders v2 APIs.

| Cause                                                                             | Impact                                                                                     | Resolution                                                                                                                                                                                                                                    |
| :-------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - The payment failed because of a problem with the payer's chosen payment method. | PayPal stops the payment. The payer cannot finish the purchase. This can cause lost sales. | - Show an error message that the payment did not go through. <br /> - Send the payer to PayPal checkout to pick another payment method. <br /> - If the problem continues, ask the payer to use a different payment method or contact PayPal. |

<Heading>
  REDIRECT\_PAYER\_FOR\_ALTERNATE\_FUNDING
</Heading>

Returns from the Billing Agreements API.

| Cause                                                                                                                                                                                                                                                                                                                                                                                                            | Impact                                                                                                                                                                                                                                       | Resolution                                                                                                                                                                                                                                                                   |
| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Insufficient funds: The payer's account may not have enough funds or credit to cover the transaction amount. <br /> - Payment method issue: The payment instrument, such as a credit card, is expired or canceled. <br /> - Account limitations: The payer's PayPal account might have limitations or restrictions. <br /> - Unsupported method: The transaction does not support the selected payment method. | - Incomplete transactions: The payer cannot complete the transaction with the selected payment method. <br /> - User experience impact: Reselecting a payment method can add additional steps for the user and delay transaction processing. | - Change payment method: Inform the user to change their payment method, then retry the transaction. <br /> - Implement alternative payment mechanism: If supported, develop business logic that redirects users to alternative payment methods, then retry the transaction. |

<Heading>
  REFERENCED\_CARD\_EXPIRED
</Heading>

Returns from the Orders v2 or Vault v3 APIs.

| Cause                                                                                                                                  | Impact                                                                                     | Resolution                                                                                                                                                                                                                                                                    |
| :------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - The transaction uses a saved payment token, but the card is expired. <br /> - The payer must use a different card or payment method. | PayPal stops the payment. The payer cannot finish the purchase. This can cause lost sales. | - Turn on Real-Time Account Updater (RTAU) to keep card expiration dates up to date. <br /> - Show an error message if the saved card is expired. <br /> - Update the saved payment token after you get a new one. <br /> - Give the payer clear steps to finish the payment. |

<Heading>
  SHIPPING\_ADDRESS\_INVALID
</Heading>

Returns from the Payments v1 or Orders v2 APIs.

| Cause                                                                                                                                                        | Impact                                                                                     | Resolution                                                                                                                                                                                   |
| :----------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Some address fields are missing or incomplete. <br /> - The address format is wrong. <br /> - System issues prevent the address from being sent correctly. | PayPal declines the payment. The payment does not go through. This can delay the purchase. | - Check that all required address fields are filled in. <br /> - Use address validation tools to fix the format. <br /> - Make sure your system sends all address fields in the API request. |

<Heading>
  SHIPPING\_ADDRESS\_INVALID
</Heading>

Returns from the Billing Agreements API.

| Cause                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Impact                                                                                                                                                                                                                                                       | Resolution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| - Incorrect formatting: The API request's shipping address fields (such as street, city, state, postal code, and country) contain formatting errors or invalid characters. <br /> - Missing fields: The API request does not contain required shipping address fields. <br /> - Validation failure: The address does not match the standards or validation rules set by PayPal or the postal service of the specified country. <br /> - Mismatch: The country code and the country name provided may mismatch, causing the error. | - Process failure: The billing agreement, transaction, or subscription setup will not proceed. <br /> - Workflow disruption: Delays in processing payments or setting up recurring billing agreements can impact payer satisfaction and business operations. | - Verify fields: Verify that all required fields in the shipping address use correct formatting. <br /> - Match address: Ensure that the address fields, such as street, city, state, postal code, and country, match the expected format for the specified country. <br /> - Verify country code: Ensure that the country code matches the country name, using address validation tools or services to confirm its accuracy. <br /> - Revise address: Contact the payer to correct or confirm the address details. |

<Heading>
  TOKEN\_ID\_NOT\_FOUND
</Heading>

Returns from the Payments v1 or Orders v2 APIs.

| Cause                                                                                                                        | Impact                                                                                     | Resolution                                                                                                                                                                 |
| :--------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - PayPal does not recognize the token ID. <br /> - The token may be wrong, mistyped, or the caller does not have permission. | PayPal stops the payment. The payer cannot finish the purchase. This can cause lost sales. | - Make sure the receiving account gave the needed permissions. <br /> - Check that the token ID is correct. <br /> - If the token is wrong or expired, create a new token. |

<Heading>
  TRANSACTION\_REFUSED
</Heading>

Returns from the Billing Agreements API.

| Cause                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Impact                                                                                                                                                                                                                                                                                                                           | Resolution                                                                                                                                                                                                                                                                                                                                                                               |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Payment method issues: The payment method linked to the billing agreement might be invalid, expired, or otherwise unable to process the payment.​ <br /> - Insufficient funds: The payer's account may not have enough funds or credit to cover the transaction amount. <br /> - Account limitations: The payer's PayPal account might have limitations or restrictions. <br /> - Risk factors: If PayPal detects any potential risks based on merchant history or if there's high risk associated with the transaction, PayPal will refuse the transaction. | - Payment failure: The payer's failure to complete the payment can potentially affect their access to services or products. <br /> - Payer dissatisfaction: Repeated transaction failures can lead to payer frustration. <br /> - Revenue loss: The merchant may experience a loss of revenue due to unsuccessful transactions.​ | - Verify payment method: Ensure that the payer uses a valid, active, and sufficiently funded payment method. <br /> - Check account status: Verify that both the payer's and merchant's PayPal accounts operate in good standing without any limitations or restrictions. <br /> - Correct API request: Double-check the API request parameters to ensure they are correct and complete. |

<Heading>
  UNSUPPORTED\_PAYEE\_CURRENCY
</Heading>

Returns from the Billing Agreements API.

| Cause                                                                                                                                                                                                                                                                                                                                                                                 | Impact                                                                                                                                                                                                                                                                            | Resolution                                                                                                                                                                                                                                                                                                                                     |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Account restrictions: The payee account restrictions permit only transactions in certain currencies. <br /> - Disabled currency: The payee did not enable the specified currency in their account settings. <br /> - Region limitations: Certain regions do not make available specific currencies for the merchant account, resulting in a currency mismatch during a transaction. | - Process failure: The merchant cannot create or manage their billing agreement. <br /> - Impacted business operations: PayPal does not record failed transactions, which prevents tracking of fund transfer issues and could impact subscription services or billing agreements. | - Confirm that PayPal supports the currency code. <br /> - Configure account: Ensure that you have enabled the specified currency in your account settings to accept payment from the payee account. <br /> - Currency conversion: Consider using a supported currency or handle currency conversion with PayPal currency conversion services. |


# Unsupported payee currency
Source: https://docs.paypal.ai/developer/how-to/api/troubleshooting/common-errors/unsupported-payee-currency



Returns from the Payments V1 API.

`UNSUPPORTED_PAYEE_CURRENCY` indicates that the payee's PayPal account does not support the currency specified in the transaction, and the payee cannot accept payments.

| Cause                                                                                                                                                                                                                                                                                                                                                                                 | Impact                                                                                                                                                                                                      | Resolution                                                                                                                                                                                                                                                                                                                           |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Account restrictions: The payee account restrictions permit only transactions in certain currencies. <br /> - Disabled currency: The payee did not enable the specified currency in their account settings. <br /> - Region limitations: Certain regions do not make available specific currencies for the merchant account, resulting in a currency mismatch during a transaction. | - Failed payment attempt: The transaction cannot be completed using the specified currency. <br /> - Customer dissatisfaction: Unprocessable payments can cause inconvenience for both the payer and payee. | - Verify supported currencies: Change the currency code in your API request to a [supported currency](https://developer.paypal.com/docs/reports/reference/paypal-supported-currencies/) for the payee account. <br /> - Contact payee: Communicate with the payee to confirm their account settings and the currencies they enabled. |


# Validation error
Source: https://docs.paypal.ai/developer/how-to/api/troubleshooting/common-errors/validation-error



You get a validation error when the API request contains invalid, missing, or incorrectly formatted data. This error can return from the [Orders v2](https://developer.paypal.com/docs/api/orders/v2/) or [Payments v1](https://developer.paypal.com/docs/api/payments/v1/) APIs.

If an issue persists or you have further questions, contact [PayPal support](https://www.paypal.com/us/cshelp/technical).

| Cause                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Impact                                                                                                                     | Resolution                                                                                                                                                                                                                                                                         |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Required fields are missing or contain incorrect values. <br /> - Field values do not match expected data types. <br /> - Currency codes are invalid or the amount formatting is incorrect. <br /> - The request body is not properly formatted as JSON. <br /> - The transaction is blocked based on the account's status or configuration. <br /> - An incorrect or outdated API version is used. Some validation rules may change between versions. | The payment process stops, and the payer cannot complete the purchase. This can result in lost sales if not fixed quickly. | - Check the error details in the API response to find the exact field and issue. <br /> - Ensure all required fields are there and contain valid data in the correct format and type. <br /> - Update the request with correct data and resend it to allow the payment to process. |


# Handling payment failures with PayPal
Source: https://docs.paypal.ai/developer/how-to/api/troubleshooting/handling-payment-failures-with-paypal



Detect and respond to payment failures using PayPal's Orders v2 API and Subscriptions API. This guide explains common failure reasons, how to surface errors to buyers, best practices for retrying or recovering failed payments, and how to leverage PayPal's intelligent retry mechanism.

## Key concepts

* Payment failures can happen for many reasons, such as declined cards, expired payment methods, insufficient funds, risk restrictions, or business validation errors.
* PayPal's APIs (Orders v2 and Subscriptions) return clear error codes and messages in their responses.
* Proper handling improves user experience, reduces lost sales, and ensures smooth subscription renewals.
* Some payment failures are asynchronous, meaning they might not be immediately apparent during the initial transaction.

## Common payment failure scenarios

Here are some of the most frequent failure reasons and how to handle them:

| Error Code / Issue                         | What It Means                                                                           | What To Do                                                                                                                  |
| :----------------------------------------- | :-------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------- |
| `INSTRUMENT_DECLINED`                      | Payment method was declined.                                                            | Prompt the buyer to select a different payment method. Restart the payment flow using `actions.restart()`.                  |
| `CARD_EXPIRED`                             | Card is expired.                                                                        | Inform the buyer and ask for a new card.                                                                                    |
| `AMOUNT_MISMATCH`, `ITEM_TOTAL_MISMATCH`   | Totals do not add up.                                                                   | Fix item or amount totals in your API request and retry.                                                                    |
| `CURRENCY_NOT_SUPPORTED`                   | Unsupported currency.                                                                   | Use a supported currency or update your PayPal account settings.                                                            |
| `ORDER_NOT_APPROVED`                       | Buyer did not approve the order.                                                        | Redirect the buyer to approve the order again.                                                                              |
| `MAX_NUMBER_OF_PAYMENT_ATTEMPTS_EXCEEDED`  | Too many failed attempts.                                                               | Ask the buyer to use a different payment method or contact PayPal support.                                                  |
| `REDIRECT_PAYER_FOR_ALTERNATE_FUNDING`     | Funding source failed, alternate source needed.                                         | Prompt the buyer to choose a different payment method.                                                                      |
| `VALIDATION_ERROR`, `UNPROCESSABLE_ENTITY` | Invalid or missing data.                                                                | Show a clear error, ask the buyer to correct the information, and retry.                                                    |
| `PAYMENT_DENIED`                           | The payment was denied by PayPal.                                                       | Investigate the reason for denial and contact PayPal support if needed. Prompt the buyer to use a different payment method. |
| `PAYER_CANNOT_PAY`                         | The payer is unable to pay using the selected payment method.                           | Prompt the buyer to select a different payment method or contact PayPal support.                                            |
| `CANNOT_BILL_PAST_DUE_BALANCE`             | The subscription is suspended because the past due balance exceeds the maximum allowed. | Contact PayPal support to resolve the suspension or prompt the buyer to pay the outstanding balance.                        |
| `REJECTED_DUE_TO_RISK_REVERSAL`            | The payment was rejected due to a risk reversal, such as a chargeback or dispute.       | Investigate the reason for the reversal and contact PayPal support if needed.                                               |
| `TRANSACTION_REFUSED`                      | The transaction was refused by the processor.                                           | Prompt the buyer to use a different payment method or contact their bank.                                                   |
| `INVALID_ACCOUNT_STATUS`                   | The payer's account is in an invalid state, such as locked or inactive.                 | Prompt the buyer to contact PayPal support to resolve their account issue.                                                  |
| `INVALID_REQUEST`                          | The request was malformed or missing required parameters.                               | Review the request parameters and ensure they are valid.                                                                    |
| `AUTHENTICATION_FAILURE`                   | Authentication failed due to invalid credentials.                                       | Verify your API credentials and ensure they are correct.                                                                    |
| `NOT_AUTHORIZED`                           | You are not authorized to perform this action.                                          | Check your account permissions and ensure you have the necessary privileges.                                                |
| `RESOURCE_NOT_FOUND`                       | The requested resource was not found.                                                   | Verify the resource ID and ensure it exists.                                                                                |
| `UNPROCESSABLE_ENTITY`                     | The request was well-formed but could not be processed due to semantic errors.          | Review the request data and ensure it is valid and consistent.                                                              |

See the [Orders v2 API Troubleshooting Guide](https://developer.paypal.com/api/rest/integration/orders-api/troubleshooting/) and the [Subscriptions API documentation](https://developer.paypal.com/docs/subscriptions/) for a more comprehensive list of error codes.

## Detect and handle payment failures

### 1. Check API responses

* Always inspect responses from the Orders API (create, authorize, or capture endpoints) or the Subscriptions API (create, update, or activate subscription endpoints).
* If the response contains an error code, use it to determine the next step.

**Example: Handling a Declined Payment in JavaScript (Orders API)**

<Tabs>
  <Tab title="Vanilla JS">
    ```javascript theme={null}
    paypal.Buttons({
      onApprove: (data, actions) => {
        return actions.order.capture().then(details => {
          // Payment successful
        }).catch(err => {
          // Handle payment failure
          if (err.name === "INSTRUMENT_DECLINED") {
            // Restart the payment flow to let buyer choose another method
            return actions.restart();
          } else {
            // Show a generic error message
            alert("Payment could not be completed. Please try again.");
          }
        });
      }
    }).render('#paypal-button-container');
    ```
  </Tab>

  <Tab title="React (JS)">
    ```javascript theme={null}
    import React, { useEffect } from 'react';

    function PayPalButton() {
      useEffect(() => {
        paypal.Buttons({
          onApprove: (data, actions) => {
            return actions.order.capture().then(details => {
              // Payment successful
            }).catch(err => {
              // Handle payment failure
              if (err.name === "INSTRUMENT_DECLINED") {
                // Restart the payment flow to let buyer choose another method
                return actions.restart();
              } else {
                // Show a generic error message
                alert("Payment could not be completed. Please try again.");
              }
            });
          }
        }).render('#paypal-button-container');
      }, []);

      return <div id="paypal-button-container"></div>;
    }

    export default PayPalButton;
    ```
  </Tab>

  <Tab title="React (TS)">
    ```typescript theme={null}
    import React, { useEffect } from 'react';

    function PayPalButton() {
      useEffect(() => {
        (window as any).paypal.Buttons({
          onApprove: (data: any, actions: any) => {
            return actions.order.capture().then((details: any) => {
              // Payment successful
            }).catch((err: any) => {
              // Handle payment failure
              if (err.name === "INSTRUMENT_DECLINED") {
                // Restart the payment flow to let buyer choose another method
                return actions.restart();
              } else {
                // Show a generic error message
                alert("Payment could not be completed. Please try again.");
              }
            });
          }
        }).render('#paypal-button-container');
      }, []);

      return <div id="paypal-button-container"></div>;
    }

    export default PayPalButton;
    ```
  </Tab>

  <Tab title="ES Module">
    ```javascript theme={null}
    paypal.Buttons({
      onApprove: (data, actions) => {
        return actions.order.capture().then(details => {
          // Payment successful
        }).catch(err => {
          // Handle payment failure
          if (err.name === "INSTRUMENT_DECLINED") {
            // Restart the payment flow to let buyer choose another method
            return actions.restart();
          } else {
            // Show a generic error message
            alert("Payment could not be completed. Please try again.");
          }
        });
      }
    }).render('#paypal-button-container');
    ```
  </Tab>
</Tabs>

* `actions.restart()` restarts the payment flow so the buyer can select a different funding source.

### 2. Surface errors to buyers

* Show clear, actionable error messages, such as “Your card was declined. Please try another payment method.”
* For validation or data errors, prompt the buyer to correct the issue and retry.

### 3. Retry or recover

* For funding failures, prompt the buyer to choose another payment method.
* For expired cards or exceeded attempts, ask the buyer to update their information or use a new card.
* For business validation errors, correct the data and resend the request.

## Intelligent retries for subscriptions

PayPal's **intelligent retry** mechanism automatically attempts to recover failed subscription payments.

* When a subscription payment fails, PayPal uses a proprietary algorithm to determine the best time to retry the payment.
* This algorithm considers factors such as the buyer's payment history, risk signals, and bank availability.
* Merchants can configure retry schedules and monitor retry attempts in the PayPal dashboard.
* Intelligent retries can significantly increase subscription renewal rates without requiring any action from the merchant.

## Asynchronous payment processing and webhooks

* Some payment failures are **asynchronous** and might not be immediately reflected in the API response.
* For example, a buyer's bank might initially authorize a payment but later decline it due to fraud concerns.
* To track these asynchronous failures reliably, it's highly recommended to use PayPal Webhooks.

### Relevant webhook events

* **Orders API**
  * `PAYMENT.CAPTURE.COMPLETED`: Indicates a successful payment capture.
  * `PAYMENT.CAPTURE.DENIED`: Indicates a failed payment capture.

* **Subscriptions API**
  * `BILLING.SUBSCRIPTION.PAYMENT.FAILED`: Indicates a failed subscription payment.
  * `BILLING.SUBSCRIPTION.PAYMENT.SUCCEEDED`: Indicates a successful subscription payment.

* Configure your webhook listener to receive these events and take appropriate action (e.g., notify the buyer, update your database).

## Manual retries for subscriptions

In addition to intelligent retries, you can also manually retry failed subscription payments.

* **PayPal Dashboard:** You can retry payments directly from the [PayPal dashboard](https://www.paypal.com/businessmanage/subscriptions).
* **Subscriptions API:** You can use the Subscriptions API to trigger a manual retry.

## Monitor and log failures

* Log all failed payment attempts with error codes and messages for troubleshooting.
* Use PayPal Webhooks to track asynchronous failures and notify your team or the buyer when needed.

## Best practices

* Promptly inform buyers of the failure reason and guide them to resolve it.
* Restart the payment flow for funding source errors using `actions.restart()` in the Smart Buttons integration (for Orders API).
* Validate all order data before sending requests to avoid preventable errors.
* Monitor webhook events for real-time updates on payment status for both Orders and Subscriptions.
* Leverage intelligent retries for Subscriptions to automatically recover failed payments.
* Consider manual retries for Subscriptions if intelligent retries are unsuccessful.
* Test payment failure scenarios during integration to ensure your system handles them correctly.

## Troubleshooting

* **Check the PayPal status page:** Verify that PayPal services are operating normally.
* **Review your API logs:** Look for any errors or warnings in your API requests and responses.
* **Use the PayPal Developer Dashboard:** Monitor your webhook events and API usage.
* **Contact PayPal support:** If you're unable to resolve the issue, contact PayPal support for assistance.

With these steps, you can handle payment failures smoothly, helping buyers complete their purchase, ensuring smooth subscription renewals, and reducing lost sales.

## See also

* [Orders v2 API Reference](/reference/api/rest/orders/create-order)
* [Orders v2 integration documentation](https://developer.paypal.com/api/rest/integration/orders-api/)
* [Common errors for the Orders v2 API](https://developer.paypal.com/api/rest/integration/orders-api/errors/)
* [Troubleshooting errors for the Orders v2 API](https://developer.paypal.com/api/rest/integration/orders-api/troubleshooting/)
* [Handle funding failures for direct merchants](https://developer.paypal.com/docs/checkout/standard/customize/handle-funding-failures/)
* [Handle funding failures for partners](https://developer.paypal.com/docs/multiparty/checkout/standard/customize/handle-funding-failures/)
* [Subscriptions API Reference](https://developer.paypal.com/docs/api/subscriptions/v1/)
* [Subscriptions integration documentation](https://developer.paypal.com/docs/subscriptions/)
* [Subscription payment failures and recovering balances](https://developer.paypal.com/docs/subscriptions/customize/payment-failure-retry/)


# Apps, scopes, and credentials
Source: https://docs.paypal.ai/developer/how-to/apps-scopes-credentials



PayPal Apps are registered apps within the PayPal Developer ecosystem that verify and authorize your software to interact with PayPal's services. Each app receives unique credentials (client ID and client secret) that establish a secure connection between your app and PayPal's payment processing network.

Register your application with PayPal to get the credentials needed for API access and understand which permissions your app requires.

PayPal Apps operate on a modern REST API architecture and follow a structured development process:

* App Registration
* Sandbox Testing
* API Integration

PayPal's sandbox environment provides developers with testing accounts to simulate real payment scenarios without processing actual transactions. PayPal sandbox provides testing environments with two main account types:

## Understanding scopes

Scopes define your app's permissions and access levels to PayPal services. The scope field in the authentication response shows all available permissions for your app.

### Common PayPal API scopes

#### Payment processing

* `https://uri.paypal.com/services/payments/payment/authcapture` - Process payments and captures
* `https://uri.paypal.com/services/payments/payment` - Real-time payment processing
* `https://uri.paypal.com/services/payments/refund` - Process refunds
* `https://uri.paypal.com/services/payments` - General payments API access

#### Vault services

* `https://uri.paypal.com/services/vault/payment-tokens/creditcard` - Store credit card info
* `https://uri.paypal.com/services/vault/payment-tokens/read` - Manage stored credit cards

#### Business services

* `https://uri.paypal.com/services/invoicing` - Create and manage invoices
* `https://uri.paypal.com/services/subscriptions` - Subscription management
* `https://uri.paypal.com/services/payments/payouts` - Send payouts

#### Dispute management

* `https://uri.paypal.com/services/disputes/read-buyer` - Read buyer dispute info
* `https://uri.paypal.com/services/disputes/read-seller` - Read seller dispute info
* `https://uri.paypal.com/services/disputes/update-seller` - Update seller dispute status

#### System integration

* `https://uri.paypal.com/services/webhooks` - Webhook management
* `openid` - OpenID Connect authentication

### PayPal API credentials

PayPal REST APIs use two types of credentials for authentication:

**Client ID**: A public identifier for your PayPal app. Safe to use in client-side code and sufficient for basic payment buttons and card fields.

**Client Secret**: A private key that verifies your app for API calls. Must be kept secure and used only server-side.

### Getting credentials

Obtain credentials through the PayPal Developer Dashboard:

* New accounts get a "Default Application" with ready-to-use credentials

* Create additional apps through "Create App" in Apps & Credentials

* Copy the client ID and client secret for your setup

For detailed implementation guides, refer to each service area's specific PayPal API docs.


# Advanced configuration
Source: https://docs.paypal.ai/developer/how-to/sdk/js/v6/advanced



Advanced configuration options for the JavaScript SDK v6 help you customize the payment experience.

## Prerequisites

Before you integrate:

* Get a [client ID and secret](/developer/how-to/api/get-started#1-get-your-client-id-and-client-secret).
* [Set up the v6 SDK](/developer/how-to/sdk/js/v6/configuration).

## Configure presentation modes and fallback

For advanced use cases, you can choose a [specific presentation mode](/reference/sdk/js/v6/reference#parameters-6). Then, implement your own fallback logic with the `isRecoverable` error property.

```javascript expandable lines theme={null}
// Alternatively, set up a standard PayPal button with a custom order of presentation modes
async function configurePayPalButton(sdkInstance) {
  const paypalPaymentSession = sdkInstance.createPayPalOneTimePaymentSession(
    paymentSessionOptions,
  );

  const paypalButton = document.querySelector("paypal-button");
  paypalButton.removeAttribute("hidden");

  paypalButton.addEventListener("click", async () => {
    const createOrderPromiseReference = createOrder();
    const presentationModesToTry = ["payment-handler", "popup", "modal"];

    for (const presentationMode of presentationModesToTry) {
      try {
        await paypalPaymentSession.start(
          { presentationMode },
          createOrderPromiseReference,
        );
        // Exit early when start() successfully resolves
        break;
      } catch (error) {
        // Try another presentationMode for a recoverable error
        if (error.isRecoverable) {
          continue;
        }
        throw error;
      }
    }
  });
}
```


# Button color updates
Source: https://docs.paypal.ai/developer/how-to/sdk/js/v6/button-color-updates

PayPal button color updates require no JavaScript SDK integration changes.

When PayPal updates its brand guidelines, the PayPal JavaScript SDK v5 and v6 automatically update the appearance of buttons rendered on your site. No code changes are required.

<table>
  <thead>
    <tr>
      <th>Current color</th>
      <th>Current button</th>

      <th />

      <th>New button</th>
      <th>New color</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Gold</strong></td>

      <td>
        <img alt="Current gold PayPal button" />
      </td>

      <td>→</td>

      <td>
        <img alt="New blue PayPal button" />
      </td>

      <td><strong>Blue</strong></td>
    </tr>

    <tr>
      <td><strong>Blue</strong></td>

      <td>
        <img alt="Current blue PayPal button" />
      </td>

      <td>→</td>

      <td>
        <img alt="New blue PayPal button" />
      </td>

      <td><strong>Blue</strong></td>
    </tr>

    <tr>
      <td><strong>Silver</strong></td>

      <td>
        <img alt="Current silver PayPal button" />
      </td>

      <td>→</td>

      <td>
        <img alt="New white PayPal button" />
      </td>

      <td><strong>White</strong></td>
    </tr>

    <tr>
      <td><strong>White</strong></td>

      <td>
        <img alt="Current white PayPal button" />
      </td>

      <td>→</td>

      <td>
        <img alt="New white PayPal button" />
      </td>

      <td><strong>White</strong></td>
    </tr>

    <tr>
      <td><strong>Black</strong></td>

      <td>
        <img alt="Current black PayPal button" />
      </td>

      <td>→</td>

      <td>
        <img alt="New black PayPal button" />
      </td>

      <td><strong>Black</strong></td>
    </tr>
  </tbody>
</table>

## Set your button color

You can set the button color for accessibility or branding reasons. To choose a specific color, apply one of the [supported color classes](/reference/sdk/js/v6/reference#web-components) to your `<paypal-button>` element.

```html theme={null}
<paypal-button type="checkout" class="paypal-blue"></paypal-button>
```

### Ensure accessibility

To comply with [WCAG 2.1 AA standards](https://www.w3.org/TR/WCAG21/):

* On light backgrounds, use the blue or black button.
* On dark backgrounds, use the white button.


# Set up JavaScript SDK v6
Source: https://docs.paypal.ai/developer/how-to/sdk/js/v6/configuration



The PayPal JavaScript SDK v6 enables you to accept the following payment methods on your website:

* PayPal and Pay Later
* Venmo (US only)
* Google Pay
* Apple Pay
* Fastlane guest checkout
* Credit and debit cards

The v6 SDK is faster and more secure than previous versions. It also supports standalone button integrations and iframe-based integrations for stricter security.

<Tip>[Check out a sample integration in GitHub](https://github.com/paypal-examples/v6-web-sdk-sample-integration).</Tip>

## Prerequisites

Before you start, make sure to [get your PayPal client ID and secret](/developer/how-to/api/get-started#1-get-your-client-id-and-client-secret).

If you're a **partner integrating on behalf of other merchants**, follow these additional steps to set up your integration:

* [Onboard as a partner with PayPal](https://developer.paypal.com/docs/multiparty/get-started/)
* [Configure your accounts](https://developer.paypal.com/docs/multiparty/create-account/)
* [Onboard sellers](https://developer.paypal.com/docs/multiparty/seller-onboarding/)
* [Integrate backend with the Orders v2 API](https://developer.paypal.com/docs/multiparty/checkout/advanced/integrate/#integrate-back-end)

## Include the SDK script

Include the v6 SDK script on each page of your site that needs to accept payments.

```html theme={null}
<script src="https://www.paypal.com/web-sdk/v6/core"></script>
```

For sandbox and testing environments:

```html theme={null}
<script src="https://www.sandbox.paypal.com/web-sdk/v6/core"></script>
```

## Authenticate the SDK

Authenticate with a client ID or a client token. Most integrations should authenticate with a client ID.

<Accordion title="Option A: client ID (recommended)">
  ### Option A: client ID (recommended)

  For most integrations, use your PayPal client ID to authenticate the SDK. You can think of the client ID as your application's user name. This static client ID value is safe to include in your front-end code.

  When to use client ID:

  * Standard checkout integrations (PayPal, cards, Venmo, digital wallets)
  * One-time payments
  * Card vaulting (save card payment methods)
  * Most payment integrations (this is the default)

  <Note>
    Select the tab that matches your integration type:

    * **Direct merchants** process payments into their own PayPal account.
    * **Partners** process payments on behalf of other merchants.
  </Note>

  <Tabs>
    <Tab title="Direct merchants">
      Replace `"YOUR_CLIENT_ID"` with your client ID.

      ```javascript lines theme={null}
      const sdkInstance = await window.paypal.createInstance({
        clientId: "YOUR_CLIENT_ID",
        components: ["paypal-payments"],
      });
      ```
    </Tab>

    <Tab title="Partners">
      * Replace `"YOUR_PARTNER_CLIENT_ID"` with your client ID.
      * Replace `"SELLER_MERCHANT_ID"` with the merchant ID of the seller you're creating the payment session for.

      ```javascript lines theme={null}
      const sdkInstance = await window.paypal.createInstance({
        clientId: "YOUR_PARTNER_CLIENT_ID",
        merchantId: "SELLER_MERCHANT_ID",
        components: ["paypal-payments"],
      });
      ```
    </Tab>
  </Tabs>
</Accordion>

<Accordion title="Option B: client token (for Fastlane only)">
  ### Option B: client token

  <Warning>Client token authentication is required for Fastlane integrations. For all other use cases, use **Option A: client ID**.</Warning>

  A client token is a secure, browser-safe access token generated server-side from your PayPal client ID and secret. This call returns an `access_token` which you use as the client token when you initialize the v6 SDK. Use `expires_in` for caching management on the server side.

  <Note>
    Partner calls must include [`PayPal-Auth-Assertion`](/developer/how-to/api/make-api-requests#paypal-auth-assertion) and [`PayPal-Partner-Attribution-Id`](/developer/how-to/api/make-api-requests#paypal-partner-attribution-id) headers.
  </Note>

  <Info>**Endpoint:** `/v1/oauth2/token/`</Info>

  ```bash lines theme={null}
  curl -X POST 'https://api-m.sandbox.paypal.com/v1/oauth2/token' \
  -u 'PAYPAL_CLIENT_ID:PAYPAL_CLIENT_SECRET' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'domains[]=YOUR_URL1_FOR_THE_SESSION,YOUR_URL2_FOR_THE_SESSION' \
  -d 'response_type=client_token'
  ```

  <Accordion title="Sample 200 response">
    ```json lines theme={null}
    {
       "access_token" : "A21AAJrhF-LjFoXzGPJlszGfKg4omnKy5e_eeRXPYzHLb3OdbjtCB3w89nm_6wCCbqn7qSdzjW77VGE7NAJAbXw53ZVpiX5tQ",
       "app_id" : "APP-80W284485P519543T",
       "expires_in" : 32400,
       "nonce" : "2025-10-22T14:32:24ZNpKbSPKuOEA75fCkaNqAcQC_7GbyY1wYSpE1qTeMDaQ",
       "scope" : "https://uri.paypal.com/services/invoicing https://uri.paypal.com/services/payments/futurepayments https://uri.paypal.com/services/vault/payment-tokens/read https://uri.paypal.com/services/disputes/read-buyer https://uri.paypal.com/services/payments/realtimepayment https://uri.paypal.com/services/payments/client-payments-eligibility https://uri.paypal.com/services/identity/activities https://api.paypal.com/v1/vault/credit-card https://api.paypal.com/v1/payments/.* https://uri.paypal.com/services/reporting/search/read https://uri.paypal.com/services/vault/payment-tokens/readwrite https://api.paypal.com/v1/payments/refund https://uri.paypal.com/services/applications/webhooks https://uri.paypal.com/services/credit/client-offer-presentment/read https://uri.paypal.com/services/paypalhere https://uri.paypal.com/services/disputes/update-seller openid https://uri.paypal.com/services/payments/payment/authcapture Braintree:Vault https://uri.paypal.com/services/disputes/read-seller https://uri.paypal.com/services/payments/orders/client_sdk_orders_api https://uri.paypal.com/services/payments/refund https://uri.paypal.com/payments/payouts https://api.paypal.com/v1/vault/credit-card/.* https://uri.paypal.com/services/shipping/trackers/readwrite https://uri.paypal.com/services/subscriptions https://api.paypal.com/v1/payments/sale/.*/refund",
       "token_type" : "Bearer"
    }
    ```
  </Accordion>

  The following server-side endpoint returns the client token to your client application. Call this endpoint from your frontend:

  ```javascript lines theme={null}
  async function getBrowserSafeClientToken() {
    const response = await fetch("/paypal-api/auth/browser-safe-client-token", {
      method: "GET",
      headers: {
        "Content-Type": "application/json",
      },
    });
    const { accessToken } = await response.json();
    return accessToken;
  }
  ```
</Accordion>

## Initialize the v6 SDK

Use `window.paypal.createInstance()` to initialize the SDK with your client ID or a client token for authentication. Also, use it to define the components you want to load and to manage other configurations like `locale` and `pageType`. The method returns an SDK instance that provides access to payment eligibility checking and session creation methods.

### `window.paypal.createInstance(options)`

Use `window.paypal.createInstance` to initialize the PayPal SDK. This method configures the SDK for your specific integration needs and returns an SDK instance that you'll use to create payment sessions.

#### Parameters

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Required</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>clientId</code></td>
      <td>conditional</td>

      <td>
        <p><strong>string.</strong> Your PayPal client ID. Use this for most integrations. Mutually exclusive with <code>clientToken</code>.</p>
      </td>
    </tr>

    <tr>
      <td><code>clientToken</code></td>
      <td>conditional</td>

      <td>
        <p><strong>string.</strong> A secure, browser-safe token that your server generates using your PayPal client ID and secret. Required for PayPal payment vaulting and Fastlane integrations. This token expires after 15 minutes and is bound to your domain for security. You must generate a new token when needed. Mutually exclusive with <code>clientId</code>.</p>
      </td>
    </tr>

    <tr>
      <td><code>components</code></td>
      <td>no</td>

      <td>
        <p><strong>string\[].</strong> An array of SDK components to load for your integration. Each component enables specific payment functionality.</p>
        <p>Available components:</p>

        <ul>
          <li><code>paypal-payments</code> — PayPal and Pay Later checkout</li>
          <li><code>venmo-payments</code> — Venmo payments (US only)</li>
          <li><code>paypal-guest-payments</code> — Standalone credit or debit card button</li>
          <li><code>paypal-messages</code> — Promotional messaging</li>
          <li><code>card-fields</code> — Inline credit and debit card fields</li>
          <li><code>fastlane</code> — Accelerated guest checkout</li>
          <li><code>googlepay-payments</code> — Google Pay integration</li>
          <li><code>applepay-payments</code> — Apple Pay integration</li>
        </ul>

        <p>Default: <code>\["paypal-payments"]</code></p>
      </td>
    </tr>

    <tr>
      <td><code>pageType</code></td>
      <td>no</td>

      <td>
        <p><strong>string.</strong> The type of page where the SDK is being initialized. This helps PayPal optimize the payment experience and provide better analytics.</p>
        <p>Accepted values:</p>

        <ul>
          <li><code>checkout</code> — Checkout or payment page</li>
          <li><code>product-details</code> — Individual product page</li>
          <li><code>cart</code> — Shopping cart page</li>
          <li><code>mini-cart</code> — Mini cart or side cart</li>
          <li><code>home</code> — Homepage</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td><code>locale</code></td>
      <td>no</td>

      <td>
        <p><strong>string.</strong> The locale for the UI components, specified as a BCP-47 language tag, for example, `"en-US"`, `"fr-FR"`, `"de-DE"`. If not specified, the SDK automatically detects the buyer's locale from their browser settings.</p>
      </td>
    </tr>

    <tr>
      <td><code>clientMetadataId</code></td>
      <td>no</td>

      <td>
        <p><strong>string.</strong> A unique identifier for tracking and debugging. You can generate this using <code>crypto.randomUUID()</code> or your own ID generation system. This ID helps correlate SDK sessions with your server-side logs.</p>
      </td>
    </tr>

    <tr>
      <td><code>merchantId</code></td>
      <td>yes for partners</td>

      <td>
        <p><strong>string.</strong> A unique identifier for the seller you're processing payments for.</p>
      </td>
    </tr>

    <tr>
      <td><code>partnerAttributionId</code></td>
      <td>no</td>

      <td>
        <p><strong>string.</strong> PayPal issues this <code>BN\_CODE</code> to you during partner onboarding.</p>
      </td>
    </tr>
  </tbody>
</table>

#### Returns

Returns a promise that resolves to an SDK instance object. This instance provides methods for checking payment eligibility and creating payment sessions.

* `findEligibleMethods()` - Check payment method availability
* `createPayPalOneTimePaymentSession()` - Create a payment session
* `createFastlane()` - Initialize accelerated guest checkout (Fastlane)

### Example

<Note>
  Partners must include the `merchantId` parameter when initializing the SDK instance. Direct merchants can omit this parameter.
</Note>

```javascript lines expandable theme={null}
// Basic initialization with client ID (recommended for most integrations)
const sdkInstance = await window.paypal.createInstance({
  clientId: "YOUR_CLIENT_ID",
});

// With client token (required for PayPal vaulting and fastlane)
const sdkInstance = await window.paypal.createInstance({
  clientToken: "YOUR_CLIENT_TOKEN",
});

// Full configuration with client ID
const sdkInstance = await window.paypal.createInstance({
  clientId: "YOUR_CLIENT_ID",
  components: ["paypal-payments", "venmo-payments"],
  pageType: "checkout",
  locale: "en-US",
  clientMetadataId: crypto.randomUUID(),
});

// With error handling
try {
  const sdkInstance = await window.paypal.createInstance({
    clientId: "YOUR_CLIENT_ID",
  });
  console.log("PayPal SDK initialized successfully");
} catch (error) {
  console.error("Failed to initialize PayPal SDK:", error);
}
```

## Recommended frontend setup

This is the recommended approach for most implementations. It includes all payment methods with eligibility logic and automatic fallback handling. The following are key components of the integration:

### PayPal SDK instance

* **Purpose**: Main entry point for PayPal functionality
* **Components**: Includes `paypal-payments` component
* **Authentication**: Requires client token from server

### Eligibility check

* **Purpose**: Determines payment methods available to the buyer
* **Factors**: User location, currency, account status, device type
* **Implementation**: Always check before showing payment buttons

### Payment sessions

* **PayPal**: Standard PayPal payments
* **Pay Later**: Financing options with specific product codes
* **PayPal Credit**: Credit-based payments with country-specific configuration

### Web components

* `<paypal-button>`: Standard PayPal payment button
* `<paypal-pay-later-button>`: Pay Later financing button
* `<paypal-credit-button>`: PayPal Credit button

### Example

The following is an example of what an `app.js` file might look like when implementing the recommended setup.

<Note>
  Partners must include the `merchantId` parameter when initializing the SDK instance. Direct merchants can omit this parameter.
</Note>

```javascript expandable lines theme={null}
async function onPayPalWebSdkLoaded() {
  try {
    // Create PayPal SDK instance
    const sdkInstance = await window.paypal.createInstance({
      clientId: "YOUR_CLIENT_ID",
      components: ["paypal-payments"],
      pageType: "checkout",
    });

    // Check eligibility for all payment methods
    const paymentMethods = await sdkInstance.findEligibleMethods({
      currencyCode: "USD",
    });

    // Set up PayPal button if eligible
    if (paymentMethods.isEligible("paypal")) {
      configurePayPalButton(sdkInstance);
    }

    // Set up Pay Later button if eligible
    if (paymentMethods.isEligible("paylater")) {
      const payLaterPaymentMethodDetails = paymentMethods.getDetails("paylater");
      setupPayLaterButton(sdkInstance, payLaterPaymentMethodDetails);
    }

    // Set up PayPal Credit button if eligible
    if (paymentMethods.isEligible("credit")) {
      const paypalCreditPaymentMethodDetails = paymentMethods.getDetails("credit");
      setupPayPalCreditButton(sdkInstance, paypalCreditPaymentMethodDetails);
    }
  } catch (error) {
    console.error("SDK initialization error:", error);
  }
}

// Shared payment session options for all payment methods
const paymentSessionOptions = {
  // Called when user approves a payment 
  async onApprove(data) {
    console.log("Payment approved:", data);
    try {
      const orderData = await captureOrder({
        orderId: data.orderId,
      });
      console.log("Payment captured successfully:", orderData);
    } catch (error) {
      console.error("Payment capture failed:", error);
    }
  },
  
  // Called when user cancels a payment
  onCancel(data) {
    console.log("Payment cancelled:", data);
  },
  
  // Called when an error occurs during payment
  onError(error) {
    console.error("Payment error:", error);
  },
};

// Set up standard PayPal button
async function configurePayPalButton(sdkInstance) {
  const paypalPaymentSession = sdkInstance.createPayPalOneTimePaymentSession(
    paymentSessionOptions,
  );

  const paypalButton = document.querySelector("paypal-button");
  paypalButton.removeAttribute("hidden");

  paypalButton.addEventListener("click", async () => {
    try {
      await paypalPaymentSession.start(
        { presentationMode: "auto" }, // Auto-detects best presentation mode
        createOrder(),
      );
    } catch (error) {
      console.error("PayPal payment start error:", error);
    }
  });
}

// Set up Pay Later button
async function setupPayLaterButton(sdkInstance, payLaterPaymentMethodDetails) {
  const payLaterPaymentSession = sdkInstance.createPayLaterOneTimePaymentSession(
    paymentSessionOptions
  );

  const { productCode, countryCode } = payLaterPaymentMethodDetails;
  const payLaterButton = document.querySelector("paypal-pay-later-button");

  // Configure button with Pay Later specific details
  payLaterButton.productCode = productCode;
  payLaterButton.countryCode = countryCode;
  payLaterButton.removeAttribute("hidden");

  payLaterButton.addEventListener("click", async () => {
    try {
      await payLaterPaymentSession.start(
        { presentationMode: "auto" },
        createOrder(),
      );
    } catch (error) {
      console.error("Pay Later payment start error:", error);
    }
  });
}

// Set up PayPal Credit button
async function setupPayPalCreditButton(sdkInstance, paypalCreditPaymentMethodDetails) {
  const paypalCreditPaymentSession = sdkInstance.createPayPalCreditOneTimePaymentSession(
    paymentSessionOptions
  );

  const { countryCode } = paypalCreditPaymentMethodDetails;
  const paypalCreditButton = document.querySelector("paypal-credit-button");

  // Configure button with PayPal Credit specific details
  paypalCreditButton.countryCode = countryCode;
  paypalCreditButton.removeAttribute("hidden");

  paypalCreditButton.addEventListener("click", async () => {
    try {
      await paypalCreditPaymentSession.start(
        { presentationMode: "auto" },
        createOrder(),
      );
    } catch (error) {
      console.error("PayPal Credit payment start error:", error);
    }
  });
}
```

## Return order ID to SDK

The `createOrder()` function must return a promise that resolves to `{ orderId: "YOUR_ORDER_ID" }`. This is a key difference between v6 and previous versions of the SDK.

```javascript lines theme={null}
// In v6, this must return an object with the shape: { orderId: "YOUR_ORDER_ID" }
  return fetch("/paypal-api/checkout/orders/create", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify(orderPayload),
  })
    .then(response => response.json())
    .then(data => ({ orderId: data.id })); // <-- Required return value
} // End createOrder
```

## Best practices

The following are best practices for integrating the v6 SDK.

Keep sensitive operations server-side and validate all payment data. Provide clear feedback to users throughout the payment flow.

### Security

* Obtain client tokens from your secure server
* Never expose PayPal client secrets in frontend code
* All payment processing happens through PayPal's secure servers
* Never pass up item total from browser - this can be manipulated
* Validate order details on your server before capture

### User experience

* Always check eligibility before showing payment buttons
* Provide clear loading states during payment processing
* Handle popup blockers gracefully with `{ presentationMode:auto }`
* Show appropriate error messages for different failure scenarios

### Performance

* Initialize the SDK early, but avoid blocking page load
* Cache client tokens appropriately
* Use presentation mode fallback strategies

## See also

* [JavaScript SDK v6 reference](/reference/sdk/js/v6/reference)
* [React SDK v6 reference](/reference/sdk/react)


# Sandboxed <iframe> integration
Source: https://docs.paypal.ai/developer/how-to/sdk/js/v6/iframe



PayPal's sandboxed `<iframe>` integration provides enhanced security by isolating payment processing code within a secure `<iframe>` wrapper while maintaining seamless communication with the parent merchant page through the `postMessage` API. In this case, the term "sandboxed" refers to the isolation of payment processing in an `<iframe>` wrapper, not the sandbox testing environment that PayPal provides.

In a sandboxed `<iframe>` integration, the parent page is a merchant page. Within the merchant page, an `<iframe>` wrapper uses the PayPal JavaScript SDK v6 and communicates with a server that accesses the PayPal server SDK. The merchant page and `<iframe>` use `postMessage` to communicate about the state of a payment. Using the PayPal SDK inside an `<iframe>` wrapper prevents having to request the SDK script directly from the merchant page.

This type of integration is recommended for high-security uses, such as banking and financial services or integrations with strict compliance requirements, such as PCI DSS, or SOC 2. However, it requires more complex setup and maintenance than other PayPal integrations.

This implementation consists of two separate applications:

* A merchant page at `localhost:3001` for your main website and app
* A PayPal `<iframe>` at `localhost:3000` that provides an isolated payment processing environment with secure cross-frame communication through the `postMessage` API

This page provides examples that you can use to help you understand and set up this kind of integration.

## Prerequisites

Before you integrate:

* Get a [client ID and secret](/developer/how-to/api/get-started#1-get-your-client-id-and-client-secret).
* [Set up the v6 SDK](/developer/how-to/sdk/js/v6/configuration).

## Environment configuration

To work with these examples, create a .env file with your PayPal sandbox credentials to enable proper authentication and API communication.

```bash theme={null}
PAYPAL_SANDBOX_CLIENT_ID=YOUR_CLIENT_ID
PAYPAL_SANDBOX_CLIENT_SECRET=YOUR_CLIENT_SECRET
```

## Merchant page HTML structure

Set up yor merchant page HTML before setting up your `<iframe>` wrapper. This example shows how to set up the main merchant page with proper `<iframe>` sandbox attributes, overlay containers for modal presentation, and debug information displays.

```html lines expandable theme={null}
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>PayPal iframe Example</title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <style>
      #iframeWrapper {
        border: none;
        width: 100%;
        height: 300px;
      }

      #iframeWrapper.fullWindow {
        position: absolute;
        top: 0;
        left: 0;
        height: 100%;
        width: 100%;
      }

      #overlayContainer::backdrop {
        background: rgba(0, 0, 0, 0.67);
      }
    </style>
  </head>
  <body>
    <script async src="/app.js" onload="onLoad()"></script>

    <div id="mainContainer">
      <h1>PayPal iframe Example</h1>
      
      <!-- Sandboxed iframe with proper permissions -->
      <iframe
        id="iframeWrapper"
        src="http://localhost:3000/?origin=http://localhost:3001"
        sandbox="allow-scripts allow-same-origin allow-popups allow-forms"
        allow="payment"
      ></iframe>
    </div>

    <!-- Modal overlay for popup presentation mode -->
    <dialog id="overlayContainer">
      <div id="overlayContainerLogo">
        <img src="https://www.paypalobjects.com/js-sdk-logos/2.2.7/paypal-white.svg" />
      </div>
      <button id="overlayCloseButtonCTA">Close</button>
      <button id="overlayCloseButtonBackdrop">X</button>
    </dialog>
  </body>
</html>
```

## Merchant page JavaScript implementation

This example implements page-state management, secure postMessage listeners with origin validation, and handlers for different presentation modes (`popup`, `modal`, `payment-handler`).

```javascript lines expandable theme={null}
class PageState {
  state = {
    presentationMode: null,
    lastPostMessage: null,
    merchantDomain: null,
  };

  constructor() {
    this.merchantDomain = window.location.origin;
  }

  set presentationMode(value) {
    this.state.presentationMode = value;
    const element = document.getElementById("presentationMode");
    element.innerHTML = value;
  }

  set lastPostMessage(event) {
    const statusContainer = document.getElementById("postMessageStatus");
    statusContainer.innerHTML = JSON.stringify(event.data);
    this.state.lastPostMessage = event;
  }
}

const pageState = new PageState();

// Set up secure postMessage listener with origin validation
function setupPostMessageListener() {
  window.addEventListener("message", (event) => {
    // 🔒 CRITICAL: Always validate origin to prevent XSS attacks!
    if (event.origin !== "http://localhost:3000") {
      return;
    }

    pageState.lastPostMessage = event;
    const { eventName, data } = event.data;
    const { presentationMode } = pageState;

    if (eventName === "presentationMode-changed") {
      const { presentationMode } = data;
      pageState.presentationMode = presentationMode;
    } else if (presentationMode === "popup") {
      popupPresentationModePostMessageHandler(event);
    } else if (presentationMode === "modal") {
      modalPresentationModePostMessageHandler(event);
    }
  });
}
```

## PayPal `<iframe>` HTML structure

This example creates the `<iframe>` content with configuration options for the presentation mode, the PayPal button element, and proper script loading for the v6 SDK.

```html lines expandable theme={null}
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>PayPal Payment Handler</title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <style>
      body {
        font-family: sans-serif;
        color: #e5f5ea;
        background: #334037;
      }
    </style>
  </head>
  <body>
    <!-- Presentation mode configuration -->
    <div id="config">
      <div>Payment flow config</div>
      <fieldset>
        <legend>presentationMode</legend>
        <div>
          <input
            checked
            type="radio"
            id="presentationMode-popup"
            name="presentationMode"
            value="popup"
          />
          <label for="presentationMode-popup">popup</label>
        </div>
        <div>
          <input
            type="radio"
            id="presentationMode-modal"
            name="presentationMode"
            value="modal"
          />
          <label for="presentationMode-modal">modal</label>
        </div>
      </fieldset>
    </div>

    <!-- PayPal button -->
    <paypal-button id="paypal-button"></paypal-button>

    <script src="/integration.js"></script>
    <script
      async
      src="https://www.sandbox.paypal.com/web-sdk/v6/core"
      onload="onPayPalWebSdkLoaded()"
    ></script>
  </body>
</html>
```

## PayPal `<iframe>` JavaScript implementation

This JavaScript runs inside the `<iframe>`, not the merchant page. It initializes the SDK, creates the payment session, and sends status updates back to the merchant page using `postMessage`.

### Initialize the SDK

The v6 SDK script in the `<iframe>` HTML calls `onPayPalWebSdkLoaded()` when it finishes loading. This function initializes the SDK and passes the instance to `configurePayPalButton()`.

* Replace `"YOUR_CLIENT_ID"` with your client ID.
* Partners: replace `"SELLER_MERCHANT_ID"` with the merchant ID of the seller you're creating the payment session for.
* Non-partners: omit `merchantId`.

```javascript lines theme={null}
async function onPayPalWebSdkLoaded() {
  const sdkInstance = await window.paypal.createInstance({
    clientId: "YOUR_CLIENT_ID",
    merchantId: "SELLER_MERCHANT_ID",
    components: ["paypal-payments"],
    pageType: "checkout",
  });

  configurePayPalButton(sdkInstance);
}
```

### Set up the payment session

`configurePayPalButton()` uses the SDK instance to create a payment session and attach a click handler to the PayPal button. When the buyer completes, cancels, or triggers an error in the payment flow, the function sends a `postMessage` event to the merchant page.

```javascript lines expandable theme={null}
class PageState {
  state = {
    paymentSession: null,
  };

  get paymentSession() {
    return this.state.paymentSession;
  }

  set paymentSession(value) {
    this.state.paymentSession = value;
  }
}

const pageState = new PageState();

// Set up PayPal button with payment session
async function configurePayPalButton(sdkInstance) {
  pageState.paymentSession = sdkInstance.createPayPalOneTimePaymentSession({
    onApprove: async (data) => {
      const orderData = await captureOrder({
        orderId: data.orderId,
      });

      sendPostMessageToParent({
        eventName: "payment-flow-approved",
        data: orderData,
      });
    },
    onCancel: (data) => {
      sendPostMessageToParent({
        eventName: "payment-flow-canceled",
        data: {
          orderId: data?.orderId,
        },
      });
    },
    onError: (data) => {
      sendPostMessageToParent({
        eventName: "payment-flow-error",
        data: {
          orderId: data?.orderId,
        },
      });
    },
  });

  const paypalButton = document.querySelector("#paypal-button");
  paypalButton.addEventListener("click", async () => {
    const paymentFlowConfig = {
      presentationMode: getSelectedPresentationMode(),
      fullPageOverlay: { enabled: false },
    };

    sendPostMessageToParent({
      eventName: "payment-flow-start",
      data: { paymentFlowConfig },
    });

    try {
      await pageState.paymentSession.start(paymentFlowConfig, createOrder());
    } catch (e) {
      console.error("Payment start error:", e);
      sendPostMessageToParent({
        eventName: "payment-flow-error",
        data: { error: e.message },
      });
    }
  });
}
```

## Package.json configuration

This example configures `npm` scripts to run the merchant page and the PayPal `<iframe>` servers concurrently using the <a href="https://vite.dev/guide/build">Vite</a> build tool with proper port assignments. For more information about Vite, see [Vite configuration files](#vite-configuration-files).

```bash lines expandable theme={null}
{
  "name": "v6-web-sdk-sample-html-iframe",
  "version": "1.0.0",
  "description": "PayPal sandboxed iframe integration example",
  "scripts": {
    "merchant-page": "vite --config vite-merchant-example.config.js",
    "paypal-iframe": "vite --config vite-paypal-iframe.config.js",
    "start": "concurrently \"npm run merchant-page\" \"npm run paypal-iframe\"",
    "format": "prettier . --write",
    "format:check": "prettier . --check"
  },
  "dependencies": {
    "concurrently": "^9.1.2",
    "vite": "^7.0.4"
  }
}
```

## Vite configuration files

This example sets up separate <a href="https://vite.dev/guide/build">Vite</a> configurations for the merchant page (port 3001) and PayPal iFrame (port 3000) with proper proxy settings for PayPal API endpoints.

```javascript lines expandable theme={null}
// vite-merchant-example.config.js
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [],
  root: "src/merchant-example",
  server: {
    port: 3001,
  },
});

// vite-paypal-iframe.config.js
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [],
  root: "src/paypal-iframe",
  server: {
    port: 3000,
    proxy: {
      "/paypal-api": {
        target: "http://localhost:8080",
        changeOrigin: true,
        secure: false,
      },
    },
  },
});
```

## `<iframe>` sandbox security configuration

This example configures `<iframe>` sandbox attributes to enable necessary permissions while maintaining security isolation with `allow-scripts`, `allow-same-origin`, `allow-popups`, and `allow-forms`.

```html lines theme={null}
<iframe
  src="http://localhost:3000/?origin=http://localhost:3001"
  sandbox="allow-scripts allow-same-origin allow-popups allow-forms"
  allow="payment"
></iframe>
```

## PostMessage origin validation

This example implements critical security measures, such as validating message origins to prevent XSS attacks and ensuring that only trusted domains can communicate with your application.

```javascript lines expandable theme={null}
// ✅ ALWAYS validate message origin
window.addEventListener("message", (event) => {
  if (event.origin !== expectedOrigin) {
    return; // Ignore messages from unknown origins
  }
  // Process trusted message
});

// ❌ NEVER accept messages without validation
window.addEventListener("message", (event) => {
  // Vulnerable to XSS attacks!
  processMessage(event.data);
});
```

## Content security policy header configuration

<a href="https://content-security-policy.com/">Content Security Policy (CSP) headers</a> control resource loading and prevent unauthorized script execution while allowing necessary PayPal SDK and `<iframe>` communication in this example. You learn more about security headers in [Production security headers](#production-security-headers).

```html theme={null}
<meta http-equiv="Content-Security-Policy" content="
  default-src 'self';
  script-src 'self' 'unsafe-inline' https://www.sandbox.paypal.com;
  frame-src 'self' http://localhost:3000;
  connect-src 'self' http://localhost:8080;
  img-src 'self' https://www.paypalobjects.com;
">
```

## Communication protocol messages

Define standardized message formats for iframe-to-parent communication, including changes to the presentation mode, payment flow events, and error handling, as shown in this example.

```javascript lines expandable theme={null}
// Presentation mode changed
{
  eventName: "presentationMode-changed",
  data: { presentationMode: "popup" }
}

// Payment flow started
{
  eventName: "payment-flow-start",
  data: { paymentFlowConfig: {...} }
}

// Payment approved
{
  eventName: "payment-flow-approved",
  data: { orderId: "...", captureData: {...} }
}

// Payment canceled
{
  eventName: "payment-flow-canceled",
  data: { orderId: "..." }
}

// Payment error
{
  eventName: "payment-flow-error",
  data: { error: "..." }
}
```

## Advanced event handling

You can implement a comprehensive event-handling system with custom logic for payment start, success, cancellation, and error scenarios. This example also includes analytics tracking and user feedback.

```javascript lines expandable theme={null}
function setupAdvancedPostMessageListener() {
  window.addEventListener("message", (event) => {
    if (event.origin !== "http://localhost:3000") {
      return;
    }

    const { eventName, data } = event.data;

    switch (eventName) {
      case "payment-flow-start":
        handlePaymentStart(data);
        break;
      case "payment-flow-approved":
        handlePaymentSuccess(data);
        break;
      case "payment-flow-canceled":
        handlePaymentCancellation(data);
        break;
      case "payment-flow-error":
        handlePaymentError(data);
        break;
      case "presentationMode-changed":
        handlePresentationModeChange(data);
        break;
      default:
        console.warn("Unknown event:", eventName);
    }
  });
}

function handlePaymentSuccess(data) {
  // Hide loading state
  hideLoadingIndicator();
  
  // Show success message
  showSuccessMessage("Payment completed successfully!");
  
  // Redirect or update UI
  setTimeout(() => {
    window.location.href = "/success";
  }, 2000);
  
  // Track conversion
  trackEvent("payment_completed", data);
}
```

## Dynamic `<iframe>` management

The `IframeManager` class can handle message queuing, ready-state management, and cleanup operations for better control over `<iframe>` lifecycle, as shown in this example.

```javascript lines expandable theme={null}
class IframeManager {
  constructor(iframeId, targetOrigin) {
    this.iframe = document.getElementById(iframeId);
    this.targetOrigin = targetOrigin;
    this.messageQueue = [];
    this.isReady = false;
  }

  sendMessage(payload) {
    if (this.isReady) {
      this.iframe.contentWindow.postMessage(payload, this.targetOrigin);
    } else {
      this.messageQueue.push(payload);
    }
  }

  onReady() {
    this.isReady = true;
    // Send queued messages
    this.messageQueue.forEach(payload => {
      this.iframe.contentWindow.postMessage(payload, this.targetOrigin);
    });
    this.messageQueue = [];
  }

  destroy() {
    this.iframe.remove();
    this.isReady = false;
    this.messageQueue = [];
  }
}

const iframeManager = new IframeManager("iframeWrapper", "http://localhost:3000");
```

## Error recovery and retry logic

Implement payment retry management with configurable retry limits, user confirmation dialogs, and graceful fallback handling for failed payment attempts, as shown in this example.

```javascript lines expandable theme={null}
class PaymentRetryManager {
  constructor(maxRetries = 3) {
    this.maxRetries = maxRetries;
    this.currentRetries = 0;
  }

  async handlePaymentError(error, retryCallback) {
    console.error("Payment error:", error);

    if (this.currentRetries < this.maxRetries) {
      this.currentRetries++;
      
      // Show retry option to user
      const shouldRetry = await showRetryDialog(
        `Payment failed (${this.currentRetries}/${this.maxRetries}). Would you like to try again?`
      );

      if (shouldRetry) {
        return retryCallback();
      }
    }

    // Max retries reached or user declined retry
    this.currentRetries = 0;
    showFinalErrorMessage("Payment could not be completed. Please try a different payment method.");
  }

  reset() {
    this.currentRetries = 0;
  }
}

const retryManager = new PaymentRetryManager();
```

## Production security headers

In a production environment, configure `Express.js` security headers for production deployment, including `X-Frame-Options`, content security policy (CSP), and MIME-type protection. For more information about CSP, see [Content security policy header configuration](#content-security-policy-header-configuration).

```javascript lines expandable theme={null}
// Express.js security headers
app.use((req, res, next) => {
  // Prevent iframe embedding from untrusted domains
  res.setHeader('X-Frame-Options', 'SAMEORIGIN');
  
  // Content Security Policy
  res.setHeader('Content-Security-Policy', `
    default-src 'self';
    script-src 'self' 'unsafe-inline' https://www.paypal.com;
    frame-src 'self' https://payments.example.com;
    connect-src 'self' https://api.paypal.com;
    img-src 'self' https://www.paypalobjects.com;
  `.replace(/\s+/g, ' ').trim());
  
  // Prevent MIME type sniffing
  res.setHeader('X-Content-Type-Options', 'nosniff');
  
  next();
});
```

## Troubleshooting PostMessage

To troubleshoot common postMessage communication issues, check origin validation and `<iframe>` loading status. Also, confirm that you configured the proper sandbox attributes.

```javascript lines expandable theme={null}
// Check origin validation
if (event.origin !== expectedOrigin) {
  console.warn(`Message rejected from origin: ${event.origin}`);
  return;
}

// Check iframe loading
iframe.onload = () => {
  console.log("Iframe ready for postMessage communication");
};

// Ensure proper sandbox attributes
const requiredSandboxAttrs = [
  'allow-scripts',
  'allow-same-origin',
  'allow-popups',
  'allow-forms'
];

const sandboxAttr = iframe.getAttribute('sandbox');
requiredSandboxAttrs.forEach(attr => {
  if (!sandboxAttr.includes(attr)) {
    console.error(`Missing sandbox attribute: ${attr}`);
  }
});
```

## See also

You can see an end-to-end (E2E) example of an `<iframe>` integration with PayPal in <a href="https://github.com/paypal-examples/v6-web-sdk-sample-integration/tree/main/client/components/paypalPayments/oneTimePayment/html/src/advanced/sandboxedIframe/">the public examples repository on GitHub</a>.


# Test and go live
Source: https://docs.paypal.ai/developer/how-to/sdk/js/v6/production



Before you go live with the JavaScript SDK v6, test your integration end to end, and confirm you've completed all items in the production checklist.

## Prerequisites

Before you test:

* Get a [client ID and secret](/developer/how-to/api/get-started#1-get-your-client-id-and-client-secret).
* [Set up the v6 SDK](/developer/how-to/sdk/js/v6/configuration).

## Test

* Test across different browsers and devices.
* Verify popup blocker handling.
* Test all callback scenarios (approve, cancel, error).
* Validate eligibility logic works correctly.

## Production checklist

* Replace sandbox URLs with production URLs.
* Update environment configuration for production.
* Test eligibility on production environment.
* Implement comprehensive error handling.
* Add analytics and conversion tracking.
* Test across different devices and browsers.
* Implement proper loading and success states.
* Set up monitoring and alerting.
* Verify webhook endpoints are configured.
* Test order capture and fulfillment process.


# PayPal security guidelines for developers
Source: https://docs.paypal.ai/developer/how-to/security-guidelines



Creating strong, secure payment systems keeps both your app and your customers' private information safe. Learn about and use PayPal's security guidelines, tools, and best practices when you integrate PayPal as a payment option to keep your customers and your app secure.

## Overview

PayPal provides a robust set of APIs and SDKs for integrating payments into your applications. Security is a top priority, and PayPal enforces strict guidelines and provides tools to help developers protect sensitive data, authenticate securely, and prevent fraud.

When integrating with PayPal, keep the following principles in mind:

* Implement IP restrictions for API access.
* Never store full credit card details.
* Encrypt any stored customer or transaction data.
* Comply with PCI DSS requirements.
* Implement HTTP Strict Transport Security (HSTS).
* Prevent brute force attacks by limiting API requests and adding timeouts.
* Conduct regular security reviews and stay updated with PayPal's advisories.

## General security requirements and guidelines

The following security requirements and guidelines apply to all PayPal integrations and help protect both your application and your customers' sensitive payment information from unauthorized access and potential security threats.

### Use Open Authorization (OAuth) 2.0 for all API authentication

PayPal uses OAuth 2.0 as the standard authentication mechanism for all REST API integrations. OAuth 2.0 provides secure, token-based authentication, allowing applications to access PayPal APIs without exposing user credentials. The process involves obtaining an access token using your client ID and secret, which is then used to authorize API requests.

For a detailed overview of how OAuth 2.0 works with PayPal, see the [PayPal Authentication Guide](https://developer.paypal.com/api/rest/authentication/).

To get an access token, your server sends a `POST` request to the PayPal OAuth endpoint with your client credentials. PayPal responds with a short-lived access token, which you use in the `Authorization` header for subsequent API calls.

For step-by-step instructions and code samples, see [Get an Access Token](https://developer.paypal.com/reference/get-an-access-token/).

### Always use HTTPS for all API and SDK requests

All communication with PayPal APIs and SDKs must use HTTPS to ensure data is encrypted in transit and protected from interception or tampering. HTTPS is required for PCI DSS compliance and is enforced by PayPal for all endpoints. Using HTTPS also ensures that sensitive information, such as credentials and payment data, is never sent in plain text.

Learn more about HTTPS requirements in the [PayPal Security Guidelines](https://developer.paypal.com/api/rest/reference/info-security-guidelines/) and [Secure Communications](https://developer.paypal.com/api/rest/reference/info-security-guidelines/#link-securecommunications).

### Never expose your client secret or API credentials in client-side code

Your client secret and API credentials must always be kept confidential and used only on the server side. Exposing these credentials in client-side cod, such as JavaScript running in the browser, can lead to credential theft and unauthorized access to your PayPal account.

For best practices on protecting your credentials, see [Secure Your API Credentials](https://developer.paypal.com/community/blog/secure-your-api-credentials/).

PayPal provides tools for managing and rotating API credentials, including the ability to generate, revoke, and monitor credentials in the developer dashboard. For more information, see [Get started with PayPal REST APIs](https://developer.paypal.com/api/rest/).

### Store credentials securely using environment variables or secure vaults

Sensitive credentials should be stored in environment variables or secure vaults, not in source code or configuration files. This reduces the risk of accidental exposure through version control or code sharing. Use secrets management tools or environment variable configuration supported by your deployment platform.

For more on secure storage, see [Secure Your API Credentials](https://developer.paypal.com/community/blog/secure-your-api-credentials/) and [Authentication Requirements](https://developer.paypal.com/api/rest/reference/info-security-guidelines/#link-authenticationrequirements).

### Rotate API credentials regularly and remove unused credentials

Regularly rotating your API credentials and removing any that are no longer in use minimizes the risk if credentials are ever compromised. PayPal allows you to manage and rotate credentials in the developer dashboard, and you should establish a schedule for credential rotation as part of your security policy.

### Validate all webhook signatures to ensure authenticity

Always verify webhook signatures using PayPal's verification API before processing events. This ensures the event is genuine and untampered, protecting your application from spoofed or malicious notifications.

For implementation details, see [Webhooks](https://developer.paypal.com/api/rest/webhooks/).

### Keep all dependencies, SDKs, and libraries up to date

Regularly update all dependencies, SDKs, and libraries to patch security vulnerabilities and benefit from the latest security improvements. Outdated software can expose your application to known exploits.

See [JavaScript SDK Best Practices](https://developer.paypal.com/sdk/js/best-practices/) for more information.

### Use Transport Layer Security (TLS) 1.2 or higher

Ensure your servers and clients support TLS 1.2 or higher for all communications with PayPal. TLS provides strong encryption and is required for PCI DSS compliance. PayPal endpoints do not support older, less secure protocols.

Read more about TLS requirements in [Secure communications](https://developer.paypal.com/reference/guidelines/info-security-guidelines/#secure-communications).

### Enable two-factor authentication (2FA) on your PayPal account

Enable 2FA to add an extra layer of security to your PayPal account and developer dashboard. 2FA helps prevent unauthorized access, even if your password is compromised.

For more information, see [Enable and Configure Two-Factor Authentication](https://developer.paypal.com/community/blog/2-factor-authentication/).

### Monitor and log all payment and API activity for suspicious behavior

Implement logging and monitoring for all payment and API activity to detect and respond to suspicious or unauthorized actions. Monitoring helps you identify fraud, abuse, or operational issues quickly.

### Follow the principle of least privilege for API credentials

Grant only the minimum permissions necessary for each API credential to reduce risk if credentials are compromised. Use separate credentials for different environments and roles.

### Do not log sensitive information such as access tokens or payment details

Never log sensitive data such as access tokens, client secrets, or full payment details to prevent accidental exposure. Logging sensitive data can lead to data breaches and non-compliance with PCI DSS.

## Integration-specific security guidelines

PayPal offers several integration paths, each with unique security considerations beyond the general guidelines. The following sections outline specific security requirements, best practices, and code examples for API, SDK, and webhook integrations.

### API integration path

The API integration path is for developers who interact directly with PayPal's REST APIs from their server-side applications. Custom payment flows, order management, and other advanced integrations in which you need to securely obtain access tokens, create and capture orders, and handle webhooks, typically use API integration.

#### Security requirements

* Use OAuth 2.0 for all API authentication.
* Always use HTTPS for all API requests.
* Never expose your client secret or API credentials in client-side code.
* Store credentials securely (environment variables or secure vaults).
* Rotate API credentials regularly and remove unused credentials.
* Validate all webhook signatures.
* Use TLS 1.2 or higher.
* Enable two-factor authentication (2FA) on your PayPal account.
* Monitor and log all payment and API activity.
* Do not log sensitive information such as access tokens or payment details.

#### Security best practices

* Never hardcode credentials in your application.
* Use environment variables or a secrets manager.
* Validate all incoming webhook events.
* Keep all dependencies and SDKs up to date.
* Enforce least privilege for API credentials.
* Regularly review and rotate credentials.
* Encrypt sensitive data at rest and in transit.

#### Back-end server code samples

The following code samples demonstrate how to obtain an OAuth 2.0 access token from PayPal in various programming languages. This is the first step required for any secure API integration and should be implemented on your back-end server, never in client-side code.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -v https://api-m.sandbox.paypal.com/v1/oauth2/token \
      -u "CLIENT_ID:CLIENT_SECRET" \
      -H "Accept: application/json" \
      -H "Accept-Language: en_US" \
      -d "grant_type=client_credentials"
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import java.net.*;
    import java.io.*;
    import java.util.Base64;

    public class PayPalToken {
        public static void main(String[] args) throws Exception {
            String clientId = "CLIENT_ID";
            String clientSecret = "CLIENT_SECRET";
            String auth = Base64.getEncoder().encodeToString((clientId + ":" + clientSecret).getBytes());

            URL url = new URL("https://api-m.sandbox.paypal.com/v1/oauth2/token");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Authorization", "Basic " + auth);
            conn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
            conn.setDoOutput(true);

            OutputStream os = conn.getOutputStream();
            os.write("grant_type=client_credentials".getBytes());
            os.flush();

            BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
            String inputLine;
            StringBuffer content = new StringBuffer();
            while ((inputLine = in.readLine()) != null) {
                content.append(inputLine);
            }
            in.close();
            System.out.println(content.toString());
        }
    }
    ```
  </Tab>

  <Tab title="JavaScript (Node.js)">
    ```nodejs theme={null}
    const fetch = require('node-fetch');
    const clientId = 'CLIENT_ID';
    const clientSecret = 'CLIENT_SECRET';

    fetch('https://api-m.sandbox.paypal.com/v1/oauth2/token', {
      method: 'POST',
      headers: {
        'Authorization': 'Basic ' + Buffer.from(`${clientId}:${clientSecret}`).toString('base64'),
        'Content-Type': 'application/x-www-form-urlencoded'
      },
      body: 'grant_type=client_credentials'
    })
      .then(res => res.json())
      .then(data => console.log(data));
    ```
  </Tab>

  <Tab title=".NET (C#)">
    ```csharp theme={null}
    using System;
    using System.Net.Http;
    using System.Net.Http.Headers;
    using System.Text;
    using System.Threading.Tasks;

    class Program {
        static async Task Main() {
            var client = new HttpClient();
            var byteArray = Encoding.ASCII.GetBytes("CLIENT_ID:CLIENT_SECRET");
            client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(byteArray));
            var content = new StringContent("grant_type=client_credentials", Encoding.UTF8, "application/x-www-form-urlencoded");
            var response = await client.PostAsync("https://api-m.sandbox.paypal.com/v1/oauth2/token", content);
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    <?php
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, "https://api-m.sandbox.paypal.com/v1/oauth2/token");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, "grant_type=client_credentials");
    curl_setopt($ch, CURLOPT_USERPWD, "CLIENT_ID:CLIENT_SECRET");
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Accept: application/json",
        "Accept-Language: en_US"
    ]);
    $result = curl_exec($ch);
    curl_close($ch);
    echo $result;
    ?>
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests
    from requests.auth import HTTPBasicAuth

    url = "https://api-m.sandbox.paypal.com/v1/oauth2/token"
    auth = HTTPBasicAuth('CLIENT_ID', 'CLIENT_SECRET')
    headers = {"Accept": "application/json", "Accept-Language": "en_US"}
    data = {"grant_type": "client_credentials"}

    response = requests.post(url, headers=headers, data=data, auth=auth)
    print(response.json())
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    require 'net/http'
    require 'uri'
    require 'base64'

    uri = URI('https://api-m.sandbox.paypal.com/v1/oauth2/token')
    req = Net::HTTP::Post.new(uri)
    req['Authorization'] = 'Basic ' + Base64.strict_encode64('CLIENT_ID:CLIENT_SECRET')
    req['Content-Type'] = 'application/x-www-form-urlencoded'
    req.body = 'grant_type=client_credentials'

    res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
    puts res.body
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import fetch from 'node-fetch';

    const clientId = 'CLIENT_ID';
    const clientSecret = 'CLIENT_SECRET';

    async function getAccessToken() {
      const response = await fetch('https://api-m.sandbox.paypal.com/v1/oauth2/token', {
        method: 'POST',
        headers: {
          'Authorization': 'Basic ' + Buffer.from(`${clientId}:${clientSecret}`).toString('base64'),
          'Content-Type': 'application/x-www-form-urlencoded'
        },
        body: 'grant_type=client_credentials'
      });
      const data = await response.json();
      console.log(data);
    }

    getAccessToken();
    ```
  </Tab>
</Tabs>

### SDK integration path

The SDK integration path is for developers who use PayPal's JavaScript SDK to embed payment buttons and checkout flows directly into their web applications.  Developers typically choose the SDK path for web-based integrations because it abstracts much of the complexity and provides built-in security features.

#### Security requirements

* Always load the PayPal JavaScript SDK from the official PayPal CDN.
* Never expose sensitive credentials (client secret) in client-side code.
* Use HTTPS for all SDK requests.
* Validate all payment events on the server.
* Use CSP and SRI for script integrity.
* Keep SDK and dependencies up to date.

#### Security best practices

* Only use the official PayPal CDN for SDK scripts.
* Use Subresource Integrity (SRI) and Content Security Policy (CSP) headers.
* Validate all payment events on the server before fulfilling orders.
* Never include secrets or sensitive data in client-side code.
* Regularly review and update SDK versions.

#### Front-end formatting code samples

The following code samples demonstrate how to securely implement PayPal payment buttons in various frontend frameworks and approaches. Each example shows the proper way to load the PayPal JavaScript SDK and render payment buttons while adhering to the security best practices mentioned in previous sections.

<Tabs>
  <Tab title="ECMAScript (ES Modules)">
    ```javascript theme={null}
    // index.html
    <script type="module" src="paypal.js"></script>
    <div id="paypal-button-container"></div>

    // paypal.js
    const script = document.createElement('script');
    script.src = "https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID";
    script.onload = () => {
      window.paypal.Buttons().render('#paypal-button-container');
    };
    document.body.appendChild(script);
    ```
  </Tab>

  <Tab title="JavaScript (React)">
    ```javascript theme={null}
    import React, { useEffect } from 'react';

    function PayPalButton() {
      useEffect(() => {
        const script = document.createElement('script');
        script.src = "https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID";
        script.addEventListener('load', () => {
          window.paypal.Buttons().render('#paypal-button-container');
        });
        document.body.appendChild(script);
      }, []);

      return <div id="paypal-button-container"></div>;
    }

    export default PayPalButton;
    ```
  </Tab>

  <Tab title="JavaScript (Vanilla)">
    ```javascript theme={null}
    <script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID"></script>
    <div id="paypal-button-container"></div>
    <script>
      paypal.Buttons().render('#paypal-button-container');
    </script>
    ```
  </Tab>

  <Tab title="TypeScript (React)">
    ```typescript theme={null}
    import React, { useEffect } from 'react';

    const PayPalButton: React.FC = () => {
      useEffect(() => {
        const script = document.createElement('script');
        script.src = "https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID";
        script.addEventListener('load', () => {
          (window as any).paypal.Buttons().render('#paypal-button-container');
        });
        document.body.appendChild(script);
      }, []);

      return <div id="paypal-button-container"></div>;
    };

    export default PayPalButton;
    ```
  </Tab>
</Tabs>

### Webhook and notification integration

Webhook and notification integration is essential for handling asynchronous events from PayPal, such as payment completions, disputes, or subscription updates. This path ensures your server can securely receive and process notifications and that your system trusts only genuine PayPal events.

#### Security requirements

* Always validate webhook signatures on your server.
* Never trust webhook data without verification.
* Use HTTPS for all webhook endpoints.

#### Security best practices

* Validate every webhook event before processing.
* Log all webhook activity for auditing.
* Rotate webhook IDs and secrets as needed.

#### Server-side webhook verification example

This example uses Python, but you can use any of the supported languages: .NET (C#), cURL, Java, JavaScript (Node.js), PHP, Python, Ruby, and TypeScript.

```python theme={null}
import hashlib
import base64
from OpenSSL import crypto
import requests
import os
from flask import Flask, request, jsonify

def verify_webhook_signature(request_body, headers):
    webhook_id = os.environ.get('PAYPAL_WEBHOOK_ID')
    transmission_id = headers.get('paypal-transmission-id')
    timestamp = headers.get('paypal-transmission-time')
    webhook_event = request_body
    webhook_signature = headers.get('paypal-transmission-sig')
    cert_url = headers.get('paypal-cert-url')
    response = requests.get(cert_url)
    cert = crypto.load_certificate(crypto.FILETYPE_PEM, response.content)
    data_string = transmission_id + '|' + timestamp + '|' + webhook_id + '|' + hashlib.sha256(str(webhook_event).encode('utf-8')).hexdigest()
    try:
        crypto.verify(cert, base64.b64decode(webhook_signature), data_string.encode('utf-8'), 'sha256')
        return True
    except:
        return False

app = Flask(__name__)
@app.route('/webhooks/paypal', methods=['POST'])
def paypal_webhook():
    if verify_webhook_signature(request.json, request.headers):
        event = request.json
        # Process event
        return jsonify({'status': 'success'}), 200
    else:
        return jsonify({'error': 'Invalid signature'}), 400
```

## Security testing guidelines

Testing your security implementation is critical to ensure your integration is robust against various threats and edge cases. While comprehensive response handling testing is covered in [Handling API responses](/developer/how-to/api/handling-api-responses), consider these additional security-specific tests:

### Authentication and authorization testing

* Test with expired access tokens to verify your token refresh logic works correctly.
* Attempt operations with insufficient permissions to ensure proper access control.
* Verify webhook signature verification correctly rejects unsigned or improperly signed events.

### Data protection testing

* Confirm sensitive data is not logged in your application logs during testing.
* Verify that error messages displayed to end-users don't expose sensitive information.
* Test that your client-side code never receives or processes sensitive credentials.

### Integration security testing

* Use [PayPal's negative testing tools](https://developer.paypal.com/tools/sandbox/negative-testing/request-headers/) to simulate various security-related errors.
* Test your implementation with different network conditions (timeouts, dropped connections).
* Verify that your TLS configuration meets PayPal's security requirements.

For comprehensive testing of API responses, including error handling and recovery flows, see the [Testing your response handling](/developer/how-to/api/handling-api-responses#testing-your-response-handling) section in the API responses guide.

## PayPal security tools

PayPal offers a suite of security tools and features to help secure your integration.

| Tool/Feature                                                                                                                        | Purpose/Use Case                       | Integration Location                                                        |
| ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | --------------------------------------------------------------------------- |
| [Open Authorization (OAuth) 2.0](https://developer.paypal.com/api/rest/authentication/)                                             | Secure API authentication              | Back-end                                                                    |
| [Webhook signature verification](https://developer.paypal.com/api/rest/webhooks/#verify-webhook-signature)                          | Validate event authenticity            | Back-end                                                                    |
| [Transport Layer Security (TLS)](https://developer.paypal.com/reference/guidelines/info-security-guidelines/#secure-communications) | Secure data in transit                 | Everywhere                                                                  |
| API credential management                                                                                                           | Securely manage API keys and secrets   | [Developer Dashboard](https://developer.paypal.com/developer/applications/) |
| [JavaScript SDK](https://developer.paypal.com/sdk/js/best-practices/)                                                               | Secure client-side payment integration | Front-end                                                                   |
| [Fraud detection tools](https://developer.paypal.com/docs/checkout/advanced/customize/fraud-protection/)                            | Prevent and detect fraudulent activity | Back-end/PayPal Portal                                                      |


# Agent toolkit quickstart guide
Source: https://docs.paypal.ai/developer/tools/ai/agent-toolkit-quickstart



PayPal's agent toolkit supports the integration of PayPal APIs into AI agent workflows using <a href="https://aws.amazon.com/bedrock/">Amazon Bedrock</a>, <a href="https://www.crewai.com/">CrewAI</a>, <a href="https://www.langchain.com/">LangChain</a>, <a href="https://modelcontextprotocol.io/introduction/">Model Context Protocol (MCP)</a>, <a href="https://github.com/openai/openai-agents-python/">OpenAI's Agents SDK</a>, and <a href="https://sdk.vercel.ai/">Vercel's AI SDK</a>. This guide provides a step-by-step process for setting up the server, building a basic conversational front-end interface using Next.js, and testing the integration.

> **Note:** For a complete list of the tools that PayPal's agent toolkit includes, see the <a href="https://docs.paypal.ai/developer/tools/ai/agent-tools-ref/">agent tools reference</a>.

## Key features

The agent toolkit from PayPal enables you to:

* **Integrate with PayPal APIs** to access orders, invoices, subscriptions, shipment tracking, transaction details, and dispute management through pre-built functions.
* **Develop with your preferred tools**, including:
  * AI agent frameworks, such as <a href="https://aws.amazon.com/bedrock/">Amazon Bedrock</a>, <a href="https://www.crewai.com/">CrewAI</a>, <a href="https://www.langchain.com/">LangChain</a>, <a href="https://modelcontextprotocol.io/introduction/">Model Context Protocol (MCP)</a>, <a href="https://github.com/openai/openai-agents-python/">OpenAI's Agents SDK</a>, and <a href="https://sdk.vercel.ai/">Vercel's AI SDK</a>
  * Multiple languages, including TypeScript and Python
* **Build custom agent capabilities** to extend core PayPal features and connect with other toolkits to create multi-step agent workflows.

## Agents for commerce

When you implement AI agents strategically, you can:

* Provide consistent customer support.
* Deliver personalized product recommendations.
* Create smoother payment processes.

The key is finding the right balance between efficient automation and the human touch that customers value. Keep human oversight in areas where personal judgment matters most, while letting AI handle repetitive tasks.

These examples are for a fictional online coffee bean store, but they illustrate some of the ways that any seller might use agents.

<Accordion title="Examples of agent types for an online store">
  | Agent type              | Purpose                                                          | Key capabilities                                                                                                                                                                                                                                                                                   |
  | ----------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Customer support        | Handle common customer inquiries and support requests.           | - Answer product questions, such as coffee origins, roast levels, or flavor profiles. <br /> - Process order status inquiries. <br /> - Explain shipping policies and timeframes. <br /> - Handle basic troubleshooting for website or order issues.                                               |
  | Product recommendation  | Help customers discover coffee beans that suit their preferences | - Ask questions about taste preferences, such as acidity, body, and flavor notes. <br /> - Consider brewing methods, such as French press, espresso, or pour-over. <br /> - Suggest complementary products, such as filters or brewing equipment. <br /> - Track and learn from customer patterns. |
  | Order processing        | Streamline the purchase process and handle order-related tasks.  | - Guide customers through checkout. <br /> - Process shipping address validation. <br /> - Handle inventory checks and back-order information. <br /> - Provide shipping cost estimates and delivery timeframes.                                                                                   |
  | Shipping                | Automate processing of end-to-end shipping capabilities.         | - Search open orders and generate shipping labels. <br /> - Print shipping labels. <br /> - Share shipping tracking information with customers and partners. <br /> - Interact with a returns agent to generate return shipping labels.                                                            |
  | Returns and exchanges   | Facilitate smooth return and exchange processes.                 | - Process return requests and generate return labels. <br /> - Explain return policies and eligibility. <br /> - Process refunds or store credits. <br /> - Gather feedback about reasons for returns.                                                                                             |
  | Subscription management | Handle coffee subscription services and recurring orders.        | - Process subscription sign-ups and modifications. <br /> - Handle requests to pause or resume a subscription. <br /> - Manage delivery frequency changes. <br /> - Process subscription cancellations with retention options.                                                                     |
</Accordion>

## Best practices

To have the best integration experience, use these tips:

* **Sandbox environment:** Always use the sandbox environment for initial testing to avoid real transactions.
* **API keys:** Keep your client ID, client secret, and API keys secure. Do not hard-code them in your source files.
* **Environment variables:** Use environment variables to manage sensitive data.
* **Error handling:** Implement error handling to ensure reliable integration.
* **System prompts:** Use well-defined system prompts to control the behavior of the agent.

## 1. Set up your environment

To prepare for an integration, set up your environment first.

### Python

Before you start, confirm that you have the prerequisites:

* Python 3.11 or higher
* pip (Python package manager)
* A <a href="https://developer.paypal.com/home/">PayPal developer</a> account for API credentials

1. Set up a Python virtual environment.

```bash theme={null}
# Step 1: Create a virtual environment
python -m venv venv

# Step 2: Activate the virtual environment
# On MacOS or Linux:
source venv/bin/activate  
# For Windows:
# venv\Scripts\activate
```

2. Install the required dependencies.

```bash theme={null}
pip install -r requirements.txt
```

> **Note:** For details about dependencies for a specific platform and the requirements.txt file, see the section for that platform on this page.

3. Install the agent toolkit.

```bash theme={null}
pip install paypal-agent-toolkit
```

### TypeScript

1. Download and install Node.js version 18 or later from the official <a href="https://nodejs.org/en/">Node.js</a> website.
2. To install the agent toolkit, run `npm install @paypal/agent-toolkit`, or download the package from the <a href="https://github.com/paypal/agent-toolkit/">GitHub repo</a>.
3. Get your PayPal account's <a href="https://developer.paypal.com/api/rest/#link-getclientidandclientsecret/">client ID and secret</a> from <a href="https://developer.paypal.com/dashboard/">PayPal Developer Dashboard</a>. You'll need them to configure this library.

## 2. Integrate

PayPal's agent toolkit supports <a href="https://aws.amazon.com/bedrock/">Amazon Bedrock</a>, <a href="https://www.crewai.com/">CrewAI</a>, <a href="https://www.langchain.com/">LangChain</a>, <a href="https://modelcontextprotocol.io/introduction/">Model Context Protocol (MCP)</a>, <a href="https://github.com/openai/openai-agents-python/">OpenAI's Agents SDK</a>, and <a href="https://sdk.vercel.ai/">Vercel's AI SDK</a>. It works with LLM providers that support function calling and is compatible with TypeScript and Python.

For integration steps, see the section for your AI platform:

* [Amazon Bedrock](#amazon-bedrock)
* [CrewAI SDK](#crewai-sdk)
* [LangChain AI SDK](#langchain-ai-sdk)
* [Model Context Protocol](#model-context-protocol)
* [OpenAI Agents SDK](#openai-agents-sdk)
* [Vercel AI SDK](#vercel-ai-sdk)

For information about setting up the front end for testing any of these integrations, see [Build the front end](#3-build-the-front-end).

### Amazon Bedrock

Complete the following steps to integrate the agent toolkit from PayPal with Amazon Bedrock. Amazon Bedrock passes the agent toolkit as a list of tools.

1. Set your environment variables by creating a .env file in `/typescript/examples/bedrock/`.

```bash theme={null}
# Bedrock Configuration
AWS_ACCESS_KEY_ID=<YOUR_AWS_API_KEY>
AWS_SECRET_ACCESS_KEY=<YOUR_AWS_SECRET_ACCESS_KEY>

# PayPal Configuration
PAYPAL_CLIENT_ID=<YOUR_PAYPAL_CLIENT_ID>
PAYPAL_SECRET=<YOUR_PAYPAL_SECRET>
```

2. Add <a href="https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-templates-and-examples.html/">prompts</a> to `userMessage` in `/typescript/examples/bedrock/index.ts`.

3. Import PayPal's agent toolkit into your code.

> **Note:** Update placeholder values, like `YOUR_PAYPAL_CLIENT_ID` and `YOUR_PAYPAL_SECRET`, with the app credentials from <a href="https://developer.paypal.com/dashboard/">PayPal Developer Dashboard</a>.

```python theme={null}
import { PayPalAgentToolkit, ALL_TOOLS_ENABLED } from '@paypal/agent-toolkit/bedrock';
import { BedrockRuntimeClient, ConverseCommand, Message } from '@aws-sdk/client-bedrock-runtime';

const ppConfig = {
    clientId: process.env.YOUR_PAYPAL_CLIENT_ID || '',
    clientSecret: process.env.YOUR_PAYPAL_SECRET || '',
    configuration: {
        actions: ALL_TOOLS_ENABLED, 
        context: {
            sandbox: true,
        }
    }
}

const paypalToolkit = new PayPalAgentToolkit(ppConfig);
```

4. Create a message, and send it to the model.

```python theme={null}
    let messages: Message[] = [
      {
          role: "user",
          content: [{ text: userMessage }],
      }
  ]

  const response = await client.send(
    new ConverseCommand({ 
        modelId: modelId,
        messages: messages,
        toolConfig: {
            tools: tools
        }
    }),
  );
```

5. Call tools to complete the user's request.

```typescript theme={null}
const reply = response.output?.message;

const toolsCalled = reply.content?.filter(content => content.toolUse);

if (toolsCalled && toolsCalled.length > 0) {
            const toolResults = await Promise.all(
                toolsCalled.map(async (toolBlock) => {
                    const toolCall = {
                        toolUseId: toolBlock.toolUse.toolUseId,
                        name: toolBlock.toolUse.name,
                        input: toolBlock.toolUse.input
                    };
                    const result = await paypalToolkit.handleToolCall(toolCall);
                    return {
                        toolResult: {
                        toolUseId: result.toolUseId,
                        content: result.content
                        }
                    };
                })
            );
      }
```

### CrewAI SDK

Complete the following steps to integrate the agent toolkit from PayPal with CrewAI. CrewAI passes the agent toolkit as a list of tools.

1. Set your environment variables.

> **Note:** Update placeholder values, like `YOUR_PAYPAL_CLIENT_ID` and `YOUR_PAYPAL_SECRET`, with the app credentials from <a href="https://developer.paypal.com/dashboard/">PayPal Developer Dashboard</a>.

```bash theme={null}
# OpenAI Configuration
OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>
OPENAI_API_VERSION=<YOUR_OPENAI_API_VERSION>

# PayPal Configuration
PAYPAL_CLIENT_ID=<YOUR_PAYPAL_CLIENT_ID>
PAYPAL_SECRET=<YOUR_PAYPAL_SECRET>
```

2. Install CrewAI SDK.

```bash theme={null}
pip install crewai==0.76.2
pip install crewai-tools==0.13.2
pip install setuptools
```

> **Recommended:** Create a file called requirements.txt and add these dependencies to that file: <br />

`paypal-agent-toolkit` <br />
`# CrewAI` <br />
`crewai==0.76.2` <br />
`crewai-tools==0.13.2`

3. Import PayPal Agent toolkit into your code.

> **Note:** Update placeholder values, like `YOUR_PAYPAL_CLIENT_ID` and `YOUR_PAYPAL_SECRET`, with the app credentials from <a href="https://developer.paypal.com/dashboard/">PayPal Developer Dashboard</a>.

```python theme={null}
import warnings
warnings.filterwarnings("ignore", category=DeprecationWarning)

import os
from crewai import Agent, Crew, Task

# from dotenv import load_dotenv
from paypal_agent_toolkit.crewai.toolkit import PayPalToolkit
from paypal_agent_toolkit.shared.configuration import Configuration, Context


#uncomment after setting the env file
# load_dotenv()
PAYPAL_CLIENT_ID = os.getenv("YOUR_PAYPAL_CLIENT_ID")
PAYPAL_SECRET = os.getenv("YOUR_PAYPAL_CLIENT_SECRET")
OPENAI_API_VERSION = "2024-02-15-preview"


toolkit = PayPalToolkit(
    client_id=PAYPAL_CLIENT_ID,
    secret=PAYPAL_SECRET,
    configuration=Configuration(
        actions={"orders": {"create": True, "get": True, "capture": True}},
        context=Context(sandbox=True)
    )
)

agent = Agent(
    role="PayPal Assistant",
    goal="Help users create and manage PayPal transactions",
    backstory="You are a finance assistant skilled in PayPal operations.",
    tools=toolkit.get_tools(),
    allow_delegation=False
)

task = Task(
    description="Create an PayPal order for $50 for Premium News service.",
    expected_output="A PayPal order ID",
    agent=agent
)

crew = Crew(agents=[agent], tasks=[task], verbose=True,
    planning=True,)

result = crew.kickoff()
print(result)
```

### LangChain AI SDK

Complete the following steps to integrate the agent toolkit from PayPal with the LangChain AI SDK. LangChain AI SDK passes the agent toolkit as a list of tools.

1. Set your environment variables:

> **Note:** Update placeholder values, like `YOUR_PAYPAL_CLIENT_ID` and `YOUR_PAYPAL_SECRET`, with the app credentials from <a href="https://developer.paypal.com/dashboard/">PayPal Developer Dashboard</a>.

```bash theme={null}
# OpenAI Configuration
OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>
OPENAI_API_VERSION=<YOUR_OPENAI_API_VERSION>

# PayPal Configuration
PAYPAL_CLIENT_ID=<YOUR_PAYPAL_CLIENT_ID>
PAYPAL_SECRET=<YOUR_PAYPAL_SECRET>
```

2. Install LangChain AI SDK.

```bash theme={null}
pip install langchain==0.3.23
pip install langchain-openai==0.2.2
```

> **Recommended:** Create a file called requirements.txt and add these dependencies to that file: <br />

`paypal-agent-toolkit` <br />
`# LangChain` <br />
`langchain==0.3.23` <br />
`langchain-openai==0.2.2` <br />

3. Import PayPal Agent toolkit into your code.

> **Note:** Update placeholder values, like `YOUR_PAYPAL_CLIENT_ID` and `YOUR_PAYPAL_SECRET`, with the app credentials from <a href="https://developer.paypal.com/dashboard/">PayPal Developer Dashboard</a>.

```python theme={null}
import os
from langchain.agents import initialize_agent, AgentType
from langchain_openai import ChatOpenAI 

from dotenv import load_dotenv

from paypal_agent_toolkit.langchain.toolkit import PayPalToolkit
from paypal_agent_toolkit.shared.configuration import Configuration, Context

#uncomment after setting the env file
# load_dotenv()
PAYPAL_CLIENT_ID = os.getenv("YOUR_PAYPAL_CLIENT_ID")
PAYPAL_CLIENT_SECRET = os.getenv("YOUR_PAYPAL_CLIENT_SECRET")
OPENAI_API_VERSION = "2024-02-15-preview"


# --- STEP 1: Setup OpenAI LLM ---
llm = ChatOpenAI(
    temperature=0.3,
    model="gpt-4o",  # or "gpt-3.5-turbo"
)


# --- STEP 2: Setup PayPal Configuration ---
configuration = Configuration(
    actions={
        "orders": {
            "create": True,
            "get": True,
            "capture": True,
        }
    },
    context=Context(
        sandbox=True
    )
)


# --- STEP 3: Build PayPal Toolkit ---
toolkit = PayPalToolkit(client_id=PAYPAL_CLIENT_ID, secret=PAYPAL_CLIENT_SECRET, configuration = configuration)
tools = toolkit.get_tools()



# --- STEP 4: Initialize LangChain Agent ---
agent = initialize_agent(
    tools=tools,
    llm=llm,
    agent=AgentType.OPENAI_FUNCTIONS,
    verbose=True
)


# --- STEP 5: Run Agent with Prompt ---
if __name__ == "__main__":
    prompt = "Create an PayPal order for $50 for Premium News service."
    result = agent.run(prompt)
    print("Agent Output:", result)
```

### Model Context Protocol

<a href="https://modelcontextprotocol.io/introduction/">Model Context Protocol (MCP)</a> supports managing and passing relevant information to models with appropriate context, so they operate properly within a given scope. Using this technology, PayPal developed an MCP server to enable merchants to use natural language with their favorite MCP client.

To install the MCP server in a local configuration:

1. Update the configuration file in your favorite MCP client:

   * Open the MCP client.
   * In the configuration settings for the client, locate the external tools or connectors configuration section, and add the PayPal connector configuration that follows this procedure. In Claude, for example, you add this to `~/Claude/claude_desktop_config.json`.

   ```json theme={null}
   {
     "mcpServers": {
       "paypal": {
         "command": "npx",
         "args": [
           "-y",
           "@paypal/mcp",
           "--tools=all"
         ],
         "env": {
           "PAYPAL_ACCESS_TOKEN": "YOUR_PAYPAL_ACCESS_TOKEN",
           "PAYPAL_ENVIRONMENT": "SANDBOX"
         }
       }
     }
   }
   ```

   > **Note:** Update placeholder values, like `YOUR_PAYPAL_CLIENT_ID` and `YOUR_PAYPAL_SECRET`, with the app credentials from <a href="https://developer.paypal.com/dashboard/">PayPal Developer Dashboard</a>. Alternatively, you can set the `PAYPAL_ACCESS_TOKEN` as an environment variable. You also can pass it as an argument using `--access-token` in `args`.<br /><br />Set the `PAYPAL_ENVIRONMENT` to `SANDBOX` for testing or `PRODUCTION` for your production environment.

   * To update the configuration, run:

   ```bash theme={null}
   npm install @paypal/mcp
   ```

2. Test the integration:

   1. Quit and restart the MCP client to apply your changes.
   2. Ask the MCP client to perform one of the supported tasks. For example, ask the MCP client to list your PayPal invoices for the last month.

> **Tip:** If your test doesn't produce the results you expect, try <a href="https://modelcontextprotocol.io/tools/debugging">these ideas from the Model Context Protocol site</a>.

### OpenAI Agents SDK

Complete the following steps to integrate PayPal's agent toolkit with OpenAI's Agents SDK. Agents SDK passes the agent toolkit as a list of tools.

#### Generate OpenAI API keys

Complete the following steps to generate and store your OpenAI keys to use in your integration with PayPal's agent toolkit.

1. Create an <a href="https://platform.openai.com/signup/">OpenAI</a> account, and complete all registration steps.
2. Generate your API keys:
3. Log into OpenAI, and navigate to the <a href="https://platform.openai.com/account/api-keys">API Keys</a> section of your account.
4. Select **Create a new secret key**.
5. Save the generated key securely. You use this key in your `env.local` file for your agent toolkit integration.

#### Complete the OpenAI integration

Complete the following steps to integrate PayPal's agent toolkit with OpenAI's Agents SDK. Agents SDK passes the agent toolkit as a list of tools.

1. Import PayPal's agent toolkit into your code.

> **Note:** Update placeholder values, like `YOUR_PAYPAL_CLIENT_ID` and `YOUR_PAYPAL_SECRET`, with the app credentials from <a href="https://developer.paypal.com/dashboard/">PayPal Developer Dashboard</a>.

```python theme={null}
from paypal_agent_toolkit.openai.toolkit import PayPalToolkit 
from paypal_agent_toolkit.shared.configuration import Configuration, Context

configuration = Configuration(     
    actions={         
        "orders": {            
            "create": True,             
            "get": True,             
            "capture": True,         
        }     
    },     
    context=Context(         
        sandbox=True     
    ) 
)  

# Initialize toolkit 
toolkit = PayPalToolkit(client_id=YOUR_PAYPAL_CLIENT_ID, secret=YOUR_PAYPAL_SECRET, configuration = configuration)
```

2. You can use the agent toolkit's functions and other tools as your integration requires.

```python theme={null}
from agents import Agent  

tools = toolkit.get_tools()  

agent = Agent(     
    name="PayPal Assistant",     
    instructions="""     
    You're a helpful assistant specialized in managing PayPal transactions:     
    - To create orders, invoke create_order.     
    - After approval by user, invoke capture_order.     
    - To check an order status, invoke get_order_status.     
    """,     
    tools=tools 
)
```

### Vercel AI SDK

Complete the following steps to integrate PayPal's agent toolkit with Vercel's AI SDK. Vercel's AI SDK passes the agent toolkit as a list of tools.

1. Set your environment variables.

> **Note:** Update placeholder values, like `YOUR_PAYPAL_CLIENT_ID` and `YOUR_PAYPAL_SECRET`, with the app credentials from <a href="https://developer.paypal.com/dashboard/">PayPal Developer Dashboard</a>.

```bash theme={null}
# OpenAI Configuration
OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>
OPENAI_API_VERSION=<YOUR_OPENAI_API_VERSION>

# PayPal Configuration
PAYPAL_CLIENT_ID=<YOUR_PAYPAL_CLIENT_ID>
PAYPAL_SECRET=<YOUR_PAYPAL_SECRET>
```

2. Install Vercel AI SDK.

```bash theme={null}
npm install ai @ai-sdk/openai
```

3. Import PayPal's agent toolkit into your code.

> **Note:** Update placeholder values, like `YOUR_PAYPAL_CLIENT_ID` and `YOUR_PAYPAL_SECRET`, with the app credentials from <a href="https://developer.paypal.com/dashboard/">PayPal Developer Dashboard</a>.

```javascript theme={null}
import { PayPalAgentToolkit } from '@paypal/agent-toolkit/ai-sdk';
const paypalToolkit = new PayPalAgentToolkit({
  clientId: process.env.PAYPAL_CLIENT_ID,
  clientSecret: process.env.PAYPAL_CLIENT_SECRET,
  configuration: {
    actions: {
      invoices: {
        create: true,
        list: true,
        send: true,
        sendReminder: true,
        cancel: true,
        generateQRC: true,
      },
      products: { create: true, list: true, update: true },
      subscriptionPlans: { create: true, list: true, show: true },
      shipment: { create: true, show: true, cancel: true },
      orders: { create: true, get: true },
      disputes: { list: true, get: true },
    },
  },
});
```

4. Use PayPal's agent toolkit's functions and other tools as your integration requires.

```javascript theme={null}
const llm: LanguageModelV1 = getModel(); // The model to be used with ai-sdk
const { text: response } = await generateText({
  model: llm,
  tools: { 
    ...paypalToolkit.getTools(),
    // Extend with other tools
  },
  maxSteps: 10,
  prompt: `Create an order for $50 for custom handcrafted item and get the payment link.`,
});
```

## 3. Build the front end

Using the Next.js framework, complete the following tasks.

### Create a Next.js project

If you don't have a Next.js app already, create one.

```typescript theme={null}
npx create-next-app@latest paypal-integration --typescript
cd paypal-integration
npm install
```

### Create a chat interface

Modify app/page.tsx to create a chat interface for interacting with the PayPal agent.

```typescript theme={null}
import React, { useState } from 'react';

const Home: React.FC = () => {
  const [message, setMessage] = useState('');
  const [chat, setChat] = useState<{ sender: 'user' | 'agent'; text: string }[]>([]);
  const handleSendMessage = async () => {
    setChat((prevChat) => [...prevChat, { sender: 'user', text: message }]);
    const response = await fetch('/api/chat', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ message }),
    });
    const data = await response.json();
    setChat((prevChat) => [...prevChat, { sender: 'agent', text: data.response }]);
    setMessage('');
  };

  return (
    <div>
      <h1>PayPal Chat Interface</h1>
      <div>
        {chat.map((c, index) => (
          <div key={index} className={c.sender}>
            {c.sender}: {c.text}
          </div>
        ))}
      </div>
      <input
        type="text"
        value={message}
        onChange={(e) => setMessage(e.target.value)}
      />
      <button onClick={handleSendMessage}>Send</button>
    </div>
  );
};

export default Home;
```

## 4. Test the integration

After you finish the integration, test it by setting up an API route.

Execute this code in `app/api/chat/route.ts`.

```typescript theme={null}
import { NextRequest, NextResponse } from 'next/server';
import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';
import { PayPalAgentToolkit } from '@paypal/agent-toolkit/ai-sdk';

const paypalToolkit = new PayPalAgentToolkit({
  clientId: process.env.PAYPAL_CLIENT_ID,
  clientSecret: process.env.PAYPAL_CLIENT_SECRET,
  configuration: {
    actions: {
      orders: { create: true, get: true },
      invoices: { create: true, list: true },
      // Extend with other actions as needed
    },
  },
});

export async function POST(req: NextRequest) {
  try {
    const { message } = await req.json();

    // Define System Prompt for controlling behavior
    const systemPrompt = 'This is a PayPal agent. You are tasked with handling PayPal orders and providing relevant information.';

    const { text: response } = await generateText({
      model: openai('gpt-4o'),
      tools: paypalToolkit.getTools(),
      maxSteps: 10,
      prompt: message,
      system: systemPrompt,
    });

    return NextResponse.json({ response });
  } catch (error) {
    const errorMessage = error instanceof Error
        ? error.message
        : 'An unknown error occurred';

    return NextResponse.json(
        { error: errorMessage },
        { status: 500 }
    );
  }
}
```

## 5. Start the application

To start the application, execute `npm run dev`, and visit [http://localhost:3000](http://localhost:3000).

## Additional resources

For more information about the concepts covered here, see these additional documents:

* <a href="https://developer.paypal.com/docs/api/overview/">PayPal developer documentation</a>
* <a href="https://github.com/paypal/agent-toolkit/tree/main/typescript/examples/">GitHub examples</a>
* <a href="https://aws.amazon.com/bedrock/">Amazon Bedrock</a>
* <a href="https://www.crewai.com/">CrewAI documentation</a>
* <a href="https://www.langchain.com/">LangChain documentation</a>
* <a href="https://modelcontextprotocol.io/introduction/">Model Context Protocol (MCP)</a>
* <a href="https://github.com/openai/openai-agents-python/">OpenAI Agents SDK</a>
* <a href="https://sdk.vercel.ai/">Vercel AI SDK</a>


# Agent tools reference
Source: https://docs.paypal.ai/developer/tools/ai/agent-tools-ref



PayPal's <a href="/developer/tools/ai/agent-toolkit-quickstart">agent toolkit</a> includes the following tools.

## Catalog management

| Functionality          | Description                                                              | Parameters                                                                                                                                                                                                                                                               | Sample Prompt                                                                 |
| ---------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| `create_product`       | Create a new product in the PayPal catalog.                              | `name` (string, required): The name of the product. <br /><br /> `type` (string, required, enum): The type of the product. Allowed values are `'PHYSICAL'`, `'DIGITAL'`, `'SERVICE'`.                                                                                    | Create a new product with the name `{product_name}` of type `{product_type}`. |
| `list_product`         | List products from the PayPal catalog. Pagination options are available. | `page` (number, optional): The specific page number to retrieve. The default behavior is to go to the first page. <br /><br /> `page_size` (number, optional): The maximum number of products to return per page. The default behavior is to use a system-defined limit. | List all products.                                                            |
| `show_product_details` | Show details of a specific product from the PayPal catalog.              | `product_id` (string, required): The ID of the product to retrieve.                                                                                                                                                                                                      | Show the details for product id `{product_id}`.                               |

## Dispute management

| Functionality          | Description                                                 | Parameters                                                                            | Sample Prompt                              |
| ---------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------ |
| `list_disputes`        | Retrieve a summary of all disputes with optional filtering. | `status` (string, optional): Filter disputes by status, such as `OPEN` or `RESOLVED`. | List all `{status}` disputes.              |
| `get_dispute`          | Retrieve detailed information about a specific dispute.     | `dispute_id` (string): The unique identifier of the dispute.                          | Get details for dispute `{dispute_id}`.    |
| `accept_dispute_claim` | Accept a dispute claim, resolving it in favor of the buyer. | `dispute_id` (string): The unique identifier of the dispute.                          | Accept the dispute with ID `{dispute_id}`. |

## Invoices

| Functionality              | Description                                                    | Parameters                                                                                                                                                                                                                                                                                        | Sample Prompt                                                                               |
| -------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `create_invoice`           | Create a new invoice in the PayPal system.                     | `recipient_email`: Email address of the invoice recipient. <br /><br /> `items`: List of items or services to include in the invoice: <br /> - `name` (string): Name of the item. <br /> - `quantity` (number): Quantity of the item. <br /> - `unit_price` (number): Price per unit of the item. | Create an invoice for `{customer_email}` including 2 hours of consulting at \$150 per hour. |
| `list_invoices`            | List invoices. Pagination and filtering options are available. | `page` (number, optional): Page number for pagination. <br /><br /> `page_size` (number, optional): Number of invoices per page. <br /><br /> `status` (string, optional): Filter invoices by status (such as `SENT` or `PAID`).                                                                  | List all `{status}` invoices on page `{page}` with `{page_size}` invoices per page.         |
| `get_invoice`              | Retrieve details about a specific invoice.                     | `invoice_id` (string): The unique identifier of the invoice.                                                                                                                                                                                                                                      | What are the details of invoice `{invoice_id}`?                                             |
| `send_invoice`             | Send an existing invoice to the specified recipient.           | `invoice_id` (string): The unique identifier of the invoice to be sent.                                                                                                                                                                                                                           | Send invoice `{invoice_id}` to the client.                                                  |
| `send_invoice_reminder`    | Send a reminder for an existing invoice.                       | `invoice_id` (string): The unique identifier of the invoice.                                                                                                                                                                                                                                      | Send a reminder for invoice `{invoice_id}`.                                                 |
| `cancel_sent_invoice`      | Cancel a sent invoice.                                         | `invoice_id` (string): The unique identifier of the invoice to cancel.                                                                                                                                                                                                                            | Cancel the sent invoice `{invoice_id}`.                                                     |
| `generate_invoice_qr_code` | Generate a QR code for an invoice.                             | `invoice_id` (string): The unique identifier of the invoice.                                                                                                                                                                                                                                      | Generate a QR code for invoice `{invoice_id}`.                                              |

## Payments

| Functionality   | Description                                                         | Parameters                                                                                                                                                                                                                                                                                                     | Sample Prompt                                                                                      |
| --------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `create_order`  | Create an order in the PayPal system based on the provided details. | `items` (array): List of items to include in the order each item should have: <br /> - `name` (string): Name of the item. <br /> - `quantity` (number): Quantity of the item. <br /> - `unit_price` (number): Price per unit of the item. <br /><br /> `currency` (string): Currency code, such as USD or EUR. | Place an order for `{quantity}` units of `'{item_name}'` at \$`{unit_price}` each.                 |
| `create_refund` | Process a refund for a captured payment.                            | `capture_id` (string): The unique identifier of the captured payment to refund. <br /><br /> `amount` (number, optional): The refund amount. If not specified, a refund is for the full amount of the purchase. <br /><br /> `currency` (string, optional): Currency code for the refund, such as USD or EUR.  | Process a refund for capture `{capture_id}`. <br /><br /> Process a refund for order `{order_id}`. |
| `get_order`     | Get details of a specific payment.                                  | `payment_id` (string, required)                                                                                                                                                                                                                                                                                | What are the details of payment `{payment_id}`?                                                    |
| `get_refund`    | Get the details for a specific refund.                              | `refund_id` (string): The unique identifier of the refund.                                                                                                                                                                                                                                                     | Get details for refund `{refund_id}`.                                                              |
| `pay_order`     | Capture payment for an authorized order.                            | `order_id` (string): The unique identifier of the order to capture.                                                                                                                                                                                                                                            | Capture payment for order `{order_id}`.                                                            |

## Reporting and insights

| Functionality           | Description                                                                                                                             | Parameters                                                                                                                                                                                                                                                                                                                                                                                                                                               | Sample Prompt                                                                               |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `get_merchant_insights` | Retrieve business intelligence metrics and analytics for a merchant, filtered by start date, end date, insight type, and time interval. | `start_date` (string, required): The start date range to filter insights. <br /><br /> `end_date` (string, required): The end date range to filter insights. <br /><br /> `insight_type` (str, required): The type of insight to retrieve. It can be `"ORDERS"` or `"SALES"` <br /><br /> `time_interval` (str, required): The time periods used for segmenting metrics data. It can be `"DAILY"`, `"WEEKLY"`, `"MONTHLY"`, `"QUARTERLY"`, or `"YEARLY"` | Give me insights on my sales data from 01/01/2025 to 02/01/2025 using daily time intervals. |
| `list_transaction`      | List all transactions. Pagination and filtering options are available.                                                                  | `start_date` (string, optional): The start date for filtering transactions. The default value is 31 days. <br /><br /> `end_date` (string, optional): The end date for filtering transactions.                                                                                                                                                                                                                                                           | Get the list of my transactions for the last `{days}` days.                                 |

## Shipment tracking

| Functionality              | Description                                                    | Parameters                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Sample Prompt                                                                                                                                                                                                                    |
| -------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_shipment_tracking` | Create shipment tracking information for a PayPal transaction. | `tracking_number` (string, required): The tracking number for the shipment. <br /><br /> `transaction_id` (string, required): The transaction ID associated with the shipment. <br /><br /> `carrier` (string, required): The carrier handling the shipment, such as FEDEX or UPS. <br /><br /> `order_id`: (string, optional): The order ID for the shipment. <br /><br /> `status`: (string, optional, enum): The current status of the shipment. Allowed values are \[`"ON_HOLD"`, `"SHIPPED"`, `"DELIVERED"`, `"CANCELLED"`, `"LOCAL_PICKUP"]`. The default value is `"SHIPPED"`.                     | Add tracking number `'{tracking_number}'` with carrier `'{carrier}'` to PayPal order ID `{order_id}`.                                                                                                                            |
| `get_shipment_tracking`    | Get shipment tracking information for a specific shipment.     | `order_id` (string, required): The order ID for the shipment. <br /><br /> `transaction_id` (string, optional): The transaction ID associated with the shipment.                                                                                                                                                                                                                                                                                                                                                                                                                                          | Get the tracking number for PayPal order ID `{order_id}`.                                                                                                                                                                        |
| `update_shipment_tracking` | Update shipment tracking information for a specific shipment.  | `transaction_id` (string, required): The transaction ID for the shipment. <br /><br /> `tracking_number` (string, required): The tracking number for the shipment that you want to update. <br /><br />`new_tracking_number` (string, optional): The new tracking number for the shipment if you're updating its tracking number. <br /><br /> `status` (string, required): The status of the shipment. It can be `"CANCELLED"`, `"DELIVERED"`, `"LOCAL_PICKUP"`, `"ON_HOLD"`, or `"SHIPPED"`.<br /><br /> `carrier` (string, optional): The carrier that is handling the shipment, such as FEDEX or UPS. | Update the shipment tracking info for `transaction_id '{transaction_id}'` with tracking number `'{tracking_number}'` and `status '{status}'` to `carrier '{carrier}'` and use the `new_tracking_number '{new_tracking_number}'`. |

## Subscription management

| Functionality                    | Description                                   | Parameters                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Sample Prompt                                                                                                                                                                                            |
| -------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cancel_subscription`            | Cancel an active subscription.                | `subscription_id` (string, required): The ID of the subscription to cancel. <br /><br /> `reason` (string, optional): Cancellation reason.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Cancel the subscription id `{subscription_id}`.                                                                                                                                                          |
| `create_subscription`            | Create a new subscription.                    | `plan_id` (string, required): The ID of the subscription plan. <br /><br /> `subscriber` (object, optional): The subscriber information: <br />- `name` (string, optional): The name of the subscriber. <br /> - `email` (string, optional): The email address of the subscriber.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Create a subscription for plan id `{plan_id}` with subscriber name as `{subscriber_name}` with email address `{subscriber_email}`.                                                                       |
| `create_subscription_plan`       | Create a new subscription plan.               | `product_id` (string, required): The ID of the product. <br /><br /> `name` (string, required): The plan name. <br /><br /> `billing_cycles` (array, required): An array of billing cycles for trial and regular billing. A plan can have at most 2 trial cycles and only 1 regular cycle: <br /> - `tenure_type` (string, required): `[REGULAR\|TRIAL]`. <br /> - `sequence` (integer, required): The order of this cycle. <br /> - `frequency` (integer, required): Frequency details. <br /> - `interval_unit` (string, required): `[DAY\|WEEK\|MONTH\|YEAR]`. <br /><br /> `payment_preferences` (object, required): Payment preferences for the subscription. <br /><br /> `auto_bill_outstanding` (boolean, optional): Automatically bill outstanding amount (default: true). | Create a `{interval_unit}` PayPal subscription plan for product '`{product_name}`' with billing cycle '`{billing_cycle}`', price '`{price}` `{currency}`'. Set trial period cycle to '`{trial_period}`'. |
| `list_subscription_plans`        | List subscription plans.                      | `product_id` (number, optional): List the subscription plans for a specific product. <br /><br /> `page` (number, optional): The page number to retrieve (default: first page). <br /><br /> `page_size` (number, optional): The maximum number of products to return per page (default: system-defined limit).                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | List all subscription plans.                                                                                                                                                                             |
| `show_subscription_details`      | Show details of a specific subscription.      | `subscription_id` (string, required): The ID of the subscription to retrieve.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Show the details for subscription id `{subscription_id}`.                                                                                                                                                |
| `show_subscription_plan_details` | Show details of a specific subscription plan. | `billing_plan_id` (string, required): The ID of the subscription plan to retrieve.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Show the details for plan id `{billing_plan_id}`.                                                                                                                                                        |
| `update_subscription`            | Update an existing subscription.              | `subscription_id` (string, required): The ID of the subscription to update.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Update the PayPal subscription ID `{subscription_id}` to billing cycle `{billing_cycle}` and price `{price}`.                                                                                            |

## Additional tools for remote MCP server

PayPal's <a href="/developer/tools/ai/mcp-quickstart#remote-mcp-server">remote MCP server</a> offers more tools for product search and checkout using PayPal for payments. These tools are for gift cards only for now, but more is coming soon.

To use these tools in your MCP client, you provide an extra argument. For example, if you are using Claude, add a header parameter, as shown in the following example.

```json theme={null}
{
  "mcpServers": {
    "paypal-commerce-ai": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.paypal.com/sse",
        //Pass additional header parameter to see the commerce tools. 
        "--header",
        "x-feature-flags: commerce:true"
      ]
    }
  }
}
```

| Functionality    | Description                                                                                                                                                                                                                                              | Sample prompt                                                                        |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `search_product` | Find gift card products in the PayPal catalog. <br /><br />This tool searches the catalog for gift cards that meet your criteria. It returns product information that includes pricing, availability, and purchase options.                              | Find available gift cards. <br /><br /> Show me gift cards that cost less than \$50. |
| `create_cart`    | Open a new shopping cart with specified items and shipping preferences.<br /><br />This tool creates a new shopping cart with the selected gift cards. It handles cart initialization, item configuration, and preparing the cart for checkout.          | Add a \$50 gift card to my cart.                                                     |
| `checkout_cart`  | Finalize a shopping cart to complete the purchase process. <br /><br />This tool processes the final checkout for a configured shopping cart using PayPal for payment. It handles payment processing, transaction validation, and purchase confirmation. | Complete checkout for my current cart using PayPal.                                  |


# PayPal's AI resources for developers
Source: https://docs.paypal.ai/developer/tools/ai/ai-intro



Using AI is a powerful way to enhance your applications and services. Everyday examples include:

* **E-commerce stores** that automate order processing, handle returns, and provide 24/7 customer support.
* **Marketplaces** that enable AI-powered product discovery and streamline seller onboarding.
* **SaaS platforms** that automate billing, subscription management, and payment reconciliation.
* **Service businesses** that generate and send invoices, process payments, and manage appointments.

When you combine AI with PayPal's powerful payment and commerce services, you can change how you build and deploy commerce automation solutions, and you can help customers use AI to shop.

```mermaid theme={null}
flowchart TD
    B{What do you want to build?}
    B -- Custom AI assistant for your website or app --> D[agent toolkit]
    B -- Integration with major LLM platforms --> E[LLM integration]
    B -- AI-powered shopping through an AI platform --> F[agentic commerce services]
```

Our suite of AI-powered tools enable you to leverage AI in these ways:

* **Build custom agents:** Create AI agents that handle payment workflows and customer interactions using the [agent toolkit quickstart guide](/developer/tools/ai/agent-toolkit-quickstart/).
* **Connect with LLMs:** Enable ChatGPT, Claude, and other AI assistants to interact with your services using the [LLM integration guide](/developer/tools/ai/llm-integration/).
* **Join PayPal's agentic commerce network:** Make your products discoverable through AI shopping surfaces with PayPal's [agentic commerce services](/growth/agentic-commerce/overview/).

## Key features of PayPal AI tools and resources

PayPal AI tools enable agents to perform commerce-related tasks using PayPal's APIs and services. Agents can process payments, manage subscriptions, handle disputes, automate invoicing, and provide customer support while maintaining the highest standards of security and compliance that PayPal is known for.

Key features of PayPal's AI tools and resources include:

* **Seamless integration:** Built on PayPal's infrastructure, our AI agents provide direct access to payment processing, financial data, and commerce APIs.
* **Intelligent automation:** Leverage advanced AI capabilities to automate repetitive tasks, make data-driven decisions, and provide personalized customer experiences at scale.
* **Developer-friendly tools:** Our agent toolkit includes everything you need, from quickstart guides to advanced MCP (Model Context Protocol) servers, to build, test, and deploy agents quickly.
* **Enterprise-grade security:** All agents operate within PayPal's secure environment, ensuring PCI compliance and protecting sensitive financial data throughout every transaction.
* **Scalable architecture:** Whether you're building a simple payment bot or a complex multi-agent commerce system, our platform scales to meet your needs.

## Getting started

These pages help you start using PayPal's AI tools and resources:

* **<a href="/growth/agentic-commerce/overview/">Agentic commerce services</a>**
* **<a href="/developer/tools/ai/agent-toolkit-quickstart/">Agent toolkit quickstart guide</a>**
* **<a href="/developer/tools/ai/mcp-quickstart/">MCP server quickstart guide</a>**
* **<a href="/developer/tools/ai/llm-integration/">LLM integration quickstart guide</a>**
* **<a href="/developer/tools/ai/agent-tools-ref/">Agent tools reference</a>**
* **<a href="/developer/tools/ai/prompt-best-practices/">Best practices for prompts</a>**


# LLM integration quickstart guide
Source: https://docs.paypal.ai/developer/tools/ai/llm-integration



PayPal recently launched a <a href="https://www.paypal.ai/tools/mcp-quickstart">Model Context Protocol (MCP) server</a> that customers can use to access the power of PayPal using natural language with any AI agent. PayPal's remote MCP server now supports large language models (LLMs) from [Anthropic](https://www.anthropic.com/) and [OpenAI](https://openai.com/), which brings even greater flexibility.

## Before you begin

Before you begin, generate a PayPal access token. You can generate an access token by making a POST request to PayPal's token endpoint, or you can generate it programmatically. For more information, see [Get client ID and client secret](https://developer.paypal.com/api/rest/#link-getclientidandclientsecret).

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api-m.paypal.com/v1/oauth2/token" \
    -u "$PAYPAL_CLIENT_ID:$PAYPAL_CLIENT_SECRET" \
    -H "Accept: application/json" \
    -H "Accept-Language: en_US" \
    -d "grant_type=client_credentials"
  ```

  ```python Python theme={null}
  response = requests.post(
      "https://api-m.paypal.com/v1/oauth2/token",
      headers={
          "Accept": "application/json",
          "Accept-Language": "en_US",
      },
      data={"grant_type": "client_credentials"},
      auth=HTTPBasicAuth(client_id, client_secret)  # Basic Auth
  )
  access_token = response.json()["access_token"]
  ```

  ```typescript TypeScript theme={null}
  const clientId = process.env.PAYPAL_CLIENT_ID!;
  const clientSecret = process.env.PAYPAL_CLIENT_SECRET!;
  const auth = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');

  (async () => {
    const response = await fetch('https://api-m.paypal.com/v1/oauth2/token', {
      method: 'POST',
      headers: {
        'Accept': 'application/json',
        'Accept-Language': 'en_US',
        'Content-Type': 'application/x-www-form-urlencoded',
        'Authorization': `Basic ${auth}`,
      },
      body: 'grant_type=client_credentials',
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    const accessToken = data.access_token;
    console.log(accessToken);
  })();
  ```
</CodeGroup>

## Anthropic integration

When you have your access token, you can connect the remote MCP server with the Anthropic LLM using the steps on this page from [Anthropic](https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector). For more information about connecting to PayPal's remote MCP server, see the <a href="/developer/tools/ai/mcp-quickstart">MCP server quickstart guide</a>.

After you connect, you can start using Anthropic's LLM with PayPal's MCP server tools by initializing the client and making a request. For example, you could ask it to create an invoice, as shown in the following code examples.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.anthropic.com/v1/messages \
    -H "Content-Type: application/json" \
    -H "X-API-Key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: mcp-client-2025-04-04" \
    -d '{
      "model": "claude-sonnet-4-20250514",
      "max_tokens": 1000,
      "messages": [{"role": "user", "content": "Create an invoice for john.doe@example.com for 2 hours of consulting services at the rate of $150 per hour."}],
      "mcp_servers": [
        {
          "type": "url",
          "url": "https://mcp.paypal.com/sse",
          "name": "example-mcp",
          "authorization_token": "YOUR_TOKEN"
        }
      ]
    }'
  ```

  ```python Python theme={null}
  import os
  import requests

  api_key = os.environ["ANTHROPIC_API_KEY"]
  url = "https://api.anthropic.com/v1/messages"
  payload = {
      "model": "claude-sonnet-4-20250514",
      "max_tokens": 1000,
      "messages": [{
          "role": "user",
          "content": "Create an invoice for john.doe@example.com for 2 hours of consulting services at the rate of $150 per hour."
      }],
      "mcp_servers": [{
          "type": "url",
          "url": "https://mcp.paypal.com/sse",
          "name": "example-mcp",
          "authorization_token": "YOUR_TOKEN"
      }]
  }
  headers = {
      "Content-Type": "application/json",
      "X-API-Key": api_key,
      "anthropic-version": "2023-06-01",
      "anthropic-beta": "mcp-client-2025-04-04"
  }
  response = requests.post(url, json=payload, headers=headers)
  print(response.text)
  ```

  ```typescript TypeScript theme={null}
  const apiKey = process.env.ANTHROPIC_API_KEY!;
  const url = "https://api.anthropic.com/v1/messages";

  const payload = {
    model: "claude-sonnet-4-20250514",
    max_tokens: 1000,
    messages: [
      {
        role: "user",
        content: "Create an invoice for john.doe@example.com for 2 hours of consulting services at the rate of $150 per hour.",
      },
    ],
    mcp_servers: [
      {
        type: "url",
        url: "https://mcp.paypal.com/sse",
        name: "example-mcp",
        authorization_token: "YOUR_TOKEN",
      },
    ],
  };

  (async () => {
    const response = await fetch(url, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-Key": apiKey,
        "anthropic-version": "2023-06-01",
        "anthropic-beta": "mcp-client-2025-04-04",
      },
      body: JSON.stringify(payload),
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log(data);
  })();
  ```
</CodeGroup>

## OpenAI integration

For additional information about the OpenAI side of this integration, see [this post](https://gist.github.com/stevenheidel/a6c8ed8ce1632dff1284e44a17554993) from OpenAI.

* When you have your access token, you can connect to the MCP server. For details about connecting to PayPal's remote MCP server, see the <a href="/developer/tools/ai/mcp-quickstart">MCP server quickstart guide</a> in PayPal's developer documentation.
* After you connect, you can start using OpenAI with PayPal's MCP server tools by initializing the client and making a request. For example, you can ask the client to create an invoice, as shown in the following code examples.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.openai.com/v1/responses \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
      "model": "gpt-4.1",
      "tools": [
        {
          "type": "mcp",
          "server_label": "paypal-mcp",
          "server_url": "https://mcp.paypal.com/sse",
          "require_approval": "never",
          "headers": { "Authorization": "Bearer $PAYPAL_ACCESSTOKEN" }
        }
      ],
      "input": "Create an invoice for john.doe@example.com for 2 hours of consulting services at the rate of $150 per hour."
    }'
  ```

  ```python Python theme={null}
  import os
  import requests

  api_key = os.environ["OPENAI_API_KEY"]
  url = "https://api.openai.com/v1/chat/completions"
  payload = {
      "model": "gpt-4.1",
      "tools": [
          {
              "type": "mcp",
              "server_label": "paypal-mcp",
              "server_url": "https://mcp.paypal.com/sse"
          }
      ],
      "messages": [
          {
              "role": "user",
              "content": "Create an invoice for john.doe@example.com for 2 hours of consulting services at the rate of $150 per hour."
          }
      ]
  }
  headers = {
      "Content-Type": "application/json",
      "Authorization": f"Bearer {api_key}"
  }
  response = requests.post(url, json=payload, headers=headers)
  print(response.text)
  ```

  ```typescript TypeScript theme={null}
  const apiKey = process.env.OPENAI_API_KEY!;
  const url = "https://api.openai.com/v1/chat/completions";

  const payload = {
    model: "gpt-4.1",
    tools: [
      {
        type: "mcp",
        server_label: "paypal-mcp",
        server_url: "https://mcp.paypal.com/sse",
      },
    ],
    messages: [
      {
        role: "user",
        content: "Create an invoice for john.doe@example.com for 2 hours of consulting services at the rate of $150 per hour.",
      },
    ],
  };

  (async () => {
    const response = await fetch(url, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${apiKey}`,
      },
      body: JSON.stringify(payload),
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log(data);
  })();
  ```
</CodeGroup>


# MCP server quickstart guide
Source: https://docs.paypal.ai/developer/tools/ai/mcp-quickstart



[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction?wt.mc_id=studentamb_263805) makes it easier to manage and send information to models. This helps models work better in specific contexts. PayPal built an MCP server that lets merchants use natural language with their favorite MCP clients. This helps users complete business tasks more easily.

PayPal provides two ways for merchants to set up the MCP server:

* [Running the MCP server locally](#local-mcp-server). This option enables developers to download, install, and run the MCP server locally.
* [Using the MCP server remotely](#remote-mcp-server). With remote MCP server, users can continue their tasks across devices with a single login after authentication.

> **Note:** Examples in this content use Claude as the MCP client, but you can use any MCP client that you prefer, such as Cursor or Cline.

## Local MCP server

To run the MCP server locally, you need Node.js v18 or later. Download and install it from the [Node.js](https://nodejs.org/en) website if you don't have it yet.

1. To update the configuration settings for your MCP client, locate the external tools or connectors  section in the client's configuration, and add the PayPal connector configuration. In Claude, for example, you add the following configuration to `~/Claude/claude_desktop_config.json`.

```json lines expandable theme={null}
{
   "mcpServers": {
     "paypal": {
       "command": "npx",
       "args": [
         "-y",
         "@paypal/mcp",
         "--tools=all"
       ],
       "env": {
         "PAYPAL_ACCESS_TOKEN": "YOUR_PAYPAL_ACCESS_TOKEN",
         "PAYPAL_ENVIRONMENT": "SANDBOX"
       }
     }
   }
}
```

2. In the new entry, replace `YOUR_PAYPAL_ACCESS_TOKEN` with your [actual PayPal access token](https://github.com/paypal/agent-toolkit/tree/main?tab=readme-ov-file#generating-an-access-token), and set the `PAYPAL_ENVIRONMENT` to `SANDBOX` for testing or `PRODUCTION` for your production environment. Alternatively, you can set the `PAYPAL_ACCESS_TOKEN` as an environment variable. You also can pass it as an argument using `--access-token` in `args`.

3. Test your integration:
   1. Quit and restart the MCP client to apply your changes.
   2. Ask the MCP client to perform one of the supported tasks. For example, ask the MCP client to list your PayPal invoices for the last month.

## Remote MCP server

If you don't want to install MCP server locally, the other option is to use the remotely hosted MCP server.

> **Tip:** You can use your preferred MCP client for this procedure.

### Environment variables

When you develop and test, use the sandbox environment variable. For a live site, use production.

| Environment | Endpoint                         |
| ----------- | -------------------------------- |
| Sandbox     | `https://mcp.sandbox.paypal.com` |
| Production  | `https://mcp.paypal.com`         |

> **Note:** You must point to the sandbox endpoint (`https://mcp.sandbox.paypal.com`) when you work in the PayPal sandbox environment.

### Set up token authorization

PayPal supports using your PayPal client credentials to connect to the remote MCP server. With this type of authorization, you use your PayPal account's [client ID and secret](https://developer.paypal.com/api/rest/#link-getclientidandclientsecret) from [PayPal Developer Dashboard](https://developer.paypal.com/dashboard/).

```json lines expandable theme={null}
{
  "mcpServers": {
    "paypal-mcp-server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.sandbox.paypal.com/sse",
        "--header",
        "Authorization: Bearer <auth_header>"
      ]
    }
  }
}
```

### Configure your transport method

The remote MCP server supports two types of transport.

<Accordion title="Server-sent events (SSE)">
  To use SSE for testing in the sandbox, open the configuration file for your MCP client in a text editor, and replace the configuration with the following one.

  ```json lines expandable theme={null}
  {
    "mcpServers": {
      "paypal-mcp-server": {
        "command": "npx",
        "args": [
          "mcp-remote",
          "https://mcp.sandbox.paypal.com/sse"
        ]
      }
    }
  }
  ```

  In a production environment for a live site, replace the sandbox URL with this URL: `https://mcp.paypal.com/sse`.
</Accordion>

<Accordion title="Streamable HTTP">
  With streamable HTTP, servers send data to clients in chunks instead of waiting to compile a complete response. Customers can receive a response immediately when they use streamable HTTP transport. Modern applications can display results as they become available, avoiding spinners and long delays.

  To use streamable HTTP for testing in the sandbox, open the configuration file for your MCP client in a text editor, and replace the configuration with the following one.

  ```json lines expandable theme={null}
  {
    "mcpServers": {
      "paypal-mcp-server": {
        "command": "npx",
        "args": [
          "mcp-remote",
          "https://mcp.sandbox.paypal.com/http"
        ]
      }
    }
  }
  ```

  In a production environment for a live site, replace the sandbox URL with this URL: `https://mcp.paypal.com/http`.
</Accordion>

### Connect to MCP server

1. Save the file, and restart your MCP client. The MCP client sends you to the PayPal login page.
2. Provide your consent for the client to work with the MCP server:
   1. Log into PayPal when the login page appears.
   2. Authorize the client to work with the MCP server.
3. Quit and reopen your MCP client.
4. To test your integration, ask the MCP client to perform one of the supported tasks. For example, ask it to create an invoice for landscaping services for Green Lawns for \$200 with a date of last Friday.

<br />

<br />

> **Tip:** If you have trouble connecting after completing this procedure, try clearing the files that the integration adds to `~/.mcp-auth` by running:
>
> `rm -rf ~/.mcp-auth`
>
> Also be aware that emerging technology, like MCP and MCP clients, can come with performance issues or other challenges initially. For example, Windows users with Cursor might encounter a known issue when connecting to the MCP server remotely.

## MCP server tools

PayPal's MCP server offers a variety of helpful tools for performing many jobs. The <a href="/developer/tools/ai/agent-tools-ref">complete catalog of tools</a> is available in both local and remote MCP server.

The following example shows how you might use these tools.

## Example: Create an invoice using MCP server tools

Using your favorite MCP client with the MCP server to create invoices offers several advantages over creating invoices in a more traditional way. For example, a merchant can use natural language with an MCP client to process multiple invoice requests by using a drive-system connector or a file-system connector. With this connection, users can ask the MCP client to perform a PayPal-related task, which allows the clients to access their records for data and then send PayPal invoices to multiple customers in bulk.

For example, a user asks the MCP client to create an invoice with PayPal.

![Claude.ai interface with a request from a user to create a PayPal invoice](https://www.paypalobjects.com/ppdevdocs/assets/createInvoice.png)

The user supplies the necessary information, as the MCP client indicates. Then, the MCP client accesses the necessary data, creates the invoice using the MCP server, and sends it to PayPal as shown in the following illustration.

![Claude.ai interface that shows confirmation of the creation of an invoice](https://www.paypalobjects.com/ppdevdocs/assets/HoustCleaningInvoice.png)

The following example shows a sample of the invoice that a  customer receives.

![Sample invoice email to a customer](https://www.paypalobjects.com/ppdevdocs/assets/Invoice.png)


# Best practices for prompts
Source: https://docs.paypal.ai/developer/tools/ai/prompt-best-practices



Build effective prompts that unlock the full potential of PayPal AI agents with these tips. To start building AI tools using PayPal'a agent toolkit, see the [agent toolkit quickstart guide](/developer/tools/ai/agent-toolkit-quickstart/).

| Principle                                          | Usage                                                                                                                                                                                                                                                             |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Be clear about what to do and how to do it.        | Put the action first ("Create an invoice…"), then supply parameter values in the order the tool expects.                                                                                                                                                          |
| Be specific.                                       | Include every required field, such as `currency` and `invoice_id`. Unclear input can cause failure.                                                                                                                                                               |
| Separate complex tasks into simple ones.           | If you want to create a checkout sequence, you might have 3 subtasks: <br /> - Create order. <br /> - Pay order. <br /> - Create shipment.                                                                                                                        |
| Encourage the agent to "think."                    | Begin an analytic request with a statement like "Think step-by-step before calling the tool…". This can help the agent to avoid making bad calls.                                                                                                                 |
| Protect personally identifiable information (PII). | Never embed card numbers, personal financial information like social security numbers (SSNs), passwords, or secrets in prompts. The agent toolkit will reject this information, and you might violate the Payment Card Industry Data Security Standard (PCI DSS). |

## Multistep agent prompt examples

The following examples provide ideas for how to form multistep prompts for some standard use cases.

### Invoice a client

To invoice a client, you might have steps like these:

1. `create_invoice`: Create an invoice for [jane@example.com](mailto:jane@example.com) for 3 hours of CAD design at \$100 per hour.
2. `send_invoice`: Send invoice `{invoice_id}` to the client.
3. `send_invoice_reminder`: Send a reminder for invoice `{invoice_id}`.

### Create an online order

For an online order with shipping, you might use these steps in your prompts:

1. `create_order`: Place an order for 2 "Custom Gold Ring" at \$450 each (currency USD).
2. `pay_order`: Capture payment for order `{order_id}`.
3. `create_shipment_tracking`: Add tracking 1Z999AA10123456784 with carrier UPS to order `{order_id}`.

### Sell a subscription

Subscriptions are a type of product, which come with specific parameters. To sell subscriptions, you might complete these tasks using your agent tools:

1. `create_product`: Create a new product named "Coffee-Club Subscription" with the type of `DIGITAL`.
2. `create_subscription_plan`: Create a `MONTH` subscription plan for product `{product_id}` named "Monthly Roast Plan" at the price of 20 USD per month.
3. `create_subscription`: Create a subscription to plan `{plan_id}` for subscriber Alice Brown whose email address is [alice@example.com](mailto:alice@example.com).

### Evaluate and resolve disputes

To manage disputes, you might use prompts like these:

1. `list_disputes`: List all `OPEN` disputes.
2. `get_dispute`: Get details for dispute `{dispute_id}`.
3. `accept_dispute_claim`: Accept the dispute with ID `{dispute_id}`.

### Add and confirm the details for a new product

When you add a new product, you'll want to confirm that the product appears where and how it should. These prompts could do that:

1. `create_product`: Create a new product called "Limited-Edition Walnut Serving Tray" of type `PHYSICAL`.
2. `list_product`: List all products (`page` 1, `page_size` 25).
3. `show_product_details`: Show the details for product `{product_id}`.

### Create an invoice with a QR code

This example shows how to invoice a client and use a QR code for on-site payment. To complete this sort of process, you might use the following tools and steps:

1. `create_invoice`: Create an invoice for [bob@example.com](mailto:bob@example.com) for one "Pop-up Booth Entry Fee" at 20 USD.
2. `send_invoice`: Send invoice `{invoice_id}`.
3. `generate_invoice_qr_code`: Generate a QR code for invoice `{invoice_id}`.

### Fix an invoice error

Correcting an invoice error might require steps like these:

1. `cancel_sent_invoice`: Cancel the `SENT` invoice with ID `{invoice_id}`.
2. `create_invoice`: Create a corrected invoice for [dana@example.com](mailto:dana@example.com): 4 h consulting at \$90 USD/h.
3. `send_invoice`: Send invoice `{new_invoice_id}`.

### Reconcile a transaction

To reconcile a transaction, compare the order details to the transaction itself:

1. `list_transaction`: List of my transactions for the last 14 days.
2. `get_order`: Get the details for order `{order_id}`.

### Cancel a subscription

If a user wants to cancel a subscription, you might need to check the terms of their subscription. To do that, you could use these steps:

1. `show_subscription_details`: Show the details for subscription ID `{subscription_id}`.
2. `cancel_subscription`: Cancel the subscription ID `{subscription_id}`.

## See also

For more information about using AI with PayPal, see [PayPal's AI resources for developers](/developer/tools/ai/ai-intro/).


# Upgrade from v5
Source: https://docs.paypal.ai/developer/upgrade/sdk/js/v5-v6



Use this guide to upgrade your PayPal integration from the JavaScript SDK v5 to the JavaScript SDK v6. The v6 SDK introduces custom elements for UI, uses payment sessions to manage checkout flows, and offers flexible authentication with a client ID or client token.

***

## Compare v5 and v6

The following table shows how the v5 and v6 SDKs are different.

| Feature                    | v5                                                                                           | v6                                                                                       |
| -------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **SDK script URL**         | You load the SDK with `https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&currency=USD`. | You load the SDK with `https://www.sandbox.paypal.com/web-sdk/v6/core`.                  |
| **Global `paypal` object** | All features are available from the global object.                                           | You call `createInstance`, which sets up the SDK.                                        |
| **Button rendering**       | You render buttons with `paypal.Buttons({ ... }).render()`.                                  | You use `<paypal-button/>` with an event listener and call `session.start()`.            |
| **Callbacks**              | You pass callbacks into `paypal.Buttons()`.                                                  | You pass callbacks into a checkout session, such as `createPayPalOneTimePaymentSession`. |
| **Venmo support**          | Venmo is included automatically in the smart stack.                                          | You enable Venmo with the `venmo-payments` component.                                    |

## Migration overview

The following sections explain the main changes and concepts you need to consider when upgrading from v5 to v6 of the PayPal JavaScript SDK.

### SDK script

In v5, you load the SDK using a script tag with the client ID and configuration directly in the URL.

```javascript theme={null}
<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&currency=USD"></script>
```

In v6, you load the SDK core script without the client ID or any configuration in the URL.

```javascript theme={null}
<script async src="https://www.sandbox.paypal.com/web-sdk/v6/core" onload="onPayPalLoaded()"></script>
```

### Authentication: Client ID (Recommended)

v5 uses your client ID in the script URL. v6 uses your client ID in the `createInstance` call when initializing the SDK (recommended for most integrations):

```javascript theme={null}
const sdkInstance = await window.paypal.createInstance({
  clientId: "YOUR_CLIENT_ID",
  components: ["paypal-payments", "venmo-payments"],
  pageType: "checkout",
});
```

**Alternative: Client Token**

For specific features like PayPal payment vaulting or Fastlane, you'll need to use client token authentication instead:

```javascript theme={null}
// Fetch browser-safe client token from your server
async function getBrowserSafeClientToken() {
  const response = await fetch("/paypal-api/auth/browser-safe-client-token");
  const { accessToken } = await response.json();
  return accessToken;
}

const clientToken = await getBrowserSafeClientToken();
const sdkInstance = await window.paypal.createInstance({
  clientToken,
  components: ["fastlane"],  // or other components requiring client token
  pageType: "checkout",
});
```

See [Authenticate the SDK](/developer/how-to/sdk/js/v6/configuration#authenticate-the-sdk) for details on when to use each method.

### Render payment buttons

In v5, you render PayPal buttons directly through `paypal.Buttons().render()`.

```javascript theme={null}
paypal.Buttons({ ... }).render('#paypal-button-container');
```

In v6, you use custom elements for payment buttons. You control visibility and actions in JavaScript.

```javascript theme={null}
<paypal-button id="paypal-button" type="pay" hidden></paypal-button>
<venmo-button id="venmo-button" type="pay" hidden></venmo-button>
```

### Manage orders and callbacks

In v5, you define `createOrder` and `onApprove` inside the button configuration.

```javascript theme={null}
paypal.Buttons({
  createOrder: function(data, actions) {
    // call your server to create an order
  }
  onApprove: function(data, actions) {
    // call your server to capture the order
  }
}).render('#paypal-button-container');
```

In v6, you define these as standalone functions and pass them to the payment session.

```javascript theme={null}
async function createOrder() {
  // do not pass this function to the session
  // call your server to create an order
  // pass the order ID Promise returned from this function to start()
}
async function onApprove({ orderId }) {
  // call your server to capture the order
}
const paypalCheckout = sdkInstance.createPayPalOneTimePaymentSession({
  onApprove,
});
```

### Handle sessions and button events

In v5, you handle button logic inside the `paypal.Buttons` configuration.

In v6, you create a payment session and attach a click handler to the button.

```javascript theme={null}
const paypalPaymentSession = sdkInstance.createPayPalOneTimePaymentSession({
  onApprove, onCancel, onError
});

paypalButton.addEventListener("click", async () => {
  await paypalPaymentSession.start(
    { presentationMode: "auto" },
    createOrder()
  );
});
```

### Check eligibility

In v5, eligibility checks are built in internally before rendering each button.

In v6, you check eligibility with the `findEligibleMethods` method or by calling the server-side API.

```javascript theme={null}
const paymentMethods = await sdkInstance.findEligibleMethods({ currencyCode: "USD" });
if (paymentMethods.isEligible("paypal")) {
  configurePayPalButton(sdkInstance);
}
```

## Summary of changes

* v6 uses client ID authentication (similar to v5) for most integrations, making migration straightforward. A client token is required only for specific features like PayPal vaulting and Fastlane.
* You use custom elements and payment sessions instead of button configurations.
* Built-in methods to check payment method availability.
* Load only the components you need for your integration.
* You pass callbacks directly to checkout sessions instead of button configurations.

For detailed code samples and advanced scenarios, see the Javascript SDK v6 examples on [GitHub](https://github.com/paypal-examples/v6-web-sdk-sample-integration).


# Agentic commerce services
Source: https://docs.paypal.ai/growth/agentic-commerce/overview



PayPal's agentic commerce services help create AI-powered shopping experiences, so customers can shop using everyday language. These services help customers find products, manage their shopping carts, and complete purchases easily across different online stores and platforms.

> **Important:** To access and use agentic commerce services, merchants must complete [this form](https://www.paypal.com/us/business/ai#form) to contact the AI team at PayPal and request access.

For information about some of PayPal's other AI offerings, see [PayPal's AI resources for developers](/developer/tools/ai/ai-intro/).

## Benefits

* **Easy setup:** Connect your product listings to PayPal's partners like Wix, Cymbio, Commerce (BigCommerce & Feedonomics), and Shopware to make your products easy to find and buy.
* **Better product discovery and more sales:** Let customers find your products through AI shopping assistants that understand what they're looking for, turning conversations into purchases and boosting your sales.
* **Keep control of your customer relationships:** With [Store Sync](#store-sync), which includes [product catalog integration](/growth/agentic-commerce/store-sync/create-a-product-catalog) and [cart operations](/growth/agentic-commerce/store-sync/your-api/api-overview/), you stay in charge of your business. You control your brand appearance and customer communications for all AI-powered transactions.
* **Connect once to reach many platforms:** With [Store Sync](#store-sync) and [Agent Ready](#agent-ready), you can connect to PayPal once and reach customers across multiple AI shopping platforms.

## Store Sync

Store Sync makes your products discoverable by AI shopping assistants and lets them place orders directly into your existing order management systems. Customers can simply tell an AI assistant what they want, and the AI can connect to your store to help with finding products, managing shopping carts, and completing purchases.

With Store Sync, you can open your online store to AI shopping assistants and automated shopping tools. Instead of browsing websites, customers can simply tell an AI assistant what they want. The AI assistant can then securely connect to your store to help find products, manage their shopping carts, and complete purchases.

## Agent Ready

With small changes to your current payment setup, you can accept payments through AI assistants, like a store's shopping bot within ChatGPT. Instead of building separate connections for each AI platform, you can use your existing PayPal tools while PayPal handles security and compatibility across different platforms. Agent Ready grows with your business, supporting both supervised and automatic shopping scenarios.

## Next steps

Use these pages to unlock the capabilities of PayPal's agentic commerce services:

* [Store Sync](/growth/agentic-commerce/store-sync/overview/)
* [Agent Ready](/growth/agentic-commerce/agent-ready/overview)

> **Tip:** For help with code snippets and API references, including migration, [get the PayPal extension from the Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=PayPal.vscode-paypal).


# Advanced use cases
Source: https://docs.paypal.ai/growth/agentic-commerce/store-sync/your-api/advanced-use-cases



To extend your API beyond basic product sales, you can enable specialized shopping experiences. This guide shows you how to:

* Handle gift cards with recipient information and delivery scheduling.
* Use geographic coordinates for location-aware services, such as local-inventory checking and delivery-radius validation.
* Support multi-item carts with create, update, and per-item error handling.

> **Note:** You can view the complete protocol reference for the [Cart API](/reference/api/rest/cart-operations/create-cart/) and the [Complete Checkout API](/reference/api/rest/checkout/complete-checkout/).

## Gift cards

Create a cart containing a gift card with recipient details and scheduled delivery.

```bash lines expandable theme={null}
POST /api/paypal/v1/merchant-cart
Content-Type: application/json
Authorization: Bearer <paypal-jwt-token>

{
  "items": [
    {
      "variant_id": "GIFTCARD-100",
      "quantity": 1,
      "gift_options": {
        "is_gift": true,
        "recipient": {
          "name": "Mary Johnson",
          "email": "mary@example.com"
        },
        "delivery_date": "2024-12-25T09:00:00Z",
        "sender_name": "John Smith",
        "gift_message": "Merry Christmas! Enjoy your shopping."
      }
    }
  ],
  "payment_method": {
    "type": "paypal"
  }
}
```

## Geographic coordinates

Some merchants offer location-based services that require precise geographic positioning beyond standard postal addresses. The Cart API supports optional latitude/longitude coordinates to enable features like local inventory checking, distance-based pricing, delivery radius validation, and enhanced shipping calculations. This geographic data operates independently from shipping addresses, allowing you to provide location-aware commerce experiences while maintaining clean separation between postal and coordinate data.

### Latitude and longitude support strategy

Geographic coordinates are optional. This feature is for merchants who can provide enhanced location services.
Geographic coordinates are provided in a separate `geo_coordinates` field, distinct from the `shipping_address` object. This clean separation allows:

* Postal addresses to remain focused on standard shipping data
* Geographic coordinates to provide precise location enhancement
* Independent handling of address and coordinate data
* Graceful degradation when coordinates aren't supported

Here's how to structure address and coordinate data separately:

```json lines expandable theme={null}
{
  "shipping_address": {
    "address_line_1": "123 Main Street",
    "admin_area_2": "San Jose",
    "admin_area_1": "CA",
    "postal_code": "95131",
    "country_code": "US"
  },
  "geo_coordinates": {
    "latitude": "37.3349",
    "longitude": "-122.0090",
    "subdivision": "CA",
    "country_code": "US"
  }
}
```

### Geographic fields

The `geo_coordinates` object contains precise location data that enhances address information for location-aware services.

| Field                      | Description                                                               | Example                                       |
| -------------------------- | ------------------------------------------------------------------------- | --------------------------------------------- |
| `latitude` and `longitude` | Precise WGS84 coordinates in decimal degrees                              | `latitude: "37.3349", longitude: "-122.0090"` |
| `subdivision`              | Administrative division (state, province, region) using ISO 3166-2 format | `subdivision: "CA"` (California)              |
| `country_code`             | ISO 3166-1 alpha-2 country code for the coordinate location               | `country_code: "US"`                          |

## Multi-item carts

The Cart API supports carts with multiple items. You can create a cart with several products in a single request, update the cart by replacing the full items list, and receive per-item error reporting when issues occur.

### Create a cart with multiple items

Include multiple items in the `items` array, each with its own `variant_id`, `quantity`, and pricing.

```json lines expandable theme={null}
{
  "items": [
    {
      "variant_id": "SHIRT-BLUE-M",
      "quantity": 2,
      "name": "Blue T-Shirt",
      "description": "Cotton crew neck, Size M",
      "price": { "currency_code": "USD", "value": "29.99" }
    },
    {
      "variant_id": "JEANS-SLIM-32",
      "quantity": 1,
      "name": "Slim Fit Jeans",
      "description": "Classic slim fit, Size 32",
      "price": { "currency_code": "USD", "value": "79.99" }
    },
    {
      "variant_id": "SNEAKERS-WHITE-10",
      "quantity": 1,
      "name": "White Sneakers",
      "description": "Classic white, Size 10",
      "price": { "currency_code": "USD", "value": "89.99" }
    }
  ],
  "totals": {
    "subtotal": { "currency_code": "USD", "value": "229.96" },
    "shipping": { "currency_code": "USD", "value": "9.99" },
    "tax": { "currency_code": "USD", "value": "20.70" },
    "total": { "currency_code": "USD", "value": "260.65" }
  }
}
```

### Update cart items

To update a cart, send the complete items list in the request. The merchant compares this list to the existing cart and applies the differences. A single update can add new items, remove existing items, and change quantities.

```json lines expandable theme={null}
{
  "items": [
    {
      "variant_id": "SHIRT-BLUE-M",
      "quantity": 3,
      "name": "Blue T-Shirt",
      "description": "Cotton crew neck, Size M",
      "price": { "currency_code": "USD", "value": "29.99" }
    },
    {
      "variant_id": "SNEAKERS-WHITE-10",
      "quantity": 1,
      "name": "White Sneakers",
      "description": "Classic white, Size 10",
      "price": { "currency_code": "USD", "value": "89.99" }
    },
    {
      "variant_id": "HAT-BLACK-OS",
      "quantity": 1,
      "name": "Black Cap",
      "description": "One Size",
      "price": { "currency_code": "USD", "value": "24.99" }
    }
  ]
}
```

In this example, compared to the original cart: `SHIRT-BLUE-M` quantity increased from 2 to 3, `JEANS-SLIM-32` was removed, and `HAT-BLACK-OS` was added.

### Error handling for multiple items

Return a separate validation issue for each item that fails, and include the `variant_id` so the AI agent can identify the affected item. Errors can be reported in two ways:

* **`200/201` with `INCOMPLETE` status** — the cart was created or updated, but some items have issues. Report them in the `validation_issues` array.
* **`422 Unprocessable Entity`** — the cart could not be created or the update could not be applied. Report per-item errors in `details[].business_context`.

The following example shows an `INCOMPLETE` response where 2 out of 3 items have inventory issues:

```json lines expandable theme={null}
{
  "id": "CART-MULTI-001",
  "status": "INCOMPLETE",
  "validation_status": "INVALID",
  "items": [
    {
      "variant_id": "SHIRT-BLUE-M",
      "quantity": 2,
      "name": "Blue T-Shirt",
      "price": { "currency_code": "USD", "value": "29.99" }
    },
    {
      "variant_id": "JEANS-SLIM-32",
      "quantity": 2,
      "name": "Slim Fit Jeans",
      "price": { "currency_code": "USD", "value": "79.99" }
    },
    {
      "variant_id": "SNEAKERS-WHITE-10",
      "quantity": 1,
      "name": "White Sneakers",
      "price": { "currency_code": "USD", "value": "89.99" }
    }
  ],
  "validation_issues": [
    {
      "code": "INVENTORY_ISSUE",
      "type": "BUSINESS_RULE",
      "message": "Product is currently out of stock",
      "user_message": "Blue T-Shirt (Size M) is out of stock. Would you like a different color?",
      "variant_id": "SHIRT-BLUE-M",
      "context": {
        "specific_issue": "ITEM_OUT_OF_STOCK",
        "available_quantity": 0,
        "requested_quantity": 2
      },
      "resolution_options": [
        { "action": "REMOVE_ITEM", "label": "Remove from cart" },
        { "action": "SUGGEST_ALTERNATIVE", "label": "View other colors" }
      ]
    },
    {
      "code": "INVENTORY_ISSUE",
      "type": "INVALID_DATA",
      "message": "Requested quantity exceeds available stock",
      "user_message": "Only 1 unit of Slim Fit Jeans is available. You requested 2.",
      "variant_id": "JEANS-SLIM-32",
      "context": {
        "specific_issue": "INSUFFICIENT_INVENTORY",
        "available_quantity": 1,
        "requested_quantity": 2
      },
      "resolution_options": [
        { "action": "MODIFY_CART", "label": "Update to available quantity" }
      ]
    }
  ],
  "totals": {
    "subtotal": { "currency_code": "USD", "value": "89.99" },
    "shipping": { "currency_code": "USD", "value": "9.99" },
    "total": { "currency_code": "USD", "value": "99.98" }
  }
}
```


# Integration use cases
Source: https://docs.paypal.ai/growth/agentic-commerce/store-sync/your-api/integration-use-cases



To handle real-world shopping scenarios that AI agents encounter, implement robust error handling patterns that provide clear context and actionable resolution options. This guide shows you how to structure validation responses for common integration challenges including inventory issues, pricing changes, shipping restrictions, geographic limitations, and system maintenance scenarios.

These validation issues are returned either as part of an `INCOMPLETE` cart in the `validation_issues` array, or within a `422 Unprocessable Entity` response in `details[].business_context` when the merchant could not create the cart or apply the requested updates.

> **Note:** You can view the complete protocol reference for the [Cart API](/reference/api/rest/cart-operations/create-cart/) and the [Complete Checkout API](/reference/api/rest/checkout/complete-checkout/).

### Inventory and stock management errors

Inventory issues are among the most common errors in e-commerce. These examples show how to handle out-of-stock scenarios, back-orders, and discontinued products gracefully.

Return a separate validation issue for each item that fails, and include the `variant_id` so the AI agent can identify the affected item.

#### Out of stock with alternatives

When a requested item is out of stock, provide alternative products and clear communication about availability.

```json lines expandable theme={null}
{
  "code": "INVENTORY_ISSUE",
  "type": "BUSINESS_RULE",
  "message": "Product is no longer available",
  "user_message": "The Blue T-Shirt is temporarily out of stock. Would you like to try a different color?",
  "variant_id": "SHIRT-BLUE-M",
  "context": {
    "specific_issue": "ITEM_OUT_OF_STOCK",
    "available_quantity": 0,
    "requested_quantity": 1,
    "suggested_alternatives": ["SHIRT-RED-M", "SHIRT-GREEN-M"],
    "restock_date": "2024-07-20T00:00:00Z"
  },
  "resolution_options": [
    {
      "action": "SUGGEST_ALTERNATIVE",
      "label": "View similar colors",
      "metadata": {
        "priority": "high",
        "auto_applicable": true
      }
    },
    {
      "action": "WAIT_FOR_RESTOCK",
      "label": "Notify when back in stock",
      "metadata": {
        "estimated_time": "5-7 days",
        "priority": "medium"
      }
    },
    {
      "action": "REMOVE_ITEM",
      "label": "Remove from cart",
      "metadata": {
        "priority": "low"
      }
    }
  ]
}
```

#### Back-order scenario

For items that can be back-ordered, communicate delivery delays and allow customers to decide.

```json lines expandable theme={null}
{
  "code": "INVENTORY_ISSUE",
  "type": "BUSINESS_RULE",
  "message": "Item is currently back-ordered",
  "user_message": "This item will ship in 2-3 weeks. Would you like to proceed with your order?",
  "variant_id": "LAPTOP-PRO-15",
  "context": {
    "available_quantity": 0,
    "back_order_limit": 50,
    "estimated_ship_date": "2024-08-15T00:00:00Z",
    "current_back_orders": 23
  },
  "resolution_options": [
    {
      "action": "ACCEPT_BACK_ORDER",
      "label": "Order anyway (ships August 15th)",
      "metadata": {
        "estimated_time": "2-3 weeks",
        "priority": "high",
        "cost_impact": "$0.00"
      }
    },
    {
      "action": "SUGGEST_ALTERNATIVE",
      "label": "View similar laptops in stock",
      "metadata": {
        "priority": "medium",
        "auto_applicable": true
      }
    }
  ]
}
```

#### Discontinued product

When a product is no longer available, guide customers to newer or similar alternatives.

```json lines expandable theme={null}
{
  "code": "INVENTORY_ISSUE",
  "type": "BUSINESS_RULE",
  "message": "Product has been discontinued",
  "user_message": "This product is no longer available. Here are some similar alternatives.",
  "variant_id": "PRODUCT-OLD-MODEL",
  "context": {
    "discontinuation_date": "2024-02-01T00:00:00Z",
    "suggested_alternatives": ["PRODUCT-NEW-MODEL", "PRODUCT-SIMILAR"],
    "upgrade_available": true
  },
  "resolution_options": [
    {
      "action": "SUGGEST_ALTERNATIVE",
      "label": "View newer model (+$50)",
      "metadata": {
        "cost_impact": "+$50.00",
        "priority": "high"
      }
    },
    {
      "action": "REMOVE_ITEM",
      "label": "Remove from cart",
      "metadata": {
        "priority": "low"
      }
    }
  ]
}
```

### Pricing and financial errors

Price changes can occur between cart creation and checkout. These error patterns help you handle pricing discrepancies transparently while maintaining customer trust.

#### Price change during checkout

Handle price increases that occur between cart creation and checkout with transparency.

```json lines expandable theme={null}
{
  "code": "PRICING_ERROR",
  "type": "BUSINESS_RULE",
  "message": "Product price has changed since cart creation",
  "user_message": "The price for Ocean Blue T-Shirt has increased from $29.99 to $34.99. Continue with new price?",
  "variant_id": "SHIRT-OCEAN-BLUE",
  "context": {
    "original_price": "29.99",
    "current_price": "34.99",
    "currency_code": "USD",
    "price_change_reason": "promotional_ended",
    "price_increase": "5.00"
  },
  "resolution_options": [
    {
      "action": "ACCEPT_NEW_PRICE",
      "label": "Continue with $34.99",
      "metadata": {
        "cost_impact": "+$5.00",
        "priority": "high",
        "auto_applicable": false
      }
    },
    {
      "action": "REMOVE_ITEM",
      "label": "Remove from cart",
      "metadata": {
        "cost_impact": "-$29.99",
        "priority": "medium"
      }
    }
  ]
}
```

### Shipping and address errors

Address validation ensures successful delivery while preventing fraud. These examples demonstrate handling invalid addresses, PO box restrictions, and shipping limitations.

#### Invalid shipping address

When address validation fails, provide specific corrections to help customers fix the issue.

```json lines expandable theme={null}
{
  "code": "SHIPPING_ERROR",
  "type": "INVALID_DATA",
  "message": "Shipping address validation failed",
  "user_message": "The shipping address appears to be incomplete or invalid. Please check and correct.",
  "field": "shipping_address",
  "context": {
    "validation_failures": ["invalid_postal_code", "missing_street_number"],
    "suggested_corrections": {
      "postal_code": "90210",
      "address_line_1": "123 Main Street"
    },
    "address_quality_score": 0.3
  },
  "resolution_options": [
    {
      "action": "UPDATE_ADDRESS",
      "label": "Use suggested corrections",
      "metadata": {
        "priority": "high",
        "auto_applicable": true
      }
    },
    {
      "action": "PROVIDE_MISSING_FIELD",
      "label": "Add street number",
      "metadata": {
        "priority": "medium"
      }
    }
  ]
}
```

#### PO box restrictions

For this example, items that require signature delivery cannot be sent to a PO box. Explain why PO box delivery isn't available for those items.

```json theme={null}
{
  "code": "SHIPPING_ERROR",
  "type": "BUSINESS_RULE",
  "message": "PO box delivery not available for this order",
  "user_message": "This order contains items requiring signature confirmation and cannot be delivered to a PO box.",
  "field": "shipping_address",
  "context": {
    "restricted_items": ["ELECTRONICS-LAPTOP-001"],
    "restriction_reason": "signature_required",
    "po_box_detected": true
  },
  "resolution_options": [
    {
      "action": "UPDATE_ADDRESS",
      "label": "Use street address instead",
      "metadata": {
        "priority": "high"
      }
    },
    {
      "action": "REMOVE_ITEM",
      "label": "Remove items requiring signature",
      "metadata": {
        "cost_impact": "-$899.00",
        "priority": "low"
      }
    }
  ]
}
```

### Geographic and legal restrictions

Some products or merchants have regional restrictions due to regulations or business policies. These errors help communicate limitations clearly to customers.

#### Regional sales restrictions

Communicate geographic limitations due to business policies or regulatory compliance.

```json lines expandable theme={null}
{
  "code": "BUSINESS_RULE_ERROR",
  "type": "BUSINESS_RULE",
  "message": "Store does not sell to this region",
  "user_message": "Unfortunately, we don't ship to your location due to regulatory restrictions. Please check our shipping policy.",
  "context": {
    "restricted_region": "EU",
    "customer_country": "DE",
    "restriction_reason": "regulatory_compliance",
    "supported_countries": ["US", "CA", "GB"],
    "policy_url": "https://merchant.com/shipping-policy"
  },
  "resolution_options": [
    {
      "action": "CONTACT_SUPPORT",
      "label": "Contact support for alternatives",
      "url": "https://merchant.com/support",
      "metadata": {
        "priority": "medium"
      }
    }
  ]
}
```

### System and store errors

Temporary system issues require special handling to maintain customer relationships. These patterns show how to communicate maintenance windows and system unavailability.

#### Store maintenance mode

During scheduled maintenance, provide clear timing for when services will resume.

```json lines expandable theme={null}
{
  "code": "BUSINESS_RULE_ERROR",
  "type": "BUSINESS_RULE",
  "message": "Store is currently in maintenance mode",
  "user_message": "The store is temporarily closed for maintenance. Please try again later.",
  "context": {
    "maintenance_end_time": "2024-06-25T09:00:00Z",
    "service_status": "maintenance",
    "reason": "system_upgrade",
    "retry_after": 7200
  },
  "resolution_options": [
    {
      "action": "RETRY_LATER",
      "label": "Try again at 9:00 AM",
      "metadata": {
        "estimated_time": "2 hours",
        "priority": "high"
      }
    }
  ]
}
```


# Set up your API
Source: https://docs.paypal.ai/growth/agentic-commerce/store-sync/your-api/set-up-your-api/braintree-integration



To enable AI agents to create and manage shopping carts through your store, integrate with PayPal's Cart API. This guide shows you how to implement the 3 core endpoints that handle cart creation, updates, and checkout completion, including Braintree integration for payment processing.

> **Note:** You can view the complete protocol reference for the [Cart API](/reference/api/rest/cart-operations/create-cart/) and the [Complete Checkout API](/reference/api/rest/checkout/complete-checkout/).

## API endpoints

The Cart API provides 3 core endpoints that handle the complete cart lifecycle. Each endpoint serves a specific purpose in the agentic shopping flow.

* `POST /merchant-cart` [creates](#create-a-cart) a new cart.
* `PUT /merchant-cart/{id}` [updates](#update-a-cart) an existing cart.
* `POST /merchant-cart/{id}/checkout` completes the checkout process.

> **Tip:** You can view the PayPal Cart schema [here](https://github.com/paypal/agent-commerce/blob/main/v1/api-spec.yaml).

### Authentication with PayPal-supplied JWTs

* **Request authentication:** Every API call includes the token in the [authorization header](#receive-token-in-the-authorization-header).
* **Merchant identification:** Tokens contain your merchant ID and permissions.
* **Security verification:** Verify token signature using PayPal's public keys. See [Verify the token](#verify-the-token).

#### Receive token in the authorization header

Every API request must include the PayPal-supplied JWT in the authorization header.

```bash lines theme={null}
POST /api/paypal/v1/merchant-cart
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6Ik1FUkNIQU5ULTEyMyIsInNjb3BlIjpbImNhcnQiXSwiaWF0IjoxNzE5MjQwMDAwLCJleHAiOjE3MTkyNDM2MDB9.signature
Content-Type: application/json

{
  ...cart create request body
}
```

#### Verify the token

1. Parse Authorization header: `"Bearer \<token\>"`.
2. Verify token signature using the PayPal [public key](https://www.paypal.ai/.well-known/jwks.json).
3. Validate the token expiration.

### Braintree credentials

To enable agentic checkout, we will need your Braintree credentials: `merchant_id` and `tokenization_key`. For more information, see [Important gateway credentials](https://developer.paypal.com/braintree/articles/control-panel/important-gateway-credentials).

### Create a cart

To create a new shopping cart with specified items, use `POST /merchant-cart`. The cart can also include customer information, such as a shipping address and payment method to use.

#### Cart creation

This example of a request payload shows how to structure a cart creation request with items and customer information.

```bash lines theme={null}
POST /api/paypal/v1/merchant-cart
Content-Type: application/json
Authorization: Bearer <paypal-jwt>

{
  "items": [...],
  "shipping_address": {...},
  "billing_address": {...},
  "customer": {"email_address": "customer@example.com"},
  "payment_method": {"type": "paypal"},
}
```

> **Important:** PayPal uses your Braintree credentials to create a token. You do not need to return a token here.

### Update a cart

To update an existing cart by replacing its contents with the provided data, use `PUT /merchant-cart/{id}`. Use this endpoint to add or remove items, change quantities, update the shipping address, apply discounts, and so on.

> **Important:** `PUT` replaces *the entire cart*. It removes or resets any fields that you do not include in your request. This is a complete replacement operation, not a merge.

Include all current cart data when making changes, as shown in the following example.

```json lines expandable theme={null}
{
  "items": [
    {"variant_id": "EXISTING-ITEM-VARIANT", "quantity": 5}
  ],
  "customer": {
    "email_address": "customer@example.com"
  },
  "shipping_address": {
    "address_line_1": "123 Current Street",
    "admin_area_2": "Current City",
    "admin_area_1": "CA",
    "postal_code": "95131",
    "country_code": "US"
  },
  "payment_method": {...}
}
```

### Complete checkout

To complete the checkout process for a cart, use `POST /merchant-cart/{id}/checkout`. This endpoint finalizes the purchase by processing the payment using the specified payment method.

```bash lines theme={null}
POST /api/paypal/v1/merchant-cart/CART-123/checkout
Content-Type: application/json
Authorization: Bearer <paypal-jwt-token>

{
  "payment_method": {
    "type": "paypal",
    "token": "15a93f45-fda1-12ee-7e10-1e0a3bdf2503", //BT nonce
  }
}
```

> **Important:** Within this endpoint, PayPal passes a Braintree nonce, which you can then use to create a transaction.

## Merchant cart response

The following examples show some successful responses that your API can return.

### Create and update cart response

Return comprehensive cart details including status, items, totals, and payment information.

```json lines expandable theme={null}
{
  "id": "CART-123",
  "status": "CREATED",
  "validation_status": "VALID",
  "validation_issues": [],
  "items": [
    {
      "variant_id": "SHIRT-001",
      "quantity": 1,
      "name": "Blue T-Shirt",
      "unit_amount": { "currency_code": "USD", "value": "25.00" },
      "item_total": { "currency_code": "USD", "value": "25.00" }
    }
  ],
  "shipping_address": {...},
  "billing_address": {...},
  "totals": {
    "subtotal": { "currency_code": "USD", "value": "25.00" },
    "shipping": { "currency_code": "USD", "value": "5.99" },
    "tax": { "currency_code": "USD", "value": "2.70" },
    "total": { "currency_code": "USD", "value": "33.69" }
  },
  "payment_method": {
    "type": "PAYPAL",
  },
}
```

### Complete checkout response

After successful checkout, return the completed cart status with payment confirmation.

```json lines expandable theme={null}
{
  "id": "CART-123",
  "status": "COMPLETED",
  "validation_status": "VALID",
  "validation_issues": [],
  "payment_confirmation": {
    "merchant_order_number": "ORDER-789",
    "order_review_page": "https://yourstore.com/orders/789"
  },
  "totals": {
    "total": {
      "currency_code": "USD",
      "value": "37.19"
    }
  }
}
```

## Next steps

Continue by [learning more about response handling](/growth/agentic-commerce/store-sync/your-api/set-up-your-api/response-handling).


# Set up your API
Source: https://docs.paypal.ai/growth/agentic-commerce/store-sync/your-api/set-up-your-api/orders-v2-integration



To enable AI agents to create and manage shopping carts through your store, integrate with PayPal's Cart API. This guide shows you how to implement the 3 core endpoints that handle cart creation, updates, and checkout completion, including PayPal [Orders API v2](https://developer.paypal.com/docs/api/orders/v2/) integration for payment processing.

> **Note:** You can view the complete protocol reference for the [Cart API](/reference/api/rest/cart-operations/create-cart/) and the [Complete Checkout API](/reference/api/rest/checkout/complete-checkout/).

## API endpoints

The Cart API provides 3 core endpoints that handle the complete cart lifecycle. Each endpoint serves a specific purpose in the agentic shopping flow.

* `POST /merchant-cart` [creates](#create-a-cart) a new cart.
* `PUT /merchant-cart/{id}` [updates](#update-a-cart) an existing cart.
* `POST /merchant-cart/{id}/checkout` completes the checkout process.

> **Tip:** You can view the PayPal Cart schema <a href="/api-reference/paypal-cart-agentic-commerce-v1.yaml">here</a>.

### Authentication with PayPal-supplied JWTs

* **Request authentication:** Every API call includes the token in the [authorization header](#receive-token-in-the-authorization-header).
* **Merchant identification:** Tokens contain your merchant ID and permissions.
* **Security verification:** Verify token signature using PayPal's public keys. See [Verify the token](#verify-the-token).

#### Receive token in the authorization header

Every API request must include the PayPal-supplied JWT in the authorization header.

```bash lines theme={null}
POST /api/paypal/v1/merchant-cart
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6Ik1FUkNIQU5ULTEyMyIsInNjb3BlIjpbImNhcnQiXSwiaWF0IjoxNzE5MjQwMDAwLCJleHAiOjE3MTkyNDM2MDB9.signature
Content-Type: application/json

{
  ...cart create request body
}
```

#### Verify the token

1. Parse the authorization header: `"Bearer \<token\>"`.
2. Verify token signature using the PayPal [public key](https://www.paypal.ai/.well-known/jwks.json).
3. Validate the token expiration.

### Create a cart

To create a new shopping cart with specified items, use `POST /merchant-cart`. The cart also can include customer information, such as a shipping address and payment method to use.

This example of a request payload shows how to structure a cart creation request with items and customer information.

```bash lines theme={null}
POST /api/paypal/v1/merchant-cart
Content-Type: application/json
Authorization: Bearer <paypal-jwt>

{
  "items": [...],
  "shipping_address": {...},
  "billing_address": {...},
  "customer": {"email_address": "customer@example.com"},
  "payment_method": {"type": "paypal"},
}
```

### Update a cart

To update an existing cart by replacing its contents with the provided data, use `PUT /merchant-cart/{id}`. With this endpoint, you can add or remove items, change quantities, update the shipping address, apply discounts, and so on.

> **Important:** `PUT` replaces *the entire cart*. It removes or resets any fields that you do not include in your request. This is a complete replacement operation, not a merge.

Include all current cart data when making changes, as shown in the following example.

```json lines expandable theme={null}
{
  "items": [
    {"variant_id": "EXISTING-ITEM-VARIANT", "quantity": 5}
  ],
  "customer": {
    "email_address": "buyer@example.com"
{
  "items": [
    {"variant_id": "EXISTING-ITEM-VARIANT", "quantity": 5}
  ],
  "customer": {
    "email_address": "customer@example.com"
  },
  "shipping_address": {
    "address_line_1": "123 Current Street",
    "admin_area_2": "Current City",
    "admin_area_1": "CA",
    "postal_code": "95131",
    "country_code": "US"
  },
  "payment_method": {...}
}
```

> **Important:** Within this endpoint, a merchant is expected to implement [Orders API v2](https://developer.paypal.com/docs/api/orders/v2/) integration. For more information about this, see [Cart update with an order update](#cart-update-with-an-order-update).

### Complete checkout

To complete the checkout process for a cart, use `POST /merchant-cart/{id}/checkout`. This endpoint finalizes the purchase by processing the payment using the specified payment method.

```bash lines theme={null}
POST /api/paypal/v1/merchant-cart/CART-123/checkout
Content-Type: application/json
Authorization: Bearer <paypal-jwt-token>

{
  "payment_method": {
    "type": "paypal",
    "token": "EC-7U8939823K567", //PayPal Orders V2 ID
    "payer_id": "PAYER123456789" //PayPal User Identifier
  }
}
```

> **Important:** Within this endpoint, a merchant is expected to implement [Orders API v2](https://developer.paypal.com/docs/api/orders/v2/) integration. For more information about this, see [Cart completed with an order captured](#cart-completed-with-an-order-captured).

## PayPal Orders API integration pattern

Behind the scenes, the PayPal Cart API integrates with PayPal's [Orders API v2](https://developer.paypal.com/docs/api/orders/v2/) to manage payment tokens and process transactions. Understanding this relationship helps you implement proper payment handling.

When implementing the Cart API, merchants must integrate with **<a href="https://developer.paypal.com/docs/api/orders/v2/">PayPal Orders API v2</a>** to handle payment tokens and order updates.

The following table explains when to create (`POST`) or update (`PATCH`) a cart.

| Scenario                                                     | PayPal Orders Action                    | Reason                            |
| ------------------------------------------------------------ | --------------------------------------- | --------------------------------- |
| Create a cart.                                               | `POST /v2/orders`                       | Create a new payment context.     |
| Add or remove items.                                         | `PATCH /v2/orders/{id}`                 | Update totals.                    |
| Apply or remove coupons.                                     | `PATCH /v2/orders/{id}`                 | Update totals.                    |
| Update the shipping address.                                 | `PATCH /v2/orders/{id}`                 | Update shipping and tax.          |
| Change quantities.                                           | `PATCH /v2/orders/{id}`                 | Update totals.                    |
| Create a fresh payment context when a payment token expires. | `POST /v2/orders`                       | Create a fresh payment context.   |
| Create a new cart after checkout.                            | `POST /v2/orders`                       | Prepare for a new transaction.    |
| Capture an order.                                            | `POST /v2/checkout/orders/{id}/capture` | Capture the payment for an order. |

### Examples

The following code snippets illustrate how to implement cart creation and updates.

#### Cart creation with an order

Implement cart creation by creating a PayPal order and linking it to your cart.

```javascript lines expandable theme={null}
// Merchant API implementation
async function createCart(cartData) {
  const cart = await validateAndCalculateCart(cartData);

  const paypalOrder = await paypalClient.orders.create({
    intent: "CAPTURE",
    purchase_units: [
      {
        amount: {
          currency_code: cart.totals.total.currency_code,
          value: cart.totals.total.value,
          breakdown: {
            item_total: {
              currency_code: "USD",
              value: cart.totals.subtotal.value,
            },
            shipping: {
              currency_code: "USD",
              value: cart.totals.shipping.value,
            },
            tax_total: { currency_code: "USD", value: cart.totals.tax.value },
          },
        },
      },
    ],
  });

  cart.payment_method = {
    type: "PAYPAL",
    token: paypalOrder.id, // PayPal uses order_id as token
  };

  return cart;
}
```

#### Cart update with an order update

When updating a cart, patch the corresponding PayPal order with new totals.

```javascript lines expandable theme={null}
async function updateCart(cartData) {
  const cart = await validateAndUpdateCart(cartData);
  const paypal_order_id = cart.payment_method.token;

  await paypalClient.orders.patch(paypal_order_id, [
    {
      op: "replace",
      path: "/purchase_units/@reference_id=='default'/amount",
      value: {
        currency_code: cart.totals.total.currency_code,
        value: cart.totals.total.value,
        breakdown: {
          item_total: {
            currency_code: "USD",
            value: cart.totals.subtotal.value,
          },
          shipping: { currency_code: "USD", value: cart.totals.shipping.value },
          tax_total: { currency_code: "USD", value: cart.totals.tax.value },
        },
      },
    },
  ]);

  return cart;
}
```

#### Cart completed with an order captured

Finalize the purchase by capturing the PayPal order.

```javascript lines  theme={null}
async function completeCart(cartData) {
  const paypal_order_id = cartData.payment_method.token;
  await paypalClient.orders.capture(paypal_order_id);

  return cartData;
}
```

## Merchant cart response

The following examples show some successful responses that your API can return.

### Cart response for create and update cart endpoints

Return comprehensive cart details, including status, items, totals, and payment information.

```json lines expandable theme={null}
{
  "id": "CART-123",
  "status": "CREATED",
  "validation_status": "VALID",
  "validation_issues": [],
  "items": [
    {
      "variant_id": "SHIRT-001",
      "quantity": 1,
      "name": "Blue T-Shirt",
      "unit_amount": { "currency_code": "USD", "value": "25.00" },
      "item_total": { "currency_code": "USD", "value": "25.00" }
    }
  ],
  "shipping_address": {...},
  "billing_address": {...},
  "totals": {
    "subtotal": { "currency_code": "USD", "value": "25.00" },
    "shipping": { "currency_code": "USD", "value": "5.99" },
    "tax": { "currency_code": "USD", "value": "2.70" },
    "total": { "currency_code": "USD", "value": "33.69" }
  },
  "payment_method": {
    "type": "PAYPAL",
    "token": "EC-7U8939823K567" //PayPal Order ID
  },
}
```

### Complete checkout response

After successful checkout, return the completed cart status with payment confirmation.

```json lines expandable theme={null}
{
  "id": "CART-123",
  "status": "COMPLETED",
  "validation_status": "VALID",
  "validation_issues": [],
  "payment_confirmation": {
    "merchant_order_number": "ORDER-789",
    "order_review_page": "https://yourstore.com/orders/789"
  },
  "totals": {
    "total": {
      "currency_code": "USD",
      "value": "37.19"
    }
  }
}
```

## Resources

To use our Postman resources, you can <a href="/data/postman/agent_commerce_collection.json">download our Postman collection</a>. This collection includes example requests for the Cart API endpoints, which you can use as a reference when building your API.

## Next steps

Continue by [learning more about response handling](/growth/agentic-commerce/store-sync/your-api/set-up-your-api/response-handling).


# Response handling
Source: https://docs.paypal.ai/growth/agentic-commerce/store-sync/your-api/set-up-your-api/response-handling



To handle Cart API responses effectively and provide AI agents with the context they need for intelligent decision-making, understand the status fields and error patterns throughout the cart lifecycle. This guide explains how to interpret cart status indicators, handle validation issues, and implement proper error responses that enable automatic problem resolution.

> **Note:** You can view the complete protocol reference for the [Cart API](/reference/api/rest/cart-operations/create-cart/) and the [Complete Checkout API](/reference/api/rest/checkout/complete-checkout/).

## Cart status fields

The PayPal Cart API uses 3 key status indicators that work together to communicate cart state and validation issues.

| Field               | Description                                                               |
| ------------------- | ------------------------------------------------------------------------- |
| `status`            | [Business outcome status](#business-outcome-status) (merchant-controlled) |
| `validation_status` | [Validation status](#validation-status)                                   |
| `validation_issues` | [Specific problems with type classification](#validation-issues)          |

> **Important:** Understanding these fields is crucial for proper error handling and cart lifecycle management.

### Business outcome status

The merchant-controlled `status` value indicates the current state of the cart.

| Value        | Description                                         |
| ------------ | --------------------------------------------------- |
| `CREATED`    | Cart was successfully created and is ready for use. |
| `INCOMPLETE` | Cart has issues that need resolution.               |
| `COMPLETED`  | Order is finalized, and payment was captured.       |

### Validation status

The `validation_status` value indicates whether the cart contents and data are valid for checkout. A valid transaction meets these requirements:

* All items are available with current pricing.
* Required information is complete (shipping address, customer data, and so on).
* No business rule violations exist.
* The `validation_issues` array is empty.

The following table describes the `validation-status` values.

| Value                             | Description                            |
| --------------------------------- | -------------------------------------- |
| `VALID`                           | Cart is ready for checkout.            |
| `INVALID`                         | Cart has problems that block checkout. |
| `REQUIRES_ADDITIONAL_INFORMATION` | PayPal requires more data to proceed.  |

For examples of validation status, see our [integration examples](https://docs.paypal.ai/growth/agentic-commerce/store-sync/your-api/integration-use-cases/).

### Validation issues

The `validation_issues` array communicates business logic problems that prevent cart completion but don't require HTTP error codes. These structured error objects help AI agents understand what went wrong and how to fix it, whether that's suggesting alternative products for out-of-stock items, requesting missing information, or explaining pricing changes. Use these patterns to provide clear, actionable feedback that enables automatic resolution or guides customers to make informed decisions.

When returning a `422 Unprocessable Entity`, each entry in the `details[]` array can include a `business_context` field that follows the same validation issue structure shown below.

| Field        | Description                                                                                                                |
| ------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `code`       | Issue category: `INVENTORY_ISSUE`, `PRICING_ERROR`, `SHIPPING_ERROR`, `PAYMENT_ERROR`, `DATA_ERROR`, `BUSINESS_RULE_ERROR` |
| `type`       | Cause classification: `MISSING_FIELD`, `INVALID_DATA`, `BUSINESS_RULE`                                                     |
| `message`    | Specific validation message describing the issue                                                                           |
| `variant_id` | Item identifier — include for item-specific issues so the AI agent can target the right item                               |

#### Simple validation error (minimal fields)

Here's the minimum structure for a validation issue with just the required fields:

```json theme={null}
{
  "code": "INVENTORY_ISSUE",
  "type": "BUSINESS_RULE",
  "message": "Product availability issue"
}
```

#### Complete validation error (all fields)

For rich context that supports AI agents, include detailed information and resolution options.

Each `code` can map to a series of `specific_issue` values. For more details, see the [protocol reference](/reference/api/rest/cart-operations/create-cart#response-validation-issues-items-context-one-of-0-specific-issue).

```json lines expandable theme={null}
{
  "code": "INVENTORY_ISSUE",
  "type": "BUSINESS_RULE",
  "message": "Product availability issue",
  "user_message": "The Blue T-Shirt is currently out of stock. Would you like to try a different color?",
  "variant_id": "SHIRT-BLUE-M",
  "context": {
    "specific_issue": "ITEM_OUT_OF_STOCK",
    "available_quantity": 0,
    "requested_quantity": 1,
    "suggested_alternatives": ["SHIRT-RED-M", "SHIRT-GREEN-M"]
  },
  "resolution_options": [
    {
      "action": "SUGGEST_ALTERNATIVE",
      "label": "View similar colors",
      "metadata": { "priority": "high", "auto_applicable": true }
    }
  ]
}
```

To see examples of validation status, look at our [integration example page](/growth/agentic-commerce/store-sync/your-api/integration-use-cases).

#### Business logic issues

For business scenarios that AI agents can understand and potentially resolve, use `200 OK`:

* Cart validation issues (out of stock, price changes)
* Missing required information (shipping address, checkout fields)
* Payment processing issues (declined payments, business rules)

#### Technical issues

Use proper HTTP error codes for technical problems. For the complete list of error codes, see [HTTP status codes](#http-status-codes).

## Error handling

Effective error handling is critical for maintaining a smooth shopping experience. The API provides rich error context that enables AI agents to resolve issues automatically or guide customers to resolution.

Instead of handling dozens of specific error cases, focus on these essential patterns:

* **Can you fix this automatically?** If you can fix it, fix it for them.
* **Can the customer fix this?** If you can't fix it for them, show them how to fix it.

### Error categories

The Cart API organizes validation issues into logical categories that help AI agents understand the nature of problems and apply appropriate resolution strategies.

| Category              | Description                                                |
| --------------------- | ---------------------------------------------------------- |
| `INVENTORY_ISSUE`     | Stock, availability, back-orders, discontinued items       |
| `PRICING_ERROR`       | Price changes, discounts, tax calculation, currency issues |
| `SHIPPING_ERROR`      | Address validation, delivery restrictions, shipping zones  |
| `PAYMENT_ERROR`       | Payment limits, currency support, processor issues         |
| `DATA_ERROR`          | Field validation, format issues, required fields           |
| `BUSINESS_RULE_ERROR` | Account restrictions, compliance, regional limits          |

### Error types

Each validation issue includes a type field that classifies the underlying cause.

| Type            | Description                                        |
| --------------- | -------------------------------------------------- |
| `MISSING_FIELD` | Need more info (address, checkout fields)          |
| `INVALID_DATA`  | Data validation failed                             |
| `BUSINESS_RULE` | Business logic violation, such as inventory issues |

### Common error pattern

Most validation errors follow this structure with clear user messaging and actionable options.

```json lines theme={null}
{
  "code": "INVENTORY_ISSUE",
  "user_message": "Blue T-Shirt is out of stock. Try a different color?",
  "resolution_options": [
    {
      "action": "SUGGEST_ALTERNATIVE",
      "label": "View other colors"
    },
    {
      "action": "REMOVE_ITEM",
      "label": "Remove from cart"
    }
  ]
}
```

### Error handling implementation strategy

When implementing error handling for the PayPal Cart API, use the following guidelines to determine appropriate HTTP status codes and error responses.

#### 200 OK and validation\_issues

Use `200 OK` for business logic issues that can be resolved through the `validation_issues` array. This allows AI agents to understand the problem and apply intelligent resolutions without needing to handle HTTP errors. Examples include:

* Inventory changes (out of stock, back-ordered)
* Price changes during checkout
* Payment processing issues that can be resolved
* Geographic restrictions
* Discount validation failures
* Customer account issues
* Address validation problems

#### 422 Unprocessable entity

Use this error code when any `validation_issue` prevents you from creating a cart. For example, if you do not create a cart for an `OUT_OF_STOCK` issue, you can send a `422 Unprocessable Entity` error with details about the error in the body.

#### 400 Bad request

Use this error code for malformed requests when client-side issues prevent processing. For example:

* Invalid JSON format
* Missing required fields (for example, the `items` array)
* Invalid field types or formats
* Malformed request structure
* Invalid cart ID format (for example, it doesn't match an expected pattern, such as `"CART-[A-Z0-9]+"`)

#### 404 not found

Use this error code when a well-formed request references a resource that doesn't exist. For example:

* **Cart ID doesn't exist in merchant's system** (well-formed ID, but not found)
* Invalid endpoint paths

#### Cart retrieval error handling

These examples use `GET /merchant-cart/{cartId}`.

**Example: Invalid cart ID format (400 response)**

When the cart ID doesn't match your expected format, return detailed validation information.

```json lines theme={null}
{
  "name": "INVALID_CART_ID",
  "message": "Cart ID format is invalid. Expected format: CART-[A-Z0-9]+",
  "debug_id": "ERROR-400-CART-FORMAT",
  "details": [
    {
      "field": "cartId",
      "issue": "INVALID_FORMAT",
      "description": "Cart ID format is invalid. Expected format: CART-[A-Z0-9]+. Provided: invalid-cart-id-123"
    }
  ]
}
```

**Example: Cart not found (404 response)**

When a well-formed cart ID doesn't exist in your system, provide clear guidance.

```json lines theme={null}
{
  "name": "CART_NOT_FOUND",
  "message": "Cart with ID 'CART-MISSING-123' does not exist",
  "debug_id": "ERROR-404-12345",
  "details": [
    {
      "field": "cartId",
      "issue": "NOT_FOUND",
      "description": "Cart with ID 'CART-MISSING-123' does not exist for merchant 'MERCHANT_789'. Verify cart ID or create a new cart."
    }
  ]
}
```

#### 500 internal server error

Use this error code for unexpected server-side issues that prevent processing. For example:

* System failures
* Database connectivity issues
* Payment processor unavailable
* Unexpected server errors

#### Error context best practices

When designing error responses, follow these practices to create actionable error messages that enable intelligent resolution.

* **Provide rich context**: Include all relevant information for smart resolution.
* **Customer-friendly messages**: Write user\_message for end customers.
* **Technical details**: Include technical message for developers.
* **Resolution guidance**: Always provide actionable next steps.
* **Cost impact**: Show financial implications of resolution options.
* **Time estimates**: Provide realistic timeframes for resolutions.

#### AI agent considerations for errors

Many errors are well-suited for AI agents to handle autonomously. For example:

* **Auto-applicable actions**: AI can resolve these without human intervention.
* **Priority guidance**: Immediate action is required.
* **Context-rich**: The system has enough information for intelligent decision-making.
* **Resolution metadata**: The system helps AI choose the best resolution.

#### Resolution action types

The Cart API supports various resolution actions that AI agents can use to automatically resolve validation issues. Each action type indicates whether it can be applied automatically (without customer intervention).

| Action                | Use Case               | Auto-applicable                |
| --------------------- | ---------------------- | ------------------------------ |
| `ACCEPT_NEW_PRICE`    | Price increases        | No                             |
| `ACCEPT_BACK_ORDER`   | Inventory delays       | Depends on customer preference |
| `SUGGEST_ALTERNATIVE` | Out of stock items     | Yes                            |
| `UPDATE_ADDRESS`      | Address validation     | Yes (if correction available)  |
| `REMOVE_ITEM`         | Restriction violations | Depends on item importance     |
| `SPLIT_ORDER`         | Payment limits         | Yes                            |
| `CONTACT_SUPPORT`     | Complex issues         | No                             |
| `RETRY_LATER`         | Temporary failures     | Yes                            |

## Next steps

Continue by [looking at integration examples](/growth/agentic-commerce/store-sync/your-api/integration-use-cases).


# Choose integration option
Source: https://docs.paypal.ai/growth/disputes/choose-integration-option



PayPal's dispute management provides two integration options to help you manage disputes seamlessly. Each option addresses different business needs based on dispute volume, automation requirements, and technical capabilities.

<Columns>
  <Card title="Resolution Center" href="/growth/disputes/handle-disputes/use-resolution-center">
    A web-based tool in your PayPal business account dashboard that lets you view, respond, and resolve disputes.
  </Card>

  <Card title="Disputes API" href="/growth/disputes/handle-disputes/use-disputes-api">
    A RESTful API that lets you integrate PayPal dispute management into your application or internal system.
  </Card>
</Columns>

|                       | Resolution Center                                                                                                                                                                                     | Disputes API                                                                                                                                                                   |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Who should use it** | Best for businesses handling a small volume of disputes or those who want a no-code solution without technical integration needs.                                                                     | Best for businesses handling a high volume of disputes or those who want to automate dispute handling. This works well for businesses with developers and technical expertise. |
| **How it works**      | You log into your PayPal business account, go to the Resolution Center, and manage disputes manually. You can communicate with buyers, provide supporting evidence, issue refunds, or escalate cases. | You integrate PayPal's Disputes API into your system to programmatically manage disputes.                                                                                      |
| **Key benefits**      | <ul><li>No development effort required</li><li>Easy to use with faster rollout</li><li>Intuitive dashboard</li></ul>                                                                                  | <ul><li>Enables automation at scale</li><li>Streamlines workflows for faster resolution</li><li>Seamless integration with your internal tools and systems</li></ul>            |


# Use Disputes API
Source: https://docs.paypal.ai/growth/disputes/handle-disputes/use-disputes-api



You can use the PayPal Disputes API to handle and resolve disputes programmatically throughout their lifecycle. This guide shows you how to gather dispute information, respond based on lifecycle stages, and automate dispute handling using webhooks.

## Prerequisites

Before you use the Disputes API, ensure you:

* Have a [PayPal developer account](https://www.paypal.com/signin?returnUri=https%3A%2F%2Fdeveloper.paypal.com%2Fdashboard%2F\&intent=developer\&ctxId=ul14c2e612301b4f5c99383ae8f762a937).
* Have your accounts and environment set up as described in [Set up accounts and environment](/growth/disputes/set-up).

## Understand dispute lifecycle stages

Every dispute goes through defined stages from creation to resolution. Understanding them helps you determine the required [actions and responses at each stage](#respond-to-a-dispute).

<Tabs>
  <Tab title="Inquiry stage">
    The inquiry or dispute stage begins immediately when a customer files a dispute. This is a pre-claim stage designed to reduce the occurrence of chargebacks and claims. PayPal provides a platform for both parties to communicate and resolve issues directly without its intervention. This stage only applies to cases with the item/service not received (INR) and significantly not as described (SNAD) issues.

    The inquiry stage lasts up to 20 days unless escalated to a claim. If the dispute remains unresolved, either party can escalate it to a claim within the 20-day inquiry period. If not, PayPal considers the dispute canceled and closes the case.

    If you do not want to engage with buyers directly, you can opt out of the inquiry stage. In this case, all disputes are created directly in the [claim stage](#claim-stage). To opt out of the inquiry stage, <a href="https://www.paypal-support.com/">contact PayPal</a> or your PayPal account manager.

    For this stage, the value of `dispute_life_cycle_stage` parameter in [Show dispute details](#show-dispute-details) response is `INQUIRY`.

    <Note>The inquiry stage is only applicable for internal disputes.</Note>

    PayPal is introducing an enhancement to the inquiry stage for eligible merchants. To understand this enhancement, see [Accelerated Response](/growth/disputes/handle-disputes/use-disputes-api#accelerated-response).
  </Tab>

  <Tab title="Claim stage">
    If both parties cannot resolve the issue during the dispute stage, either party can escalate the dispute to PayPal within the 20-day inquiry period. This moves the dispute to the claim stage. All external and non-merchandise disputes proceed directly to the claim stage. This includes claims for incorrect charges, duplicate payments, or unauthorized transactions due to account compromise.

    For this stage, the value of `dispute_life_cycle_stage` parameter in [Show dispute details](#show-dispute-details) response can be one of these values:

    * `CHARGEBACK`: A buyer or merchant can escalate an inquiry to a claim. This authorizes PayPal to review the case and adjudicate. During this stage, only PayPal agents can view the buyer’s notes. The buyer waits for PayPal's response before taking further action. PayPal shares dispute details with the merchant, who can accept the claim, submit evidence to challenge the claim, or offer to resolve the dispute.
      <Note>The `CHARGEBACK` stage is a PayPal dispute lifecycle stage, not a credit or debit card chargeback.</Note>

    * `PRE_ARBITRATION`: This is the first appeal stage for merchants. A merchant can appeal a chargeback if the outcome is not in the merchant's favor. If the merchant does not appeal within the appeal period, PayPal considers the case resolved.

    * `ARBITRATION`: This is the second appeal stage for merchants. If the first appeal is denied, a merchant can appeal a dispute for a second time. If the merchant does not appeal within the appeal period, PayPal returns the case to the resolved status in the `PRE_ARBITRATION` stage.
  </Tab>

  <Tab title="Dispute resolution">
    PayPal adjudicates only internal dispute cases. To resolve the claim, PayPal reviews the submitted evidence and adjudicates within 10 days in favor of either the buyer or merchant. PayPal then informs both parties about the resolution.

    Disputes can be resolved at any stage of the dispute lifecycle. After resolution, PayPal updates the `status` of the case as `RESOLVED`.

    <Note>For external cases, the card issuer adjudicates the cases in `CHARGEBACK` and `PRE_ARBITRATION` stages based on the card network's rules. However, the card network adjudicates the external cases in the `ARBITRATION` stage.</Note>
  </Tab>
</Tabs>

### Accelerated Response

Accelerated Response enhances the inquiry stage. As a merchant, you can submit supporting documentation within 10 days after the inquiry starts.

During this period, either you or the buyer can escalate the inquiry to a claim. Post escalation, you may be given additional time to submit supporting documents. The time available to submit documents depends on who escalates the case and when.

Once the required documentation is submitted, we will proceed to adjudicate the case.

| Scenario                     | Escalating party  | Message or offer sent during inquiry | Time to submit documents (post-escalation)   | Outcome if no documents submitted               |
| :--------------------------- | :---------------- | :----------------------------------- | :------------------------------------------- | :---------------------------------------------- |
| Escalated before day 8       | Buyer or Merchant | Not required                         | Remaining time within original 10-day window | Case adjudicated on available information       |
| Escalated on day 8, 9, or 10 | Buyer             | Yes                                  | 3 days                                       | Case adjudicated on available information       |
| Escalated on day 8, 9, or 10 | Buyer             | No                                   | Remaining time within original 10-day window | Case adjudicated on available information       |
| Escalated after day 10       | Buyer             | Yes                                  | 3 days                                       | Case closed buyer's favor                       |
| Escalated after day 10       | Buyer             | No                                   | No additional time                           | Case closed buyer's favor                       |
| Escalated after day 8        | Merchant          | Not required                         | 3 days                                       | Case adjudicated based on available information |

<Note> PayPal is rolling out Accelerated Response in phases. PayPal notifies eligible merchants when this enhancement becomes available on their accounts. </Note>

## Gather dispute information

You can use the Disputes API to gather information about disputes associated with your account. The following sections describe how to [list all disputes](#list-disputes) and [retrieve details of a specific dispute](#show-dispute-details).

### List disputes

Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token">valid access token</a> and make a `GET` call to the `/v1/customer/disputes` endpoint to view all the disputes associated with an account.

<Tip>You can also filter the results using query parameters. For example, use the `disputed_transaction_id` query parameter to show disputes for a specific transaction. For information on query parameters, see <a href="https://docs.paypal.ai/reference/api/rest/disputes/list-disputes">API reference</a>.</Tip>

<CodeGroup>
  ```shell lines Sample request theme={null}
  curl -v -X GET https://api-m.sandbox.paypal.com/v1/customer/disputes \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer ACCESS-TOKEN'
  ```

  ```json expandable lines Sample response theme={null}
  {
  "items": [
    {
      "dispute_id": "PP-R-ORC-10135512",
      "create_time": "2025-09-23T09:25:28.000Z",
      "update_time": "2025-09-23T09:47:03.000Z",
      "disputed_transactions": [
        {
          "buyer_transaction_id": "1XC473123G8516345",
          "seller": {
            "merchant_id": "HAAP3SNYZZ9NG"
          }
        }
      ],
      "reason": "MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED",
      "status": "RESOLVED",
      "dispute_state": "RESOLVED",
      "dispute_amount": {
        "currency_code": "USD",
        "value": "10.00"
      },
      "dispute_life_cycle_stage": "INQUIRY",
      "dispute_channel": "INTERNAL",
      "outcome": "LOST",
      "links": [
        {
          "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-R-ORC-10135512",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "dispute_id": "PP-R-AYP-10135034",
      "create_time": "2025-09-18T09:46:54.000Z",
      "update_time": "2025-09-23T09:57:13.000Z",
      "disputed_transactions": [
        {
          "buyer_transaction_id": "7XB07472F52871902",
          "seller": {
            "merchant_id": "HAAP3SNYZZ9NG"
          }
        }
      ],
      "reason": "MERCHANDISE_OR_SERVICE_NOT_RECEIVED",
      "status": "WAITING_FOR_SELLER_RESPONSE",
      "dispute_state": "REQUIRED_ACTION",
      "dispute_amount": {
        "currency_code": "USD",
        "value": "2.00"
      },
      "dispute_life_cycle_stage": "CHARGEBACK",
      "dispute_channel": "INTERNAL",
      "seller_response_due_date": "2025-10-04T06:59:59.000Z",
      "links": [
        {
          "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-R-AYP-10135034",
          "rel": "self",
          "method": "GET"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes",
      "rel": "first",
      "method": "GET"
    }
  ]
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response. The response includes the following parameter:

| Parameter                                     | Description                        | Further action                                                                                                               |
| --------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `items[].dispute_id`<br /><span>string</span> | Unique identifier for the dispute. | Use this value to [retrieve the dispute details](#show-dispute-details) and [respond to the dispute](#respond-to-a-dispute). |

<Note>For information on all response parameters, see the [API reference](/reference/api/rest/disputes/list-disputes)</Note>

### Show dispute details

Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token">valid access token</a> and make a `GET` call to the `/v1/customer/disputes/{ID}` endpoint to retrieve details of a specific dispute.

**Path parameter**: `ID` is the `dispute_id` returned in the [List disputes](#list-disputes) response.

<CodeGroup>
  ```shell lines Sample request theme={null}
  curl -v -X GET https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-R-AYP-10135034 \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer ACCESS-TOKEN'
  ```

  ```json expandable lines Sample response theme={null}
  {
  "dispute_id": "PP-R-AYP-10135034",
  "create_time": "2025-09-18T09:46:54.926Z",
  "update_time": "2025-09-18T09:49:53.336Z",
  "disputed_transactions": [
    {
      "buyer_transaction_id": "7XB07472F52871902",
      "seller_transaction_id": "8AW70038VH226914P",
      "create_time": "2025-09-18T09:42:33.000Z",
      "transaction_status": "HELD",
      "gross_amount": {
        "currency_code": "USD",
        "value": "2.00"
      },
      "buyer": {
        "name": "John Doe"
      },
      "seller": {
        "email": "sb-ekqdo43289257@business.example.com",
        "merchant_id": "HAAP3SNYZZ9NG",
        "name": "The Happy Store"
      },
      "items": [
        {
          "item_name": "Check Ngo",
          "item_description": "Check Ngo",
          "item_quantity": "1",
          "reason": "MERCHANDISE_OR_SERVICE_NOT_RECEIVED",
          "item_type": "PRODUCT"
        }
      ],
      "seller_protection_eligible": true,
      "seller_protection_type": "EXPANDED_SELLER_PROTECTION"
    }
  ],
  "reason": "MERCHANDISE_OR_SERVICE_NOT_RECEIVED",
  "status": "WAITING_FOR_SELLER_RESPONSE",
  "dispute_amount": {
    "currency_code": "USD",
    "value": "2.00"
  },
  "dispute_state": "REQUIRED_ACTION",
  "dispute_life_cycle_stage": "INQUIRY",
  "dispute_channel": "INTERNAL",
  "messages": [
    {
      "posted_by": "BUYER",
      "time_posted": "2025-09-18T09:46:54.926Z",
      "content": "Test support case"
    }
  ],
  "extensions": {
    "merchant_contacted": false,
    "buyer_contacted_time": "2025-09-18T09:46:53.836Z"
  },
  "evidences": [
    {
      "evidence_type": "CREATE",
      "notes": "Test support case",
      "source": "SUBMITTED_BY_BUYER",
      "date": "2025-09-18T09:46:54.926Z",
      "dispute_life_cycle_stage": "INQUIRY"
    },
    {
      "evidence_type": "PROOF_OF_FULFILLMENT",
      "source": "REQUESTED_FROM_SELLER",
      "date": "2025-09-18T09:49:53.336Z"
    }
  ],
  "seller_response_due_date": "2025-10-08T09:46:54.926Z",
  "offer": {
    "buyer_requested_amount": {
      "currency_code": "USD",
      "value": "2.00"
    }
  },
  "refund_details": {
    "allowed_refund_amount": {
      "currency_code": "USD",
      "value": "2.00"
    }
  },
  "allowed_response_options": {
    "accept_claim": {
      "accept_claim_types": [
        "PARTIAL_REFUND",
        "REFUND"
      ]
    },
    "make_offer": {
      "offer_types": [
        "REFUND"
      ]
    }
  },
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-R-AYP-10135034",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-R-AYP-10135034/send-message",
      "rel": "send_message",
      "method": "POST"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-R-AYP-10135034/escalate",
      "rel": "escalate",
      "method": "POST"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-R-AYP-10135034/accept-claim",
      "rel": "accept_claim",
      "method": "POST"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-R-AYP-10135034/make-offer",
      "rel": "make_offer",
      "method": "POST"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-R-AYP-10135034/provide-evidence",
      "rel": "provide_evidence",
      "method": "POST"
    }
  ]
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response. The response includes the following parameters:

| Parameter                                                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Further action                                                                                                                                                                                                                                 |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dispute_id`<br /><span>string</span>                    | Unique identifier for the dispute.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Use this value to [respond to a dispute](#respond-to-a-dispute).                                                                                                                                                                               |
| `reason`<a /><br /><span>string</span>                   | Reason for the dispute.<Note>See [Dispute reasons and evidence](/growth/disputes/reference/dispute-reasons) for more information. </Note>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Use this value to determine and [provide the required evidence](#provide-evidence).                                                                                                                                                            |
| `status`<a /><br /><span>string</span>                   | Current status of the dispute.<br /><br />**Possible values**: `OPEN`, `WAITING_FOR_SELLER_RESPONSE`, `WAITING_FOR_BUYER_RESPONSE`, `UNDER_REVIEW`, `RESOLVED`.<br /><br />PayPal may request additional evidence multiple times throughout the dispute’s lifecycle and the `WAITING_FOR_SELLER_RESPONSE` status indicates that you need to provide evidence.                                                                                                                                                                                                                                                                                                                                                                                | Use this value to determine your [response to a dispute](#respond-to-a-dispute).                                                                                                                                                               |
| `dispute_life_cycle_stage`<br /><span>string</span>      | Current stage of the dispute lifecycle. <br /><br />**Possible values**: `INQUIRY`, `CHARGEBACK`, `PRE_ARBITRATION`, `ARBITRATION`.<Note>For more information, see [Understand dispute lifecycle stages](#understand-dispute-lifecycle-stages).</Note>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Use this value to determine your [response to a dispute](#respond-to-a-dispute).                                                                                                                                                               |
| `evidences`<br /><span>array</span>                      | Array of evidence documents.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Use this array to find the evidence requested for the dispute and share it using the [Provide evidence](#provide-evidence) endpoint.                                                                                                           |
| `evidences.evidence_type`<a /><br /><span>string</span>  | Type of evidence requested by PayPal.<br /><br />**Possible values**: `PROOF_OF_FULFILLMENT`, `PROOF_OF_REFUND`, `OTHER`, and so on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Use this value to determine the evidence you need to provide.                                                                                                                                                                                  |
| `evidences.source`<a /><br /><span>string</span>         | Source of the evidence.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | If the value is `REQUESTED_FROM_SELLER`, you need to provide the evidence.                                                                                                                                                                     |
| `evidences.document.url`<br /><span>string</span>        | Downloadable URL for the evidence document. <br /><Note>Contact your PayPal account manager to add the <a href="/growth/disputes/set-up#disputes-api-2">additional scope</a> to enable document downloads.</Note>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Use this link to download the document provided as evidence.                                                                                                                                                                                   |
| `seller_response_due_date`<br /><span>string</span>      | Due date and time by which you need to respond to the dispute.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Respond within this timeline to prevent the dispute from automatically closing in the customer's favor.                                                                                                                                        |
| `allowed_response_options`<a /><br /><span>object</span> | Allowed response options for the dispute.<br /><br />**Response options**: <ul><li>`make_offer.offer_types`: Types of applicable offers.<br /><br />**Possible values**: `REFUND`, `REFUND_WITH_RETURN`, `REFUND_WITH_REPLACEMENT`, `REPLACEMENT_WITHOUT_REFUND`.</li><li>`accept_claim.accept_claim_types`: Types of applicable refunds.<br /><br />**Possible values**: `REFUND`, `REFUND_WITH_RETURN`, `PARTIAL_REFUND`, `REFUND_WITH_RETURN_SHIPMENT_LABEL`.</li><li>`acknowledge_return_item.acknowledgement_types`: Types of applicable acknowledgements for the item returned by the buyer.<br /><br />**Possible values**: `ITEM_RECEIVED`, `ITEM_NOT_RECEIVED`, `DAMAGED`, `EMPTY_PACKAGE_OR_DIFFERENT`, `MISSING_ITEMS`.</li></ul> | Use this value to respond with one of the following options:<ul><li>[Make an offer](#make-offer-to-resolve-dispute).</li><li>[Accept the claim](#accept-claim).</li><li>[Acknowledge the returned item](#acknowledge-returned-item).</li></ul> |
| `links`<br /><span>array</span>                          | Array of HATEOAS links that list the applicable actions for the dispute at its current stage.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Use these links to take further actions on the dispute.                                                                                                                                                                                        |

<Note>For information on all response parameters, see the [API reference](/reference/api/rest/disputes-actions/provide-evidence).</Note>

## Respond to a dispute

After gathering dispute information, you can determine the appropriate response action using the following key parameters from the [Show dispute details](#show-dispute-details) response:

* Use the HATEOAS `links` to understand the actions available at any stage of the dispute case lifecycle.
* Review the values of the `dispute_life_cycle_stage` and `status` parameters. Based on these values, the following table lists the possible response actions you can perform to ensure proper dispute handling:

| **Stage**                                                    | **Status**                    | **Description**                  | **Possible response actions**                                                                                                                                                                                                                                                                                                                                             |
| ------------------------------------------------------------ | ----------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `INQUIRY`                                                    | `OPEN`                        | Dispute is created.              | None                                                                                                                                                                                                                                                                                                                                                                      |
| `INQUIRY`                                                    | `WAITING_FOR_SELLER_RESPONSE` | Waiting for merchant response.   | <ul><li>[Send message to other party](#send-message-to-other-party)</li><li>[Make offer to resolve dispute](#make-offer-to-resolve-dispute)</li><li>[Accept claim](#accept-claim)</li><li>[Escalate dispute to claim](#escalate-dispute-to-claim)</li><li>[Provide evidence](#provide-evidence)</li><li>[Acknowledge returned item](#acknowledge-returned-item)</li></ul> |
| `CHARGEBACK`, `PRE_ARBITRATION`, or `ARBITRATION`            | `UNDER_REVIEW`                | PayPal is reviewing the dispute. | [Provide supporting information](https://docs.paypal.ai/growth/disputes/handle-disputes/use-disputes-api#provide-supporting-information)                                                                                                                                                                                                                                  |
| `INQUIRY`, `CHARGEBACK`, `PRE_ARBITRATION`, or `ARBITRATION` | `WAITING_FOR_BUYER_RESPONSE`  | Waiting for buyer response.      | None                                                                                                                                                                                                                                                                                                                                                                      |
| `CHARGEBACK`, `PRE_ARBITRATION`, or `ARBITRATION`            | `WAITING_FOR_SELLER_RESPONSE` | Waiting for merchant response.   | <ul><li>[Provide evidence](#provide-evidence)</li><li>[Accept claim](#accept-claim)</li><li>[Make offer to resolve dispute](#make-offer-to-resolve-dispute)</li><li>[Appeal dispute](#appeal-dispute) (available only for disputes resolved in buyer's favor)</li><li>[Acknowledge returned item](#acknowledge-returned-item)</li></ul>                                   |
| `INQUIRY`, `CHARGEBACK`, `PRE_ARBITRATION`, or `ARBITRATION` | `RESOLVED`                    | Dispute is resolved.             | None                                                                                                                                                                                                                                                                                                                                                                      |

### Send message to other party

You can send a message to the other party during the inquiry stage to share information that helps resolve the dispute.

Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token">valid access token</a> and make a `POST` call to the `/v1/customer/disputes/{ID}/send-message` endpoint with the [request parameter](/reference/api/rest/disputes-actions/send-message-about-dispute-to-other-party).

**Path parameter**: `ID` is the `dispute_id` returned in the [List disputes](#list-disputes) response.

<Tip>You can also attach documents and pictures to the message. To do this, you need to send a multipart request instead of a JSON one. For constraints and rules regarding documents, see <a href="/growth/disputes/reference/supported-file-types-sizes">Supported file types and sizes</a>.</Tip>

<CodeGroup>
  ```shell lines Sample request theme={null}
  curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-R-AYP-10135034/send-message \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer ACCESS-TOKEN' \
    -d '{
      "message": "Shipment is in progress."
    }'
  ```

  ```shell lines Sample multipart request theme={null}
  curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-R-AYP-10135034/send-message \
    -H 'Content-Type: multipart/form-data' \
    -H 'Authorization: Bearer ACCESS-TOKEN' \
    -F 'input={
      "message": "Shipment is in progress."
    };type=application/json' \
    -F 'file1=@doc.pdf;type=application/pdf'
  ```

  ```json lines Sample response theme={null}
    {
      "links": [
        {
          "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-R-AYP-10135034",
          "rel": "detail",
          "method": "GET"
        }
      ]
    }
  ```
</CodeGroup>

A successful call returns a `200 OK` response and a HATEOAS link for the dispute.

### Make offer to resolve dispute

You can make an offer to the buyer to resolve the dispute. To determine which offer types are available for a specific dispute, check the `allowed_response_options.make_offer.offer_types` parameter in the [Show dispute details](#show-dispute-details) response.

Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token">valid access token</a> and make a `POST` call to the `/v1/customer/disputes/{ID}/make-offer` endpoint with the <a href="https://docs.paypal.ai/reference/api/rest/disputes-actions/make-offer-to-resolve-dispute">request parameters</a>.

**Path parameter**: `ID` is the `dispute_id` returned in the [List disputes](#list-disputes) response.

<CodeGroup>
  ```shell lines Sample request theme={null}
  curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-R-ORC-10135512/make-offer \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer ACCESS-TOKEN' \
    -d '{
      "note": "Offer refund with replacement item.",
      "offer_amount": {
        "currency_code": "USD",
        "value": "10"
      },
      "offer_type": "REFUND_WITH_REPLACEMENT"
    }'
  ```

  ```json lines Sample response theme={null}
  {
  "links": [
      {
        "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-R-ORC-10135512",
        "rel": "detail",
        "method": "GET"
      }
    ]
  }  
  ```
</CodeGroup>

A successful call returns a `200 OK` response and a HATEOAS link for the dispute.

### Accept claim

You can accept liability for a dispute by accepting the claim. This closes the dispute in the buyer's favor, and PayPal automatically refunds the buyer. To determine which refund types are available for a specific dispute, check the `allowed_response_options.accept_claim.accept_claim_types` parameter in the [Show dispute details](#show-dispute-details) response.

Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token">valid access token</a> and make a `POST` call to the `/v1/customer/disputes/{ID}/accept-claim` endpoint with the <a href="https://docs.paypal.ai/reference/api/rest/disputes-actions/accept-claim">request parameters</a>. You can also include the accept claim reason or invoice ID if required.

**Path parameter**: `ID` is the `dispute_id` returned in the [List disputes](#list-disputes) response.

<CodeGroup>
  ```shell lines Sample request theme={null}
  curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803/accept-claim \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer ACCESS-TOKEN' \
    -d '{
      "note": "Full refund to the customer."
    }'
  ```

  ```json lines Sample response theme={null}
  {
    "links": [
      {
      "rel": "self",
      "method": "GET",
      "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803"
      }
    ]
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response and a HATEOAS link for the dispute.

### Provide evidence

You can provide evidence for a dispute to support your case. PayPal requests specific evidence based on the dispute reason. Check the following parameters in the [Show dispute details](#show-dispute-details) response to determine what evidence to provide:

* [`reason`](#reason)
* [`evidences.evidence_type`](#evidences-evidence-type)
* [`evidences.source`](#evidences-source)

Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token">valid access token</a> and make a `POST` call to the `/v1/customer/disputes/{ID}/provide-evidence` endpoint. Include the following parameters:

| Parameter name                                     | Action                                                                                                                                                                                                                                                     |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `evidences.evidence_type`<br /><span>string</span> | Set the evidence type as the value received in the [Show dispute details](#show-dispute-details) response. For example, `PROOF_OF_FULFILLMENT`.                                                                                                            |
| `evidences.documents`<br /><span>array</span>      | Provide the document details and attach the required evidence documents in the request.<Note>For constraints and rules regarding documents, see <a href="/growth/disputes/reference/supported-file-types-sizes">Supported file types and sizes</a>.</Note> |
| `evidences.notes`<br /><span>string</span>         | Provide any additional notes regarding the evidence.                                                                                                                                                                                                       |
| `evidences.evidence_info`<br /><span>object</span> | Provide details such as `refund_ids` or `tracking_info` in this object based on the `evidence_type`. For example, provide refund ID for `PROOF_OF_REFUND` and tracking information for `PROOF_OF_FULFILLMENT`.                                             |

<Note>For more information on all request parameters, see the <a href="https://docs.paypal.ai/reference/api/rest/disputes-actions/provide-evidence">API reference</a>.</Note>

**Path parameter**: `ID` is the `dispute_id` returned in the [List disputes](#list-disputes) response.

<CodeGroup>
  ```shell lines Sample request theme={null}
  curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803/provide-evidence \
    -H 'Authorization: Bearer ACCESS-TOKEN' \
    -H 'Content-Type: multipart/form-data' \
    -F 'input={
      "evidences": [
        {
          "evidence_type": "PROOF_OF_FULFILLMENT",
          "evidence_info": {
            "tracking_info": [
              {
                "carrier_name": "FEDEX",
                "tracking_number": "122533485"
              }
            ]
          },
          "notes": "Test"
        }
      ]
    };type=application/json' \
    -F 'file1=@NewDoc.pdf;type=application/pdf'
  ```

  ```json lines Sample response theme={null}
  {
    "links": [
      {
        "rel": "self",
        "method": "GET",
        "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803"
      }
    ]
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response and a HATEOAS link for the dispute.

### Escalate dispute to claim

If either party is unsatisfied with the other party's response during the inquiry stage, they can escalate the dispute to a claim. The dispute then moves to the claim stage.

Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token">valid access token</a> and make a `POST` call to the `/v1/customer/disputes/{ID}/escalate` endpoint.

**Path parameter**: `ID` is the `dispute_id` returned in the [List disputes](#list-disputes) response.

<CodeGroup>
  ```shell lines Sample request theme={null}
  curl https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-R-AYP-10135034/escalate \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer ACCESS-TOKEN' \
    -d '{
    "note": "Escalating to PayPal claim for resolution."
    }'
  ```

  ```json lines Sample response theme={null}
  {
    "links": [
      {
        "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-R-AYP-10135034",
        "rel": "detail",
        "method": "GET"
      }
    ]
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response and a HATEOAS link for the dispute.

<Note>For more information, see the <a href="https://docs.paypal.ai/reference/api/rest/disputes-actions/escalate-dispute-to-claim">API reference</a>.</Note>

### Provide supporting information

You can provide additional supporting information for a case under PayPal's review to help with the review process.

Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token">valid access token</a> and make a `POST` call to the `/v1/customer/disputes/{ID}/provide-supporting-info` endpoint with the <a href="https://docs.paypal.ai/reference/api/rest/disputes-actions/provide-evidence">request parameter</a>.

**Path parameter**: `ID` is the `dispute_id` returned in the [List disputes](#list-disputes) response.

<Tip>You can also provide documents and pictures by sending a multipart request instead of a JSON one. For constraints and rules regarding documents, see <a href="/growth/disputes/reference/supported-file-types-sizes">Supported file types and sizes</a>.</Tip>

<CodeGroup>
  ```shell lines Sample request theme={null}
  curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803/provide-supporting-info \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer ACCESS-TOKEN' \
    -d '{
      "notes": "Additional supporting information"
    }'
  ```

  ```shell lines Sample multipart request theme={null}
  curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803/provide-supporting-info \
    -H 'Authorization: Bearer ACCESS-TOKEN' \
    -H 'Content-Type: multipart/form-data'
    -F 'input={
          "notes": "Additional supporting information"
    };type=application/json' \
    -F 'file1=@NewDoc.pdf;type=application/pdf'
  ```

  ```json lines Sample response theme={null}
  {
    "links": [
      {
        "rel": "self",
        "method": "GET",
        "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803"
      }
    ]
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response and a HATEOAS link for the dispute.

### Appeal dispute

You can appeal a dispute that was resolved in the buyer's favor. To determine if a dispute is eligible for appeal, check whether the HATEOAS link for appeal is present in the [Show dispute details](#show-dispute-details) response.

Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token">valid access token</a> and make a `POST` call to the `/v1/customer/disputes/{ID}/appeal` endpoint. Include the following parameters:

| Parameter name                                     | Action                                                                                                                                                                                                                                                     |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `evidences.evidence_type`<br /><span>string</span> | Set the evidence type based on the evidence you are providing for your appeal. For example, `PROOF_OF_FULFILLMENT`.                                                                                                                                        |
| `evidences.documents`<br /><span>array</span>      | Provide the document details and attach the required evidence documents in the request.<Note>For constraints and rules regarding documents, see <a href="/growth/disputes/reference/supported-file-types-sizes">Supported file types and sizes</a>.</Note> |
| `evidences.notes`<br /><span>string</span>         | Provide any additional notes regarding the evidence.                                                                                                                                                                                                       |
| `evidences.evidence_info`<br /><span>object</span> | Provide details such as `refund_ids` or `tracking_info` in this object based on the `evidence_type`. For example, provide refund ID for `PROOF_OF_REFUND` and tracking information for `PROOF_OF_FULFILLMENT`.                                             |

<Note>For information on all request parameters, see the <a href="https://docs.paypal.ai/reference/api/rest/disputes-actions/appeal-dispute">API reference</a>.</Note>

**Path parameter**: `ID` is the `dispute_id` returned in the [List disputes](#list-disputes) response.

<CodeGroup>
  ```shell lines Sample request theme={null}
  curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803/appeal \
    -H 'Content-Type: multipart/form-data' \
    -H 'Authorization: Bearer ACCESS-TOKEN' \
    -F 'input={
      "evidences": [
        {
          "evidence_type": "PROOF_OF_FULFILLMENT",
          "evidence_info": {
            "tracking_info": [
              {
                "carrier_name": "FEDEX",
                "tracking_number": "122533485"
              }
            ]
          },
          "notes": "Test"
        }
      ]
    };type=application/json' \
    -F 'file1=@NewDoc.pdf;type=application/pdf'
  ```

  ```json lines Sample response theme={null}
  {
    "links": [
      {
        "rel": "self",
        "method": "GET",
        "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803"
      }
    ]
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response and a HATEOAS link for the dispute.

### Acknowledge returned item

For SNAD disputes with the `MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED` reason, you can [make an offer to resolve the dispute](#make-offer-to-resolve-dispute) by offering a full refund in exchange for returning the item. After the buyer ships the returned item and reports it to PayPal, the acknowledge return item action becomes available. Use this endpoint to acknowledge receipt of the item.

To determine which acknowledgements are available for a specific dispute, check the `allowed_response_options.acknowledge_return_item.acknowledgement_types` parameter in the [Show dispute details](#show-dispute-details) response.

Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token">valid access token</a> and make a `POST` call to the `/v1/customer/disputes/{ID}/acknowledge-return-item` endpoint. You can also include the note or acknowledgement type.

**Path parameter**: `ID` is the `dispute_id` for which you are acknowledging receipt of the returned item.

<CodeGroup>
  ```shell lines Sample request theme={null}
  curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-000-000-651-454/acknowledge-return-item \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer ACCESS-TOKEN' \
    -d '{
      "note": "I have received the item back.",
      "acknowledgement_type": "ITEM_RECEIVED"
    }'
  ```

  ```json lines Sample response theme={null}
  {
    "links": [
      {
        "rel": "self",
        "method": "GET",
        "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-000-000-651-454"
      }
    ]
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response and a HATEOAS link for the dispute.

<Note>For more information, see <a href="https://docs.paypal.ai/reference/api/rest/disputes-actions/acknowledge-returned-item">API reference</a>.</Note>

## Common issues

When calling the Disputes API, you may see these common errors:

* 400 Bad Request when required fields or formats are invalid. Fix: Validate request body and parameters against the Disputes API reference.
* 401 Unauthorized when the access token is missing, expired, or invalid. Fix: Regenerate the access token and retry the call with the updated token.
* 403 Forbidden when the app or account is not permitted to perform the requested action. Fix: Confirm Disputes API access, scopes, and account permissions.

For more details, see the [HTTP status codes and error messages](/developer/how-to/api/troubleshooting/common-errors/overview#http-status-codes-and-error-messages).

## Use webhooks to monitor dispute events

Webhook events are external events that your app does not know about unless it receives event notifications. For example, a new dispute raised or resolved is a webhook event. You can subscribe to such events and register a callback (listener) URL. When the event occurs, PayPal sends a notification to the registered callback URL. You can code your app to perform relevant actions based on the event notification it receives.

To handle webhook events:

1. Review the <a href="/reference/webhook-events/disputes-v1">list of webhook events for disputes</a> and select the events for your app to subscribe.
2. Subscribe to the selected webhook events through one of the following means:
   * **PayPal developer account**: Log in to your account, go to <strong>App details</strong> page > <strong>Features</strong> > <strong>Webhooks</strong>, and subscribe to webhook events.
   * <a href="https://docs.paypal.ai/reference/api/rest/webhooks/list-webhooks">Webhooks management API</a>.
3. In your server-side app code, define a webhook handler that:
   * <a href="https://docs.paypal.ai/reference/api/rest/webhooks/create-webhook#body-url">Listens to the webhook event</a>.
   * <a href="https://docs.paypal.ai/reference/webhook-events/webhook-format">Processes the webhook event message sent to your listener URL</a>.
   * <a href="https://docs.paypal.ai/reference/api/rest/verify-webhook-signature/verify-webhook-signature#body-webhook-event">Verifies the source of the event notification</a>.
   * Performs further actions based on event data.

See [Webhook management](https://docs.paypal.ai/reference/api/rest/webhooks/list-webhooks) for more information.


# Use Resolution Center
Source: https://docs.paypal.ai/growth/disputes/handle-disputes/use-resolution-center



You can use the PayPal Resolution Center to manually view, respond, and resolve disputes for your PayPal business account.

## Prerequisites

* Have a [PayPal business account](https://www.paypal.com/signin?returnUri=https%3A%2F%2Fwww.paypal.com%2Fdisputes%2Fdashboard%2F).
* Have your accounts and environment set up as described in [Set up accounts and environment](https://docs.paypal.ai/growth/disputes/set-up).

## Handle disputes in Resolution Center

| Action                             | Description                                                                                                                                                                                                                                                                                          | Procedure                                                                                                                                                                                                                                                                                                                                                                                                             |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| View open disputes                 | See a list of all current disputes for your business account.                                                                                                                                                                                                                                        | <ol><li>Log in to your PayPal business account and go to the <a href="https://www.paypal.com/disputes/">Resolution Center</a>.</li><li>Select **All open cases** tab.</li></ol>                                                                                                                                                                                                                                       |
| View dispute details               | Review specific information about a dispute, including case status, transaction details, and communication history.                                                                                                                                                                                  | <ol><li>Under **All open cases** tab, select the required **Case ID**.</li><li>Select **Case details** to view the transaction ID, date reported, and other details.</li></ol>                                                                                                                                                                                                                                        |
| Message buyer                      | Communicate directly with the buyer to discuss and resolve the dispute.                                                                                                                                                                                                                              | <ol><li>Select a **Case ID** and go to **Your conversation with customer**.</li><li>Enter the message details in **Send a message to Customer** and select the send button.</li></ol>                                                                                                                                                                                                                                 |
| Make an offer to resolve a dispute | Propose a solution, such as a refund or replacement, to settle the dispute.                                                                                                                                                                                                                          | <ol><li>Select a **Case ID** and go to **Other actions**. </li><li>Select one of these actions: <ul><li>**Send a refund**: This refunds the requested amount to the buyer, who retains the product.</li><li>**Send an Offer**: Select one of these offers and follow the system instructions: <ul><li>Partial refund</li><li>Send a replacement</li><li>Full refund with return of item</li></ul></li></ul></li></ol> |
| Escalate dispute to claim          | Request PayPal to review and resolve the dispute if you and the buyer cannot agree. After escalation: <ul><li>You cannot message the buyer.</li><li>PayPal places any previous offers or refunds shared with the buyer on hold.</li><li>PayPal reviews the case and provides a resolution.</li></ul> | <ol><li>Select a **Case ID** and select **Escalate issue to PayPal**. </li><li>Enter a detailed description and select **Escalate Issue**.</li></ol>                                                                                                                                                                                                                                                                  |
| Accept claim                       | Accept liability for a dispute by closing the case in the buyer’s favor and issuing a refund.                                                                                                                                                                                                        | Select a **Case ID** and select **I'll issue a refund to my customer and close this case**.                                                                                                                                                                                                                                                                                                                           |
| Provide evidence                   | Submit documents or information to support your case and contest the dispute.                                                                                                                                                                                                                        | <ol><li>Select **Needs your attention** tab and select the required **Case ID**.</li><li>In case status, select **Respond**. Under **Submit an evidence**, select the desired option and upload the evidence.<br />**For example**: Select **Provide fulfillment info** to update fulfillment details like **Tracking Number** and **Carrier name**.</li></ol>                                                        |
| Provide supporting information     | Add additional details or documents to support your case.                                                                                                                                                                                                                                            | <ol><li>Select **All open cases** tab and select the required **Case ID**.</li><li>In case status, if you have the option **Provide Additional Info** or **Have Something to Share?**, select the option and upload the supporting information.</li></ol>                                                                                                                                                             |
| Appeal dispute                     | Ask PayPal to reconsider the case if you disagree with the outcome.                                                                                                                                                                                                                                  | Select a **Case ID** and select **I disagree with the claim. I'd like to submit additional info**.                                                                                                                                                                                                                                                                                                                    |

<Note>Partners using connected integrations will not have access to the Resolution Center as merchants handle disputes directly. </Note>

### Common issues

* If an expected action (for example, **Escalate issue to PayPal** or **Provide Additional Info**) is missing for a case, check the case status and lifecycle stage. Some actions are only available while the dispute is open or under PayPal review.
* If you cannot see any open disputes, confirm you are signed in to the correct PayPal business account and that you are viewing the **All open cases** tab.


# Overview
Source: https://docs.paypal.ai/growth/disputes/overview



A dispute or chargeback occurs when a buyer reports an issue with their transaction, such as non-receipt of an item, receiving an item significantly different from its description, discovering an unauthorized transaction, or identifying a billing error.

PayPal's dispute management provides a clear, structured process to help you resolve these issues fairly and efficiently. It enables you to communicate with buyers, provide supporting evidence, and work toward a fair resolution. This protects your business and maintains buyer trust by giving transparent outcomes.

You can manage disputes using one of these integration options:

* **Resolution Center**: A web-based dashboard where you can view, monitor, and manually respond to disputes.
* **Disputes API**: A programmatic interface that enables you to automate dispute management actions directly from your systems.

<Note>This guide applies to direct merchants and connected integrations where merchants handle disputes and chargebacks and assume financial liability.</Note>

## Key features

* **Structured dispute lifecycle**: Handle disputes efficiently through defined stages from submission to resolution with a clearly defined workflow that minimizes ambiguity and supports efficient, timely resolution.
* **No-code solution**: Simplify dispute handling with Resolution Center, a ready-to-use web interface that requires no technical integration.
* **Automated operations**: Scale dispute management, reduce manual effort, and save time with Disputes API that works seamlessly with your existing systems.
* **Amicable resolution option**: Engage directly with buyers through messaging on our platform to resolve disputes, avoiding escalation and associated fees.

## Understand disputes

You can use the information in this section to get familiar with PayPal's dispute management process. This helps you understand and manage disputes effectively.

### Parties involved in dispute management

The following table outlines the key parties involved and their roles in the dispute management process:

| **Party**           | **Role**                                                                                                                                                                                                            |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Buyer               | Customer who makes a transaction for a product or service and initiates the dispute for that transaction.                                                                                                           |
| Merchant            | Seller who provides the product or service for the transaction. They monitor and respond to disputes.                                                                                                               |
| PayPal              | Payment processor that facilitates the transaction and helps you manage the dispute resolution process.                                                                                                             |
| Bank or card issuer | Bank or financial institution that issued the buyer's payment instrument (for example, debit or credit card). They manage chargebacks and ACH returns.                                                              |
| Card network        | Payment network that facilitates transactions and chargebacks between issuing and acquiring banks. It sets dispute resolution rules and timelines.<br />For example: Visa, Mastercard, American Express, and so on. |
| Partner             | Platform that uses connected integration and onboards merchants through PayPal. In connected integration, merchants assume financial liability and handle disputes and chargebacks.                                 |

### Types of disputes

PayPal classifies disputes into [internal](#internal-disputes) and [external](#external-disputes) disputes based on where they originate and who manages adjudication.

#### Internal disputes

When a buyer files a dispute using the PayPal Resolution Center, it becomes an internal dispute (or internal case). The buyer and merchant can communicate directly through PayPal's platform to resolve the dispute amicably without PayPal's intervention. If they cannot reach an agreement, either party may escalate the dispute to a claim, where PayPal reviews and adjudicates the case based on submitted evidence.

* The buyer has 180 days from the payment date to dispute a transaction.
* PayPal holds the disputed payment until resolution.
* The buyer and merchant have up to 20 days to resolve the disputes amicably. If either party escalates the dispute to PayPal, it will review the case and adjudicate within 10 days based on the evidence from both parties. Both merchants and buyers can appeal unfavorable decisions.

<Note>The buyer can also file a dispute using the PayPal chatbot, IVR, or by calling customer support.</Note>

#### External disputes

When a buyer files a dispute with their bank or card issuer, it becomes an external dispute (or external case). The bank or card issuer manages and adjudicates the outcome. PayPal acts solely as an intermediary to transmit information and evidence between the merchant and the bank or card issuer.

##### Types of external disputes

* **Chargeback**: A chargeback occurs when the buyer disputes a charge with their debit or credit card issuer, who reverses the payment and refunds the buyer.
  <Note>The merchant can also receive a pre-chargeback alert, which is a notification about a potential chargeback. Merchants can issue a refund within 20 hours without fulfilling the order to avoid the chargeback and associated fees.</Note>
* **ACH return**: A bank reversal (or ACH return) occurs when the bank requests PayPal to reverse a payment.

### Dispute lifecycle and stages

Understanding the dispute lifecycle helps you manage disputes more efficiently. Disputes typically progress through these stages:

1. **Inquiry stage**: The buyer files a dispute. PayPal provides a platform for merchants and buyers to resolve disputes directly without its intervention. If the dispute remains unresolved, either party may escalate it to a claim. Item/service not received (INR) or significantly not as described (SNAD) issues begin in the inquiry stage, and if unresolved, may escalate to the claim stage.
2. **Claim stage**: Once the dispute is escalated to a claim, PayPal requests the evidence from both parties, and reviews the submitted evidence. Issues such as billing errors, duplicate charges, or unauthorized transactions are handled directly as claims.
3. **Dispute resolution stage**: For internal disputes, PayPal adjudicates and communicates the resolution to both parties. For external disputes, the bank or card issuer adjudicates the case and communicates the resolution to PayPal.

You can track disputes through these stages, gather relevant information, and respond appropriately to resolve them.

<Note>For detailed information, see <a href="/growth/disputes/handle-disputes/use-disputes-api#understand-dispute-lifecycle-stages">Understand dispute lifecycle stages</a>.</Note>

### Common buyer issues

The following table summarizes the common buyer issues that lead to disputes:

| **Issue**                             | **Description**                                                                                                                                                                                     |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Item not received (INR)               | Buyer claims they ordered and paid for an item or service, but did not receive it.                                                                                                                  |
| Significantly not as described (SNAD) | Buyer received the item, but it does not match the merchant's description. It looks significantly different or has sustained damage during shipping.                                                |
| Billing or subscription errors        | Buyer claims billing or subscription errors, such as duplicate charges, multiple transactions, or incorrect amounts.                                                                                |
| Unauthorized transactions             | Buyer claims: <ul><li>They did not authorize the purchase, and the transaction occurred without their consent.</li><li>They were victims of debit or credit card fraud or identity theft.</li></ul> |
| Request for additional details        | Buyer may require additional transaction details, such as a copy of the transaction or a receipt, to resolve uncertainties or discrepancies.                                                        |
| Misdirected transactions              | Buyer claims the payment went to an incorrect recipient or account.                                                                                                                                 |

## How disputes work

This section provides an overview of the internal and external dispute workflows.

### Internal disputes

![Internal disputes workflow depicting the dispute resolution process at a high level between the buyer, merchant, and PayPal.](https://www.paypalobjects.com/ppdevdocs/flowdg-internaldispustesescalates1.png)

1. **Buyer**: Files a dispute for a transaction with PayPal.
2. **PayPal**:
   1. Creates a case for the dispute and holds the disputed payment.
   2. Notifies the merchant.
3. **Merchant**:
   1. Reviews the dispute details and gathers necessary information and evidence.
   2. Responds to the dispute. This may include full or partial refunds, offers, supporting information, or escalation of the dispute to a claim.
4. **Buyer**:
   1. Reviews the response.
   2. Accepts the offer or reviews the supporting information and closes the dispute, or rejects it and escalates the dispute to a claim.
5. **PayPal** (if escalated to claim):
   1. Requests evidence from the merchant and buyer.
   2. Adjudicates based on the evidence from both parties.
      * If resolved in the buyer's favor, PayPal refunds the transaction amount.
      * If resolved in the merchant's favor, PayPal releases the hold on the transaction amount.
   3. Updates dispute status and communicates the resolution to the merchant.
6. **Merchant | Buyer**: \[Optional] Appeals the resolution and provides additional evidence for further review.

### External disputes

![External disputes workflow depicting the dispute resolution process at a high level between the buyer, bank or card issuer, merchant, and PayPal.](https://www.paypalobjects.com/ppdevdocs/flowdg-externaldispustes2.png)

1. **Buyer**: Files a dispute for a transaction with the bank or card issuer.
2. **Bank | Card issuer**: Reviews the buyer's claim. If valid, sends a chargeback through the card network to PayPal.
3. **PayPal**:
   1. Creates the dispute case.
   2. Notifies the merchant.
4. **Merchant**:
   1. Reviews the dispute details.
   2. Responds to the dispute by issuing a refund or submitting evidence to PayPal.
5. **PayPal**: Forwards the merchant's response through the card network to the bank or card issuer.
6. **Bank | Card issuer**:
   1. Reviews and adjudicates based on the evidence from both parties.
      * If resolved in the buyer's favor, the bank or card issuer refunds the transaction amount.
      * If resolved in the merchant's favor, the bank or card issuer reverses the transaction amount.
   2. Communicates the resolution through the card network to PayPal.
7. **PayPal**: Updates dispute status and notifies the merchant.

## Additional information

[Article on disputes, claims, chargebacks, and bank reversals](https://www.paypal.com/brc/article/customer-disputes-claims-chargebacks-bank-reversals)


# Dispute reasons and evidence
Source: https://docs.paypal.ai/growth/disputes/reference/dispute-reasons



You can determine what evidence to provide for a dispute or chargeback based on its reason.

To defend a dispute or chargeback effectively:

1. Use the <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">Show dispute details</a> response to determine the required evidence. The `reason` and `evidences.evidence_type` parameters denote the dispute reason and the evidence type respectively.
2. Use the <a href="/growth/disputes/handle-disputes/use-disputes-api#provide-evidence">Provide evidence</a> endpoint to submit the evidence to PayPal.

Each dispute reason requires specific evidence that helps PayPal review and resolve the case. The following sections list the dispute reasons and the required evidence for each reason.

### MERCHANDISE\_OR\_SERVICE\_NOT\_RECEIVED

The buyer did not receive the merchandise or service.

| Evidence type          | Required evidence                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `PROOF_OF_FULFILLMENT` | Provide one of the following to PayPal:<ul><li>Carrier name and tracking number through `evidences.evidence_info.tracking_info.carrier_name` and `evidences.evidence_info.tracking_info.tracking_number` parameters respectively.</li>Or<li>Notes or documents in the `evidences.notes` or `evidences.documents` parameters respectively. For example, a document can be a proof of delivery signature or a proof of receipt copy. For more information about supported files, see <a href="/growth/disputes/reference/supported-file-types-sizes">Supported file types and sizes</a>.</li></ul> |
| `PROOF_OF_REFUND`      | Pass the refund ID in the `evidences.evidence_info.refund_ids` parameter.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

### MERCHANDISE\_OR\_SERVICE\_NOT\_AS\_DESCRIBED

The buyer reports that the merchandise or service was not as described.

| Evidence type     | Required evidence                                                                                                                                                                                                            |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OTHER`           | Pass the notes or documents in the `evidences.notes` or `evidences.documents` parameters respectively. For example, you can include a product description, item URL, return policy, or a copy of a contract or an affidavit. |
| `PROOF_OF_REFUND` | Pass the refund ID in the `evidences.evidence_info.refund_ids` parameter.                                                                                                                                                    |

### UNAUTHORISED

The buyer did not authorize purchase of the merchandise or service.

| Evidence type          | Required evidence                                                                                                                                                                               |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PROOF_OF_FULFILLMENT` | Provide the carrier name and tracking number through `evidences.evidence_info.tracking_info.carrier_name` and `evidences.evidence_info.tracking_info.tracking_number` parameters respectively.  |
| `PROOF_OF_REFUND`      | Pass the refund ID in the `evidences.evidence_info.refund_ids` parameter.                                                                                                                       |
| `OTHER`                | Pass the notes or documents in the `evidences.notes` or `evidences.documents` parameters respectively. For example, a document can be a proof of delivery signature or a proof of receipt copy. |

### CREDIT\_NOT\_PROCESSED

The refund or credit transaction was not processed for the buyer.

| Evidence type     | Required evidence                                                                                                                                          |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PROOF_OF_REFUND` | Pass the refund ID in the `evidences.evidence_info.refund_ids` parameter.                                                                                  |
| `OTHER`           | Pass the notes or documents in the `evidences.notes` or `evidences.documents` parameters respectively. For example, a document can be a credit due reason. |

### DUPLICATE\_TRANSACTION

The transaction was a duplicate.

| Evidence type     | Required evidence                                                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| `PROOF_OF_REFUND` | Pass the refund ID in the `evidences.evidence_info.refund_ids` parameter.                              |
| `OTHER`           | Pass the notes or documents in the `evidences.notes` or `evidences.documents` parameters respectively. |

### INCORRECT\_AMOUNT

The buyer was charged an incorrect amount.

| Evidence type     | Required evidence                                                                                                                                                |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PROOF_OF_REFUND` | Pass the refund ID in the `evidences.evidence_info.refund_ids` parameter for the difference in amount.                                                           |
| `OTHER`           | Pass the notes or documents in the `evidences.notes` or `evidences.documents` parameters respectively. For example, a document can be a price difference reason. |

### PAYMENT\_BY\_OTHER\_MEANS

The buyer paid for the transaction through other means.

| Evidence type     | Required evidence                                                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| `PROOF_OF_REFUND` | Pass the refund ID in the `evidences.evidence_info.refund_ids` parameter for the difference in amount. |
| `OTHER`           | Pass the notes or documents in the `evidences.notes` or `evidences.documents` parameters respectively. |

### CANCELED\_RECURRING\_BILLING

The buyer was incorrectly charged after canceling the subscription or recurring billing.

| Evidence type     | Required evidence                                                                                                                                               |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PROOF_OF_REFUND` | Pass the refund ID in the `evidences.evidence_info.refund_ids` parameter for the difference in amount.                                                          |
| `OTHER`           | Pass the notes or documents in the `evidences.notes` or `evidences.documents` parameters respectively. For example, a document can be a subscription agreement. |

### OTHER

| Evidence type     | Required evidence                                                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| `PROOF_OF_REFUND` | Pass the refund ID in the `evidences.evidence_info.refund_ids` parameter.                              |
| `OTHER`           | Pass the notes or documents in the `evidences.notes` or `evidences.documents` parameters respectively. |


# Disputes API - test values for simulations
Source: https://docs.paypal.ai/growth/disputes/reference/disputes-api-test-values



Developers and QA engineers can use these predefined test values to simulate negative Disputes API responses in a sandbox while they develop and test their integration.

<Note>Test values are case-sensitive.</Note>

## Prerequisites

* Access to the Disputes API sandbox.
* Valid API credentials and authentication set up.
* An HTTP client (for example, cURL, Postman, or your application).

For more information, see [Set up accounts and environment](/business/payments/disputes/set-up).

## Simulate negative responses

1. Pick the Disputes API operation and the error you want to test.
2. Find the matching test value in the tables below and send a request that uses it in the path or query parameter.
3. Confirm that the response and your integration’s behavior match the simulated error described in the table.

## List disputes

Use the query parameter in the request URL to simulate the negative responses.

**Endpoint**: `GET /v1/customer/disputes?disputed_transaction_id={TRANSACTION-ID}`

| Query parameter                                           | Simulated error response                                        |
| --------------------------------------------------------- | --------------------------------------------------------------- |
| `/v1/customer/disputes?disputed_transaction_id=ERRDIS023` | `FORBIDDEN`                                                     |
| `/v1/customer/disputes?disputed_transaction_id=ERRDIS024` | `INVALID_RESOURCE_ID`                                           |
| `/v1/customer/disputes?disputed_transaction_id=ERRDIS025` | `NOT_ACCEPTABLE`                                                |
| `/v1/customer/disputes?disputed_transaction_id=ERRDIS026` | `UNSUPPORTED_MEDIA_TYPE`                                        |
| `/v1/customer/disputes?disputed_transaction_id=ERRDIS027` | `RATE_LIMIT_REACHED`                                            |
| `/v1/customer/disputes?disputed_transaction_id=ERRDIS028` | `SERVICE_UNAVAILABLE`                                           |
| `/v1/customer/disputes?disputed_transaction_id=ERRDIS029` | `INTERNAL_SERVICE_ERROR`                                        |
| `/v1/customer/disputes?disputed_transaction_id=ERRDIS030` | `AUTHORIZATION_ERROR`                                           |
| `/v1/customer/disputes?disputed_transaction_id=ERRDIS031` | `VALIDATION_ERROR`<br />(issue: DATE\_CAN\_NOT\_BE\_IN\_FUTURE) |
| `/v1/customer/disputes?disputed_transaction_id=ERRDIS032` | `VALIDATION_ERROR`<br />(issue: INVALID\_PAGE\_SIZE)            |
| `/v1/customer/disputes?disputed_transaction_id=ERRDIS033` | `VALIDATION_ERROR`<br />(issue: INVALID\_START\_TIME\_FORMAT)   |
| `/v1/customer/disputes?disputed_transaction_id=ERRDIS034` | `VALIDATION_ERROR`<br />(issue: INVALID\_START\_TIME\_RANGE)    |

## Show dispute details

Use the test values as path parameters to simulate the negative responses.

**Endpoint**: `GET /v1/customer/disputes/{ID}`

| Path parameter                    | Simulated error response |
| --------------------------------- | ------------------------ |
| `/v1/customer/disputes/ERRDIS015` | `FORBIDDEN`              |
| `/v1/customer/disputes/ERRDIS016` | `INVALID_RESOURCE_ID`    |
| `/v1/customer/disputes/ERRDIS017` | `NOT_ACCEPTABLE`         |
| `/v1/customer/disputes/ERRDIS018` | `UNSUPPORTED_MEDIA_TYPE` |
| `/v1/customer/disputes/ERRDIS019` | `RATE_LIMIT_REACHED`     |
| `/v1/customer/disputes/ERRDIS020` | `SERVICE_UNAVAILABLE`    |
| `/v1/customer/disputes/ERRDIS021` | `INTERNAL_SERVICE_ERROR` |
| `/v1/customer/disputes/ERRDIS022` | `AUTHORIZATION_ERROR`    |

## Send message to other party

Use the test values as path parameters to simulate the negative responses.

**Endpoint**: `POST /v1/customer/disputes/{ID}/send-message`

| Path parameter                                 | Simulated error response |
| ---------------------------------------------- | ------------------------ |
| `/v1/customer/disputes/ERRDIS091/send-message` | `FORBIDDEN`              |
| `/v1/customer/disputes/ERRDIS092/send-message` | `INVALID_RESOURCE_ID`    |
| `/v1/customer/disputes/ERRDIS093/send-message` | `NOT_ACCEPTABLE`         |
| `/v1/customer/disputes/ERRDIS094/send-message` | `UNSUPPORTED_MEDIA_TYPE` |
| `/v1/customer/disputes/ERRDIS095/send-message` | `RATE_LIMIT_REACHED`     |
| `/v1/customer/disputes/ERRDIS096/send-message` | `SERVICE_UNAVAILABLE`    |
| `/v1/customer/disputes/ERRDIS097/send-message` | `INTERNAL_SERVICE_ERROR` |
| `/v1/customer/disputes/ERRDIS098/send-message` | `AUTHORIZATION_ERROR`    |
| `/v1/customer/disputes/ERRDIS099/send-message` | `UNPROCESSABLE_ENTITY`   |

## Make offer to resolve dispute

Use the test values as path parameters to simulate the negative responses.

**Endpoint**: `POST /v1/customer/disputes/{ID}/make-offer`

| Path parameter                               | Simulated error response |
| -------------------------------------------- | ------------------------ |
| `/v1/customer/disputes/ERRDIS100/make-offer` | `FORBIDDEN`              |
| `/v1/customer/disputes/ERRDIS101/make-offer` | `INVALID_RESOURCE_ID`    |
| `/v1/customer/disputes/ERRDIS102/make-offer` | `NOT_ACCEPTABLE`         |
| `/v1/customer/disputes/ERRDIS103/make-offer` | `UNSUPPORTED_MEDIA_TYPE` |
| `/v1/customer/disputes/ERRDIS104/make-offer` | `RATE_LIMIT_REACHED`     |
| `/v1/customer/disputes/ERRDIS105/make-offer` | `SERVICE_UNAVAILABLE`    |
| `/v1/customer/disputes/ERRDIS106/make-offer` | `INTERNAL_SERVICE_ERROR` |
| `/v1/customer/disputes/ERRDIS107/make-offer` | `AUTHORIZATION_ERROR`    |
| `/v1/customer/disputes/ERRDIS108/make-offer` | `UNPROCESSABLE_ENTITY`   |

## Accept claim

Use the test values as path parameters to simulate the negative responses.

**Endpoint**: `POST /v1/customer/disputes/{ID}/accept-claim`

| Path parameter                                 | Simulated error response                                                    |
| ---------------------------------------------- | --------------------------------------------------------------------------- |
| `/v1/customer/disputes/ERRDIS051/accept-claim` | `FORBIDDEN`                                                                 |
| `/v1/customer/disputes/ERRDIS052/accept-claim` | `INVALID_RESOURCE_ID`                                                       |
| `/v1/customer/disputes/ERRDIS053/accept-claim` | `NOT_ACCEPTABLE`                                                            |
| `/v1/customer/disputes/ERRDIS054/accept-claim` | `UNSUPPORTED_MEDIA_TYPE`                                                    |
| `/v1/customer/disputes/ERRDIS055/accept-claim` | `RATE_LIMIT_REACHED`                                                        |
| `/v1/customer/disputes/ERRDIS056/accept-claim` | `SERVICE_UNAVAILABLE`                                                       |
| `/v1/customer/disputes/ERRDIS057/accept-claim` | `INTERNAL_SERVICE_ERROR`                                                    |
| `/v1/customer/disputes/ERRDIS058/accept-claim` | `AUTHORIZATION_ERROR`                                                       |
| `/v1/customer/disputes/ERRDIS059/accept-claim` | `UNPROCESSABLE_ENTITY`                                                      |
| `/v1/customer/disputes/ERRDIS060/accept-claim` | `VALIDATION_ERROR`<br />(issue: AMOUNT\_SHOULD\_NOT\_BE\_PASSED)            |
| `/v1/customer/disputes/ERRDIS061/accept-claim` | `VALIDATION_ERROR`<br />(issue: INSUFFICIENT\_FUNDS)                        |
| `/v1/customer/disputes/ERRDIS062/accept-claim` | `VALIDATION_ERROR`<br />(issue: INTANGIBLE\_ITEM\_CANNOT\_BE\_RETURNED)     |
| `/v1/customer/disputes/ERRDIS063/accept-claim` | `VALIDATION_ERROR`<br />(issue: INVALID\_RETURN\_SHIPPING\_ADDRESS\_FORMAT) |
| `/v1/customer/disputes/ERRDIS064/accept-claim` | `VALIDATION_ERROR`<br />(issue: MISSING\_RETURN\_SHIPPING\_ADDRESS)         |
| `/v1/customer/disputes/ERRDIS065/accept-claim` | `UNPROCESSABLE_ENTITY`                                                      |

## Provide evidence

Use the test values as path parameters to simulate the negative responses.

**Endpoint**: `POST /v1/customer/disputes/{ID}/provide-evidence`

| Path parameter                                     | Simulated error response                                                           |
| -------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `/v1/customer/disputes/ERRDIS035/provide-evidence` | `FORBIDDEN`                                                                        |
| `/v1/customer/disputes/ERRDIS036/provide-evidence` | `INVALID_RESOURCE_ID`                                                              |
| `/v1/customer/disputes/ERRDIS037/provide-evidence` | `NOT_ACCEPTABLE`                                                                   |
| `/v1/customer/disputes/ERRDIS038/provide-evidence` | `UNSUPPORTED_MEDIA_TYPE`                                                           |
| `/v1/customer/disputes/ERRDIS039/provide-evidence` | `RATE_LIMIT_REACHED`                                                               |
| `/v1/customer/disputes/ERRDIS040/provide-evidence` | `SERVICE_UNAVAILABLE`                                                              |
| `/v1/customer/disputes/ERRDIS041/provide-evidence` | `INTERNAL_SERVICE_ERROR`                                                           |
| `/v1/customer/disputes/ERRDIS042/provide-evidence` | `AUTHORIZATION_ERROR`                                                              |
| `/v1/customer/disputes/ERRDIS043/provide-evidence` | `UNPROCESSABLE_ENTITY`                                                             |
| `/v1/customer/disputes/ERRDIS044/provide-evidence` | `VALIDATION_ERROR`<br />(issue: INVALID\_EVIDENCE\_FILE)                           |
| `/v1/customer/disputes/ERRDIS045/provide-evidence` | `VALIDATION_ERROR`<br />(issue: INVALID\_EVIDENCE\_TYPE\_PROOF\_OF\_FULFILLMENT)   |
| `/v1/customer/disputes/ERRDIS046/provide-evidence` | `VALIDATION_ERROR`<br />(issue: ITEM\_ID\_IS\_MANDATORY\_FOR\_MULTIPLE\_EVIDENCES) |
| `/v1/customer/disputes/ERRDIS047/provide-evidence` | `VALIDATION_ERROR`<br />(issue: MISSING\_EVIDENCE\_INFO)                           |
| `/v1/customer/disputes/ERRDIS048/provide-evidence` | `VALIDATION_ERROR`<br />(issue: MISSING\_EVIDENCE\_TYPE)                           |
| `/v1/customer/disputes/ERRDIS049/provide-evidence` | `VALIDATION_ERROR`<br />(issue: MISSING\_REFUND\_ID)                               |
| `/v1/customer/disputes/ERRDIS050/provide-evidence` | `VALIDATION_ERROR`<br />(issue: MISSING\_TRACKING\_INFO)                           |

## Escalate dispute to claim

Use the test values as path parameters to simulate the negative responses.

**Endpoint**: `POST /v1/customer/disputes/{ID}/escalate`

| Path parameter                             | Simulated error response |
| ------------------------------------------ | ------------------------ |
| `/v1/customer/disputes/ERRDIS082/escalate` | `FORBIDDEN`              |
| `/v1/customer/disputes/ERRDIS083/escalate` | `INVALID_RESOURCE_ID`    |
| `/v1/customer/disputes/ERRDIS084/escalate` | `NOT_ACCEPTABLE`         |
| `/v1/customer/disputes/ERRDIS085/escalate` | `UNSUPPORTED_MEDIA_TYPE` |
| `/v1/customer/disputes/ERRDIS086/escalate` | `RATE_LIMIT_REACHED`     |
| `/v1/customer/disputes/ERRDIS087/escalate` | `SERVICE_UNAVAILABLE`    |
| `/v1/customer/disputes/ERRDIS088/escalate` | `INTERNAL_SERVICE_ERROR` |
| `/v1/customer/disputes/ERRDIS089/escalate` | `AUTHORIZATION_ERROR`    |
| `/v1/customer/disputes/ERRDIS090/escalate` | `UNPROCESSABLE_ENTITY`   |

## Appeal dispute

Use the test values as path parameters to simulate the negative responses.

**Endpoint**: `POST /v1/customer/disputes/{ID}/appeal`

| Path parameter                           | Simulated error response                                                           |
| ---------------------------------------- | ---------------------------------------------------------------------------------- |
| `/v1/customer/disputes/ERRDIS066/appeal` | `FORBIDDEN`                                                                        |
| `/v1/customer/disputes/ERRDIS067/appeal` | `INVALID_RESOURCE_ID`                                                              |
| `/v1/customer/disputes/ERRDIS068/appeal` | `NOT_ACCEPTABLE`                                                                   |
| `/v1/customer/disputes/ERRDIS069/appeal` | `UNSUPPORTED_MEDIA_TYPE`                                                           |
| `/v1/customer/disputes/ERRDIS070/appeal` | `RATE_LIMIT_REACHED`                                                               |
| `/v1/customer/disputes/ERRDIS071/appeal` | `SERVICE_UNAVAILABLE`                                                              |
| `/v1/customer/disputes/ERRDIS072/appeal` | `INTERNAL_SERVICE_ERROR`                                                           |
| `/v1/customer/disputes/ERRDIS073/appeal` | `AUTHORIZATION_ERROR`                                                              |
| `/v1/customer/disputes/ERRDIS074/appeal` | `UNPROCESSABLE_ENTITY`                                                             |
| `/v1/customer/disputes/ERRDIS075/appeal` | `VALIDATION_ERROR`<br />(issue: INVALID\_EVIDENCE\_FILE)                           |
| `/v1/customer/disputes/ERRDIS076/appeal` | `VALIDATION_ERROR`<br />(issue: INVALID\_EVIDENCE\_TYPE\_PROOF\_OF\_FULFILLMENT)   |
| `/v1/customer/disputes/ERRDIS077/appeal` | `VALIDATION_ERROR`<br />(issue: ITEM\_ID\_IS\_MANDATORY\_FOR\_MULTIPLE\_EVIDENCES) |
| `/v1/customer/disputes/ERRDIS078/appeal` | `VALIDATION_ERROR`<br />(issue: MISSING\_EVIDENCE\_INFO)                           |
| `/v1/customer/disputes/ERRDIS079/appeal` | `VALIDATION_ERROR`<br />(issue: MISSING\_EVIDENCE\_TYPE)                           |
| `/v1/customer/disputes/ERRDIS080/appeal` | `VALIDATION_ERROR`<br />(issue: MISSING\_REFUND\_ID)                               |
| `/v1/customer/disputes/ERRDIS081/appeal` | `VALIDATION_ERROR`<br />(issue: MISSING\_TRACKING\_INFO)                           |

## Acknowledge returned item

Use the test values as path parameters to simulate the negative responses.

**Endpoint**: `POST /v1/customer/disputes/{ID}/acknowledge-return-item`

| Path parameter                                            | Simulated error response |
| --------------------------------------------------------- | ------------------------ |
| `/v1/customer/disputes/ERRDIS109/acknowledge-return-item` | `FORBIDDEN`              |
| `/v1/customer/disputes/ERRDIS110/acknowledge-return-item` | `INVALID_RESOURCE_ID`    |
| `/v1/customer/disputes/ERRDIS111/acknowledge-return-item` | `NOT_ACCEPTABLE`         |
| `/v1/customer/disputes/ERRDIS112/acknowledge-return-item` | `UNSUPPORTED_MEDIA_TYPE` |
| `/v1/customer/disputes/ERRDIS113/acknowledge-return-item` | `RATE_LIMIT_REACHED`     |
| `/v1/customer/disputes/ERRDIS114/acknowledge-return-item` | `SERVICE_UNAVAILABLE`    |
| `/v1/customer/disputes/ERRDIS115/acknowledge-return-item` | `INTERNAL_SERVICE_ERROR` |
| `/v1/customer/disputes/ERRDIS116/acknowledge-return-item` | `AUTHORIZATION_ERROR`    |
| `/v1/customer/disputes/ERRDIS117/acknowledge-return-item` | `UNPROCESSABLE_ENTITY`   |

Additional information

* Use these test values in automated tests to regularly validate error handling.
* For full request and response formats, see the [Disputes API integration guide](/business/payments/disputes/handle-disputes/use-disputes-api).
* For happy‑path flows and additional examples, see the [Disputes API reference](/reference/api/rest/disputes/list-disputes).


# Supported file types and sizes
Source: https://docs.paypal.ai/growth/disputes/reference/supported-file-types-sizes



When handling disputes, you can upload supporting files as evidence to strengthen your case. Evidence can include receipts, delivery confirmations, photos, or other relevant documentation.

Ensure the files meet the following criteria:

* **Supported file types**: `.jpg`, `.jpeg`, `.gif`, `.png`, and `.pdf`
* **Individual file size**: Less than 10 MB per file
* **Total file size**: Up to 50 MB per API call


# Set up accounts and environment
Source: https://docs.paypal.ai/growth/disputes/set-up



Use these procedures to configure your PayPal business and sandbox accounts to manage disputes in the Resolution Center or to integrate with the Disputes API.

You can use the procedures in this section to ensure that your accounts and environment are set up to manage disputes.

## Set up sandbox account

<Tabs>
  <Tab title="Resolution Center">
    Use this path if you only need to test and manage disputes manually through the PayPal Resolution Center without integrating the Disputes API.

    1. <a href="https://www.paypal.com/signin?returnUri=https%3A%2F%2Fdeveloper.paypal.com%2Fdashboard%2F&intent=developer&ctxId=ul14c2e612301b4f5c99383ae8f762a937">Sign up for a developer account</a>. On successful signup, PayPal automatically creates your sandbox environment. The sandbox environment is a test environment that helps you mimic real-world transactions.
    2. Retrieve sandbox account credentials to log in to your PayPal sandbox account and access the Resolution Center. To do this:
       1. Select **Sandbox Accounts**. By default, the environment includes a business and personal account. To create more sandbox accounts, you can select **Create account**.
       2. Locate the account for which you want to get credentials, and select `⋮`.
       3. Select **View/Edit Account** to view the account email address and the system-generated password.
    3. Sign in to your <a href="https://www.sandbox.paypal.com/signin">PayPal sandbox account</a> using the personal sandbox credentials. In a separate browser session, sign in with the business sandbox credentials. When you test dispute workflows, use the personal account to create disputes and the business account to handle them. Verify the dispute status in both accounts.
  </Tab>

  <Tab title="Disputes API">
    Use this path if you plan to integrate the Disputes API and test automated dispute handling end to end.

    1. <a href="https://www.paypal.com/signin?returnUri=https%3A%2F%2Fdeveloper.paypal.com%2Fdashboard%2F&intent=developer&ctxId=ul14c2e612301b4f5c99383ae8f762a937">Sign up for a developer account</a>. On successful signup, PayPal automatically creates your sandbox environment. The sandbox environment is a test environment that helps you mimic real-world transactions. By default, the environment includes a business and personal account. When testing your app, you can use the personal account to create disputes and the business account to handle them. You can create additional business and personal accounts.

    2. Set up the sandbox environment:
       1. Go to your <a href="https://developer.paypal.com/dashboard/">PayPal developer account</a> and toggle to **Sandbox**.
       2. Go to **Apps & Credentials** and select **Create App**.
       3. Enter your app name, select **Type** as **Merchant**, select the sandbox business account to test your app, and select **Create App**. The app details page is displayed.
       4. Go to **Features** > **Add-on services**. By default, the **Customer disputes** checkbox is selected. If not, select it.
       5. Optional: Configure a webhook listener for the app and subscribe to events:

          1. In the app details page, go to **Sandbox Webhooks**.
          2. Select **Add Webhook**.
          3. Enter a **Webhook URL** (the server endpoint where notifications from PayPal are sent), select the events the app wants to subscribe to, and select **Save**.
          4. The webhook listener is successfully configured, and a **Webhook ID** is displayed. You can store the ID and use it in your app code to verify the source sending messages to your listener.

          For more information on webhooks, see <a href="https://developer.paypal.com/api/rest/webhooks/">Webhooks guide</a>. For the list of disputes events that the app can subscribe to, see <a href="/reference/webhook-events/disputes-v1">Webhook reference</a>.

    3. **Retrieve sandbox app credentials**: To integrate and test the Disputes API, you need the sandbox credentials (**Client ID** and **Client secret**) for your app. To retrieve them, see <a href="/developer/how-to/api/get-started#1-get-your-client-id-and-client-secret">Get your client ID and client secret</a>.

    4. **Get an access token**: To authenticate your API calls, get an access token using your client ID and client secret. For more information, see [Get started with PayPal REST APIs](https://docs.paypal.ai/developer/how-to/api/get-started#2-get-an-access-token)

    5. **Retrieve sandbox account credentials:** When you test your disputes integration end-to-end, you log in to your PayPal personal account, create a dispute, handle it through your PayPal business account, and check the dispute status in both accounts. You need sandbox login credentials for both accounts. For information on how to get these from your developer account, see <a href="/developer/how-to/api/get-started#3-get-sandbox-account-credentials"> Get sandbox account credentials</a>.

    6. Set up the development environment. This involves building your server, installing dependencies, verifying configuration files that the package managers use, and setting up the environment variables.

    ### Set up buyer-side credentials

    <Note>The procedures in this section apply only to the test simulations of the Disputes API.</Note>

    To create disputes or change dispute reasons as a buyer using the Disputes API, you need to set up buyer-side credentials. To do this:

    1. [Configure your REST app](#configure-your-rest-app).
    2. [Get buyer consent](#get-buyer-consent) for your sandbox personal account.
    3. [Use PayPal-Auth-Assertion request header](#use-paypal-auth-assertion-request-header) when you make API calls to create disputes or change dispute reasons as a buyer.

    #### Configure your REST app

    Contact your PayPal account manager to add the following scopes to your REST app:

    | Scope name       | Scope                                                   | Description                         |
    | ---------------- | ------------------------------------------------------- | ----------------------------------- |
    | `DISPUTE_CREATE` | `https://uri.paypal.com/services/disputes/create`       | Scope to create a dispute.          |
    | `UPDATE_BUYER`   | `https://uri.paypal.com/services/disputes/update-buyer` | Scope to change the dispute reason. |

    #### Get buyer consent

    You need to obtain buyer consent to create disputes or change dispute reasons on behalf of your sandbox personal account (buyer) using the Disputes API. To do this:

    1. Create a **Log in with PayPal** button:
       1. Complete the steps to <a href="https://developer.paypal.com/docs/log-in-with-paypal/integrate/#enable-log-in-with-paypal">Enable Log in with PayPal</a> in your PayPal developer account.
       2. Complete the steps to <a href="https://developer.paypal.com/docs/log-in-with-paypal/integrate/generate-button">Generate button</a>. When you do this, you can configure the following options:
          * `application ID (client ID)` as your app's client ID.
          * `container ID` as `lippButton`.
          * `auth end point` as `sandbox`. Confirm this is set to sandbox, as the field may default to production.
          * `scope` as either `https://uri.paypal.com/services/disputes/create` or `https://uri.paypal.com/services/disputes/update-buyer`.
          * `return URL` should match the one configured for your REST app in the previous step.
    2. Run your application.
    3. Under **Features** > **Add-on Services**, select the **Log in with PayPal** on your application.
    4. Log in with your sandbox personal account credentials as a buyer and approve the consent.

    #### Use PayPal-Auth-Assertion request header

    During the API test simulation, include the `PayPal-Auth-Assertion` request header in API calls to create disputes or change dispute reasons as a buyer.

    [Generate the JSON Web Token (JWT)](#generate-jwt-for-paypal-auth-assertion) and pass it in this request header to identify the buyer.

    ##### **Generate JWT for PayPal-Auth-Assertion** <a />

    Replace the following in the HTML code provided:

    * `CLIENT_ID` with your app's client ID.
    * `BUYER_EMAIL` with the buyer's email address.

    Run this code in any HTML sandbox environment or save it as an HTML file and open it in a browser. This generates a JWT that you can use in the `PayPal-Auth-Assertion` request header.

    ```html lines theme={null}
    <span id='cwppButton'></span>
    <html>
      <script>
        function base64url(source) {
          var encodedSource = btoa(source);
          encodedSource = encodedSource.replace(/=+$/, '');
          encodedSource = encodedSource.replace(/\+/g, '-');
          encodedSource = encodedSource.replace(/\//g, '-');
          return encodedSource;
        }
        function generateJWT() {
          var header = {"alg": "none", "typ": "JWT"};
          var data = {"iss":"CLIENT_ID", "email" : "BUYER_EMAIL" };
          document.write(base64url(JSON.stringify(header)) + "." +
          base64url(JSON.stringify(data)) + ".");
        }
      </script>
      <body onload="generateJWT()"/>
    </html>
    ```

    ### Common issues

    **Issue:** `PayPal-Auth-Assertion` header is ignored or rejected.\
    **Fix:** Verify that the JWT contains the correct `CLIENT_ID` and `BUYER_EMAIL`, and that you are using the sandbox personal account email for the buyer.
  </Tab>
</Tabs>

## Set up live account

<Tabs>
  <Tab title="Resolution Center">
    Use this path to manage disputes manually in production without building an API integration.

    Log in to your PayPal business account at the <a href="https://www.paypal.com/disputes/dashboard/">PayPal Business Dashboard</a>. No additional setup or configuration is required to use the Resolution Center in the live environment.
  </Tab>

  <Tab title="Disputes API">
    Use this path when you are ready to move your Disputes API integration from sandbox to production.

    <Note>**Partners**: To set up a partner account with connected integration, complete <a href="https://developer.paypal.com/docs/multiparty/#multi-party-form-wrapper">this form</a>. A PayPal representative will reach out to you. You can work with them to configure your Live account. Use the following procedure after your Live account is configured.</Note>

    1. Log in to your PayPal business account at the <a href="https://developer.paypal.com/">PayPal Developer Dashboard</a>.

    2. Switch to the **Live** environment.

    3. Go to **Apps & Credentials** and create a new app or select an existing app.

    4. Go to **Features** > **Other features**. By default, the **Customer disputes** checkbox is selected. If not, select it.

    5. Optional: Configure a webhook listener for the app and subscribe to events:

       1. On the app details page, go to **Live Webhooks**.
       2. Select **Add Webhook**.
       3. Enter a **Webhook URL** (the server endpoint where notifications from PayPal are sent), select the events the app wants to subscribe to, and select **Save**.
       4. The webhook listener is successfully configured, and a **Webhook ID** is displayed. You can store the ID and use it in your app code to verify the source sending messages to your listener.

       For more information on webhooks, see <a href="https://developer.paypal.com/api/rest/webhooks/">Webhooks guide</a>. For the list of dispute events that the app can subscribe to, see <a href="/reference/webhook-events/disputes-v1">Webhook reference</a>.

    6. Copy your **Client ID** and **Secret** for the live app.

    7. Optional: To download the files submitted as evidence, contact your PayPal account manager to add the following scopes to your REST app:
       1. In scopes - `DOCUMENTS_DISPUTES_DOWNLOAD`
       2. In claims - `dms_data_access_rule:all_of` and `dms_data_access_fields:account_number`
  </Tab>
</Tabs>


# Test and go live
Source: https://docs.paypal.ai/growth/disputes/test-go-live



Implement and validate the PayPal Disputes API in sandbox and live environments as a developer or QA engineer.

## Simulate test scenarios

Before going live, you can use the PayPal sandbox environment to test the Disputes API integration. This ensures it works as expected and meets all business and technical requirements.

### Prerequisites

1. Ensure you <a href="/growth/disputes/set-up#disputes-api">set up the sandbox environment</a>.
2. Ensure you <a href="/growth/disputes/set-up#set-up-buyer-side-credentials">set up buyer-side credentials</a> in the sandbox environment. This is required to [create disputes](#create-dispute) or [change dispute reasons](#change-dispute-reason) as a buyer.

### Simulate buyer actions

Before testing dispute responses for your integration, you need to simulate buyer actions to create the disputes and transactions in the sandbox environment.

<AccordionGroup>
  <Accordion title="Create transaction">
    To create a transaction in the sandbox environment, do these steps:

    1. Log in to your <a href="https://www.sandbox.paypal.com/">sandbox personal account</a> as a buyer.
    2. Select **Send and Request** and follow the on-page instructions to send money to your sandbox business account's email ID.
       <Note>For a transaction to be eligible for chargeback, ensure you use a credit card to send money.</Note>
    3. Select **Go to Summary**.
    4. In the **Recent activity** section, select the transaction.
    5. On the **Summary** page, copy the **Transaction ID**. Use this value to [create a dispute](#create-dispute).
  </Accordion>

  <Accordion title="Create dispute">
    You can create disputes as a buyer using this endpoint and test how to handle them in the sandbox environment.

    <Note>This is a sandbox-only endpoint. You cannot use it to create disputes in the live environment.</Note>

    Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token">valid access token</a>, include the <a href="/growth/disputes/set-up#use-paypal-auth-assertion-request-header">PayPal-Auth-Assertion request header with a valid JWT</a>, and make a `POST` call to the `/v1/customer/disputes` endpoint. Include the following parameters:

    | Parameter                                       | Description                                                                                                                                                           | Action                                                                                                                         |
    | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
    | `disputed_transactions`<br /><span>array</span> | Array of transaction details for which the dispute is created.                                                                                                        | Pass the transaction ID retrieved after [creating a transaction](#create-transaction) in the `buyer_transaction_id` parameter. |
    | `reason`<br /><span>string</span>               | Reason for the dispute. <Note>For more information, see <a href="/growth/disputes/reference/dispute-reasons">Dispute reasons</a>.</Note>                              | Pass the reason for which you are disputing the transaction.                                                                   |
    | `dispute_amount`<br /><span>object</span>       | Currency and value of the amount in dispute. The amount value must be less than or equal to the transaction amount of the [created transaction](#create-transaction). | Pass the currency and amount details.                                                                                          |
    | `extensions`<br /><span>object</span>           | Additional dispute details, including whether the merchant was contacted, the contact outcome, and the issue type.                                                    | Pass the additional dispute details as needed.                                                                                 |

    <CodeGroup>
      ```shell lines Sample request theme={null}
      curl -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes \
      -H 'Authorization: Bearer ACCESS-TOKEN' \
      -H 'Content-Type: multipart/form-data' \
      -H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \
      -F 'input={
          "disputed_transactions": [{
              "buyer_transaction_id": "BUYER-TRANSACTION-ID"
              }],
          "reason": "MERCHANDISE_OR_SERVICE_NOT_RECEIVED",
          "dispute_amount": { 
              "currency_code":"USD", 
              "value": "20"
              },
          "extensions": {
              "merchant_contacted": true,
              "merchant_contacted_outcome": "NO_RESPONSE",
              "merchandize_dispute_properties": {
                "issue_type": "PRODUCT"
              }
          }
      };type=application/json'
      ```

      ```json lines Sample response theme={null}
      {
        "links": [
          {
            "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803",
            "rel": "self",
            "method": "GET"
          }
        ]
      }
      ```
    </CodeGroup>

    A successful call returns a `201 Created` response and an HATEOAS link for the dispute. Use the dispute ID from the HATEOAS link to perform subsequent tests on the dispute.

    To test Accelerated Response, see [Accelerated Response sandbox testing](/growth/disputes/test-go-live#accelerated-response-sandbox-testing).
  </Accordion>

  <Accordion title="Create chargeback">
    You can create chargebacks using this endpoint and test how to handle them in the sandbox environment.

    <Note>This is a sandbox-only endpoint. You cannot use it to create chargebacks in the live environment.</Note>

    Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token">valid access token</a> and make a `POST` call to the `/v2/customer-support/process-chargeback` endpoint. Include the following parameters:

    | Parameter                                                                         | Description                                                                                                               | Action                                                                                                                                    |
    | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
    | `adjacency`<br /><span>Required</span>, <span>string</span>                       | Payment method used for the transaction.                                                                                  | Set the value as `PAYPAL` for PayPal transactions.                                                                                        |
    | `file_layout`<br /><span>Required</span>, <span>string</span>                     | Format or layout for the chargeback event.                                                                                | Set the value as `ATCK_CB` for PayPal transactions.                                                                                       |
    | `merchant_id`<br /><span>Required</span>, <span>string</span>                     | Unique identifier for the merchant.                                                                                       | Pass the merchant ID associated with the PayPal account.                                                                                  |
    | `financial_institution.processor`<br /><span>Required</span>, <span>string</span> | Name of the payment processor.                                                                                            | Set the value as `FDMS` for PayPal transactions.                                                                                          |
    | `transaction.id_enc`<br /><span>Required</span>, <span>string</span>              | Encrypted transaction identifier of the transaction for which the chargeback is created.                                  | Pass the `SELLER-TRANSACTION-ID` in this parameter. This is the transaction ID available when you log in using the business test account. |
    | `transaction.amount`<br /><span>Required</span>, <span>object</span>              | Currency and amount for the transaction.                                                                                  | Pass the currency and amount details.                                                                                                     |
    | `instrument`<br /><span>Required</span>, <span>object</span>                      | Details about the payment instrument used for the transaction.                                                            | Pass the payment instrument details.                                                                                                      |
    | `instrument.instrument_type`<br /><span>Required</span>, <span>string</span>      | Type of payment instrument used for the transaction.<br /><br />**Possible values**: `CARD`, `BANK`, `CREDIT`, and so on. | Set the value as `CARD` for card-funded transactions.                                                                                     |
    | `dispute`<br /><span>Required</span>, <span>object</span>                         | Details about the dispute.                                                                                                | Pass the dispute details.                                                                                                                 |
    | `dispute.receive_date`<br /><span>string</span>                                   | Date and time when the chargeback was received.                                                                           | Pass a current value for this parameter.                                                                                                  |
    | `dispute.money_movement_date`<br /><span>string</span>                            | Date and time when the money movement happened.                                                                           | Pass a current value for this parameter.                                                                                                  |
    | `dispute.response_date`<br /><span>string</span>                                  | Date and time when the response to the chargeback is due.                                                                 | Pass a future value for this parameter.                                                                                                   |

    <CodeGroup>
      ```shell lines expandable Sample request theme={null}
      curl -X POST https://api-m.sandbox.paypal.com/v2/customer-support/process-chargeback \
      -H 'Authorization: Bearer ACCESS-TOKEN' \
      -H 'Content-Type: application/json' \
      -d '{
          "adjacency": "PAYPAL",
          "file_layout": "ATCK_CB",
          "merchant_id": "99038409233245",
          "financial_institution": {
              "processor": "FDMS"
          },
          "transaction": {
              "id_enc": "SELLER-TRANSACTION-ID",
              "amount": {
                  "currency_code": "USD",
                  "value": "20"
              }
          },
          "instrument": {
              "instrument_type": "CARD",
              "card_brand": "VISA",
              "credit_card_transaction_id": "2347289342893472",
              "external": false
          },
          "dispute": {
              "id": null,
              "stage": "CHARGEBACK",
              "response_date": "2023-07-16T12:05:22.544Z",
              "status": "2",
              "amount": {
                  "currency_code": "USD",
                  "value": "10"
              },
              "receive_date": "2025-06-16T12:05:22.544Z",
              "event_code": "CHARGEBACK_INITIATED",
              "money_movement_date": "2025-06-16T12:05:22.544Z",
              "event_type": "DEBIT",
              "chargeback_type": "REPORTED_TO_PROCESSOR",
              "processor_info": {
                  "reference_number": "31639435342702423793399",
                  "reason_code": "1330",
                  "notes": "TEST_MEMO"
              }
          }
      }'
      ```

      ```json lines Sample response theme={null}
      {
        "dispute_id": "PP-D-1234"
      }
      ```
    </CodeGroup>

    A successful call returns a `201 Created` response and a dispute ID. Use the dispute ID to perform subsequent tests on the dispute.
  </Accordion>

  <Accordion title="Change dispute reason">
    You can change the reason for a dispute using this endpoint in the sandbox environment. This allows you to test how your integration handles changes to dispute reasons.

    <Note>This is a sandbox-only endpoint. You cannot use it to change dispute reasons in the live environment.</Note>

    Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token">valid access token</a>, include the <a href="/growth/disputes/set-up#use-paypal-auth-assertion-request-header">PayPal-Auth-Assertion request header with a valid JWT</a>, and make a `POST` call to the `/v1/customer/disputes/{ID}/change-reason` endpoint. Include the following parameters:

    | Parameter name                      | Description                                                                                      | Action                                                                                                                                       |
    | ----------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
    | `reason`<br /><span>string</span>   | New reason for the dispute.                                                                      | Set the value to the new dispute reason. For more information, see <a href="/growth/disputes/reference/dispute-reasons">Dispute reasons</a>. |
    | `note`<br /><span>string</span>     | Note explaining the reason for the change.                                                       | Pass the reason for the change if needed.                                                                                                    |
    | `item_info`<br /><span>array</span> | Details about the disputed item if more than one item was available in the disputed transaction. | Pass the item details if needed.                                                                                                             |

    **Path parameter**: `ID` is the `dispute_id` returned in the [Create dispute](#create-dispute) response.

    <CodeGroup>
      ```shell lines expandable Sample request theme={null}
      curl -X POST "https://api-m.sandbox.paypal.com/v1/customer/disputes/{ID}/change-reason" \
      -H 'Authorization: Bearer ACCESS-TOKEN' \
      -H 'Content-Type: multipart/related' \
      -H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \
      -F 'input={
          "reason": "MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED",
          "note": "Product is not as advertised",
          "item_info":
          [
              {
                  "item_name": "item 1",
                  "item_quantity": "2",
                  "reason": "MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED",
                  "item_type": "PRODUCT",
                  "product_details":
                  {
                      "sub_reason": "DELAYED",
                      "category": "OTHER"
                  },
                  "expected_refund":
                  {
                      "currency_code": "USD",
                      "value": "10"
                  }
              }
          ]
      };type=application/json'
      ```

      ```json lines Sample response theme={null}
      {
        "links": [
          {
            "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803",
            "rel": "self",
            "method": "GET"
          }
        ]
      }
      ```
    </CodeGroup>

    A successful call returns a `200 OK` response and an HATEOAS link for the dispute.
  </Accordion>

  <Accordion title="Accept offer to resolve dispute">
    Accept a merchant's offer to resolve a dispute by ID. PayPal automatically refunds the proposed amount to the customer.

    Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token">valid access token</a> and make a `POST` call to the `/v1/customer/disputes/{id}/accept-offer` endpoint. Include the following parameter:

    | Parameter                       | Description                                                                                           | Action                 |
    | ------------------------------- | ----------------------------------------------------------------------------------------------------- | ---------------------- |
    | `note`<br /><span>string</span> | The customer's notes about accepting the offer. PayPal can view these notes, but the merchant cannot. | Pass a note if needed. |

    **Path parameter**: `id` is the `dispute_id` returned in the [Create dispute](#create-dispute) response.

    <CodeGroup>
      ```shell lines Sample request theme={null}
      curl --request POST \
        --url https://api-m.sandbox.paypal.com/v1/customer/disputes/{id}/accept-offer \
        --header 'Authorization: Bearer ACCESS TOKEN' \
        --header 'Content-Type: application/json' \
        --header 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \
        --data '{
        "note": "I am ok with the refund offered."
      }'
      ```

      ```json lines Sample response theme={null}
      {
        "links": [
          {
            "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803",
            "rel": "self",
            "method": "GET"
          }
        ]
      }
      ```
    </CodeGroup>

    A successful call returns an HTTP `200 OK` status code and a HATEOAS link to the dispute. If money movement for the offer is delayed due to internal reasons, the call returns an HTTP `202 Accepted` status code instead.
  </Accordion>

  <Accordion title="Deny offer to resolve dispute">
    The customer denies a merchant's offer to resolve a dispute, by ID.

    Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token">valid access token</a> and make a `POST` call to the `/v1/customer/disputes/{id}/deny-offer` endpoint. Include the following parameter:

    | Parameter                                              | Description                                                                                               | Action                                 |
    | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- | -------------------------------------- |
    | `note`<br /><span>Required</span>, <span>string</span> | The customer's notes about the denial of the offer. PayPal can view these notes, but the merchant cannot. | Pass the reason for denying the offer. |

    **Path parameter**: `id` is the `dispute_id` returned in the [Create dispute](#create-dispute) response.

    <CodeGroup>
      ```shell lines Sample request theme={null}
      curl --request POST \
        --url https://api-m.sandbox.paypal.com/v1/customer/disputes/{id}/deny-offer \
        --header 'Authorization: Bearer ACCESS-TOKEN' \
        --header 'Content-Type: application/json' \
        --header 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \
        --data '{
        "note": "Refund offer is low."
      }'
      ```

      ```json lines Sample response theme={null}
      {
        "links": [
          {
            "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803",
            "rel": "self",
            "method": "GET"
          }
        ]
      }
      ```
    </CodeGroup>

    A successful call returns an HTTP `200 OK` status code and a HATEOAS link to the dispute.
  </Accordion>
</AccordionGroup>

### Simulate PayPal actions

<AccordionGroup>
  <Accordion title="Settle dispute">
    <Note>This is a sandbox-only endpoint. You cannot use it to settle disputes in the live environment.</Note>

    Settle a dispute in the customer's or merchant's favor to complete end-to-end dispute resolution testing in the sandbox. Before you make this call, confirm that the dispute `status` is `UNDER_REVIEW` and the `adjudicate` link is available in the HATEOAS links of the show dispute details response.

    To make this call, the dispute `status` must be `UNDER_REVIEW` and the `adjudicate` link must be available in the HATEOAS links of the show dispute details response.

    Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token">valid access token</a> and make a `POST` call to the `/v1/customer/disputes/{id}/adjudicate` endpoint. Include the following parameter:

    | Parameter                                                              | Description                                                                                    | Action                                                                                              |
    | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
    | `adjudication_outcome`<br /><span>Required</span>, <span>string</span> | The outcome of the adjudication.<br /><br />**Possible values**: `BUYER_FAVOR`, `SELLER_FAVOR` | Pass the outcome to indicate whether the dispute is resolved in the customer's or merchant's favor. |

    **Path parameter**: `id` is the `dispute_id` returned in the [Create dispute](#create-dispute) response.

    <CodeGroup>
      ```shell lines Sample request theme={null}
      curl --request POST \
        --url https://api-m.sandbox.paypal.com/v1/customer/disputes/{id}/adjudicate \
        --header 'Authorization: Bearer ACCESS-TOKEN' \
        --header 'Content-Type: application/json' \
        --data '{
        "adjudication_outcome": "BUYER_FAVOR"
      }'
      ```

      ```json lines Sample response theme={null}
      {
        "links": [
          {
            "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803",
            "rel": "self",
            "method": "GET"
          }
        ]
      }
      ```
    </CodeGroup>

    A successful call returns an HTTP `200 OK` status code and a HATEOAS link to the dispute.
  </Accordion>

  <Accordion title="Update dispute status">
    <Note>This is a sandbox-only endpoint. You cannot use it to update dispute statuses in the live environment.</Note>

    Updates the status of a dispute, by ID, from `UNDER_REVIEW` to either `WAITING_FOR_BUYER_RESPONSE` or `WAITING_FOR_SELLER_RESPONSE`. This status change enables either the customer or merchant to submit evidence for the dispute.

    To make this call, the dispute `status` must be `UNDER_REVIEW` and the `require-evidence` link must be available in the HATEOAS links of the show dispute details response.

    Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token">valid access token</a> and make a `POST` call to the `/v1/customer/disputes/{id}/require-evidence` endpoint. Include the following parameter:

    | Parameter                                                | Description                                                                                                                                                  | Action                                                                                                                                    |
    | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
    | `action`<br /><span>Required</span>, <span>string</span> | Indicates whether the status change enables the customer or merchant to submit evidence.<br /><br />**Possible values**: `BUYER_EVIDENCE`, `SELLER_EVIDENCE` | Pass `BUYER_EVIDENCE` to set the status to `WAITING_FOR_BUYER_RESPONSE`, or `SELLER_EVIDENCE` to set it to `WAITING_FOR_SELLER_RESPONSE`. |

    **Path parameter**: `id` is the `dispute_id` returned in the [Create dispute](#create-dispute) response.

    <CodeGroup>
      ```shell lines Sample request theme={null}
      curl --request POST \
        --url https://api-m.sandbox.paypal.com/v1/customer/disputes/{id}/require-evidence \
        --header 'Authorization: Bearer ACCESS-TOKEN' \
        --header 'Content-Type: application/json' \
        --data '{
        "action": "BUYER_EVIDENCE"
      }'
      ```

      ```json lines Sample response theme={null}
      {
        "links": [
          {
            "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803",
            "rel": "self",
            "method": "GET"
          }
        ]
      }
      ```
    </CodeGroup>

    A successful call returns an HTTP `200 OK` status code and a HATEOAS link to the dispute.
  </Accordion>
</AccordionGroup>

### Test dispute scenarios

You can use the scenarios in this section to test how your integration handles disputes and chargebacks in the sandbox environment.

<AccordionGroup>
  <Accordion title="Test internal disputes">
    You can test internal disputes by [creating a dispute](#create-dispute) for a transaction with PayPal. The dispute can be for payments made using a card, bank account, digital wallet, or other supported payment methods.

    **Test data condition**: Use `OTHER` as the evidence type when you <a href="/growth/disputes/handle-disputes/use-disputes-api#provide-evidence">provide evidence</a>.

    | Scenario                                                                                     | Description                                                                                                                                                                                                                              | Test steps                                                                                                                                                                                                                       | Expected outcome                                                                                                                                                                                                                                                     |
    | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Dispute NO HOLD, MERCHANT WINS CASE                                                          | <ul><li>The buyer creates a dispute for a transaction where PayPal does not hold the money in the merchant's account.</li><li>The merchant provides evidence and the case resolves in the merchant's favor.</li></ul>                    | <ol><li>**Buyer**: [Create a dispute](#create-dispute) using the PayPal wallet.</li><li>**Merchant**: <a href="/growth/disputes/handle-disputes/use-disputes-api#provide-evidence">Provide the requested evidence</a>.</li></ol> | <ol><li>The merchant receives the relevant [notifications](#internal-dispute-possible-notifications).</li><li>The merchant's account balance remains unchanged.</li></ol>                                                                                            |
    | Dispute WITH HOLD, MERCHANT WINS CASE                                                        | <ul><li>The buyer creates a dispute for a transaction where PayPal holds the money in the merchant's account.</li><li> The merchant provides evidence and the case resolves in the merchant's favor. PayPal releases the hold.</li></ul> | <ol><li>**Buyer**: [Create a dispute](#create-dispute) using the PayPal wallet.</li><li>**Merchant**: <a href="/growth/disputes/handle-disputes/use-disputes-api#provide-evidence">Provide the requested evidence</a>.</li></ol> | <ol><li>The merchant receives the relevant [notifications](#internal-dispute-possible-notifications).</li><li>PayPal releases the hold on the merchant's account.</li></ol>                                                                                          |
    | Dispute NO HOLD, MERCHANT LOSES CASE (no data), NO SELLER PROTECTION, DISPUTE FEE is charged | <ul><li>The buyer creates a dispute for a transaction where PayPal does not hold the money in the merchant's account.</li><li>The merchant does not provide evidence and the case resolves in the buyer's favor.</li></ul>               | <ol><li>**Buyer**: [Create a dispute](#create-dispute) using the PayPal wallet.</li><li>**Merchant**: Do not provide evidence.</li></ol>                                                                                         | <ol><li>The merchant receives the relevant [notifications](#internal-dispute-possible-notifications).</li><li>The case resolves in the buyer's favor. The transaction is not eligible for Seller Protection.</li><li>PayPal debits the merchant's account.</li></ol> |

    **Possible notifications**<a />

    * **Webhooks**:
      * Case creation: `CUSTOMER.DISPUTE.CREATED`
      * Merchant response for evidence submission: `CUSTOMER.DISPUTE.UPDATED`
      * Case resolution: `CUSTOMER.DISPUTE.RESOLVED`
    * **Emails**: Case creation, response request, and resolution.
  </Accordion>

  <Accordion title="Test chargebacks">
    You can [create chargebacks](#create-chargeback) for card transactions and test them using these scenarios.

    **Test data conditions:**

    * **Mastercard**: Reason code - `4853`
    * **Visa**: Reason code - `C2`
    * For test conditions where a temporary hold applies, the hold is placed and released when the case is resolved in the merchant's favor.

    | Scenario                                                               | Description                                                                                                                                                                                                                                                        | Test steps                                                                                                                                                                                                     | Expected outcome                                                                                                                                                                                                                 |
    | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Chargeback WITH PROVISIONAL CREDIT, MERCHANT WINS CASE                 | <ul><li>A chargeback is created for a transaction.</li><li>The merchant provides evidence, the case resolves in the merchant’s favor, and the merchant retains the provisional credit.</li></ul>                                                                   | <ol><li>**Buyer**: [Create a chargeback](#create-chargeback).</li><li>**Merchant**: <a href="/growth/disputes/handle-disputes/use-disputes-api#provide-evidence">Provide the requested evidence</a>.</li></ol> | <ol><li>The merchant receives the relevant [notifications](#chargeback-possible-notifications).</li><li>The merchant's account balance remains unchanged.</li></ol>                                                              |
    | Chargeback WITHOUT PROVISIONAL CREDIT, MERCHANT WINS CASE              | <ul><li>A chargeback is created for a transaction where PayPal does not hold the money in the merchant's account.</li><li>The merchant provides evidence and the case resolves in the merchant's favor.</li></ul>                                                  | <ol><li>**Buyer**: [Create a chargeback](#create-chargeback).</li><li>**Merchant**: <a href="/growth/disputes/handle-disputes/use-disputes-api#provide-evidence">Provide the requested evidence</a>.</li></ol> | <ol><li>The merchant receives the relevant [notifications](#chargeback-possible-notifications).</li><li>The merchant's account balance remains unchanged.</li></ol>                                                              |
    | Chargeback WITH PROVISIONAL CREDIT, MERCHANT LOSES CASE (no data)      | <ul><li>A chargeback is created for a transaction where PayPal does not hold the money in the merchant's account.</li><li>The merchant does not provide evidence, the case resolves in the buyer's favor, and the merchant loses the provisional credit.</li></ul> | <ol><li>**Buyer**: [Create a chargeback](#create-chargeback).</li><li>**Merchant**: Do not provide evidence.</li></ol>                                                                                         | <ol><li>The merchant receives the relevant [notifications](#chargeback-possible-notifications).</li><li>The case resolves in the buyer's favor. </li><li>PayPal debits the merchant's account.</li></ol>                         |
    | Chargeback WITHOUT PROVISIONAL CREDIT, MERCHANT LOSES CASE (no data)   | <ul><li>A chargeback is created for a transaction where PayPal does not hold the money in the merchant's account.</li><li>The merchant does not provide evidence and the case resolves in the buyer's favor.</li></ul>                                             | <ol><li>**Buyer**: [Create a chargeback](#create-chargeback).</li><li>**Merchant**: Do not provide evidence.</li></ol>                                                                                         | <ol><li>The merchant receives the relevant [notifications](#chargeback-possible-notifications).</li><li>The case resolves in the buyer's favor.</li><li> PayPal debits the merchant's account.</li></ol>                         |
    | Chargeback WITH PROVISIONAL CREDIT, MERCHANT LOSES CASE (adjudication) | <ul><li>A chargeback is created for a transaction where PayPal does not hold the money in the merchant's account.</li><li> The merchant provides evidence and the case resolves in the buyer's favor and the merchant loses the provisional credit.</li></ul>      | <ol><li>**Buyer**: [Create a chargeback](#create-chargeback).</li><li>**Merchant**: <a href="/growth/disputes/handle-disputes/use-disputes-api#provide-evidence">Provide the requested evidence</a>.</li></ol> | <ol><li>The merchant receives the relevant [notifications](#chargeback-possible-notifications).</li><li>The case adjudicates in the buyer's favor after evidence review.</li><li>PayPal debits the merchant's account.</li></ol> |

    **Possible notifications**<a />

    * **Webhooks**:
      * Case creation: `CUSTOMER.DISPUTE.CREATED`
      * Merchant response for evidence submission: `CUSTOMER.DISPUTE.UPDATED`
      * Case resolution: `CUSTOMER.DISPUTE.RESOLVED`
    * **Emails**: Case creation, response request, and resolution.
  </Accordion>
</AccordionGroup>

### Test merchant response

You can test and determine how to respond to disputes using different scenarios. This ensures that your integration correctly handles the merchant actions during the dispute process.

**Key terms**:

* **INR**: Item Not Received
* **SNAD**: Significantly Not As Described

#### Check response due date and HATEOAS links

You can use the <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">Show dispute details</a> response to determine how and when to respond to disputes.

| Test steps                                                                                                                                                                                                                                                                     | Expected outcome                                                                                                                                                        |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <ol><li>**Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create an INR case.</li><li>**Merchant**: <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">Retrieve the dispute details</a>.</li></ol> | The API returns a `200 OK` response. It includes `status`, `seller_response_due_date`, and `links` parameters that help you respond appropriately within the timeframe. |

#### Inquiry stage

You can use the procedures in this section to test dispute response handling during the inquiry stage.

<AccordionGroup>
  <Accordion title="Send message to other party">
    You can test sending a message to the buyer during the inquiry stage of a dispute. For example, when a buyer creates an INR or SNAD case for a completed transaction, you can send a message to the buyer directly and help resolve the issue before it escalates.

    | Test steps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Expected outcome                                                                                                                                                                                               |
    | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | <ol><li>**Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create an INR or SNAD case.</li><li>**Merchant**:<ol><li><a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">Retrieve the dispute details</a>.</li><li>Check if the send message action is available in the HATEOAS links.</li><li><a href="/growth/disputes/handle-disputes/use-disputes-api#send-message-to-other-party">Send a message to the other party</a>.</li></ol></li></ol> | The API returns a `200 OK` response. You can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check the `messages` array in the response. |
  </Accordion>

  <Accordion title="Make offer to resolve dispute">
    You can test making an offer to the buyer in these scenarios.

    > **Note**: Merchant must have sufficient funds to issue a refund.

    <AccordionGroup>
      <Accordion title="REFUND_WITH_RETURN - SNAD case">
        For a SNAD case in the inquiry stage, you can test offering the buyer a refund in exchange for returning the item.

        | Test steps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Expected outcome                                                                                                                                                                                                                                              |
        | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
        | <ol><li>**Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create a SNAD case.</li><li>**Merchant**:<ol><li><a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">Retrieve the dispute details</a>.</li><li>Check if the make offer action is available in the HATEOAS links.</li><li><a href="/growth/disputes/handle-disputes/use-disputes-api#make-offer-to-resolve-dispute">Make an offer</a> with the following parameters:<ul><li>`offer_amount`: Set the amount that you are willing to refund the buyer.</li><li>`offer_type`: Set the value as `REFUND_WITH_RETURN`.</li><li>`return_shipping_address`: Pass the shipping address for returning the item.</li></ul></li></ol></li></ol> | The API returns a `200 OK` response. You can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check the `offer.seller_offered_amount` and `offer.offer_type` parameters in the response. |
      </Accordion>

      <Accordion title="REFUND_WITH_REPLACEMENT - SNAD case">
        For a SNAD case in the inquiry stage, you can test offering the buyer a replacement item along with a refund.

        | Test steps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Expected outcome                                                                                                                                                                                                                                              |
        | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
        | <ol><li>**Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create a SNAD case.</li><li>**Merchant**:<ol><li><a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">Retrieve the dispute details</a>.</li><li>Check if the make offer action is available in the HATEOAS links.</li><li><a href="/growth/disputes/handle-disputes/use-disputes-api#make-offer-to-resolve-dispute">Make an offer</a> with the following parameters:<ul><li>`offer_amount`: Set the amount that you are willing to refund the buyer.</li><li>`offer_type`: Set the value as `REFUND_WITH_REPLACEMENT`.</li></ul></li></ol></li></ol> | The API returns a `200 OK` response. You can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check the `offer.seller_offered_amount` and `offer.offer_type` parameters in the response. |
      </Accordion>

      <Accordion title="REPLACEMENT_WITHOUT_REFUND - SNAD case">
        For a SNAD case in the inquiry stage, you can test offering the buyer a replacement item without a refund.

        | Test steps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Expected outcome                                                                                                                                                                                                           |
        | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
        | <ol><li>**Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create a SNAD case.</li><li>**Merchant**:<ol><li><a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">Retrieve the dispute details</a>.</li><li>Check if the make offer action is available in the HATEOAS links.</li><li><a href="/growth/disputes/handle-disputes/use-disputes-api#make-offer-to-resolve-dispute">Make an offer</a> with the `offer_type` parameter value as `REPLACEMENT_WITHOUT_REFUND`.</li></ol></li></ol> | The API returns a `200 OK` response. You can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check the `offer.offer_type` parameter in the response. |
      </Accordion>

      <Accordion title="REFUND">
        For an INR or SNAD case in the inquiry stage, you can test offering the buyer a refund without the replacement of the item.

        | Test steps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Expected outcome                                                                                                                                                                                                                                              |
        | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
        | <ol><li>**Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create an INR or SNAD case.</li><li>**Merchant**:<ol><li><a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">Retrieve the dispute details</a>.</li><li>Check if the make offer action is available in the HATEOAS links.</li><li><a href="/growth/disputes/handle-disputes/use-disputes-api#make-offer-to-resolve-dispute">Make an offer</a> with the following parameters:<ul><li>`offer_amount`: Set the amount that you are willing to refund the buyer.</li><li>`offer_type`: Set the value as `REFUND`.</li></ul></li></ol></li></ol> | The API returns a `200 OK` response. You can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check the `offer.seller_offered_amount` and `offer.offer_type` parameters in the response. |
      </Accordion>
    </AccordionGroup>

    For the actions involving return, you can <a href="#acknowledge-returned-item">acknowledge returned item</a> when the buyer returns the item and uploads the tracking information.
  </Accordion>

  <Accordion title="Acknowledge returned item">
    You can test [offering a refund with the return of the item](#refund-with-return-snad-case), accept it as a buyer and upload the return tracking information. After this, the acknowledge return item option will be available for you.

    | Test steps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Expected outcome                                                                                                                                                                                                                                                                       |
    | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | <ol><li>**Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create a SNAD case.</li><li>**Merchant**:<ol><li><a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">Retrieve the dispute details</a>.</li><li>Check if the make offer action is available in the HATEOAS links.</li><li><a href="/growth/disputes/handle-disputes/use-disputes-api#make-offer-to-resolve-dispute">Make an offer</a> with the following parameters:<ul><li>`offer_amount`: Set the amount that you are willing to refund the buyer.</li><li>`offer_type`: Set the value as `REFUND_WITH_RETURN`.</li><li>`return_shipping_address`: Pass the shipping address for returning the item.</li></ul></li></ol></li><li>**Buyer**:<ol><li>In the <a href="https://www.sandbox.paypal.com/disputes/dashboard/">PayPal Resolution Center</a>, view the dispute details and accept the offer.</li><li>Add the tracking information for the returned item.</li></ol></li><li>**Merchant**:<ol><li><a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">Retrieve the dispute details</a>.</li><li>Check if the acknowledge returned item action is available in HATEOAS links.</li><li><a href="/growth/disputes/handle-disputes/use-disputes-api#acknowledge-returned-item">Acknowledge the returned item</a>.</li></ol></li></ol> | The API returns a `200 OK` response. You can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check the `offer.seller_offered_amount`, `offer.offer_type`, and `acknowledgement_type` parameters in the response. |
  </Accordion>

  <Accordion title="Provide evidence">
    You can test providing evidence for these evidence types. This section applies to INR cases only.

    <AccordionGroup>
      <Accordion title="PROOF_OF_FULFILLMENT">
        You can test the `PROOF_OF_FULFILLMENT` evidence type by providing tracking information for the INR cases.

        | Test steps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Expected outcome                                                                                                                                                                                                                                                                                    |
        | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
        | <ol><li>**Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create an INR case.</li><li>**Merchant**:<ol><li><a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">Retrieve the dispute details</a>.</li><li>Check if the provide evidence is available in the HATEOAS links and if the `evidences` object contains `evidence_type` as `PROOF_OF_FULFILLMENT` and `source` as `REQUESTED_FROM_SELLER`.</li><li><a href="/growth/disputes/handle-disputes/use-disputes-api#provide-evidence">Provide the evidence</a> with the following parameters within the `evidences` object:<ul><li>`evidence_type`: Set the value as `PROOF_OF_FULFILLMENT`.</li><li>`evidence_info.tracking_info`: Pass the tracking information for the item.</li></ul></li></ol></li></ol> | The API returns a `200 OK` response. You can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check the `evidence_type`, `source`, and `evidence_info.tracking_info` parameters within the `evidences` object in the response. |
      </Accordion>

      <Accordion title="PROOF_OF_REFUND">
        You can test the `PROOF_OF_REFUND` evidence type by providing refund details for the INR cases.

        | Test steps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Expected outcome                                                                                                                                                                                                                                                                                 |
        | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
        | <ol><li>**Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create an INR case.</li><li>**Merchant**:<ol><li><a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">Retrieve the dispute details</a>.</li><li>Check if the provide evidence is available in the HATEOAS links and if the `evidences` object contains `evidence_type` as `PROOF_OF_REFUND` and `source` as `REQUESTED_FROM_SELLER`.</li><li><a href="/growth/disputes/handle-disputes/use-disputes-api#provide-evidence">Provide the evidence</a> with the following parameters within the `evidences` object:<ul><li>`evidence_type`: Set the value as `PROOF_OF_REFUND`.</li><li>`evidence_info.refund_ids`: Pass the refund ID for the item.</li></ul></li></ol></li></ol> | The API returns a `200 OK` response. You can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check the `evidence_type`, `source`, and `evidence_info.refund_ids` parameters within the `evidences` object in the response. |
      </Accordion>

      <Accordion title="OTHER">
        You can test the `OTHER` evidence type by providing notes or documents (including photos and files) for the INR cases.
        <Note>For more information about the supported file types and size limits, see <a href="/growth/disputes/reference/supported-file-types-sizes">Supported file types and sizes</a>.</Note>

        | Test steps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Expected outcome                                                                                                                                                                                                                                                                           |
        | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
        | <ol><li>**Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create an INR case.</li><li>**Merchant**:<ol><li><a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">Retrieve the dispute details</a>.</li><li>Check if the provide evidence is available in the HATEOAS links and if the `evidences` object contains `evidence_type` as `OTHER` and `source` as `REQUESTED_FROM_SELLER`.</li><li><a href="/growth/disputes/handle-disputes/use-disputes-api#provide-evidence">Provide the evidence</a> with the following parameters within the `evidences` object:<ul><li>`evidence_type`: Set the value as `OTHER`.</li><li>`notes`: Pass the additional evidence details as notes.</li><li>`documents`: Pass the document details.</li></ul></li></ol></li></ol> | The API returns a `200 OK` response. You can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check the `evidence_type`, `source`, `notes`, and `documents` parameters within the `evidences` object in the response. |
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="Accept claim">
    You can test accepting the claim and refunding the buyer when you choose not to dispute the case.

    > **Note**: Merchant must have sufficient funds to issue a refund.

    | Test steps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Expected outcome                                                                                                                                                                                                                                                                                                          |
    | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | <ol><li>**Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create an INR or SNAD case.</li><li>**Merchant**:<ol><li><a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">Retrieve the dispute details</a>.</li><li>Check if the accept claim action is available in the HATEOAS links.</li><li><a href="/growth/disputes/handle-disputes/use-disputes-api#accept-claim">Accept the claim</a> with the `accept_claim_type` parameter value as `REFUND`.</li></ol></li></ol> | The API returns a `200 OK` response. You can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check the `dispute_outcome` object in the response. The `CUSTOMER.DISPUTE.RESOLVED` webhook notification with the refund details is sent to the buyer. |
  </Accordion>

  <Accordion title="Escalate dispute to claim">
    You can test escalating the dispute to a claim to simulate cases where you cannot reach an amicable resolution with the buyer.

    | Test steps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Expected outcome                                                                                                                                                                                                                                                                                                                    |
    | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | <ol><li>**Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create an INR or SNAD case.</li><li>**Merchant**:<ol><li><a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">Retrieve the dispute details</a>.</li><li>Check if the escalate action is available in the HATEOAS links.</li><li><a href="/growth/disputes/handle-disputes/use-disputes-api#escalate-dispute-to-claim">Escalate the dispute to claim</a>.</li></ol></li></ol> | The API returns a `200 OK` response. You can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check the `dispute_life_cycle_stage` parameter value is updated from `INQUIRY` to `CHARGEBACK`. The system also triggers the `CUSTOMER.DISPUTE.UPDATED` webhook. |

    To test Accelerated Response, see [Accelerated Response sandbox testing](/growth/disputes/test-go-live#accelerated-response-sandbox-testing).
  </Accordion>
</AccordionGroup>

#### Claim stage

You can use the procedures in this section to test dispute response handling during the claim stage.

<AccordionGroup>
  <Accordion title="Provide evidence">
    You can test providing evidence for these evidence types.

    <AccordionGroup>
      <Accordion title="PROOF_OF_FULFILLMENT - INR case">
        You can test the `PROOF_OF_FULFILLMENT` evidence type by providing tracking information for the INR cases.

        | Test steps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Expected outcome                                                                                                                                                                                                                                                                                    |
        | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
        | <ol><li>**Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create an INR case.</li><li>**Merchant**:<ol><li><a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">Retrieve the dispute details</a>.</li><li>Check if the provide evidence is available in the HATEOAS links and if the `evidences` object contains `evidence_type` as `PROOF_OF_FULFILLMENT` and `source` as `REQUESTED_FROM_SELLER`.</li><li><a href="/growth/disputes/handle-disputes/use-disputes-api#provide-evidence">Provide the evidence</a> with the following parameters within the `evidences` object:<ul><li>`evidence_type`: Set the value as `PROOF_OF_FULFILLMENT`.</li><li>`evidence_info.tracking_info`: Pass the tracking information for the item.</li></ul></li></ol></li></ol> | The API returns a `200 OK` response. You can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check the `evidence_type`, `source`, and `evidence_info.tracking_info` parameters within the `evidences` object in the response. |
      </Accordion>

      <Accordion title="PROOF_OF_REFUND">
        You can test the `PROOF_OF_REFUND` evidence type by providing refund details for the INR or SNAD cases.

        | Test steps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Expected outcome                                                                                                                                                                                                                                                                                 |
        | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
        | <ol><li>**Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create an INR or SNAD case.</li><li>**Merchant**:<ol><li><a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">Retrieve the dispute details</a>.</li><li>Check if the provide evidence is available in the HATEOAS links and if the `evidences` object contains `evidence_type` as `PROOF_OF_REFUND` and `source` as `REQUESTED_FROM_SELLER`.</li><li><a href="/growth/disputes/handle-disputes/use-disputes-api#provide-evidence">Provide the evidence</a> with the following parameters within the `evidences` object:<ul><li>`evidence_type`: Set the value as `PROOF_OF_REFUND`.</li><li>`evidence_info.refund_ids`: Pass the refund ID for the item.</li></ul></li></ol></li></ol> | The API returns a `200 OK` response. You can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check the `evidence_type`, `source`, and `evidence_info.refund_ids` parameters within the `evidences` object in the response. |
      </Accordion>

      <Accordion title="OTHER">
        You can test the `OTHER` evidence type by providing notes or documents (including photos and files) for the INR or SNAD cases.
        <Note>For more information about the supported file types and size limits, see <a href="/growth/disputes/reference/supported-file-types-sizes">Supported file types and sizes</a>.</Note>

        | Test steps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Expected outcome                                                                                                                                                                                                                                                                           |
        | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
        | <ol><li>**Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create an INR or SNAD case.</li><li>**Merchant**:<ol><li><a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">Retrieve the dispute details</a>.</li><li>Check if the provide evidence is available in the HATEOAS links and if the `evidences` object contains `evidence_type` as `OTHER` and `source` as `REQUESTED_FROM_SELLER`.</li><li><a href="/growth/disputes/handle-disputes/use-disputes-api#provide-evidence">Provide the evidence</a> with the following parameters within the `evidences` object:<ul><li>`evidence_type`: Set the value as `OTHER`.</li><li>`notes`: Pass the additional evidence details as notes.</li><li>`documents`: Pass the document details.</li></ul></li></ol></li></ol> | The API returns a `200 OK` response. You can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check the `evidence_type`, `source`, `notes`, and `documents` parameters within the `evidences` object in the response. |
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="Accept claim">
    You can test accepting the claim and refunding the buyer if you choose to resolve the case using these accept claim types.

    > **Note**: Merchant must have sufficient funds to issue a refund.

    <AccordionGroup>
      <Accordion title="REFUND">
        The test procedure to refund the dispute amount is identical in the inquiry and claim stages. For detailed information, see [Accept claim](#accept-claim).
      </Accordion>

      <Accordion title="REFUND_WITH_RETURN">
        You can test accepting the claim for a SNAD case and refunding the buyer after they return the item to a specified address.

        | Test steps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Expected outcome                                                                                                                                                                                                                                                                  |
        | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
        | <ol><li>**Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create a SNAD dispute.</li><li>**Merchant**: <ol><li><a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">Retrieve the dispute details</a>.</li><li>Check if the accept claim action is available in the HATEOAS links.</li><li><a href="/growth/disputes/handle-disputes/use-disputes-api#accept-claim">Accept the claim</a> with the following parameters:<ul><li>`return_shipping_address`: Pass the shipping address for returning the item.</li><li>`accept_claim_type`: Set the value as `REFUND_WITH_RETURN`.</li></ul></li></ol></li><li>**Buyer**: In the <a href="https://www.sandbox.paypal.com/disputes/dashboard/">PayPal Resolution Center</a>, view the dispute details and provide the tracking information for the returned item.</li></ol> | The system triggers the `CUSTOMER.DISPUTE.UPDATED` webhook.<br />You can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check the response parameters to get the tracking information and update the case. |
      </Accordion>

      <Accordion title="PARTIAL_REFUND">
        You can test accepting the claim and providing a partial refund (amount less than the buyer-requested refund) to the buyer for a INR or SNAD cases.

        | Test steps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Expected outcome                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
        | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
        | <ol><li>**Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create a SNAD dispute.</li><li>**Merchant**:<ol><li><a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">Retrieve the dispute details</a>.</li><li>Check if the accept claim action is available in the HATEOAS links.</li><li><a href="/growth/disputes/handle-disputes/use-disputes-api#accept-claim">Accept the claim</a> with the following parameters:<ul><li>`refund_amount`: Amount to refund.</li><li>`accept_claim_type`: Set the value as `PARTIAL_REFUND`.</li></ul></li></ol></li></ol> | <ul><li>The API returns a `200 OK` response. You can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and track the updates.</li><li>If the refund amount is greater than or equal to the buyer-requested refund amount, the case is resolved, and you receive the `CUSTOMER.DISPUTE.RESOLVED` webhook notification.</li><li>If the amount is less than the buyer-requested refund amount, it triggers an email to the buyer for their consent in the Resolution Center.</li></ul> |
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="Acknowledge returned item">
    You can test [offering a refund with the return of the item](#refund-with-return-snad-case), accept it as a buyer and upload the return tracking information. After this, the acknowledge return item option will be available for you.

    | Test steps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Expected outcome                                                                                                                                                                                                                                                                       |
    | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | <ol><li>**Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create a SNAD case.</li><li>**Merchant**:<ol><li><a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">Retrieve the dispute details</a>.</li><li>Check if the make offer action is available in the HATEOAS links.</li><li><a href="/growth/disputes/handle-disputes/use-disputes-api#make-offer-to-resolve-dispute">Make an offer</a> with the following parameters:<ul><li>`offer_amount`: Set the amount that you are willing to refund the buyer.</li><li>`offer_type`: Set the value as `REFUND_WITH_RETURN`.</li><li>`return_shipping_address`: Pass the shipping address for returning the item.</li></ul></li></ol></li><li>**Buyer**:<ol><li>In the <a href="https://www.sandbox.paypal.com/disputes/dashboard/">PayPal Resolution Center</a>, view the dispute details and accept the offer.</li><li>Add the tracking information for the returned item.</li></ol></li><li>**Merchant**:<ol><li><a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">Retrieve the dispute details</a>.</li><li>Check if the acknowledge returned item action is available in HATEOAS links.</li><li><a href="/growth/disputes/handle-disputes/use-disputes-api#acknowledge-returned-item">Acknowledge the returned item</a>.</li></ol></li></ol> | The API returns a `200 OK` response. You can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check the `offer.seller_offered_amount`, `offer.offer_type`, and `acknowledgement_type` parameters in the response. |
  </Accordion>
</AccordionGroup>

#### Appeal dispute

When PayPal adjudicates a case against a party, you or the buyer may be eligible to appeal the decision. PayPal uses predefined rules to determine appeal eligibility.

To test appeals, create a buyer account with a primary email address that includes `allowappeal` (for example, [testallowappeal@personal.example.com](mailto:testallowappeal@personal.example.com)). The disputes created with this account will trigger:

* The seller appeal workflow if you are found liable.
* The buyer appeal workflow if the buyer is found liable.

<Note>Each party can submit only one appeal per case.</Note>

To simulate cases where appeals are not allowed for a buyer, create a buyer account with a primary email address that includes `noappeal` (for example, [testnoappeal@personal.example.com](mailto:testnoappeal@personal.example.com)).

You can appeal the case and provide evidence using these evidence types.

<AccordionGroup>
  <Accordion title="PROOF_OF_FULFILLMENT">
    If the case is resolved in the buyer's favor, you can appeal by providing the fulfillment information for INR, unauthorized, or other cases.

    | Test steps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Expected outcome                                                                                                                                                                                                                                                                                                                                                                                                                                  |
    | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | <ol><li>**Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create an INR case.</li><li>**Merchant**:<ol><li><a href="https://developer.paypal.com/docs/api/customer-disputes/v1/#disputes_adjudicate">Settle the dispute</a> with `adjudication_outcome` as `BUYER_FAVOR` to resolve the case in the buyer's favor.</li><li><a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">Retrieve the dispute details</a>.</li><li>Check if the appeal action is available in the HATEOAS links.</li><li><a href="/growth/disputes/handle-disputes/use-disputes-api#appeal-dispute">Appeal the case</a> with the following parameters within the `evidences` object:<ul><li>`evidence_type`: Set the value as `PROOF_OF_FULFILLMENT`.</li><li>`evidence_info.tracking_info`: Pass the tracking information for the item.</li></ul></li></ol></li></ol> | The API returns a `200 OK` response. You can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check:<ul><li>If the `evidences` object contains the `evidence_type` and `evidence_info.tracking_info` parameter values you provided.</li><li>If the `status` and `dispute_life_cycle_stage` parameter values are `UNDER_REVIEW` and `PRE_ARBITRATION` respectively.</li></ul> |
  </Accordion>

  <Accordion title="PROOF_OF_REFUND">
    If the case is resolved in the buyer's favor, you can appeal by providing the refund information for all the dispute reasons.

    | Test steps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Expected outcome                                                                                                                                                                                                                                                                                                                                                                                                                               |
    | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | <ol><li>**Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create an INR or SNAD case.</li><li>**Merchant**:<ol><li><a href="https://developer.paypal.com/docs/api/customer-disputes/v1/#disputes_adjudicate">Settle the dispute</a> with `adjudication_outcome` as `BUYER_FAVOR` to resolve the case in the buyer's favor.</li><li><a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">Retrieve the dispute details</a>.</li><li>Check if the appeal action is available in the HATEOAS links.</li><li><a href="/growth/disputes/handle-disputes/use-disputes-api#appeal-dispute">Appeal the case</a> with the following parameters within the `evidences` object:<ul><li>`evidence_type`: Set the value as `PROOF_OF_REFUND`.</li><li>`evidence_info.refund_ids`: Pass the refund ID for the item.</li></ul></li></ol></li></ol> | The API returns a `200 OK` response. You can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check:<ul><li>If the `evidences` object contains the `evidence_type` and `evidence_info.refund_ids` parameter values you provided.</li><li>If the `status` and `dispute_life_cycle_stage` parameter values are `UNDER_REVIEW` and `PRE_ARBITRATION` respectively.</li></ul> |
  </Accordion>

  <Accordion title="OTHER">
    If the case is resolved in the buyer's favor, you can appeal by providing notes or documents. You can use the `OTHER` evidence type if the requested evidence is not covered by the `PROOF_OF_FULFILLMENT` and `PROOF_OF_REFUND` evidence types.

    | Test steps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Expected outcome                                                                                                                                                                                                 |
    | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | <ol><li>**Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create an INR or SNAD case.</li><li>**Merchant**:<ol><li><a href="https://developer.paypal.com/docs/api/customer-disputes/v1/#disputes_adjudicate">Settle the dispute</a> with `adjudication_outcome` as `BUYER_FAVOR` to resolve the case in the buyer's favor.</li><li><a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">Retrieve the dispute details</a>.</li><li>Check if the appeal action is available in the HATEOAS links and the `evidences` object for the requested evidence.</li><li><a href="/growth/disputes/handle-disputes/use-disputes-api#appeal-dispute">Appeal the case</a> with the following parameters within the `evidences` object:<ul><li>`evidence_type`: Set the value as `OTHER`.</li><li>`notes`: Pass the additional evidence details as notes.</li><li>`documents`: Pass the document details.</li></ul></li></ol></li></ol> | The API returns a `200 OK` response. You can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check the `evidences` object in the response. |
  </Accordion>
</AccordionGroup>

## Accelerated Response sandbox testing

To enable Accelerated Response for a dispute, include the value `ACCELERATED_RESPONSE_ENABLED` in the `notes` field under `evidences` when submitting your `create_dispute` API request.

<CodeGroup>
  ```shell lines Sample request theme={null}
  curl -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes \
  -H 'Authorization: Bearer A21AAItEDV4r4hH1p72Aw8iciCdCyVmIeiXi7XkX8I38AHTDN7Zc4KywkWgsjH8gP4hfQwWFVn8Hj880z_s2ormzjPh80D_5w' \
  -H 'Content-Type: multipart/form-data' \
  -H 'PayPal-Auth-Assertion: eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0.eyJpc3MiOiJBWmdidVpPU1B0YnJIWnNrNFZHeFAxOVFvZFUzVk91R1R5UEhhRTZJNkJVVm9NdTJvSnpIZExGeVc3Rmpvd1labGdVaEk4eWRzcXh6RlAtSSIsImVtYWlsIjoic2ItcmstYnV5ZXJAcGVyc29uYWwuZXhhbXBsZS5jb20ifQ.' \
  -F 'input={
      "disputed_transactions": [{
          "buyer_transaction_id": "2NJ45340EV624100G"
          }],
      "reason": "MERCHANDISE_OR_SERVICE_NOT_RECEIVED",
      "dispute_amount": {
          "currency_code":"USD",
          "value": "5"
          },
      "extensions": {
          "merchant_contacted": true,
          "merchant_contacted_outcome": "NO_RESPONSE",
          "merchandize_dispute_properties": {
            "issue_type": "PRODUCT"
          }
      },
      "evidences": [{
              "notes": "ACCELERATED_RESPONSE_ENABLED"
          }
      ]
  };type=application/json'
  ```

  ```json lines Sample response theme={null}
  {
    "links": [{
      "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-R-TOW-10161582",
      "rel": "self",
      "method": "GET"
    }]
  }
  ```
</CodeGroup>

### Escalation simulation

To simulate the day of escalation in the sandbox environment, use the following transaction amounts:

| Transaction amount (USD) | Simulated escalation day |
| ------------------------ | ------------------------ |
| 5.00 – 5.99              | Day 5 escalation         |
| 9.00 – 9.99              | Day 9 escalation         |
| ≥ 11.00                  | Day 11 escalation        |

Create a transaction with one of the listed amounts, then use that transaction when creating the dispute to simulate the corresponding escalation day.

### Applicable dispute reasons

Accelerated Response currently applies to these dispute reasons:

* `MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED`
* `MERCHANDISE_OR_SERVICE_NOT_RECEIVED`

Once the dispute is created, you can perform any of the actions listed under the [Inquiry stage](https://docs.paypal.ai/growth/disputes/handle-disputes/use-disputes-api#inquiry-stage) section.

## Applicable document proofs

Refer to the applicable documentation requirements in [Supported file types and sizes](/growth/disputes/reference/supported-file-types-sizes).

## Test webhooks

To test disputes webhooks, you need to wait a few minutes after creating the dispute for the actions to become available. You can then perform the actions to trigger the webhooks.

### Test dispute created webhook

You can test the `CUSTOMER.DISPUTE.CREATED` webhook in both the [inquiry](#test-dispute-created-inquiry-stage) and [claim](#test-dispute-created-claim-stage) stages.

#### **Inquiry stage** <a />

You can test this webhook in the inquiry stage for these scenarios.

<AccordionGroup>
  <Accordion title="SNAD case">
    You can create a SNAD case for a transaction and test triggering the webhook.

    | Test steps                                                                                                          | Expected outcome                                                                                                                                                                                                                                                                                                                                                                                                 |
    | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create a SNAD case. | <ol><li>The system triggers the `CUSTOMER.DISPUTE.CREATED` webhook.</li><li>After receiving the webhook notification, you can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check if the parameter values of `reason` and `dispute_life_cycle_stage` are `MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED` and `INQUIRY` respectively.</li></ol> |
  </Accordion>

  <Accordion title="INR case">
    You can create an INR case for a transaction and test triggering the webhook.

    | Test steps                                                                                                          | Expected outcome                                                                                                                                                                                                                                                                                                                                                                                             |
    | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | **Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create an INR case. | <ol><li>The system triggers the `CUSTOMER.DISPUTE.CREATED` webhook.</li><li>After receiving the webhook notification, you can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check if the parameter values of `reason` and `dispute_life_cycle_stage` are `MERCHANDISE_OR_SERVICE_NOT_RECEIVED` and `INQUIRY` respectively.</li></ol> |
  </Accordion>
</AccordionGroup>

#### **Claim stage** <a />

You can test this webhook in the claim stage for these scenarios.

<AccordionGroup>
  <Accordion title="SNAD case">
    If you have opted out of the dispute stage, you can create a SNAD case for a transaction and test triggering this webhook in the claim stage.

    | Test steps                                                                                                          | Expected outcome                                                                                                                                                                                                                                                                                                                                                                                                    |
    | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create a SNAD case. | <ol><li>The system triggers the `CUSTOMER.DISPUTE.CREATED` webhook.</li><li>After receiving the webhook notification, you can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check if the parameter values of `reason` and `dispute_life_cycle_stage` are `MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED` and `CHARGEBACK` respectively.</li></ol> |
  </Accordion>

  <Accordion title="INR case">
    If you have opted out of the dispute stage, you can create an INR case for a transaction and test triggering this webhook in the claim stage.

    | Test steps                                                                                                          | Expected outcome                                                                                                                                                                                                                                                                                                                                                                                                |
    | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create an INR case. | <ol><li>The system triggers the `CUSTOMER.DISPUTE.CREATED` webhook.</li><li>After receiving the webhook notification, you can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check if the parameter values of `reason` and `dispute_life_cycle_stage` are `MERCHANDISE_OR_SERVICE_NOT_RECEIVED` and `CHARGEBACK` respectively.</li></ol> |
  </Accordion>

  <Accordion title="Unauthorized case">
    You can create an unauthorized case for a transaction and test triggering the webhook.

    <Note>For unauthorized disputes, the buyer and merchant receive different dispute IDs. For merchants, the format and identifiers of the notifications stay the same as those of other dispute types.</Note>

    | Test steps                                                                                                                   | Expected outcome                                                                                                                                                                                                                                                                                                                                                                         |
    | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create an unauthorized case. | <ol><li>The system triggers the `CUSTOMER.DISPUTE.CREATED` webhook.</li><li>After receiving the webhook notification, you can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check if the parameter values of `reason` and `dispute_life_cycle_stage` are `UNAUTHORISED` and `CHARGEBACK` respectively.</li></ol> |
  </Accordion>

  <Accordion title="Transaction error case">
    You can test triggering the webhook by creating a dispute for a transaction error using one of these dispute reasons: `CREDIT_NOT_PROCESSED`, `DUPLICATE_TRANSACTION`, `INCORRECT_AMOUNT`, `PAYMENT_BY_OTHER_MEANS`, `CANCELED_RECURRING_BILLING`, or `OTHER`.

    <Note>For more information about the dispute reasons, see <a href="/growth/disputes/reference/dispute-reasons">Dispute reasons</a>.</Note>

    | Test steps                                                                                                                                     | Expected outcome                                                                                                                                                                                                                                                                                                                                                                                               |
    | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create a case with one of the dispute reasons. | <ol><li>The system triggers the `CUSTOMER.DISPUTE.CREATED` webhook.</li><li>After receiving the webhook notification, you can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check if the parameter values of `reason` and `dispute_life_cycle_stage` are the dispute reason that you provided and `CHARGEBACK` respectively.</li></ol> |
  </Accordion>

  <Accordion title="Duplicate dispute creation (negative testing)">
    You can test that a buyer cannot open a duplicate dispute on a transaction that already has an existing dispute. Even after the original dispute case is closed, the buyer cannot open a new dispute on the same transaction.

    | Test steps                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Expected outcome                                             |
    | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
    | <ol><li>**Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create an INR or SNAD case.</li><li>**Merchant**: <a href="https://developer.paypal.com/docs/api/customer-disputes/v1/#disputes_adjudicate">Settle the dispute</a> with `adjudication_outcome` as `BUYER_FAVOR` to resolve the case in the buyer's favor.</li><li>**Buyer**: Check if you can create a dispute for the same transaction.</li></ol> | You cannot open a duplicate dispute on the same transaction. |
  </Accordion>
</AccordionGroup>

### Test dispute updated webhook

You can test the `CUSTOMER.DISPUTE.UPDATED` webhook in both the [inquiry](#test-dispute-updated-inquiry-stage) and [claim](#test-dispute-updated-claim-stage) stages.

#### **Inquiry stage** <a />

You can test this webhook in the inquiry stage for this scenario.

<Accordion title="Buyer sends message to merchant">
  You can test this webhook by sending a message to the merchant as a buyer for the INR or SNAD case.

  | Test steps                                                                                                                                                                                                   | Expected outcome                                                                                                                                                                                                                                                                                                               |
  | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  | **Buyer**: <ol><li>Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create an INR or SNAD case.</li><li>Select the case ID and send a message to the merchant.</li></ol> | <ol><li>The system triggers `CUSTOMER.DISPUTE.UPDATED` webhook. </li><li>After receiving the webhook notification, you can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check if the message details are available in the `messages` array.</li></ol> |
</Accordion>

#### **Claim stage** <a />

You can test this webhook in the claim stage for these scenarios.

<AccordionGroup>
  <Accordion title="Buyer provides return tracking information">
    If you have opted out of the dispute stage, you can accept a claim for a case and provide the buyer with the return shipping address. Then, test as a buyer by returning the item and providing the return tracking information.

    | Test steps                                                                                                                                                                                                                                                                                                                                                                                                                             | Expected outcome                                                                                                                                                                                                                                                                                                          |
    | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | <ol><li>**Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create a SNAD dispute.</li><li>**Merchant**: <a href="https://developer.paypal.com/docs/api/customer-disputes/v1/#disputes_accept-claim">Accept the claim</a>.</li><li>**Buyer**: Provide the tracking number through the <a href="https://www.sandbox.paypal.com/disputes/dashboard/">PayPal Resolution Center</a>.</li></ol> | <ol><li>The system triggers `CUSTOMER.DISPUTE.UPDATED` webhook. </li><li>After receiving the webhook notification, you can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check the response parameters to get the tracking information.</li></ol> |
  </Accordion>

  <Accordion title="Buyer changes reason">
    You can test changing the dispute reason of the INR dispute to SNAD or unauthorized activity.

    | Test steps                                                                                                                                                                                                                           | Expected outcome                                                                                                                                                                                                                                                                                                                     |
    | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | **Buyer**: <ol><li>Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create an INR dispute.</li><li>Select **Change case type** and update the reason to SNAD or unauthorized activity.</li></ol> | <ol><li>The system triggers `CUSTOMER.DISPUTE.UPDATED` webhook.</li><li>After receiving the webhook notification, you can <a href="/growth/disputes/handle-disputes/use-disputes-api#show-dispute-details">retrieve the dispute details</a> and check if the `reason` parameter value contains the updated dispute reason.</li></ol> |
  </Accordion>
</AccordionGroup>

### Test dispute resolved webhook

You can test the `CUSTOMER.DISPUTE.RESOLVED` webhook for these scenarios.

<AccordionGroup>
  <Accordion title="Buyer cancels dispute">
    You can test cancelling the dispute in the Resolution Center as a buyer to trigger the webhook.

    | Test steps                                                                                                                                                                                      | Expected outcome                                         |
    | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
    | **Buyer**:<ol><li>Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create a dispute.</li><li>Select the case ID and then, select **Cancel case**.</li></ol> | The system triggers `CUSTOMER.DISPUTE.RESOLVED` webhook. |
  </Accordion>

  <Accordion title="Settle dispute (buyer wins)">
    You can test settling the case in the buyer's favor to trigger the webhook.

    | Test steps                                                                                                                                                                                                                                                                                                                                                        | Expected outcome                                         |
    | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
    | <ol><li>**Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create a dispute.</li><li>**Merchant**: <a href="https://developer.paypal.com/docs/api/customer-disputes/v1/#disputes_adjudicate">Settle the dispute</a> with `adjudication_outcome` as `BUYER_FAVOR` to resolve the case in the buyer's favor.</li></ol> | The system triggers `CUSTOMER.DISPUTE.RESOLVED` webhook. |
  </Accordion>

  <Accordion title="Settle dispute (merchant wins)">
    You can test settling the case in the merchant's favor to trigger the webhook.

    | Test steps                                                                                                                                                                                                                                                                                                                                                            | Expected outcome                                         |
    | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
    | <ol><li>**Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create a dispute.</li><li>**Merchant**: <a href="https://developer.paypal.com/docs/api/customer-disputes/v1/#disputes_adjudicate">Settle the dispute</a> with `adjudication_outcome` as `SELLER_FAVOR` to resolve the case in the merchant's favor.</li></ol> | The system triggers `CUSTOMER.DISPUTE.RESOLVED` webhook. |
  </Accordion>
</AccordionGroup>

### Identify unique webhook through webhook ID

You can test identifying a specific webhook using the webhook ID in the webhook payload.

| Test steps                                                                                                                                                                                                                                                                                   | Expected outcome                                                                                                                                   |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <ol><li>**Merchant**: Subscribe and listen to the dispute webhooks: `CUSTOMER.DISPUTE.CREATED`, `CUSTOMER.DISPUTE.RESOLVED`, `CUSTOMER.DISPUTE.UPDATED`.</li><li>**Buyer**: Log in to your <a href="https://sandbox.paypal.com">sandbox personal account</a> and create a dispute.</li></ol> | The system triggers the `CUSTOMER.DISPUTE.CREATED` webhook notification. You can use the unique webhook ID in the payload to identify the webhook. |

### Test API calls: use test values and simulate responses <a />

To simulate Disputes API responses, inject test values as a path or query parameter in the request URL. These methods allow you to trigger specific error responses without creating actual disputes.

<Tabs>
  <Tab title="Sample - test value as path parameter">
    | Path parameter                    | Simulated error response |
    | --------------------------------- | ------------------------ |
    | `/v1/customer/disputes/ERRDIS015` | `FORBIDDEN`              |

    <CodeGroup>
      ```shell lines Sample request theme={null}
      curl -X GET https://api-m.sandbox.paypal.com/v1/customer/disputes/ERRDIS015 \
        -H 'Authorization: Bearer ACCESS-TOKEN' \
        -H 'Content-Type: application/json'
      ```

      ```json lines Sample response theme={null}
      {
          "name": "FORBIDDEN",
          "message": "No permission for the requested operation",
          "debug_id": "e90ec082e0e4d"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Sample - test value as query parameter">
    | Query parameter                                           | Simulated error response |
    | --------------------------------------------------------- | ------------------------ |
    | `/v1/customer/disputes?disputed_transaction_id=ERRDIS023` | `FORBIDDEN`              |

    <CodeGroup>
      ```shell lines Sample request theme={null}
      curl -X GET https://api-m.sandbox.paypal.com/v1/customer/disputes?disputed_transaction_id=ERRDIS023 \
        -H 'Authorization: Bearer ACCESS-TOKEN' \
        -H 'Content-Type: application/json'
      ```

      ```json lines Sample response theme={null}
      {
          "name": "FORBIDDEN",
          "message": "No permission for the requested operation",
          "debug_id": "e90ec082e0e4d"
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

### Common issues

If an API call fails while you test , check for these common issues:

* 400 Bad Request when required fields or formats are invalid.
* 401 Unauthorized when the access token is missing, expired, or invalid.
* 403 Forbidden when the app is not permitted to perform this action.

For more details, see the [HTTP status codes and error messages](/developer/how-to/api/troubleshooting/common-errors/overview#http-status-codes-and-error-messages).

## Go live

1. <a href="/growth/disputes/set-up#disputes-api-2">Set up live account</a>.
2. <a href="https://docs.paypal.ai/reference/webhook-events/webhook-format#webhook-message-format">Set up webhooks</a> to get real-time notifications about dispute events, such as created, updated, or resolved disputes.
3. Go live with your app.


# Add a Donate button to your website with PayPal's Donate SDK
Source: https://docs.paypal.ai/growth/grow-business/donate/integration



With the Donate SDK, users can select the PayPal Donate button to donate in a pop-up overlaid on your website. This keeps users on your website instead of redirecting them to a donation page on PayPal.

# Eligibility

The easiest way to find out if you're eligible to integrate the Donate SDK is to use paypal.com.

1. Log into <a href="https://www.paypal.com/donate/buttons?_ga=2.37509794.365520210.1755702720-1032254505.1740765755">paypal.com/donate/buttons/</a> with the account you want to use to make a Donate button.
2. If you can start a flow to make a **Donate** button, you're eligible to integrate the Donate SDK.

# 1. Create a Donate button

To use the Donate SDK, create a Donate button in the sandbox.

1. Log in to <a href="https://sandbox.paypal.com/donate/buttons?_ga=2.99832476.365520210.1755702720-1032254505.1740765755">sandbox.paypal.com/donate/buttons/</a>, and make your Donate button.
   After you create a button, you get code.
2. From the code, copy:
   * The `hosted_button_id` value if you have a business account
   * The `business` value if you have a personal account
3. You'll need this parameter to pass to the SDK.

The Donate SDK accepts all parameters that a Donate button accepts, such as `item_name` or `item_number`.

# 2. Add the Donate SDK to your web page

Add the Donate JavaScript SDK to your web page to integrate the Donate button into your site.

```html theme={null}
<!DOCTYPE html>

<head>
 <meta name="viewport" content="width=device-width, initial-scale=1"> <!-- Ensures optimal rendering on mobile devices. -->
 <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <!-- Optimal Internet Explorer compatibility -->
</head>

<body>
 <script src="https://www.paypalobjects.com/donate/sdk/donate-sdk.js" charset="UTF-8"></script>
</body>
```

# 3. Render the Donate button

Render the **Donate** button to a container element on your web page.

If you have a business account, provide the `hosted_button_id` parameter value. For any other account type, provide the `business` parameter value.

```html theme={null}
<body>
 <div id="paypal-donate-button-container"></div>

  <script>
   PayPal.Donation.Button({
       env: 'sandbox',
       hosted_button_id: 'YOUR_SANDBOX_HOSTED_BUTTON_ID',
       // business: 'YOUR_EMAIL_OR_PAYERID',
       image: {
           src: 'https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif',
           title: 'PayPal - The safer, easier way to pay online!',
           alt: 'Donate with PayPal button'
       },
       onComplete: function (params) {
           // Your onComplete handler
       },
   }).render('#paypal-donate-button-container');
</script>
</body>
```

To render another button on the same page, create another container, for example, `<div id="paypal-donate-button-container-2">`. Then render the button in the new container: `}).render('#paypal-donate-button-container-2')`.

# 4. Test the Donate button

1. On the site, click the **Donate** button.
2. Confirm that the button opens a pop-up window and displays your donation page.
3. Complete a donation using a sandbox credit card or sandbox PayPal account.
4. Verify that the `onComplete` function returns an object parameter.

This object parameter contains the following fields.

| Variable      | Description                                         |
| ------------- | --------------------------------------------------- |
| `tx`          | Transaction ID                                      |
| `st`          | Status of the transaction                           |
| `amt`         | Amount of the transaction                           |
| `cc`          | Currency code                                       |
| `cm`          | Custom message                                      |
| `item_number` | Configurable field for the transaction              |
| `item_name`   | Value that the donor selects during the transaction |

# 5. Go live

To go live with your new Donate button, replace the sandbox data with live data.

1. Replace the `hosted_button_id` value for the sandbox with a live `hosted_button_id` for a business account. For any other type of account, replace the sandbox `business` value with a live `business` value.
2. Remove the `env` value, or change `env` to `production`.

```html theme={null}
<body>
 <div id="paypal-donate-button-container"></div>

  <script>
   PayPal.Donation.Button({
       env: 'production',
       hosted_button_id: 'YOUR_LIVE_HOSTED_BUTTON_ID',
       // business: 'YOUR_LIVE_EMAIL_OR_PAYERID',
       image: {
           src: 'https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif',
           title: 'PayPal - The safer, easier way to pay online!',
           alt: 'Donate with PayPal button'
       },
       onComplete: function (params) {
           // Your onComplete handler
       },
   }).render('#paypal-donate-button-container');
</script>
</body>
```

# See also

* <a href="https://developer.paypal.com/api/nvp-soap/ipn/IPNandPDTVariables/">IPN and PDT variables</a>
* <a href="https://developer.paypal.com/api/nvp-soap/paypal-payments-standard/integration-guide/Appx-websitestandard-htmlvariables/">HTML variables for PayPal Payments Standard</a>


# Choose between Invoicing solutions
Source: https://docs.paypal.ai/growth/grow-business/invoicing/choose-solution



PayPal Invoicing supports two ways to create and manage invoices:

* [PayPal Invoicing (Dashboard)](/growth/grow-business/invoicing/quickstart) – Manual invoice creation in the PayPal dashboard
* [Invoicing REST API](/growth/grow-business/invoicing/quickstart-api) – Programmatic invoice creation and automation through backend integration

The key difference between these options is how invoices are created, sent, and tracked: either manually in the Dashboard, programmatically in your application, or a mix of both.

<Columns>
  <Card title="PayPal Invoicing (Dashboard)" href="/growth/grow-business/invoicing/quickstart">
    PayPal Invoicing (Dashboard) lets you to create, send, and manage invoices directly from your PayPal business account without writing code.
  </Card>

  <Card title="Invoicing API" href="/growth/grow-business/invoicing/quickstart-api">
    The Invoicing REST API lets you to create, update, send, and manage invoices programmatically from your backend systems.
  </Card>
</Columns>

All invoices, regardless of how they are created, are accessible in the PayPal dashboard for tracking and management. The primary difference between these options is how invoices are created and updated: manually in the dashboard or programmatically through your application.

## Comparision

| Category                     | PayPal Invoicing (Dashboard)                                                                                                                              | Invoicing REST API                                                                                                                                        |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Who should use it            | Businesses that want a no-code solution and manually create invoices from the PayPal dashboard <br />Ideal for low to moderate invoice volume             | Businesses that need automated invoicing, higher invoice volumes, or integration with backend systems such as ERP, CRM, or SaaS platforms                 |
| How invoices are created     | Manually in the PayPal dashboard                                                                                                                          | Programmatically via REST API calls from your backend                                                                                                     |
| Technical requirements       | No development required                                                                                                                                   | Requires backend development and REST API integration <br />Uses OAuth 2.0 authentication                                                                 |
| Automation                   | Limited to dashboard-based workflows                                                                                                                      | Full automation of invoice creation, sending, reminders, and reconciliation                                                                               |
| Invoice lifecycle management | Manage invoices in the PayPal dashboard (status tracking, reminders, refunds, offline payments)                                                           | Manage invoices via API and webhooks <br />Invoices are also visible in the PayPal dashboard for operational support                                      |
| Payer experience             | PayPal-managed payment workflow with multiple payment methods such as PayPal, debit and credit cards, digital wallets, and eligible local payment methods | PayPal-managed payment workflow with multiple payment methods such as PayPal, debit and credit cards, digital wallets, and eligible local payment methods |


# Core concepts
Source: https://docs.paypal.ai/growth/grow-business/invoicing/core-concepts



The PayPal Invoicing API helps you create, send, and track invoices programmatically. This page describes the core resources, the invoice lifecycle, and the authentication model.

## Core resources

The API centers on the following three primary resources: invoices, templates, and payment records.

### Invoice

An invoice is a hosted payment request that PayPal delivers to your customer and manages through different states over its lifecycle. Unlike a static PDF, an invoice is a dynamic object that moves through distinct states from creation to payment, refund, or cancellation. Each state determines what actions are available.

When you send an invoice, PayPal generates a secure payment page where the customer can view line items and pay using PayPal, a credit card, a debit card, or other eligible payment methods. Customers access this page from a PayPal-issued email link or a QR code you generate.

### Templates

A template is a reusable invoice configuration that pre-populates common fields, including merchant details, default line items, payment terms, tax settings, and branding. Templates decouple invoice design from invoice creation. Instead of hardcoding these values into each request, you create a template and reference it by ID. PayPal inherits default values, including merchant name, email, address, logo, default tax rates, and payment terms, when you create an invoice from that template.

You can override any template value in the invoice request. The invoice is independent of the template after creation, so updating a template doesn't affect invoices already created from it. You can create up to 50 templates.

PayPal provides standard system templates that you can't delete.

### Payment and refund records

The API distinguishes between two types of payment recording.

* **Automatic payment recording:** When customers pay through PayPal's hosted invoice page, PayPal automatically records the transaction and updates the invoice status.

* **Manual payment recording:** For payments received outside PayPal, such as checks, bank transfers, or cash, explicitly call the Record External Payment endpoint to document receipt. This is critical for integrating with non-PayPal payment channels.

This model helps you use PayPal invoicing as a complete tracking system across all payment channels, with a clear record of whether each payment came from PayPal or an external source.

## Invoice lifecycle

| State                | Description                                                                                                                                                                                                                                   |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DRAFT`              | The invoice exists, but the customer hasn't been notified. You can edit all fields freely.                                                                                                                                                    |
| `SENT`               | The invoice is delivered and payable. The customer is notified unless you suppress notification. You can't return a sent invoice to `DRAFT`. If the invoice has a future issue date, PayPal holds it and sends it automatically on that date. |
| `PARTIALLY_PAID`     | A partial payment has been recorded. The balance decreases, but the invoice stays open.                                                                                                                                                       |
| `PAID`               | The full amount was paid through PayPal's hosted page.                                                                                                                                                                                        |
| `MARKED_AS_PAID`     | The full amount was recorded manually via the Record External Payment endpoint.                                                                                                                                                               |
| `REFUNDED`           | The invoice was fully refunded through PayPal.                                                                                                                                                                                                |
| `MARKED_AS_REFUNDED` | A full refund was recorded manually.                                                                                                                                                                                                          |
| `PARTIALLY_REFUNDED` | A partial refund was issued. The balance increases accordingly.                                                                                                                                                                               |
| `CANCELLED`          | The invoice was canceled after being sent. Canceled invoices are retained for audit purposes and remain queryable. To remove a draft invoice, delete it instead. You can't cancel a draft.                                                    |

Invoices stay in `DRAFT` until you send them so customers aren't notified of an incomplete or incorrect request. After you send it, the invoice represents a formal payment commitment. You can cancel it, but you can't unsend it. Canceled invoices are retained for audit purposes rather than deleted, which supports compliance and dispute resolution.

## Billing types

Each line item on an invoice uses one of three unit-of-measure types. A single invoice can combine all three.

| Type       | Best for                                     | Example                |
| ---------- | -------------------------------------------- | ---------------------- |
| `QUANTITY` | Discrete, countable items                    | 2 widgets at \$50 each |
| `HOURS`    | Time-based services                          | 12 hours \$150/hour    |
| `AMOUNT`   | Flat-rate charges with no quantity breakdown | Consultation: \$500    |

## External system integration

If you manage invoices in an external system, such as an ERP or accounting platform, two fields let you bridge it with your system.

* Use `detail.invoice_number` to store your external invoice ID, for example `NETSUITE-INV-78432`. This value is customer-visible and must be unique within your PayPal invoices.
* Use `detail.reference` for cross-referencing order or PO numbers. This field is also visible to customers on the PayPal payment page.

Both fields help PayPal invoicing function as a payment layer on top of your existing invoice management system.

## Authentication

The Invoicing API uses OAuth 2.0. Every request requires an access token in the `Authorization` header. The token is scoped to specific operations. The `https://api.paypal.com/v1/invoicing:*` scope grants full access to invoicing operations.

* **Access token expiration:** Tokens expire after approximately 9 hours. There's no refresh token. Request a new access token using your client credentials when the current one expires. Cache the token with its expiration date timestamp and refresh it proactively rather than waiting for a `401` response.
* **Partner integrations:** If you act on behalf of multiple merchants, include the `PayPal-Auth-Assertion` header on each request. This signed header identifies which merchant you're operating for, and PayPal applies the corresponding merchant context and permissions.
* **Idempotency:** Use the `PayPal-Request-Id` header to make requests idempotent. If a network error causes a request to fail, retry with the same request ID. PayPal recognizes the duplicate and returns the original result without creating a duplicate invoice or recording a duplicate payment.

PayPal invalidates tokens when client credentials are revoked, API scope grants are removed, or the merchant account status changes.


# Errors
Source: https://docs.paypal.ai/growth/grow-business/invoicing/errors



All Invoicing API error responses follow a consistent structure. This guide covers error codes, retry guidance, and client handling patterns.

## Canonical error object

All error responses follow this structure.

```json [expandable] theme={null}
{
  "name": "ERROR_CODE",
  "message": "Human-readable description.",
  "debug_id": "abc123def456",
  "details": [
    {
      "field": "/items/0/unit_amount",
      "issue": "INVALID_FORMAT",
      "description": "The value must be a valid currency amount.",
      "value": "$value",
      "path": "body"
    }
  ],
  "links": [
    {
      "rel": "information_link",
      "href": "https://developer.paypal.com/docs/api/invoicing/#errors"
    }
  ]
}
```

## Field descriptions

| Field                   | Type   | Description                                                                  |
| ----------------------- | ------ | ---------------------------------------------------------------------------- |
| `name`                  | string | Stable error code, for example, `INVALID_REQUEST`, `AUTHENTICATION_FAILURE`. |
| `message`               | string | Human-readable summary of the error.                                         |
| `debug_id`              | string | Unique request identifier for support diagnostics.                           |
| `details`               | array  | Field-level validation errors for 4xx responses.                             |
| `details[].field`       | string | JSON path to the problematic field.                                          |
| `details[].issue`       | string | Specific validation issue, for example, `INVALID_FORMAT`, `REQUIRED_FIELD`.  |
| `details[].description` | string | Resolution guidance.                                                         |
| `links`                 | array  | Links to documentation or support resources.                                 |

## Error taxonomy

The following table lists all error codes, their HTTP status, and whether the request can be retried.

| Status | Error code                | Description                                                                                                                    | Retryable                                             |
| ------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- |
| `400`  | `INVALID_REQUEST`         | Malformed request body, missing required fields, or invalid field values.                                                      | No                                                    |
| `401`  | `AUTHENTICATION_FAILURE`  | Invalid or missing access token. The token may have expired.                                                                   | Yes, after refreshing the token.                      |
| `403`  | `AUTHORIZATION_FAILURE`   | Valid token, but insufficient permissions for this operation.                                                                  | No                                                    |
| `404`  | `NOT_FOUND`               | Invoice, template, or resource doesn't exist.                                                                                  | No                                                    |
| `409`  | `CONFLICT`                | Operation conflicts with the current resource state, for example, invoice already sent or recipient changed twice in 72 hours. | No                                                    |
| `422`  | `UNPROCESSABLE_ENTITY`    | Request is well-formed but violates business rules, for example, payment amount exceeds invoice total.                         | No                                                    |
| `429`  | `RATE_LIMIT_EXCEEDED`     | Too many requests in the time window.                                                                                          | Yes, with exponential backoff.                        |
| `500`  | `INTERNAL_ERROR`          | Unexpected server error.                                                                                                       | Yes, with exponential backoff.                        |
| `502`  | `TEMPORARILY_UNAVAILABLE` | Service temporarily unavailable.                                                                                               | Yes, with exponential backoff.                        |
| `503`  | `SYSTEM_ERROR`            | Scheduled maintenance or service degradation.                                                                                  | Yes, with exponential backoff. Check the status page. |

## Common error scenarios

The following scenarios show common errors and how to resolve them.

### Create an invoice with an invalid merchant account

```json [expandable] theme={null}
{
  "name": "INVALID_REQUEST",
  "message": "The merchant account specified must be in good standing with PayPal.",
  "debug_id": "xyz789abc",
  "details": [
    {
      "field": "/invoicer",
      "issue": "INVALID_ACCOUNT",
      "description": "The specified merchant account does not exist or is not in good standing."
    }
  ]
}
```

To resolve this, verify the invoicer's email address and PayPal account status. Confirm the account isn't suspended or limited.

### Record a payment on a PayPal-processed invoice

If you try to record a payment on an invoice that PayPal has already processed, you receive the following error.

```json [expandable] theme={null}
{
    "name": "UNPROCESSABLE_ENTITY",
    "message": "The requested action could not be performed, semantically incorrect, or failed business validation.",
    "debug_id": "2493c71e2152b",
    "details": [
        {
            "field": "invoiceId",
            "value": "INV2-5GE6-2KVL-XPUN-G5LQ",
            "location": "path",
            "issue": "INVOICE_ALREADY_SENT",
            "description": "The invoice is already sent."
        }
    ],
    "links": [
        {
            "href": "https://developer.paypal.com/docs/api/invoicing/#errors",
            "method": "GET"
        }
    ]
}
```

To resolve this, verify the invoice status using `GET`. If the status is already `PAID` or `PARTIALLY_PAID`, PayPal automatically records the payment. Use the record payment endpoint only for offline payments received through channels other than PayPal.

## Client handling guidance

The following guidance covers how to handle different error types in your integration.

### Retryable errors

For `5xx` and `429` errors, implement exponential backoff with jitter.

```javascript [expandable] theme={null}
async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      if (response.ok) {
        return response;
      }
      if (response.status === 429 || response.status >= 500) {
        const delayMs = Math.pow(2, attempt - 1) * 1000 + Math.random() * 1000;
        console.log(`Retrying in ${delayMs}ms...`);
        await new Promise(resolve => setTimeout(resolve, delayMs));
        continue;
      }
      // Non-retryable error
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    } catch (error) {
      if (attempt === maxRetries) throw error;
    }
  }
}
```

### Non-retryable errors

For `4xx` errors other than `401` and `429`, return the error to the user with the `debug_id`. Don't retry. Use the `details` array to provide field-level feedback.

### Authentication errors

For `401` errors, refresh the access token and retry the request once. If the second attempt also returns `401`, return the error to the user.

## Alerting guidance

* Log all errors with `debug_id` for troubleshooting.
* Alert on `5xx` errors that persist for more than 5 minutes.
* Flag `403` errors as a configuration issue and review your OAuth scopes.
* Track `429` patterns to understand API usage and adjust request rates.

<CardGroup>
  <Card title="Troubleshooting" href="/growth/grow-business/invoicing/troubleshooting">
    Find solutions to common integration issues with the PayPal Invoicing API.
  </Card>

  <Card title="Quick start using Invoicing API" href="/growth/grow-business/invoicing/quickstart-api">
    Create and send your first invoice using the PayPal Invoicing API.
  </Card>
</CardGroup>


# Invoice object
Source: https://docs.paypal.ai/growth/grow-business/invoicing/invoice-object



An invoice is a payment request you send to a customer for goods or services delivered. In the PayPal Invoicing API, invoices flow through a lifecycle: created as `DRAFT`, sent to customers, tracked through payment states (`UNPAID`, `PARTIALLY_PAID`, `PAID`), and optionally refunded.

The invoice object represents a complete invoice including sender and recipient details, line items, amounts, payment configuration, and status. You receive this object when you create, send, or fetch an invoice.

## Sample invoice objects

The following examples show a simple and complex invoice object.

### Simple

```json [expandable] theme={null}
{
  "id": "INV2-XXXX-XXXX-XXXX",
  "status": "DRAFT",
  "detail": {
    "currency_code": "GBP",
    "invoice_number": "INV-0001"
  },
  "invoicer": {
    "email_address": "merchant@example.com"
  },
  "primary_recipients": [
    {
      "billing_info": {
        "email_address": "customer@example.com"
      }
    }
  ],
  "items": [
    {
      "name": "Consulting",
      "quantity": "1",
      "unit_amount": {
        "currency_code": "GBP",
        "value": "100.00"
      }
    }
  ]
}
```

### Complex

```json [expandable] theme={null}
{
  "id": "INV2-XXXX-XXXX-XXXX-XXXX",
  "detail": {
    "invoice_number": "INV-2026-0089",
    "reference": "SOW-2026-003",
    "invoice_date": "2026-03-15",
    "due_date": "2026-03-29",
    "currency_code": "USD",
    "note": "Thank you for working with us. Please don't hesitate to reach out with any questions.",
    "memo": "Internal ref: Q1 closeout — Acct Manager: TJ — Client tier: Enterprise",
    "term": "Payment due within 14 days of invoice date. Late payments subject to a 1.5% monthly fee.",
    "payment_term": {
      "term_type": "NET_14"
    },
    "metadata": {
      "create_time": "2026-03-15T10:30:45Z",
      "update_time": "2026-03-15T10:30:45Z",
      "recipient_view_url": "https://www.paypal.com/invoice/view/...",
      "first_sent_time": "2026-03-15T11:00:00Z"
    }
  },
  "invoicer": {
    "name": {
      "given_name": "Taylor",
      "surname": "Brooks"
    },
    "email_address": "taylor@brooksdesign.com",
    "business_name": "Brooks Design Studio",
    "address": {
      "address_line_1": "450 Market Street",
      "address_line_2": "Suite 800",
      "admin_area_2": "San Francisco",
      "admin_area_1": "CA",
      "postal_code": "94105",
      "country_code": "US"
    },
    "phones": [
      {
        "country_code": "1",
        "national_number": "4155550192",
        "phone_type": "MOBILE"
      }
    ],
    "website": "https://brooksdesign.com"
  },
  "primary_recipients": [
    {
      "billing_info": {
        "name": {
          "given_name": "Jordan",
          "surname": "Kim"
        },
        "business_name": "Kim & Associates LLC",
        "email_address": "jordan@kimassociates.com",
        "address": {
          "address_line_1": "450 Market Street",
          "address_line_2": "Suite 800",
          "admin_area_2": "San Francisco",
          "admin_area_1": "CA",
          "postal_code": "94105",
          "country_code": "US"
        }
      }
    }
  ],
  "items": [
    {
      "name": "UX Design — Discovery & Research",
      "description": "User interviews, competitive analysis, journey mapping",
      "quantity": "12",
      "unit_amount": {
        "currency_code": "USD",
        "value": "150.00"
      },
      "unit_of_measure": "HOURS",
      "tax": {
        "name": "Sales Tax",
        "percent": "8.5"
      }
    },
    {
      "name": "UX Design — Wireframing & Prototyping",
      "description": "Low and high-fidelity wireframes, interactive prototype",
      "quantity": "18",
      "unit_amount": {
        "currency_code": "USD",
        "value": "150.00"
      },
      "unit_of_measure": "HOURS",
      "tax": {
        "name": "Sales Tax",
        "percent": "8.5"
      }
    }
  ],
  "configuration": {
    "allow_tip": true,
    "partial_payment": {
      "allow_partial_payment": true,
      "minimum_amount_due": {
        "currency_code": "USD",
        "value": "500.00"
      }
    },
    "tax_calculated_after_discount": true,
    "tax_inclusive": false
  },
  "amount": {
    "breakdown": {
      "items_total": {
        "currency_code": "USD",
        "value": "4500.00"
      },
      "tax_total": {
        "currency_code": "USD",
        "value": "382.50"
      }
    },
    "total_amount": {
      "currency_code": "USD",
      "value": "4882.50"
    }
  },
  "status": "SENT",
  "payment_summary": {
    "paid_amount": {
      "currency_code": "USD",
      "value": "0.00"
    },
    "outstanding_balance": {
      "currency_code": "USD",
      "value": "4882.50"
    }
  }
}
```

## Object schema

The following tables document the top-level fields in the invoice object, along with the fields in each nested object.

| Field                   | Type   | Required  | Description                                                                                                                                                                                                            |
| ----------------------- | ------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                    | string | Read-only | The unique PayPal-generated invoice ID (`INV2-XXXX-XXXX-XXXX-XXXX`).                                                                                                                                                   |
| `status`                | string | Read-only | The current status of the invoice. Values: `DRAFT`, `SENT`, `SCHEDULED`, `PAID`, `MARKED_AS_PAID`, `CANCELLED`, `REFUNDED`, `PARTIALLY_PAID`, `PARTIALLY_REFUNDED`, `MARKED_AS_REFUNDED`, `UNPAID`, `PAYMENT_PENDING`. |
| `detail`                | object | Required  | Core invoice details including invoice number, date, currency, and payment terms. See [**detail**](#detail) for more information.                                                                                      |
| `invoicer`              | object | Optional  | The business information of the invoice sender. See [**invoicer**](#invoicer) for more information.                                                                                                                    |
| `primary_recipients`    | array  | Optional  | The billing and shipping information for the invoice recipients. Up to 100 recipients. See [**primary\_recipients**](#primary_recipients) for more information.                                                        |
| `additional_recipients` | array  | Optional  | An array of CC email addresses to receive invoice notifications. Up to 100 addresses.                                                                                                                                  |
| `items`                 | array  | Optional  | The line items on the invoice. Up to 100 items. See [**items**](#items) for more information.                                                                                                                          |
| `configuration`         | object | Optional  | Invoice configuration options including partial payment, tips, and tax settings. See [**configuration**](#configuration) for more information.                                                                         |
| `amount`                | object | Read-only | The computed invoice amount summary including totals, tax, discounts, and shipping. See [**amount**](#amount) for more information.                                                                                    |
| `due_amount`            | object | Read-only | The amount outstanding on the invoice. Contains `currency_code` and `value`.                                                                                                                                           |
| `gratuity`              | object | Read-only | The tip amount added by the payer. Contains `currency_code` and `value`.                                                                                                                                               |
| `payments`              | object | Read-only | Payments recorded against the invoice. See [**payments**](#payments) for more information.                                                                                                                             |
| `refunds`               | object | Read-only | Refunds recorded against the invoice. See [**refunds**](#refunds) for more information.                                                                                                                                |
| `links`                 | array  | Read-only | HATEOAS links for available actions on the invoice, for example, `send`, `replace`, `delete`, `qr-code`.                                                                                                               |

### detail

This is core invoice metadata that is required when creating an invoice.

| Field                  | Type   | Required  | Description                                                                                                            |
| ---------------------- | ------ | --------- | ---------------------------------------------------------------------------------------------------------------------- |
| `invoice_number`       | string | Optional  | A merchant-defined invoice number. Max 25 characters. If omitted, PayPal auto-generates one.                           |
| `invoice_date`         | string | Optional  | The invoice date in `YYYY-MM-DD` format. Defaults to the date the invoice is created.                                  |
| `currency_code`        | string | Required  | The three-character ISO-4217 currency code, for example, `USD`, `GBP`.                                                 |
| `reference`            | string | Optional  | A merchant-defined reference identifier, for example, a purchase order number. Max 120 characters.                     |
| `payment_term`         | object | Optional  | The payment due terms. Contains `term_type`, for example, `NET_10`, `NET_30`, `DUE_ON_DATE_SPECIFIED`, and `due_date`. |
| `note`                 | string | Optional  | A note to the recipient. Visible on the invoice. Max 4,000 characters.                                                 |
| `terms_and_conditions` | string | Optional  | The terms and conditions of the invoice. Max 4,000 characters.                                                         |
| `memo`                 | string | Optional  | A memo for internal use. Not visible to the recipient. Max 500 characters.                                             |
| `attachments`          | array  | Optional  | File references to attach to the invoice.                                                                              |
| `metadata`             | object | Read-only | Audit data including `create_time`, `last_update_time`, `recipient_view_url`, and `invoicer_view_url`.                 |

### invoicer

The sender's business information displayed on the invoice.

| Field              | Type   | Required | Description                                                                                                                                   |
| ------------------ | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `email_address`    | string | Optional | The invoicer's email address. Must match the email of the PayPal business account associated with the access token.                           |
| `name`             | object | Optional | The invoicer's name. Contains `given_name` and `surname`.                                                                                     |
| `address`          | object | Optional | The invoicer's address. Contains `address_line_1`, `address_line_2`, `admin_area_1`, `admin_area_2`, `postal_code`, and `country_code`.       |
| `phones`           | array  | Optional | The invoicer's phone numbers. Each entry contains `country_code`, `national_number`, and `phone_type`, for example, `MOBILE`, `HOME`, `WORK`. |
| `website`          | string | Optional | The invoicer's website URL. Max 2,048 characters.                                                                                             |
| `tax_id`           | string | Optional | The invoicer's tax ID.                                                                                                                        |
| `logo_url`         | string | Optional | The URL of a logo to display on the invoice. Must be HTTPS. Max 2,000 characters.                                                             |
| `additional_notes` | string | Optional | Additional notes about the invoicer. Max 40 characters.                                                                                       |

### primary\_recipients

An array of recipient objects. Each entry contains a `billing_info` object and optionally a `shipping_info` object.

#### billing\_info

| Field                   | Type   | Required | Description                                                                                             |
| ----------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------- |
| `email_address`         | string | Optional | The recipient's email address. PayPal sends the invoice notification to this address.                   |
| `name`                  | object | Optional | The recipient's name. Contains `given_name` and `surname`.                                              |
| `address`               | object | Optional | The recipient's billing address. Same structure as `invoicer.address`.                                  |
| `phones`                | array  | Optional | The recipient's phone numbers. Same structure as `invoicer.phones`.                                     |
| `additional_info_value` | string | Optional | A free-text field for additional recipient information, for example, account number. Max 40 characters. |

#### shipping\_info

| Field     | Type   | Required | Description                                                             |
| --------- | ------ | -------- | ----------------------------------------------------------------------- |
| `name`    | object | Optional | The recipient's name for shipping. Contains `given_name` and `surname`. |
| `address` | object | Optional | The shipping destination address. Same structure as `invoicer.address`. |

### items

An array of line items on the invoice. Each item contains the following fields.

| Field             | Type   | Required | Description                                                                    |
| ----------------- | ------ | -------- | ------------------------------------------------------------------------------ |
| `name`            | string | Required | The item name. Max 200 characters.                                             |
| `description`     | string | Optional | A description of the item. Max 1,000 characters.                               |
| `quantity`        | string | Required | The quantity of the item. Supports decimals, for example, `"2.5"`.             |
| `unit_amount`     | object | Required | The price per unit. Contains `currency_code` and `value`.                      |
| `tax`             | object | Optional | Tax applied to this item. Contains `name`, `percent`, and a computed `amount`. |
| `discount`        | object | Optional | Discount applied to this item. Contains either `percent` or a fixed `amount`.  |
| `item_date`       | string | Optional | The date the item or service was provided. Format: `YYYY-MM-DD`.               |
| `unit_of_measure` | string | Optional | The unit of measure for the item. Values: `QUANTITY`, `HOURS`, `AMOUNT`.       |

### configuration

Options that control invoice behavior and payment rules.

| Field                           | Type    | Required | Description                                                                                     |
| ------------------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------- |
| `partial_payment`               | object  | Optional | Partial payment settings. Contains `allow_partial_payment` and `minimum_amount_due`.            |
| `allow_tip`                     | boolean | Optional | If `true`, the payer can add a tip when paying. Default: `false`.                               |
| `tax_calculated_after_discount` | boolean | Optional | If `true`, tax is calculated on the post-discount amount. Default: `false`.                     |
| `tax_inclusive`                 | boolean | Optional | If `true`, the unit amounts already include tax. Default: `false`.                              |
| `template_id`                   | string  | Optional | The ID of a saved template to associate with this invoice. Doesn't auto-populate template data. |

### amount

A read-only computed summary of the invoice total. PayPal populates this based on items and configuration.

| Field                  | Type   | Description                                                                      |
| ---------------------- | ------ | -------------------------------------------------------------------------------- |
| `currency_code`        | string | The invoice currency.                                                            |
| `value`                | string | The total invoice amount.                                                        |
| `breakdown`            | object | A detailed breakdown of the total.                                               |
| `breakdown.item_total` | object | The subtotal of all line items before tax or discount.                           |
| `breakdown.discount`   | object | The total discount applied. Contains `item_discount` and `invoice_discount`.     |
| `breakdown.tax_total`  | object | The total tax applied across all items and shipping.                             |
| `breakdown.shipping`   | object | The shipping amount and any associated tax.                                      |
| `breakdown.custom`     | object | A custom line item, for example, packing charges. Contains `label` and `amount`. |

### payments

A read-only record of payments made against the invoice.

| Field          | Type   | Description                                                                                                         |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| `paid_amount`  | object | The total amount paid so far. Contains `currency_code` and `value`.                                                 |
| `transactions` | array  | An array of individual payment records. Each contains `payment_id`, `method`, `payment_date`, `note`, and `amount`. |

### refunds

A read-only record of refunds issued against the invoice.

| Field           | Type   | Description                                                                                              |
| --------------- | ------ | -------------------------------------------------------------------------------------------------------- |
| `refund_amount` | object | The total amount refunded so far. Contains `currency_code` and `value`.                                  |
| `transactions`  | array  | An array of individual refund records. Each contains `refund_id`, `method`, `refund_date`, and `amount`. |

<CardGroup>
  <Card title="Quick start using Invoicing API" href="/growth/grow-business/invoicing/quickstart-api">
    Create and send your first invoice using the PayPal Invoicing API.
  </Card>

  <Card title="Reference" href="/reference/api/rest/invoices/list-invoices">
    Explore the full schema definitions and interactive examples for the PayPal Invoicing API.
  </Card>
</CardGroup>


# Invoice lifecycle and status flow
Source: https://docs.paypal.ai/growth/grow-business/invoicing/lifecycle



PayPal Invoicing defines a set of statuses that represent an invoice's lifecycle. Most invoices follow a simple flow: **Draft** → **Due** → **Paid** (or **Cancelled**). An invoice starts as a draft, is sent to request payment, and finishes as paid or canceled, depending on the result.

## Invoice statuses

The invoice status determines how the invoice should be interpreted and what actions are allowed at any given point.

| UI status          | API status                         | Description and possible actions                                                                                                                                                                                | Next possible status                                                                         |
| ------------------ | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Draft              | `DRAFT`                            | All invoices start in draft status. The invoice is created but not sent. It is fully editable and invisible to the payer.                                                                                       | **Due**, **Scheduled**, **Overdue** (after the due date), **Marked as Paid**, or **Deleted** |
| Due                | `SENT` or `UNPAID`                 | The invoice is payable. <br />- `SENT`: The invoice is sent to the customer’s registered email address through the invoicing UI. <br />- `UNPAID`: The invoice is shared through a link or QR code.             | **Overdue** (after the due date), **Paid**, **Partially Paid**, or **Canceled**              |
| Overdue            | `SENT` or `UNPAID`                 | The invoice is payable and past due.<br />- `SENT`: The invoice is sent to the customer’s registered email address through the invoicing UI. <br />- `UNPAID`: The invoice is shared through a link or QR code. | **Paid**, **Partially Paid**, or **Canceled**                                                |
| Scheduled          | `SCHEDULED`                        | The invoice is scheduled for a future send date. The invoice is fully editable and invisible to the payer.                                                                                                      | **Due** (on the scheduled date), **Overdue** (after the due date), or **Deleted**            |
| Partially Paid     | `PARTIALLY_PAID`                   | Partially paid with an outstanding balance.                                                                                                                                                                     | **Paid** when the remaining balance is collected                                             |
| Paid               | `PAID` or `MARKED_AS_PAID`         | - `PAID`: The invoice is fully paid and settled, and is no longer payable. <br />-`MARKED_AS_PAID`: The invoice is manually marked as paid to reflect an external payment for reconciliation.                   | **Partially Refunded**, **Marked as Refunded** or **Refunded**, if you issue a refund        |
| Payment Pending    | `PAYMENT_PENDING`                  | Payment is in progress but not yet completed.                                                                                                                                                                   | **Paid**, **Partially Paid**                                                                 |
| Canceled           | `CANCELLED` or `AUTO_CANCELLED`    | - `CANCELLED`: The invoice is canceled, no longer payable, and retained for audit and reference. <br />- `AUTO_CANCELLED`: The invoice is automatically cancelled.                                              | No further transitions allowed                                                               |
| Partially Refunded | `PARTIALLY_REFUNDED`               | The invoice has been partially refunded, so some but not all of the original payment has been returned.                                                                                                         | No further transitions allowed                                                               |
| Refunded           | `REFUNDED` or `MARKED_AS_REFUNDED` | - `REFUNDED`: The invoice is fully refunded. <br />- `MARKED_AS_REFUNDED`: The invoice is manually marked as refunded to show that the refund was handled outside PayPal and is used for manual reconciliation. | No further transitions allowed                                                               |


# Overview
Source: https://docs.paypal.ai/growth/grow-business/invoicing/overview



PayPal Invoicing lets merchants and partners create and send itemized invoices and get paid through a secure PayPal payment page, without building their own payment flow. Customers can pay using PayPal, major credit and debit cards, and other eligible payment methods, often without needing a PayPal account, depending on regional availability. Merchants can share invoices via a secure URL, merchant-branded email, or scannable QR code, and configure automatic payment reminders.

### Invoicing vs Payment Link

Use the following table to compare PayPal’s Invoicing and [Payment Links](/payments/pay-links-buttons), and choose the option that best matches your needs.

|                                                                                            | Invoicing                                                                             | Payment Links                                                             |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Description                                                                                | Use Invoicing to collect one-time or recurring payments from a specific customer      | Use Payment Links to sell a product, service, or accept a donation or tip |
| Customer                                                                                   | Specific individual or business                                                       | Anyone with the link                                                      |
| Reusability                                                                                | One invoice per transaction                                                           | Reuse the same link multiple times                                        |
| Integration options                                                                        | Business Dashboard or API                                                             | Business Dashboard or API                                                 |
| Sharing options                                                                            | Email invoice, share hosted invoice link, or provide a QR code that opens the invoice | Share link through email, SMS, or social channels                         |
| Customization                                                                              | Invoice branding and business details.                                                | Limited checkout customization                                            |
| Payment methods                                                                            | PayPal, Pay Later, Venmo, Debit or Credit Cards, Apple Pay, and Pay by Bank (ACH)     | PayPal, cards, and eligible local methods                                 |
| Recurring payments                                                                         | One-time invoices                                                                     | One-time payments only                                                    |
| Collection tools                                                                           | Invoice reminders and status tracking                                                 | Not supported                                                             |
| Customers can choose what to pay                                                           | ❌                                                                                     | ✅                                                                         |
| Hosted payment page                                                                        | ✅                                                                                     | ✅                                                                         |
| Partial payments                                                                           | ✅                                                                                     | ❌                                                                         |
| Discounts                                                                                  | ✅                                                                                     | ✅                                                                         |
| Taxes                                                                                      | ✅                                                                                     | ✅                                                                         |
| [PCI compliance handling](https://www.paypal.com/us/brc/article/pci-dss-compliance-basics) | ✅                                                                                     | ✅                                                                         |

<Columns>
  <Card title="How Invoicing works" href="/growth/grow-business/invoicing/lifecycle">
    Learn what happens after you create and send an invoice, including how customers pay, what you can change along the way, and how to track the final outcome.
  </Card>

  <Card title="Choose between Invoicing solutions" href="/growth/grow-business/invoicing/choose-solution">
    Decide between using the PayPal dashboard or the Invoicing API by comparing setup effort, automation needs, invoice volume, and how invoices are created and managed.
  </Card>

  <Card title="Quick start using Dashboard" href="/growth/grow-business/invoicing/quickstart">
    Create and send an invoice from your Dashboard using just the essential fields—no code required.
  </Card>

  <Card title="Quick start using Invoicing API" href="/growth/grow-business/invoicing/quickstart-api">
    The Invoicing REST API lets you to create, update, send, and manage invoices programmatically from your backend systems.
  </Card>
</Columns>


# Quick start using Dashboard
Source: https://docs.paypal.ai/growth/grow-business/invoicing/quickstart



Use this guide to create and send an invoice from the [PayPal Business Dashboard](https://www.paypal.com/mep/dashboard), using only commonly used and required fields—no code required.

## Prerequisites

* Create a [PayPal Business account](https://www.paypal.com/business/open-business-account).
* (Optional) Use a test email you can access, not your PayPal business email.

## Create and send an invoice

1. Log in to your PayPal Business account.
2. Select **Create** > **Invoice**.
3. Fill out the customer details. An email is required to send an invoice to customer’s email address.
4. In the **Items** section, select **New Item**​ to add a product or service.
5. Select **Amount only** and add the item details. For example, set **Name** to “Consulting Services”, and **Amount** to `100.00`.
6. Select **Add**.
7. Review the invoice details, confirm that the invoice total is calculated automatically from your line items, and ensure that the customer email address is correct.
8. Select the **Preview** button to review the invoice and verify the customer, items, and total.​
9. Select **Send** to finalize and submit this invoice.
10. Select **Done** to close the invoice preview.


# Quick start using Invoicing API
Source: https://docs.paypal.ai/growth/grow-business/invoicing/quickstart-api



PayPal Invoicing API helps you create, update, send, and manage invoices programmatically from your backend systems.

This quick start is for developers who want a minimal, end-to-end example in a sandbox account and need to see the core create-and-send flow with as little setup as possible. You’ll use the PayPal Invoicing REST API to create a draft invoice in your sandbox account, send it to a test customer, and verify that the invoice appears in your sandbox business account.

## Prerequisites

* [PayPal business account](https://www.paypal.com/business/open-business-account?_ga=2.49411041.673139926.1760916697-1259758161.1760473483) with Invoicing enabled.
* Obtain your sandbox credentials and access token. Refer to [Get Started with PayPal REST APIs](/developer/how-to/api/get-started) for more information.
* (Optional) Use a test email you can access, not your PayPal business email.

For the complete API reference, including full schema definitions and interactive examples, see the [Invoicing API Reference](/reference/api/rest/invoices/list-invoices/).

## What you'll build

After completing this quick start, you will have:

* Created a draft invoice in your sandbox account
* Sent the invoice to a sandbox customer email address
* Confirmed the invoice status has changed to `UNPAID`

## Flow summary

1. Your server sends a `POST` request to create a draft invoice.
2. PayPal creates the invoice resource and returns an invoice ID.
3. Your server sends a `POST` request to send the invoice.
4. PayPal delivers the invoice to the recipient and updates the status.
5. You verify the invoice appears as `UNPAID` in your sandbox account.

## Quick start

### Step 1: Get your token

Open the dashboard, then create or select an app. Copy the **Client ID** and **Secret**. Use these credentials to generate an access token, and include that token in the `Authorization` header for every request.

> **Note:** Replace `CLIENT_ID` and `CLIENT_SECRET` with your sandbox app credentials from the dashboard.

```bash theme={null}
curl -X POST https://api-m.sandbox.paypal.com/v1/oauth2/token \
  -H "Accept: application/json" \
  -H "Accept-Language: en_US" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d "grant_type=client_credentials"
```

#### Expected result

* A successful token request returns the status `200 OK`.
* Copy the `access_token` value from the response body. You'll use this value in Steps 2 and 3.

### Step 2: Create a draft invoice

Create a draft invoice in a single API call. The invoice is not visible to your customer yet. This step generates the invoice with all required details, such as customer, items, and amount, before sending to the customer. The invoice workflow is: Draft → Sent → Viewed → Paid (or Cancelled/Overdue).

This example creates a draft invoice. Save the returned `id`, then call the send invoice endpoint when you're ready to request payment.

> **Note:** Replace `ACCESS_TOKEN` with your token from Step 1, and replace `customer@example.com` with your sandbox personal account email.

```bash [expandable] theme={null}
curl -X POST https://api-m.sandbox.paypal.com/v2/invoicing/invoices \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "detail": {
      "currency_code": "USD",
      "note": "Thanks for your business"
    },
    "invoicer": {
      "name": {
        "given_name": "Jane",
        "surname": "Doe"
      }
    },
    "primary_recipients": [
      {
        "billing_info": {
          "email_address": "customer@example.com"
        }
      }
    ],
    "items": [
      {
        "name": "Website design",
        "quantity": "1",
        "unit_amount": {
          "currency_code": "USD",
          "value": "500.00"
        }
      }
    ]
  }'
```

#### Expected result

* A successful request returns the status `201 Created`.
* The response body contains an `href` link with your invoice ID (`INV2-XXXX-XXXX-XXXX-XXXX`).
* The invoice appears in your sandbox account with `Draft` status.
* The invoice is not yet visible to the customer.

### Step 3: Send the invoice

In your sandbox account, send the draft invoice you created in the previous step. This moves the invoice from `DRAFT` to `SENT` status, and PayPal sends a secure payment link in the email to your customer. Use the `id` from step 2 and pass it as the `invoice_id` path parameter. To change details in the sent invoice, update the specific details using the `PUT` method and `send_to_recipient: true` to notify the customer. After you send an invoice, you can’t delete it. You can only cancel it to mark it as no longer active.

```bash theme={null}
curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/invoices/{invoice_id}/send \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "send_to_recipient": true,
    "send_to_invoicer": true
  }'
```

#### Expected result

* A successful request returns the status `200 OK`.
* The invoice status changes to `UNPAID` in your sandbox account.
* PayPal sends the invoice to the customer email address provided in Step 2.
* The customer receives a payment link to pay through PayPal's hosted payment page.

## Verify it works

You should see:

* Invoice appears in your sandbox PayPal business account under **Invoicing**.
* Invoice status shows as `UNPAID`.
* The customer email address you provided has received a payment notification.
* The invoice ID returned in Step 2 matches the invoice visible in the dashboard.

If verification fails, see [Troubleshooting](/growth/grow-business/invoicing/troubleshooting).

## See also

* [Invoicing API reference](/reference/api/rest/invoices/list-invoices/) for full operation and schema reference.


# Reference
Source: https://docs.paypal.ai/growth/grow-business/invoicing/reference



Use the PayPal Invoicing API to create, send, and manage invoices programmatically. This page covers all endpoints, request parameters, response objects, and error codes. For full schema definitions and interactive examples, see the [Invoicing API reference](/reference/api/rest/invoices/list-invoices).

## Invoice endpoints

The following endpoints cover the full invoice lifecycle, from creating a draft to sending, updating, recording payments, and canceling.

### `POST` Create draft invoice

Creates a draft invoice. The customer isn't notified until you call `POST /v2/invoicing/invoices/{id}/send`. Include an `items` array and merchant information in the `invoicer` object.

A successful request returns HTTP 201 Created and a PayPal-assigned invoice `id`. Save this ID because you'll need it for all subsequent operations, including sending, updating, recording payments, and generating QR codes.

> **Note**: The merchant account must be in good standing with PayPal. For partner integrations acting on behalf of a merchant, include the `PayPal-Auth-Assertion` header.

### `POST` Send invoice

Sends or schedules an invoice to be delivered to the customer, depending on the invoice issue date:

* If the issue date is today or in the past, PayPal sends the invoice immediately and changes the status to `SENT`.
* If the issue date is in the future, PayPal schedules and sends the invoice automatically on that date.

Set `send_to_recipient: false` to move the invoice to payable state without emailing the customer. This is useful when sharing the payment link yourself or generating a QR code. Set `send_to_invoicer: false` to suppress the merchant copy of the notification.

**Notes:**

* Resending an already-sent invoice has no effect.
* To notify the customer of an invoice update, update the invoice and set `send_to_recipient: true`.

### `GET` Show invoice details

Returns the full invoice object for a given invoice ID, including current status, line items, recipient information, payment and refund history, and HATEOAS links for available next actions. Use this to check invoice state, retrieve the customer-facing payment URL (`detail.metadata.recipient_view_url`), or verify recorded payments.

### `POST` Search for invoices

Searches for invoices matching multiple criteria simultaneously. All specified criteria must match. Supports filtering by recipient email, invoice status, date range, amount range, currency, reference number, memo, and item description.

Use this endpoint when you need to combine multiple filters that aren't available as query parameters on `GET /v2/invoicing/invoices`.

### `PUT` Fully update invoice

Fully replaces an invoice by ID. The request body must include the complete invoice object, and any fields omitted are cleared. To safely update a single field, first retrieve the current invoice with `GET /v2/invoicing/invoices/{id}`, modify the required fields, then resubmit the full object.

> **Note**: The recipient (`primary_recipients`) can only be changed twice within a 72-hour window.

### `DELETE` Delete invoice

Permanently deletes a draft or scheduled invoice by ID. For sent invoices, use `POST /v2/invoicing/invoices/{id}/cancel` instead. You can't recover or query the invoice after deletion, but you can reuse the invoice number.

### `POST` Cancel sent invoice

Cancels a sent invoice and changes its status to `CANCELLED`. For invoices that were never sent, use `DELETE /v2/invoicing/invoices/{id}` instead. PayPal retains canceled invoices for record-keeping, and you can still query them. Optionally sends cancellation notifications to the customer, merchant, and CC recipients.

### `POST` Send invoice reminder

Sends a payment reminder email to the customer for an unpaid invoice. Use this to follow up on overdue invoices or prompt payment before the due date.

**Limit:** You can send up to 2 reminders per invoice per day.

### `POST` Record external payment

Records an offline payment against an invoice, for example, cash, check, bank transfer, or wire payment received outside of PayPal. PayPal updates the invoice status to `MARKED_AS_PAID` if the full balance is covered, or `PARTIALLY_PAID` if a partial amount is recorded.

> **Note**: Payments made through the PayPal-hosted invoice page are recorded automatically. Only use this endpoint for payments received through other channels.

### `DELETE` Delete external payment

Deletes a previously recorded offline payment from an invoice. Use this to correct a payment entry recorded in error via `POST /v2/invoicing/invoices/{id}/payments`. Doesn't affect payments processed through PayPal's hosted payment page.

### `POST` Record refund for invoice

Records an offline refund against a paid invoice, for example, a refund issued through cash, check, or bank transfer outside of PayPal. Updates the invoice status to `MARKED_AS_REFUNDED` if fully refunded, or `PARTIALLY_REFUNDED` if a partial amount is recorded.

> **Note**: For refunds on payments processed through PayPal, use the Payments Refund API instead.

### `DELETE` Delete external refund

Deletes a previously recorded offline refund from an invoice. Use this to correct a refund entry recorded in error through `POST /v2/invoicing/invoices/{id}/refunds`. Doesn't affect refunds processed through PayPal.

### `POST` Generate invoice number

Generates the next sequential invoice number for the authenticated merchant, incrementing from the last used number and preserving any prefix or suffix pattern. For example, the next number after `INVOICE-1234` is `INVOICE-1235`.

Use this when you want PayPal to automatically manage invoice numbering. To use your own reference system, such as an ERP or accounting platform order ID, pass a custom `invoice_number` directly in the create draft invoice request instead.

### `POST` Generate QR code

Generates a Base64-encoded PNG QR code for a sent invoice. Add it to a paper or PDF invoice — when a customer scans it with a mobile device they are redirected to a PayPal-hosted payment page to pay using PayPal or card.

The invoice must be in `SENT` status before generating a QR code. To move an invoice to payable state without emailing the customer, set `send_to_recipient: false` in the send invoice request.

## Template endpoints

The following endpoints let you create and manage reusable invoice templates.

### `POST` Create template

Creates a reusable invoice template that pre-populates fields — such as merchant information, line items, payment terms, and tax configuration — when creating new invoices. Templates reduce repetitive data entry for merchants who regularly send the same invoice type.

To apply a template when creating an invoice, pass the `template_id` in the `configuration` object of `POST /v2/invoicing/invoices`. Merchants can create up to 50 templates.

### `GET` List templates

Returns a list of merchant-created invoice templates, including associated business information such as emails, addresses, and phone numbers from the merchant's PayPal profile. Use the returned `template_id` when creating invoices to pre-populate fields from a saved configuration.

### `GET` Show template details

Returns the full template object for a given template ID, including all configured fields, display settings, line item defaults, and payment configuration. Retrieve this before a full update to avoid unintentionally clearing fields.

### `PUT` Fully update template

Fully replaces an invoice template by ID. The request body must include the complete template object — fields omitted will be cleared. Retrieve the current template with `GET /v2/invoicing/templates/{id}` before updating to avoid unintended data loss.

Updates to a template don't affect invoices previously created from it.

### `DELETE` Delete template

Permanently deletes an invoice template by ID. Existing invoices created from this template aren't affected. You can't delete standard PayPal-provided system templates.

<CardGroup>
  <Card title="Quick start using Invoicing API" href="/growth/grow-business/invoicing/quickstart-api">
    Create and send your first invoice using the PayPal Invoicing API.
  </Card>

  <Card title="Use cases" href="/growth/grow-business/invoicing/use-cases">
    Explore common invoicing scenarios and how to implement them.
  </Card>
</CardGroup>


# Templates
Source: https://docs.paypal.ai/growth/grow-business/invoicing/templates



Templates let you save reusable invoice details such as your business information, standard line items, payment terms, and display preferences so you don't have to repeat them every time you create an invoice. You can create up to 50 templates per merchant account. Every account starts with three PayPal system templates pre-optimized for `QUANTITY`, `HOURS`, and `AMOUNT` billing.

## Templates API

Templates are managed through five endpoints covering the full create, read, update, and delete lifecycle. Use `POST` to create a new template, `GET` to retrieve either a single template by ID or your full list, `PUT` to fully update an existing template, and `DELETE` to remove one. All template endpoints are scoped to `/v2/invoicing/templates` and require a valid `Bearer` token. For the complete request and response schemas, see the [Invoicing API reference](/reference/api/rest/invoices/list-invoices).

| Method   | Endpoint                                | Description                                                                                                                           |
| -------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `POST`   | `/v2/invoicing/templates`               | Create a new template.                                                                                                                |
| `GET`    | `/v2/invoicing/templates`               | List all templates. Use `?fields=all` for full details or `?fields=none` for name, ID, and default flag only.                         |
| `GET`    | `/v2/invoicing/templates/{template_id}` | Show details for a single template. Use `@default` as the ID to retrieve the current default template.                                |
| `PUT`    | `/v2/invoicing/templates/{template_id}` | Fully update a template by ID. Doesn't support partial updates, so you'll need to include the complete template object.               |
| `DELETE` | `/v2/invoicing/templates/{template_id}` | Delete a template by ID. Returns `HTTP 204 No Content`. Can't be used on PayPal system templates where `standard_template` is `true`. |

## Template object

The following fields make up the template object.

| Field               | Type    | Required  | Description                                                                                                                                             |
| ------------------- | ------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                | string  | Read-only | The PayPal-generated template ID (`TEMP-XXXXXXXXXXXX`).                                                                                                 |
| `name`              | string  | Required  | A merchant-defined name for the template. Shown in the dashboard and template list.                                                                     |
| `default_template`  | boolean | Optional  | If `true`, this template is used as the default when creating invoices. Only one template can be the default at a time. Default: `false`.               |
| `template_info`     | object  | Optional  | The invoice details are pre-populated by this template. See [**template\_info**](#template-info) for more information.                                  |
| `settings`          | array   | Optional  | Display rules that control which fields are shown or hidden on invoices created from this template. See [**settings**](#settings) for more information. |
| `unit_of_measure`   | string  | Optional  | The unit of measure for line items. Values: `QUANTITY`, `HOURS`, `AMOUNT`. Default: `QUANTITY`.                                                         |
| `standard_template` | boolean | Read-only | If `true`, this is a PayPal system template and can't be deleted.                                                                                       |
| `links`             | array   | Read-only | HATEOAS links for available actions on the template, for example, `self`, `delete`, `replace`.                                                          |

### template\_info

The invoice data stored in the template shares the same structure as the invoice object. See the most commonly used fields.

| Field                | Type   | Description                                                                                                                            |
| -------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `detail`             | object | Default invoice detail including `currency_code`, `note`, `terms_and_conditions`, `memo`, `reference`, and `attachments`.              |
| `invoicer`           | object | The merchant's business information, including name, address, email, phone, logo URL, and tax ID.                                      |
| `primary_recipients` | array  | Default recipient billing and shipping information.                                                                                    |
| `items`              | array  | Default line items with name, quantity, unit amount, tax, and unit of measure.                                                         |
| `configuration`      | object | Default invoice configuration including `allow_tip`, `tax_calculated_after_discount`, `tax_inclusive`, and `partial_payment` settings. |
| `amount`             | object | Default amount breakdown including shipping, custom charges, and discount.                                                             |

### settings

An array of display rules controlling field visibility on invoices created from this template. Each entry contains a `field_name` and a `display_preference` object with a single `hidden` boolean. Set `hidden: true` to hide the field, or `hidden: false` to show it.

Supported `field_name` values:

| Value               | Description                                         |
| ------------------- | --------------------------------------------------- |
| `items.date`        | The date column on line items.                      |
| `items.description` | The description column on line items.               |
| `items.discount`    | The per-item discount field.                        |
| `items.tax`         | The per-item tax field.                             |
| `discount`          | The invoice-level discount field.                   |
| `shipping`          | The shipping charge field.                          |
| `custom`            | The custom charge field, for example, packing fees. |

## Create a template

Creates a new invoice template. A successful request returns `HTTP 201 Created` and the template object if you set `Prefer: return=representation`.

### Request

```bash theme={null}
curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/templates \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -d '{
    "name": "Standard Services Invoice",
    "default_template": true,
    "unit_of_measure": "HOURS",
    "template_info": {
      "detail": {
        "currency_code": "USD",
        "note": "Thank you for your business.",
        "terms_and_conditions": "Payment due within 30 days.",
        "memo": "Internal reference only"
      },
      "invoicer": {
        "name": {
          "given_name": "David",
          "surname": "Larusso"
        },
        "address": {
          "address_line_1": "1234 First Street",
          "admin_area_2": "Anytown",
          "admin_area_1": "CA",
          "postal_code": "98765",
          "country_code": "US"
        },
        "email_address": "merchant@example.com",
        "logo_url": "https://example.com/logo.PNG"
      },
      "items": [
        {
          "name": "Consulting",
          "description": "Hourly consulting services.",
          "quantity": "1",
          "unit_amount": {
            "currency_code": "USD",
            "value": "150.00"
          },
          "tax": {
            "name": "Sales Tax",
            "percent": "7.25"
          },
          "unit_of_measure": "HOURS"
        }
      ],
      "configuration": {
        "tax_calculated_after_discount": true,
        "tax_inclusive": false,
        "allow_tip": false
      }
    },
    "settings": [
      {
        "field_name": "items.date",
        "display_preference": { "hidden": false }
      },
      {
        "field_name": "custom",
        "display_preference": { "hidden": true }
      },
      {
        "field_name": "shipping",
        "display_preference": { "hidden": true }
      }
    ]
  }'
```

### Response

```json theme={null}
{
  "id": "TEMP-19V05281TU309413B",
  "name": "Standard Services Invoice",
  "default_template": true,
  "unit_of_measure": "HOURS",
  "standard_template": false,
  "links": [
    {
      "href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
      "rel": "delete",
      "method": "DELETE"
    },
    {
      "href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
      "rel": "replace",
      "method": "PUT"
    }
  ]
}
```

Save the returned `id` to reference this template when listing, updating, or associating it with an invoice through `configuration.template_id`.

<CardGroup>
  <Card title="Quick start using Invoicing API" href="/growth/grow-business/invoicing/quickstart-api">
    Create and send your first invoice using the PayPal Invoicing API.
  </Card>

  <Card title="Use cases" href="/growth/grow-business/invoicing/use-cases">
    See how templates fit into common invoicing workflows.
  </Card>

  <Card title="Reference" href="/reference/api/rest/invoices/list-invoices">
    Explore the full schema for the template object and all other Invoicing API objects.
  </Card>
</CardGroup>


# Test and go live
Source: https://docs.paypal.ai/growth/grow-business/invoicing/test-go-live



Use test values to simulate error responses with the PayPal Invoicing API and verify that your application handles different scenarios correctly.

## Prerequisites

* Get your [access token](https://developer.paypal.com/api/rest/authentication/).
* Use [Postman](https://identity.getpostman.com/login?continue=https%3A%2F%2Fgo.postman.co%2Ffork%3Fcollection%3D19024122-92a85d0e-51e7-47da-9f83-c45dcb1cdf24%26referrer%3Dhttps%253A%252F%252Fdeveloper.paypal.com%252Fapi%252Frest%252F%26token%3Da88e6154-b499-46fd-bf83-f99a6267dedb%26key%3DeyJhbGciOiJBMjU2Q1RSIiwiZXh0Ijp0cnVlLCJrIjoiT3BwM0EzTVU4b0ZBM1daTW8zZmlPczd4dEdOSUpGNkxwR3JXQXV3LWxrYyIsImtleV9vcHMiOlsiZW5jcnlwdCIsImRlY3J5cHQiXSwia3R5Ijoib2N0In0%253D%26counter%3DbbhMUbsoFAUBKcDlXqGK3Q%253D%253D%26traceId%3D60b5403d-d4d6-497c-ac61-c6fb7e6dcdf0) to test the PayPal APIs.
* Use the [sandbox environment](https://api-m.sandbox.paypal.com).

## Simulation methods

You can simulate responses in two ways: [JSON pointer method](#json-pointer-method) or the [path parameter method](#path-parameter-method).

### JSON pointer method

| Request location   | Test value  | Simulated response  |
| :----------------- | :---------- | :------------------ |
| `detail.reference` | `ERRINV002` | `PERMISSION_DENIED` |

The following sample code shows a simulated request with a test value and the sandbox response.

#### Request \[expandable]

```bash theme={null}
curl -X POST \
  https://api-m.sandbox.paypal.com/v2/invoicing/invoices \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
          "detail":
          {
                    "reference": "ERRINV002"
          }
}'
```

#### Response

```json [expandable] theme={null}
{
    "localizedMessage": "No permission for the requested operation. ",
    "name": "PERMISSION_DENIED",
    "message": "No permission for the requested operation. ",
    "details": [
        {
            "issue": "No permission for the requested operation. "
        }
    ],
    "information_link": "https://developer.paypal.com/docs/archive/permissions-service/",
    "debug_id": "6e07326c281c4"
}
```

### Path parameter method

Use test value in the request URI. This simulates a response.

| Test value                                        | Simulated response  |
| :------------------------------------------------ | :------------------ |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0010` | `INVOICE_NOT_FOUND` |

The following sample code shows a simulated request with a test value and the sandbox response.

#### Request

```bash theme={null}
curl -X GET \
  https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0010 \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -H 'Content-Type: application/json'
```

#### Response

```json [expandable] theme={null}
{
    "name": "RESOURCE_NOT_FOUND",
    "message": "The specified resource does not exist.",
    "debug_id": "98b2b9d2d89cb",
    "links": [
        {
            "href": "https://developer.paypal.com/docs/api/invoicing/#errors",
            "rel": "information_link"
        }
    ]
}
```

## Test values

> **Note**: Test values are case sensitive.

The following test values simulate different responses for each Invoicing API operation. Each operation shows where to insert the test value and the response you can expect.

### Generate invoice number

Use the path parameter in the request URI at `POST /v2/invoicing/invoices/generate-next-invoice-number` to simulate the following error responses.

| Test value  | Simulated response      |
| :---------- | :---------------------- |
| `ERRINV066` | `INTERNAL_SERVER_ERROR` |
| `ERRINV067` | `PERMISSION_DENIED`     |

### Create invoices

Use the JSON pointer method at
`POST /v2/invoicing/invoices/` to simulate the following error responses.

| Request location   | Test value  | Simulated response                 |
| :----------------- | :---------- | :--------------------------------- |
| `detail.reference` | `ERRINV001` | `INTERNAL_SERVER_ERROR`            |
| `detail.reference` | `ERRINV002` | `PERMISSION_DENIED`                |
| `detail.reference` | `ERRINV003` | `UNSUPPORTED_MEDIA_TYPE`           |
| `detail.reference` | `ERRINV004` | `VALIDATION_ERROR_EMPTY_BODY`      |
| `detail.reference` | `ERRINV005` | `INVALID_REQUEST_GENERIC`          |
| `detail.reference` | `ERRINV006` | `INVALID_REQUEST_SCHEMA_VIOLATION` |

### Get invoice

Use the path parameter in the request URI at `GET /v2/invoicing/invoices/{invoice_id}` to simulate the following error responses.

| Test value                                        | Simulated response      |
| :------------------------------------------------ | :---------------------- |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0007` | `INTERNAL_SERVER_ERROR` |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0008` | `PERMISSION_DENIED`     |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0009` | `UNAUTHORIZED_ACCESS`   |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0010` | `INVOICE_NOT_FOUND`     |

### Delete invoice

Use the path parameter in the request URI to simulate the following response at `DELETE /v2/invoicing/invoices/{invoice_id}`.

#### Success

| Test value                                        | Simulated response               |
| :------------------------------------------------ | :------------------------------- |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0059` | `PAYLOAD WITH 200 RESPONSE CODE` |

#### Error

| Test value                                        | Simulated response      |
| :------------------------------------------------ | :---------------------- |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0055` | `INTERNAL_SERVER_ERROR` |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0056` | `PERMISSION_DENIED`     |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0057` | `UNAUTHORIZED_ACCESS`   |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0058` | `INVOICE_NOT_FOUND`     |

### Update the invoice

Use the path parameter in the request URI to simulate the following error response at `PUT /v2/invoicing/invoices/{invoice_id}`.

| Test value                                        | Simulated response                 |
| :------------------------------------------------ | :--------------------------------- |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0060` | `INTERNAL_SERVER_ERROR`            |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0061` | `PERMISSION_DENIED`                |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0062` | `UNSUPPORTED_MEDIA_TYPE`           |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0063` | `VALIDATION_ERROR_EMPTY_BODY`      |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0064` | `INVALID_REQUEST_GENERIC`          |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0065` | `INVALID_REQUEST_SCHEMA_VIOLATION` |

### Cancel a sent invoice

Use the path parameter in the request URI to simulate the following response at `POST /v2/invoicing/invoices/{invoice_id}/cancel`.

#### Success

| Test value                                               | Simulated response               |
| :------------------------------------------------------- | :------------------------------- |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0029/cancel` | `PAYLOAD WITH 204 RESPONSE CODE` |

#### Error

| Test value                                               | Simulated response                   |
| :------------------------------------------------------- | :----------------------------------- |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0024/cancel` | `INTERNAL_SERVER_ERROR`              |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0025/cancel` | `PERMISSION_DENIED`                  |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0026/cancel` | `UNAUTHORIZED_ACCESS`                |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0027/cancel` | `INVOICE_NOT_FOUND`                  |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0028/cancel` | `CANT_CANCEL_INVOICE_IN_DRAFT_STATE` |

### Record payment for invoice

Use the path parameter in the request URI to simulate the following response at `POST /v2/invoicing/invoices/{invoice_id}/payments`.

#### Success

| Test value                                                 | Simulated response               |
| :--------------------------------------------------------- | :------------------------------- |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0037/payments` | `PAYLOAD WITH 200 RESPONSE CODE` |

#### Error

| Test value                                                 | Simulated response                     |
| :--------------------------------------------------------- | :------------------------------------- |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0031/payments` | `INTERNAL_SERVER_ERROR`                |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0032/payments` | `PERMISSION_DENIED`                    |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0033/payments` | `UNAUTHORIZED_ACCESS`                  |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0034/payments` | `INVOICE_NOT_FOUND`                    |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0035/payments` | `CANT_PAY_AN_PAID_OR_CANCELED_INVOICE` |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0036/payments` | `CANT_PAY_MORE_THAN_INVOICE_AMOUNT`    |

### Delete payment

Use the path parameter in the request URI to simulate the following response at `DELETE /v2/invoicing/invoices/INV2-ABCD-1234-EFGH-5678/payments/{transaction_id}`.

#### Success

| Test value                                                                       | Simulated response               |
| :------------------------------------------------------------------------------- | :------------------------------- |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EFGH-5678/payments/EXT-ABCDEFGHERRINV042` | `PAYLOAD WITH 200 RESPONSE CODE` |

#### Error

| Test value                                                                       | Simulated response             |
| :------------------------------------------------------------------------------- | :----------------------------- |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EFGH-5678/payments/EXT-ABCDEFGHERRINV038` | `INTERNAL_SERVER_ERROR`        |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EFGH-5678/payments/EXT-ABCDEFGHERRINV039` | `PERMISSION_DENIED`            |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EFGH-5678/payments/EXT-ABCDEFGHERRINV040` | `UNAUTHORIZED_ACCESS`          |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EFGH-5678/payments/EXT-ABCDEFGHERRINV041` | `PAYMENT_OR_INVOICE_NOT_FOUND` |

### Record refund for invoice

Use the path parameter in the request URI to simulate the following response at `POST /v2/invoicing/invoices/{invoice_id}/refunds`:

#### Success

| Test value                                                | Simulated response               |
| :-------------------------------------------------------- | :------------------------------- |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0049/refunds` | `PAYLOAD WITH 200 RESPONSE CODE` |

#### Error

| Test value                                                | Simulated response                     |
| :-------------------------------------------------------- | :------------------------------------- |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0043/refunds` | `INTERNAL_SERVER_ERROR`                |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0044/refunds` | `PERMISSION_DENIED`                    |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0045/refunds` | `UNAUTHORIZED_ACCESS`                  |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0046/refunds` | `INVOICE_NOT_FOUND`                    |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0047/refunds` | `CANT_REFUND_A_CANCELED_INVOICE`       |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0048/refunds` | `CANT_REFUND_MORE_THAN_PAYMENT_AMOUNT` |

### Delete refund

Use the path parameter in the request URI to simulate the following response at `DELETE /v2/invoicing/invoices/{invoice_id}/refunds/{transaction_id}`.

#### Success

| Test value                                                                      | Simulated response               |
| :------------------------------------------------------------------------------ | :------------------------------- |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EFGH-5678/refunds/EXT-ABCDEFGHERRINV054` | `PAYLOAD WITH 200 RESPONSE CODE` |

#### Error

| Test value                                                                      | Simulated response            |
| :------------------------------------------------------------------------------ | :---------------------------- |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EFGH-5678/refunds/EXT-ABCDEFGHERRINV050` | `INTERNAL_SERVER_ERROR`       |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EFGH-5678/refunds/EXT-ABCDEFGHERRINV051` | `PERMISSION_DENIED`           |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EFGH-5678/refunds/EXT-ABCDEFGHERRINV052` | `UNAUTHORIZED_ACCESS`         |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EFGH-5678/refunds/EXT-ABCDEFGHERRINV053` | `REFUND_OR_INVOICE_NOT_FOUND` |

### Send invoice reminder

Use the path parameter in the request URI to simulate the following response at `POST /v2/invoicing/invoices/{invoice_id}/remind`.

#### Success

| Test value                                               | Simulated response               |
| :------------------------------------------------------- | :------------------------------- |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0023/remind` | `PAYLOAD WITH 200 RESPONSE CODE` |

#### Error

| Test value                                               | Simulated response                         |
| :------------------------------------------------------- | :----------------------------------------- |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0017/remind` | `INTERNAL_SERVER_ERROR`                    |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0018/remind` | `PERMISSION_DENIED`                        |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0019/remind` | `UNAUTHORIZED_ACCESS`                      |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0020/remind` | `INVOICE_NOT_FOUND`                        |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0021/remind` | `CANT_REMIND_INVOICE_IN_DRAFT_STATE`       |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0022/remind` | `CANT_REMIND_INVOICE_WITHOUT_BILLING_INFO` |

### Send invoice

Use the path parameter in the request URI to simulate the following response at `POST /v2/invoicing/invoices/{invoice_id}/send`.

#### Success

| Test value                                             | Simulated response               |
| :----------------------------------------------------- | :------------------------------- |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0016/send` | `PAYLOAD WITH 200 RESPONSE CODE` |

#### Error

| Test value                                             | Simulated response                |
| :----------------------------------------------------- | :-------------------------------- |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0011/send` | `INTERNAL_SERVER_ERROR`           |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0012/send` | `PERMISSION_DENIED`               |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0013/send` | `UNAUTHORIZED_ACCESS`             |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0014/send` | `INVOICE_NOT_FOUND`               |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0015/send` | `CANT_SEND_INVOICE_WITHOUT_EMAIL` |
| `/v2/invoicing/invoices/INV2-ABCD-1234-EINV-0030/send` | `CANT_SEND_ALREADY_SENT_INVOICE`  |

### Search invoices

Use the path parameter in the request URI to simulate the following error responses at `POST /v2/invoicing/search-invoices`.

| Test value  | Simulated response      |
| :---------- | :---------------------- |
| `ERRINV068` | `INTERNAL_SERVER_ERROR` |
| `ERRINV069` | `PERMISSION_DENIED`     |
| `ERRINV070` | `INVALID_REQUEST`       |


# Troubleshooting Invoicing API
Source: https://docs.paypal.ai/growth/grow-business/invoicing/troubleshooting



The PayPal Invoicing API returns specific error codes and messages to help you troubleshoot integration issues.

## Error response format

All Invoicing API errors follow this structure:

```json [expandable] theme={null}
{
    "name": "INVALID_REQUEST",
    "message": "Request is not well-formed, syntactically incorrect, or violates schema.",
    "details": [
    {
        "description": "Payment method is missing.",
        "field": "/method",
        "issue": "MISSING_REQUIRED_PARAMETER",
        "location": "body"
    }
    ],
    "links": [
    {
        "href": "https://developer.paypal.com/docs/limited-release/invoicing/#errors",
        "rel": "information_link"
    }
    ],
    "debug_id": "04228dda78114"
}
```

## API errors

PayPal returns HTTP `4XX` status codes if something passes in the request has an error. `5XX` status codes appear when something is wrong on our end with a server or service. For more information, see [Handling API responses when integrating with PayPal APIs](https://paypal.mintlify.app/developer/how-to/api/handling-api-responses#common-paypal-api-error-codes).

| HTTP code | Error name               | Message                                                    | Details                                                                        |
| :-------- | :----------------------- | :--------------------------------------------------------- | :----------------------------------------------------------------------------- |
| `400`     | `INVALID_REQUEST`        | Invalid request                                            | One or more validation errors have occurred.                                   |
| `401`     | `AUTHENTICATION_FAILURE` | Authorization error occurred                               | Authorization error occurred. Check your credentials.                          |
| `404`     | `RESOURCE_NOT_FOUND`     | Resource not found                                         | The resource requested is not found in the system.                             |
| `422`     | `UNPROCESSABLE_ENTITY`   | Invoicing business error                                   | A detailed error message is passed in the message field.                       |
| `429`     | `RATE_LIMIT_REACHED`     | Too many requests and user is blocked due to rate limiting | The rate limit for the user, application, or token exceeds a predefined value. |
| `500`     | `INTERNAL_SERVER_ERROR`  | Internal service error                                     | Resend the request at another time.                                            |

## Authorization errors

| HTTP code | Issue               | Message                                                                       | Common cause                                          | Affected fields           |
| :-------- | :------------------ | :---------------------------------------------------------------------------- | :---------------------------------------------------- | :------------------------ |
| `403`     | `NOT_AUTHORIZED`    | Authorization failed due to insufficient permissions                          | Invalid access token or account permissions           | `invoiceId`, `templateId` |
| `403`     | `PERMISSION_DENIED` | The requested invoice and template are not associated with the requested user | Accessing resources that don't belong to your account | `invoiceId`, `templateId` |

## Request validation errors

| Issue                        | Description                                                  | Affected fields                                           |
| :--------------------------- | :----------------------------------------------------------- | :-------------------------------------------------------- |
| `INVALID_STRING_LENGTH`      | Currency code must be 3 characters                           | `/detail/currency_code`, `/amount/currency_code`          |
| `INVALID_STRING_MAX_LENGTH`  | Field exceeds maximum character limit                        | `/detail/note`, `/items/0/name`, `/detail/invoice_number` |
| `INVALID_PARAMETER_SYNTAX`   | Invalid format of the dates, phone numbers, or country codes | `/detail/invoice_date`, `/detail/payment_term/due_date`   |
| `MISSING_REQUIRED_PARAMETER` | Required field is missing                                    | `/method`, `/amount/value`                                |

## Business logic errors

| Issue                                    | Description                                                             |
| :--------------------------------------- | :---------------------------------------------------------------------- |
| `INVOICE_ALREADY_SENT`                   | The system blocks sending any invoice that has already been sent.       |
| `CANT_SEND_INVOICE_WITHOUT_EMAIL`        | A recipient email address is required before an invoice can be sent.    |
| `CANT_CANCEL_INVOICE_IN_DRAFT_STATE`     | Cannot cancel an invoice that is in draft state.                        |
| `CANT_PAY_AN_PAID_OR_CANCELED_INVOICE`   | Cannot record a payment on an invoice that is already paid or canceled. |
| `PAYMENT_AMOUNT_GREATER_THAN_AMOUNT_DUE` | Payment amount cannot exceed the total amount due on the invoice.       |
| `CANT_REFUND_MORE_THAN_PAYMENT_AMOUNT`   | Cannot refund more than the amount of recorded payments.                |
| `INVOICE_CANNOT_BE_DELETED`              | Only draft, scheduled, or canceled invoices can be deleted.             |
| `INVOICE_NOT_FOUND`                      | Invoice with specified id does not exists.                              |

## Field validation limits

| Field                | Character limit |
| :------------------- | :-------------- |
| Invoice number       | 25              |
| Currency code        | 3               |
| Country code         | 2               |
| Email address        | 3–254           |
| Phone number         | 1–14 digits     |
| Item name            | 200             |
| Item description     | 1000            |
| Invoice note         | 4000            |
| Terms and conditions | 4000            |
| Reference field      | 120             |
| Logo URL             | 2000            |
| Website URL          | 2048            |


# Use cases
Source: https://docs.paypal.ai/growth/grow-business/invoicing/use-cases



Explore key ways to apply the PayPal Invoicing API in your billing and payment collection flows. See how different configuration options map to common business scenarios so you can choose the pattern that best fits your integration.

Select a use case that fits your integration:

* [Create a draft invoice with minimum required fields](#create-a-draft-invoice-with-minimum-required-fields)
* [Create a payment request linked to an external invoice](#create-a-payment-request-linked-to-an-external-invoice)
* [Create an hourly services invoice](#create-an-hourly-services-invoice)
* [Create an invoice for shippable goods](#create-an-invoice-for-shippable-goods)
* [Create an invoice for digital goods](#create-an-invoice-for-digital-goods)
* [Create a mixed billing invoice](#create-a-mixed-billing-invoice)

For more information, see the [API reference](/reference/api/rest/invoices/list-invoices).

## Prerequisites

* [PayPal business account](https://www.paypal.com/business/open-business-account?_ga=2.49411041.673139926.1760916697-1259758161.1760473483) with Invoicing enabled.
* Obtain your sandbox credentials and access token. Refer to [Get Started with PayPal REST APIs](https://docs.paypal.ai/developer/how-to/api/get-started) for more information.
* (Optional) Use a test email you can access, not your PayPal business email.

## Use cases

See how to create invoices that address common scenarios and requirements.

### Create a draft invoice with minimum required fields

This is a good starting point for merchants new to the API or developers testing an integration before adding complexity.

1. Call `POST /v2/invoicing/invoices` with minimal required fields.
2. Save the `id` from the `201 Created` response.
3. Call `POST /v2/invoicing/invoices/{id}/send` to deliver the invoice to the recipient.

| Field                           | Description                                                  |
| ------------------------------- | ------------------------------------------------------------ |
| `detail.invoice_number`         | Your reference number for the invoice.                       |
| `detail.currency_code`          | Currency applied to all monetary values.                     |
| `detail.payment_term.term_type` | When payment is due, such as `DUE_ON_RECEIPT`.               |
| `invoicer`                      | Sender name and email.                                       |
| `primary_recipients`            | Customer name and email.                                     |
| `items`                         | At least one line item with name, quantity, and unit amount. |

**Request**

```json [expandable] theme={null}
{
  "detail": {
    "invoice_number": "INV-001",
    "invoice_date": "2026-03-15",
    "currency_code": "USD",
    "payment_term": {
      "term_type": "DUE_ON_RECEIPT"
    }
  },
  "invoicer": {
    "name": {
      "given_name": "Alex",
      "surname": "Rivera"
    },
    "email_address": "alex@example.com",
    "business_name": "Rivera Consulting"
  },
  "primary_recipients": [
    {
      "billing_info": {
        "name": {
          "given_name": "Jamie",
          "surname": "Lee"
        },
        "email_address": "jamie.lee@example.com"
      }
    }
  ],
  "items": [
    {
      "name": "Consulting Services",
      "quantity": "1",
      "unit_amount": {
        "currency_code": "USD",
        "value": "500.00"
      },
      "unit_of_measure": "QUANTITY"
    }
  ]
}
```

A successful call returns HTTP `201 Created`. Save the returned `id` — you need it to send, update, or query the invoice.

> **Note:** This creates a `DRAFT` invoice. The customer isn't notified until you call `POST /v2/invoicing/invoices/{id}/send`.

### Create a payment request linked to an external invoice

This pattern is ideal for merchants using a enterprise resource planning (ERP) or accounting platforms like NetSuite, QuickBooks, or Xero who want to collect payment through PayPal without recreating the invoice. Pass the external reference via `invoice_number` or `detail.reference`, and optionally attach the original invoice PDF.

1. Create the invoice in your external system and capture the external invoice ID.
2. Call `POST /v2/invoicing/invoices` to create a PayPal payment request, passing the external invoice ID and optionally attaching the original invoice PDF.
3. Call `POST /v2/invoicing/invoices/{id}/send` to deliver the payment request to the customer.
4. The customer receives a PayPal-hosted payment link by email and pays using PayPal or a card.

| Field                               | Description                                                   |
| ----------------------------------- | ------------------------------------------------------------- |
| `items[].unit_of_measure: "AMOUNT"` | Flat-rate billing with no quantity or hourly breakdown.       |
| `attachments`                       | Attach the original invoice PDF for the customer's reference. |

**Request — External ID as `invoice_number`**

```json [expandable] theme={null}
{
  "detail": {
    "invoice_number": "NETSUITE-INV-78432",
    "invoice_date": "2026-03-15",
    "currency_code": "USD",
    "note": "Please use the link below to pay your outstanding invoice. The original invoice is attached for your reference.",
    "payment_term": {
      "term_type": "DUE_ON_RECEIPT"
    }
  },
  "invoicer": {
    "name": {
      "given_name": "Morgan",
      "surname": "Shaw"
    },
    "email_address": "billing@apexsupply.com",
    "business_name": "Apex Supply Co."
  },
  "primary_recipients": [
    {
      "billing_info": {
        "name": {
          "given_name": "Dana",
          "surname": "Patel"
        },
        "email_address": "dana.patel@clientcorp.com"
      }
    }
  ],
  "items": [
    {
      "name": "Invoice NETSUITE-INV-78432",
      "description": "Payment for goods and services per attached invoice.",
      "quantity": "1",
      "unit_amount": {
        "currency_code": "USD",
        "value": "3450.00"
      },
      "unit_of_measure": "AMOUNT"
    }
  ],
  "attachments": [
    {
      "name": "Invoice-NETSUITE-INV-78432.pdf",
      "url": "https://your-storage.example.com/invoices/NETSUITE-INV-78432.pdf"
    }
  ]
}
```

**Request — External ID as `detail.reference`**

```json [expandable] theme={null}
{
  "detail": {
    "invoice_number": "PAY-2026-00142",
    "reference": "NETSUITE-INV-78432",
    "invoice_date": "2026-03-15",
    "currency_code": "USD",
    "note": "Please use the link below to pay invoice NETSUITE-INV-78432. The original invoice is attached for your reference.",
    "payment_term": {
      "term_type": "DUE_ON_RECEIPT"
    }
  },
  "invoicer": {
    "name": {
      "given_name": "Morgan",
      "surname": "Shaw"
    },
    "email_address": "billing@apexsupply.com",
    "business_name": "Apex Supply Co."
  },
  "primary_recipients": [
    {
      "billing_info": {
        "name": {
          "given_name": "Dana",
          "surname": "Patel"
        },
        "email_address": "dana.patel@clientcorp.com"
      }
    }
  ],
  "items": [
    {
      "name": "Invoice NETSUITE-INV-78432",
      "description": "Payment for goods and services per attached invoice.",
      "quantity": "1",
      "unit_amount": {
        "currency_code": "USD",
        "value": "3450.00"
      },
      "unit_of_measure": "AMOUNT"
    }
  ],
  "attachments": [
    {
      "name": "Invoice-NETSUITE-INV-78432.pdf",
      "url": "https://your-storage.example.com/invoices/NETSUITE-INV-78432.pdf"
    }
  ]
}
```

**Notes**

* Use `unit_of_measure: "AMOUNT"` when billing a flat total with no quantity or hourly breakdown.
* The `attachments` array accepts publicly accessible URLs. The PDF must be reachable by PayPal's servers at the time you create the invoice.
* `detail.reference` is visible to the customer on the PayPal invoice page. This is useful for cross-referencing the external invoice number.
* `detail.memo` is a private field visible only to the invoicer. Use this for internal bookkeeping notes.

### Create an hourly services invoice

Create an hourly services invoice with `unit_of_measure: "HOURS"`, a client billing address, tip enabled, and partial payment configured for deposit workflows. This pattern works best for consultants, freelancers, photographers, and tradespeople billing for time and labor.

1. Confirm the scope, hours, and rate for completed service work.
2. Call `POST /v2/invoicing/invoices` with hourly or amount-based line items and the client's billing address. Don't include `shipping_info`.
3. Call `POST /v2/invoicing/invoices/{id}/send` to deliver the invoice to the client.
4. The client receives the invoice and pays with PayPal or card.

| Field                                       | Description                                                                  |
| ------------------------------------------- | ---------------------------------------------------------------------------- |
| `items[].unit_of_measure: "HOURS"`          | Renders quantity as hours worked and `unit_amount` as the hourly rate.       |
| `primary_recipients[].billing_info.address` | Client billing address; no `shipping_info` included.                         |
| `detail.payment_term.term_type`             | When payment is due, such as `NET_14` or `NET_30`.                           |
| `detail.note`                               | Project summary or message visible to the client.                            |
| `detail.term`                               | Formal payment terms and conditions.                                         |
| `configuration.allow_tip: true`             | Enables an optional tip or gratuity field on the PayPal-hosted payment page. |
| `configuration.partial_payment`             | Supports deposit or installment payment workflows.                           |

**Request**

```json [expandable] theme={null}
{
  "detail": {
    "invoice_number": "INV-2026-0089",
    "invoice_date": "2026-03-15",
    "currency_code": "USD",
    "note": "Thank you for working with us. Please don't hesitate to reach out with any questions.",
    "term": "Payment due within 14 days of invoice date. Late payments subject to a 1.5% monthly fee.",
    "payment_term": {
      "term_type": "NET_14"
    }
  },
  "invoicer": {
    "name": {
      "given_name": "Taylor",
      "surname": "Brooks"
    },
    "email_address": "taylor@brooksdesign.com",
    "business_name": "Brooks Design Studio",
    "phones": [
      {
        "country_code": "1",
        "national_number": "4155550192",
        "phone_type": "MOBILE"
      }
    ],
    "website": "https://brooksdesign.com"
  },
  "primary_recipients": [
    {
      "billing_info": {
        "name": {
          "given_name": "Jordan",
          "surname": "Kim"
        },
        "business_name": "Kim & Associates LLC",
        "email_address": "jordan@kimassociates.com",
        "address": {
          "address_line_1": "450 Market Street",
          "address_line_2": "Suite 800",
          "admin_area_2": "San Francisco",
          "admin_area_1": "CA",
          "postal_code": "94105",
          "country_code": "US"
        }
      }
    }
  ],
  "items": [
    {
      "name": "UX Design — Discovery & Research",
      "description": "User interviews, competitive analysis, journey mapping",
      "quantity": "12",
      "unit_amount": {
        "currency_code": "USD",
        "value": "150.00"
      },
      "unit_of_measure": "HOURS",
      "tax": {
        "name": "Sales Tax",
        "percent": "8.5"
      }
    },
    {
      "name": "UX Design — Wireframing & Prototyping",
      "description": "Low and high-fidelity wireframes, interactive prototype",
      "quantity": "18",
      "unit_amount": {
        "currency_code": "USD",
        "value": "150.00"
      },
      "unit_of_measure": "HOURS",
      "tax": {
        "name": "Sales Tax",
        "percent": "8.5"
      }
    }
  ],
  "configuration": {
    "allow_tip": true,
    "partial_payment": {
      "allow_partial_payment": true,
      "minimum_amount_due": {
        "currency_code": "USD",
        "value": "500.00"
      }
    },
    "tax_calculated_after_discount": true,
    "tax_inclusive": false
  }
}
```

**Notes**

* `unit_of_measure: "HOURS"` renders quantity as hours and `unit_amount` as the hourly rate on both the invoice and the customer-facing payment page.
* Omitting `shipping_info` from `primary_recipients` indicates a non-shippable, services-based invoice. Only `billing_info` is required.
* `allow_tip: true` renders an optional tip or gratuity field on the PayPal-hosted payment page — no additional API calls required. Use this for service businesses where tipping is customary, such as trades, personal care, event services, or photography. Set `allow_tip: false` for B2B or formal invoicing contexts.
* `allow_partial_payment: true` with a `minimum_amount_due` supports deposit-first or installment workflows common in service businesses.
* Use `unit_of_measure: "AMOUNT"` instead of `"HOURS"` if you're billing a flat project fee rather than hourly.
* To record a payment received outside of PayPal, such as by check or bank transfer, use `POST /v2/invoicing/invoices/{id}/payments`.

### Create an invoice for shippable goods

Create a physical goods invoice with quantity-based line items, separate billing and shipping addresses, a shipping charge, and shipping-specific tax. This pattern works best for e-commerce sellers, wholesalers, and distributors shipping physical products.

1. Confirm the products, quantities, and shipping details from the order in your system.
2. Call `POST /v2/invoicing/invoices` with quantity-based line items, a shipping address, and a shipping charge.
3. Call `POST /v2/invoicing/invoices/{id}/send` to deliver the invoice.
4. The buyer pays via PayPal or card; fulfill and ship the order.

| Field                                 | Description                                                               |
| ------------------------------------- | ------------------------------------------------------------------------- |
| `primary_recipients[].shipping_info`  | Buyer's shipping address. This can differ from billing address.           |
| `primary_recipients[].billing_info`   | Buyer's billing address.                                                  |
| `items[].unit_of_measure: "QUANTITY"` | Unit-based billing for physical goods.                                    |
| `amount.breakdown.shipping.amount`    | Flat shipping charge.                                                     |
| `amount.breakdown.shipping.tax`       | Tax applied specifically to the shipping charge.                          |
| `items[].tax`                         | Per-line sales tax on individual goods.                                   |
| `detail.reference`                    | Purchase order or order reference number. This value is customer-visible. |

**Request**

```json [expandable] theme={null}
{
  "detail": {
    "invoice_number": "INV-2026-ORD-4421",
    "reference": "PO-CLIENT-4421",
    "invoice_date": "2026-03-15",
    "currency_code": "USD",
    "note": "Thank you for your order! Your items will ship within 2 business days.",
    "term": "All goods remain the property of Apex Supply Co. until payment is received in full.",
    "payment_term": {
      "term_type": "DUE_ON_RECEIPT"
    }
  },
  "invoicer": {
    "name": {
      "given_name": "Casey",
      "surname": "Nguyen"
    },
    "email_address": "orders@apexsupply.com",
    "business_name": "Apex Supply Co.",
    "address": {
      "address_line_1": "800 Industrial Blvd",
      "admin_area_2": "Austin",
      "admin_area_1": "TX",
      "postal_code": "78701",
      "country_code": "US"
    }
  },
  "primary_recipients": [
    {
      "billing_info": {
        "name": {
          "given_name": "Sam",
          "surname": "Torres"
        },
        "business_name": "Torres Hardware Inc.",
        "email_address": "sam@torreshardware.com",
        "address": {
          "address_line_1": "220 Commerce Drive",
          "admin_area_2": "Chicago",
          "admin_area_1": "IL",
          "postal_code": "60601",
          "country_code": "US"
        }
      },
      "shipping_info": {
        "name": {
          "given_name": "Sam",
          "surname": "Torres"
        },
        "address": {
          "address_line_1": "500 Warehouse Road",
          "admin_area_2": "Chicago",
          "admin_area_1": "IL",
          "postal_code": "60607",
          "country_code": "US"
        }
      }
    }
  ],
  "items": [
    {
      "name": "Heavy-Duty Work Gloves",
      "description": "Model HG-200, Size L, Black",
      "quantity": "24",
      "unit_amount": {
        "currency_code": "USD",
        "value": "12.99"
      },
      "unit_of_measure": "QUANTITY",
      "tax": {
        "name": "Sales Tax",
        "percent": "8.25"
      }
    },
    {
      "name": "Safety Goggles",
      "description": "Model SG-500, Anti-fog, Clear lens",
      "quantity": "12",
      "unit_amount": {
        "currency_code": "USD",
        "value": "18.50"
      },
      "unit_of_measure": "QUANTITY",
      "tax": {
        "name": "Sales Tax",
        "percent": "8.25"
      }
    }
  ],
  "configuration": {
    "allow_tip": false,
    "partial_payment": {
      "allow_partial_payment": false
    },
    "tax_calculated_after_discount": false,
    "tax_inclusive": false
  },
  "amount": {
    "breakdown": {
      "shipping": {
        "amount": {
          "currency_code": "USD",
          "value": "18.00"
        },
        "tax": {
          "name": "Shipping Tax",
          "percent": "8.25"
        }
      }
    }
  }
}
```

**Notes**

* `shipping_info` and `billing_info` can have different addresses — PayPal renders both on the invoice and buyer confirmation page.
* `unit_of_measure: "QUANTITY"` renders items as discrete units — the standard for physical goods.
* Shipping tax is defined separately in `amount.breakdown.shipping.tax` and is independent from line item taxes.
* `detail.reference` is customer-visible and useful for linking back to a purchase order or external order management reference.
* To record a payment received outside of PayPal, such as by check or bank transfer, use `POST /v2/invoicing/invoices/{id}/payments`.

### Create an invoice for digital goods

Create a digital goods invoice with unit and flat-rate line items and a billing address only — no shipping address or charges. This pattern works best for merchants selling software licenses, downloads, online courses, or other digital products.

1. Capture the order details for the digital product purchase in your system.
2. Call `POST /v2/invoicing/invoices` with digital line items and a billing address only. Don't include `shipping_info`.
3. Call `POST /v2/invoicing/invoices/{id}/send` to deliver the invoice.
4. The customer pays via PayPal or card; handle digital delivery separately.

| Field                                 | Description                                                                        |
| ------------------------------------- | ---------------------------------------------------------------------------------- |
| `items[].unit_of_measure: "QUANTITY"` | Unit-based billing for seat or license-based products.                             |
| `items[].unit_of_measure: "AMOUNT"`   | Flat-rate billing for bundles or one-time packages.                                |
| `primary_recipients[].billing_info`   | Billing address only; no `shipping_info` included.                                 |
| `items[].tax`                         | Applicable sales tax. Digital goods tax rules vary by jurisdiction.                |
| `detail.note`                         | Delivery instructions or next-step guidance visible to the customer after payment. |

**Request**

```json [expandable] theme={null}
{
  "detail": {
    "invoice_number": "INV-2026-DIG-0028",
    "invoice_date": "2026-03-15",
    "currency_code": "USD",
    "note": "Your license keys and download links will be emailed within 24 hours of payment.",
    "payment_term": {
      "term_type": "DUE_ON_RECEIPT"
    }
  },
  "invoicer": {
    "name": {
      "given_name": "Riley",
      "surname": "Chen"
    },
    "email_address": "sales@stacktools.io",
    "business_name": "StackTools Inc.",
    "website": "https://stacktools.io"
  },
  "primary_recipients": [
    {
      "billing_info": {
        "name": {
          "given_name": "Avery",
          "surname": "Johnson"
        },
        "business_name": "Johnson Media Group",
        "email_address": "avery@johnsonmedia.com",
        "address": {
          "address_line_1": "1200 5th Avenue",
          "admin_area_2": "New York",
          "admin_area_1": "NY",
          "postal_code": "10001",
          "country_code": "US"
        }
      }
    }
  ],
  "items": [
    {
      "name": "StackTools Pro — Annual License",
      "description": "Single-seat annual license. Includes all features and priority support.",
      "quantity": "3",
      "unit_amount": {
        "currency_code": "USD",
        "value": "299.00"
      },
      "unit_of_measure": "QUANTITY",
      "tax": {
        "name": "Sales Tax",
        "percent": "8.875"
      }
    },
    {
      "name": "Onboarding & Setup Package",
      "description": "One-time onboarding session and configuration assistance.",
      "quantity": "1",
      "unit_amount": {
        "currency_code": "USD",
        "value": "149.00"
      },
      "unit_of_measure": "AMOUNT"
    }
  ],
  "configuration": {
    "allow_tip": false,
    "partial_payment": {
      "allow_partial_payment": false
    },
    "tax_calculated_after_discount": true,
    "tax_inclusive": false
  }
}
```

**Notes**

* Omitting `shipping_info` from `primary_recipients` signals that no physical delivery is required.
* Use `unit_of_measure: "QUANTITY"` for seat or unit-based products. Use `"AMOUNT"` for flat-rate bundles or packages where itemized quantity doesn't apply.
* Digital goods tax rules vary significantly by jurisdiction — consult your tax advisor for the correct rate based on customer location.
* Use `detail.note` to communicate delivery instructions or access information. This field is customer-visible on the PayPal invoice and payment confirmation page.

### Create a mixed billing invoice

Create an invoice that combines all three `unit_of_measure` types — `HOURS`, `QUANTITY`, and `AMOUNT` — in a single request, with an invoice-level discount and partial payment configuration. This pattern works best for agencies, consultancies, and IT services firms billing for a mix of time, deliverables, and flat fees within the same engagement.

> **Note:** This is an advanced use case that builds on the patterns above. If your business bills using only one line item type, refer to the appropriate use case.

1. Confirm time logs, deliverable counts, and agreed flat fees for the completed project work.
2. Call `POST /v2/invoicing/invoices` with mixed line items combining `HOURS`, `QUANTITY`, and `AMOUNT` types.
3. Review the draft, then call `POST /v2/invoicing/invoices/{id}/send`.
4. The client receives the invoice, reviews the itemized breakdown, and pays via PayPal or card.

| Field                                 | Description                                                             |
| ------------------------------------- | ----------------------------------------------------------------------- |
| `items[].unit_of_measure: "HOURS"`    | Billable time; quantity = hours worked, `unit_amount` = hourly rate.    |
| `items[].unit_of_measure: "QUANTITY"` | Discrete units; quantity = number of items, `unit_amount` = unit price. |
| `items[].unit_of_measure: "AMOUNT"`   | Flat-rate charge; quantity = `"1"`, `unit_amount` = total flat fee.     |
| `items[].discount`                    | Line item-level discount, such as percent or fixed amount.              |
| `amount.breakdown.discount`           | Invoice-level discount applied across all line items.                   |
| `configuration.partial_payment`       | Supports structured deposit and balance workflows.                      |
| `detail.memo`                         | Private internal note, not visible to the client.                       |

**Request**

```json [expandable] theme={null}
{
  "detail": {
    "invoice_number": "INV-2026-AGY-0047",
    "reference": "SOW-2026-003",
    "invoice_date": "2026-03-15",
    "currency_code": "USD",
    "note": "Thank you for partnering with us on this project. Please review the itemized breakdown below and don't hesitate to reach out with any questions.",
    "term": "Payment due within 30 days of invoice date. A late payment fee of 1.5% per month applies to overdue balances.",
    "memo": "Internal ref: Q1 closeout — Acct Manager: TJ — Client tier: Enterprise",
    "payment_term": {
      "term_type": "NET_30"
    }
  },
  "invoicer": {
    "name": {
      "given_name": "Priya",
      "surname": "Nair"
    },
    "email_address": "billing@northstaragency.com",
    "business_name": "North Star Agency LLC",
    "phones": [
      {
        "country_code": "1",
        "national_number": "6175550183",
        "phone_type": "WORK"
      }
    ],
    "website": "https://northstaragency.com",
    "address": {
      "address_line_1": "200 State Street",
      "address_line_2": "Floor 4",
      "admin_area_2": "Boston",
      "admin_area_1": "MA",
      "postal_code": "02109",
      "country_code": "US"
    }
  },
  "primary_recipients": [
    {
      "billing_info": {
        "name": {
          "given_name": "Marcus",
          "surname": "Webb"
        },
        "business_name": "Webb Enterprises Inc.",
        "email_address": "marcus.webb@webbenterprises.com",
        "address": {
          "address_line_1": "1 Financial Center",
          "admin_area_2": "Boston",
          "admin_area_1": "MA",
          "postal_code": "02111",
          "country_code": "US"
        }
      }
    }
  ],
  "items": [
    {
      "name": "Strategy & Discovery",
      "description": "Stakeholder interviews, competitive landscape analysis, and project scoping",
      "quantity": "20",
      "unit_amount": {
        "currency_code": "USD",
        "value": "200.00"
      },
      "unit_of_measure": "HOURS",
      "tax": {
        "name": "Sales Tax",
        "percent": "6.25"
      }
    },
    {
      "name": "Creative Design",
      "description": "Brand identity refresh — logo, typography, color system, and style guide",
      "quantity": "35",
      "unit_amount": {
        "currency_code": "USD",
        "value": "175.00"
      },
      "unit_of_measure": "HOURS",
      "tax": {
        "name": "Sales Tax",
        "percent": "6.25"
      }
    },
    {
      "name": "Licensed Stock Photography",
      "description": "Commercial license, 1-year term per image",
      "quantity": "12",
      "unit_amount": {
        "currency_code": "USD",
        "value": "45.00"
      },
      "unit_of_measure": "QUANTITY",
      "tax": {
        "name": "Sales Tax",
        "percent": "6.25"
      }
    },
    {
      "name": "Software Tools & Subscriptions",
      "description": "Figma, Maze, and Loom — project duration licenses",
      "quantity": "3",
      "unit_amount": {
        "currency_code": "USD",
        "value": "120.00"
      },
      "unit_of_measure": "QUANTITY"
    },
    {
      "name": "Project Management & Coordination",
      "description": "Flat-rate fee covering sprint planning, client communications, and delivery coordination for full project duration",
      "quantity": "1",
      "unit_amount": {
        "currency_code": "USD",
        "value": "1500.00"
      },
      "unit_of_measure": "AMOUNT",
      "tax": {
        "name": "Sales Tax",
        "percent": "6.25"
      }
    }
  ],
  "configuration": {
    "allow_tip": false,
    "partial_payment": {
      "allow_partial_payment": true,
      "minimum_amount_due": {
        "currency_code": "USD",
        "value": "2500.00"
      }
    },
    "tax_calculated_after_discount": true,
    "tax_inclusive": false
  },
  "amount": {
    "breakdown": {
      "discount": {
        "invoice_discount": {
          "percent": "5"
        }
      }
    }
  }
}
```

**Notes**

* You can mix all three `unit_of_measure` types — `HOURS`, `QUANTITY`, and `AMOUNT` — freely within the same `items` array. Each line item renders according to its own type on the invoice.
* Use `quantity: "1"` on `AMOUNT` lines for flat-rate fees. Don't use a quantity greater than `"1"` on an `AMOUNT` line — the API multiplies the values, which is likely unintended for flat fees.
* The invoice-level `amount.breakdown.discount` applies across the entire invoice total after individual line item subtotals are summed. Line item-level discounts apply before the invoice-level discount.
* Set `configuration.tax_calculated_after_discount: true` to calculate tax on the post-discount amount — the correct behavior for most jurisdictions.
* `detail.memo` is private and never shown to the client — use it for internal bookkeeping, account references, or sales attribution.

<Columns>
  <Card title="Invoicing API" href="/growth/grow-business/invoicing/quickstart-api">
    The Invoicing REST API lets you create, update, send, and manage invoices programmatically from your backend systems.
  </Card>

  <Card title="Troubleshooting" href="/growth/grow-business/invoicing/troubleshooting">
    Resolve common Invoicing API errors and integration issues.
  </Card>
</Columns>


# Manage your domain
Source: https://docs.paypal.ai/growth/grow-business/invoicing/use-your-email-domain/manage-domain



Manage your verified custom email domain after you complete the initial setup. Before you begin, [Set up your domain](/growth/grow-business/invoicing/use-your-email-domain/set-up-domain).

## Update your sender email prefix

You can update your sender email prefix at any time without re-verifying your domain.

1. From the [PayPal dashboard](https://developer.paypal.com/dashboard/), go to **Invoicing** > **Settings** > **Domain**.
2. Select **Update Sender Prefix**.
3. Enter your new prefix.
4. Select **Save**.

Your updated sender address appears in the **Domain** settings.

> **Note:** Avoid changing your sender prefix frequently. It may cause confusion for buyers who recognize your existing sender address.

## Deactivate your domain

Deactivating your domain reverts all invoice emails to [service@paypal.com](mailto:service@paypal.com) until you reactivate it. Your domain remains verified and you can reactivate it at any time.

1. Go to **Invoicing** > **Settings** > **Domain**.
2. Select **Deactivate Domain**.

Your domain status updates to inactive and invoice emails revert to [service@paypal.com](mailto:service@paypal.com).

## Reactivate your domain

1. Go to **Invoicing** > **Settings** > **Domain**.
2. Slide the toggle to activate domain.

Your domain status updates to active and invoice emails resume sending from your
custom domain.

## Remove your domain

Removing your domain permanently reverts all invoice emails to [service@paypal.com](mailto:service@paypal.com). To use a custom domain again, complete the setup wizard from the beginning.

1. Go to **Invoicing** > **Settings** > **Domain**.
2. Select **Remove Domain**.

Your domain is removed, and invoice emails revert to [service@paypal.com](mailto:service@paypal.com) permanently.

After removing the domain from PayPal, clean up the unused DNS records from your DNS provider.

## Ongoing domain monitoring

After initial verification, PayPal continuously monitors your domain to ensure email deliverability is maintained. If a record goes missing or becomes invalid, custom sending is suspended and emails revert to [service@paypal.com](mailto:service@paypal.com) until the records are restored.

You receive email notifications for the following domain lifecycle events:

| Event                                                                       | Action required                                                              |
| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Domain verified                                                             | Activate your domain from Invoicing settings.                                |
| Verification failed                                                         | Review and correct your DNS records, then re-verify from Invoicing settings. |
| Transient error reverted to [service@paypal.com](mailto:service@paypal.com) | No action required. PayPal will attempt to re-verify automatically.          |
| Transient error resolved and domain verified                                | Activate your domain from Invoicing settings.                                |

## Switch to a different domain

Each merchant account supports one custom domain at a time. To switch to a new domain, remove your existing domain first, then run through the dashboard setup again.

<Columns>
  <Card title="Troubleshooting" href="/growth/grow-business/invoicing/use-your-email-domain/troubleshooting">
    Resolve verification failures, bounce issues, and DNS configuration errors.
  </Card>

  <Card title="Set up your custom email domain" href="/growth/grow-business/invoicing/use-your-email-domain/set-up-domain">
    Configure your subdomain, add DNS records, and verify ownership with PayPal.
  </Card>
</Columns>


# Overview
Source: https://docs.paypal.ai/growth/grow-business/invoicing/use-your-email-domain/overview



Send PayPal invoice emails from your own email domain instead of [service@paypal.com](mailto:service@paypal.com). Set up your custom email in your [PayPal dashboard](https://www.paypal.com/invoice/s/settings/custom-domain?utm_medium=paypal_dev_docs) without the need for API integration.

Your custom email applies only to buyer-facing invoice emails, including invoice notifications, reminders, updates, and cancellations. Payment receipts and merchant notifications continue to use the default PayPal sender, [service@paypal.com](mailto:service@paypal.com). If your custom email becomes unavailable, PayPal automatically falls back to this default sender to ensure uninterrupted email delivery.

## How it works

* Setup: You add DNS records to your DNS provider to authenticate your email.
* Verification: PayPal verifies your domain ownership.
* Email sending: Buyer-facing invoice emails are sent from your domain instead of [service@paypal.com](mailto:service@paypal.com).
* Automatic fallback: If your domain becomes unavailable, PayPal automatically sends invoice emails from [service@paypal.com](mailto:service@paypal.com) to ensure uninterrupted delivery.

## Next steps

<Columns>
  <Card title="Set up your custom email domain" href="/growth/grow-business/invoicing/use-your-email-domain/set-up-domain">
    Configure your subdomain, add DNS records, and verify ownership with PayPal.
  </Card>

  <Card title="Manage your custom email domain" href="/growth/grow-business/invoicing/use-your-email-domain/manage-domain">
    Update your sender prefix, deactivate your domain, or switch to a different domain after setup.
  </Card>
</Columns>


# Set up your domain
Source: https://docs.paypal.ai/growth/grow-business/invoicing/use-your-email-domain/set-up-domain



Send PayPal invoice emails from your own domain instead of a paypal.com address. This guide shows you how to create a subdomain, configure the required DNS records, and verify your domain with PayPal.

## Prerequisites

* An active PayPal Business account
* A domain you own
* Access to your DNS provider's management console. DNS (Domain Name System) is the system that maps domain names to servers and stores records like TXT and CNAME. Common providers include Route 53, Cloudflare, GoDaddy, or equivalent.
* Check your domain settings to see if you have permission to add TXT and CNAME records.
  > **Additional info**: A TXT record is a note attached to your domain, often used for verification and security. A CNAME record is a nickname that points a domain name to another domain name.

## Create a subdomain

A subdomain is a prefix added to your domain. It is configured through DNS records, not purchased separately. If you already have a subdomain, you can skip the following steps.

1. Log in to your DNS provider's dashboard and navigate to **DNS Records** or **Zone Editor** for your domain.
2. Add a new DNS record with the following fields:

| Field             | Value                                                              |
| :---------------- | :----------------------------------------------------------------- |
| Type              | A, AAAA, or CNAME depending on your setup                          |
| Name / Host       | Your desired subdomain prefix, such as `api`, `staging`, or `docs` |
| Value / Points to | The IP address or hostname of the server handling the subdomain    |
| TTL               | `300` (5 min) for testing or `3600` for production                 |

3. Choose the right record type for your setup:
   * **A record** points the subdomain to an IPv4 address
   * **AAAA record** points the subdomain to an IPv6 address
   * **CNAME record** points the subdomain to another hostname

DNS changes can take up to 72 hours to propagate. Consult your DNS provider's documentation for specific instructions.

Common providers include:

* [Amazon Web Services](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/CreatingNewSubdomain.html)
* [DreamHost](https://help.dreamhost.com/hc/en-us/articles/215457827-Adding-a-subdomain)
* [Cloudflare DNS](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-subdomain/)
* [GoDaddy](https://www.godaddy.com/en-in/help/add-a-subdomain-4080)
* [Squarespace](https://support.squarespace.com/hc/en-us/articles/205812058-Creating-a-subdomain-for-your-Squarespace-site)
* [HostGator](https://www.hostgator.com/help/article/what-is-a-subdomain-name-how-do-i-create-and-delete-one)

## Step 1: Add your subdomain

1. In the PayPal dashboard, select **Invoicing** > **Settings** > **Domain**.
2. Select **Get Started**.
3. Enter your subdomain.
4. Enter a sender email prefix. Common choices include `billing`, `invoices`, `noreply`. A preview of your full sender address appears as you type.
5. Select **Continue**.

> **Note:** Replies to invoice emails go to your PayPal-registered business email address, not to the custom sender address. No functioning inbox is required on the custom domain.

## Step 2: Configure DNS records

After you submit your domain, PayPal displays the required DNS records on the DNS configuration page. Add all three records to your DNS provider before starting the verification process.

PayPal uses the following three email authentication standards to verify your domain:

| Record                              | Type  | Purpose                                                                                |
| :---------------------------------- | :---- | :------------------------------------------------------------------------------------- |
| Sender Policy Framework (SPF)       | TXT   | Authorizes mail servers to send email on behalf of your domain                         |
| DomainKeys Identified Mail 1 (DKIM) | CNAME | Adds a digital signature to emails so recipients can verify they weren't tampered with |
| DKIM 2                              | CNAME | Provides a backup DKIM key for continued email authentication                          |

Copy DNS records using the copy button to help prevent transcription errors.

> **Tip**: If another person manages your DNS settings, download the PDF generated for your domain from the DNS configuration page and share it with them. The PDF includes your domain's DNS records and setup instructions.

<Tabs>
  <Tab title="Add the SPF record">
    1. Check whether an SPF record already exists for your subdomain. SPF records are TXT records that follow this format: `v=spf1 include:_spf.google.com ~all`.
    2. If no SPF record exists, create a new TXT record using a hostname and the SPF value shown on the DNS configuration page.
    3. If an SPF record already exists, do not create a new one. Only one SPF record is allowed for a subdomain. Instead, update the existing record with the new value shown on the DNS configuration page.
  </Tab>

  <Tab title="Add the DKIM CNAME record">
    1. Select **Add New Record** and then select **CNAME** from the **Type** menu.
    2. Add the CNAME record to your root domain's DNS settings.
    3. Return to **Invoicing** > **Settings** > **Domain** and select **Get Started** to open the DNS configuration page. Copy the **Name** and **Value**, and enter them in your DNS provider.
    4. Repeat these steps to add the second DKIM CNAME record.
  </Tab>

  <Tab title="Add a DMARC policy">
    Most DNS providers create a DMARC record by default. If your provider doesn't create a record by default, publish one as a TXT record using `_dmarc` as the name and the following tags:

    | Tag              | Description                                                    | Example                     |
    | :--------------- | :------------------------------------------------------------- | :-------------------------- |
    | `v` (required)   | Protocol version. Must be `DMARC1`                             | `v=DMARC1`                  |
    | `p` (required)   | Domain policy. Accepted values: `none`, `quarantine`, `reject` | `p=none`                    |
    | `rua` (optional) | Address to receive aggregate DMARC reports                     | `rua=mailto:dmarc@acme.com` |

    For example:

    ```
    TXT  _dmarc  v=DMARC1; p=none; rua=mailto:dmarc@acme.com
    ```

    If you are new to DMARC, start with `p=none` for monitoring, then move to `quarantine` or `reject` once you are confident in your configuration.

    > **Important:** PayPal does not support strict SPF alignment. Do not include `aspf=s` in your DMARC policy. If you are already using this domain to send email, consult an IT or email professional before modifying your DMARC record.
  </Tab>
</Tabs>

For instructions on adding DNS records, see the documentation for your DNS provider. Common providers include:

* [Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-creating.html)
* [Cloudflare](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/)
* [DreamHost](https://help.dreamhost.com/hc/en-us/articles/360035516812-Adding-custom-DNS-records)
* [GoDaddy](https://www.godaddy.com/en-in/help/add-a-cname-record-19236)
* [Google Cloud DNS](https://docs.cloud.google.com/dns/docs/records)
* [Squarespace](https://support.squarespace.com/hc/en-us/articles/205812348-Accessing-your-Squarespace-managed-domain-s-DNS-settings)

## Step 3: Verify and activate

Once you've added all the DNS records, return to your PayPal dashboard to verify ownership and activate your domain.

1. In the PayPal dashboard, select **Invoicing** > **Settings** > **Domain**.
2. Select **Verify Domain**.

DNS changes can take up to 72 hours to propagate. Use [dnschecker.org](https://dnschecker.org) to confirm your records are published before selecting **Verify Domain**.

After the provider verifies the domain, open **Invoicing** settings and turn on domain. When the domain is active, all buyer-facing invoice emails are automatically sent from your custom sender address. Your existing invoice creation workflow continues to work exactly as before.

> **Important:** Do not delete your DNS records after verification. PayPal revalidates them regularly. If a record goes missing, custom sending is suspended, and emails revert to [service@paypal.com](mailto:service@paypal.com) until the records are restored.

### Verification status

After selecting **Verify Domain**, your domain enters one of the following states:

| Status           | Description                                                                                 |
| :--------------- | :------------------------------------------------------------------------------------------ |
| Setup incomplete | Domain registered is awaiting DNS configuration and verification.                           |
| Verifying        | Verification in progress can take up to 72 hours.                                           |
| Verified         | All DNS records confirmed. Activate domain.                                                 |
| Error            | One or more checks failed. Review per-record status, correct the records, and verify again. |

### After activation

When your domain is active, all buyer-facing invoice emails are sent from your custom sender address automatically. No additional configuration is required.

* **Sender address:** Emails are sent from `{prefix}@{domain}`. For example, if your domain is `invoices.acme.com` and your prefix is `billing`, emails are sent from `billing@invoices.acme.com`.
* **Reply-to:** Buyer replies go to your PayPal-registered business email address, not the custom sender address.
* **CC recipients:** CC'd recipients see the custom domain as the sender.

<Columns>
  <Card title="Manage your domain" href="/growth/grow-business/invoicing/use-your-email-domain/manage-domain">
    Update your sender prefix, deactivate your domain, or switch to a different domain.
  </Card>

  <Card title="Troubleshooting" href="/growth/grow-business/invoicing/use-your-email-domain/troubleshooting">
    Resolve verification failures, bounce issues, and DNS configuration errors.
  </Card>
</Columns>


# Troubleshooting
Source: https://docs.paypal.ai/growth/grow-business/invoicing/use-your-email-domain/troubleshooting



Resolve verification failures, bounce issues, and DNS configuration errors. If you run into issues with your custom email domain, use this page to diagnose and resolve common problems.

## Domain not verifying

If your domain hasn't verified after 72 hours, check the following:

* **Typos in records:** Double-check the Name and Value fields from the DNS configuration screen in your dashboard. Use the copy buttons to avoid transcription errors.
* **Conflicting CNAME records:** CNAME records must be the only record for a given hostname. Remove any conflicting A, AAAA, or TXT records at the same name.
* **Duplicate domain in record name:** Some DNS providers automatically append your domain. If your domain is `acme.com`, enter only `bounce` in the Name field, not `bounce.acme.com`.
* **DNS propagation:** Use [dnschecker.org](https://dnschecker.org) to confirm your records are published globally before selecting **Verify Domain**.
* **Cloudflare proxy:** If using Cloudflare, ensure CNAME records are set to **DNS Only**. Proxied records will prevent verification.

## Emails reverting to [service@paypal.com](mailto:service@paypal.com)

PayPal sends your emails from [service@paypal.com](mailto:service@paypal.com) instead of your custom domain when a domain health check fails.  Common causes:

* DNS records were accidentally deleted or modified.
* Domain registration expired at the registrar level.
* Transient error and no action required.

In the [PayPal dashboard](https://www.paypal.com/mep/dashboard?_ga=1.78831252.1259758161.1760473483), select **Invoicing** > **Settings** > **Domain** to see the current status and per-record diagnostics. Correct the issue and the system restores custom sending on the next health check cycle.

## Bounce handling

If a custom-domain email bounces, PayPal's behavior depends on the cause:

| Cause                                    | PayPal behavior                                                                                                                                                                                                                                                                                                              |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SPF, DKIM, or DMARC failure              | PayPal automatically attempts to re-verify your domain and retry sending. If your domain is no longer valid, the email falls back to [service@paypal.com](mailto:service@paypal.com). See [High bounce rates](/growth/grow-business/invoicing/use-your-email-domain/troubleshooting#high-bounce-rates) for more information. |
| Invalid or nonexistent recipient address | PayPal sends a bounce notification to the merchant.                                                                                                                                                                                                                                                                          |
| Recipient mailbox full                   | PayPal sends a bounce notification to the merchant.                                                                                                                                                                                                                                                                          |

For SPF, DKIM, or DMARC failures, your domain status moves to pending while PayPal attempts to re-verify. You'll receive an email notification when this happens. No action is required until PayPal confirms the domain status.

## High bounce rates

A `5.7.x` bounce code indicates a domain authentication failure. Check that your SPF, DKIM, and DMARC records are correctly configured using [dnschecker.org](https://dnschecker.org) or select **Verify Domain** from Invoicing Settings.

When PayPal detects an authentication failure:

* PayPal attempts to re-verify your domain and retry sending.
* If your domain is healthy, the email is resent from your custom domain.
* If your domain is no longer valid, the email falls back to [service@paypal.com](mailto:service@paypal.com).

Your domain status moves to pending during re-verification. You'll receive an email notification and no action is required until PayPal confirms the domain status.

<Columns>
  <Card title="Set up your custom email domain" href="/growth/grow-business/invoicing/use-your-email-domain/set-up-domain">
    Configure your subdomain, add DNS records, and verify ownership with PayPal.
  </Card>

  <Card title="Manage your domain" href="/growth/grow-business/invoicing/use-your-email-domain/manage-domain">
    Update your sender prefix, deactivate your domain, or switch to a different domain.
  </Card>
</Columns>


# Invoicing webhooks
Source: https://docs.paypal.ai/growth/grow-business/invoicing/webhooks



When a merchant creates, updates, pays, or cancels an invoice, PayPal sends a webhook event to your server. Your server can then process the events automatically.
To set up webhooks, see our [Webhooks guide](https://developer.paypal.com/api/rest/webhooks/).

PayPal sends these webhook events for invoice activities.

| Event                         | PayPal sends this webhook when                                     | API reference                                                                                         |
| :---------------------------- | :----------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- |
| `INVOICING.INVOICE.CANCELLED` | A merchant or customer cancels an invoice                          | [Cancel sent invoice](https://developer.paypal.com/docs/api/invoicing/v1/#invoice_cancel)             |
| `INVOICING.INVOICE.CREATED`   | A merchant creates an invoice                                      | [Create draft invoice](https://developer.paypal.com/docs/api/invoicing/v1/#invoices_create)           |
| `INVOICING.INVOICE.PAID`      | A customer makes a full, partial, or pending payment on an invoice | [Mark invoice as paid](https://developer.paypal.com/docs/api/invoicing/v1/#invoice_record-payment)    |
| `INVOICING.INVOICE.REFUNDED`  | A merchant issues a full or partial refund for an invoice          | [Mark invoice as refunded](https://developer.paypal.com/docs/api/invoicing/v1/#invoice_record-refund) |
| `INVOICING.INVOICE.SCHEDULED` | A merchant schedules an invoice                                    | [Schedule invoice](https://developer.paypal.com/docs/api/invoicing/v1/#invoice_schedule)              |
| `INVOICING.INVOICE.UPDATED`   | A merchant updates an invoice                                      | [Update invoice](https://developer.paypal.com/docs/api/invoicing/v1/#invoice_update)                  |


# Customize Payouts API integration
Source: https://docs.paypal.ai/growth/payouts/customize/customize-payouts-api-integration



You can use the procedures in this section to customize your Payouts API integration to support global payments, optimize API responses, and ensure reliable payout processing.

## Pay recipients in their local currency

You can pay recipients in any supported currency, even if your PayPal account does not hold a balance in that currency. To do this, set the `items.amount.currency` parameter in your <a href="/growth/payouts/send-money/use-payouts-api#1-create-payout-batch">payout request</a> to the appropriate <a href="/growth/payouts/reference/countries-supported-features#supported-currencies-for-automatic-conversion">currency code</a>. PayPal automatically converts currencies and applies relevant fees. This helps you reach recipients globally and simplify cross-border payments.

<Note>For more information about currency conversion, country exclusions, and restrictions, see <a href="/growth/payouts/reference/countries-supported-features#currency-conversion">Currency conversion</a>.</Note>

Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token">valid access token</a> and make a GET call to the `/v1/payments/payouts/{ID}` endpoint.

**Path parameter**: `ID` is the `payout_batch_id` returned in the <a href="/growth/payouts/send-money/use-payouts-api#1-create-payout-batch">Create payout batch</a> response.

<CodeGroup>
  ```shell Sample request lines theme={null}
  curl -X GET https://api-m.sandbox.paypal.com/v1/payments/payouts/5UXD2E8A7EBQJ \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer ACCESS-TOKEN'
  ```

  ```json Sample response lines expandable theme={null}
  {
    "total_items": 1,
    "total_pages": 1,
    "batch_header": {
      "payout_batch_id": "5UXD2E8A7EBQJ",
      "batch_status": "SUCCESS",
      "time_created": "2024-07-03T10:30:00Z",
      "time_completed": "2024-07-03T10:32:15Z",
      "sender_batch_header": {
        "sender_batch_id": "Payouts_2024_100001",
        "email_subject": "You have a payout!",
        "email_message": "Congratulations! You have received a payout."
      },
      "funding_source": "BALANCE",
      "amount": {
        "currency": "USD",
        "value": "108.50"
      },
      "fees": {
        "currency": "USD",
        "value": "1.95"
      }
    },
    "items": [
      {
        "payout_item_id": "9MYSR9GT8AEUG",
        "transaction_id": "2JE19762AW167960J",
        "activity_id": "3E158638XS0329103",
        "transaction_status": "SUCCESS",
        "payout_item_fee": {
          "currency": "USD",
          "value": "1.95"
        },
        "payout_batch_id": "5UXD2E8A7EBQJ",
        "payout_item": {
          "recipient_type": "EMAIL",
          "amount": {
            "currency": "EUR",
            "value": "100.00"
          },
          "note": "Thank you for your business!",
          "receiver": "recipient.europe@example.com",
          "sender_item_id": "EUR_PAYOUT_001"
        },
        "currency_conversion": {
          "from_amount": {
            "currency": "USD",
            "value": "108.50"
          },
          "to_amount": {
            "currency": "EUR", 
            "value": "100.00"
          },
          "exchange_rate": "0.9217"
        },
        "time_processed": "2024-07-03T10:31:45Z"
      }
    ],
    "links": [
      {
        "href": "https://api-m.sandbox.paypal.com/v1/payments/payouts/5UXD2E8A7EBQJ",
        "rel": "self",
        "method": "GET"
      }
    ]
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response with the payout details, including currency conversion fee details for each payout item.

## Get specific payout details

When you <a href="/growth/payouts/send-money/use-payouts-api#poll-for-updates">track payouts status</a>, you can use the `fields` query parameter and customize the response to return only the information you need. This enables you to tailor the API output for summary reporting or reconciliation. Requesting specific fields reduces response size and improves performance.

Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token">valid access token</a> and make a GET call to the `/v1/payments/payouts/{ID}?fields={FIELDS}` endpoint.

**Path parameter**: `ID` is the `payout_batch_id` returned in the <a href="/growth/payouts/send-money/use-payouts-api#1-create-payout-batch">Create payout batch</a> response.

**Query parameter**: `FIELDS` are the specific fields that you need in the response. For example, you can request only the `batch_header` for a summary.

<CodeGroup>
  ```shell Sample request lines theme={null}
  curl -v -X GET 'https://api-m.sandbox.paypal.com/v1/payments/payouts/NNX8XK9T3CGWN?fields=batch_header' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer ACCESS-TOKEN'
  ```

  ```json Sample response lines expandable theme={null}
  {
      "batch_header": {
          "payout_batch_id": "NNX8XK9T3CGWN",
          "batch_status": "SUCCESS",
          "time_created": "2025-07-31T07:00:57Z",
          "time_completed": "2025-07-31T07:01:26Z",
          "sender_batch_header": {
              "sender_batch_id": "Payouts_1753945252",
              "email_subject": "You have a payout!",
              "email_message": "Congratulations! You have received a payout."
          },
          "funding_source": "BALANCE",
          "amount": {
              "currency": "USD",
              "value": "10.00"
          },
          "fees": {
              "currency": "USD",
              "value": "0.25"
          }
      },
      "items": [],
      "links": [{
          "href": "https://api.sandbox.paypal.com/v1/payments/payouts/NNX8XK9T3CGWN?page_size=1000&page=1",
          "rel": "self",
          "method": "GET",
          "encType": "application/json"
      }]
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response with the requested details of the payout batch.

## Prevent duplicate requests

You can prevent the processing of duplicate batch payouts. To do this, in the <a href="/growth/payouts/send-money/use-payouts-api#1-create-payout-batch">create payout batch request</a>, use a unique `sender_batch_id` for each batch. If you reuse a `sender_batch_id` from the last 30 days, the API rejects the request and returns an error with a HATEOAS link to the original batch. When you retry a request after an HTTP 5xx error, use the same `sender_batch_id` as the original request to ensure PayPal processes only one batch, even if you submit multiple requests.

## Implement idempotency

You can retry a payout request multiple times and still ensure that it has the effect of only one successful request, through idempotency.

To implement idempotency:

* Include a unique, self-generated idempotency key as the `PayPal-Request-Id` header-parameter value for each payout request.
* Use the same idempotency key when you retry the request due to a network issue or HTTP 5xx server error.
* If the payout details already exist, PayPal returns the current state of the payout. This ensures you create only one payout for each unique key.

<Note>If PayPal receives two simultaneous requests with the same `PayPal-Request-Id` (idempotency key), PayPal processes only the first request. The second request fails with an error indicating the duplicate key. For more information, see <a href="/developer/how-to/api/make-api-requests#paypal-request-id">PayPal-Request-Id</a>.</Note>


# Customize Web UI payouts
Source: https://docs.paypal.ai/growth/payouts/customize/customize-web-ui-payouts



You can use the procedures in this section to improve payout governance and global payout capabilities using the Web UI.

## Pay recipients in their local currency

You can pay recipients in any supported currency, even if your PayPal account does not hold a balance in that currency. To do this:

1. <a href="/growth/payouts/send-money/use-web-ui#1-create-input-file">Create one input file</a> for each payout currency.
   <Note>An input file can payout only in one currency type. For local currency payouts, group recipients based on currency type and create multiple files.</Note>
2. <a href="/growth/payouts/send-money/use-web-ui#2-upload-input-file">Upload the input files one by one</a>. PayPal reviews the file and if valid, displays the Review your payment details page. The page contains the currency conversion fees and other currency exchange details, that PayPal calculates automatically.
3. Review and select **Send Payout**.

<Note>For more information about currency conversion, country exclusions, and restrictions, see <a href="/growth/payouts/reference/countries-supported-features#currency-conversion">Currency conversion</a>.</Note>

## Set up payout approval flow

You can add an approval flow to your payouts for proper governance over fund disbursement. To do this:

1. Log in to your PayPal business account.
2. Go to **Account Settings** > **Account Access** > **Manage Users** and select **Update**.
3. In the Users page, select **Manage Approvals**.
4. In the Approvals page, select **Get Started** for **Send payouts**.
5. In the pop-up window, choose the users who can approve payout requests and select **Done**.
6. Select **Yes, Turn On Approvals**.
7. Select **Close**. The Send Payout approvers page displays the users who can approve payout requests.

<Note>The user who creates a payout cannot approve the same payout.</Note>


# Collect recipient information with AAC
Source: https://docs.paypal.ai/growth/payouts/customize/integrate-aac



You can use Assisted Account Creation (AAC) to let your customers use their PayPal account to log in or sign up on your site. AAC simplifies onboarding, increases customer account creation, and helps your customers receive payouts quickly and securely.

When a customer completes the onboarding flow, you receive their payer ID and email address. Payer IDs are typically the most reliable way to ensure accurate and secure payouts.

AAC can:

* Identify customers with PayPal accounts and display a **Log in with PayPal** button.
* Enable merchants to customize rewards for PayPal users.
* Allow customers to connect their PayPal account at your site's payment settings screen.

## Prerequisites

* Complete all mandatory steps to <a href="/growth/payouts/set-up#set-up-sandbox-account-for-payouts-api-integration">get started</a>. Use the retrieved sandbox app credentials (client ID and secret) in your code to generate an access token. The access token is a server-side token that authenticates your application when accessing PayPal API resources.
* Ensure you have verified your PayPal business account and enabled it for Payouts. For more information, see <a href="/growth/payouts/set-up#set-up-live-account">Set up your PayPal business account</a>.
* <a href="https://www.paypal.com/us/cshelp/contact-us">Contact PayPal</a> or work with your account manager to enable <a href="https://www.paypal.com/in/cshelp/article/how-do-i-confirm-my-identity--help606"> identity services</a> and configure the following return URLs for your application:
  * **Sandbox**: [https://www.sandbox.paypal.com/conex/ac/add-offer-recipient](https://www.sandbox.paypal.com/conex/ac/add-offer-recipient)
  * **Live**: [https://www.paypal.com/conex/ac/add-offer-recipient](https://www.paypal.com/conex/ac/add-offer-recipient)
* Enable **Log in with PayPal** in your app settings:
  1. Go to your <a href="https://developer.paypal.com/dashboard/">PayPal developer account</a> and toggle to **Sandbox**.
  2. Go to **Apps & Credentials** and select your app.
  3. Go to **Features** and select **Log in with PayPal**.
  4. Select **Advanced settings**. This displays the Log in with PayPal page.
  5. Enter the **Return URL** to redirect your customers after they complete the Log in with PayPal flow.
  6. Go to **Information requested from customers** and select the following options:
     * **Email**
     * **Account verification status**
     * **PayPal account ID (payer ID)**
     * **Enable customers who have not yet confirmed their email with PayPal to log in to your app**: Select this option based on your business requirement. For details, see <a href="https://developer.paypal.com/docs/log-in-with-paypal/">Enable Log in with PayPal</a>.
  7. Save your app settings.
* Get your **Paypal Merchant ID** from the **Account Settings** > **Business information** page of your PayPal business account. Use this ID to uniquely identify your PayPal business account in your integration setup and API requests.

## Integrate assisted account creation

Integrating AAC enables your application to access customers’ email addresses and payer IDs (encrypted PayPal account numbers) during sign up, log in, or payment setup on your website or partner platform.

### Integrate client side

In your client-side code, integrate the AAC SDK to render the AAC component. The AAC SDK uses <a href="https://github.com/krakenjs/zoid">Zoid</a>, PayPal’s open-source cross-domain component library.
Use the following samples to integrate AAC based on your client-side framework.

<CodeGroup>
  ```html HTML lines  theme={null}
  <script src="https://www.paypalobjects.com/payouts/js/payouts_aac.js"></script>
  {/* Set up a container to render the AAC component */}
  <div id="container"></div>
  <script>
      // Render the AAC component
      paypal.PayoutsAAC.render({
          // Use sandbox for testing
          env: "<sandbox/production>",
          clientId: {
            production: "<production clientId>",
            sandbox: "<sandbox clientId>"
          },
          merchantId: "<Merchant Account ID>",
          pageType: "<signup/login>",
          onLogin: function(response) {
            if (response.err) {
              console.log(response.err)
            } else {
              console.log(response.body.code);
            }
          }
        }, '#container');
  </script>
  ```

  ```jsx React lines theme={null}
  import React from 'react';
  import ReactDOM from 'react-dom';
  const AACComponent = paypal.PayoutsAAC.driver('react', {
    React,
    ReactDOM
  });
  class OtherReactComponent extends React.Component {
    render() {
      return (
        <AACComponent
          clientId="<clientId>"
          merchantId="<Merchant Account ID>"
          env="<sandbox/production>"
          pageType="<signup/login>"
          onLogin={onLogin} />
      );
    }
  }
  ```

  ```typescript Angular lines theme={null}
  // Specify the component name as a dependency to your angular app:
  angular.module('myapp', ['payouts-aac']);
  // Include the tag in one of your templates (use kebab case for prop names)
  <payouts-aac
    client-id="<clientId>"
    merchant-id="<Merchant Account ID>"
    env="<sandbox/production>"
    page-type="<signup/login>"
    on-login="onLogin">
  </payouts-aac>
  ```
</CodeGroup>

### Integrate server side

After the user completes the PayPal log in or sign-up flow, PayPal redirects to your `redirect_uri` with a `code` parameter.

1. Use the authorization code from the client-side code to obtain an access token.

```shell lines theme={null}
curl -X POST https://api-m.sandbox.paypal.com/v1/identity/openidconnect/tokenservice \
  -H 'Authorization: Basic <Base64 Encoded client_id:secret>' \
  -d 'grant_type=authorization_code&code=<code>'
```

2. Use the access token to get the customer's email address and payer ID.

```shell lines theme={null}
curl -v -X GET https://api-m.sandbox.paypal.com/v1/oauth2/token/userinfo?schema=openid \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'
```

#### Integrate with Node or Python

In your server-side code, use the following samples to integrate AAC.

<CodeGroup>
  ```javascript Node lines theme={null}
  var paypal = require('paypal-rest-sdk');
  paypal.configure({
    'mode': 'sandbox', //sandbox or live
    'client_id': '',
    'client_secret': ''
  });
  // Get tokeninfo with Authorization code
  paypal.openIdConnect.tokeninfo.create("Replace with authorization code", function(error, tokeninfo){
    console.log(tokeninfo);
  });
  // Get userinfo with Access code
  paypal.openIdConnect.userinfo.get("Replace with access_code", function(error, userinfo){
    console.log(userinfo);
  });
  ```

  ```python Python lines theme={null}
  import paypalrestsdk
  from paypalrestsdk.openid_connect import Tokeninfo, Userinfo
  paypalrestsdk.configure({
    "mode": "sandbox", # sandbox or live
    "client_id": "",
    "client_secret": "" })
  tokeninfo = Tokeninfo.create("Replace with authorization code")
  userinfo  = tokeninfo.userinfo()
  ```
</CodeGroup>

## Test end-to-end flow

To test the AAC integration in the sandbox:

1. Run your application.
2. Verify if your application renders the **Log in with PayPal** button.
3. Select **Log in with PayPal** on your application.
4. Log in with your sandbox personal account credentials or complete the sign up process.
5. Approve the consent to share the customer details.
6. Use your sandbox business account to:
   * Verify that your application receives the authorization code.
   * Exchange the authorization code for an access token.
   * Use the access token to retrieve the customer details.
   * Check if the customer account exists. If not, use the retrieved customer details to create a new account in your application.
   * Use the access token to make a payout request.
7. Verify the payout:
   * Confirm if the payout status is `SUCCESS` in your sandbox business account.
   * Confirm the movement of money into your sandbox personal account.


# Cancel or reverse payouts
Source: https://docs.paypal.ai/growth/payouts/manage-payouts/cancel-reverse-payouts



You can use the procedure and information in this section to cancel unclaimed payouts and understand payout reversals.

## Cancel payout item

You can cancel a payout item only if its status is `UNCLAIMED`. Use the PayPal business account dashboard or the Payouts API to cancel unclaimed payout items.

To implement payment cancellation functionality, you can use the [Dashboard](#dashboard) or the [API](#api).

<Note>Unclaimed payouts expire in 30 days, and PayPal returns the money to your PayPal account.</Note>

<Tabs>
  <Tab title="Dashboard">
    1. Log into your <a href="https://www.paypal.com">PayPal business account</a>.
    2. Select **Activity** > **Transactions** > **All Transactions**.
    3. On the **Transactions** page:
       1. Select **Email address** from the drop-down list.
       2. Enter the recipient's email address in the search box.
       3. Select **Filter**.
       4. Select the date range.
       5. Select **Apply Filters**. The search results display the transaction list that matches your criteria.
    4. Select the title of the unclaimed payment you want to cancel.
    5. On the details page, select **Cancel** and follow the on-screen instructions.
  </Tab>

  <Tab title="API">
    Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token">valid access token</a> and make a POST call to the `/v1/payments/payouts-item/{PAYOUT-ITEM-ID}/cancel` endpoint. <br />
    **Path parameter**: `PAYOUT-ITEM-ID` is the `payout_item_id` returned in the <a href="/reference/api/rest/payouts/show-payout-batch-details">Show payout batch details</a> response.

    <CodeGroup>
      ```bash Sample request lines theme={null}
      curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/payouts-item/5KUDKLF8SDC7S/cancel \
          -H 'Content-Type: application/json' \
          -H 'Authorization: Bearer ACCESS-TOKEN' \
          -d '{}'
      ```

      ```json Sample response lines expandable theme={null}
      {
        "payout_item_id": "5KUDKLF8SDC7S",
        "transaction_id": "1DG93452WK758815H",
        "activity_id": "0E158638XS0329101",
        "transaction_status": "RETURNED",
        "payout_item_fee": {
          "currency": "USD",
          "value": "0.35"
        },
        "payout_batch_id": "CQMWKDQF5GFLL",
        "sender_batch_id": "Payouts_2018_100006",
        "payout_item": {
          "recipient_type": "EMAIL",
          "amount": {
            "value": "9.87",
            "currency": "USD"
          },
          "note": "Thanks for your patronage!",
          "receiver": "receiver@example.com",
          "sender_item_id": "14Feb_234"
        },
        "time_processed": "2018-01-27T10:17:41Z",
        "errors": {
          "name": "RECEIVER_UNREGISTERED",
          "message": "Receiver is unregistered",
          "information_link": "https://developer.paypal.com/docs/api/payments.payouts-batch#errors"
        },
        "links": [
          {
            "rel": "self",
            "href": "https://api-m.sandbox.paypal.com/v1/payments/payouts-item/5KUDKLF8SDC7S",
            "method": "GET"
          },
          {
            "rel": "batch",
            "href": "https://api-m.sandbox.paypal.com/v1/payments/payouts/CQMWKDQF5GFLL",
            "method": "GET"
          }
        ]
      }
      ```
    </CodeGroup>

    A successful call returns a `200 OK` response with a JSON response body that shows payout item details.
  </Tab>
</Tabs>

## Understand payout reversals

PayPal cannot reverse payments that a payer sends to an incorrect email address or phone number. However, if the status of the payout item is `UNCLAIMED`, a payer can [cancel the payout item](#cancel-payout-item) and create a new payout with the correct recipient details.
If not, all unclaimed payouts expire in 30 days, and PayPal returns the money to the payer's PayPal account.


# Handle unclaimed payouts
Source: https://docs.paypal.ai/growth/payouts/manage-payouts/handle-unclaimed-payouts



When recipients do not claim their payouts, the status of the payout items remains `UNCLAIMED`. Typically, unclaimed payouts can occur due to:

* Incorrect recipient details such as email address or mobile number.
* Unverified email addresses.
* Unaccepted payments in the recipient's PayPal account.

Track and resolve unclaimed payouts promptly to avoid delays and improve the payment success rate. If not, these payouts expire in 30 days, and PayPal automatically returns the money to your PayPal account.

## Track unclaimed payouts

<a href="/growth/payouts/manage-payouts/reports-transaction-logs#generate-activity-report">Download the Activity report</a> to view the details of the payout items. To view the unclaimed payouts, filter the status column for `UNCLAIMED`.

## Resolve unclaimed payouts

Verify recipient details, such as email address and phone number.

1. If the recipient details are incorrect:
   1. <a href="/growth/payouts/manage-payouts/cancel-reverse-payouts#cancel-payout-item">Cancel the payout item</a>.
   2. <a href="/growth/payouts/send-money/use-payouts-api#1-create-payout-batch">Create a new payout</a> with the correct recipient information.
2. If the recipient details are correct:
   1. Contact the recipient to verify their email address and phone number.
   2. If the recipient has not verified their email address, notify them to confirm it.
   3. If the recipient has not accepted the payment, notify your recipient to log in to their PayPal account and accept the payment.

## Best practices to reduce unclaimed payouts

* Validate recipient data before initiating payouts.
* Notify payout timelines to recipients.
* Monitor payout statuses regularly to track and resolve issues.


# View reports and transaction logs
Source: https://docs.paypal.ai/growth/payouts/manage-payouts/reports-transaction-logs



You can access the reports and transaction logs for payouts using your PayPal business account. These reports help you monitor, download, and analyze payout activity for reconciliation, compliance, and troubleshooting.

## Generate Activity report

You can use the Activity report to get a list of all the transaction activity for your PayPal business account.

1. Log into your <a href="https://www.paypal.com">PayPal business account</a>.
2. Go to **Activity** > **All reports**.
3. On the All reports page, select **Activities** tab > **Activity report**.
4. On the Activity report page, choose the **Transaction type**, **Date range**, and **Format**.
5. Optional: Select **Customize report fields** to add or remove fields from the report.
6. Select **Create report**. The report appears in the Activity reports list. You will receive a notification when it is ready for download.
7. Select **Download**. The report contains the transaction details such as **Date**, **Name**, **Status**, **Transaction ID**, **Fee**, and so on.

## Generate Settlements report and Transaction details report

You can use the [Settlements report](#generate-settlements-report) and [Transaction details report](#generate-transaction-details-report) to identify different types of payout transactions using [Transaction event codes](#understand-transaction-event-codes).

### Understand transaction event codes

You can use the Transaction event codes (T-codes) to identify the type of payout transactions in your reports. For payouts, T-codes help you monitor payout transactions at every step.

| T-code  | Description                              |
| ------- | ---------------------------------------- |
| `T0001` | Mass Payment (successful)                |
| `T0104` | Mass Payment batch fee                   |
| `T1105` | Account hold released                    |
| `T1114` | Mass Payment reversal transaction        |
| `T1115` | Mass Payment refund transaction          |
| `T1503` | Temporary hold on payout amount and fees |

For example:

* `T1503`: When you start a payout, PayPal assigns this code to the transaction and places a temporary hold on the payout amount and associated fees.
* `T1105`: When the batch payout completes, PayPal changes the T-code to this value and releases the hold on the payout amount. If PayPal declines any payments, your final balance may be higher than during the hold.

### Generate Settlements report

You can use the Settlements report to view a summary of transactions that affect your PayPal balance. It includes details of sent and refunded payouts but excludes declined payments.

1. <a href="https://www.paypal-support.com/">Contact PayPal</a> to enable the Settlements report access for your PayPal business account.
2. After you get the report access, log into your <a href="https://www.paypal.com">PayPal business account</a>.
3. Go to **Activity** > **All reports**.
4. On the All reports page, select **Payments** tab > **Settlements report**.
5. Set the date range and filters.
6. Download the report as a `.csv` or `.tsv` file.
7. In the downloaded report, you can:
   * Use the **Transaction ID** from the [Activity report](#generate-activity-report) to filter the **PayPal Reference ID** column and track specific transactions.
   * Use the T-codes in the **Transaction Event Code** column to find the type of payout transaction. For more information about T-codes, see [Understand transaction event codes](#understand-transaction-event-codes).

For more information, see the <a href="https://developer.paypal.com/docs/reports/sftp-reports/settlement-report/">Settlement Report Specification</a>.

### Generate Transaction details report

You can use the Transaction details report to view a summary of transactions that affect your PayPal balance. It includes details of all payout transactions but excludes declined payments.

1. <a href="https://www.paypal-support.com/">Contact PayPal</a> to enable the Transaction details report access for your PayPal business account.
2. After you get the report access, log into your <a href="https://www.paypal.com">PayPal business account</a>.
3. Go to **Activity** > **All reports**.
4. On the All reports page, select **Payments** tab > **Transaction details report**.
5. Download the report as a `.csv` or `.tsv` file.
6. In the downloaded report, you can:
   * Use the **Transaction ID** from the [Activity report](#generate-activity-report) to filter the **PayPal Reference ID** column and track specific transactions.
   * Use the T-codes in the **Transaction Event Code** column to find the type of payout transaction. For more information about T-codes, see [Understand transaction event codes](#understand-transaction-event-codes).

For more information, see the <a href="https://developer.paypal.com/docs/reports/sftp-reports/transaction-detail/">Transaction Detail Report Specification</a>.

## Access stage reports for large-batch file transfer

PayPal provides the <a href="/growth/payouts/send-money/use-large-batch-file-transfer#3-review-stage-reports">stage reports</a> for payouts made through large-batch file transfer.

To access these reports:

1. Connect to the DropZone SFTP server using your credentials.
2. Go to the `Outgoing` folder on PayPal's DropZone SFTP server.
3. Download the report files in `.csv` format.

## View transaction log

1. Log into your <a href="https://www.paypal.com">PayPal business account</a>.
2. You can view the transaction log using one of these ways:
   * Go to **Activity** > **All transactions**.
   * From the dashboard, go to **Recent activity** section > select **View Activity**.
3. On Transactions page, select **Filter**.
4. Choose **Payouts** as the **Transaction type**.
5. Select the date range. By default, the Transactions page displays a list of transactions from last 30 days. You can view payout transactions for any date range in the last three years.
6. Optional: Adjust other search filters.
7. Select **Apply filters**. The search results display transaction list that matches your criteria, showing:
   * Date
   * Type
   * Name
   * Status
   * Gross Amount
   * Fee
   * Net Amount
8. Select the payout transaction you want to review.
9. On the Transaction details page, you can review the payout details.
10. Select **Download (CSV)** or **Download (TXT)** to download the payment log and view all the individual payment details. If the payout required currency conversion, the log includes the exchange rate, fee, and total amount in both currencies.

Transaction logs also include error and reason codes. For more information, see [Review error and reason codes](#review-error-and-reason-codes).

### Review error and reason codes

The following errors may occur when PayPal processes your payouts. After you review and fix the errors, retry the payout.

| Reason  | Error code                                                  | Description                                                                                                                                                                                                                                                 |
| ------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`   | `ITEM_ALREADY_CANCELLED`                                    | Requested item is already cancelled.                                                                                                                                                                                                                        |
| `400`   | `ITEM_CANCELLATION_FAILED`                                  | Requested item is already cancelled.                                                                                                                                                                                                                        |
| `400`   | `ITEM_INCORRECT_STATUS`                                     | You can only cancel items that are in `UNCLAIMED` state.                                                                                                                                                                                                    |
| `400`   | `USER_BUSINESS_ERROR`                                       | A business error occurred for the user.                                                                                                                                                                                                                     |
| `403`   | `REQUIRED_SCOPE_MISSING`                                    | Access token does not have the required scope.                                                                                                                                                                                                              |
| `403`   | `SENDER_ACCOUNT_UNVERIFIED`                                 | Verify your account to send a payout. To verify your account, confirm your bank account or credit card. For assistance, contact your account manager or <a href="https://www.paypal.com/in/smarthelp/contact-us">customer support</a>.                      |
| `429`   | `RATE_LIMIT_VALIDATION_FAILURES`                            | Request blocked due to multiple failed attempts. Try again later.                                                                                                                                                                                           |
| `504`   | `REQUEST_TIMEOUT_EXCEEDED`                                  | System did not respond within the timeout period. Try again later.                                                                                                                                                                                          |
| `1000`  | `UNDEFINED`                                                 | An error occurred while processing this payout request. Try again later or make a new request.                                                                                                                                                              |
| `1002`  | `INSUFFICIENT_FUNDS`                                        | To complete the payout transaction, add money to your account.                                                                                                                                                                                              |
| `1003`  | `USER_COUNTRY_NOT_ALLOWED`                                  | Payouts not allowed in the country mentioned in your address. For assistance, contact your account manager or <a href="https://www.paypal.com/in/smarthelp/contact-us">customer support</a>.                                                                |
| `1004`  | `USER_FUNDING_SOURCE_INELIGIBLE`                            | Funding source for this transaction is not allowed. Try again using your PayPal balance.                                                                                                                                                                    |
| `1005`  | `PENDING_RECIPIENT_NON_HOLDING_CURRENCY_PAYMENT_PREFERENCE` | Transaction is pending because the recipient has set their account preferences to review credits in this currency. PayPal has notified the recipient. Check the payout status later.                                                                        |
| `3004`  | `SELF_PAY_NOT_ALLOWED`                                      | You cannot send a payout to yourself. Try sending it to a different account.                                                                                                                                                                                |
| `3014`  | `SENDER_ACCOUNT_LOCKED`                                     | Account locked or inactive. Cannot send a payout now, For assistance, contact your account manager or <a href="https://www.paypal.com/in/smarthelp/contact-us">customer support</a>.                                                                        |
| `3015`  | `RECEIVER_ACCOUNT_LOCKED`                                   | Recipient's account locked or inactive. Cannot send a Payouts now. Money returned to your account.                                                                                                                                                          |
| `3017`  | `SPENDING_LIMIT_EXCEEDED`                                   | Exceeded your spending limit. For assistance, contact your account manager or <a href="https://www.paypal.com/in/smarthelp/contact-us">customer support</a>.                                                                                                |
| `3047`  | `ACCOUNT_RESTRICTED`                                        | Restricted account access. For assistance, contact your account manager or <a href="https://www.paypal.com/in/smarthelp/contact-us">customer support</a>.                                                                                                   |
| `3078`  | `NEGATIVE_BALANCE`                                          | Insufficient amount in your PayPal balance. Add funds to your account to complete the payout.                                                                                                                                                               |
| `3107`  | `REFUSED_RECEIVER_REFUSED`                                  | Recipient refused payout in this currency. Try resending in a different currency.                                                                                                                                                                           |
| `3141`  | `REFUSED_ACTION_DENIED`                                     | Access denied. This merchant cannot use the send money option.                                                                                                                                                                                              |
| `3148`  | `RECEIVER_COUNTRY_NOT_ALLOWED`                              | PayPal cannot send this payout because the recipient lives in a country where Payouts are not allowed.                                                                                                                                                      |
| `3501`  | `INVALID_EMAIL_ID`                                          | Email ID entered for this recipient is invalid.                                                                                                                                                                                                             |
| `3547`  | `SENDER_STATE_RESTRICTED`                                   | Cannot send this transaction since your address is in a restricted state.                                                                                                                                                                                   |
| `3558`  | `RECEIVER_STATE_RESTRICTED`                                 | Cannot send this transaction because the recipient lives in a state where Payouts are not allowed.                                                                                                                                                          |
| `3769`  | `CLOSED_MARKET`                                             | Account is not allowed to receive Payouts from other countries. Try resending this payout to another account.                                                                                                                                               |
| `4002`  | `INTERNAL_ERROR`                                            | Internal error occurred during payout request processing. Retry this payout as a new batch or file.                                                                                                                                                         |
| `8304`  | `ACCOUNT_UNCONFIRMED_EMAIL`                                 | Verify your PayPal account to send Payouts. To verify your account, confirm your email and your bank account or credit card. For assistance, contact your account manager or <a href="https://www.paypal.com/in/smarthelp/contact-us">customer support</a>. |
| `8319`  | `ZERO_AMOUNT`                                               | Provide a valid payment amount.                                                                                                                                                                                                                             |
| `8330`  | `RECEIVING_LIMIT_EXCEEDED`                                  | Recipient cannot accept this Payouts because it exceeds the amount they can receive at this time. Resubmit your payout request for a different amount.                                                                                                      |
| `8331`  | `DUPLICATE_ITEM`                                            | Duplicate transaction in the batch. Check the reference ID and sender ID.                                                                                                                                                                                   |
| `9302`  | `RISK_DECLINE`                                              | Transaction declined due to risk concerns.                                                                                                                                                                                                                  |
| `9500`  | `GAMER_FAILED_COUNTRY_OF_RESIDENCE_CHECK`                   | Recipient lives in a country that is not allowed to accept this Payouts transaction.                                                                                                                                                                        |
| `9501`  | `GAMER_FAILED_FUNDING_SOURCE_CHECK`                         | Funding source that was selected for this payout is not allowed. Try again using your PayPal balance.                                                                                                                                                       |
| `9502`  | `GAMING_INVALID_PAYMENT_FLOW`                               | Payment flow is not allowed for gaming merchant accounts.                                                                                                                                                                                                   |
| `11711` | `TRANSACTION_LIMIT_EXCEEDED`                                | Payouts request exceeds the limit for this type of transaction. The money has been returned to your account.                                                                                                                                                |
| `14159` | `CURRENCY_NOT_SUPPORTED_FOR_RECEIVER`                       | Recipient's account does not support this currency. Resend this payout with a different currency.                                                                                                                                                           |
| `14550` | `CURRENCY_COMPLIANCE`                                       | Transaction not allowed, due to currency compliance regulations.                                                                                                                                                                                            |
| `14763` | `REGULATORY_PENDING`                                        | Transaction is pending while it is reviewed for compliance with government regulations.                                                                                                                                                                     |
| `14764` | `REGULATORY_BLOCKED`                                        | Transaction blocked due to regulatory compliance restrictions.                                                                                                                                                                                              |
| `14765` | `RECEIVER_UNREGISTERED`                                     | Recipient for this payout does not have an account. Sent a sign up link to the recipient. However, if the recipient does not claim this Payouts amount within 30 days, money returns to your account.                                                       |
| `14766` | `RECEIVER_UNCONFIRMED`                                      | Recipient's email or phone number is unconfirmed. Until the recipient confirms their account information, payments made to this account will be marked `UNCLAIMED`. Money will be returned to your account if they are not claimed within 30 days.          |
| `14767` | `RECEIVER_YOUTH_ACCOUNT`                                    | Unable to send Payouts because the recipient has a youth account. Check with the recipient for an alternate account to receive the money.                                                                                                                   |
| `14776` | `TRANSACTION_DECLINED_BY_TRAVEL_RULE`                       | An error occurred while processing this payout request. Try resending as part of a new request or file later. For assistance, contact your account manager or <a href="https://www.paypal.com/in/smarthelp/contact-us">customer support</a>.                |
| `14800` | `POS_LIMIT_EXCEEDED`                                        | You have exceeded the POS cumulative spending limit. For assistance, contact your account manager or <a href="https://www.paypal.com/in/smarthelp/contact-us">customer support</a>.                                                                         |
| `14801` | `UNVERIFIED_RECIPIENT_NOT_SUPPORTED`                        | Payout request incomplete because of unverified recipient account. Your account can send Payouts only to verified accounts.                                                                                                                                 |
| `14802` | `NON_HOLDING_CURRENCY`                                      | No PayPal balance in this currency. Try again with a currency that has money in your PayPal account, or change your account settings to this currency.                                                                                                      |


# Track payout item status
Source: https://docs.paypal.ai/growth/payouts/manage-payouts/track-payout-item-status



You can track the status of the individual payout items in a payout batch.

Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token">valid access token</a> and make a GET call to the `/v1/payments/payouts-item/{PAYOUT-ITEM-ID}` endpoint.<br />
**Path parameter**: `PAYOUT-ITEM-ID` is the `payout_item_id` returned as part of the <a href="/growth/payouts/send-money/use-payouts-api#2-track-status">payout batch details</a> response.

<CodeGroup>
  ```bash Sample request lines theme={null}
  curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/payouts-item/8AELMXH8UB2P8 \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer ACCESS-TOKEN'  
  ```

  ```json Sample response lines expandable theme={null}
  {
    "payout_item_id": "8AELMXH8UB2P8",
    "transaction_id": "0C413693MN970190K",
    "activity_id": "0E158638XS0329106",
    "transaction_status": "SUCCESS",
    "payout_item_fee": {
      "currency": "USD",
      "value": "0.35"
    },
    "payout_batch_id": "Q8KVJG9TZTNN4",
    "sender_batch_id": "Payouts_1753867886",
    "payout_item": {
      "recipient_type": "EMAIL",
      "amount": {
        "value": "9.87",
        "currency": "USD"
      },
      "note": "Thanks for your patronage!",
      "receiver": "receiver@example.com",
      "sender_item_id": "14Feb_234",
      "recipient_wallet": "PAYPAL",
      "purpose": "GOODS"
    },
    "time_processed": "2018-01-27T10:17:41Z",
    "links": [
      {
        "rel": "self",
        "href": "https://api-m.sandbox.paypal.com/v1/payments/payouts-item/8AELMXH8UB2P8",
        "method": "GET",
        "encType": "application/json"
      },
      {
        "href": "https://api-m.sandbox.paypal.com/v1/payments/payouts/Q8KVJG9TZTNN4",
        "rel": "batch",
        "method": "GET",
        "encType": "application/json"
      }
    ]
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response. The response includes the `transaction_status` parameter, which indicates the current status of the payout item.

The following table summarizes the possible values of `transaction_status` and what they mean:

| Status      | Description                                                                                                                                                                                                                                                                                                                                          | Possible management action                                                                                                                                       |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SUCCESS`   | PayPal has completed processing the payout and credited the money to the recipient's account.                                                                                                                                                                                                                                                        | No action required.                                                                                                                                              |
| `FAILED`    | The payout has failed. PayPal does not deduct money from your account.                                                                                                                                                                                                                                                                               | Review the failure reason and <a href="/growth/payouts/send-money/use-payouts-api#1-create-payout-batch">create a new payout request</a> if needed.              |
| `PENDING`   | PayPal is processing the payout.                                                                                                                                                                                                                                                                                                                     | Check the status again later.                                                                                                                                    |
| `UNCLAIMED` | The recipient has not claimed the payout. This typically occurs when the recipient does not have a PayPal or Venmo account. PayPal sends a signup link, and the payout status remains unclaimed until claimed or returned. For more information, see <a href="/growth/payouts/manage-payouts/handle-unclaimed-payouts">Handle unclaimed payouts</a>. | Notify the recipient to claim the payout.                                                                                                                        |
| `RETURNED`  | PayPal has returned the money to your account. This occurs when the recipient does not claim the payout or you cancel it.                                                                                                                                                                                                                            | <a href="/growth/payouts/send-money/use-payouts-api#1-create-payout-batch">Create a new payout request</a> if needed.                                            |
| `ONHOLD`    | PayPal has temporarily placed the payout on hold.                                                                                                                                                                                                                                                                                                    | Check the status again later.                                                                                                                                    |
| `BLOCKED`   | PayPal has blocked the payout.                                                                                                                                                                                                                                                                                                                       | Review the reason, resolve the issues, and <a href="/growth/payouts/send-money/use-payouts-api#1-create-payout-batch">create a new payout request</a> if needed. |
| `REFUNDED`  | The recipient has refunded the payout. PayPal returns the money to your account.                                                                                                                                                                                                                                                                     | No action required.                                                                                                                                              |
| `REVERSED`  | PayPal has reversed the payout. PayPal returns the money to your account. <Note>This status is specific to payouts created through web uploads.</Note>                                                                                                                                                                                               | No action required.                                                                                                                                              |


# PayPal Payouts overview
Source: https://docs.paypal.ai/growth/payouts/overview



PayPal Payouts helps you send secure, mass payouts to multiple recipients using just their email, phone number, PayPal ID, or Venmo handle. With PayPal Payouts, you can pay recipients in 96 countries and 24 currencies. Recipients can receive a payout in their PayPal or Venmo account.

## Key features

* **Mass payouts**: Send payments to multiple recipients at once to save time and reduce manual work.
* **Multi-currency support**: Expand your global reach by paying recipients in over 96 countries in their local currencies.
* **Flexible payout methods**: Improve recipient experience with two ways to claim payouts (PayPal and Venmo) and include custom messages for clear communication.
* **Automated operations**: Manage and track payouts easily through the PayPal dashboard, Payouts API, or webhooks.
* **Compliance and security**: Protect transactions and customer information with PayPal’s trusted security and compliance infrastructure.

## How it works

![How payouts work diagram](https://www.paypalobjects.com/ppdevdocs/how-payouts-work.png)

1. **Sender**: Initiates payouts using one of these integration patterns:
   * **Payouts Web UI file upload**: Creates a CSV file, uploads it to the PayPal account, and clicks **Send Payouts**.
   * **Large-batch file transfer**: Creates an input file and uploads it to the SFTP server.
   * **Payouts API**: Sends an API request.

2. **PayPal**: Starts payouts processing and confirms successful start in one of these ways:
   * **Payouts Web UI file upload status**: Updates the transaction status on the **Activity** page of the sender’s PayPal account.
   * **Large-batch file transfer acknowledgment**: Uploads an ACK report in the `Outgoing` folder on the SFTP server.
   * **Payouts API response**: Sends a response to the server that sent the API request.

3. **PayPal**: Notifies recipients about the payout.

4. **Recipient**: Claims the payout using one of the payout methods:
   * **Recipient with a PayPal or Venmo account**: Logs into their account and claims the payout.
   * **New recipient**: Opens a PayPal or Venmo account and claims the payout.

## Eligibility

**Available countries**: PayPal Payouts is available in 96 countries. See <a href="/growth/payouts/reference/countries-supported-features#eligible-countries-and-their-feature-sets">Supported countries</a>.

**Available currencies**: You can pay in 24 currencies. See the <a href="https://www.paypal.com/us/business/paypal-business-fees#paypal-payouts">PayPal Merchant Fees</a> page for supported currencies.

**Available features**: PayPal Payouts lets users send, receive, and withdraw money. Recipients can also withdraw money in their local currency. You can offer an experience to recipients that matches their local language needs. All these features fall into four sets. Each country has a feature set and businesses in that country can use the features in their set. For information on countries and eligible feature sets, see <a href="/growth/payouts/reference/countries-supported-features#feature-sets-and-what-they-mean">Countries and supported features</a>.

**Account type - Business account**: To integrate PayPal Payouts, PayPal must approve your business account for Payouts. <a href="https://www.paypal.com/payoutsweb/landing">Request access to the Payouts feature</a>. PayPal notifies you about your access status through email.

## Important information

Ensure to review the following information before you send payouts.

### Sender fee

* PayPal applies a fee to each payout transaction. This fee is either a percentage of the payout amount or a flat rate if the sender uses Payouts API.
* Each transaction has a maximum fee limit, which depends on the payment currency.
* PayPal does not charge recipients any fees to receive payouts.
* Venmo payouts incur the same fee as PayPal Payouts in the US.
* If a payout requires currency conversion, extra charges apply. See <a href="/growth/payouts/reference/countries-supported-features#currency-conversion">PayPal currency conversion</a>.

<Note>For accurate and up-to-date fee details, see the <a href="https://www.paypal.com/us/business/paypal-business-fees#paypal-payouts">PayPal Merchant Fees</a> page.</Note>

### Payout limits

The following table shows the individual and total payout limits for PayPal Payouts:

| Country         | Individual payout maximum                              | Total payout maximum |
| --------------- | ------------------------------------------------------ | -------------------- |
| U.S.            | \$20,000.00 USD                                        | Unlimited            |
| Other countries | Up to \$20,000.00 USD in your country's local currency | Unlimited            |


# Send, track, and manage payouts to multiple recipients
Source: https://docs.paypal.ai/growth/payouts/paypal-enterprise-payouts



Payouts helps businesses pay multiple recipients—vendors, contractors, employees, or customers—across regions in various currencies. PayPal offers two payout solutions to meet different business needs, from basic to enterprise-scale.

<Columns>
  <Card title="PayPal Payouts" href="/growth/payouts/overview">
    A basic solution for sending batch payments using recipients' email addresses, phone numbers, or PayPal IDs.
  </Card>

  <Card title="Enterprise Payouts - Hyperwallet" href="https://docs.hyperwallet.com/content/hyperwallet-payout-documentation">
    An enterprise solution for businesses with global operations or complex payout requirements.
  </Card>
</Columns>

## PayPal and enterprise payouts features

| Feature                                                 | PayPal | Enterprise |
| ------------------------------------------------------- | :----: | :--------: |
| Pay with PayPal and Venmo                               |   ✔️   |     ✔️     |
| API integration                                         |   ✔️   |     ✔️     |
| Web-upload integration                                  |   ✔️   |     ✔️     |
| File-transfer integration                               |   ✔️   |     ✔️     |
| Manage a single payout program                          |   ✔️   |            |
| Self-serve onboarding                                   |   ✔️   |            |
| PayPal-managed experience                               |   ✔️   |            |
| Pay with physical or virtual prepaid card or eGift card |        |     ✔️     |
| Pay with check or cash at pickup                        |        |     ✔️     |
| Implement multiple programs with one integration        |        |     ✔️     |
| Personalized onboarding                                 |        |     ✔️     |
| Drop-in UI integration                                  |        |     ✔️     |
| Pay portal or embedded experience                       |        |     ✔️     |
| 1099 tax reporting                                      |        |     ✔️     |
| Detailed payee and transaction activity reporting       |        |     ✔️     |
| Multilingual payee support                              |        |     ✔️     |
| Supported currencies                                    |   20+  |     50+    |
| Supported countries and regions                         |   96   |    240+    |


# Plan your integration
Source: https://docs.paypal.ai/growth/payouts/plan-your-integration



Ensure you understand the integration patterns and payout methods available, before using PayPal Payouts to efficiently send payouts to your recipients.

## Choose integration pattern

PayPal Payouts provides three integration patterns to send payouts efficiently. Each integration pattern is designed to meet different business needs based on payout volume, automation requirements, and user's technical capabilities.

### 1. Payouts Web UI file upload

* **What it is**: A manual tool that lets you upload payout files from the PayPal account dashboard.
* **How it works**: You log into your PayPal account, go to the Payouts section, and upload the payouts file. PayPal processes the file and sends payouts.
* **Who should use it**: Best for businesses that send payouts less frequently and do not require automation. This integration pattern works well for businesses with limited technical expertise.
* **Key benefits**: Provides easy access from the PayPal dashboard and requires no technical setup.

### 2. Large-batch file transfer

* **What it is**: A batch processing tool that lets you send payouts by uploading files safely through SFTP (Secure File Transfer Protocol) to PayPal's DropZone.
* **How it works**: You prepare a payout file in the right format and upload it to the DropZone. PayPal processes the file and sends the payouts.
* **Who should use it**: Best for businesses that need to send large-scale payouts and prefer batch processing over real-time API calls. This integration pattern requires some technical skills to set up and manage SFTP.
* **Key benefits**: Handles large numbers of payouts efficiently and keeps file transfers secure.

### 3. Payouts API

* **What it is**: RESTful API that lets you to programmatically send payouts to multiple recipients.
* **How it works**: You integrate PayPal’s Payouts API into your system to automate payouts.
* **Who should use it**: Best for businesses with frequent, high payout volumes that require automation. This integration pattern works well for businesses with developers and technical expertise.
* **Key benefits**: Provides scalability, real-time processing, and full control over payouts.

## Choose payout method

You can send payouts to PayPal accounts and Venmo users. Each Send money section provides information that enables you to integrate the selected integration pattern and send payouts.


# Countries and supported features
Source: https://docs.paypal.ai/growth/payouts/reference/countries-supported-features



You can use the following information to review country and currency requirements before sending payouts.

<Warning>You can use Venmo as a payout method only for recipients in the United States.</Warning>

## Feature sets and what they mean

The following table summarizes the payout feature sets:

| Feature set                                   | Description                                                                                                                                                               |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Send, receive, and withdraw                   | Merchants can send payouts from this country. PayPal account holders can receive and withdraw money.                                                                      |
| Send, receive, and withdraw in local currency | Merchants can send payouts from this country. PayPal account holders can receive and withdraw money in local currency.                                                    |
| Fully localized                               | Merchants can send payouts from this country. PayPal account holders can receive and withdraw money in local currency. The PayPal app is available in the local language. |
| Receive and withdraw                          | Merchants cannot send payouts from this country. PayPal account holders can receive and withdraw money.                                                                   |

## Eligible countries and their feature sets

The following table lists countries eligible for payouts and their available feature sets:

| Country              | Feature set                                   | Country Code |
| -------------------- | --------------------------------------------- | ------------ |
| Andorra              | Send, receive, and withdraw                   | `AD`         |
| Argentina            | Send, receive, and withdraw                   | `AR`         |
| Australia            | Fully localized                               | `AU`         |
| Austria              | Fully localized                               | `AT`         |
| Bahamas              | Send, receive, and withdraw                   | `BS`         |
| Bahrain              | Send, receive, and withdraw                   | `BH`         |
| Belgium              | Fully localized                               | `BE`         |
| Bermuda              | Send, receive, and withdraw                   | `BM`         |
| Botswana             | Send, receive, and withdraw                   | `BW`         |
| Brazil¹              | Fully localized                               | `BR`         |
| Bulgaria             | Send, receive, and withdraw                   | `BG`         |
| Canada               | Fully localized                               | `CA`         |
| Cayman Islands       | Send, receive, and withdraw                   | `KY`         |
| Chile                | Send, receive, and withdraw                   | `CL`         |
| China²               | Fully localized                               | `C2`         |
| Colombia³            | Send, receive, and withdraw                   | `CO`         |
| Costa Rica           | Send, receive, and withdraw                   | `CR`         |
| Croatia              | Send, receive, and withdraw                   | `HR`         |
| Cyprus               | Send, receive, and withdraw in local currency | `CY`         |
| Czech Republic       | Send, receive, and withdraw in local currency | `CZ`         |
| Denmark              | Fully localized                               | `DK`         |
| Dominican Republic   | Send, receive, and withdraw                   | `DO`         |
| Ecuador              | Send, receive, and withdraw in local currency | `EC`         |
| El Salvador          | Send, receive, and withdraw                   | `SV`         |
| Estonia              | Send, receive, and withdraw                   | `EE`         |
| Faroe Islands        | Send, receive, and withdraw                   | `FO`         |
| Finland              | Send, receive, and withdraw in local currency | `FI`         |
| France               | Fully localized                               | `FR`         |
| Georgia              | Send, receive, and withdraw                   | `GE`         |
| Germany              | Fully localized                               | `DE`         |
| Gibraltar            | Send, receive, and withdraw                   | `GI`         |
| Greece               | Send, receive, and withdraw in local currency | `GR`         |
| Greenland            | Send, receive, and withdraw                   | `GL`         |
| Guatemala            | Send, receive, and withdraw                   | `GT`         |
| Honduras             | Send, receive, and withdraw                   | `HN`         |
| Hong Kong SAR China  | Fully localized                               | `HK`         |
| Hungary              | Send, receive, and withdraw in local currency | `HU`         |
| Iceland              | Send, receive, and withdraw                   | `IS`         |
| India                | Receive and withdraw                          | `IN`         |
| Indonesia            | Send, receive, and withdraw                   | `ID`         |
| Ireland              | Send, receive, and withdraw                   | `IE`         |
| Israel               | Fully localized                               | `IL`         |
| Italy                | Fully localized                               | `IT`         |
| Jamaica              | Send, receive, and withdraw                   | `JM`         |
| Japan                | Fully localized                               | `JP`         |
| Jordan               | Send, receive, and withdraw                   | `JO`         |
| Kazakhstan           | Send, receive, and withdraw                   | `KZ`         |
| Kenya                | Send, receive, and withdraw                   | `KE`         |
| Kuwait               | Send, receive, and withdraw                   | `KW`         |
| Latvia               | Send, receive, and withdraw                   | `LV`         |
| Lesotho              | Send, receive, and withdraw                   | `LS`         |
| Liechtenstein        | Send, receive, and withdraw in local currency | `LI`         |
| Lithuania            | Send, receive, and withdraw                   | `LT`         |
| Luxembourg           | Send, receive, and withdraw in local currency | `LU`         |
| Malaysia¹            | Send, receive, and withdraw in local currency | `MY`         |
| Malta                | Send, receive, and withdraw in local currency | `MT`         |
| Mauritius            | Send, receive, and withdraw                   | `MU`         |
| Mexico               | Receive and withdraw                          | `MX`         |
| Moldova              | Send, receive, and withdraw                   | `MD`         |
| Monaco³              | Send, receive, and withdraw                   | `MC`         |
| Morocco              | Send, receive, and withdraw                   | `MA`         |
| Mozambique           | Send, receive, and withdraw                   | `MZ`         |
| Netherlands          | Fully localized                               | `NL`         |
| New Zealand          | Send, receive, and withdraw in local currency | `NZ`         |
| Nicaragua            | Send, receive, and withdraw                   | `NI`         |
| Norway               | Fully localized                               | `NO`         |
| Oman                 | Send, receive, and withdraw                   | `OM`         |
| Panama               | Send, receive, and withdraw                   | `PA`         |
| Peru                 | Send, receive, and withdraw                   | `PE`         |
| Philippines          | Send, receive, and withdraw in local currency | `PH`         |
| Poland               | Fully localized                               | `PL`         |
| Portugal             | Fully localized                               | `PT`         |
| Qatar                | Send, receive, and withdraw                   | `QA`         |
| Réunion              | Send, receive, and withdraw                   | `RE`         |
| Romania              | Send, receive, and withdraw                   | `RO`         |
| San Marino           | Send, receive, and withdraw in local currency | `SM`         |
| Saudi Arabia         | Send, receive, and withdraw                   | `SA`         |
| Senegal              | Send, receive, and withdraw                   | `SN`         |
| Serbia               | Send, receive, and withdraw                   | `RS`         |
| Singapore            | Fully localized                               | `SG`         |
| Slovakia             | Send, receive, and withdraw                   | `SK`         |
| Slovenia             | Send, receive, and withdraw in local currency | `SI`         |
| South Africa         | Send, receive, and withdraw                   | `ZA`         |
| Spain                | Fully localized                               | `ES`         |
| Sweden               | Fully localized                               | `SE`         |
| Switzerland          | Fully localized                               | `CH`         |
| Turkey               | Fully localized                               | `TR`         |
| United Arab Emirates | Send, receive, and withdraw                   | `AE`         |
| United Kingdom       | Fully localized                               | `GB`         |
| United States        | Fully localized                               | `US`         |
| Uruguay              | Send, receive, and withdraw                   | `UY`         |
| Venezuela            | Send, receive, and withdraw                   | `VE`         |
| Vietnam              | Send, receive, and withdraw                   | `VN`         |

¹ This country has currency restrictions.

² PayPal China Platform allows merchants in China to receive cross-border payments and to have foreign currency payments settle in `CNY`.

³ This country can only send and receive cross-border payments.

## Country-specific payout restrictions

The following table lists countries with specific payout restrictions:

| Country  | Currency code | Restriction details                                                                                                                                                                                                                                                                                         |
| -------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Brazil   | `BRL`         | <ul><li>Supported as a payout and balance for in-country PayPal accounts only.</li><li>If the recipient is not from Brazil, PayPal converts funds into the primary currency of the recipient's account. The conversion rate includes PayPal’s spread or fee.</li></ul>                                      |
| Malaysia | `MYR`         | <ul><li>Malaysian users can send payouts in <code>MYR</code> to other Malaysian users and send payouts in other currencies to all users.</li><li>Malaysian users cannot send payouts that require exchange to or from <code>MYR</code>, or send <code>MYR</code> balances to non-Malaysian users.</li></ul> |
| China    | `CNY`         | PayPal China Platform allows merchants to receive cross-border payouts and settle in <code>CNY</code>.                                                                                                                                                                                                      |
| Colombia | `COP`         | Can only send and receive cross-border payouts.                                                                                                                                                                                                                                                             |
| Monaco   | `EUR`         | Can only send and receive cross-border payouts.                                                                                                                                                                                                                                                             |

## Currency conversion

PayPal Payouts supports automatic currency conversion when the payout currency differs from the recipient’s account currency. However, some countries and currencies have exclusions or restrictions.

Before initiating a payout with currency conversion, you can:

* Check the recipient’s country and currency eligibility.
* Review the exclusion and restriction rules for countries to avoid payout failures.
* Use the supported currency list to determine if automatic conversion is available for your use case.

<Note>The conversion rate applied to payouts includes PayPal’s spread or fee. For more information, see the <a href="https://www.paypal.com/us/business/paypal-business-fees#paypal-payouts">PayPal Merchant Fees</a> page.</Note>

### Exclusions

Currency conversion is not available for payouts to the following countries and regions:

**Asia**

* China
* India
* South Korea
* Taiwan
* Thailand
* Turkey

**Caribbean**

* Anguilla
* Antigua and Barbuda
* Aruba
* Bahamas
* Barbados
* Bermuda
* British Virgin Islands
* Cayman Islands
* Falkland Islands
* Grenada
* Jamaica
* Montserrat
* Netherlands Antilles
* Saint Vincent and the Grenadines
* Suriname

<Note>For the Caribbean, you can send payouts in `USD`. Recipients can withdraw their balance in local currency from their bank.</Note>

**Latin America**

* Argentina
* Bolivia
* Chile
* Colombia
* Costa Rica
* Dominican Republic
* Ecuador
* El Salvador
* Guatemala
* Guyana
* Honduras
* Nicaragua
* Panama
* Paraguay
* Peru
* Uruguay
* Venezuela

<Note>For Latin America, you can send payouts in `USD`. Recipients can withdraw their balance in local currency from their bank.</Note>

### Restrictions

The following table lists the countries that have specific restrictions on currency conversion for payouts:

| Country  | Currency | Restrictions                                                                                                                                                                                                                                                            |
| -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Brazil   | `BRL`    | Brazilian users can send payments and hold balances in `BRL` for in-country PayPal accounts only. If the recipient is not from Brazil, PayPal converts funds into the primary currency of the recipient's account. The conversion rate includes PayPal’s spread or fee. |
| Malaysia | `MYR`    | Malaysian users can send payments in `MYR` to other Malaysian users and send payments in other currencies to all users. Malaysian users cannot send payments that require exchange to or from `MYR`, or send `MYR` balances to non-Malaysian users.                     |

### Supported currencies for automatic conversion

When you send a payout in a currency different from the recipient’s account currency, PayPal automatically converts the amount using the applicable exchange rate, which includes PayPal’s currency conversion spread or fee.

| Currency             | Code  |
| -------------------- | ----- |
| Australian dollar    | `AUD` |
| Canadian dollar      | `CAD` |
| Euro                 | `EUR` |
| Mexican peso         | `MXN` |
| Pound sterling       | `GBP` |
| United States dollar | `USD` |
| Swiss franc          | `CHF` |
| Swedish krona        | `SEK` |
| Polish złoty         | `PLN` |
| Norwegian krone      | `NOK` |
| Hungarian forint     | `HUF` |
| Danish krone         | `DKK` |
| Czech koruna         | `CZK` |
| Israeli shekel       | `ILS` |
| Hong Kong dollar     | `HKD` |
| New Zealand dollar   | `NZD` |
| Indonesian rupiah    | `IDR` |
| Philippine peso      | `PHP` |
| Japanese yen         | `JPY` |
| Singapore dollar     | `SGD` |


# Payouts API - test values
Source: https://docs.paypal.ai/growth/payouts/reference/payouts-api-test-values



You can use predefined test values to simulate a variety of positive and negative API responses.

<Note>Test values are case-sensitive.</Note>

## Create payout batch

Use the test values in the request payload to simulate both positive and negative responses.

**Endpoint**: `POST v1/payments/payouts/`

**Positive response test values**

| Trigger        | Test value | Simulated response                         |
| -------------- | ---------- | ------------------------------------------ |
| items\[0]/note | POSPYO001  | PAYLOAD WITH `201` RESPONSE CODE           |
| items\[0]/note | POSPYO003  | PAYLOAD WITH `201` RESPONSE CODE FOR VENMO |

**Negative response test values**

| Trigger                     | Test value | Simulated error response                  |
| --------------------------- | ---------- | ----------------------------------------- |
| items\[0]/note              | ERRPYO001  | `SENDER_RESTRICTED`                       |
| items\[0]/note              | ERRPYO002  | `SENDER_EMAIL_UNCONFIRMED`                |
| items\[0]/note              | ERRPYO003  | `AUTHORIZATION_ERROR`                     |
| items\[0]/note              | ERRPYO005  | `INSUFFICIENT_FUNDS`                      |
| items\[0]/note              | ERRPYO006  | `INTERNAL_ERROR`                          |
| items\[0]/note              | ERRPYO010  | `VALIDATION_ERROR`                        |
| items\[0]/note              | ERRPYO011  | `REQUIRED_SCOPE_MISSING`                  |
| items\[0]/note              | ERRPYO012  | `SENDER_LOCKED`                           |
| items\[0]/sender\_batch\_id | ERRPYO013  | `VALIDATION_ERROR FOR VENMO NOTE MISSING` |
| items\[0]/note              | ERRPYO014  | `USER_BUSINESS_ERROR`                     |
| items\[0]/note              | ERRPYO035  | `RATE_LIMIT_VALIDATION`                   |
| items\[0]/note              | ERRPYO036  | `REQUEST_TIMEOUT_EXCEEDED`                |
| items\[0]/note              | ERRPYO037  | `SYNC_MODE_NOT_APPLICABLE`                |
| items\[0]/note              | ERRPYO038  | `NON_HOLDING_CURRENCY`                    |
| items\[0]/note              | ERRPYO039  | `PREVIOUS_REQUEST_IN_PROGRESS`            |
| items\[0]/note              | ERRPYO040  | `CIP_NOT_VERIFIED`                        |

## Track status

Use the test values as path parameters in the request URL to simulate both positive and negative responses.

**Endpoint**: `GET v1/payments/payouts/{id}`

**Positive response test values**

| Path parameter                  | Simulated response |
| ------------------------------- | ------------------ |
| /v1/payments/payouts/ERRPYOB001 | `SUCCESS`          |
| /v1/payments/payouts/ERRPYOB002 | `PENDING`          |
| /v1/payments/payouts/ERRPYOB003 | `PROCESSING`       |

**Negative response test values**

| Path parameter                  | Simulated response |
| ------------------------------- | ------------------ |
| /v1/payments/payouts/ERRPYOB004 | `DENIED`           |

## Show payout details

Use the test values as path parameters in the request URL to simulate both positive and negative responses.

**Endpoint**: `GET v1/payments/payouts/{id}`

**Positive response test values**

| Path parameter                 | Simulated response               |
| ------------------------------ | -------------------------------- |
| /v1/payments/payouts/POSPYO002 | PAYLOAD WITH `200` RESPONSE CODE |

**Negative response test values**

| Path parameter                  | Simulated error response                                    |
| ------------------------------- | ----------------------------------------------------------- |
| /v1/payments/payouts/ERRPYOB005 | `ACCOUNT_RESTRICTED`                                        |
| /v1/payments/payouts/ERRPYOB006 | `ACCOUNT_UNCONFIRMED_EMAIL`                                 |
| /v1/payments/payouts/ERRPYOB007 | `APPROVER_DENIED`                                           |
| /v1/payments/payouts/ERRPYOB008 | `GAMER_FAILED_COUNTRY_OF_RESIDENCE_CHECK`                   |
| /v1/payments/payouts/ERRPYOB009 | `GAMER_FAILED_FUNDING_SOURCE_CHECK`                         |
| /v1/payments/payouts/ERRPYOB010 | `GAMING_INVALID_PAYMENT_FLOW`                               |
| /v1/payments/payouts/ERRPYOB011 | `NON_HOLDING_CURRENCY`                                      |
| /v1/payments/payouts/ERRPYOB012 | `PENDING_RECIPIENT_NON_HOLDING_CURRENCY_PAYMENT_PREFERENCE` |
| /v1/payments/payouts/ERRPYOB013 | `SENDER_STATE_RESTRICTED`                                   |
| /v1/payments/payouts/ERRPYOB014 | `SPENDING_LIMIT_EXCEEDED`                                   |
| /v1/payments/payouts/ERRPYOB015 | `TRANSACTION_DECLINED_BY_TRAVEL_RULE`                       |
| /v1/payments/payouts/ERRPYO015  | `CLOSED_MARKET`                                             |
| /v1/payments/payouts/ERRPYO016  | `CURRENCY_COMPLIANCE`                                       |
| /v1/payments/payouts/ERRPYO017  | `CURRENCY_NOT_SUPPORTED_FOR_RECEIVER`                       |
| /v1/payments/payouts/ERRPYO018  | `DUPLICATE_ITEM`                                            |
| /v1/payments/payouts/ERRPYO019  | `RECEIVER_ACCOUNT_LOCKED`                                   |
| /v1/payments/payouts/ERRPYO020  | `RECEIVER_COUNTRY_NOT_ALLOWED`                              |
| /v1/payments/payouts/ERRPYO021  | `RECEIVER_UNCONFIRMED`                                      |
| /v1/payments/payouts/ERRPYO022  | `RECEIVER_UNREGISTERED`                                     |
| /v1/payments/payouts/ERRPYO023  | `RECEIVER_YOUTH_ACCOUNT`                                    |
| /v1/payments/payouts/ERRPYO024  | `RECEIVING_LIMIT_EXCEEDED`                                  |
| /v1/payments/payouts/ERRPYO025  | `REGULATORY_BLOCKED`                                        |
| /v1/payments/payouts/ERRPYO026  | `REGULATORY_PENDING`                                        |
| /v1/payments/payouts/ERRPYO027  | `RISK_DECLINE`                                              |
| /v1/payments/payouts/ERRPYO028  | `SELF_PAY_NOT_ALLOWED`                                      |
| /v1/payments/payouts/ERRPYO029  | `TRANSACTION_LIMIT_EXCEEDED`                                |
| /v1/payments/payouts/ERRPYO030  | `UNDEFINED`                                                 |
| /v1/payments/payouts/ERRPYO031  | `ZERO_AMOUNT`                                               |
| /v1/payments/payouts/ERRPYO032  | `INVALID_RESOURCE_ID`                                       |
| /v1/payments/payouts/ERRPYO033  | `INTERNAL_ERROR`                                            |
| /v1/payments/payouts/ERRPYO034  | `INVALID_EMAIL`                                             |
| /v1/payments/payouts/ERRPYO060  | `RECEIVER_ACCOUNT_LIMITATION`                               |

## Cancel payout item

Use the test values as path parameters in the request URL to simulate both positive and negative responses.

**Endpoint**: `POST v1/payments/payouts-item/payouts_item_id/cancel`

**Positive response test values**

| Path parameter                             | Simulated response               |
| ------------------------------------------ | -------------------------------- |
| /v1/payments/payouts-item/POSPOI002/cancel | PAYLOAD WITH `200` RESPONSE CODE |

**Negative response test values**

| Path parameter                             | Simulated error response   |
| ------------------------------------------ | -------------------------- |
| /v1/payments/payouts-item/ERRPOI001/cancel | `INVALID_RESOURCE_ID`      |
| /v1/payments/payouts-item/ERRPYO004/cancel | `BATCH_NOT_COMPLETED`      |
| /v1/payments/payouts-item/ERRPYO007/cancel | `ITEM_ALREADY_CANCELLED`   |
| /v1/payments/payouts-item/ERRPYO008/cancel | `ITEM_CANCELLATION_FAILED` |
| /v1/payments/payouts-item/ERRPYO009/cancel | `ITEM_INCORRECT_STATUS`    |

## Show payout item details

Use the test values as path parameters in the request URL to simulate both positive and negative responses.

**Endpoint**: `GET v1/payments/payouts-item/{item-id}`

**Positive response test values**

| Path parameter                      | Simulated response          |
| ----------------------------------- | --------------------------- |
| /v1/payments/payouts-item/POSPOI001 | PAYLOAD WITH `200` RESPONSE |

**Negative response test values**

| Path parameter                        | Simulated error response                                    |
| ------------------------------------- | ----------------------------------------------------------- |
| /v1/payments/payouts-item/ERRPYO041   | `CLOSED_MARKET`                                             |
| /v1/payments/payouts-item/ERRPYO042   | `CURRENCY_COMPLIANCE`                                       |
| /v1/payments/payouts-item/ERRPYO043   | `CURRENCY_NOT_SUPPORTED_FOR_RECEIVER`                       |
| /v1/payments/payouts-item/ERRPYO044   | `RECEIVER_ACCOUNT_LOCKED`                                   |
| /v1/payments/payouts-item/ERRPYO045   | `RECEIVER_COUNTRY_NOT_ALLOWED`                              |
| /v1/payments/payouts-item/ERRPYO046   | `RECEIVER_UNCONFIRMED`                                      |
| /v1/payments/payouts-item/ERRPYO047   | `RECEIVER_UNREGISTERED`                                     |
| /v1/payments/payouts-item/ERRPYO048   | `RECEIVER_YOUTH_ACCOUNT`                                    |
| /v1/payments/payouts-item/ERRPYO049   | `RECEIVING_LIMIT_EXCEEDED`                                  |
| /v1/payments/payouts-item/ERRPYO050   | `REGULATORY_BLOCKED`                                        |
| /v1/payments/payouts-item/ERRPYO051   | `REGULATORY_PENDING`                                        |
| /v1/payments/payouts-item/ERRPYO052   | `RISK_DECLINE`                                              |
| /v1/payments/payouts-item/ERRPYO053   | `SELF_PAY_NOT_ALLOWED`                                      |
| /v1/payments/payouts-item/ERRPYO054   | `TRANSACTION_LIMIT_EXCEEDED`                                |
| /v1/payments/payouts-item/ERRPYO055   | `UNDEFINED`                                                 |
| /v1/payments/payouts-item/ERRPYO056   | `ZERO_AMOUNT`                                               |
| /v1/payments/payouts-item/ERRPYO057   | `INVALID_RESOURCE_ID`                                       |
| /v1/payments/payouts-item/ERRPYO058   | `INTERNAL_ERROR`                                            |
| /v1/payments/payouts-item/ERRPYO059   | `INVALID_EMAIL`                                             |
| /v1/payments/payouts-item/ERRPYO061   | `RECEIVER_ACCOUNT_LIMITATION`                               |
| /v1/payments/payouts-items/ERRPYOB016 | `ACCOUNT_RESTRICTED`                                        |
| /v1/payments/payouts-items/ERRPYOB017 | `ACCOUNT_UNCONFIRMED_EMAIL`                                 |
| /v1/payments/payouts-items/ERRPYOB018 | `APPROVER_DENIED`                                           |
| /v1/payments/payouts-items/ERRPYOB019 | `GAMER_FAILED_COUNTRY_OF_RESIDENCE_CHECK`                   |
| /v1/payments/payouts-items/ERRPYOB020 | `GAMER_FAILED_FUNDING_SOURCE_CHECK`                         |
| /v1/payments/payouts-items/ERRPYOB021 | `GAMING_INVALID_PAYMENT_FLOW`                               |
| /v1/payments/payouts-items/ERRPYOB022 | `NON_HOLDING_CURRENCY`                                      |
| /v1/payments/payouts-items/ERRPYOB023 | `PENDING_RECIPIENT_NON_HOLDING_CURRENCY_PAYMENT_PREFERENCE` |
| /v1/payments/payouts-items/ERRPYOB024 | `SENDER_STATE_RESTRICTED`                                   |
| /v1/payments/payouts-items/ERRPYOB025 | `SPENDING_LIMIT_EXCEEDED`                                   |
| /v1/payments/payouts-items/ERRPYOB026 | `TRANSACTION_DECLINED_BY_TRAVEL_RULE`                       |


# Payouts SDK
Source: https://docs.paypal.ai/growth/payouts/reference/payouts-sdk



You can use the PayPal Payouts SDK for Java or Python to work with the Payouts REST API. The SDK helps keep your integration up to date with API changes and is intended for server-side use only.

With the SDK, you can:

* Handle OAuth 2.0 authentication automatically.
* Call the Payouts API with less code.
* Manage API responses and handle errors.

<Note>If you want a more customized integration or use a language not supported by the SDK, use the Payouts API directly. For more information, see <a href="/growth/payouts/send-money/use-payouts-api">Use Payouts API</a>.</Note>

## Install SDK

Install the Payouts SDK in your preferred language.

<CodeGroup>
  ```bash Java lines theme={null}
  # Create a Java Maven or Gradle project in your directory, then add the following dependency to the project from Maven Central.
  <dependency>
    <groupId>com.paypal.sdk</groupId>
    <artifactId>payouts-sdk</artifactId>
    <version>1.1.1</version>
  </dependency>
  ```

  ```bash Python lines theme={null}
  # Create a Python project in your directory, then run the following command to install the PayPal Payouts Python SDK.
  pip install paypal-payouts-sdk
  ```
</CodeGroup>

## Set up your environment and credentials

1. Create a new file in your preferred language in the directory where you installed the SDK.
2. Copy the following code sample for your language to initialize the SDK and configure your environment.
3. Update the code with your PayPal client ID and secret.
4. Set the environment to `SandboxEnvironment` for testing or `LiveEnvironment` for production.

<CodeGroup>
  ```java Java lines expandable theme={null}
  import com.paypal.core.PayPalEnvironment;
  import com.paypal.core.PayPalHttpClient;

  public class PayPalClient 
  {
      /**
       * Set up PayPal SDK environment with your access credentials. 
       * This sample uses SandboxEnvironment. In production, use LiveEnvironment.
       */
      private PayPalEnvironment environment = new PayPalEnvironment.Sandbox(
          System.getProperty("PAYPAL_CLIENT_ID") != null ? System.getProperty("PAYPAL_CLIENT_ID") : "PAYPAL_CLIENT_ID", 
          System.getProperty("PAYPAL_CLIENT_SECRET") != null ? System.getProperty("PAYPAL_CLIENT_SECRET") : "PAYPAL_CLIENT_SECRET");
      /**
       * Returns a PayPal HTTP client instance.
       * Use this instance to call PayPal APIs.
       */
      PayPalHttpClient client = new PayPalHttpClient(environment);
      /**
       * Method to get client object
       * @return PayPalHttpClient client
       */ 
      public PayPalHttpClient client() 
      {
          return this.client;
      }
  }
  ```

  ```python Python lines expandable theme={null}
  import os
  from paypalpayoutssdk.core import PayPalHttpClient, SandboxEnvironment

  class PayPalClient:
      def __init__(self):
          self.client_id =  os.environ["PAYPAL_CLIENT_ID"] if 'PAYPAL_CLIENT_ID' in os.environ else "PAYPAL_CLIENT_ID"
          self.client_secret = os.environ["PAYPAL_CLIENT_SECRET"] if 'PAYPAL_CLIENT_SECRET' in os.environ else "PAYPAL_CLIENT_SECRET"
          
          # Set up and return PayPal Python SDK environment with PayPal Access credentials.
          # This sample uses SandboxEnvironment. In production, use LiveEnvironment.
          self.environment = SandboxEnvironment(client_id=self.client_id, client_secret=self.client_secret)
          # Returns a PayPal HTTP client instance.
          # Use this instance to call PayPal APIs.
          self.client = PayPalHttpClient(self.environment)
  ```
</CodeGroup>

<Note>For more information on finding your REST API credentials for both sandbox and live environments, see <a href="https://developer.paypal.com/api/rest/sandbox/accounts/">Sandbox accounts</a>.</Note>

## Create payout batch

Use the following code samples to create a payout batch.

<CodeGroup>
  ```java Java lines expandable theme={null}
  package com.paypal;

  import com.paypal.http.Encoder;
  import com.paypal.http.HttpResponse;
  import com.paypal.http.exceptions.HttpException;
  import com.paypal.http.serializer.Json;
  import com.paypal.payouts.Error;
  import com.paypal.payouts.*;
  import org.apache.commons.lang3.RandomStringUtils;
  import org.json.JSONObject;

  import java.io.ByteArrayInputStream;
  import java.io.IOException;
  import java.nio.charset.StandardCharsets;
  import java.util.List;
  import java.util.stream.Collectors;
  import java.util.stream.IntStream;

  public class CreatePayoutsBatch extends PayPalClient {
      private static final Encoder encoder = new Encoder();
      /**
       * This sample creates a payout batch with five payout items.
       * Calls the create batch payout API (POST - /v1/payments/payouts).
       * A maximum of 15000 payout items are supported in a single batch request.
       * @return - Response for the create batch payout call.
       * @throws IOException - Throws exception if the API call fails.
       */
      public HttpResponse<CreatePayoutResponse> createPayout() throws IOException {
          PayoutsPostRequest request = buildRequestBody(false);
          HttpResponse<CreatePayoutResponse> response = client().execute(request);
          System.out.println("Response Body:");
          System.out.println(new JSONObject(new Json().serialize(response.result())).toString(4));
          return response;
      }
      /**
       * Builds a request body to create payout batch with five payout items to receivers' email.
       * @param isValidationFailure - Includes validation failure in payload.
       * @return - Request payload for Payouts create (POST) request.
       */
      private PayoutsPostRequest buildRequestBody(boolean isValidationFailure) {
          List<PayoutItem> items = IntStream
                  .range(1, 6)
                  .mapToObj(index -> new PayoutItem()
                          .senderItemId("Test_txn_" + index)
                          .note("Thank you for your business!")
                          .receiver("payout-sdk-" + index + "@paypal.com")
                          .amount(new Currency()
                                  .currency("USD")
                                  .value(isValidationFailure ? "1.0.0" : "1.00")))
                  .collect(Collectors.toList());
          CreatePayoutRequest payoutBatch = new CreatePayoutRequest()
                  .senderBatchHeader(new SenderBatchHeader()
                          .senderBatchId("Test_sdk_" + RandomStringUtils.randomAlphanumeric(7))
                          .emailMessage("SDK payouts test txn")
                          .emailSubject("This is a test transaction from SDK")
                          .recipientType("EMAIL"))
                  .items(items);
          return new PayoutsPostRequest()
                  .requestBody(payoutBatch);
      }
      /**
       * Driver method to execute this sample.
       * This creates a payout batch with five items and prints the response.
       * @param args
       * @throws IOException - Throws exception if the API call fails.
       */
      public static void main(String[] args) throws IOException {
          new CreatePayoutsBatch().createPayout();
      }
  }
  ```

  ```python Python lines expandable theme={null}
  import json
  import random
  import string
  from paypal_client import PayPalClient
  from paypalpayoutssdk.payouts import PayoutsPostRequest
  from paypalhttp.serializers.json_serializer import Json
  from paypalhttp.http_error import HttpError
  from paypalhttp.encoder import Encoder

  class CreatePayouts(PayPalClient):
      # Creates a payout batch with two payout items.
      # Calls the create batch payout API (POST - /v1/payments/payouts).
      # A maximum of 15000 payout items are supported in a single batch request.
      @staticmethod
      def build_request_body(include_validation_failure = False):
          senderBatchId = str(''.join(random.sample(string.ascii_uppercase + string.digits, k=7)))
          amount = "1.0.0" if include_validation_failure else "1.00"
          return {
              "sender_batch_header": {
                  "recipient_type": "EMAIL",
                  "email_message": "SDK payouts test txn",
                  "sender_batch_id": senderBatchId,
                      "email_subject": "This is a test transaction from SDK"
                  },
                  "items": [{
                      "note": "Thank you for your business!",
                      "amount": {
                          "currency": "USD",
                          "value": amount
                      },
                      "receiver": "payout-sdk-1@paypal.com",
                      "sender_item_id": "Test_txn_1"
                  }, {
                      "note": "Thank you for your business!",
                      "amount": {
                          "currency": "USD",
                          "value": amount
                      },
                      "receiver": "payout-sdk-2@paypal.com",
                      "sender_item_id": "Test_txn_2"
                  }]
              }

      def create_payouts(self, debug=False):
          request = PayoutsPostRequest()
          request.request_body(self.build_request_body(False))
          response = self.client.execute(request)
          if debug:
              print("Status Code: ", response.status_code)
              print("Payout Batch ID: " + response.result.batch_header.payout_batch_id)
              print("Payout Batch Status: " + response.result.batch_header.batch_status)
              print("Links: ")
              for link in response.result.links:
                  print('\t{}: {}\tCall Type: {}'.format(link.rel, link.href, link.method))
              # To toggle print the whole body comment/uncomment the below line
              # json_data = self.object_to_json(response.result)
              # print "json_data: ", json.dumps(json_data, indent=4)
          return response

  # Driver function which invokes the create_payouts function to create a payout batch.
  if __name__ == "__main__":
      CreatePayouts().create_payouts(debug=True)
  ```
</CodeGroup>

## Track status

Use the payout batch ID to retrieve the payout batch details.

<CodeGroup>
  ```java Java lines expandable theme={null}
  package com.paypal;

  import com.paypal.http.Encoder;
  import com.paypal.http.HttpResponse;
  import com.paypal.http.exceptions.HttpException;
  import com.paypal.http.serializer.Json;
  import com.paypal.payouts.CreatePayoutResponse;
  import com.paypal.payouts.Error;
  import com.paypal.payouts.PayoutBatch;
  import com.paypal.payouts.PayoutsGetRequest;
  import org.json.JSONObject;

  import java.io.ByteArrayInputStream;
  import java.io.IOException;
  import java.nio.charset.StandardCharsets;

  public class GetPayoutBatch extends PayPalClient {
      private static final Encoder encoder = new Encoder();
      /**
       * Uses the show payout batch details API (GET - /v1/payments/payouts/<batchId>) to retrieve the payout batch details. 
       * This paginated API supports retrieving a maximum of 1000 items per page. 
       * Check 'links' in the response for previous and next page of URIs.
       * Add 'totalRequired' parameter to know the total number of pages available.
       *
       * @param batchId - Id of a Payouts batch.
       * @return - Returns the details of the payout batch.
       * @throws IOException - Throws exception if the API call fails.
       */
      public HttpResponse<PayoutBatch> getPayoutBatch(String batchId) throws IOException {
          PayoutsGetRequest request = new PayoutsGetRequest(batchId)
                  //Optional parameters, maximum of 1000 items are retrieved by default.
                  .page(1)
                  .pageSize(10)
                  .totalRequired(true);
          try {
              HttpResponse<PayoutBatch> response = client().execute(request);
              System.out.println("Response Body:");
              System.out.println(new JSONObject(new Json().serialize(response.result())).toString(4));
              return response;
          } catch (IOException e) {
              //Client side failure
              System.out.println(e);
              throw e;
          }
      }
      /**
       * Driver method to execute this sample and retrieve the payout batch details.
       * To retrieve a valid Payouts batch it creates a Payouts Batch with 5 items and use that id for retrieval
       *
       * @param args
       * @throws IOException when call to the api fails
       */
      public static void main(String[] args) throws IOException {
          HttpResponse<CreatePayoutResponse> response = new CreatePayoutsBatch().createPayout();
          new GetPayoutBatch().getPayoutBatch(response.result().batchHeader().payoutBatchId());
      }
  }
  ```

  ```python Python lines expandable theme={null}
  # Creates a request to get the payout batch status
  import json
  from paypal_client import PayPalClient
  from paypalpayoutssdk.payouts import PayoutsGetRequest
  from create_payouts import CreatePayouts
  from paypalhttp.serializers.json_serializer import Json
  from paypalhttp.http_error import HttpError
  from paypalhttp.encoder import Encoder

  class GetPayouts(PayPalClient):
      # Retrieves a payout batch details based on the provided payout_batch_id.
      # This API is paginated and by default 1000 payout items are retrieved per page.
      # Use pagination links to navigate through all the items, add 'total_required' parameter to get the total pages.
      def get_payouts(self, payout_batch_id, debug=False):
          request = PayoutsGetRequest(payout_batch_id)
          request.page(1)
          request.page_size(10)
          request.total_required(True)
          try:
              response = self.client.execute(request)
              if debug:
                  print(response.result)
                  print("Status Code: ", response.status_code)
                  print("Payout Batch ID: " + response.result.batch_header.payout_batch_id)
                  print("Payout Batch Status: " + response.result.batch_header.batch_status)
                  print("Items count: ", len(response.result.items))
                  print("First item id: " + response.result.items[0].payout_item_id)
                  print("Links: ")
                  for link in response.result.links:
                      print('\t{}: {}\tCall Type: {}'.format(link.rel, link.href, link.method))
                  # To toggle print the whole body comment/uncomment the below line
                  # json_data = self.object_to_json(response.result)
                  # print "json_data: ", json.dumps(json_data, indent=4)
              return response
          except IOError as ioe:
              # Handles client side connection failures
              print(ioe.message)

  # This is the driver function which invokes the get_payouts function to retrieve the payouts batch details.
  if __name__ == "__main__":
      create_response = CreatePayouts().create_payouts(debug=True)
      batch_id = create_response.result.batch_header.payout_batch_id
      GetPayouts().get_payouts(batch_id, True)
  ```
</CodeGroup>

## SDK reference

* <a href="https://github.com/paypal/Payouts-Java-SDK">Payouts Java SDK</a>
* <a href="https://github.com/paypal/Payouts-Python-SDK">Payouts Python SDK</a>


# Use large-batch file transfer
Source: https://docs.paypal.ai/growth/payouts/send-money/use-large-batch-file-transfer



You can use this pattern to pay more than 15,000 people at once with a single payment file. Common use-cases for this functionality include payroll payouts, rebate payouts, reward payouts, and affiliate program payouts.

<Tip>You can send payouts to PayPal accounts and Venmo users.</Tip>

## Prerequisites

* Complete all mandatory steps to <a href="/growth/payouts/set-up#set-up-sftp-account">get started</a>.
* Ensure your <a href="/growth/payouts/set-up#set-up-live-account">PayPal business account is set up</a>.
* Ensure to <a href="/growth/payouts/set-up#fund-your-account">fund your business account</a>.

## Send payouts

You can use the procedures in this section to send payouts using the large-batch file transfer.

### 1. Create input file

1. **Add a summary line**: Follow <a href="#summary-line-format">the required format</a> and add a summary line as the first row of your file.
2. **Add payout records**: Follow <a href="#payout-item-row-format">the required format</a> and add each payment as a separate row.
3. Name your file using this pattern: `pp_payouts_<epoch_time>_<reference_name><format>` <br />**Example**: `pp_payouts_1728883200_batch1.csv`
   * `pp_payouts`: Always use these exact words in lowercase.
   * `<epoch_time>`: A special <a href="https://www.epochconverter.com/">time code</a> (from the past or up to 7 days ahead).
   * `<reference_name>`: Your chosen name using letters, numbers, underscore (\_), or hyphen (-). Maximum: 63 characters.
   * `<format>`: File type - use `.csv` or `.csv.gz`.

#### Summary line format

```csv Sample summary line theme={null}
PAYOUT_SUMMARY,1500.75,USD,5,"Thank you, ""Top Seller""!",Payout for May
```

| Field                                          | Description                                                                                        | Notes                                                                                                                                                                                                                               |
| :--------------------------------------------- | :------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Entry type <br /><span>Required</span>         | The first line must always contain `PAYOUT_SUMMARY`.                                               | Use uppercase only.<br /><br />**Example:** `PAYOUT_SUMMARY`                                                                                                                                                                        |
| Total payout amount<br /><span>Required</span> | Total of all payout items.                                                                         | Must be in decimal format.<br />Currency symbols not allowed.<br />Cannot be empty or zero.<br /><br />**Example:** `1500.75`                                                                                                       |
| Currency <br /><span>Required</span>           | Three-letter ISO 4217 currency code. Each file must contain only one currency type.                | Use separate files for different currencies.<br /><br />**Example:** `USD`<br />**Max length:** 3 characters                                                                                                                        |
| Total payments  <br /><span>Required</span>    | Total number of payout items in the file.                                                          | Use numbers only.<br /><br />**Example:** `5`                                                                                                                                                                                       |
| Email subject   <br /><span />                 | A standard subject line in the email notification sent to all recipients for each payout item.     | If text has commas or special characters, use double quotes (") around it.<br />If text has quotes, double them ("") and wrap in quotes.<br /><br />**Example:** `"Thank you, ""Top Seller""!"`<br />**Max length:** 256 characters |
| Email message    <br /><span />                | A standard message included in the email notification sent to all recipients for each payout item. | If text has commas or special characters, use double quotes (") around it.<br />If text has quotes, double them ("") and wrap in quotes.<br /><br />**Example:** `Payout for May`<br />**Max length:** 1000 characters              |

#### Payout item row format

```csv Sample payout line items theme={null}
PAYOUT,test@paypal.com,1000.50,USD,REF_ID_1,Thanks for your work
PAYOUT_VENMO,5551232368,500.25,USD,REF_ID_2,"Congrats!"
PAYOUT,test@paypal.com,1,USD,REF_ID_1,NOTE_1,,,AWARDS
```

<Note>If you skip any optional fields, add commas to keep the columns in the correct order.</Note>

| Field                                                            | Description                                                                         | Notes                                                                                                                                                                                                                               |
| :--------------------------------------------------------------- | :---------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Recipient wallet <br /><span>Required</span>                     | Target wallet for the payout.                                                       | Use uppercase only.<br /><br />**Possible values:**<br />• `PAYOUT`<br />• `PAYOUT_VENMO`                                                                                                                                           |
| Recipient identifier <br /><span>Required</span>                 | Identifier for the payout recipient based on the wallet type.                       | PayPal: Recipient’s PayPal-associated email address, phone number, or encrypted PayPal account number.<br />Venmo: Recipient’s US mobile number or Venmo handle.<br /><br />**Example:** `test@paypal.com`                          |
| Payout amount <br /><span>Required</span>                        | Amount to send.                                                                     | Use decimal format only (local currency formats are not supported). Cannot be empty or zero.<br /><br />**Example:** `100.50`                                                                                                       |
| Currency <br /><span>Required</span>                             | Three-letter ISO 4217 currency code. Each file must contain only one currency type. | Use separate files for different currencies.<br /><br />**Example:** `USD`<br />**Max length:** 3 characters                                                                                                                        |
| Reference ID                                                     | Unique identifier for each payout item.                                             | Use letters, numbers, underscore (\_), or hyphen (-).<br /><br />**Example:** `REF_ID_1`<br />**Max length:** 30 characters                                                                                                         |
| Item-level note <br /><span />                                   | Custom note included in the email for each payout item.                             | If text has commas or special characters, use double quotes (") around it.<br />If text has quotes, double them ("") and wrap in quotes.<br /><br />**Example:** `Thanks for your work`<br />**Max length:** 1000 characters        |
| Social feed privacy <br /><span>Venmo only</span>                | Visibility setting for the Venmo recipient’s social feed.                           | **Default value:** `PRIVATE`<br /><br />**Possible values:**<br />• `PUBLIC`<br />• `FRIENDS_ONLY`<br />• `PRIVATE`                                                                                                                 |
| Holler URL <span>Deprecated</span> <br /><span>Venmo only</span> | URL of a Holler sticker to include with the Venmo message.                          | **Example:** [https://example.com/sticker.png](https://example.com/sticker.png)<br />**Max length:** 151 characters                                                                                                                 |
| Logo URL <br /><span>Venmo only</span>                           | URL of the business logo shown in the Venmo feed.                                   | Image uploaded at the access URL must be a square image of max size 1024 × 1024 px.<br /><br />**Example:** [https://example.com/logo.png](https://example.com/logo.png)<br />**Max length:** 2000 characters                       |
| Purpose <br /><span />                                           | Reason for the transaction.                                                         | **Default value:** `GOODS`<br /><br />**Possible values:**<br />• `AWARDS`<br />• `PRIZES`<br />• `DONATIONS`<br />• `GOODS`<br />• `SERVICES`<br />• `REBATES`<br />• `CASHBACK`<br />• `DISCOUNTS`<br />• `NON_GOODS_OR_SERVICES` |

### 2. Upload input file

<Note>You can use your Sandbox DropZone credentials, log into the DropZone account, test your file upload, and rectify errors if any. You can then use your Production DropZone credentials and upload your file for payouts.</Note>

1. Connect to PayPal’s DropZone on the SFTP server using your <a href="/growth/payouts/set-up#set-up-sftp-account">SFTP login details</a>.
2. Go to the `Incoming` folder on the server and upload your file. PayPal checks the file and creates an acknowledgement report. See <a href="#file-validation-steps-and-outcomes">File validation steps and outcomes</a>. PayPal places the report in the `Outgoing` folder.
3. Review the report to verify the file validation status.

#### Acknowledgment reports

| <span>Report</span>     | <span>File name suffix</span> | <span>What it means</span>    | <span>What to do</span>                                     |
| ----------------------- | ----------------------------- | ----------------------------- | ----------------------------------------------------------- |
| Accepted (**ACK**)      | `_ack.csv`                    | File is ready for processing. | Wait for PayPal to process your payouts.                    |
| Not Accepted (**NACK**) | `_nack.csv`                   | File has errors.              | Fix the errors and upload a new file with a different name. |
| Duplicate (**DUPS**)    | `_dups.csv`                   | File name already used.       | Change the file name and upload again.                      |

**NACK report**

The NACK report consists of two types of errors lines.

* **Summary error line**

  * Columns: Entry type, Currency code, Error code, Error message

  ```csv Example theme={null}
  PAYOUT_SUMMARY,USD,INVALID_CURRENCY,Invalid currency code in line 3
  ```

* **Item-level error line**

  * Columns: Payout type, Line number, Reference ID, Error code, Error message

  ```csv Example theme={null}
  PAYOUT,3,REF_ID_1,INVALID_CURRENCY,Invalid currency code
  ```

For a complete list of possible error codes, see <a href="#file-validation-errors">File validation errors</a>.

**ACK report**

The ACK report shows:

* The date and time (in UTC) when PayPal received your file.
* Your original file name (without the ending).
* The status: `ACCEPTED_FOR_PROCESSING`.

```csv Example theme={null}
2018-02-26T05:48:53Z,pp_payouts_6627887729_testfile,ACCEPTED_FOR_PROCESSING
```

### 3. Review stage reports

As PayPal processes payouts, stage reports are saved in your `Outgoing` folder to help you track and match your payments.

| <span>Report</span>   | <span>When you get it</span>          | <span>What it shows</span>                                                                                           | <span>What to do</span>                                                 |
| --------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| Part File report      | After part of your file is processed. | Shows results for the processed part. Large files may have multiple part files as PayPal processes them in sections. | Check each part file to track progress and fix problems as they appear. |
| Out or Interim report | After your whole file is processed.   | Shows results for all payments in your file, including status and errors.                                            | Use this to check your records and confirm all payments were sent.      |
| Final report          | 31 days after the Interim report.     | Shows the final status of payments that were not claimed.                                                            | Check which payments were not claimed and decide what to do next.       |

<Note>If a recipient does not claim their payment within 30 days, PayPal automatically returns the money to your account.</Note>

#### Report file format

The Part, Out or Interim, and Final reports are `.csv` files that include the following columns:

* Reference ID
* Payout item ID
* Transaction ID
* Recipient name
* Recipient identifier
* Currency code
* Payout amount
* Fee
* Total
* Transaction status
* Error enum
* Error message
* Processed time
* Claimed time (applicable for unilateral case)

```csv Sample report entries theme={null}
REF_ID_1,SX3QT8QVBVE4L,35P324312A142790D,,test-1@paypal.com,USD,4.82,0.25,5.07,UNCLAIMED,RECEIVER_UNREGISTERED,Receiver is unregistered,2018-01-16T10:33:22Z
REF_ID_2,HP3B9BRJYMKRU,1H080416VK328525U,,bjonny-us4@paypal.com,USD,4.93,0.25,5.18,SUCCESS,,,2018-01-16T10:33:20Z
REF_ID_3,BUPR735Z5CJBJ,7FB53422KY616915S,,test-3@paypal.com,USD,2.77,0.25,3.02,UNCLAIMED,RECEIVER_UNREGISTERED,Receiver is unregistered,2018-01-16T10:33:19Z
REF_ID_6,AU49JFTXWUQ8Q,7RG81691FV520321P,,test-1@paypal.com,USD,0.86,0.25,1.11,UNCLAIMED,RECEIVER_UNREGISTERED,Receiver is unregistered,2018-01-16T10:33:20Z
REF_ID_7,C5USHNEDMCXWL,,,bjonny-us9@paypal.com,USD,1.71,0,1.71,FAILED,ACCOUNT_RESTRICTED,User is restricted,2018-01-16T10:33:16Z
```

## Reference

You can use the following information to understand the file validation process and errors. You can review the errors, fix them, and upload your payout file again.

### File validation steps and outcomes

The following table summarizes the various file validation steps and the possible results:

| <span>Validation step</span> | <span>What PayPal checks</span>                                                                                         | <span>Result</span>         |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| File exists                  | Checks if your file is in the folder.                                                                                   | `NACK` if missing           |
| File not empty               | Checks if your file has content and is not broken.                                                                      | `NACK` if empty or broken   |
| File encoding                | Makes sure your file uses UTF-8 text format.                                                                            | `NACK` if wrong format      |
| File format                  | Checks for correct file type (`.csv` or `.csv.gz`) and proper columns.                                                  | `NACK` if wrong             |
| File matches                 | Checks if summary totals match your payment details.                                                                    | `NACK` if they do not match |
| File name                    | Makes sure your file name follows the rules.                                                                            | `NACK` or `DUPS` if wrong   |
| Duplicate file               | Checks if you already sent a file with this name.                                                                       | `DUPS` if already used      |
| Sandbox limit                | Checks if you have too many items (sandbox only).                                                                       | `NACK` if too many          |
| Summary and line checks      | Checks for: text length, valid currency, one summary only, summary in first line, correct payment count, valid purpose. | `NACK` if wrong             |
| Payment details              | Checks each payment line has all needed info.                                                                           | `NACK` if missing info      |
| Amount and currency          | Makes sure amounts and currency codes are valid.                                                                        | `NACK` if wrong             |

### File validation errors

The following table summarizes the file validation errors that PayPal may find in your payout file:

| <span>Error</span>                  | <span>Description</span>                                                                                                                                                |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DUPLICATE_REF_ID`                  | Reference IDs must be unique within an input file.                                                                                                                      |
| `EMAIL_MESSAGE_EXCEEDED_MAX_SIZE`   | The email message exceeded the maximum character limit. The limit is 1000.                                                                                              |
| `EMAIL_SUBJECT_EXCEEDED_MAX_SIZE`   | The email subject exceeded the maximum character limit. The limit is 255.                                                                                               |
| `ENCODING_ERROR`                    | The payout input file is not in UTF-8 format.                                                                                                                           |
| `FILE_EMPTY_OR_CORRUPT`             | The payout input file is empty or corrupt and cannot be processed.                                                                                                      |
| `FILE_NOT_FOUND`                    | The file does not exist in the source folder. Contact our customer support.                                                                                             |
| `FILE_SIZE_ERROR`                   | The payout input file is empty.                                                                                                                                         |
| `GZ_FILE_CORRUPT_ERROR`             | The payout input file is corrupt or has a checksum issue.                                                                                                               |
| `INVALID_CURRENCY`                  | The currency code is invalid.                                                                                                                                           |
| `INVALID_FILE_FORMAT`               | The input file contains characters, columns, or details that are not required for processing payouts. Remove these characters, columns, or details and upload the file. |
| `INVALID_FILE_NAME`                 | The format of the file name is invalid.                                                                                                                                 |
| `INVALID_FIRST_COLUMN`              | The first column entry in the summary must be `PAYOUT_SUMMARY`. For an item record, this must be `PAYOUT`.                                                              |
| `INVALID_REF_ID_FORMAT`             | The reference ID must be alphanumeric. The maximum character limit is 63.                                                                                               |
| `INVALID_SUMMARY_LINE_POSITION`     | The payout summary record is missing from the first line in the payout input file.                                                                                      |
| `MANDATORY_COLUMN_MISSING`          | The file is missing mandatory columns. Please enter the required information and retry the Payout.                                                                      |
| `MULTI_CURRENCY_NOT_SUPPORTED`      | The payout input file has more than one currency.                                                                                                                       |
| `MULTIPLE_SUMMARY_RECORDS`          | The payout input file should contain only one summary record.                                                                                                           |
| `PAYOUT_AMOUNT_INVALID_FORMAT`      | The payout amount must use a decimal. Other special characters are not allowed.                                                                                         |
| `PAYOUT_AMOUNT_NON_POSITIVE`        | The payout amount must be greater than zero.                                                                                                                            |
| `SANDBOX_LIMIT_ERROR`               | The number of items in the file exceeds the sandbox file limit (sandbox only).                                                                                          |
| `SCHEDULED_TIME_ERROR`              | The payout can be scheduled a maximum of seven days in advance.                                                                                                         |
| `SUMMARY_AMOUNT_INVALID_FORMAT`     | The summary amount must be a decimal. Other special characters are not allowed.                                                                                         |
| `SUMMARY_AMOUNT_NON_POSITIVE`       | The total payout amount in the summary line must be greater than zero.                                                                                                  |
| `SUMMARY_AND_PAYOUT_MATCH_CONFLICT` | The payout amount in the summary line does not match the total item value.                                                                                              |
| `SUMMARY_LINES_NON_INTEGER`         | The total number of payments field in the summary line must be an integer.                                                                                              |
| `SUMMARY_LINES_NON_POSITIVE`        | The total number of payments field in summary line must be greater than zero.                                                                                           |
| `SUMMARY_MISSING`                   | The summary line is missing from the payout input file.                                                                                                                 |
| `TOTAL_PAYMENTS_MISMATCH`           | The `TOTAL_NO_OF_PAYMENTS` in the `PAYOUTS_SUMMARY` row must match the total records in the payout input file.                                                          |
| `INVALID_PURPOSE`                   | The purpose specified for the transaction is invalid.                                                                                                                   |


# Use Payouts API
Source: https://docs.paypal.ai/growth/payouts/send-money/use-payouts-api



You can use this pattern to send payouts to multiple recipients with a single API call.

<Tip>You can send payouts to PayPal accounts and Venmo users.</Tip>

**Useful resource**: <a href="https://www.paypal.com/apex/product-profile/payouts/getAccessToken">PayPal API Executor</a>

## Important information

Ensure to review the following information before you send payouts.

### Rate-limiting guideline

PayPal does not have a published rate-limiting policy. To ensure site security and stability for merchants, we might temporarily apply rate limiting if we see unusual or abusive traffic. We hold the rate limit until we know the traffic is safe. For Payouts API, we allow 400 POST requests per minute. If you get an HTTP `429 Unprocessable Entity - RATE_LIMIT_REACHED` message, you have exceeded the rate limit. If this affects your integration, contact <a href="https://www.paypal-techsupport.com/s/?language=en_US">Merchant Technical Support</a>.

You can <a href="#use-webhooks">use webhooks</a> for status updates instead of repeated API calls through <a href="#poll-for-updates">polling</a> and reuse <a href="#1-generate-access-token">OAuth 2.0 access tokens</a> (till their expiry time) to avoid unnecessary requests.

### Payouts SDK

You can use the PayPal Payouts SDK as an alternative to direct API integration. The SDK provides methods for authentication, request construction, and error handling in multiple programming languages. For more information, see <a href="/growth/payouts/reference/payouts-sdk">Payouts SDK</a>.

## End-to-end workflow

![Payouts API end-to-end workflow diagram](https://www.paypalobjects.com/ppdevdocs/Payouts%20APIs.png)

## Prerequisites

* Complete all mandatory steps to <a href="/growth/payouts/set-up#set-up-sandbox-account-for-payouts-api-integration">get started</a>.
* Ensure your <a href="/growth/payouts/set-up#set-up-live-account">PayPal business account is set up</a>.
* Ensure to <a href="/growth/payouts/set-up#fund-your-account">fund your business account</a>.

## Send payouts

You can use the procedures in this section to send payouts using the Payouts API.

### 1. Create payout batch

Use a <a href="https://docs.paypal.ai/developer/how-to/api/get-started#2-get-an-access-token">valid access token</a> and make a POST call to the `/v1/payments/payouts` endpoint.

<Tip>You can use the `PayPal-Request-Id` header parameter to <a href="/growth/payouts/customize/customize-payouts-api-integration#implement-idempotency">implement idempotency</a>.</Tip>

Include the following parameters:

| <span>Parameter </span>                                               | <span>Action</span>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sender_batch_header`<br /><span>Required</span>, <span>object</span> | Use the `sender_batch_id` within this header to <a href="/growth/payouts/customize/customize-payouts-api-integration#prevent-duplicate-requests">prevent duplicate requests</a>.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `items.amount`<br /><span>Required</span>, <span>object</span>        | To pay a recipient in their local currency, set the `currency` parameter to the <a href="/growth/payouts/reference/countries-supported-features#eligible-countries-and-their-feature-sets">local currency code</a>. PayPal converts the payment to the specified currency and applies conversion fees. When you <a href="#poll-for-updates">retrieve the payout details</a>, the response shows the funding source, payout amount, fees, and other currency conversion details. For a sample request and response for cross-currency payouts, see <a href="/growth/payouts/customize/customize-payouts-api-integration#pay-recipients-in-their-local-currency">Pay in local currency</a>.<br /><Note>Review <a href="/growth/payouts/reference/countries-supported-features#currency-conversion">country exclusions and restrictions</a> before sending cross-currency payouts.</Note> |
| `items.receiver`<br /><span>Required</span>, <span>string</span>      | Pass the value that identifies the recipient. <br />For example, [user@example.com](mailto:user@example.com), +15555550123, @venmousername, PAYPALUSERID123                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `items.recipient_type`<br /><span>string</span>                       | For Venmo payouts, set the recipient type to `USER_HANDLE` and pass the handle in `items.receiver`. <br /><br />**Possible values**: `PHONE`, `EMAIL`, `USER_HANDLE`, `PAYPAL_ID`<br /><br />**Default value**: `EMAIL` <br /><Note>If you set the recipient type in `sender_batch_header`, all items use that type unless you override it per item.</Note>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `items.recipient_wallet`<br /><span>string</span>                     | Set the recipient wallet type. <br /><br />**Possible values**:<ul><li>**Venmo**: Set to `Venmo` to send a payout to a Venmo account. Use `PHONE`, `EMAIL`, or `USER_HANDLE` as the `recipient_type`. <Note>Venmo payouts are available only in the US. If the recipient does not have a Venmo account, they receive instructions to create one and claim the payout.</Note></li><li>**PayPal**: Set to `PayPal` to send a payout to a PayPal account. This is the default value.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                            |

For information on all parameters, see <a href="https://docs.paypal.ai/reference/api/rest/payouts/create-batch-payout">API reference</a>.

<CodeGroup>
  ```shell Sample request lines expandable theme={null}
  curl -X POST https://api-m.sandbox.paypal.com/v1/payments/payouts \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer ACCESS-TOKEN' \
    -H 'PayPal-Request-Id: REQUEST-ID' \
    -d '{
      "sender_batch_header": {
        "sender_batch_id": "Batch-123",
        "email_subject": "You have a payout!"
      },
      "items": [
        {
          "recipient_type": "EMAIL",
          "amount": {
            "value": "10.00",
            "currency": "USD"
          },
          "receiver": "recipient@example.com",
          "note": "Thank you for your business!",
          "sender_item_id": "ITEM-ID-1"
        },
        {
          "recipient_type": "PHONE",
          "amount": {
            "value": "10.00",
            "currency": "USD"
          },
          "receiver": "+15555550123",
          "note": "Thanks for using Venmo!",
          "sender_item_id": "ITEM-ID-2"
        }
      ]
    }'
  ```

  ```json Sample response lines theme={null}
  {
    "batch_header": {
      "payout_batch_id": "3TRXJ4Z8XJ8QY",
      "batch_status": "PENDING",
      "sender_batch_header": {
        "sender_batch_id": "Batch-123",
        "email_subject": "You have a payout!"
      },
    },
    "links": [
      {
        "href": "https://api-m.sandbox.paypal.com/v1/payments/payouts/3TRXJ4Z8XJ8QY",
        "rel": "self",
        "method": "GET",
        "encType": "application/json"
      }
    ]
  }
  ```
</CodeGroup>

A successful call returns a `201 Created` response. The response includes the following parameters:

| <span>Parameter</span>             | <span>Description</span>                                                                                              | <span>Further action</span>                                                                                                                                                                                                              |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_header.payout_batch_id`     | Unique ID for the payout batch.                                                                                       | Use this ID to track or reference the batch in future API calls.                                                                                                                                                                         |
| `batch_header.batch_status`        | Status of the payout batch.<br /><br />**Possible values**: `SUCCESS`, `PENDING`, `PROCESSING`, `DENIED`, `CANCELED`. | PayPal may process the batch immediately or later. If the status is `PENDING`, check again later. <br /><br />To retry after a server error (such as HTTP `5xx`), send the request again with the same `sender_batch_id` within 30 days. |
| `batch_header.sender_batch_header` | Metadata of the payout batch that the sender originally provided in the payout request.                               | You can use it to match the response with your original request parameters.                                                                                                                                                              |
| `links`                            | URLs to get batch or item status.                                                                                     | Use these URLs to check the status of the batch or individual items.                                                                                                                                                                     |

### 2. Track status

After placing the payouts request, you can code your app to track the payout status by [polling for updates](#poll-for-updates) or [using webhooks](#use-webhooks).

#### Poll for updates

Use a <a href="https://docs.paypal.ai/developer/how-to/api/get-started#2-get-an-access-token">valid access token</a> and make a GET call to the `/v1/payments/payouts/{ID}` endpoint. <br />
**Path parameter**: `ID` is the `payout_batch_id` returned in the <a href="#1-create-payout-batch">Create payout batch</a> response.

<Tip>You can customize the request and choose which information to get in the response. See <a href="/growth/payouts/customize/customize-payouts-api-integration#get-specific-payout-details">Get specific payouts details</a>.</Tip>

<CodeGroup>
  ```shell Sample request lines  theme={null}
  curl -X GET https://api-m.sandbox.paypal.com/v1/payments/payouts/MJ77GF8MQ2TF6 \
    -H 'Authorization: Bearer ACCESS-TOKEN' \
    -H 'Content-Type: application/json'
  ```

  ```json Sample response lines expandable theme={null}
  {
    "total_items": 3,
    "total_pages": 1,
    "batch_header": {
      "payout_batch_id": "MJ77GF8MQ2TF6",
      "batch_status": "SUCCESS",
      "time_created": "2023-04-10T20:16:44Z",
      "time_completed": "2023-04-10T20:16:45Z",
      "sender_batch_header": {
        "sender_batch_id": "Payouts_1681157804",
        "email_subject": "You have a payout!",
        "email_message": "You have received a payout! Thanks for using our service!"
      },
      "funding_source": "BALANCE",
      "amount": {
        "currency": "USD",
        "value": "60.00"
      },
      "fees": {
        "currency": "USD",
        "value": "0.50"
      }
    },
    "items": [
      {
        "payout_item_id": "CX64X3KPCVYLC",
        "transaction_id": "4XH44110EC095525K",
        "activity_id": "0KJ317812H109105P",
        "transaction_status": "UNCLAIMED",
        "payout_item_fee": {
          "currency": "USD",
          "value": "0.25"
        },
        "payout_batch_id": "MJ77GF8MQ2TF6",
        "payout_item": {
          "recipient_type": "EMAIL",
          "amount": {
            "currency": "USD",
            "value": "10.00"
          },
          "note": "Thanks for your patronage!",
          "receiver": "recipient@example.com",
          "sender_item_id": "201403140001",
          "recipient_wallet": "PAYPAL"
        },
        "time_processed": "2023-04-10T20:16:45Z",
        "links": [
          {
            "href": "https://api.sandbox.paypal.com/v1/payments/payouts-item/CX64X3KPCVYLC",
            "rel": "item",
            "method": "GET"
          }
        ]
      },
      {
        "payout_item_id": "S697W7QJMAEX4",
        "transaction_id": "0FY48488BY887313U",
        "transaction_status": "UNCLAIMED",
        "payout_item_fee": {
          "currency": "USD",
          "value": "0.25"
        },
        "payout_item": {
          "recipient_type": "PHONE",
          "amount": {
            "currency": "USD",
            "value": "20.00"
          },
          "note": "Thanks for your support!",
          "receiver": "15562941698",
          "sender_item_id": "201403140002",
          "recipient_wallet": "PAYPAL"
        },
        "time_processed": "2023-04-10T20:16:45Z"
      },
      {
        "payout_item_id": "J64P4FHTAY7UN",
        "transaction_status": "FAILED",
        "payout_item_fee": {
          "currency": "USD",
          "value": "0.00"
        },
        "payout_item": {
          "recipient_type": "PAYPAL_ID",
          "amount": {
            "currency": "USD",
            "value": "30.00"
          },
          "note": "Thanks for your patronage!",
          "receiver": "invalid@example.com",
          "sender_item_id": "201403140003",
          "recipient_wallet": "PAYPAL"
        },
        "errors": {
          "name": "RECEIVER_ACCOUNT_INVALID",
          "message": "Receiver's account is invalid."
        }
      }
    ],
    "links": [
      {
        "href": "https://api.sandbox.paypal.com/v1/payments/payouts/MJ77GF8MQ2TF6?page_size=1000&page=1",
        "rel": "self",
        "method": "GET"
      }
    ]
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response. The response includes the following parameters:

| <span>Parameter </span>            | <span>Description </span>                                                                                                                                                                                                                                                                                                                                                                                | <span>Action </span>                                                                                                                                                                                                                                                     |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `batch_header.batch_status`        | Status of the payout batch.<br /><br />**Possible values**:<br /><ul><li>`SUCCESS`: PayPal has processed and completed the payout batch.</li><li>`PENDING`: PayPal has queued the payout batch for processing.</li><li>`PROCESSING`: PayPal is processing the payout batch.</li><li>`DENIED`: PayPal has denied the payout requests.</li><li>`CANCELED`: PayPal has canceled the payout batch.</li></ul> | If the status is `PENDING` or `PROCESSING`, check again later. <br />If the status is `DENIED` or `CANCELED`, review the error message or reason and resubmit if needed. <Tip>For real-time updates about payout events, <a href="#use-webhooks">use webhooks</a>.</Tip> |
| `batch_header.sender_batch_header` | Metadata of the payout batch that the sender originally provided in the payout request.                                                                                                                                                                                                                                                                                                                  | You can use it to match the response with your original request parameters.                                                                                                                                                                                              |
| `items`                            | Array of payout items with details for each item.                                                                                                                                                                                                                                                                                                                                                        | Use the `payout_item_id` to <a href="/growth/payouts/manage-payouts/track-payout-item-status">track the status of each payout item</a>.                                                                                                                                  |
| `links`                            | URLs to get batch or item status.                                                                                                                                                                                                                                                                                                                                                                        | You can use them to poll for updates.                                                                                                                                                                                                                                    |

<Note>For information on all parameters, see <a href="/reference/api/rest/payouts/show-payout-batch-details">API reference</a>.</Note>

#### Use webhooks

Webhook events are external events that your app does not know about unless it receives event notifications. For example, a payout processed or completed is a webhook event. You can subscribe to such events and register a callback (listener) URL. When the event occurs, PayPal sends a notification to the registered callback URL. You can code your app to perform relevant actions based on the event notification it receives.

To handle webhook events:

1. Review the <a href="/reference/webhook-events/payouts-v1">list of webhook events for Payouts</a> and select the events for your app to subscribe.
2. Subscribe to the selected webhook events through one of the following means:
   * **PayPal developer account**: Log in to your account, go to <strong>App details</strong> page > <strong>Features</strong> > <strong>Webhooks</strong>, and subscribe to webhook events.
   * <a href="/reference/api/rest/webhooks/create-webhook">Webhooks management API</a>.
3. In your server-side app code, define a webhook handler that:
   * <a href="https://developer.paypal.com/api/rest/webhooks/rest/#link-subscribingalistenerurl">Listens to the webhook event</a>.
   * <a href="https://developer.paypal.com/api/rest/webhooks/#link-receivingthemessage">Confirms receipt of the webhook event to PayPal</a>.
   * <a href="https://developer.paypal.com/api/rest/webhooks/#link-verifyingthemessagereceived">Verifies the source of the event notification</a>.
   * Performs further actions based on event data.

For more information, see <a href="https://developer.paypal.com/api/rest/webhooks/">Webhooks overview</a> and <a href="https://developer.paypal.com/api/rest/webhooks/rest/">Webhooks integration guide</a>.

### 3. Handle errors

PayPal uses standard HTTP status codes to indicate the result of an API request:

* `2xx`: Success
* `4xx`: Incorrect request (for example, missing parameter)
* `5xx`: PayPal server error

When an API call returns an error, the response includes a JSON body with the error details and HATEOAS links to help you diagnose and resolve issues. In your app code, include the logic to review the error code, message, and related links to determine the cause. Implement actions based on the error processing.
For more information, see <a href="/developer/how-to/api/handling-api-responses">API responses</a>.

### 4. Test

Use the PayPal sandbox environment to ensure your integration works as expected and meets all business and technical requirements before you go live.

Testing your Payouts API integration involves:

* Testing end-to-end payouts flow to verify money movement from your business account to your personal account (in case of PayPal payouts) or out of your business account (in case of Venmo payouts).
* <a href="#test-api-calls%3A-use-test-values-and-simulate-responses">Testing API calls</a>.

#### Test API calls: use test values and simulate responses

To simulate Payouts API responses, inject <a href="/growth/payouts/reference/payouts-api-test-values">test values</a> in the [request payload](#sample-test-value-in-request-payload) or as a [path parameter in the request URL](#sample-test-value-as-path-parameter). These methods allow you to trigger specific error responses without creating actual payouts.

<Tabs>
  <Tab title="Sample - test value in request payload">
    | <span>Trigger</span> | <span>Test value</span> | <span>Simulated error response</span> |
    | -------------------- | ----------------------- | ------------------------------------- |
    | items\[0]/note       | ERRPYO002               | `SENDER_EMAIL_UNCONFIRMED`            |

    <CodeGroup>
      ```shell Sample request lines expandable theme={null}
      curl -X POST https://api-m.sandbox.paypal.com/v1/payments/payouts \
        -H 'Content-Type: application/json' \
        -H 'Authorization: Bearer ACCESS-TOKEN' \
        -d '{
          "sender_batch_header": 
          {
            "sender_batch_id": "1524086406556",
            "email_subject": "This email is related to simulation"
          },
          "items": [
            {
              "recipient_type": "EMAIL",
              "receiver": "payouts-simulator-receiver@paypal.com",
              "note": "ERRPYO002",
              "sender_item_id": "15240864065560",
              "amount": 
              {
                "currency": "USD",
                "value": "1.00"
              }
            }
          ]
        }'
      ```

      ```json Sample response lines theme={null}
      {
        "name": "SENDER_EMAIL_UNCONFIRMED",
        "message": "Authorization error occurred",
        "debug_id": "ca787bdf80d7a",
        "information_link": "https://developer.paypal.com/docs/api/payments.payouts-batch/v1/#errors"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Sample - test value as path parameter">
    | <span>Path parameter</span> | <span>Test value</span> | <span>Simulated error response</span> |
    | --------------------------- | ----------------------- | ------------------------------------- |
    | /v1/payments/payouts/       | ERRPYO015               | `CLOSED_MARKET`                       |

    <CodeGroup>
      ```bash Sample request lines theme={null}
      curl -X GET https://api-m.sandbox.paypal.com/v1/payments/payouts/ERRPYO015 \
        -H 'Content-Type: application/json' \
        -H 'Authorization: Bearer ACCESS-TOKEN'
      ```

      ```json Sample response lines expandable theme={null}
      {
        "batch_header": {
          "payout_batch_id": "DQCP2UAJCBMNY",
          "batch_status": "SUCCESS",
          "time_created": "2017-08-21T11:22:33Z",
          "time_completed": "2017-08-21T11:22:54Z",
          "sender_batch_header": {
            "email_subject": "user test case"
          },
          "amount": {
            "currency": "USD",
            "value": "190.0"
          },
          "fees": {
            "currency": "USD",
            "value": "0.0"
          }
        },
        "items": [
          {
            "payout_item_id": "RWD4Y3H9VV8BA",
            "transaction_status": "FAILED",
            "errors": {
              "name": "CLOSED_MARKET",
              "message": "Payouts to this market are not supported.",
              "information_link": "https://developer.paypal.com/docs/api/payments.payouts-batch/v1/#errors",
              "details": []
            },
            "links": [
              {
                "href": "https://api-m.sandbox.paypal.com/v1/payments/payouts-item/RWD4Y3H9VV8BA",
                "rel": "item",
                "method": "GET",
                "encType": "application/json"
              }
            ]
          }
        ],
        "links": [
          {
            "href": "https://api-m.sandbox.paypal.com/v1/payments/payouts/DQCP2UAJCBMNY",
            "rel": "self",
            "method": "GET",
            "encType": "application/json"
          }
        ]
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

### 5. Go live

1. <a href="/growth/payouts/set-up#set-up-live-account">Set up live account.</a>
2. <a href="https://developer.paypal.com/docs/api-basics/notifications/webhooks/">Set up webhooks</a> to get real-time notifications about payout events, such as completed or failed payouts.
3. <a href="https://developer.paypal.com/api/rest/production/">Go live with your app</a>.


# Use Web UI
Source: https://docs.paypal.ai/growth/payouts/send-money/use-web-ui



You can use this pattern to send up to 5,000 payouts at once by uploading a `.csv` file in your PayPal business account dashboard. You can send batch payouts without writing code or setting up servers.

<Tip>You can send payouts to PayPal accounts and Venmo users.</Tip>

## Prerequisites

* Complete all mandatory steps to <a href="/growth/payouts/set-up#set-up-business-account-for-web-ui-file-upload">get started</a>.
* Ensure your <a href="/growth/payouts/set-up#set-up-live-account">PayPal business account is set up</a>.
* Ensure to <a href="/growth/payouts/set-up#fund-your-account">fund your business account</a>.

## Send payouts

You can use the procedures in this section to send payouts using the Payouts Web UI.

### 1. Create input file

Create a `.csv` file and add payout records as line items. Use the following format and add each payout you want to send as a separate row. You can add a maximum of 5000 rows.

#### Sample payout line items

```csv Example file 1 - Pay PayPal and Venmo recipients in US from your US business account theme={null}
mbrown@email.com,100.5,USD,ID001,Here is your payment,PAYPAL
jdoe@venmo.com,100.5,USD,,Here is your payment,VENMO,FRIENDS_ONLY
```

```csv Example file 2 - Pay a recipient in Germany from your US business account theme={null}
mbrown@myco.com,"100,50",EUR,ID001,Here is your payment,PAYPAL
```

| Field                                                                                     | Description                                                                         | Notes                                                                                                                                                                                                                                                                                                                                                                                                             |
| :---------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Recipient identifier <br /><span>Required</span>                                          | Identifier for the payout recipient based on the wallet type.                       | PayPal: Recipient's PayPal-associated email address or PayPal PayerID (retrieved through PayPal Checkout or Assisted Account Creation).<br />Venmo: Recipient's US mobile number or Venmo handle.<br /><br />**Examples:** `mbrown@email.com`, `jdoe@venmo.com`, `mbrown@myco.com`                                                                                                                                |
| Payment amount <br /><span>Required</span>                                                | Amount to send.                                                                     | For currencies that use a comma, enclose the amount in double quotes. PayPal validates the format on upload.<br /><br />**Example:** `100.5` or `"100,50"`                                                                                                                                                                                                                                                        |
| Currency <br /><span>Required</span>                                                      | Three-letter ISO 4217 currency code. Each file must contain only one currency type. | Use separate files for different currencies. To pay recipients in the local currency, group the recipients by their currency type and create one file for each payout currency. For more information, see <a href="/growth/payouts/customize/customize-web-ui-payouts#pay-recipients-in-their-local-currency">Pay in local currency</a>.<br /><br />**Example:** `USD` or `EUR`<br />**Max length:** 3 characters |
| Customer ID                                                                               | Unique recipient identifier.                                                        | No spaces allowed. Use double quotes if value contains commas.<br /><br />**Example:** `ID001`<br />**Max length:** 30 characters                                                                                                                                                                                                                                                                                 |
| Note to recipient <br /><span>Required for Venmo</span>, <span>Optional for PayPal</span> | Custom message sent to the recipient.                                               | PayPal: Overrides the default message set in the PayPal UI, if provided.<br />Venmo: A message must be included for each recipient. The message inherits the recipient’s privacy setting.<br /><br />**Example:** `Here is your payment`<br />**Max length:** 400 characters                                                                                                                                      |
| Recipient wallet <br /><span>Required</span>                                              | Target wallet for the payout.                                                       | **Default value:** `PAYPAL`<br /><br />**Possible values:**<br />• `PAYPAL`<br />• `VENMO`                                                                                                                                                                                                                                                                                                                        |
| Social feed privacy <br /><span>Venmo only</span>                                         | Visibility setting for the Venmo recipient’s social feed.                           | **Default value:** `PRIVATE`<br /><br />**Possible values:**<br />• <code>PUBLIC</code><br />• <code>FRIENDS\_ONLY</code><br />• <code>PRIVATE</code>                                                                                                                                                                                                                                                             |
| Holler URL <span>Deprecated</span> <br /><span>Venmo only</span>                          | URL of a Holler sticker to include with the Venmo message.                          | **Example:** [https://example.com/sticker.png](https://example.com/sticker.png)<br />**Max length:** 151 characters                                                                                                                                                                                                                                                                                               |
| Logo URL <br /><span>Venmo only</span>                                                    | URL of the business logo shown in the Venmo feed.                                   | Image uploaded at the access URL must be a square image of max size 1024 × 1024 px.<br /><br />**Example:** [https://example.com/logo.png](https://example.com/logo.png)<br />**Max length:** 2000 characters<br />                                                                                                                                                                                               |
| Purpose                                                                                   | Reason for the transaction.                                                         | **Default value:** `GOODS`<br /><br />**Possible values:**<br />• `AWARDS`<br />• `PRIZES`<br />• `DONATIONS`<br />• `GOODS`<br />• `SERVICES`<br />• `REBATES`<br />• `CASHBACK`<br />• `DISCOUNTS`<br />• `NON_GOODS_OR_SERVICES`                                                                                                                                                                               |

#### CSV file format specifications

Use the following specifications to ensure your payout file meets the required format and is accepted:

* Use a period (`.`) as the decimal separator for currencies like U.S. dollars (USD), Canadian dollars (CAD), and British pounds (GBP). For example: `100.5`.
* Use a comma (`,`) for currencies such as euros (EUR) and Brazilian reais (BRL), and enclose the amount in double quotes. For example: `"100,50"`.
* Each file must contain only one currency. For multi-currency payouts, upload a separate file per currency.
* Preserve the defined column order and ensure all rows include the same number of columns. Leave optional fields blank if not used and do not remove them.
* Add one row per recipient, adhering to the exact column structure.
* Wrap values containing commas or special characters in double quotes. For example, `"100,50"` or `"Custom Message with Comma, Here"`.

### 2. Upload input file

<Note>You can upload a sample input file in your sandbox account, test the payout, and then move to production.</Note>

1. Log in to your PayPal account.
2. Go to **Business Tools** > **Make Payments** > **Payouts** > **Get Started**.
3. On the Send a Mass Payment page:
   * Go to **Choose File** to select your `.csv` payment file.
   * Select **Open** to upload it.
4. (Optional) Enter additional details:
   * **Email subject:** Appears in the recipient’s email.
   * **Custom message for recipient:** Overrides the default message (applies to PayPal payouts only).
5. Review the consent statement and select the checkbox to acknowledge it.
6. Select **Continue**. PayPal validates your file and displays a Review Your Payments Details page.
7. Select **Send Payout** to submit the file. If you have set up a payout approval flow for your business account, PayPal sends the payout for approval and an approver must approve it. See <a href="/growth/payouts/customize/customize-web-ui-payouts#set-up-payout-approval-flow">Set up payout approval flow</a>.
8. After submission, select one of the following:
   * **Send another payout:** Process a new `.csv` file.
   * **View activity details:** Check payment status and transaction details.

<Note>If you reupload the same file within 30 days, PayPal shows a duplicate warning.</Note>

### 3. Track and manage payouts

You can:

* Monitor the status of each payment after submitting your `.csv` file.
* View payout details on the confirmation page or in the **Activity** tab of your PayPal business account dashboard.
* Download reports and transaction logs to review fees, statuses, and currency conversion details.

For more information, see <a href="/growth/payouts/manage-payouts/track-payout-item-status">Track payout item status</a>.

### 4. Go live

If you tested an input file in sandbox and the payout is successful:

1. Modify your input file to reflect actual payouts.
2. Go to your live account and upload the input file.


# Set up accounts and environment for payouts
Source: https://docs.paypal.ai/growth/payouts/set-up



You can use the procedures in this section to ensure that your accounts and environment are set up to send payouts.

## Set up business account for Web UI file upload

Work with your account manager, call 1-888-221-1161, or <a href="https://www.paypal.com/payoutsweb/landing?_ga=2.176099874.1452783257.1750650615-149702003.1736315018">contact PayPal</a> to request Payouts access. After successful activation, you can go to your account and send payouts through file upload.

## Set up SFTP account for large-batch file transfer

1. <a href="https://www.paypal-support.com/">Contact PayPal</a> or your PayPal account manager to onboard you to PayPal’s DropZone SFTP server and to enable Payouts. As part of onboarding, PayPal asks you for your server authentication preference – password or SSH.
2. If your authentication preference is SSH, generate a public and private SSH key-pair and share the public SSH key with PayPal.
3. PayPal onboards you to the DropZone SFTP server. DropZone is PayPal’s SFTP platform. The account setup might take up to 48 hours. After this, PayPal sends an encrypted email to your primary email address with the DropZone SFTP server access credentials.
4. Log in to your <a href="https://www.paypal.com/mep/dashboard/">PayPal business account</a> and add users who can access the SFTP server:
   1. Click on your profile logo and from the dropdown menu, select **Account settings**.
   2. On the Account access page, click **Update** next to Secure FTP.
   3. Follow the on-page instructions to add users. When finished, the final page displays the list of SFTP server users and their information.
5. Use any SFTP client of your choice (FileZilla, WinSCP, or Cyberduck) and access `dropzone.paypal.com` (production) or `dropzone.es-ext.paypalcorp.com` (sandbox).
6. Log in with the following credentials:

   * **Username**: SFTP account name sent in the email from PayPal
   * **Password**: Password sent in the email from PayPal

   OR

   * **Username**: SFTP account name sent in the email from PayPal
   * **SSH key**: Private key generated in step 2

### Sandbox DropZone SFTP server credentials

* **Sandbox endpoint/URL**: `dropzone.es-ext.paypalcorp.com`
* **Destination host port**: `22`
* **Username**: Sent in the encrypted mail from PayPal after SFTP server onboarding
* **Your private SSH key**

### Production DropZone SFTP server credentials

* **Production endpoint/URL**: `dropzone.paypal.com`
* **Destination host port**: `22`
* **Username**: Sent in the encrypted mail from PayPal after SFTP server onboarding
* **Your private SSH key**

## Set up sandbox account for Payouts API integration

1. <a href="https://www.paypal.com/signin?returnUri=https%3A%2F%2Fdeveloper.paypal.com%2Fdashboard%2F&intent=developer&ctxId=ul14c2e612301b4f5c99383ae8f762a937">Sign up for a developer account</a>. On successful signup, PayPal automatically creates your sandbox environment. The sandbox environment is a test environment that helps you mimic real-world transactions. By default, the environment includes a business and personal account. When testing your app, you can use the business account to send payouts and the personal account to receive. You can create multiple additional business and personal accounts.

2. Set up the sandbox environment:
   1. Go to your [PayPal developer account](https://developer.paypal.com/dashboard/) and toggle to **Sandbox**.
   2. Go to **Apps & Credentials** and select **Create App**.
   3. Enter your app name, select **Type** as **Merchant**, select the sandbox business account to test your app, and select **Create App**. The app details page is displayed.
   4. Configure a webhook listener for the app and subscribe to events:

      * Go to **Features** > **Sandbox Webhooks**.
      * Select **Add Webhook**.
      * Enter a **Webhook URL** (the server endpoint where notifications from PayPal are sent), select the events the app wants to subscribe to, and select **Save**.

      The webhook listener is successfully configured and a **Webhook ID** is displayed. You can store the ID and use it in your app code to verify the source sending a message to your listener. For more information on webhooks, see [Webhooks guide](https://developer.paypal.com/api/rest/webhooks/). For the list of payouts events that the app can subscribe to, see <a href="/reference/webhook-events/payouts-v1">Webhook reference</a>.

3. **Retrieve sandbox app credentials**: To integrate and test the Payouts API successfully, you need the sandbox credentials (**Client ID** and **Client secret**) for your app. To retrieve them, see <a href="/developer/how-to/api/get-started#1-get-your-client-id-and-client-secret">Get your client ID and client secret</a>.

4. **Retrieve sandbox account credentials**: When you test your payout integration end-to-end, you run your app, start a payout, log in to your business and personal PayPal accounts, and check that money moves from your business to your personal account. If you send a payout to a Venmo account, you check that the money moves from your business account. You require sandbox login credentials for both accounts. For information on how to get these from your developer account, see <a href="/developer/how-to/api/get-started#3-get-sandbox-account-credentials">Get sandbox account credentials</a>.

5. Set up the development environment. This involves building your server, installing dependencies, verifying configuration files that the package managers use, and setting up the environment variables.

## Set up live account

To use PayPal Payouts, you need a verified PayPal business account. After creating your production business account:

1. **Verify your account**:
   1. Complete [identity verification](https://www.paypal.com/policy/flow/verifyCip).
   2. Complete [email verification](https://www.paypal.com/in/cshelp/article/how-do-i-confirm-my-email-address-help138).
   3. [Link a bank account or credit card](https://www.paypal.com/businessexp/money/addbank) to your PayPal account.

2. **Request payouts activation**: [Contact PayPal support](https://www.paypal.com/payoutsweb/landing) to enable Payouts on your account.

## Fund your account

To successfully send payouts, ensure your PayPal account has sufficient funds.

1. **Link a funding source**: Log in to your PayPal account and link a bank account or credit card.
2. **Add funds to your PayPal account**:
   1. Navigate to the **Wallet** section of your PayPal account.
   2. Transfer money from your linked bank account or card to your PayPal balance.
3. **Set up auto-funding**: Enable auto-funding in your PayPal account settings to ensure your account always has sufficient funds for payouts.
4. **Monitor transactions**: Regularly review your account balance and transaction history to ensure smooth payouts.


# Use Enterprise Payouts - Hyperwallet
Source: https://docs.paypal.ai/growth/payouts/use-advanced-payouts





# Integrate reports using Transaction Reports API
Source: https://docs.paypal.ai/growth/reports/api



The [Transaction Search API](https://developer.paypal.com/docs/api/transaction-search/v1/) provides programmatic access to your PayPal transaction data, enabling real-time queries and automated reporting workflows. You can use this API to get transaction data with various query parameters and filters.

It takes a maximum of three hours for executed transactions to appear in the API calls, and it provides transaction data for the previous three years.

## Prerequisites

* PayPal Developer account.
* API credentials (Client ID and Secret).
* Access token generation capability.
* Understanding of REST API principles.

## Server-side integration

### Authentication setup

```javascript theme={null}
// Generate access token
const getAccessToken = async () => {
  const auth = Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64');
  
  const response = await fetch('https://api-m.paypal.com/v1/oauth2/token', {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${auth}`,
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: 'grant_type=client_credentials'
  });
  
  return await response.json();
};
```

### Basic transaction search

```javascript theme={null}
// Search transactions
const searchTransactions = async (accessToken, params) => {
  const queryString = new URLSearchParams(params).toString();
  
  const response = await fetch(`https://api-m.paypal.com/v1/reporting/transactions?${queryString}`, {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    }
  });
  
  return await response.json();
};
```

## Steps for implementation

1. **Set up authentication**
   * Obtain API credentials from PayPal Developer portal.
   * Implement token generation and refresh logic.
   * Secure credential storage.

2. **Build query parameters**
   * Define date ranges.
   * Set transaction status filters.
   * Configure pagination settings.

3. **Make API calls**
   * Send authenticated requests.
   * Handle response data.
   * Implement error handling.

4. **Process results**
   * Parse transaction data.
   * Transform for your business logic.
   * Store or forward as needed.

### Warnings

* API rate limits apply (check documentation).
* Date ranges are limited to specific periods.
* Some transaction details may have delays.

## Samples

```javascript theme={null}
// Example transaction search with filters
const params = {
  start_date: '2024-01-01T00:00:00Z',
  end_date: '2024-01-31T23:59:59Z',
  transaction_status: 'SUCCESS',
  page_size: 100
};

const transactions = await searchTransactions(accessToken, params);
```

## Testing

* Use sandbox endpoints for development.
* Test with various date ranges and filters.
* Verify pagination handling.
* Check error response handling.

## Best practices

* Implement proper authentication refresh.
* Use appropriate page sizes.
* Handle rate limiting gracefully.
* Store transaction IDs for deduplication.


# Download reports from your dashboard
Source: https://docs.paypal.ai/growth/reports/dashboard-downloads



The PayPal dashboard provides a user-friendly way to generate and download reports without any coding requirements. This no-code solution is perfect for merchants who need occasional reports or want to get started quickly.

## Prerequisites

To download reports from your dashboard, you need to have:

* PayPal Business account login access.
* Report viewing permissions.
* A clear understanding of required date ranges and filters.

## Steps to download reports

1. **Log into PayPal Business Account**

   * Navigate to your PayPal Business dashboard.
   * Ensure you have the necessary permissions.

2. **Access reports Ssection**

   * Click on "Reports" in the main navigation.
   * Select "Activity Download" or relevant report type.

3. **Configure report parameters**

   * Set date range for the data you need.
   * Choose transaction types to include.
   * Select file format, such as CSV or PDF.

4. **Generate report**

   * Click "Create Report" or similar action button.
   * Wait for processing to complete.

5. **Download file**

   * Download the generated report file.
   * Save to your preferred location.

## Warnings

* Large date ranges may take longer to process.
* Some reports have daily download limits.
* Historical data availability may be limited.

## Best practices

* Use specific date ranges to reduce file size.
* Download reports regularly to avoid data limits.
* Keep downloaded files secure and organized.


# Report fields and formats reference
Source: https://docs.paypal.ai/growth/reports/fields-formats



## Activity Download Report

The Activity Download Report provides you with access to transaction details for advanced reporting. You can customize reports with user-selected date ranges, file types, and data fields. The Activity Download Report is available for merchants with access to the reporting portal. It is available at the account level.

The Activity Download Report contains standardized fields and support multiple output formats. Understanding these specifications helps you process and integrate report data effectively.

## Know before you begin

* The reports character encoding is UTF-8 (8-bit UCS/Unicode Transformation Format).
* The reports are available in these formats:
  * Portable Document Format (PDF)
  * Comma-Separated Values (CSV)
  * Tab-Separated Value (TAB)
  * Quickbooks (IIF-enabled only for US accounts)
  * Quicken (QIF-USD only)

> **Note:** An Activity Download Report of CSV or TAB format can contain a maximum of 50,000 records. If the report contains more than 50,000 records, the report is split across multiple files and compiled into a ZIP file.

## Getting started

### Common report fields

#### Transaction level fields

* **Transaction ID**: Unique identifier for each transaction
* **Transaction Date**: When the transaction occurred
* **Transaction Type**: PAYMENT, REFUND, ADJUSTMENT, etc.
* **Transaction Status**: SUCCESS, PENDING, FAILED, etc.
* **Amount**: Transaction amount in original currency
* **Currency Code**: Three-letter ISO currency code
* **Fee Amount**: PayPal processing fees
* **Net Amount**: Amount after fees

#### Merchant information

* **Merchant Account ID**: Your PayPal account identifier
* **Store ID**: Physical or online store identifier
* **Invoice Number**: Your internal invoice reference
* **Custom Field**: Additional tracking data

#### Customer details (when available)

* **Payer Email**: Customer's PayPal email
* **Payer Name**: Customer's name
* **Payer Country**: Customer's country code
* **Shipping Address**: Delivery address details

### Supported file formats

#### CSV format

```csv theme={null}
Transaction ID,Date,Type,Status,Amount,Currency,Fee,Net
TXN123456789,2024-01-15,PAYMENT,SUCCESS,100.00,USD,3.20,96.80
```

#### JSON format

```json theme={null}
{
  "transaction_details": [
    {
      "transaction_info": {
        "transaction_id": "TXN123456789",
        "transaction_event_code": "T0006",
        "transaction_initiation_date": "2024-01-15T10:30:00Z",
        "transaction_updated_date": "2024-01-15T10:30:00Z",
        "transaction_amount": {
          "currency_code": "USD",
          "value": "100.00"
        },
        "fee_amount": {
          "currency_code": "USD",
          "value": "3.20"
        },
        "transaction_status": "S",
        "transaction_subject": "Payment for Order #12345"
      }
    }
  ]
}
```

### Field specifications

#### Date fields

* **Format**: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ)
* **Timezone**: UTC unless specified
* **Precision**: Seconds level

#### Amount fields

* **Decimal Places**: Up to 2 for most currencies
* **Negative Values**: Indicated by minus sign
* **Zero Values**: Represented as "0.00"

#### Status codes

| Code | Description |
| ---- | ----------- |
| S    | Success     |
| P    | Pending     |
| F    | Failed      |
| C    | Cancelled   |
| R    | Refunded    |

#### Transaction event codes

* **T0006**: Payment received
* **T0007**: Payment sent
* **T0111**: Refund issued
* **T0200**: Chargeback initiated

### Custom field mapping

```javascript theme={null}
// Map PayPal fields to your system
const mapTransactionFields = (paypalTransaction) => {
  return {
    internalId: paypalTransaction.custom_field,
    externalId: paypalTransaction.transaction_id,
    amount: parseFloat(paypalTransaction.transaction_amount.value),
    currency: paypalTransaction.transaction_amount.currency_code,
    status: mapStatus(paypalTransaction.transaction_status),
    timestamp: new Date(paypalTransaction.transaction_initiation_date)
  };
};
```

## Report availability and retention

Activity download reports can be generated for any time period within the last 7 years. Users can select a time period of up to 12 months at a time for report generation.

In addition to choosing dates from a calendar, you can choose:

* Since last download
* Today
* Yesterday
* Past month
* Past 3 months
* Past 6 months

## Report file name

The filename of a report from Activity Download follows this naming convention:

`Download.*format*`

`format` is one of the following:

* `CSV`: A comma-separated value file.
* `TAB`: A tab-separated value file.
* `PDF`: A portable document format file.
* `IFF`: An Intuit Interchange Format file.
* `QIF`: A Quicken Interchange Format file.

## Download fields

The following download data fields are available in the Activity Download report:

* **Column name**: The exact field name as it appears in the report, representing a specific transaction detail.
* **Position**: The sequential order of the column if all available fields are included in the report.
* **State**: Indicates whether a field is included in the report by default:
  * **Mandatory**: Always included and cannot be removed.
  * **Selected**: Included by default, but can be deselected by the user.
  * **Unselected**: Not included by default, but can be added by the user.
* Users can customize which fields appear in their report by editing the selection of **Selected** and **Unselected** fields.

### Download data fields

<table>
  <thead>
    <tr>
      <th>Position</th>
      <th>Column name</th>
      <th>Data type</th>
      <th>Char max length</th>
      <th>State</th>
      <th>In PDF</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>1</td>
      <td>Date</td>
      <td>Date</td>
      <td>10</td>
      <td>Mandatory</td>
      <td>Yes</td>
      <td>The localized completion date of the transaction. For the US, <code>MM/DD/YYYY</code>.</td>
    </tr>

    <tr>
      <td>2</td>
      <td>Time</td>
      <td>Time</td>
      <td>8</td>
      <td>Mandatory</td>
      <td>No</td>
      <td>The localized completion time of the transaction. Format is <code>HH:MM:SS</code>.</td>
    </tr>

    <tr>
      <td>3</td>
      <td>TimeZone</td>
      <td>Alphanumeric</td>
      <td>32</td>
      <td>Mandatory</td>
      <td>No</td>
      <td>The time zone used for displaying transaction date and time.</td>
    </tr>

    <tr>
      <td>4</td>
      <td>Name</td>
      <td>Alphanumeric</td>
      <td>200</td>
      <td>Mandatory</td>
      <td>No</td>
      <td>Counterparty name. Business name for business users and name for personal or premier users. Not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>5</td>
      <td>Type</td>
      <td>Alphanumeric</td>
      <td>100</td>
      <td>Mandatory</td>
      <td>Yes</td>
      <td>Transaction event code (T-Code) description. Not unique and can have spaces. See the <a href="https://developer.paypal.com/docs/reports/reference/tcodes/">Transaction Detail Report Specification</a> for a full list of T-Codes.</td>
    </tr>

    <tr>
      <td>6</td>
      <td>Status</td>
      <td>Alphanumeric</td>
      <td>127</td>
      <td>Mandatory</td>
      <td>Yes</td>
      <td>The status of the transaction. Possible values include Completed, Denied, Reversed, Pending, Active, Expired, Removed, Unverified, Voided, Processing, Created, Canceled, and more for invoice activity such as Error, Draft, Unpaid, Paid, Marked as paid, Refunded, etc. Not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>7</td>
      <td>Currency</td>
      <td>3-char currency code</td>
      <td>3</td>
      <td>Mandatory</td>
      <td>Yes</td>
      <td>Currency of transaction. Not unique and cannot have blanks.</td>
    </tr>

    <tr>
      <td>8</td>
      <td>Gross</td>
      <td>Currency/Money</td>
      <td>25</td>
      <td>Mandatory</td>
      <td>Yes</td>
      <td>Localized gross amount. Total amount of the transaction including fees. Not unique and cannot have blanks.</td>
    </tr>

    <tr>
      <td>9</td>
      <td>Fee</td>
      <td>Currency/Money</td>
      <td>25</td>
      <td>Mandatory</td>
      <td>Yes</td>
      <td>Localized fee amount associated with the transaction. Not unique and can have spaces.</td>
    </tr>

    <tr>
      <td>10</td>
      <td>Net</td>
      <td>Currency/Money</td>
      <td>25</td>
      <td>Mandatory</td>
      <td>Yes</td>
      <td>Localized net amount of the transaction (usually gross minus fee). Not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>1</td>
      <td>Date</td>
      <td>Date</td>
      <td>10</td>
      <td>Mandatory</td>
      <td>Yes</td>
      <td>The localized completion date of the transaction in a format based on the user's country. For the US, <code>MM/DD/YYYY</code></td>
    </tr>

    <tr>
      <td>2</td>
      <td>Time</td>
      <td>Time</td>
      <td>8</td>
      <td>Mandatory</td>
      <td>No</td>
      <td>The localized completion time of the transaction. Format is <code>HH:MM:SS</code>.</td>
    </tr>

    <tr>
      <td>3</td>
      <td>TimeZone</td>
      <td>Alphanumeric</td>
      <td>32</td>
      <td>Mandatory</td>
      <td>No</td>
      <td>The time zone used for displaying transaction date and time.</td>
    </tr>

    <tr>
      <td>4</td>
      <td>Name</td>
      <td>Alphanumeric</td>
      <td>200</td>
      <td>Mandatory</td>
      <td>No</td>
      <td>Counterparty name. Business name for business users and name for personal or premier users. Is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>5</td>
      <td>Type</td>
      <td>Alphanumeric</td>
      <td>100</td>
      <td>Mandatory</td>
      <td>Yes</td>
      <td>Transaction event code (T-Code) description. Is not unique and can have spaces. See the <a href="https://developer.paypal.com/docs/reports/reference/tcodes/">Transaction Detail Report Specification</a> for a full list of T-Codes.</td>
    </tr>

    <tr>
      <td>6</td>
      <td>Status</td>
      <td>Alphanumeric</td>
      <td>127</td>
      <td>Mandatory</td>
      <td>Yes</td>
      <td>The status of the transaction. Possible values for all activity:<ul>
      <li>Completed</li>
      <li>Denied</li>
      <li>Reversed</li>
      <li>Pending</li>
      <li>Active</li>
      <li>Expired</li>
      <li>Removed</li>
      <li>Unverified</li>
      <li>Voided</li>
      <li>Processing</li>
      <li>Created</li>
      <li>Canceled</li>
      </ul>Possible additional values are supported for invoice activity:<ul>
      <li>Error</li>
      <li>Draft</li>
      <li>Unpaid</li>
      <li>Paid</li>
      <li>Unpaid (sent)</li>
      <li>Marked as paid</li>
      <li>Marked as refunded</li>
      <li>Refunded</li>
      <li>Partially refunded</li>
      <li>Scheduled</li>
      <li>Partially paid</li>
      <li>Payment pending</li>
      </ul>It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>7</td>
      <td>Currency</td>
      <td>3-char currency code</td>
      <td>3</td>
      <td>Mandatory</td>
      <td>Yes</td>
      <td>Currency of transaction. It is not unique and cannot have blanks.</td>
    </tr>

    <tr>
      <td>8</td>
      <td>Gross</td>
      <td>Currency/Money</td>
      <td>25</td>
      <td>Mandatory</td>
      <td>Yes</td>
      <td>Localized gross amount. To talk amount of the transaction including fees. It is not unique and cannot have blanks.</td>
    </tr>

    <tr>
      <td>9</td>
      <td>Fee</td>
      <td>Currency/Money</td>
      <td>25</td>
      <td>Mandatory</td>
      <td>Yes</td>
      <td>Localized fee amount associated with the transaction. This field contains the fee amount value for all transactions where a transactional fee has been processed. Fees are not amortized across several transactions. Is not unique and can have spaces.</td>
    </tr>

    <tr>
      <td>10</td>
      <td>Net</td>
      <td>Currency/Money</td>
      <td>25</td>
      <td>Mandatory</td>
      <td>Yes</td>
      <td>Localized net amount of the transaction (usually gross fee). It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>11</td>
      <td>From Email Address</td>
      <td>Alphanumeric</td>
      <td>127</td>
      <td>Mandatory</td>
      <td>No</td>
      <td>The email address of the person with which the merchant transacted (buyer). It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>12</td>
      <td>To Email Address</td>
      <td>Alphanumeric</td>
      <td>127</td>
      <td>Mandatory</td>
      <td>No</td>
      <td>The email address of the transaction recipient. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>13</td>
      <td>Transaction ID</td>
      <td>Varchar</td>
      <td>24</td>
      <td>Mandatory</td>
      <td>No</td>
      <td>Encrypted Transaction ID. The ID of the transaction against which the case was filed. This unique 17-character ID is generated by PayPal and cannot be altered. It is unique and can have blanks.</td>
    </tr>

    <tr>
      <td>14</td>
      <td>CounterParty Status</td>
      <td>Alphanumeric</td>
      <td>127</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The accounts status of the counterparty. Possible values: <ul>
      <li>Verified</li>
      <li>Unverified</li>
      <li>Unregistered</li>
      </ul>It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>15</td>
      <td>Shipping Address</td>
      <td>Alphanumeric</td>
      <td>127</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The complete shipping address for the transaction. This information is a pass-through of what was provided by the payer. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>16</td>
      <td>Address Status</td>
      <td>Alphanumeric</td>
      <td>127</td>
      <td>Selected</td>
      <td>No</td>
      <td>The status of the counterparty's shipping address. Possible values: <ul>
      <li>Confirmed</li>
      <li>Non-Confirmed</li>
      </ul>It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>17</td>
      <td>Item Title</td>
      <td>Alphanumeric</td>
      <td>127</td>
      <td>Selected</td>
      <td>No</td>
      <td>The item title specified by a buyer in the website Auction/Item title field. It is specified by the seller in any of the following <code>buttoncreation</code> fields (<code>item\_name</code> or <code>item\_name\_x</code>):<ul>
      <li>PayPal Shopping Cart Item Name</li>
      <li>Buy Now Item Name</li>
      <li>Donations Item Name</li>
      <li>Subscriptions Name</li>
      </ul>It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>18</td>
      <td>Item ID</td>
      <td>Alphanumeric</td>
      <td>127</td>
      <td>Selected</td>
      <td>No</td>
      <td>Specified by the seller in any of the following <code>buttoncreation</code> fields (<code>item\_name</code> or <code>item\_name\_x</code>):<ul>
      <li>PayPal Shopping Cart Item Name</li>
      <li>Buy Now Item Name</li>
      <li>Donations Item Name</li>
      <li>Subscriptions Name</li>
      </ul>It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>19</td>
      <td>Shipping and Handling Amount</td>
      <td>Currency/Money</td>
      <td>25</td>
      <td>Selected</td>
      <td>No</td>
      <td>The localized amount paid, as reported by either PayPal or the merchant, for shipping and handling as a part of the transaction. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>20</td>
      <td>Insurance Amount</td>
      <td>Currency/Money</td>
      <td>25</td>
      <td>Selected</td>
      <td>No</td>
      <td>The localized insurance amount, as reported by either PayPal or the merchant, for the transaction. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>21</td>
      <td>Sales Tax</td>
      <td>Currency/Money</td>
      <td>25</td>
      <td>Selected</td>
      <td>No</td>
      <td>The localized sales tax amount, as reported by either PayPal or the merchant, paid as part of the transaction. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>22</td>
      <td>Option 1 Name</td>
      <td>Alphanumeric</td>
      <td>64</td>
      <td>Selected</td>
      <td>No</td>
      <td>The Option 1 Name associated with a transaction. It is specified by the seller in any of the following <code>buttoncreation</code> fields )<code>on0</code> or <code>on0\_x</code>): <ul>
      <li>3 PayPal Shopping Cart Option 1 Name</li>
      <li>3 Buy Now Option 1 Name</li>
      <li>3 Subscription Option 1 Name</li>
      </ul> It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>23</td>
      <td>Option 1 Value</td>
      <td>Alphanumeric</td>
      <td>200</td>
      <td>Selected</td>
      <td>No</td>
      <td>The Option 1 Value associated with a transaction. It is entered by the buyer in any of the following website fields:<ul>
      <li>3 PayPal Shopping Cart Option 1 Value</li>
      <li>3 Buy Now Option 1 Value</li>
      <li>3 Subscription Option 1 Value</li>
      </ul>It is specified by the seller in any of the following<code>A1:F56</code> fields:<ul>
      <li>3 PayPal Shopping Cart Option 1 Value</li>
      <li>3 Buy Now Option 1 Value</li>
      <li>3 Subscription Option 1 Value</li>
      </ul> It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>24</td>
      <td>Option 2 Name</td>
      <td>Alphanumeric</td>
      <td>64</td>
      <td>Selected</td>
      <td>No</td>
      <td>The Option 2 Name associated with a transaction. It is specified by the seller in any of the following <code>buttoncreation</code> fields )<code>on0</code> or <code>on0\_x</code>): <ul>
      <li>3 PayPal Shopping Cart Option 2 Name</li>
      <li>3 Buy Now Option 2 Name</li>
      <li>3 Subscription Option 2 Name</li>
      </ul> It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>25</td>
      <td>Option 2 Value</td>
      <td>Alphanumeric</td>
      <td>200</td>
      <td>Selected</td>
      <td>No</td>
      <td>The Option 2 Value associated with a transaction. It is entered by the buyer in any of the following website fields:<ul>
      <li>3 PayPal Shopping Cart Option 2 Value</li>
      <li>3 Buy Now Option 2 Value</li>
      <li>3 Subscription Option 2 Value</li>
      </ul>It is specified by the seller in any of the following fields:<ul>
      <li>3 PayPal Shopping Cart Option 2 Value</li>
      <li>3 Buy Now Option 2 Value</li>
      <li>3 Subscription Option 2 Value</li>
      </ul> It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>26</td>
      <td>Auction Site</td>
      <td>Varchar</td>
      <td>255</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The name of the auction site:<ul>
      <li>eBay</li>
      <li>Yahoo! Auctions</li>
      <li>uBid.com</li>
      <li>Amazon.com Auctions</li>
      <li>MSN Auctions</li>
      <li>BidVille</li>
      <li>Other</li>
      </ul> It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>27</td>
      <td>Buyer ID</td>
      <td>Varchar</td>
      <td>255</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The ID of the buyer making the purchase in the auction. This ID can be different from the payer ID provided for the payment. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>28</td>
      <td>Item URL</td>
      <td>Alphameric</td>
      <td>4000</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The URL of the eBay/Auction Item. In the case of multiple items, items are separated with a comma and shown along with the payment row. For example, <code>[http://cgi.ebay.com/ws/eBayISAPI.dll?ViewItem\&amp;item=252297991684](http://cgi.ebay.com/ws/eBayISAPI.dll?ViewItem\&amp;item=252297991684)</code>. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>29</td>
      <td>Closing Date</td>
      <td>Alphanumeric</td>
      <td>100</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The close date of eBay/Auction Item. The date format is based on the user's country. For example, <code>3/12/2016 10:31:52 PM</code>. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>30</td>
      <td>Escrow ID</td>
      <td>Numeric</td>
      <td>22</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The ID associated with the eBay Escrow CN Checkout transaction. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>31</td>
      <td>Reference Txn ID</td>
      <td>Varchar</td>
      <td>24</td>
      <td>Mandatory</td>
      <td>No</td>
      <td>The encrypted Transaction ID of the parent transaction. It is unique and can have blanks.</td>
    </tr>

    <tr>
      <td>32</td>
      <td>Invoice Number Text</td>

      <td />

      <td>127</td>
      <td>Selected</td>
      <td>No</td>
      <td>The invoice ID set by the merchant with the transaction. Uniqueness enforced by PayPal when the transaction is created. If an invoice ID was sent with the capture request, this value is reported here. However, if no invoice ID was sent with the capture request, the value of the invoice ID (if any) from the authorizing transaction is reported here. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>33</td>
      <td>Custom Number</td>
      <td>Alphanumeric</td>
      <td>256</td>
      <td>Selected</td>
      <td>No</td>
      <td>Shown only to seller/admin. The shopping cart customer number, Buy Now customer number, Subscription custom number, gift certificate tracking ID, or Masspay 2.0 disbursement ID. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>34</td>
      <td>Quantity</td>
      <td>Numeric</td>
      <td>25</td>
      <td>Selected</td>
      <td>No</td>
      <td>This shows the total number of items present in the payment transaction. For item rows, it shows quantity of an individual item.</td>
    </tr>

    <tr>
      <td>35</td>
      <td>Receipt ID</td>
      <td>Alphanumeric</td>
      <td>19</td>
      <td>Mandatory</td>
      <td>No</td>
      <td>The receipt identification number. 16-digit number in <code>xxxx-xxxx-xxxx-xxxx</code> format. It is not unique and can contain blanks.</td>
    </tr>

    <tr>
      <td>36</td>
      <td>Balance</td>
      <td>Currency/Money</td>
      <td>25</td>
      <td>Selected</td>
      <td>No</td>
      <td>Reflects the running amount in the merchant's bank account (available balance) in the currency of the transaction. Balance equals the previous balance plus the net. It is not unique and can contain blanks.</td>
    </tr>

    <tr>
      <td>37</td>
      <td>Address Line 1</td>
      <td>Varchar</td>
      <td>300</td>
      <td>Selected</td>
      <td>No</td>
      <td>The first line of the shipping address. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>38</td>
      <td>Address Line 2/<br />District/<br />Neighborhood</td>
      <td>Varchar</td>
      <td>300</td>
      <td>Selected</td>
      <td>No</td>
      <td>The second line of the shipping address. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>39</td>
      <td>Town/City</td>
      <td>Alphanumeric</td>
      <td>120</td>
      <td>Selected</td>
      <td>No</td>
      <td>The town or city of the shipping address.</td>
    </tr>

    <tr>
      <td>40</td>
      <td>State/Province/<br />Region/Country/<br />Territory/Prefecture/<br />Republic</td>
      <td>Alphanumeric</td>
      <td>120</td>
      <td>Selected</td>
      <td>No</td>
      <td>The state, province, region, territory, prefecture, or republic of the shipping address. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>41</td>
      <td>Zip/Postal Code</td>
      <td>Varchar</td>
      <td>60</td>
      <td>Selected</td>
      <td>No</td>
      <td>The zip or postal code of the shipping address. It is not unique and can contain blanks.</td>
    </tr>

    <tr>
      <td>43</td>
      <td>Contact Phone Number</td>
      <td>Numeric</td>
      <td>22</td>
      <td>Selected</td>
      <td>No</td>
      <td>The contact phone number. It is not unique and can contain blanks.</td>
    </tr>

    <tr>
      <td>44</td>
      <td>Subject</td>
      <td>Alphanumeric</td>
      <td>256</td>
      <td>Selected</td>
      <td>No</td>
      <td>The Transaction Subject/Item name. The subject of the payment as passed through the payer to the payee. This data is controlled by the payer exclusively in the interfaces through which it is sent. It is not unique and can contain blanks.</td>
    </tr>

    <tr>
      <td>45</td>
      <td>Note</td>
      <td>Varchar</td>
      <td>4000</td>
      <td>Selected</td>
      <td>No</td>
      <td>The transaction note. A special note of payment as passed through by the payer to the payee. This data is controlled by the payer exclusively in the interfaces through which it is sent. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>46</td>
      <td>Payment Source</td>
      <td>Varchar</td>
      <td>50</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The funding method. Possible values are:<ul>
      <li>PayPal</li>
      <li>PayPal Funds</li>
      <li>Instant Transfer</li>
      <li>Instant</li>
      <li>Non-Instant</li>
      <li>eCheck</li>
      <li>Credit Card</li>
      <li>Electronic Funds Transfer</li>
      <li>Direct Debit</li>
      <li>Buyer Credit</li>
      <li>PayPal Pay Later</li>
      <li>Plus Card</li>
      <li>eBay Master Card</li>
      <li>PayPal Credit</li>
      <li>Payment with giropay</li>
      <li>Virtual Terminal Transaction</li>
      <li>Debit Card</li>
      <li>Venmo</li>
      <li>Apple Pay</li>
      <li>Google Pay</li>
      <li>Network Token</li>
      <li>Pay Upon Invoice</li>
      <li><a href="https://developer.paypal.com/docs/multiparty/checkout/apm/supported-apms/">Supported APMs</a></li>
      </ul>It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>47</td>
      <td>Card Type</td>
      <td>Varchar</td>
      <td>30</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The funding source used for the transaction. Possible values are:<ul>
      <li><code>VISA</code></li>
      <li><code>MASTERCARD</code></li>
      <li><code>AMEX</code></li>
      <li><code>BANKCARD</code></li>
      <li><code>DISCOVER</code></li>
      <li><code>DINERS</code></li>
      <li><code>SWITCH</code></li>
      <li><code>SOLO</code></li>
      <li><code>GE</code></li>
      <li><code>CARTES\_BANCIARES</code></li>
      <li><code>JCB</code></li>
      <li><code>UNKNOWN</code></li>
      </ul>It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>48</td>
      <td>Transaction Event Code</td>
      <td>Alpahanumeric</td>
      <td>5</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The T-Code number. It is not unique and cannot have blanks.</td>
    </tr>

    <tr>
      <td>49</td>
      <td>Payment Tracking ID</td>
      <td>Varchar</td>
      <td>127</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The tracking ID specified by partners to obtain information about a payment or to request a refund. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>50</td>
      <td>Bank Reference ID</td>
      <td>Varchar</td>
      <td>13</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The bank reference ID. It is unique and can have blanks.</td>
    </tr>

    <tr>
      <td>51</td>
      <td>Transaction Buyer Country Code</td>
      <td>Varchar</td>
      <td>45</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The buyer country code. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>52</td>
      <td>Item Details</td>
      <td>Varchar</td>
      <td>1024</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The item details. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>53</td>
      <td>Coupons</td>
      <td>Varchar</td>
      <td>2048</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The information about all the coupons associated with the transaction. Each individual item contains four pipe-delimited parts of information:<ul>
      <li>3 Incentive code (offers or coupon)</li>
      <li>3 Amount</li>
      <li>3 Currency</li>
      <li>3 Campaign ID (associated with store offer or coupon)</li>
      </ul>For example, for a USD \$20 store offer with offer code 1234 and campaign ID ABCD, the delimited information would be \`1234</td>
    </tr>

    <tr>
      <td>54</td>
      <td>Special Offers</td>
      <td>Varchar</td>
      <td>2048</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The informationa bout all the store credits associated with the transaction. Each individual item contains four pipe-delimited parts of information:<ul>
      <li>3 Incentive code (offers or coupon)</li>
      <li>3 Amount</li>
      <li>3 Currency</li>
      <li>3 Campaign ID (associated with store offer or coupon)</li>
      </ul>For example, for a USD \$20 store offer with offer code 1234 and campaign ID ABCD, the delimited information would be \`1234</td>
    </tr>

    <tr>
      <td>55</td>
      <td>Loyalty Card Number</td>
      <td>Varchar</td>
      <td>100</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The customer's loyalty card provided to the merchant. This is applicable for Point of Sale transactions only. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>56</td>
      <td>Authorization Review Status</td>
      <td>Varchar</td>
      <td>2</td>
      <td>Unselected</td>
      <td>No</td>
      <td>Indicated the current status of the transaction and whether it is under review. If it is under review, then the status is either Green (01) or Yellow (02). Possible values are:<ul>
      <li>01</li>
      <li>02</li>
      <li>Blank</li>
      </ul>It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>57</td>
      <td>Protection Eligibility</td>
      <td>Varchar</td>
      <td>2</td>
      <td>Unselected</td>
      <td>No</td>
      <td>Indicates whether the transaction is eligible (01), not eligible (02), or partially eligible (03) for seller protection. Possible values are:<ul>
      <li>01</li>
      <li>02</li>
      <li>03</li>
      </ul>It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>58</td>
      <td>Country Code</td>
      <td>Varchar</td>
      <td>64</td>
      <td>Selected</td>
      <td>No</td>
      <td>The two letter country code of the shipping address. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>59</td>
      <td>Balance Impact</td>
      <td>Varchar</td>
      <td>64</td>
      <td>Selected</td>
      <td>No</td>
      <td>The impact on the balance for the transaction. Possible values are:<ul>
      <li>Debit</li>
      <li>Credit</li>
      <li>Memo</li>
      </ul>It is not unique and cannot have blanks.</td>
    </tr>

    <tr>
      <td>60</td>
      <td>Buyer Wallet</td>
      <td>Varchar</td>
      <td>10</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The text that identifies the company (PayPal or one of its subsidiaries) that processes the payment. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>61</td>
      <td>Comment 1</td>
      <td>Varchar</td>
      <td>1000</td>
      <td>Unselected</td>
      <td>No</td>
      <td>A note that accompanies a gateway transaction. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>62</td>
      <td>Comment 2</td>
      <td>Varchar</td>
      <td>1000</td>
      <td>Unselected</td>
      <td>No</td>
      <td>A note that accompanies a gateway transaction. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>63</td>
      <td>Invoice Number</td>
      <td>Varchar</td>
      <td>200</td>
      <td>Selected</td>
      <td>No</td>
      <td>The identifier of the invoice issued by the merchant. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>64</td>
      <td>PO Number</td>
      <td>Varchar</td>
      <td>200</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The identifier of the manifest of goods bought from the merchant. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>65</td>
      <td>Customer Reference Number</td>
      <td>Varchar</td>
      <td>80</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The identifier of the customer for a merchant. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>66</td>
      <td>Payflow Transaction ID (PNREF)</td>
      <td>Varchar</td>
      <td>80</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The unique idenitifier for the gateway transaction. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>67</td>
      <td>Tip</td>
      <td>Currency/Money</td>
      <td>25</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The amount of money paid by a consumer to a merchant over and above the item costs and any handling amounts in appreciation for services rendered. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>68</td>
      <td>Discount</td>
      <td>Currency/Money</td>
      <td>25</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The amount of discount given on the ordinary price of an item or group of items by the merchant. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>69</td>
      <td>SellerID</td>
      <td>Varchar</td>
      <td>200</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The unique identifier for the merchant at the marketplace site. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>70</td>
      <td>Risk Filter</td>
      <td>Varchar</td>
      <td>500</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The risk checks that the transaction matches. For a list of possible values see <a href="https://developer.paypal.com/docs/reports/reference/changed-download-fields/">Changed Download Fields</a> It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>71</td>
      <td>Tax ID Type</td>
      <td>Varchar</td>
      <td>4</td>
      <td>Unselected</td>
      <td>No</td>
      <td>Indicates the tax ID type of the buyer. Available for Brazil only. Possible values are:<ul>
      <li>CPF</li>
      <li>CNPJ</li>
      </ul>It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>72</td>
      <td>Tax ID</td>
      <td>Varchar</td>
      <td>80</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The buyer's taxpayer registry number. Avaiable for Brazil only. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>73</td>
      <td>Number of Installments</td>
      <td>Numeric</td>
      <td>26</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The number of installments for the credit offer. Available for Brazil and Mexico only. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>74</td>
      <td>Installment Amount</td>
      <td>Currency/Money</td>
      <td>26</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The installment amount for the credit offer. Only available for Brazil and Mexico. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>75</td>
      <td>Installment Fee</td>
      <td>Currency/Money</td>
      <td>26</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The installment fee for the credit offer. Only available for Brazil and Mexico. It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>76</td>
      <td>Credit Transactional Fee</td>
      <td>Currency/Money</td>
      <td>26</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The credit-related transaction fee amount for a merchant-selected credit offering.</td>
    </tr>

    <tr>
      <td>77</td>
      <td>Credit Promotional Fee</td>
      <td>Currency/Money</td>
      <td>26</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The credit-related transaction fee amount for a merchant-selected credit offering with a promotional APR.</td>
    </tr>

    <tr>
      <td>78</td>
      <td>Credit Term</td>
      <td>Numeric</td>
      <td>26</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The time span covered by the merchant-selected credit offer. The length of the term is captured in months.</td>
    </tr>

    <tr>
      <td>79</td>
      <td>Credit Offer Type</td>
      <td>Alphanumeric</td>
      <td>64</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The name of the credit offer used by the buyer as a funding instrument.</td>
    </tr>

    <tr>
      <td>80</td>
      <td>Original Invoice ID</td>
      <td>Varchar</td>
      <td>200</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The invoice ID of the original payment record. This ID helps users link and track all related transactions to the original parent transaction.</td>
    </tr>

    <tr>
      <td>81</td>
      <td>Campaign Fee</td>
      <td>Currency/Money</td>
      <td>22</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The fee charged to a merchant for each sale with a discount applied during a campaign.</td>
    </tr>

    <tr>
      <td>82</td>
      <td>Campaign Name</td>
      <td>Varchar</td>
      <td>200</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The name given to the campaign. Merchants can track this name on the campaign dashboard. Examples: <code>XMAS2021</code>, <code>Sales Recovery Campaign</code>.</td>
    </tr>

    <tr>
      <td>83</td>
      <td>Campaign Discount</td>
      <td>Currency/Money</td>
      <td>22</td>
      <td>Unselected</td>
      <td>No</td>
      <td>Denotes the value of a discount amount applied in the transaction. For marketing campaigns, merchants can offer customers a discount in either a dollar amount or percentage.</td>
    </tr>

    <tr>
      <td>84</td>
      <td>Campaign Discount Currency</td>
      <td>3-char currency code</td>
      <td>3</td>
      <td>Unselected</td>
      <td>No</td>
      <td>Denotes the currency of the discounted amount.</td>
    </tr>

    <tr>
      <td>85</td>
      <td>Payment Source Subtype</td>
      <td>Varchar</td>
      <td>50</td>
      <td>Unselected</td>
      <td>No</td>
      <td>The funding source used for the transaction and the name of the credit offer used by the buyer as a funding instrument. Possible values are:<ul>
      <li><code>VISA</code></li>
      <li><code>MASTERCARD</code></li>
      <li><code>AMEX</code></li>
      <li><code>BANKCARD</code></li>
      <li><code>DISCOVER</code></li>
      <li><code>DINERS</code></li>
      <li><code>SWITCH</code></li>
      <li><code>SOLO</code></li>
      <li><code>CARTES\_BANCIARES</code></li>
      <li><code>GE</code></li>
      <li><code>JCB</code></li>
      <li><code>CB\_NATIONALE</code></li>
      <li>Pay in 3</li>
      <li>Pay in 4</li>
      <li>Easy Payments</li>
      <li>0% for 4 months</li>
      <li>Installments</li>
      </ul>For Wallets and Network token, Payment Source Subtype would show details of card type and card brand used to fund the transaction.<br />For example: <ul>
      <li><code>Credit Card-VISA</code></li>
      <li><code>Debit Card-MASTERCARD</code></li>
      </ul>It is not unique and can have blanks.</td>
    </tr>

    <tr>
      <td>86</td>
      <td>Decline Code</td>
      <td>Varchar</td>
      <td>50</td>
      <td>Unselected</td>
      <td>No</td>

      <td>
        <ul>
          <li><a href="https://www.europeanpaymentscouncil.eu/sites/default/files/kb/file/2021-11/EPC173-14%20v6.0%20Guidance%20on%20Reason%20Codes%20for%20SDD%20R-transactions.pdf" title="external link">UDD SEPA Decline Codes</a></li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>87</td>
      <td>Fastlane Checkout Transaction</td>
      <td>Varchar</td>
      <td>1</td>
      <td>Unselected</td>
      <td>No</td>
      <td>Indicates whether the transaction was checked out using fastlane accelerated checkout.</td>
    </tr>
  </tbody>
</table>

## Best practices

* Validate all field formats before processing.
* Handle missing or null fields gracefully.
* Store original data for audit purposes.
* Use consistent field mapping across systems.


# Get started with PayPal reports
Source: https://docs.paypal.ai/growth/reports/get-started



PayPal Reports provide detailed insights into your business transactions, helping you track performance, reconcile accounts, and analyze customer behavior patterns.

## Steps to begin

1. **Identify Your Needs**: Determine what data you need and how often.
2. **Choose Access Method**: Select between dashboard, API, or automated options.
3. **Set Up Credentials**: Obtain necessary API keys and permissions.
4. **Test Access**: Verify you can retrieve sample data.
5. **Implement Solution**: Build or configure your chosen approach.

## Report types available

* **Transaction Reports**: Individual payment details.
* **Settlement Reports**: Batch processing summaries.
* **Activity Reports**: Comprehensive business activity.
* **Balance Reports**: Account balance history.

## Best practices

* Start with small date ranges when testing.
* Implement proper error handling.
* Store credentials securely.
* Regular monitoring and validation.


# How reports and analytics work
Source: https://docs.paypal.ai/growth/reports/how-it-works



PayPal's reporting system processes transaction data in real-time and batch modes, providing comprehensive insights through various access methods and data formats.

## Getting started

### Data flow architecture

1. **Transaction processing**: PayPal captures all payment events.
2. **Data aggregation**: Information is compiled and indexed.
3. **Report generation**: Data is formatted for various output types.
4. **Delivery methods**: Reports delivered via dashboard, API, or automation.

## Core components

### Data collection

* Real-time transaction capture.
* Event logging and timestamping.
* Multi-currency processing.
* Geographic data tracking.

### Processing pipeline

* Data validation and cleansing.
* Aggregation and summarization.
* Format conversion and optimization.
* Security and compliance filtering.

### Delivery mechanisms

* **Synchronous**: Immediate API responses.
* **Asynchronous**: Scheduled report generation.
* **Event-driven**: Webhook notifications.

## Integration patterns

### Pull-based access

* API calls initiated by your system.
* On-demand data retrieval.
* Real-time query capabilities.

### Push-based delivery

* PayPal initiates data delivery.
* Scheduled report generation.
* Webhook event notifications.

## Best practices

* Understand data latency characteristics.
* Implement appropriate caching strategies.
* Plan for peak processing times.
* Monitor API rate limits.


# Manage and automate reports
Source: https://docs.paypal.ai/growth/reports/manage-automate



PayPal offers several options to automate and schedule the generation and delivery of reports, helping you streamline reconciliation, compliance, and business intelligence processes.

Automate your reporting workflows using PayPal's scheduling APIs, SFTP delivery, and webhook integrations to ensure consistent, timely access to your business data.

## Getting started

### Prerequisites

* PayPal Business account with API access
* Understanding of your reporting schedule needs
* Technical capability for automation setup
* Secure storage for automated reports

### Scheduling options

#### Payflow reporting API scheduling

The [Transaction Search API](https://developer.paypal.com/docs/api/transaction-search/v1/) allows you to programmatically retrieve transaction history for a PayPal account. You can use this API to get transaction data with various query parameters and filters.

It takes a maximum of three hours for executed transactions to appear in the API calls, and it provides transaction data for the previous three years.

```javascript theme={null}
// Create scheduled report template
const createScheduledReport = async (templateData) => {
  const response = await fetch('/v1/reporting/templates/schedule', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateData.template_id,
      schedule_type: 'DAILY', // WEEKLY, MONTHLY
      delivery_method: 'SFTP',
      start_date: '2024-01-01',
      frequency: 1
    })
  });
  
  return await response.json();
};
```

#### SFTP automation setup

PayPal offers [SFTP access](https://developer.paypal.com/docs/reports/sftp-reports/) for secure retrieval of reports that are updated daily. Reports like the Transaction Detail Report are generated and placed on SFTP on a 24-hour basis in CSV format. The Transaction Detail Report is generated and put on PayPal's website and the Secure Dropbox by no later than 12:00PM daily.

##### Steps for SFTP configuration

1. **Request SFTP access**

   * Contact PayPal support for SFTP credentials
   * Provide security requirements and IP restrictions
   * Configure firewall and access controls

2. **Set Up automated retrieval**

   * Schedule daily report downloads
   * Reports available by 12 PM in leading time zone
   * Implement secure file transfer protocols

3. **Process retrieved files**

   * Automate file parsing and validation
   * Integrate with your business systems
   * Archive processed reports securely

##### Sample SFTP integration

```javascript theme={null}
// SFTP file retrieval automation
const downloadDailyReports = async () => {
  const sftp = new SFTP();
  
  try {
    await sftp.connect(sftpConfig);
    const files = await sftp.list('/reports/daily');
    
    for (const file of files) {
      if (isNewReport(file)) {
        await sftp.get(file.name, `./downloads/${file.name}`);
        await processReport(file.name);
      }
    }
  } finally {
    await sftp.end();
  }
};
```

#### Webhook automation

PayPal's REST APIs use webhooks for event notification, which are HTTP callbacks that receive notification messages for events. You can subscribe webhook listeners to events and automate responses when transactions occur. You can use webhooks for reporting by collecting information from webhook notifications to create reports based on different triggers, such as subscription cancellations.

##### Webhook setup for reporting

1. **Configure webhook endpoints**
   * Set up secure HTTPS endpoints
   * Implement signature verification
   * Handle event processing logic

2. **Event-driven report generation**

   * Trigger reports based on specific events
   * Process transaction completion webhooks
   * Generate custom reports on demand

##### Webhook processing example

````javascript theme={null}
// Webhook-triggered report generation
app.post('/webhook/transaction-complete', async (req, res) => {
  const event = req.body;
  
  if (event.event_type === 'PAYMENT.CAPTURE.COMPLETED') {
    await generateTransactionReport(event.resource.id);
  }
  
  res.status(200).send('OK');
});

### Management operations

#### Update scheduled reports

```javascript
// Modify existing schedule
const updateSchedule = async (scheduleId, updates) => {
  return await fetch(`/v1/reporting/schedules/${scheduleId}`, {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(updates)
  });
};
````

#### Delete report schedules

```javascript theme={null}
// Remove scheduled report
const deleteSchedule = async (scheduleId) => {
  return await fetch(`/v1/reporting/schedules/${scheduleId}`, {
    method: 'DELETE',
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  });
};
```

## Best practices

* Monitor automation health regularly
* Implement failure notifications
* Maintain backup scheduling methods
* Secure all automated processes
* Test schedule changes in sandbox first


# Grow and run your business with reports and analytics
Source: https://docs.paypal.ai/growth/reports/overview



PayPal provides a comprehensive suite of tools to help you grow and manage your business effectively. The Reports & Analytics features give you actionable insights into your business performance, transaction data, and customer behavior. With these tools, you can track business performance, analyze transaction patterns, and generate reports for accounting and business intelligence.

## Overview

PayPal offers multiple ways to access your business data, from simple dashboard downloads to sophisticated API integrations. Choose the method that best fits your technical capabilities and business needs.

## Getting started

To access and use PayPal Reports & Analytics, you need to have:

* An active PayPal Business account with reporting permissions.
* Developer or API credentials if you want to access reports programmatically.
* Appropriate permissions for report access.
* A clear understanding of your business reporting requirements.

Consider these factors when choosing your data access method:

* Technical expertise level
* Data volume requirements
* Automation needs
* Integration complexity

## Available options

### No-code solutions

* **Dashboard Downloads**: Manual report generation through PayPal's web interface
* **Scheduled Reports**: Automated delivery via email or SFTP
* **Basic Analytics**: Built-in dashboard charts and summaries

### Pro-code solutions

* **Transaction Search API**: Real-time programmatic access to transaction data
* **Reporting APIs**: Automated report generation and retrieval
* **Webhook Integration**: Event-driven data processing

## Key features

* **Reports and analytics**: Access detailed business data and insights.
* **Transaction monitoring**: Track all payment activities in real time.
* **Business intelligence**: Make data-driven decisions with historical and current data.
* **Automated reporting**: Schedule and automate report generation and delivery.
* **Flexible formats**: Download reports in CSV, PDF, or JSON formats.
* **API integration**: Integrate reporting features directly into your business systems.

## Best practices

* Start with simple dashboard downloads to understand your data.
* Gradually move to API solutions as your needs grow.
* Plan for data security and compliance requirements.


# Test and verify reports
Source: https://docs.paypal.ai/growth/reports/test-verify-reports



Thorough testing ensures your reporting integration works correctly before going live. PayPal provides sandbox environments and verification tools to validate your implementation.

## Prerequisites

* Sandbox PayPal Developer account.
* Test API credentials.
* Understanding of expected data formats.
* Verification checklist.

## Steps for testing

### 1. Sandbox environment setup

* Create sandbox business account.
* Generate test API credentials.
* Configure sandbox endpoints.
* Create test transactions.

### 2. API endpoint testing

```javascript theme={null}
// Test with sandbox endpoint
const SANDBOX_BASE_URL = 'https://api-m.sandbox.paypal.com';

const testTransactionSearch = async () => {
  try {
    const response = await fetch(`${SANDBOX_BASE_URL}/v1/reporting/transactions`, {
      headers: {
        'Authorization': `Bearer ${sandboxAccessToken}`,
        'Content-Type': 'application/json'
      }
    });
    
    console.log('Test successful:', await response.json());
  } catch (error) {
    console.error('Test failed:', error);
  }
};
```

### 3. Data validation testing

* Verify transaction data completeness.
* Check date range filtering.
* Test pagination functionality.
* Validate response formats.

### 4. Error handling verification

* Test invalid credentials.
* Check rate limit responses.
* Verify timeout handling.
* Test malformed requests.

## Using webhooks events dashboard

### Access event details

1. Navigate to PayPal Developer Dashboard.
2. Select "Webhooks Events" section.
3. View event status and details.
4. Use resend functionality for testing.

### Webhook verification testing

* Test webhook endpoint reception.
* Verify signature validation.
* Check event processing logic.
* Test retry mechanisms.

## Samples

```javascript theme={null}
// Comprehensive test function
const runReportingTests = async () => {
  const tests = [
    testAuthentication,
    testTransactionSearch,
    testDateFiltering,
    testPagination,
    testErrorHandling
  ];
  
  for (const test of tests) {
    await test();
  }
};
```

## Testing checklist

* Authentication works correctly.
* API responses are properly parsed.
* Date filtering functions as expected.
* Pagination handles all scenarios.
* Error responses are handled gracefully.
* Webhook events are received and processed.

## Best practices

* Test with realistic data volumes.
* Verify all error scenarios.
* Use automated testing where possible.
* Document test results and fixes.


# Troubleshooting reports and analytics
Source: https://docs.paypal.ai/growth/reports/troubleshooting



Common reporting issues can be resolved by following systematic troubleshooting steps and understanding PayPal's error responses and system limitations.

## Getting started

### Common error types

* Authentication failures
* API rate limit exceeded
* Invalid request parameters
* Data availability issues
* Network connectivity problems

### Error response format

PayPal API errors follow a standard format:

```json theme={null}
{
  "error": "invalid_client",
  "error_description": "Client authentication failed",
  "error_uri": "https://developer.paypal.com/docs/api/overview/#error"
}
```

### Error codes

| Error                    | Message                                                                                      | Description                                                                                                                      |
| ------------------------ | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `INTERNAL_SERVICE_ERROR` | Internal service error.                                                                      | Something unexpected occurred on the server.                                                                                     |
| `INVALID_REQUEST`        | Invalid request - see details.                                                               | The request is not well-formed or is syntactically incorrect or violates the schema.                                             |
| `INVALID_RESOURCE_ID`    | The resource was not found.                                                                  | The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible. |
| `RESULTSET_TOO_LARGE`    | Result set size is greater than the maximum limit. Change the filter criteria and try again. | The request returned more items than the maximum limit. To reduce the result set, include additional query                       |

### Troubleshooting steps

#### 1. Authentication issues

##### Symptoms

* HTTP 401 Unauthorized responses
* "invalid\_client" errors
* Token expiration messages

##### Solutions

```javascript theme={null}
// Check token validity
const validateToken = async (token) => {
  try {
    const response = await fetch('https://api-m.paypal.com/v1/identity/oauth2/userinfo', {
      headers: {
        'Authorization': `Bearer ${token}`,
        'Accept': 'application/json'
      }
    });
    
    if (!response.ok) {
      console.error('Token invalid:', response.status);
      return false;
    }
    
    return true;
  } catch (error) {
    console.error('Token validation failed:', error);
    return false;
  }
};

// Refresh token if needed
const refreshAccessToken = async () => {
  // Implement token refresh logic
  const newToken = await getAccessToken();
  return newToken;
};
```

#### 2. Rate limiting problems

##### Symptoms

* HTTP 429 Too Many Requests
* Temporary service unavailable
* Slow response times

##### Solutions

```javascript theme={null}
// Implement exponential backoff
const makeRequestWithRetry = async (url, options, maxRetries = 3) => {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || Math.pow(2, attempt);
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
      
      return response;
    } catch (error) {
      if (attempt === maxRetries) throw error;
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
    }
  }
};
```

#### 3. Data query issues

##### Invalid date ranges

```javascript theme={null}
// Validate date parameters
const validateDateRange = (startDate, endDate) => {
  const start = new Date(startDate);
  const end = new Date(endDate);
  const now = new Date();
  const maxRangeMs = 31 * 24 * 60 * 60 * 1000; // 31 days
  
  if (start > end) {
    throw new Error('Start date must be before end date');
  }
  
  if (end > now) {
    throw new Error('End date cannot be in the future');
  }
  
  if (end - start > maxRangeMs) {
    throw new Error('Date range cannot exceed 31 days');
  }
  
  return true;
};
```

##### Missing transaction data

```javascript theme={null}
// Handle incomplete data
const processTransactionSafely = (transaction) => {
  const safeTransaction = {
    id: transaction.transaction_id || 'UNKNOWN',
    amount: transaction.transaction_amount?.value || '0.00',
    currency: transaction.transaction_amount?.currency_code || 'USD',
    date: transaction.transaction_initiation_date || new Date().toISOString(),
    status: transaction.transaction_status || 'UNKNOWN'
  };
  
  // Log missing fields for monitoring
  if (!transaction.transaction_id) {
    console.warn('Missing transaction ID:', transaction);
  }
  
  return safeTransaction;
};
```

#### 4. Network and connectivity issues

##### Connection timeouts

```javascript theme={null}
// Configure appropriate timeouts
const fetchWithTimeout = async (url, options = {}) => {
  const controller = new AbortController();
  const timeoutId = setTimeout(() => controller.abort(), 30000); // 30 second timeout
  
  try {
    const response = await fetch(url, {
      ...options,
      signal: controller.signal
    });
    
    clearTimeout(timeoutId);
    return response;
  } catch (error) {
    clearTimeout(timeoutId);
    
    if (error.name === 'AbortError') {
      throw new Error('Request timeout');
    }
    
    throw error;
  }
};
```

### Diagnostic tools

#### API response logging

```javascript theme={null}
// Comprehensive error logging
const logApiError = (error, requestDetails) => {
  console.error('PayPal API Error:', {
    timestamp: new Date().toISOString(),
    endpoint: requestDetails.url,
    method: requestDetails.method,
    status: error.status,
    message: error.message,
    requestId: error.headers?.['paypal-request-id']
  });
};
```

#### Health check implementation

```javascript theme={null}
// Regular API health monitoring
const checkApiHealth = async () => {
  try {
    const token = await getAccessToken();
    const response = await fetch('https://api-m.paypal.com/v1/reporting/transactions?page_size=1', {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    });
    
    return response.ok;
  } catch (error) {
    console.error('API health check failed:', error);
    return false;
  }
};
```

## Error prevention best practices

* Implement comprehensive error handling.
* Use appropriate request timeouts.
* Monitor API rate limits.
* Validate input parameters.
* Log errors with sufficient detail.
* Set up alerting for critical failures.
* Regular health checks and monitoring.
* Keep API credentials secure and up-to-date.


# Integration
Source: https://docs.paypal.ai/limited-release/tokenization/e-commerce/integration



This guide walks through the end-to-end implementation of Ecommerce network tokenization using Secure Credential Services by PayPal.

## Prerequisites

To integrate with Secure Credential Services, you need:

* A PayPal account with a Client ID provisioned for Ecommerce tokenization
* OAuth 2.0 credentials (Client ID and Client Secret)
* Required API scopes provisioned by the PayPal team for your use case
* A decision on your TRID model

> **Note:** Contact your PayPal account representative to obtain sandbox OAuth credentials and confirm your TRID model before starting. Configure sandbox and production environments separately: never share credentials between environments.

## API reference

Use the following base URLs and endpoints for all Payment Tokenization requests.

### Base URLs

All paths are prefixed [`/v1/payment-tokenization/`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/). All PayPal REST API requests target one of two base URLs:

| Environment | URL                                |
| ----------- | ---------------------------------- |
| Sandbox     | `https://api-m.sandbox.paypal.com` |
| Production  | `https://api-m.paypal.com`         |

### List of APIs

| Method | Endpoint                                                                                                                                        | Purpose                                                              | Requirement   |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------------- |
| `POST` | [`/v1/payment-tokenization/enrollments`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/enrollment-decision)          | Create a real-time token enrollment for a single card                | **Mandatory** |
| `GET`  | [`/v1/payment-tokenization/enrollments/{id}`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/enrollment-status)       | Retrieve enrollment details and token information                    | **Mandatory** |
| `POST` | [`/v1/payment-tokenization/payment-credentials`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/token-provisioning)   | Fetch or pre-fetch a one-time payment cryptogram for a transaction   | **Mandatory** |
| `POST` | [`/v1/payment-tokenization/enrollments/{id}/close`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/token-close)       | Permanently close a token enrollment                                 | **Mandatory** |
| `GET`  | [`/v1/payment-tokenization/contents/{content_id}`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/get-content)        | Retrieve card art, terms & conditions, or logos for a tokenized card | **Mandatory** |
| `POST` | [`/v1/payment-tokenization/batch-requests`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/batch-post)                | Submit a bulk enrollment batch (up to 1,000 cards)                   | **Mandatory** |
| `GET`  | [`/v1/payment-tokenization/batch-requests/{id}`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/batch-get)            | Retrieve the status and results of a bulk enrollment batch           | **Mandatory** |
| `POST` | `/v1/payment-tokenization/token-requestors`                                                                                                     | Create and onboard a new Token Requestor (TRID)                      | Recommended   |
| `GET`  | `/v1/payment-tokenization/token-requestors/{tokenRequestorId}`                                                                                  | Retrieve TRID configuration, status, and supported networks          | Recommended   |
| `POST` | `/v1/payment-tokenization/search-token-requestors`                                                                                              | Search for TRIDs by name, status, or supported network               | Recommended   |
| `POST` | [`/v1/payment-tokenization/search-enrollments`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/list-enrollments)      | Search enrollments by merchant, partner, token reference, or status  | Recommended   |
| `POST` | [`/v1/payment-tokenization/enrollments/{id}/activate`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/token-activate) | Reactivate a previously suspended enrollment                         | Recommended   |
| `POST` | [`/v1/payment-tokenization/enrollments/{id}/suspend`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/token-suspend)   | Temporarily suspend a token enrollment                               | Recommended   |

## Authentication

All API calls require an OAuth 2.0 Bearer token obtained from the PayPal token endpoint.

```
# Obtain a token:
POST https://api-m.sandbox.paypal.com/v1/oauth2/token
Authorization: Basic <Base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=<required_scope>

# Pass the token in every request
Authorization: Bearer <access_token>
```

Bearer tokens expire after approximately 8-9 hours. Implement token caching and refresh logic in your client. Do not request a new token on every API call.

> **Note:** The required API scopes for Ecommerce tokenization must be provisioned by the PayPal team before you begin. Work with your PayPal account representative to confirm the correct scopes for your integration.

## Steps for integration

Complete the following steps in order to set up your environment, onboard your TRID, and enroll cards for Ecommerce tokenization. Depending on your use case, enrollment uses either real-time provisioning, where a cardholder adds or updates a card in an interactive flow, or bulk provisioning, which tokenizes existing cards-on-file at scale.

### 1. Set up PayPal sandbox environment

The sandbox is where you test end-to-end using simulators and mocked data — no real authorizations or settlements occur.

**What you need from PayPal's integration team:**

* OAuth client credentials (Client ID and Secret)
* One or more sandbox TRIDs aligned to your business model
* Required authorization scopes

**Environment configuration:**

* PayPal sandbox base URL: `api-m.sandbox.paypal.com`
* Production base URL: `api-m.paypal.com`
* API calls follow the pattern: `https://{base-url}/v1/payment-tokenization/{resource}`

Keep sandbox and live environment credentials completely separate — never share them between environments.

### 2. Onboard your Token Requestor ID (TRID)

To enable tokenization across supported card networks, merchants must first complete onboarding for tokenization. A **TRID** is a unique identifier issued to a token requestor that enables them to securely request network tokens from card networks.

```
POST /v1/payment-tokenization/token-requestors
```

Provide your merchant name, partner name, client credentials, and product template. The response returns your `paypal_token_requestor_id` along with per-network sub-product TRIDs for Visa VTS, Mastercard MDES, American Express AETS, and Discover DDX.

<Tabs>
  <Tab title="Sample request">
    ```bash theme={null}
    curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/token-requestors' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>' \
    -d '{
        "merchant_name": "MerchantName",
        "merchant_account_id": "SZEKQNBKSSQ8L",
        "client_credentials": [
            { "client_id": "asc7678akneqmdalkuf0wj==" },
            { "tenant_name": "TenantName" }
        ],
        "partner_name": "PARTNER_NAME",
        "product_templates": ["PARTNER_TEMPLATE_NAME"],
        "external_reference_id": "extRefId"
    }'
    ```
  </Tab>

  <Tab title="Sample response (201 Created)">
    ```json theme={null}
    {
      "id": "<TRID_ID>",
      "status": "ACTIVE",
      "paypal_token_requestor_id": "<TRID_ID>",
      "merchant_name": "MerchantName",
      "partner_name": "PARTNER_NAME",
      "external_reference_id": "extRefId",
      "merchant_account_id": "SZEKQNBKSSQ8L",
      "additional_attributes": [],
      "products": [
        {
          "product_name": "COF_WALLET_PROVIDER",
          "instrument_product_name": "PPWALLET_COF_ACQUIRING_NTT",
          "status": "ACTIVE",
          "additional_attributes": [],
          "sub_products": [
            {
              "product_name": "COF_ACQUIRING_ECOM_DDX_TPAN",
              "product_type": "OPEN_LOOP_SINGLE_USE",
              "token_requestor_id": { "token_service_provider": "DDX", "value": "<DDX_TRID_ID>" },
              "status": "ACTIVE",
              "additional_attributes": []
            },
            {
              "product_name": "COF_ACQUIRING_ECOM_VTS_TPAN",
              "product_type": "OPEN_LOOP_SINGLE_USE",
              "token_requestor_id": { "token_service_provider": "VTS", "value": "<VTS_TRID_ID>" },
              "status": "ACTIVE",
              "additional_attributes": [
                { "name": "DEVICE_ENROLLMENT_PRODUCT", "value": "VTS_DEVICE_ENROLLMENT_TOKEN" },
                { "name": "DEVICE_BINDING_PRODUCT", "value": "VTS_DEVICE_BINDING_TOKEN" }
              ]
            },
            {
              "product_name": "COF_ACQUIRING_ECOM_AETS_TPAN",
              "product_type": "OPEN_LOOP_SINGLE_USE",
              "token_requestor_id": { "token_service_provider": "AETS", "value": "<AETS_TRID_ID>" },
              "status": "ACTIVE",
              "additional_attributes": []
            }
          ]
        }
      ]
    }
    ```
  </Tab>
</Tabs>

Once registered, verify your TRID with these two calls before proceeding:

* `GET …/token-requestors/{tokenRequestorId}`: confirm your config and supported networks
* `POST …/search-token-requestors`: useful in multi-TRID setups to discover TRIDs by name or status

### 3. Determine minimum API implementation for your business model

| Business Model | Must-Have APIs                                                                     | Optional        |
| -------------- | ---------------------------------------------------------------------------------- | --------------- |
| Merchant       | TRID Mgmt, Enroll, Payment Credential, Lifecycle Mgmt, Webhooks                    | Bulk Enrollment |
| Marketplace    | TRID Mgmt, Enroll, Payment Credential, Lifecycle Mgmt, Webhooks                    | Bulk Enrollment |
| PSP / Enabler  | TRID Mgmt, Enroll, Payment Credential, Lifecycle Mgmt, Webhooks                    | Bulk Enrollment |
| Wallet         | TRID Mgmt, Enroll, Payment Credential, Content Retrieval, Lifecycle Mgmt, Webhooks | Bulk Enrollment |

### 4. Implement real-time token enrollment

#### Choosing between real-time and bulk provisioning

You can use a combination of both real-time and bulk provisioning methods depending on your use cases. The general guideline for partners is as follows:

* If the card is being added or updated by a Cardholder in an interactive flow, use real-time provisioning.

* If the card already exists in a secure vault and needs to be upgraded to a network token at scale, use bulk provisioning.

Use the following interactive flows when a cardholder adds or updates a payment method.

* **Collect card details:** PAN, expiration date, CVV, and cardholder name. Then pass these values in your enrollment request using the `payment_data` object. Use the `base64-encode` option.

* **Call:** Send a `POST` request to [`/v1/payment-tokenization/enrollments`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/enrollment-decision) with the card details. A `201` response returns the `enrollment_id` and `network_token`.

* **Persist:** Keep the `enrollment_id` and `network_token` in your card vault. You'll need both for all subsequent lifecycle and payment credential calls.

<Tabs>
  <Tab title="Sample request">
    ```bash theme={null}
    curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/enrollments' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>' \
    -d '{
      "payment_data": "<base64-encoded PAN, expiry, CVV>",
      "reference_account_id": "REFERENCE-ACCOUNT-ID",
      "applicant": {
        "name": { "given_name": "John", "surname": "Doe" },
        "date_of_birth": "1990-01-01",
        "address": {
          "address_line_1": "1 Main St",
          "admin_area_2": "San Jose",
          "admin_area_1": "CA",
          "postal_code": "95131",
          "country_code": "US"
        },
        "email_address": "johndoe@example.com",
        "phone": { "phone_number": { "national_number": "4085551234" } }
      },
      "locale": "en-US",
      "product_name": "COF_MERCHANT",
      "token_requestor": { "id": "<TRID_ID>" },
      "payment_instrument_input_method": "ONFILE"
    }'
    ```
  </Tab>

  <Tab title="Sample response (201 Created)">
    ```json theme={null}
    {
      "enrollment_id": "<ENROLLMENT_ID>",
      "status": "ACTIVE",
      "reuse_type": "NEW",
      "token_info": {
        "id": "<network_token>",
        "expiry_date": "2028-01",
        "tpan_last4": "1234",
        "account_id": "<account_id>",
        "network_token_requestor_id": "<TRID_ID>",
        "issuer_expiry_date": "2028-01",
        "token_assurance_level": "<assurance_level>"
      },
      "metadata": { "...": "..." },
      "issuer_data": { "...": "..." },
      "contents": [ { "...": "content references, such as card art, and terms and conditions" } ],
      "payment_credentials": [],
      "token_requestor": { "id": "<TRID_ID>" },
      "verification_results": { "...": "..." },
      "device_bindings": [],
      "verification_methods": [],
      "risk_decision": "<risk_decision>"
    }
    ```
  </Tab>
</Tabs>

Run this full flow end-to-end in the sandbox first with PayPal-provided test cards before moving to a live environment.

**PayPal sandbox test cards:**

* **Visa**: `4622943127025676` (success), `4622943127025673` (ineligible)
* **Mastercard**: `5204731530000000` (success), `5204731530000007` (ineligible)
* **American Express (Amex)**: `3717073691911199` (success), `371707369199999` (ineligible)
* **Discover**: Cards starting with `6011000000` (success), Cards starting with `601101000` (PAN ineligible)

<Tabs>
  <Tab title="Sample request: Retrieve card art/Terms & Conditions">
    Use the `content_id` values returned in the enrollment response's contents array to retrieve display assets such as card art:

    ```bash theme={null}
    curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/contents/{content_id}' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>'
    ```
  </Tab>

  <Tab title="Sample response (200 OK)">
    ```json theme={null}
    {
      "content_id": "<content_id>",
      "content_type": "CARD_ART",
      "mime_type": "image/png",
      "width": 600,
      "height": 380,
      "content_cdn_url": "https://<cdn-host>/<path-to-asset>.png"
    }
    ```
  </Tab>
</Tabs>

### 5. Implement bulk enrollment - optional

Use this to asynchronously tokenize large volumes of existing cards-on-file (up to 1,000 for batch).

* **Submit batch:** Send a `POST` request to [`/v1/payment-tokenization/batch-requests`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/batch-post) with a file containing the card details. PP TSP returns a `batch_request_id` to track the batch.
* **Listen:** PP TSP sends a `PAYMENT-TOKENIZATION.BATCH-REQUEST.STATUS-CHANGED` webhook when the batch completes or fails.
* **Retrieve results:** Send a `GET` request to [`/v1/payment-tokenization/batch-requests/{id}`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/batch-get). Append `?fields=ALL` only after the batch reaches `COMPLETED` status to avoid loading partial data.

<Tabs>
  <Tab title="Sample request: Submit a batch enrollment">
    ```bash theme={null}
    curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/batch-requests' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>' \
    -H 'PayPal-Request-Id: <idempotency-key>' \
    -d '{
      "requests": [
        {
          "bulk_id": "enrollment-1",
          "method": "POST",
          "path": "/v1/payment-tokenization/enrollments",
          "body": {
      "payment_data": "<base64-encoded PAN, expiry, CVV>",
      "reference_account_id": "REFERENCE-ACCOUNT-ID",
      "applicant": {
        "name": { "given_name": "John", "surname": "Doe" },
        "date_of_birth": "1990-01-01",
        "address": {
          "address_line_1": "1 Main St",
          "admin_area_2": "San Jose",
          "admin_area_1": "CA",
          "postal_code": "95131",
          "country_code": "US"
        },
        "email_address": "johndoe@example.com",
        "phone": { "phone_number": { "national_number": "4085551234" } }
      },
      "locale": "en-US",
      "product_name": "COF_MERCHANT",
      "token_requestor": { "id": "<TRID_ID>" },
      "payment_instrument_input_method": "ONFILE"
    }
        },
        {
          "bulk_id": "enrollment-2",
          "method": "POST",
          "path": "/v1/payment-tokenization/enrollments",
          "body": {
      "payment_data": "<base64-encoded PAN, expiry, CVV>",
      "reference_account_id": "REFERENCE-ACCOUNT-ID-2",
      "applicant": {
        "name": { "given_name": "John", "surname": "Doe" },
        "date_of_birth": "1990-01-01",
        "address": {
          "address_line_1": "1 Main St",
          "admin_area_2": "San Jose",
          "admin_area_1": "CA",
          "postal_code": "95131",
          "country_code": "US"
        },
        "email_address": "johndoe@example.com",
        "phone": { "phone_number": { "national_number": "4085551234" } }
      },
      "locale": "en-US",
      "product_name": "COF_MERCHANT",
      "token_requestor": { "id": "<TRID_ID>" },
      "payment_instrument_input_method": "ONFILE"
    }
        }
      ]
    }'
    ```
  </Tab>

  <Tab title="Sample response (202 Accepted)">
    ```json theme={null}
    {
      "total_items": 2,
      "details": [
        { "batch_id": "<batch_request_id>", "status": "ACCEPTED" }
      ]
    }
    ```
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Sample request: Get batch status">
    Retrieve the batch tokenization results by sending the following request:

    ```bash theme={null}
    curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/batch-requests/{id}' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>'
    ```
  </Tab>

  <Tab title="Sample response">
    ```json theme={null}
    {
          "total_items": 2,
          "details": [
            {
              "total_batch_items": 2,
              "total_success": 2,
              "batch_id": "11EF-4A21-EE5441F9-A1FB-FA1B92B407D4",
              "status": "COMPLETED",
              "operations": [
                {
                  "method": "POST",
                  "headers": [],
                  "bulk_id": "e5d7b48f-dcd6-4aa7-9cdb-3d77f57c0a37",
                  "status": {
                    "code": "200"
                  },
                  "body": {
                    "verification_results": [],
                    "enrollment_data": [
                      {
                        "token_info": {
                          "id": "2fd1-188667e0-7ab9-46ab-a120-d48d8ff9e3a2",
                          "expiry_date": "2025-12",
                          "tpan_info": "NDg5NTM3MDAxMzM0Njk2Nw==",
                          "tpan_last4": "6967",
                          "account_id": "1234",
                          "network_token_requestor_id": "40010061540"
                        },
                        "metadata": {},
                        "contents": [],
                        "payment_credentials": []
                      }
                    ],
                    "verification_methods": [],
                    "device_bindings": [],
                    "lifecycle_reason_details": [],
                    "reference_account_id": "CBKM9L56PTL4C",
                    "enrollment_id": "8002033245411672066",
                    "status": "ACTIVE"
                  }
                },
                {
                  "method": "POST",
                  "headers": [],
                  "bulk_id": "95bc1aa6-667f-4572-8254-346d6c4a4705",
                  "status": {
                    "code": "200"
                  },
                  "body": {
                    "verification_results": [],
                    "enrollment_data": [
                      {
                        "token_info": {
                          "id": "2fd1-e497c83f-ebbc-4d8d-ae08-57ada9906928",
                          "expiry_date": "2025-12",
                          "tpan_info": "NDg5NTM3MDAxMzM0NTY3OA==",
                          "tpan_last4": "5678",
                          "account_id": "5678",
                          "network_token_requestor_id": "40010061540"
                        },
                        "metadata": {},
                        "contents": [],
                        "payment_credentials": []
                      }
                    ],
                    "verification_methods": [],
                    "device_bindings": [],
                    "lifecycle_reason_details": [],
                    "reference_account_id": "CBKM9L56PTL4C",
                    "enrollment_id": "8002036407153469914",
                    "status": "ACTIVE"
                  }
                }
              ]
            }
          ]
        }
    ```
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Sample request: Get batch details">
    After the batch status is `COMPLETED`, request full item-level details by sending the following request:

    ```bash theme={null}
    curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/batch-requests/{id}?fields=ALL' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>'
    ```
  </Tab>

  <Tab title="Sample response">
    ```json theme={null}
    {
          "total_items": 2,
          "details": [
            {
              "total_batch_items": 2,
              "total_success": 2,
              "batch_id": "11EF-4A21-EE5441F9-A1FB-FA1B92B407D4",
              "status": "COMPLETED",
              "operations": [
                {
                  "method": "POST",
                  "headers": [],
                  "bulk_id": "e5d7b48f-dcd6-4aa7-9cdb-3d77f57c0a37",
                  "status": {
                    "code": "200"
                  },
                  "body": {
                    "verification_results": [],
                    "enrollment_data": [
                      {
                        "token_info": {
                          "id": "2fd1-188667e0-7ab9-46ab-a120-d48d8ff9e3a2",
                          "expiry_date": "2025-12",
                          "tpan_info": "NDg5NTM3MDAxMzM0Njk2Nw==",
                          "tpan_last4": "6967",
                          "account_id": "1234",
                          "network_token_requestor_id": "40010061540"
                        },
                        "metadata": {},
                        "contents": [],
                        "payment_credentials": []
                      }
                    ],
                    "verification_methods": [],
                    "device_bindings": [],
                    "lifecycle_reason_details": [],
                    "reference_account_id": "CBKM9L56PTL4C",
                    "enrollment_id": "8002033245411672066",
                    "status": "ACTIVE"
                  }
                },
                {
                  "method": "POST",
                  "headers": [],
                  "bulk_id": "95bc1aa6-667f-4572-8254-346d6c4a4705",
                  "status": {
                    "code": "200"
                  },
                  "body": {
                    "verification_results": [],
                    "enrollment_data": [
                      {
                        "token_info": {
                          "id": "2fd1-e497c83f-ebbc-4d8d-ae08-57ada9906928",
                          "expiry_date": "2025-12",
                          "tpan_info": "NDg5NTM3MDAxMzM0NTY3OA==",
                          "tpan_last4": "5678",
                          "account_id": "5678",
                          "network_token_requestor_id": "40010061540"
                        },
                        "metadata": {},
                        "contents": [],
                        "payment_credentials": []
                      }
                    ],
                    "verification_methods": [],
                    "device_bindings": [],
                    "lifecycle_reason_details": [],
                    "reference_account_id": "CBKM9L56PTL4C",
                    "enrollment_id": "8002036407153469914",
                    "status": "ACTIVE"
                  }
                }
              ]
            }
          ]
        }
    ```
  </Tab>
</Tabs>

### 6. Integrate payment credentials into your auth flow

For card-not-present authorizations, call the payment-credentials API to retrieve the network token and cryptogram before constructing the authorization request, then pass these values to your payment processor.

* **Call:** Send a `POST` request to [`/v1/payment-tokenization/payment-credentials`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/token-provisioning) with token details and transaction data.
  `payment-credentials` endpoint supports two modes, fetch and pre-fetch, which you can select through the `Prefer: respond-async` header.
  Call just-in-time for Cardholder-Initiated Transaction (CIT) transactions. Cryptograms are single-use and have a limited validity window.
* The response returns the **network token**, **cryptogram**, and **Electronic Commerce Indicator (ECI)** needed for authorization. Use these values instead of the original card data when processing the payment.
* **Pass these fields unchanged** into the authorization message to your payment processor. This replaces the raw card number entirely.

<Tabs>
  <Tab title="Sample request: Fetch, synchronous">
    ```bash theme={null}
    curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/payment-credentials' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>' \
    -d '{
      "enrollment_id": "<ENROLLMENT_ID>",
      "product_type": "OPEN_LOOP_SINGLE_USE",
      "credential_type": "E_COMMERCE_LONG_FORM",
      "applicant": {
        "email_address": "johndoe@example.com",
        "phone": { "phone_number": { "national_number": "4085551234" } },
        "address": { "...": "billing address" }
      },
      "amount": { "total": { "currency_code": "USD", "value": "49.99" } }
    }'
    ```
  </Tab>

  <Tab title="Sample request: Prefetch, asynchronous">
    Identical to the synchronous request, plus this header: `Prefer: respond-async`.

    ```bash theme={null}
    curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/payment-credentials' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>' \
    -H 'Prefer: respond-async' \
    -d '{
      "enrollment_id": "<ENROLLMENT_ID>",
      "product_type": "OPEN_LOOP_SINGLE_USE",
      "credential_type": "E_COMMERCE_LONG_FORM",
      "applicant": {
        "email_address": "johndoe@example.com",
        "phone": { "phone_number": { "national_number": "4085551234" } },
        "address": { "...": "billing address" }
      },
      "amount": { "total": { "currency_code": "USD", "value": "49.99" } }
    }'
    ```
  </Tab>

  <Tab title="Sample response">
    ```json theme={null}
    {
      "token_info": {
        "id": "<network_token>",
        "expiry_date": "2028-01",
        "tpan_info": { "...": "..." },
        "tpan_last4": "1234",
        "account_id": "<account_id>",
        "network_token_requestor_id": "<TRID_ID>",
        "issuer_expiry_date": "2028-01",
        "payment_account_reference": "<PAR>"
      },
      "payment_credentials": [
        {
          "tpan_id": "<tpan_id>",
          "payment_credential_id": "<credential_id>",
          "credential_type": "E_COMMERCE_LONG_FORM",
          "payment_credential_data": "<cryptogram / ECI data>"
        }
      ],
      "links": [ { "...": "..." } ]
    }
    ```
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Sample Account Funding Transaction request">
    ```bash theme={null}
    curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/payment-credentials' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>' \
    -d '{
        "credential_type": "E_COMMERCE_LONG_FORM",
        "enrollment_id": "<ENROLLMENT_ID>",
        "amount": {
           "total": {
              "value": "12.00",
              "currency_code": "USD"
           }
        },
        "purchase_context": {"transaction_type":"ACCOUNT_FUND_TRANSFER"},
        "ttl_duration": "PT30M"
    }'
    ```
  </Tab>

  <Tab title="Sample response">
    ```json theme={null}
    {
      "token_info": {
        "id": "<network_token>",
        "expiry_date": "2028-01",
        "tpan_info": { "...": "..." },
        "tpan_last4": "1234",
        "account_id": "<account_id>",
        "network_token_requestor_id": "<TRID_ID>",
        "issuer_expiry_date": "2028-01",
        "payment_account_reference": "<PAR>"
      },
      "payment_credentials": [
        {
          "tpan_id": "<tpan_id>",
          "payment_credential_id": "<credential_id>",
          "credential_type": "E_COMMERCE_LONG_FORM",
          "payment_credential_data": "<cryptogram / ECI data>"
        }
      ],
      "links": [ { "...": "..." } ]
    }
    ```
  </Tab>
</Tabs>

### 7. Handle token lifecycle changes

Lifecycle changes must be mirrored in your vault immediately.

| Action                                                 | Endpoint                                                  |
| ------------------------------------------------------ | --------------------------------------------------------- |
| Suspend enrollment, update vault to `SUSPENDED`        | `POST /v1/payment-tokenization/enrollments/{id}/suspend`  |
| Reactivate enrollment, update vault to `ACTIVE`        | `POST /v1/payment-tokenization/enrollments/{id}/activate` |
| Close enrollment (network token closed asynchronously) | `POST /v1/payment-tokenization/enrollments/{id}/close`    |

A suspension only pauses the enrollment. A close is permanent and cannot be undone. It cascades to the underlying network token, which is closed asynchronously.

For **issuer-initiated changes**, such as card reissue, expiration date update, and fraud replacement, PP TSP automatically propagates them and notifies you using `PAYMENT-TOKENIZATION.TOKEN-STATUS.CHANGED` or `PAYMENT-TOKENIZATION.TOKEN-METADATA.CHANGED` webhooks. Process these events to keep your vault in sync.

### 8. Register and test the webhooks

Subscribe to these webhook events to keep your systems current:

| Event                                               | Description                                                | Requirement   |
| --------------------------------------------------- | ---------------------------------------------------------- | ------------- |
| `PAYMENT-TOKENIZATION.BATCH-REQUEST.STATUS-CHANGED` | Batch completion/failure                                   | **Mandatory** |
| `PAYMENT-TOKENIZATION.TOKEN-METADATA.CHANGED`       | Card art, terms and conditions (T\&C), or metadata updates | **Mandatory** |
| `PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.UPDATED`   | Credential changes                                         | **Mandatory** |
| `PAYMENT-TOKENIZATION.TOKEN-REQUESTOR.UPDATED`      | TRID configuration changes                                 | **Mandatory** |
| `PAYMENT-TOKENIZATION.TOKEN-STATUS.CHANGED`         | Token activated, suspended, or closed                      | **Mandatory** |

#### Sample webhook payloads

Each event is delivered to your registered endpoint in this envelope:

```json theme={null}
{
  "status": "200 OK",
  "headers": { "...": "..." },
  "body": {
    "events": [
      {
        "event_type": "<EVENT_NAME>",
        "resource": { "...": "event-specific resource fields" },
        "links": [ { "...": "..." } ]
      }
    ]
  }
}
```

`PAYMENT-TOKENIZATION.TOKEN-STATUS.CHANGED`

```json theme={null}
{ "event_type": "PAYMENT-TOKENIZATION.TOKEN-STATUS.CHANGED", "resource": { "enrollment_id": "<enrollment_id>" }, "links": [] }
```

`PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.UPDATED`

```json theme={null}
{ "event_type": "PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.UPDATED", "resource": { "enrollment_id": "<enrollment_id>", "payment_credential_id": "<credential_id>" }, "links": [] }
```

`PAYMENT-TOKENIZATION.TOKEN-METADATA.CHANGED`

```json theme={null}
{ "event_type": "PAYMENT-TOKENIZATION.TOKEN-METADATA.CHANGED", "resource": { "enrollment_id": "<enrollment_id>" }, "links": [] }
```

`PAYMENT-TOKENIZATION.BATCH-REQUEST.STATUS-CHANGED`

```json theme={null}
{ "event_type": "PAYMENT-TOKENIZATION.BATCH-REQUEST.STATUS-CHANGED", "resource": { "batch_id": "<batch_request_id>" }, "links": [] }
```

`PAYMENT-TOKENIZATION.TOKEN-REQUESTOR.UPDATED`

```json theme={null}
{ "event_type": "PAYMENT-TOKENIZATION.TOKEN-REQUESTOR.UPDATED", "resource": { "id": "<trid>" }, "links": [] }
```

> **Note:** Looking for detailed documentation?
> A comprehensive Ecommerce Solution Guide, Integration Guide, and API Specification Document are available upon request. The API Specification Document includes sample reference payloads and end-to-end use case examples specific to Ecommerce network tokenization, covering all APIs and common integration scenarios.
> Reach out to your PayPal Account Representative for the latest documentation.


# Ecommerce network tokenization
Source: https://docs.paypal.ai/limited-release/tokenization/e-commerce/overview



Ecommerce network tokenization replaces stored card numbers (PANs) with network-issued tokens (TPANs) for use in card-not-present transactions. Tokens are unique to each token requestor and card, and each payment requires a one-time cryptogram. This is a dynamic security value bound to a single transaction and is not reusable. Even if a token is compromised, it cannot be used to initiate a transaction without a valid cryptogram.

## Network tokenization advantages

Storing raw card numbers across merchant systems creates serious security risks. Network tokenization eliminates this risk at its root. Sensitive card data is never transmitted or stored in the clear at any stage of the payment flow. Instead, the real card number is replaced with a network-issued token, scoped to a specific merchant, token requestor, and the underlying card it was issued for. Each transaction is further secured by a unique, one-time cryptogram, ensuring even a compromised token cannot be replayed or reused outside its intended scope.

### Better authorization rates

Tokenized transactions include richer data that helps card issuers make smarter approval decisions, resulting in higher acceptance rates than with standard card transactions. For merchants processing large volumes, better authorization rates mean more completed sales and less lost revenue, making tokenization a performance upgrade, not just a security measure.

### Key benefits

| Benefit                        | Description                                                                                                                                                  |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Enhanced security              | Network tokens and one-time cryptograms protect card data. A stolen token alone cannot be used to complete a transaction.                                    |
| Higher authorization rates     | Richer token data improves issuer risk decisions, increasing approvals by 200–500 bps.                                                                       |
| Reduced PCI scope              | Partners do not store or transmit raw card data, significantly simplifying PCI DSS compliance.                                                               |
| Processor-agnostic             | Route tokenized transactions to any processor — no lock-in to a specific acquirer.                                                                           |
| Automated lifecycle management | When a card expires, is reissued, or replaced, the associated token is updated automatically. Transactions continue without disruption.                      |
| Card art display               | Display issuer-provided card images in your UI, helping cardholders identify and select the right card — improving conversion and reducing selection errors. |
| Reduced integration complexity | One integration with PayPal covers all supported networks: Visa, Mastercard, American Express, and Discover.                                                 |

### Network tokenization frameworks

Secure Credential Services supports Ecommerce network tokenization across a range of business structures. Your business model determines how Token Requestor IDs (TRIDs) are scoped and how tokens are shared or isolated across your merchants or users.

| Business Model                    | TRID Model                              | Token Scope                   | Token Sharing                        | Who Controls Processing              |
| --------------------------------- | --------------------------------------- | ----------------------------- | ------------------------------------ | ------------------------------------ |
| Enterprise / Individual Merchants | One TRID per merchant                   | Per merchant                  | Not shared across merchants          | Merchant                             |
| Digital Wallets                   | One TRID per wallet                     | Per wallet                    | Not shared outside the wallet        | Wallet provider                      |
| PSPs & Gateways                   | PSP parent + child TRID per merchant    | Per merchant TRID             | Not shared across merchants          | PSP provisions; merchant processes   |
| Marketplaces / Commerce Platforms | Single marketplace TRID or seller TRIDs | Per marketplace or per seller | Shared (single) or isolated (seller) | Marketplace (and optionally sellers) |
| Payment Enablers                  | One TRID per enabler                    | Per enabler                   | Not shared outside enabler network   | Enabler                              |

> **Note** Tokens are unique for each combination of TRID + FPAN + User Account ID. Under a PSP or marketplace using per-merchant TRIDs, the same card enrolled with different merchants produces a separate token for each. Under a single shared marketplace TRID, the same card produces one token used across all sellers in that marketplace.
> If you're unsure which model fits your business structure, contact your PayPal account representative.

## Architecture

PP TSP serves as the single integration point between your platform and the card networks. Rather than building and maintaining separate connections to Visa, Mastercard, Discover, and American Express, you integrate with PP TSP, after which it handles token provisioning, cryptogram generation, and lifecycle management across all networks on your behalf.

![Network Tokenization Framework](https://www.paypalobjects.com/ppdevdocs/nfc.png)

### How Ecommerce tokenization works end to end

* You register with PP TSP and receive a Token Requestor ID (TRID) for each supported card network. The TRID identifies your platform in all tokenization requests.

* A cardholder stores a card with your platform. You send the card details to PP TSP to initiate enrollment.

* PP TSP forwards the request to the card network and issuer for approval, then returns a TPAN and enrollment metadata.

* You store the TPAN in place of the card number. The original card number (FPAN) is no longer needed for transaction processing.

* At checkout, request a one-time **cryptogram** from PP TSP. The cryptogram is generated by the card network and scoped to the specific transaction — it cannot be reused. Submit the TPAN and cryptogram to your payment processor, which constructs and routes the authorization request to the card network and issuer. The issuer validates both values and returns an approval or decline.

* PP TSP handles the token lifecycle on your behalf. If the underlying card changes — due to renewal, re-issuance, or an account update — PP TSP updates the token automatically and notifies you using webhooks. No cardholder re-enrollment required.

For step-by-step implementation details, see the [Integration Guide](/limited-release/tokenization/e-commerce/integration).


# NFC Device Tokenization Overview
Source: https://docs.paypal.ai/limited-release/tokenization/nfc/device-tokenization



## Overview

You can use device tokenization to provision payment credentials onto Near Field Communication (NFC)-enabled devices so that cardholders can make secure tap-to-pay transactions at point-of-sale terminals.

NFC device tokenization works by replacing a cardholder's real payment credentials, such as a card number, with a tokenized primary account number (TPAN) issued by the network. This payment credential replaces the real card number and is safe to store on a device.

Device tokenization is offered as part of [**Secure Credential Services (SCS) by PayPal**](/limited-release/tokenization/secure-credential/scs/). Rather than building and maintaining separate integrations with each payment network, device partners integrate once with PayPal Token Service Provider (PP TSP). This single, certified path covers token provisioning, payment credential delivery, lifecycle management, and outbound webhook notifications across all supported networks. PP TSP handles sensitive card data on your behalf, significantly reducing your PCI DSS scope.

> **Note:** This page covers NFC device tokenization. It is distinct from PayPal's Ecommerce Network Tokenization (card-not-present) offering. Do not use this guide for online checkout integrations.

### Tokenization flow

NFC device tokenization involves five participants who interact from initial card enrollment, through everyday tap-to-pay use, and ongoing lifecycle management.

![Swimlane diagram showing the five participants, Cardholder, Device Partner/Wallet Server, PP TSP, Card networks, and Issuers, and how they interact across device registration, enrollment, tokenization, credential delivery, tap to pay, and lifecycle management.](https://www.paypalobjects.com/ppdevdocs/nfc/tokenization-flow-diagram.svg)

Each participant has a specific role in that process:

| Participant                    | Role                                                                                                                                                 |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cardholder                     | Adds a card to their NFC-enabled device and initiates tap-to-pay transactions at point of sale.                                                      |
| Device Partner / Wallet Server | The device partner's backend. Calls PP TSP APIs to register devices, manage enrollments, fetch payment credentials, and handle lifecycle operations. |
| PP TSP                         | Provisions network tokens, stores and delivers payment credentials, manages token lifecycle, and publishes webhook events to Wallet Server.          |
| Card networks                  | Issue and manage network tokens and payment credentials. PP TSP mediates all interactions with the networks on your behalf.                          |
| Issuers                        | Approve tokenization requests and authorize NFC transactions at point of sale.                                                                       |

### How NFC device tokenization works end to end

NFC device tokenization happens in three stages: enrollment and activation, credential provisioning and tap to pay, and lifecycle management. Each stage is shown in its own diagram.

#### Device registration and token enrollment

The device partner registers the device and enrolls the cardholder's card, then the card network decides whether the token activates immediately or needs identity verification (IDV) first.

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor Cardholder
    participant Wallet as Device Partner / Wallet Server
    participant TSP as PP TSP
    participant Network as Card Network
    participant Issuer as Issuer

    Wallet->>TSP: Register NFC device
    TSP-->>Wallet: device_id

    Cardholder->>Wallet: Authenticate & select card to add
    Wallet->>TSP: Create enrollment (encrypted card details)
    TSP->>Network: Check card eligibility
    TSP-->>Wallet: enrollment_id & T&C id

    Cardholder->>Wallet: Accept terms & conditions
    Wallet->>Network: Submit tokenization request (via TSP)

    alt Green path — no IDV required
        Network-->>TSP: Token → ACTIVE
    else Yellow path — IDV required
        Network-->>TSP: Token → PENDING_VERIFICATION_REQUIRED
        Issuer->>Cardholder: Request identity verification (IDV)
        Cardholder->>Issuer: Complete IDV
        Issuer-->>Network: IDV result
        Network-->>TSP: Token → ACTIVE
    end
```

1. The device partner registers the NFC device with PP TSP and receives a unique `device_id`.
2. The cardholder authenticates and selects a card to add to their PayPal wallet.
3. The Wallet Server creates an enrollment with PP TSP, including encrypted card details. PP TSP checks card eligibility with the card network and returns an enrollment ID and a terms and conditions (T\&C) ID.
4. The cardholder reviews and accepts the T\&C. The Wallet Server submits a tokenization request to the card network through PP TSP.
5. The card network determines the token activation path:
   * **Green path**: no IDV required. The token is provisioned and moves to `ACTIVE`.
   * **Yellow path:** IDV required. The token is held in `PENDING_VERIFICATION_REQUIRED` until the cardholder completes verification, after which it moves to `ACTIVE`. If IDV is not completed, the token remains in this state and cannot be used for transactions.

#### Credential provisioning and tap to pay

PP TSP provisions the payment credential for the Wallet Server to fetch, then the cardholder can tap to pay.

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor Cardholder
    participant Wallet as Device Partner / Wallet Server
    participant TSP as PP TSP
    participant Network as Card Network
    participant Issuer as Issuer

    TSP-)Wallet: Webhook — PAYMENT-CREDENTIAL.CREATED
    Wallet->>TSP: Fetch credentials & acknowledge
    TSP->>Network: Confirm successful provisioning

    Cardholder->>Network: Tap device (one-time cryptogram)
    Network->>Issuer: Request authorization
    Network-->>TSP: Transaction result
    TSP-)Wallet: Webhook — TRANSACTION.CREATED
```

1. PP TSP provisions the TPAN, caches encrypted payment credentials, and notifies the Wallet Server using a `PAYMENT-CREDENTIAL.CREATED` webhook.
2. The Wallet Server fetches the payment credentials and acknowledges receipt. PP TSP notifies the card network that provisioning was successful.
3. The credential is ready for tap to pay. Each transaction generates a one-time cryptogram bound to the token and the specific transaction context. PP TSP sends a `TRANSACTION.CREATED` webhook after each tap.

#### Token lifecycle management

PP TSP manages the ongoing token lifecycle, keeping the token synchronized with the payment method and notifying the Wallet Server whenever the card issuer or network changes its status.

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant Wallet as Device Partner / Wallet Server
    participant TSP as PP TSP
    participant Network as Card Network
    participant Issuer as Issuer

    Issuer->>Network: Trigger status change
    Network->>TSP: Propagate change
    TSP-)Wallet: Webhook — TOKEN-STATUS.CHANGED
    Note over Wallet: SUSPENDED = declined until reactivated · ACTIVE = reactivated · CLOSED = permanent, blocked
```

1. The card issuer sends the card network a status change for the payment method.
2. The card network sends the status change to the PP TSP.
3. PP TSP sends a `TOKEN-STATUS.CHANGED` webhook to the Wallet Server to update the token for that payment method.

PP TSP supports the following token state changes:

* **Suspension:** token moves to `SUSPENDED`. NFC transactions are declined until the token is reactivated.
* **Reactivation:** token returns to `ACTIVE`.
* **Permanent deactivation:** token moves to `CLOSED`. Tap to pay is blocked. This state cannot be reversed.

### Next steps

* [**Integration Guide**](/limited-release/tokenization/nfc/integration/): Step-by-step instructions for connecting to PP TSP, including authentication, endpoint configuration, and webhook setup.
* [**API Reference**](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/registerdevice): Full specification for all PP TSP endpoints, request/response schemas, and error codes.
* [**Key Concepts**](/limited-release/tokenization/nfc/key-concepts/): Definitions for terms and abbreviations used throughout the NFC device tokenization documentation.

> **Note:** For questions about eligibility or onboarding, contact your PayPal Technical Account Manager.


# NFC Device Tokenization Integration
Source: https://docs.paypal.ai/limited-release/tokenization/nfc/integration



This guide walks through the end-to-end implementation of NFC Device Tokenization using Secure Credential Services by PayPal.

## Prerequisites

To integrate with Secure Credential Services NFC Device Tokenization, you need:

* A PayPal business account with a Client ID provisioned for NFC device tokenization
* OAuth 2.0 credentials (Client ID and Client Secret)
* A Token Requestor ID (TRID), a unique 11-digit identifier obtained via TRID onboarding with the PayPal integration team
* A device product configuration and sandbox test card data from your PayPal integration team
* Registered HTTPS webhook endpoint for receiving PP TSP event notifications

> **Note:** Contact your PayPal integration team to obtain sandbox OAuth credentials, a device product configuration, and test card data before starting. Configure sandbox and production environments separately: never share credentials between environments.

## API reference

Use the following base URLs and endpoints for all Payment Tokenization requests.

### Base URLs

All paths are prefixed [`/v1/payment-tokenization/`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/). All PayPal REST API requests target one of two base URLs:

| Environment | Base URL                           |
| ----------- | ---------------------------------- |
| Sandbox     | `https://api-m.sandbox.paypal.com` |
| Production  | `https://api-m.paypal.com`         |

### List of APIs

| Method | Endpoint                                                                                                                                                                                          | Purpose                                                                  | Requirement   |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------- |
| `POST` | [`/v1/payment-tokenization/devices`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/registerdevice)                                                                     | Register an NFC-enabled device                                           | **Mandatory** |
| `POST` | [`/v1/payment-tokenization/enrollments`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/enrollment-decision)                                                            | Create a card enrollment (initiate provisioning)                         | **Mandatory** |
| `GET`  | [`/v1/payment-tokenization/enrollments/{id}`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/enrollment-status)                                                         | Retrieve enrollment details and token information                        | **Mandatory** |
| `POST` | [`/v1/payment-tokenization/enrollments/{id}/tokens`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/token-creation)                                                     | Request token digitization from the card network                         | **Mandatory** |
| `GET`  | [`/v1/payment-tokenization/contents/{content_id}`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/get-content)                                                          | Retrieve T\&C, card art, or other display assets                         | **Mandatory** |
| `GET`  | `/v1/payment-tokenization/enrollments/{id}/identity-verifications`                                                                                                                                | Get available IDV methods (Yellow Path). Applicable only for Visa cards. | **Mandatory** |
| `POST` | [`/v1/payment-tokenization/enrollments/{id}/identity-verifications/{idv_id}/deliver`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/deliver-idv)                       | Deliver the chosen verification method (OTP, etc.)                       | **Mandatory** |
| `POST` | [`/v1/payment-tokenization/enrollments/{id}/identity-verifications/{idv_id}/validate`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/validate-idv)                     | Validate the user's verification code                                    | **Mandatory** |
| `POST` | [`/v1/payment-tokenization/payment-credentials`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/token-provisioning)                                                     | Fetch full or dynamic payment credentials                                | **Mandatory** |
| `POST` | [`/v1/payment-tokenization/enrollments/{id}/payment-credentials/{cred_id}/acknowledge`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/acknowledge-payment-credentials) | Acknowledge receipt of payment credentials                               | **Mandatory** |
| `POST` | [`/v1/payment-tokenization/enrollments/{id}/activate`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/token-activate)                                                   | Reactivate a suspended enrollment                                        | Recommended   |
| `POST` | [`/v1/payment-tokenization/enrollments/{id}/suspend`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/token-suspend)                                                     | Temporarily suspend a token enrollment                                   | Recommended   |
| `POST` | [`/v1/payment-tokenization/enrollments/{id}/close`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/token-close)                                                         | Permanently close a token enrollment                                     | **Mandatory** |
| `GET`  | [`/v1/payment-tokenization/transactions`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/get-transactions)                                                              | Query transaction history for a token or enrollment                      | Recommended   |

## Authentication

All API calls require an OAuth 2.0 Bearer token obtained from the PayPal token endpoint.

```
# Obtain a token:
POST https://api-m.sandbox.paypal.com/v1/oauth2/token
Authorization: Basic <Base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

# Pass the token in every request
Authorization: Bearer <access_token>
```

Bearer tokens expire after approximately 8-9 hours. Implement token caching and refresh logic in your client: do not request a new token on every API call.

## Steps for integration

Complete the following steps to onboard your TRID, register a device, and enroll a card for NFC tokenization. Depending on the card network's response, enrollment follows either the Green Path, where the card is approved without additional verification, or the Yellow Path, which requires additional identity verification.

### 1. Complete TRID onboarding

Before initiating any card enrollment, the device partner must complete Token Requestor ID (TRID) onboarding with PayPal TSP. The TRID is a unique 11-digit identifier required in all enrollment and payment credential API calls.

Work with your PayPal integration team to complete TRID onboarding and obtain your PP TRID. Include it in the `token_requestor.id` field of all enrollment and payment credential API requests.

### 2. Register the device

Device registration is a one-time operation that establishes a trusted device identity with PayPal TSP. The returned `device_id` is used in all subsequent enrollment calls.

```
POST /v1/payment-tokenization/devices
```

On success, PP TSP returns a unique `device_id`. Store this securely and include it in all subsequent card enrollment requests. Do not re-register the same device.

<Tabs>
  <Tab title="Sample request">
    ```
    curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/devices' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>' \
    -d '{
      "device_info": {
        "external_device_id": "04a4bbce-1d03-4bbc-aa21-1b6a22afee01",
        "device_type": "WEARABLE",
        "extended_device_data": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
      },
      "certificates": {
        "device_certificates": [
          { "certificate_usage": "CONFIDENTIALITY", "certificate_format": "X509", "certificate_value": "28 A3 49 78 FA 12 37 44 81 B7 C3 93 C1 ..." },
          { "certificate_usage": "INTEGRITY", "certificate_format": "X509", "certificate_value": "78 A3 44 21 1A 22 47 B8 B1 B7 C3 32 45 ..." },
          { "certificate_usage": "DEVICE_ROOT", "certificate_format": "X509", "certificate_value": "22 A4 54 81 FA 28 34 BB C2 A1 28 28 12 ..." }
        ]
      },
      "wallet_id": "0esfiuy197akh091nq93j383uj8js",
      "product_name": "PPWALLET_NFC_TOKEN_PROVIDER"
    }'
    ```
  </Tab>

  <Tab title="Sample response">
    ```
    {
      "device_id": "<device_id>",
      "external_device_id": "04a4bbce-1d03-4bbc-aa21-1b6a22afee01",
      "status": "ACTIVE",
      "links": [
        { "rel": "self", "method": "GET", "href": ".../v1/payment-tokenization/devices/<device_id>" },
        { "rel": "enrollments", "method": "POST", "href": ".../v1/payment-tokenization/devices/<device_id>/enrollments" }
      ]
    }
    ```
  </Tab>
</Tabs>

### 3. Enroll a card (Green Path)

The Green Path is the standard provisioning flow where a card is approved for tokenization without additional user identity verification.

#### 3a. Create enrollment

After the user authenticates and selects a card, submit the enrollment request with encrypted card details:

```
POST /v1/payment-tokenization/enrollments
```

PP TSP checks card eligibility with the card network and returns an `enrollment_id`, a Terms & Conditions (T\&C) ID, and an initial enrollment status of `PENDING_TOKEN_CREATION`.

<Tabs>
  <Tab title="Sample request">
    ```
    curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/enrollments' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>' \
    -d '{
      "payment_data": "<base64-encoded card details>",
      "locale": "en-US",
      "product_name": "PPWALLET_DEVICE_TOKEN",
      "token_requestor": { "id": "<TRID_ID>" },
      "device_info": { "device_id": "656E5DYUS6EQL" },
      "payment_instrument_input_method": "MANUAL"
    }'
    ```
  </Tab>

  <Tab title="Sample response">
    ```
    {
      "enrollment_id": "<ENROLLMENT_ID>",
      "status": "PENDING_TOKEN_CREATION",
      "enrollment_data": {
        "contents": [
          { "content_id": "<content_id>", "content_type": "TERMS_AND_CONDITIONS" }
        ]
      },
      "links": [
        { "rel": "self", "method": "GET", "href": ".../v1/payment-tokenization/enrollments/<ENROLLMENT_ID>" }
      ]
    }
    ```
  </Tab>
</Tabs>

#### 3b. Retrieve and display T\&C, card art, and other assets

```
GET /v1/payment-tokenization/contents/{content_id}
```

Retrieve the T\&C and other content and display it to the user. Capture explicit user consent before proceeding.

<Tabs>
  <Tab title="Sample request">
    ```
    curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/contents/{CONTENT_ID}' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>'
    ```
  </Tab>

  <Tab title="Sample response">
    ```
    {
       "content_id":"<CONTENT_ID>",
       "content_type":"CARD_ART",
       "mime_type":"image/png",
       "width":"256",
       "height":"256",
       "content_cdn_url":"<URL>"
    }
    ```
  </Tab>
</Tabs>

#### 3c. Tokenize the card

```
POST /v1/payment-tokenization/enrollments/{id}/tokens
```

PP TSP requests token digitization from the card network. The network responds with a Token Unique Reference (TUR), token details, and an initial token status: either `ACTIVE`, `PENDING_TOKEN_ACTIVATION`, or `PENDING_VERIFICATION_REQUIRED`.

If the token is not immediately active, PayPal TSP will send a `PAYMENT-TOKENIZATION.TOKEN-STATUS.CHANGED` notification when the token is activated.

PayPal TSP sends a `PAYMENT-TOKENIZATION.ENROLLMENT.CREATED` webhook followed by a `PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.CREATED` webhook once credentials are provisioned.

<Tabs>
  <Tab title="Sample request">
    ```
    curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/enrollments/<ENROLLMENT_ID>/tokens' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>' \
    -d '{
       "token_info":{
          "tsp_info":{
             "type":"VTS",
             "network_enrollment_id":"58efa5580d5646a0d7cc1162f205b302"
          },
          "wallet_provider_info":{
             "enrollment_id":"71bb9617b76614ed0b871bf4177a5302",
             "name":"THALES",
             "product_id":"VTSMOCK_Pay_001",
             "product_name":"Visa Card"
          },
          "payment_account_reference":"<REF_ID>",
          "expiry_date":"2027-12",
          "tpan_last4":"9747",
          "issuer_expiry_date":"2026-12",
          "account_id":"2432"
       },
       "metadata":{
          "long_description":"Visa Card",
          "short_description":"Visa Card"
       },
       "issuer_data":{
          "name":"Visa Test",
          "email":"visatest_02@visa.com",
          "toc_url":"https://terms.html"
       }
    }'
    ```
  </Tab>

  <Tab title="Sample response: 201 Created">
    ```
    {
       "enrollment":{
          "enrollment_id":"<ENROLLMENT_ID>",
          "status":"ACTIVE",
          "enrollment_data":[
             {
                "token_info":{
                   "id":"<TOKEN_ID>",
                   "tpan_last4":"9747",
                   "issuer_expiry_date":"2026-12",
                   "account_id":"2432",
                   "issuing_country_code":"US",
                   "payment_account_reference":"<REF_ID>",
                   "tsp_info":{
                      "type":"VTS",
                      "network_enrollment_id":"58efa5580d5646a0d7cc1162f205b302"
                   }
                }
             }
          ]
       },
       "idv_decision":"APPROVED"
    }
    ```
  </Tab>
</Tabs>

### 4. Enroll a card (Yellow Path)

The Yellow Path extends the Green Path when the card network requires additional identity verification (IDV) before activating the token.

#### 4a. Get verification methods

```
GET /v1/payment-tokenization/enrollments/{id}/identity-verifications
```

Returns available IDV methods such as SMS OTP, email, and app-to-app. Present these options to the user.

<Tabs>
  <Tab title="Sample request">
    ```
    curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/enrollments/<ENROLLMENT_ID>/identity-verifications' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>'
    ```
  </Tab>

  <Tab title="Sample response: 200 OK">
    ```
    {
       "verification_methods":[
          {
             "id":"idv-method-sms-001",
             "method_type":"SMS",
             "value":"+1-XXX-XXX-7890"
          },
          {
             "id":"idv-method-email-002",
             "method_type":"EMAIL",
             "value":"u***r@example.com"
          }
       ],
       "links":[
          {
             "rel":"self",
             "method":"GET",
             "href":"https://api-m.sandbox.paypal.com/v1/payment-tokenization/enrollments/<ENROLLMENT_ID>/identity-verifications"
          },
          {
             "rel":"deliver",
             "method":"POST",
             "href":"https://api-m.sandbox.paypal.com/v1/payment-tokenization/enrollments/<ENROLLMENT_ID>/identity-verifications/idv-method-sms-001/deliver"
          }
       ]
    }
    ```
  </Tab>
</Tabs>

#### 4b. Submit verification

```
POST /v1/payment-tokenization/enrollments/{id}/identity-verifications/{idv_id}/deliver
```

PP TSP forwards the IDV delivery request to the card network. The response includes OTP expiry details.

<Tabs>
  <Tab title="Sample request">
    ```
    curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/enrollments/<ENROLLMENT_ID>/identity-verifications/idv-method-sms-001/deliver' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>'
    ```
  </Tab>

  <Tab title="Sample response">
    ```
    {
       "otp_expiration_time":"2026-05-12T10:30:00Z",
       "max_otp_retries":3,
       "max_new_otp_requests":5,
       "links":[
          {
             "rel":"validate",
             "method":"POST",
             "href":"https://api-m.sandbox.paypal.com/v1/payment-tokenization/enrollments/<ENROLLMENT_ID>/identity-verifications/idv-method-sms-001/validate"
          }
       ]
    }
    ```
  </Tab>
</Tabs>

#### 4c. Validate OTP

```
POST /v1/payment-tokenization/enrollments/{id}/identity-verifications/{idv_id}/validate
```

Submit the user's OTP. Returns `HTTP 204` on success. After successful IDV, the card network sends a provisioning notification to PP TSP, which caches the credentials and sends a `PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.CREATED` webhook.

<Tabs>
  <Tab title="Sample request">
    ```
    curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/enrollments/<ENROLLMENT_ID>/identity-verifications/idv-method-sms-001/validate' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>' \
    -H 'Content-Type: application/json' \
    -d '{
        "idv_code": "457291",
        "idv_code_type": "ONE_TIME_PASSCODE"
    }'
    ```
  </Tab>

  <Tab title="Sample response">
    ```
    204 No Content
    ```
  </Tab>
</Tabs>

### 5. Fetch payment credentials

After receiving the `PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.CREATED` webhook, fetch and acknowledge payment credentials. Repeat this step whenever the device's credential cache needs replenishing.

#### 5a. Retrieve enrollment and credential details

Confirm the enrollment state and retrieve the payment credential metadata:

```
GET /v1/payment-tokenization/enrollments/{id}
```

Use the `enrollment_id` and `payment_credential_id` from the webhook payload. Skip this step when replenishing an existing enrollment: you already have this context from the initial fetch.

#### 5b. Fetch credentials

After receiving the `PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.CREATED` webhook, fetch the full encrypted credentials:

```
POST /v1/payment-tokenization/payment-credentials
```

Set `credential_type` based on what the device needs:

| Credential Type            | Description                                                                                          | When to Use                                                                           |
| -------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `TOKEN_CREDENTIAL_FULL`    | A complete set of credentials loaded from PP TSP's secure cache. No network call required.           | Initial provisioning or when a full credential set is needed.                         |
| `TOKEN_CREDENTIAL_DYNAMIC` | A fresh, single-use credential generated by the card network in response to a replenishment request. | When the device's credential cache is running low or after credentials are exhausted. |

<Tabs>
  <Tab title="Sample request">
    ```
    curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/payment-credentials' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>' \
    -d '{
       "enrollment_id":"<ENROLLMENT_ID>",
       "credential_type":"TOKEN_CREDENTIAL_FULL",
       "device_info":{
          "device_id":"947c4425-5c65-4417-9c35-f87af665a95c",
          "device_type":"WEARABLE"
       }
    }'
    ```
  </Tab>

  <Tab title="Sample response">
    ```
    {
       "token_info":{
          "id":"<TOKEN_ID>",
          "expiry_date":"2027-12",
          "tpan_info":"<BASE 64 encoded TPAN_INFO>",
          "tpan_last4":"5272",
          "account_id":"1183",
          "payment_account_reference":"50016DHAIAOOEA7BU7PVVJLHBFVZ0"
       },
       "payment_credentials":[
          {
             "tpan_id":"2fab-9f1e7d5c-1429-40d5-beec-16d26fa80a39",
             "payment_credential_id":"11EF-F3C0-7AFC4CE1-902A-72144E2C9AAC",
             "credential_type":"TOKEN_CREDENTIAL_FULL",
             "network_type":"MASTERCARD",
             "payment_credential_data":"Base 64 encoded credential data"
          }
       ]
    }
    ```
  </Tab>
</Tabs>

PP TSP returns encrypted credential data secured using device certifications.

#### 5c. Acknowledge receipt

After the device successfully receives and stores the full credentials, acknowledge receipt:

```
POST /v1/payment-tokenization/enrollments/{id}/payment-credentials/{cred_id}/acknowledge
```

PP TSP uses this acknowledgment to notify the card network of the successful provisioning outcome. Repeat **5b** and **5c** whenever the device needs a dynamic credential.

<Tabs>
  <Tab title="Sample request">
    ```
    curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/enrollments/<ENROLLMENT_ID>/payment-credentials/<PC_ID>/acknowledge' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>' \
    -d '{
        "provisioning_status": "SUCCESS",
        "credential_type": "TOKEN_CREDENTIAL_FULL"
    }'
    ```
  </Tab>

  <Tab title="Sample response">
    ```
    204 No Content
    ```
  </Tab>
</Tabs>

### 6. Handle token lifecycle events

PP TSP automatically keeps tokens synchronized with underlying card state. Use the following endpoints for partner-initiated operations:

| Scenario                            | Action                          | Endpoint                                                  |
| ----------------------------------- | ------------------------------- | --------------------------------------------------------- |
| User removes a card from the device | Close enrollment (irreversible) | `POST /v1/payment-tokenization/enrollments/{id}/close`    |
| Device is lost or stolen            | Suspend enrollment              | `POST /v1/payment-tokenization/enrollments/{id}/suspend`  |
| Device is recovered                 | Reactivate enrollment           | `POST /v1/payment-tokenization/enrollments/{id}/activate` |

For **issuer- or network-initiated changes** such as card reissue, fraud replacement, or loss/theft, PP TSP processes the update and notifies Wallet Server via a `PAYMENT-TOKENIZATION.TOKEN-STATUS.CHANGED` webhook. Call `GET enrollment` to retrieve the updated state and take appropriate action.

Closing an enrollment is **irreversible:** PP TSP sends a delete request to the card network and the token is permanently deactivated. Use suspend for temporary disabling.

### 7. Register and handle webhooks

PP TSP publishes signed webhook events to your registered HTTPS endpoint whenever a significant event occurs. Subscribe to all events below and return `HTTP 200` to acknowledge receipt. PP TSP retries delivery for unacknowledged events. Set up idempotent handlers to handle duplicate deliveries safely.

| Event                                             | Trigger                                                                                                                                                      | Required action                                                                                                                                                                      | Requirement   |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
| `PAYMENT-TOKENIZATION.ENROLLMENT.CREATED`         | A card enrollment has been successfully created and the token is provisioned by the card network.                                                            | Store the `enrollment_id` and `device_id` from the payload. Proceed to fetch payment credentials.                                                                                    | **Mandatory** |
| `PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.CREATED` | PP TSP has cached a new set of encrypted payment credentials and they are ready to be fetched by Wallet Server.                                              | Call the Fetch Payment Credentials endpoint using the `enrollment_id` in the event payload, then acknowledge receipt.                                                                | **Mandatory** |
| `PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.UPDATED` | An existing payment credential has been updated: for example, following a token reissue or credential refresh by the card network.                           | Discard the outdated credential on the device and fetch the updated credential set. Re-acknowledge after delivery.                                                                   | **Mandatory** |
| `PAYMENT-TOKENIZATION.TOKEN-STATUS.CHANGED`       | The token status has changed: either partner-initiated (activate, suspend, close) or issuer/network-initiated (card reissue, fraud replacement, loss/theft). | Call `GET /enrollments/{id}` to retrieve the current status. Update your local vault and surface the new state to the user, such as disabling tap-to-pay if `SUSPENDED` or `CLOSED`. | **Mandatory** |
| `PAYMENT-TOKENIZATION.TOKEN-METADATA.CHANGED`     | Token metadata has been updated: for example, card art, Terms & Conditions, or other display assets associated with the token have changed.                  | Re-fetch the relevant content using the `content_id` values in the event payload. Re-display updated T\&C to the user if required and capture fresh consent.                         | **Mandatory** |
| `PAYMENT-TOKENIZATION.TRANSACTION.CREATED`        | An NFC tap-to-pay transaction has been processed against a token managed by PP TSP.                                                                          | Log the transaction details for reconciliation, display transaction history to the user, and trigger any downstream notifications or replenishment flows as needed.                  | **Mandatory** |

> **Note:** PP TSP signs all webhook payloads. Always verify the signature before processing the event. Never process an event from an unverified source.

**Sample webhook payloads**

Each event is delivered to your registered endpoint in the following envelope:

```
{
  "status": "200 OK",
  "headers": { "...": "..." },
  "body": {
    "events": [
      {
        "event_type": "<EVENT_NAME>",
        "resource": { "...": "event-specific resource fields" },
        "links": [ { "...": "..." } ]
      }
    ]
  }
}
```

`PAYMENT-TOKENIZATION.ENROLLMENT.CREATED`

```
{ "event_type": "PAYMENT-TOKENIZATION.ENROLLMENT.CREATED", "resource": { "enrollment_id": "<enrollment_id>", "device_id": "<device_id>" }, "links": [] }
```

`PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.CREATED`

```
{ "event_type": "PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.CREATED", "resource": { "enrollment_id": "<enrollment_id>", "device_id": "<device_id>", "payment_credential_id": "<payment_credential_id>" }, "links": [] }
```

`PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.UPDATED`

```
{ "event_type": "PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.UPDATED", "resource": { "enrollment_id": "<enrollment_id>", "payment_credential_id": "<payment_credential_id>" }, "links": [] }
```

`PAYMENT-TOKENIZATION.TOKEN-STATUS.CHANGED`

```
{ "event_type": "PAYMENT-TOKENIZATION.TOKEN-STATUS.CHANGED", "resource": { "enrollment_id": "<enrollment_id>"}, "links": [] }
```

`PAYMENT-TOKENIZATION.TOKEN-METADATA.CHANGED`

```
{ "event_type": "PAYMENT-TOKENIZATION.TOKEN-METADATA.CHANGED", "resource": { "enrollment_id": "<enrollment_id>"}, "links": [] }
```

`PAYMENT-TOKENIZATION.TRANSACTION.CREATED`

```
{ "event_type": "PAYMENT-TOKENIZATION.TRANSACTION.CREATED", "resource": { "enrollment_id": "<enrollment_id>" }, "links": [] }
```

## Testing and go-live checklist

Complete the following in your sandbox environment before moving to production.

* **Credentials and setup:** Obtain sandbox OAuth credentials, test device configuration, and test card data from the PayPal integration team. Confirm OAuth token acquisition and refresh logic.
* **TRID onboarding:** Complete TRID onboarding and verify your PP TRID is included in all enrollment and credential requests.
* **Device registration:** Confirm device registration returns a valid `device_id` with ACTIVE status.
* **Green Path enrollment:** Complete an end-to-end Green Path enrollment with ACTIVE status confirmed.
* **Yellow Path enrollment:** Complete an end-to-end Yellow Path enrollment including all IDV steps.
* **Payment credentials:** Test both Full and Dynamic credential fetch and acknowledgment successfully.
* **Lifecycle management:** Test activate, suspend, and close operations via API.
* **Webhooks:** Verify all webhook event types are delivered and processed correctly in sandbox.
* **Security:** Confirm no raw PAN data appears in logs, responses, or stored records.
* **Go-live:** Contact your PayPal integration team to confirm production credentials, TRIDs, and webhook endpoints are configured separately from sandbox.


# Key concepts for NFC device tokenization
Source: https://docs.paypal.ai/limited-release/tokenization/nfc/key-concepts



Use this page to look up terms and abbreviations used throughout the NFC device tokenization documentation.

| Term                                   | Definition                                                                                                                                                                                                                                      |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Device Partner                         | An organization that integrates with PP TSP to enable tap-to-pay functionality on their NFC-enabled hardware.                                                                                                                                   |
| Funding Primary Account Number (FPAN)  | The actual card number.                                                                                                                                                                                                                         |
| Green Path                             | The provisioning path the card network selects when a token can be approved without additional identity verification. The token moves directly to `ACTIVE`.                                                                                     |
| Identity Verification (IDV)            | An additional step required in the Yellow Path when the network requests user authentication before activating a token.                                                                                                                         |
| Key Encryption Key (KEK)               | Used to encrypt payment credential data returned to the client.                                                                                                                                                                                 |
| Lifecycle Management (LCM)             | Operations to activate, suspend, or close a token enrollment.                                                                                                                                                                                   |
| Near Field Communication (NFC)         | The wireless protocol enabling contactless tap-to-pay transactions.                                                                                                                                                                             |
| Network Token / TPAN                   | A secure substitute for the real card number (FPAN), unique per device and card.                                                                                                                                                                |
| Payment Credential                     | A dynamically generated, single-use cryptographic value required to authorize an NFC transaction.                                                                                                                                               |
| PayPal Token Service Provider (PP TSP) | PayPal's service that generates, delivers, and manages the full lifecycle of payment tokens across supported networks on behalf of device partners.                                                                                             |
| Provisioning                           | The process of generating a token and delivering it to a device for storage, triggered when a user adds a payment method.                                                                                                                       |
| Secure Credential Services (SCS)       | PayPal's product umbrella for in-store tap-to-pay credential functionality, of which PP TSP is a core component.                                                                                                                                |
| Token Lifecycle                        | The set of states a token can move through: `ACTIVE`, `CLOSED`, `PENDING_TOKEN_ACTIVATION`, `PENDING_VERIFICATION_REQUIRED`, and `SUSPENDED`.                                                                                                   |
| Token Requestor ID (TRID)              | A unique 11-digit identifier enabling the partner to request network tokens.                                                                                                                                                                    |
| Token Unique Reference (TUR)           | The network-assigned identifier for a provisioned token.                                                                                                                                                                                        |
| Wallet Server                          | The device partner's backend systems that integrate with PP TSP.                                                                                                                                                                                |
| Yellow Path                            | The provisioning path the card network selects when identity verification (IDV) is required before a token activates. The token is held in `PENDING_VERIFICATION_REQUIRED` until the cardholder completes verification, then moves to `ACTIVE`. |


# Secure Credential Services
Source: https://docs.paypal.ai/limited-release/tokenization/secure-credential/scs



**Secure Credential Services** by PayPal is a unified platform of secure credential solutions designed to support diverse payment needs across channels and use cases. It provides a comprehensive suite of services that enable businesses to securely manage and utilize payment credentials, ensuring seamless and secure transactions for cardholders.

**Network tokenization** serves as the core of everything. It’s the foundational capability that replaces sensitive payment credentials with secure, network-issued tokens.

**The Secure Credential Services portfolio includes:**

* **Ecommerce tokens:** Network tokens for card-not-present online transactions. These tokens replace stored card numbers with network-issued tokens and one-time cryptograms, so sensitive card data is never transmitted or stored in the clear during online checkout.
* **In-store tap-and-pay credentials:** Contactless payment credentials for physical point-of-sale. These enable cardholders to pay by tapping a device at a terminal, using credentials provisioned and managed through the same tokenization infrastructure as online payments.
* **Device-bound credentials:** Credentials scoped to a specific device for enhanced security. The credential is tied to a particular device. It cannot be used from another device, reducing the risk of unauthorized use if account details are compromised.

Because all credential types share a common tokenization infrastructure, partners can adopt new capabilities incrementally without redesigning their existing payment stack. This helps businesses expand their payment offerings and adapt to evolving consumer preferences while maintaining a consistent and secure payment experience across channels, enhancing security, reducing fraud, and providing cardholders with convenient payment options.

## How Secure Credential Services works

Secure Credential Services (SCS) operates through PayPal's Token Service Provider (PP TSP). This is a centralized orchestration layer that serves between your platform and the card networks. Instead of building and maintaining separate integrations with Visa, Mastercard, American Express, and Discover, you connect to PP TSP once, which handles tokenization, credential management, and lifecycle operations on your behalf.
Products in the SCS portfolio are built on this shared infrastructure. Implementation details, end-to-end flows, and API references are available within each product's guide.


# Choose integration option
Source: https://docs.paypal.ai/payments/choose-integration-option



You can create and manage payment links in two ways: through the PayPal business dashboard or by using the Payment Links and Buttons API. This page helps you choose the option that fits your setup and level of control.

> **Note**: The Payment Links and Buttons API supports payment links only. Buy buttons and shopping cart buttons are created and managed in the dashboard.

<Columns>
  <Card title="UI Editor" href="/payments/create-pay-link">
    Create payment links and buttons in the PayPal dashboard and use them in emails, social posts, or on your site without writing code.
  </Card>

  <Card title="Payment Links and Buttons API" href="/payments/pay-links-buttons-api">
    Use a REST API to create and manage payment links from your application and use them wherever you accept payments.
  </Card>
</Columns>

The key difference between these options is how payment links are created, managed, and controlled, whether manually in the dashboard or programmatically in your application.

|                       | UI Editor                                                                                                                                                  | API                                                                                                                                                                                |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Who should use it** | Best for merchants who want to create and manage payment links or buttons without writing code.                                                            | Best for merchants and platforms that want to create and manage payment links programmatically from their applications and have experience with REST APIs and backend development. |
| **How it works**      | You create and customize links or buttons in the dashboard, then use the generated link or button code on your website or other channels.                  | Your application calls the Payment Links and Buttons API to create and manage payment links. You store and use the returned URLs within your own payment flows.                    |
| **Key benefits**      | <ul><li>No backend development required</li><li>Create and manage links and buttons manually</li><li>Suitable for low-to-medium volume use cases</li></ul> | <ul><li>Automate link creation and updates</li><li>Manage links from your application and deployment workflows</li><li>Suitable for high-volume or dynamic use cases</li></ul>     |


# Create buy button
Source: https://docs.paypal.ai/payments/create-buy-button



Add a buy button to your website so customers can pay for a specific product or service directly from your page, without writing custom code. Create the button, add the generated code to your site’s HTML where you want it to appear, and then test a full checkout to confirm the payment flow works end to end.

## Prerequisites

* [PayPal business account](https://www.paypal.com/business/open-business-account?_ga=2.49411041.673139926.1760916697-1259758161.1760473483)
* [PayPal sandbox account](https://www.sandbox.paypal.com/?_ga=2.235638529.1825699906.1774759059-1259758161.1760473483&_gac=1.119179899.1772050711.CjwKCAiA2PrMBhA4EiwAwpHyC1eMcD67U9yOBYbJw87PsAfFCbhlVRJOVNHzaHkwkSAo46L1wEG98xoCieUQAvD_BwE) to test the button before using it in production
* Website HTML access required if creating payment buttons

## Create buy button

Before creating your buy button, select a price type:

* **One set price**: You set a single price that every customer pays. Use this for products or services with a defined cost.
* **Customer-set price**: Customers enter the amount they want to pay. Use this for donations, tips, or pay-what-you-want offers.

1. Log in to your PayPal business account.
2. From the left navigation, select **Pay & Get Paid** > **Create Payment Links and Buttons**.
3. Select the button type, then choose the product or service you want to sell.
4. In the **Product** tab, fill out the product or service details.
5. Under **Price**, select the appropriate pricing option and enter the required details.
6. (Optional) Turn on **Images** to show product visuals on the payment page.
7. (Optional) Add quantity, variants, and inventory to help customers choose the correct options.
8. If you selected **Customer-set price**, turn on **Label for Invoice ID** so customers can enter an invoice number at checkout, and mark it as required if you need to match payments to specific invoices or orders.
9. Use stacked buttons to show multiple payment options together, and a single button when you only need one primary button. See [Customize checkout and buttons](/payments/customize-checkout) to change button layout, colors, and behaviors.
10. (Optional) In the **Checkout** tab, add shipping, taxes, discounts, and handling fees.
11. (Optional) In the **Confirmation** tab, turn on **Auto-return** and enter the URL where customers are redirected after successful payment.
12. Select **Build it**.

## Add button code to website

After your buttons are created, add them to your website so customers can see and use them during checkout. You can choose to display multiple payment options together or show just a single button, depending on your preference.

## Stacked button

Customers see multiple PayPal payment options, such as PayPal, Pay Later, and cards in one stacked experience. Choose your preferred code language, HTML or React, from the **Code language** dropdown to view the relevant example.

### Use HTML

1. Open your website editor.
2. Copy the **Part 1** HTML code.
3. Paste it once in your site’s `<head>` on every page where you plan to use buttons.
4. If you can’t edit the `<head>`, paste the **Part 1** code at the top of the `<body>`.
5. Copy the **Part 2** HTML code.
6. Paste it where you want your stacked buttons to appear in the page `<body>`, ideally near your product or checkout section.​​
7. Save your changes and publish your site.

### Use React

1. Open your React project in your code editor.
2. Copy the **Part 1** React code.
3. Paste it once in your site’s `<head>` on every page where you plan to use buttons.
4. Copy the **Part 2** React code.
5. Paste it where you want your stacked buttons to appear in the page `<body>`.
6. Copy the **Part 3** React code.
7. Paste it where you want your stacked buttons to appear in the page `<body>`, ideally near your product or checkout section.​​

## Single button

Customers see a single PayPal button experience, with just one code snippet to add to your site.

1. Open your website editor.
2. Copy the single button code snippet.
3. Paste the code where you want the button to appear in your page’s `<body>`, near your product or call to action.
4. Save your changes and publish your site.

## Test buttons

Test the workflow to ensure the buttons function correctly.

1. Refresh your website to confirm all buttons appear correctly.
2. Make a test purchase on your site.
3. Verify the transaction in your PayPal account.
4. Refund the test transaction when finished.

## Common issues

**Button code is out of date after updating product details**

* In most cases, you don't need to update the button code. The button uses configuration stored on PayPal servers, so your changes take effect after you save them in your PayPal account. However, if you change the product's currency code, ensure you replace the existing button code with the updated code.

For more information, see [FAQ](/payments/faq) and [Troubleshooting](/payments/troubleshooting).


# Create payment link
Source: https://docs.paypal.ai/payments/create-pay-link



Use payment links to collect payments by sharing a URL with customers through email, text, social media, or on your website. Create the link in your PayPal business dashboard, set product details, pricing, and checkout behavior, then send it so customers can complete payment on a checkout page.

## Prerequisites

* [PayPal business account](https://www.paypal.com/business/open-business-account?_ga=2.49411041.673139926.1760916697-1259758161.1760473483)
* (Optional) [PayPal sandbox account](https://www.sandbox.paypal.com/?_ga=2.235638529.1825699906.1774759059-1259758161.1760473483&_gac=1.119179899.1772050711.CjwKCAiA2PrMBhA4EiwAwpHyC1eMcD67U9yOBYbJw87PsAfFCbhlVRJOVNHzaHkwkSAo46L1wEG98xoCieUQAvD_BwE) to test the payment link before using it in production

## Create payment link

Create a secure, shareable payment link to accept payments for your products or services. Set a fixed or customer-defined price, configure checkout options, and send the link to customers to complete payments without needing a website.

* **One set price**: You set a single price that every customer pays. Use this for products or services with a defined cost.
* **Customer-set price**: Customers enter the amount they want to pay. Use this for donations, tips, or pay-what-you-want offers.

1. Log in to your PayPal business account.
2. From the left navigation, select **Pay & Get Paid** > **Create Payment Links and Buttons**.
3. Create a payment link for the product or service you want to sell.
4. In the **Product** tab, fill out the product or service details.
5. Under **Price**, select the appropriate pricing option and enter the required details.
6. (Optional) Turn on **Images** to show product visuals on the payment page.
7. Add quantity, variants, and inventory to help customers choose the correct options.
8. If you selected **Customer-set price**, turn on **Label for Invoice ID** so customers can enter an invoice number at checkout, and mark it as required if you need to match payments to specific invoices or orders.
9. (Optional) In the **Checkout** tab, add shipping, taxes, discounts, and handling fees.
10. (Optional) In the **Confirmation** tab, turn on **Auto-return** and enter the URL where customers are redirected after successful payment.
11. Select **Build it**, then copy the link and share it with customers by email, SMS, or social media.

## Test your payment link

Verify that customers can open the link, see the correct pricing, and complete payment.

1. Open the payment link in a new browser window.
2. Confirm the product name, price, and currency display correctly.
3. Complete a test payment:
   * Use a low-value transaction if testing in live mode.
   * Use a sandbox buyer account if testing in the sandbox.
4. Confirm that the:
   * Payment completes successfully.
   * Confirmation page automatically redirects buyers to the expected return URL if auto-return is set.
   * Transaction appears in your dashboard activity.

## Common issues

**Auto-return does not redirect correctly**

* Verify that the return URL is valid and publicly accessible.

**Checkout experience is not customized**

* You haven't customized your checkout experience yet. Update your business name, logo, and brand colors to match your brand. Customization options vary depending on the checkout type you use. For more information, see [Customize checkout and buttons](/payments/customize-checkout).

<Columns>
  <Card title="Share a payment link" href="/payments/share-pay-links">
    Share a payment link by email, text, social, or on your website, and use QR codes or buttons so customers can pay from wherever they are.
  </Card>

  <Card title="Settings" href="/payments/customize-checkout">
    After your payment link or button is built, customize which payment methods are shown and update branding to match your business.
  </Card>

  <Card title="Manage inventory, variants, and optional features" href="/payments/manage-inventory-variants-taxes">
    Set variants, track stock levels, and manage taxes, discounts, and fees so your payment links and buttons stay in sync with your current inventory.
  </Card>
</Columns>

For more information, see [FAQ](/payments/faq) and [Troubleshooting](/payments/troubleshooting).


# Create shopping cart button
Source: https://docs.paypal.ai/payments/create-shopping-cart-buttons



You can add Add to Cart and View Cart buttons to your website without building a custom integration. Use the PayPal Business Dashboard to define product details, pricing, and checkout behavior, then copy the generated code snippets into your site. You can also customize the layout and styling of your buttons to match the look and feel of your website and brand.

## How buttons work

* Add to Cart button helps customers select and store products in their shopping cart so they can continue browsing or shopping before completing the purchase.
* View Cart button helps customers review the items they add, modify quantities, and proceed to checkout.

## Prerequisites

* [PayPal business account](https://www.paypal.com/business/open-business-account?_ga=2.49411041.673139926.1760916697-1259758161.1760473483)
* Website HTML access

## Create shopping cart buttons

1. Log in to your [PayPal Business Account](https://www.paypal.com/business/open-business-account?_ga=2.49411041.673139926.1760916697-1259758161.1760473483).
2. In the left navigation, select **Pay & Get Paid** > **Create Shopping Cart Buttons**.
3. Enter the details in the **Product**, **Checkout**, and **Confirmation** tabs.
4. Select **Build it**.
5. Copy the generated code snippets to place the buttons on your website. A downloadable PDF with detailed instructions is available on this page.
6. Select **More Actions** > **Settings** > **Cart buttons** to customize button appearance and preview the customization.

> **Note**: If you select **Settings** while you are still building a button, the editor is replaced by the **Settings** page, and any unsaved changes are lost.

For more information on customization, see [Customize checkout](/payments/customize-checkout).

## Add shopping cart buttons

Add both the View Cart and Add to Cart buttons after you create your shopping cart buttons so the cart works correctly.

### Add the View Cart button

1. Open your website editor.
2. Copy the **Part 1 View Cart** code from the UI:
   * Paste it once into your site’s `<head>` on each page.
   * If you can’t edit the `<head>`, paste it at the top of the `<body>`.
3. Copy the **Part 2 View Cart** code:
   * Paste it into a visible location in the `<body>` that appears on every page, such as the site navigation.
   * You can paste Part 2 in more than one location if needed.
4. Save your changes.

### Add the Add to Cart button

1. Open your website editor.
2. In the page’s `<body>`, paste the Add to Cart button code where you want it to appear, ideally near the product.
3. Save your changes.
4. Repeat these steps for each product on the page.

## Test buttons

Test the workflow to ensure the buttons function correctly.

1. Refresh your website to confirm all buttons appear correctly.
2. Make a test purchase on your site.
3. Verify the transaction in your PayPal account.
4. Refund the test transaction when finished.

## Common issues

**Site builder doesn't expose the HTML `<head>`**

* If your site builder doesn't allow access to the `<head>`, paste the Part 1 code at the top of your page's `<body>`, above the Part 2 code.


# Customize your checkout and buttons
Source: https://docs.paypal.ai/payments/customize-checkout



Use the Payment Links and Buttons settings to choose payment methods, button styles, business branding, and return URLs for checkout.

## Before you begin

1. Log in to your [PayPal Business Account](https://www.paypal.com/business/open-business-account?_ga=2.49411041.673139926.1760916697-1259758161.1760473483).
2. From the left navigation, select **Pay & Get Paid** > **Create Payment Links and Buttons** or **Create Shopping Cart Buttons**.
3. Select **Settings**.

## Choose payment methods

Select which payment methods to appear at checkout.

* Available options include: PayPal, Pay Later, Venmo, and Apple Pay. Credit and debit cards are enabled by default.

## Set business identity and branding

* Configure how your business appears during checkout.
* Display **business name**.
* Display **business logo**.
* Set a **homepage URL**. Customers are sent here when selecting your logo or home icon.

Business name, logo, and profile details can be updated in [account settings](https://www.paypal.com/businessprofile/settings/info/edit).

## Button layout and styles

Control how your PayPal buttons look and behave across your site. Use stacked buttons to show multiple payment options together, single buttons for a primary checkout action, and cart buttons to keep your existing shopping cart buttons consistent.

<Tabs>
  <Tab title="Stacked buttons">
    Stacked button settings apply to all existing stacked buttons on your site. Use stacked buttons to offer multiple payment options within the same checkout entry point.

    * **Layout:** Vertical or horizontal
    * **Color:** Standard PayPal color schemes only (custom colors not supported)
    * **Shape:** Pill or rectangle
    * **Size:** Small, medium, or large

    Second button behavior:

    * Control what appears on the second button in the stack. The options you see depend on which payment methods are available in the buyer’s region. For example, you can show a Venmo button when available, or select **None** to hide the second button entirely.

    Checkout button label:

    * Choose the text that appears on your checkout button. The button redirects buyers to a PayPal checkout page, where available payment methods are displayed.
    * Choose the button label: **Checkout**, **Proceed**, **Pay**, or **Custom**.
  </Tab>

  <Tab title="Single button">
    Changes to single buttons apply only to new buttons that you create. Use a single button when you want a single primary option for customers to select.

    * **Shape:** Pill or rectangle
    * **Size:** Small, medium, or large
    * **Color:** Standard PayPal colors or customize the button color
  </Tab>

  <Tab title="Cart button">
    Changes to cart buttons apply to all existing shopping cart buttons you have already added to your website. Configure how cart buttons look:

    * **Shape:** Pill or rectangle
    * **Size:** Small, medium, or large
    * **Color:** Standard PayPal colors or customize the button color
  </Tab>
</Tabs>

Each shopping cart button automatically generates a payment link and a QR code that you can reuse across other channels.

## Auto-return URL

Use auto-return to send customers back to your site after checkout. The URL applies to all shopping cart transactions. Configure the auto-return URL in the **Cart Buttons** tab under **Settings**.

> **Note**: For Payment Links and Buy Buttons, the auto-return URL is set in the **Confirmation** tab. This URL applies only to the transactions for that specific link or button.


# Frequently asked questions
Source: https://docs.paypal.ai/payments/faq



Find answers to common questions about Payment Links and Buttons, including configuration, customization, testing, and supported features.

## What’s the difference between payment links and buttons?

Payment links collect payments by sharing a URL with customers. Best for accepting in-person or contactless payments without building a website.

Payment buttons collect payments directly from your website by adding button code to your page’s HTML. Best for selling a specific product or service with a direct payment option on your website.

## Do payment links and buttons support a manually added locale?

Yes. By default, payment links and buttons use the customer’s browser settings to determine the language and locale. You can override the locale for payment links and button code by appending `locale.x` and `country.x` as query parameters. Any custom text you enter during configuration does not get translated.

See the [JavaScript SDK script configuration](https://developer.paypal.com/sdk/js/configuration/#link-locale) for supported locale codes.

Example payment link:\
`https://www.paypal.com/ncp/payment/F3YMU2ZGT49XX?locale.x=ja_JP&country.x=JP`

Example script tag:

```html theme={null}
<script src="...&currency=USD&locale.x=ja_JP&country.x=JP"></script>
```

## Can I use webhooks with payment links and buttons?

Yes. To enable webhooks:

1. Sign in to the Developer Dashboard with your merchant account.
2. Switch to **Live**.
3. Select **Apps and Credentials**.
4. Scroll down and select **Manage webhooks**.
5. Add your webhook callback URL and choose the events you want to receive, such as checkout and payment events.

You can repeat these steps in the sandbox by switching the environment from Live to Sandbox in the top-right corner.

## Can I hide labels for the Add to Cart button?

Yes. You can hide all text and labels around the button to fit your site’s visual design. This does not change how PayPal processes the transaction, which still uses the hosted button ID configuration. If you hide labels, make sure your button type does not require customer input, such as changing quantity.

Example CSS to hide surrounding fields (replace `<hostedButtonID>` with your actual ID):

```xml theme={null}
<style>
  #paypal-form-fields-container-<hostedButtonID> .item-header {
    display: none !important;
  }
  #paypal-form-fields-container-<hostedButtonID> .carousel-container {
    display: none !important;
  }
</style>
```

Use this approach only when the button does not require customer selections or input.

## Where can I test my payment links and buttons?

You can test payment links and buttons in the sandbox at:
`https://www.sandbox.paypal.com/us/home`.

## How do I test Venmo in the sandbox?

Pay with Venmo is not currently available in the sandbox. To test Venmo, you must test in the live environment.

## Do payment links and buttons support IPN (Instant Payment Notification)?

Yes. Payment links and buttons support IPN.

To open IPN settings:

1. Go to your [account settings](http://www.paypal.com/businessmanage/account/accountAccess).
2. Select **Notifications** to see a list of alerts.
3. Select **Update for Instant payment notifications** to open your [IPN settings](https://www.paypal.com/merchantnotification/ipn/preference).
4. Enter your Notification URL and select **Receive IPN messages (Enabled)**.
5. Select **Save**.

## When a customer returns to my site, what purchase information does PayPal send?

Payment links and buttons support Payment Data Transfer (PDT) variables. You receive PDT data when you turn on **Auto Return** in your payment links and buttons configuration. PDT lets PayPal send transaction details to your return URL after checkout.

## Can I override payment links and buttons to use my account shipping settings?

No. Payment links and buttons do not honor the bulk shipping settings override in your account shipping preferences. The shipping option in your account profile does not apply to payment links or buttons.

## I updated the product details. Do I need to update the button code?

Usually no. The button uses configuration stored on PayPal servers. After you save your changes in your PayPal account, you do not need to update the button code on your site.

**Exception:** If you change the product’s currency code, you must replace the existing button code with the updated code.

## Why is there a client ID in the code?

The client ID identifies your PayPal account in the integration. Do not edit or remove it. Use it exactly as provided in the button code.

## Can I hide labels generated by the payment links and button code?

Yes. You can hide specific text and labels around the button. This does not change how PayPal processes the transaction, which still uses your configured hosted button ID. Only hide labels when your button type does not require customer input. If you hide fields that collect required data, such as quantity or item selection, the transaction can fail.

Example: Hide the price label for a specific hosted button (replace `<HostedButton_ID>` with your actual ID):

```xml theme={null}
<style>
  #paypal-form-fields-container-<HostedButton_ID> #price-label {
    display: none !important;
  }
</style>
```

Hide multiple labels, such as product name and price:

```xml theme={null}
<style>
  #paypal-form-fields-container-<HostedButton_ID> #price-label,
  #paypal-form-fields-container-<HostedButton_ID> #desc-label {
    display: none !important;
  }
</style>
```

Hide all text fields around the button for a specific hosted button:

```xml theme={null}
<style>
  #paypal-form-fields-container-<HostedButton_ID> {
    display: none !important;
  }
</style>
```

Use the full-hide approach only when your button does not require any customer selections or input.

## Do payment links support subscriptions?

No. Payment links support one-time payments only.

## Are payment links PCI compliant?

Yes. Payment links securely process payments in compliance with Payment Card Industry (PCI) standards.

## Can I customize the checkout branding?

Yes. You can customize certain elements of your checkout experience, such as your business name, logo, and brand colors. The level of customization can vary by checkout type. See [Customize checkout and buttons](/payments/customize-checkout) for more information.

## Can I use payment links internationally?

Yes. You can use payment links to accept payments from customers in many countries and regions. Availability can vary by market.

## Do payment links expire?

No. Currently, we do not support single-use payment links or link expiration.

## Can I generate payment links through an API?

Yes. You can generate payment links programmatically by using PayPal APIs. This lets you create and manage links at scale and integrate payment link creation into your own systems or workflows. See Use [API to create a payment link](/payments/pay-links-buttons-api) for more information.


# Manage inventory, variants, and taxes
Source: https://docs.paypal.ai/payments/manage-inventory-variants-taxes



Use the Payment Links and Buttons dashboard to build flexible purchase experiences while configuring pricing, variants, taxes, inventory behavior, and alerts to fit your platform's needs.

## Prerequisites

1. Log in to your [PayPal Business Account](https://www.paypal.com/business/open-business-account?_ga=2.49411041.673139926.1760916697-1259758161.1760473483).
2. From the navigation menu, select **Pay & Get Paid** > **Create Payment Links and Buttons** or **Create Shopping Cart Buttons**.

## Manage inventory

Keep product quantities accurate with inventory tracking and alerts.

1. Log in to your PayPal business account.
2. From the left navigation, select **Sales** > **Payment Links and Buttons**.
3. Set the maximum number of units a customer can purchase in a single transaction in the **Quantity** field. This setting only applies when you use the **One set price** pricing option, and is useful when you want to limit bulk purchases.
4. Enter **Item ID**, **Quantity in stock**, and **Alert quantity** to receive email notifications when inventory is low or out of stock.
5. Choose whether customers can purchase out-of-stock items.

## Variants

Variants let you offer up to three variations per item, such as color, size, or type.

1. In the dashboard, select **Show more options** and turn on **Variants**.
2. Enter a variant name, and list up to 10 options for that variant.
3. Add images and prices for your item’s primary variant.
4. To price each option individually, select **Add price per variant**.

## Taxes, discounts, and fees

Use the **Checkout** tab to configure taxes, discounts, and fees for each item so customers see accurate pricing during checkout.

| Type         | Description                                                                                                                                         | How to set it                                                                                                                                                                                 |
| :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Taxes        | Set tax rates for each item, including custom rates. If your country requires tax-inclusive pricing, make sure the item price already includes tax. | In the **Checkout** tab, turn on **Taxes**. Then select **Use tax from my settings** or **Use a specific tax rate**, and choose **Percentage**, **Flat amount**, or **Taxes not applicable**. |
| Discounts    | Apply automatic discounts to each item and variant.                                                                                                 | In the **Checkout** tab, turn on **Discounts**. Then choose **Amount Off** (fixed amount), **Percentage** (percentage off the price), or **No discount** from the drop-down menu.             |
| Handling fee | Add a single handling fee for this item, regardless of how many units a customer buys.                                                              | In the **Checkout** tab, turn on the **Handling fee** and enter the fee amount.                                                                                                               |
| Shipping fee | Set the shipping fee for this item, including free shipping.                                                                                        | In the **Checkout tab**, turn on the **Shipping fee**, choose a setting from the **Shipping fee** dropdown,  and enter the fee amount.                                                        |


# Integrate 3D Secure with PayPal's JavaScript SDK v6
Source: https://docs.paypal.ai/payments/methods/cards/3ds



With PayPal's JavaScript SDK v6, you can support Strong Customer Authentication (SCA) and 3D Secure (3DS) in two payment flows:

* **One-time payments** process a single transaction with 3DS when required. The SDK collects card details, creates an order, and captures payment upon approval.
* **Save payment methods (vaulting)** store cards for future purchases. The server creates setup tokens, and the client submits card details to complete vaulting with optional 3DS.

## One-time payment

On your server, create an order and define SCA and 3DS settings. Use `payment_source.card.attributes.verification.method` and supply return and cancel URLs in `experience_context`.

```javascript theme={null}
// POST /paypal-api/checkout/orders
// Body (example — adapt amounts, currency, and URLs)
{
  "intent": "CAPTURE",
  "purchase_units": [
    { "amount": { "currency_code": "USD", "value": "100.00" } }
  ],
  "payment_source": {
    "card": {
      "attributes": {
        "verification": { "method": "SCA_ALWAYS" } // or SCA_WHEN_REQUIRED
      },
      "experience_context": {
        "return_url": "https://example.com/returnUrl",
        "cancel_url": "https://example.com/cancelUrl"
      }
    }
  }
}
```

### Verification methods

* Use `SCA_ALWAYS` to attempt 3DS for eligible cards and regions.
* Use `SCA_WHEN_REQUIRED` to rely on network or regulatory mandates.

### Submit card details

On the client side, initialize the SDK and card fields. Submit the order and handle each possible outcome.

```javascript theme={null}
const sdk = await window.paypal.createInstance({ clientId: "YOUR_CLIENT_ID", components: ["card-fields"] });
const session = sdk.createCardFieldsOneTimePaymentSession();

// Render fields
const numberField = session.createCardFieldsComponent({ type: "number", placeholder: "Card number" });
const cvvField = session.createCardFieldsComponent({ type: "cvv", placeholder: "CVV" });
const expiryField = session.createCardFieldsComponent({ type: "expiry", placeholder: "MM/YY" });

["#paypal-card-fields-number", "#paypal-card-fields-cvv", "#paypal-card-fields-expiry"]
  .map((sel, i) => document.querySelector(sel).appendChild([numberField, cvvField, expiryField][i]));

// Pay click
document.querySelector("#pay-button").addEventListener("click", async () => {
  try {
    const orderId = await createOrder({ enable3DS: true, scaMethod: getScaMethodFromUI() });
    const { state, data } = await session.submit(orderId, {
      billingAddress: { postalCode: "95131" }
    });

    switch (state) {
      case "succeeded": {
        const { orderId, liabilityShift } = data
          // 3DS may or may not have occurred; Use liabilityShift 
          // to determine if the payment should be captured
        const result = await captureOrder(data.orderId);
          // success UI
        break;
      }
      case "canceled": {
        // buyer closed 3DS modal
        break;
      }
      case "failed": {
        // inspect data.message
        break;
      }
    }
  } catch (e) { console.error(e); }
});
```

### Example order endpoint

Use this Express handler to create a PayPal order and optionally include 3DS parameters based on your request body.

```javascript theme={null}
app.post("/paypal-api/checkout/orders", async (req, res) => {
  const { enable3DS, scaMethod = "SCA_WHEN_REQUIRED" } = req.body || {};
  const body = {
    intent: "CAPTURE",
    purchase_units: [{ amount: { currency_code: "USD", value: "100.00" } }],
  };
  if (enable3DS) {
    body.payment_source = {
      card: {
        attributes: { verification: { method: scaMethod } },
        experience_context: {
          return_url: "https://example.com/returnUrl",
          cancel_url: "https://example.com/cancelUrl",
        },
      },
    };
  }
  // call PayPal Orders API with body and return { id }
});
```

## Save payment method

On the server, create a vault setup token to save a payment method and require 3DS. Specify a verification method in the request.

```javascript theme={null}
// POST /paypal-api/vault/setup-token
// Body (example)
{
  "payment_source": {
    "card": {
      "experience_context": {
        "return_url": "https://example.com/returnUrl",
        "cancel_url": "https://example.com/cancelUrl"
      },
      "verification_method": "SCA_ALWAYS" // or SCA_WHEN_REQUIRED
    }
  }
}
```

### Submit card with setup token

On the client side, initialize the SDK and card fields. Submit the order and handle each possible outcome.

```javascript theme={null}
const sdk = await window.paypal.createInstance({ clientId: "YOUR_CLIENT_ID", components: ["card-fields"] });
const session = sdk.createCardFieldsSavePaymentSession();

// Render 3 fields as shown above...

const { setupToken } = await createVaultSetupToken({ enable3DS: true, scaMethod: getScaMethodFromUI() });
const { state, data } = await session.submit(setupToken);

switch (state) {
  case "succeeded": {
    // Persist data.vaultSetupToken on your server (maps to a vaulted instrument)
    break;
  }
  case "canceled": {
    // user dismissed 3DS
    break;
  }
  case "failed": {
    // show retry message
    break;
  }
}
```

## Best practices

* Include both the `return_url` and `cancel_url` in all 3DS requests.
* Handle every submit state and add `break;` in each switch case.
* Track the liability shift in `data` to manage risk.


# PayPal Expanded Checkout Best Practices
Source: https://docs.paypal.ai/payments/methods/cards/best-practices



This page explains the best practices and core concepts that drive authorization, risk, and liability for card payments in Expanded Checkout.

It is written for payments and backend engineers who are familiar with card-not-present processing, issuers and acquirers, and REST APIs. It focuses on elements that shape system behavior, such as data quality, 3D Secure, stored credentials, retry patterns, and related signals. It does not include step-by-step integration flows or SDK usage.

## Why data quality drives Expanded Checkout authorization

Passing complete and accurate cardholder data is the most impactful step a partner or merchant can take to improve authorization rates. Card issuers use this data to make real-time approval decisions. Incomplete data increases false declines.

### Important data fields

The Expanded Checkout authorization model assumes the issuer receives a complete cardholder profile. The fields below are the minimum set required for the issuer to evaluate risk correctly.

| Data field                    | API location                                              |
| :---------------------------- | :-------------------------------------------------------- |
| Cardholder name               | `payment_source.card.name`                                |
| Billing address – street      | `payment_source.card.billing_address.address_line_1`      |
| Billing address – city        | `payment_source.card.billing_address.admin_area_2`        |
| Billing address – postal code | `payment_source.card.billing_address.postal_code`         |
| Expiration date               | `payment_source.card.expiry`                              |
| CVV/Security code             | `payment_source.card.security_code`                       |
| Customer first name           | `payment_source.card.attributes.customer.name.given_name` |
| Customer last name            | `payment_source.card.attributes.customer.name.surname`    |

### Recommended data fields

The following fields are not required but improve risk scoring and authorization outcomes:

| Data field       | API location                                                    | Notes                        |
| :--------------- | :-------------------------------------------------------------- | :--------------------------- |
| Email address    | `payment_source.card.attributes.customer.email_address`         |                              |
| Phone number     | `payment_source.card.attributes.customer.phone.phone_number`    | Mobile preferred             |
| IP address       | `purchase_units[n].supplementary_data.risk.customer.ip_address` | Critical for fraud detection |
| Shipping address | `purchase_units[n].shipping.address`                            | Reduces risk signals         |

### Address Verification Service (AVS)

AVS compares the billing address provided by the customer with the address on file at the card issuer. A complete billing address is a prerequisite for AVS to act as a reliable fraud signal. Issuers use AVS as one of the primary indicators to distinguish legitimate mismatches from fraud. In Expanded Checkout, feed AVS codes into your decisioning model as nuanced signals rather than a pass or fail switch.

> **Best Practice:** For non-matching AVS responses, prompt the customer to re-verify their billing address before declining the transaction.

| AVS code | Meaning                      | Recommended action                |
| :------- | :--------------------------- | :-------------------------------- |
| `Y`      | Street and ZIP match         | Proceed                           |
| `A`      | Street matches, ZIP does not | Proceed with caution              |
| `Z`      | ZIP matches, street does not | Proceed with caution              |
| `N`      | Neither matches              | Prompt customer to verify address |
| `U`      | Unavailable                  | Proceed (not merchant fault)      |

> **Note:**
>
> * Issuers outside the US, Canada, and the UK do not consistently support AVS.
> * If you use AVS filters in your fraud-prevention systems, collect the billing street and postal code so AVS can be evaluated when available.

## 3D Secure (3DS) in Expanded Checkout authorization

3D Secure (3DS) is an authentication protocol that adds a verification layer for card-not-present transactions. Correct implementation is critical for liability shift protection, regulatory compliance (EU PSD2/SCA), and fraud reduction.

For more information, see:

* [3D Secure Integration](https://developer.paypal.com/docs/checkout/advanced/customize/3d-secure/)
* [3DS Response Parameters](https://developer.paypal.com/docs/checkout/advanced/customize/3d-secure/response-parameters/)

### When Expanded Checkout relies on 3DS

Think of 3DS as a policy switch. You trade a small amount of friction for a significant liability and fraud-reduction benefit in certain scenarios.

* **Mandatory:** EU/EEA transactions (PSD2 Strong Customer Authentication requirement)
* **Recommended:** High-risk verticals (travel, digital goods, subscriptions)
* **Recommended:** High-value transactions (typically >\$100)
* **Recommended:** Cross-border transactions

### How 3DS changes liability in Expanded Checkout

Always check `liability_shift` first when handling a 3DS response.

In Expanded Checkout, `liability_shift` is the primary conceptual signal: it tells you whether the issuer or the merchant is expected to absorb fraud losses for this transaction class. Your risk policies should key off this value, not just the presence of 3DS.

See [3D Secure Response Parameters](https://developer.paypal.com/docs/checkout/advanced/customize/3d-secure/response-parameters/) for more information.

### Maximizing frictionless authentication

Frictionless authentication (no customer challenge) provides the best conversion outcome. Increasing the frictionless rate may lead to higher authorization and completion rates because fewer customers drop out during additional challenges.

To maximize frictionless flow, send the following data in your 3DS request:

* Billing and shipping address
* Customer email and phone
* IP address
* Account age and purchase history indicators

## Stored credentials and card-on-file

Stored credentials (card-on-file) extend a one-time card payment into an ongoing, reusable payment relationship. The way you represent customer-initiated transactions (CIT) and merchant-initiated transactions (MIT) in Expanded Checkout affects authorization rates and customer experience.

Merchant-initiated authorization can improve significantly when CIT and MIT flags are set correctly and you pass the appropriate network transaction references.

See [SCA payment indicators](https://developer.paypal.com/docs/checkout/advanced/customize/sca-payment-indicators/) for more information on Strong Customer Authentication.

### Customer-Initiated Transactions (CIT)

A CIT occurs when the customer is actively participating in the checkout, such as one-click checkout with a saved card. In most Expanded Checkout integrations, the customer completes 3D Secure authentication on the first transaction before storing credentials for future use. Initial authentication improves MIT authorization and shifts liability away from the merchant.

* Authenticate the first CIT with 3DS when storing credentials for future use.
* Set `stored_credential.payment_initiator = CUSTOMER`.
* Set `stored_credential.payment_type = ONE_TIME` or `RECURRING`.
* Store the `network_transaction_reference` value you will need to reference the original successful CIT for future MITs.

### Merchant-Initiated Transactions (MIT)

A MIT is an automated charge without active customer participation, such as a subscription renewal or auto-top-up. Successful MIT behavior depends on carrying forward a trusted reference to the original CIT.

* Include `previous_transaction_reference` from the original CIT. Missing references reduce MIT authorization rates.
* Set `stored_credential.payment_initiator = MERCHANT`.
* Set `stored_credential.usage = SUBSEQUENT`.
* Set `stored_credential.payment_type = RECURRING` or `UNSCHEDULED`.

### Network transaction reference priority

In Expanded Checkout, network transaction references carry the history of a cardholder's prior approvals. Use the strongest available reference to improve MIT authorization rates.

1. **First Priority:** `previous_transaction_reference` (from PayPal CIT)
   * PayPal manages CIT reference retrieval automatically
   * Highest authorization rates

2. **Second Priority:** `previous_network_transaction_reference` (from a non-PayPal PSP)
   * Use when the initial CIT was processed outside of PayPal
   * Include all relevant network data fields

## Response code handling

Expanded Checkout exposes issuer and system response codes as signals, not just errors. Proper response code handling determines when to retry, when to switch payment methods, and when to stop the flow. It also shapes how you communicate with customers and protects your overall authorization rates.

### Soft declines (retryable)

Soft declines represent temporary or recoverable conditions where a retry may succeed if you adjust timing, amount, or funding source.

| Response code                | Reason                | Retry? | Timing              | Customer message                                                                |
| :--------------------------- | :-------------------- | :----- | :------------------ | :------------------------------------------------------------------------------ |
| `CARD_DECLINED`              | Generic decline       | Once   | Immediate, then 24h | "Your card was declined. Please try again or use a different payment method."   |
| `INSUFFICIENT_FUNDS`         | Not enough funds      | Yes    | 24–72 hours         | "Insufficient funds. Please try a different card or try again later."           |
| `ISSUER_UNAVAILABLE`         | Bank system down      | Yes    | Exponential backoff | "Your bank is temporarily unavailable. Please try again."                       |
| `TRANSACTION_LIMIT_EXCEEDED` | Velocity/amount limit | Yes    | 1–4 hours           | "Transaction limit exceeded. Please try a smaller amount or contact your bank." |

### Hard declines (do not retry)

Hard declines indicate a terminal decision from the issuer or scheme. Additional retries with the same card are unlikely to succeed and can add risk or noise.

| Response code                    | Reason                        | Action                                                                  |
| :------------------------------- | :---------------------------- | :---------------------------------------------------------------------- |
| `SUSPECTED_FRAUD`                | Fraud detection triggered     | Request alternate payment method immediately. Never retry.              |
| `LOST_STOLEN_CARD`               | Card reported lost or stolen  | Block card, request new payment method. Never retry.                    |
| `CARD_EXPIRED`                   | Card past expiration          | Prompt customer to update card details. Use Account Updater to prevent. |
| `DO_NOT_HONOR`                   | Issuer generic block          | Request a different payment method. Never retry with same card.         |
| `INVALID_ACCOUNT`                | Card number invalid or closed | Request new payment method.                                             |
| `SECURITY_VIOLATION`             | Security policy violation     | Request new payment method.                                             |
| `PICKUP_CARD_SPECIAL_CONDITIONS` | Issuer fraud block            | Request new payment method.                                             |
| `ACCOUNT_CLOSED`                 | Payer account closed          | Request new payment method.                                             |

### System and technical errors (retry with same idempotency key)

| Response code           | Retry strategy                                                |
| :---------------------- | :------------------------------------------------------------ |
| `INTERNAL_SERVER_ERROR` | Exponential backoff. Reuse same idempotency key.              |
| `GATEWAY_TIMEOUT`       | Immediate retry 2–3 times. Reuse same idempotency key.        |
| `RATE_LIMITED`          | Exponential backoff (10s, 30s, 1m, 5m). Implement throttling. |

### Customer messaging guidelines

**Do:**

* Be specific but non-technical in customer-facing messages.
* Provide clear next steps, such as "Try a different card" or "Contact your bank".
* Offer alternative payment methods.

**Do not:**

* Expose technical error codes or internal decline reasons.
* Reveal fraud detection logic or specific AVS/CVV failure details.
* Use vague messages such as "An error occurred."

> **Security note:** Revealing fraud logic helps fraudsters circumvent detection systems. Always use generic messaging for fraud-related declines.

## How Expanded Checkout handles declines and retries

Payments that are initially declined may be soft declines that can succeed on retry. A well-implemented retry strategy can recover significant revenue, particularly for subscription businesses.

### Idempotency and safe retries

Idempotency keys are the core mechanism that lets Expanded Checkout support safe retries without creating duplicate charges.

* Reusing the same key preserves a single logical transaction, even if the request is sent multiple times, and adds a safety layer around your retry sequence.
* Most merchants apply idempotency keys to all state-changing operations, including create, authorize, capture, refund, and void.
* Idempotency keys are valid for 24 hours. After 24 hours, a reused key is treated as a new transaction.

### Subscription retry schedule

For recurring billing failures, use a graduated retry schedule with customer communications at each step. Expanded Checkout does not enforce a specific retry schedule. The following pattern illustrates a common approach that balances recovery and customer experience for recurring payments:

| Day    | Action                 | Communication                                              |
| :----- | :--------------------- | :--------------------------------------------------------- |
| Day 0  | Initial charge attempt | —                                                          |
| Day 1  | Retry #1               | Soft notification: "We'll try again soon."                 |
| Day 3  | Retry #2               | Moderate urgency: "Please verify your payment method."     |
| Day 7  | Retry #3               | High urgency: "Service may be suspended." Suspend service. |
| Day 14 | Final retry #4         | Cancellation notice if declined.                           |

#### Guidelines

* **Maximum retries:** Most merchants attempt 4–5 retries before cancelling the subscription.
* **Hard declines:** In practice, hard declines are treated as terminal decisions, so merchants typically stop retries and ask the customer to update their payment method.
* **Backup payment method:** After the second failed retry, it is common to prompt for a backup payment method rather than waiting until the final attempt.
* **Time and day optimization:** Many merchants distribute retries across different times of day and days of the week, since balances and issuer risk posture vary over time.

## How Expanded Checkout keeps stored cards up to date

Stored cards introduce risks when they stop working after reissues, expirations, or other card updates. This section explains how network tokenization and the real-time account updater help keep stored payment methods usable over time while reducing declines.

### Network tokenization

Network tokenization replaces a card's Primary Account Number (PAN) with a network-issued token that remains valid even when the physical card expires or is reissued.

**Implementation options:**

* **PayPal Vault:** PayPal manages tokenization end-to-end. Recommended for most partners and merchants. [Save Payment Methods](https://developer.paypal.com/docs/checkout/save-payment-methods/)
* **Third-Party Tokens:** Use your own network tokens with PayPal. [Network Token Processing](https://developer.paypal.com/docs/checkout/advanced/3rd-party-token-processing/)

### Real-Time Account Updater (RTAU)

RTAU proactively updates stored card information when cards are replaced, expired, or reissued by the card issuer. This can improve auth rates on recurring and stored-credential transactions.

RTAU is valuable for:

* Subscription and recurring billing businesses
* Merchants storing payment methods for repeat customers

See [Real-Time Account Updater Documentation](https://developer.paypal.com/docs/checkout/advanced/customize/rtau/) for more information.

## Security and compliance

This section outlines the key security and compliance expectations for integrating with Expanded Checkout.

### TLS requirements

Expanded Checkout integrations must follow PayPal’s current HTTPS and TLS standards for all API traffic. For the latest requirements on supported TLS versions, cipher suites, and certificate expectations, see:

* [PayPal security guidelines for developers](/developer/how-to/security-guidelines)
* [Security guidelines and best practices](https://developer.paypal.com/api/rest/reference/info-security-guidelines/)

### Client credential management

* Store API credentials in environment variables. Never hard-code them.
* Use separate credentials for sandbox and production environments.
* Rotate keys every 6–12 months.
* Never commit credentials to version control or share through email or chat.
* Apply IP restrictions and least-privilege access principles.

### Authentication and session security

* Passwords should follow modern guidance such as [NIST SP 800-63B](https://pages.nist.gov/800-63-4/sp800-63b.html) or the [OWASP Authentication Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html). Require a minimum length of at least 12 characters and allow passphrases. Screen passwords against lists of common or compromised passwords, but don't require specific character classes.
* Passwords must be transmitted over HTTPS and stored using a non-reversible hashing method, such as bcrypt with a unique salt per user.
* Session tokens must be cryptographically strong, transmitted only over secure sessions, and re-authenticated after 15 minutes of inactivity.
* Implement controls to prevent brute force attacks on login credentials, including account lockout and CAPTCHA mechanisms.

### Fraud prevention

Implement multiple layers of fraud prevention to protect your integration and your customers:

1. **reCAPTCHA** — Prevents bot-based card testing attacks. [Google reCAPTCHA](https://developers.google.com/recaptcha/intro)
2. **FraudNet** — PayPal's device fingerprinting SDK for risk analysis. [FraudNet Integration](https://developer.paypal.com/docs/checkout/apm/pay-upon-invoice/fraudnet/)
3. **Velocity Limits** — Limit transactions per card, IP address, and email address to detect unusual patterns.
4. **AVS/CVV Verification** — Always collect and verify. Decline after multiple consecutive failures.
5. **Fraud Protection Advanced (FPA)** — ML-powered fraud detection and behavioral analytics. [FPA Documentation](https://developer.paypal.com/docs/checkout/advanced/customize/fraud-protection/fraud-protection-advanced/)

### Anti-phishing and site security

* Collect login credentials only on HTTPS pages using Extended Validation (EV) certificates.
* Maintain a process to proactively monitor for and take down spoofing and phishing sites.
* Provide a mechanism for customers to report suspected spoof sites.
* Protect against Cross-Site Scripting (XSS) and Cross-Site Request Forgery (XSRF) with appropriate framework controls. Test periodically with commercial tools, especially on new code deployments.
* Maintain a vulnerability management process covering infrastructure patching and application library updates, with patches prioritized by criticality.

## Monitoring and diagnostics

This section describes how to use monitoring and diagnostics to understand Expanded Checkout behavior and authorization patterns in production.

### Decline reason targets

| Decline category   | Acceptable % of total declines | Action if exceeded                  |
| :----------------- | :----------------------------- | :---------------------------------- |
| Insufficient Funds | \< 30%                         | Normal — optimize retry strategy    |
| Suspected Fraud    | \< 10%                         | Review fraud rules and data quality |
| Card Expired       | \< 5%                          | Enable Real-Time Account Updater    |
| AVS/CVV Failure    | \< 5%                          | Improve data collection at checkout |
| System Errors      | \< 2%                          | Investigate technical issues        |

### Critical alerts

Set up real-time alerting for the following thresholds:

#### P0: Page immediately

* Authorization rate drops below 75%.
* Overall error rate exceeds 10%.
* Decline volume increases by more than 50% in 1 hour.

#### P1: Warning

* Authorization rate drops more than 5% vs. 7-day average.
* Webhook endpoint returns more than 5% errors.
* Any single decline code increases by more than 20%.

### Diagnostic tools

**Attempts and Declines Report:** Access via PayPal Business account under **Reports** > **Decline Analysis**. See the [Attempts and Declines Report User Guide](https://developer.paypal.com/docs/multiparty/reports/attempts-declines/) for more details.

### Webhook implementation

Webhooks are mandatory for production integrations. They are required because customers may not return to the success page, and many payment events are asynchronous, such as 3D Secure authentication, Automated Clearing House (ACH) payments, and disputes.

#### Requirements

* HTTPS endpoint, publicly accessible, returning a `2xx` status within 5–10 seconds.
* Process webhooks asynchronously — do not block the response.
* Verify every incoming webhook using PayPal's documented signature verification approach, such as the [Verify webhook signature endpoint](/reference/api/rest/verify-webhook-signature/verify-webhook-signature#verify-webhook-signature) of the Webhooks Management v1 API, to confirm it originated from PayPal.
* Implement idempotent webhook processing — PayPal will retry failed deliveries up to 25 times with exponential backoff.

#### Critical events to handle

| Event                       | Action                         |
| :-------------------------- | :----------------------------- |
| `PAYMENT.CAPTURE.COMPLETED` | Fulfill the order.             |
| `PAYMENT.CAPTURE.DECLINED`  | Cancel order, notify customer. |
| `PAYMENT.CAPTURE.REFUNDED`  | Notify customer of refund.     |
| `CUSTOMER.DISPUTE.CREATED`  | Gather evidence immediately.   |

## Glossary

| Term        | Definition                                                                                 |
| :---------- | :----------------------------------------------------------------------------------------- |
| AVS         | **Address Verification Service:** validates billing address against issuer records         |
| CIT         | **Customer-Initiated Transaction:** customer is actively present at checkout               |
| CVV/CVC     | **Card Verification Value/Code:** 3–4 digit security code on the card                      |
| 3DS         | **3D Secure:** authentication protocol for card-not-present transactions                   |
| Idempotency | Property ensuring the same operation produces the same result when repeated                |
| MIT         | **Merchant-Initiated Transaction:** automated charge without active customer participation |
| PAN         | **Primary Account Number:** the full card number                                           |
| PSD2        | **Payment Services Directive 2:** EU regulation requiring Strong Customer Authentication   |
| RTAU        | **Real-Time Account Updater:** automatic card detail refresh on stored payment methods     |
| SCA         | **Strong Customer Authentication:** PSD2 two-factor authentication requirement             |

## Related resources

* [PayPal Developer Security Guidelines](https://developer.paypal.com/api/rest/reference/info-security-guidelines/)
* [3D Secure Integration](https://developer.paypal.com/docs/checkout/advanced/customize/3d-secure/)
* [SCA payment indicators](https://developer.paypal.com/docs/checkout/advanced/customize/sca-payment-indicators/)


# Fastlane integration
Source: https://docs.paypal.ai/payments/methods/cards/fastlane



PayPal Fastlane is a streamlined checkout experience that allows returning customers to authenticate and pay quickly using saved payment methods and shipping addresses. New customers can also use it for a smooth guest checkout experience. For more information about Fastlane, see the <a href="https://developer.paypal.com/studio/checkout/fastlane">PayPal Fastlane documentation</a>.

This guide provides instructions for integrating PayPal Fastlane into your web application using the v6 web SDK.

## Prerequisites

* PayPal sandbox account with appropriate credentials. For more information about using PayPal's sandbox for testing, see the <a href="https://developer.paypal.com/tools/sandbox/">PayPal sandbox testing guide</a>.
* Backend server for API proxy.  For more information, see <a href="https://github.com/paypal-examples/v6-web-sdk-sample-integration/blob/main/server/node/README.md">`/server/node/README.md`</a>.
* A web browser with ES6 support.

There also are requirements for the [backend](#backend-endpoints) and your [HTML](#html-structure).

### Backend endpoints

Your backend must provide these API endpoints:

* The client token endpoint provides a client token for SDK initialization.
  * URL: `GET /paypal-api/auth/browser-safe-client-token`
  * Response: `{ "accessToken": "YOUR-CLIENT-TOKEN" }`
* The order creation endpoint creates a PayPal order using the payment token.
  * URL: `POST /paypal-api/checkout/orders/create`
  * Headers: <br />
    `Content-Type: application/json` <br />
    `PayPal-Request-Id: <unique-id>`

### HTML structure

Your HTML must include these elements.

```html theme={null}
<!-- Email form -->
<form id="email-form">
  <input type="email" id="email-input" />
  <div id="watermark-container"></div>
  <button id="email-submit-button">Submit</button>
</form>

<!-- Payment containers -->
<div id="card-container"></div>
<div id="payment-container"></div>

<!-- Shipping display -->
<div id="shipping-display-container" hidden></div>
<button id="change-shipping-button" hidden>Change Shipping Address</button>

<!-- Order submission -->
<button id="submit-button" hidden>Submit Order</button>

<!-- Card testing info -->
<p id="card-testing-info" hidden>
  For more info on testing cards with PayPal, see
  <a href="https://developer.paypal.com/tools/sandbox/card-testing/">
    https://developer.paypal.com/tools/sandbox/card-testing/
  </a>
</p>
```

## Integration

Fastlane integration consists of three main JavaScript files:

* `fastlaneSdkComponent.js`: SDK initialization and client token management
* `fastlane.js`: Main integration logic and UI handling
* `fastlane.css`: Basic styling for the checkout experience

For examples of these files, see <a href="https://github.com/paypal-examples/v6-web-sdk-sample-integration/tree/fcaf5ceb342a41813803c060bdbe4039ccbe3f56/client/components/fastlane/html/src">this GitHub repo folder</a>.

To complete the integration:

1. Include the PayPal SDK script in your HTML.

```html theme={null}
<script async onload="onPayPalLoaded()" src="https://www.sandbox.paypal.com/web-sdk/v6/core"></script>
```

1. Initialize the SDK and Fastlane (`fastlaneSdkComponent.js`).

In this example, you see some Fastlane SDK options:

* `pageType`: The applicable page type, such as `product-details`
* `clientMetadataId`: Unique session identifier
* `components`: Array that includes `fastlane` <br /><br />

```javascript theme={null}
async function onPayPalLoaded() {
  const clientToken = await getBrowserSafeClientToken();
  const sdkInstance = await window.paypal.createInstance({
    clientToken,
    pageType: "product-details",
    clientMetadataId: crypto.randomUUID(),
    components: ["fastlane"],
  });
  fastlane = await sdkInstance.createFastlane();
  setupFastlaneSdk();
}
```

2. Set up the email-lookup flow (`fastlane.js`).

The email-lookup process determines whether a user is a Fastlane member.

```javascript theme={null}
async function setupFastlaneSdk() {
  fastlane.setLocale("en_us");
  // Render Fastlane watermark
  const fastlaneWatermark = await fastlane.FastlaneWatermarkComponent({
    includeAdditionalInfo: true,
  });
  fastlaneWatermark.render("#watermark-container");
  // Handle email submission
  const emailSubmitButton = document.getElementById("email-submit-button");
  emailSubmitButton.addEventListener("click", async (e) => {
    e.preventDefault();
    const {
      customerContextId
    } = await fastlane.identity.lookupCustomerByEmail(emailInput.value, );
    let shouldRenderFastlaneMemberExperience = false;
    let profileData;
    if (customerContextId) {
      const response = await fastlane.identity.triggerAuthenticationFlow(customerContextId);
      if (response.authenticationState === "succeeded") {
        shouldRenderFastlaneMemberExperience = true;
        profileData = response.profileData;
      }
    }
    // Route to appropriate experience
    if (shouldRenderFastlaneMemberExperience) {
      renderFastlaneMemberExperience(profileData);
    } else {
      renderFastlaneGuestExperience();
    }
  });
}
```

3. Set up handling for members (`fastlane.js`).

Members are authenticated Fastlane members who have saved data.

```javascript theme={null}
async function renderFastlaneMemberExperience(profileData) {
  if (profileData.shippingAddress) {
    setShippingAddressDisplay(profileData.shippingAddress);
    // Allow address changes
    const changeAddressButton = document.getElementById("change-shipping-button");
    changeAddressButton.addEventListener("click", async () => {
      const {
        selectedAddress,
        selectionChanged
      } = await fastlane.profile.showShippingAddressSelector();
      if (selectionChanged) {
        profileData.shippingAddress = selectedAddress;
        setShippingAddressDisplay(profileData.shippingAddress);
      }
    });
    // Render payment component with shipping address
    const fastlanePaymentComponent = await fastlane.FastlanePaymentComponent({
      options: {},
      shippingAddress: profileData.shippingAddress,
    });
    fastlanePaymentComponent.render("#payment-container");
  }
}
```

4. Set up handling for guests (`fastlane.js`).

Guests are new or unauthenticated users.

```javascript theme={null}
async function renderFastlaneGuestExperience() {
  const cardTestingInfo = document.getElementById("card-testing-info");
  cardTestingInfo.removeAttribute("hidden");
  const FastlanePaymentComponent = await fastlane.FastlanePaymentComponent({});
  await FastlanePaymentComponent.render("#card-container");
}
```

5. Set up payment processing (`fastlane.js`).

Payment processing includes generating a payment token and creating an order.

In this step, you see these payment component options:

* `options`: Additional payment component configuration
* `shippingAddress`: Pre-populate with a member's saved address <br /><br />

```javascript theme={null}
// Get payment token
const {
  id
} = await fastlanePaymentComponent.getPaymentToken();
// Create order via backend API
async function createOrder(paymentToken) {
  const response = await fetch("/paypal-api/checkout/orders/create", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "PayPal-Request-Id": Date.now().toString(),
    },
    body: JSON.stringify({
      paymentSource: {
        card: {
          singleUseToken: paymentToken,
        },
      },
      purchaseUnits: [{
        amount: {
          currencyCode: "USD",
          value: "10.00",
          breakdown: {
            itemTotal: {
              currencyCode: "USD",
              value: "10.00",
            },
          },
        },
      }, ],
      intent: "CAPTURE",
    }),
  });
  return await response.json();
}
```

## Error handling

This integration includes basic error handling, including:

* If a member's authentication fails, they get the guest experience.
* Errors in order creation display user-friendly messages.
* The console logs error information to help with debugging.

## Testing

For testing, use PayPal's <a href="https://developer.paypal.com/tools/sandbox/">sandbox environment</a> with sandbox credentials.

Test <a href="https://developer.paypal.com/studio/checkout/fastlane/integrate#test-integration"> member and guest flows with card numbers</a>.

## Sample app

To see the sample app, run these commands.

```bash theme={null}
npm install
npm start
```

The sample app will run at `http://localhost:3000/`. The sample requires a backend server at `http://localhost:8080`.

## See also

Examine a full example of a Fastlane integration on <a href="https://github.com/paypal-examples/v6-web-sdk-sample-integration/tree/main/client/components/fastlane/html/">GitHub</a>.


# Render card fields for one-time checkout with PayPal's JavaScript SDK v6
Source: https://docs.paypal.ai/payments/methods/cards/js-sdk-v6-card-fields-one-time



This guide shows how to:

* Load the JavaScript SDK v6 core script
* Initialize an SDK instance using a client ID
* Render Card Fields (number, CVV, expiry)
* Create and submit an order
* Capture the order and handle 3-D Secure (3DS) outcomes

You'll connect two backend routes:

* `POST /paypal-api/checkout/orders/create-with-sample-data`: returns a new orderId
* `POST /paypal-api/checkout/orders/{orderId}/capture` captures the order

## Prerequisites

You'll need the following:

* A PayPal sandbox business account and REST app with permissions to create client tokens.
* A server capable of calling PayPal APIs securely. Node and Express examples included below.
* [PCI Compliance](https://www.pcisecuritystandards.org/).
  PCI DSS SAQ A-EP considerations: Card fields are hosted or iframes from PayPal. Your page must follow security best practices.

## Add the JavaScript SDK script

Include the core script and call the `onPayPalWebSdkLoaded()` handler when it's ready.

```html theme={null}
<script async src="https://sandbox.paypal.com/web-sdk/v6/core" onload="onPayPalWebSdkLoaded()"></script>
```

Keep `async` to avoid blocking the render.

## Build an HTML container

Provide containers for each card field and a pay button.

The provided containers must have a defined height and width. The card field fills the entire space of the parent container.

The `button id` in the sample is `pay-button`. Make sure your JavaScript uses the same selector.

```html theme={null}
<style>
  .card-field {
    height: 3rem;
    margin-bottom: 1rem;
  }
</style>

<div class="card-fields-container">
  <div class="card-field" id="paypal-card-fields-number"></div>
  <div class="card-field" id="paypal-card-fields-expiry"></div>
  <div class="card-field" id="paypal-card-fields-cvv"></div>
</div>
<button id="pay-button" class="pay-button">Pay</button>
```

## Initialize the SDK and render card fields

Create an SDK instance with your client ID, then create a one‑time payment session for credit and debit card fields and mount the components.

To pass billing fields, use the `submit(orderId, { billingAddress: { ... } })` options object. Include at least the fields you require for your risk and SCA strategy, for example, `postalCode`.

```javascript theme={null}
async function onPayPalWebSdkLoaded() {
  try {
    const sdk = await window.paypal.createInstance({
      clientId: "YOUR_CLIENT_ID",
      components: ["card-fields"],
    });

    const paymentMethods = await sdk.findEligibleMethods();
    const isCardFieldsEligible = paymentMethods.isEligible("advanced_cards");
    if (isCardFieldsEligible) {
      await setupCardFields(sdk);
    }
  } catch (err) {
    console.error("SDK init failed", err);
  }
}

async function setupCardFields(sdk) {
  const cardSession = sdk.createCardFieldsOneTimePaymentSession();

  const numberField = cardSession.createCardFieldsComponent({
    type: "number",
    placeholder: "Card number",
  });

  const expiryField = cardSession.createCardFieldsComponent({
    type: "expiry",
    placeholder: "MM/YY",
  });

  const cvvField = cardSession.createCardFieldsComponent({
    type: "cvv",
    placeholder: "CVV",
  });


  document.querySelector("#paypal-card-fields-number").appendChild(numberField);
  document.querySelector("#paypal-card-fields-expiry").appendChild(expiryField);
  document.querySelector("#paypal-card-fields-cvv").appendChild(cvvField);

  const payButton = document.querySelector("#pay-button");
  payButton.addEventListener("click", () => onPayClick(cardSession));
}
```

## Create, submit, and capture the order

1. Create the order on your server, then receive the `orderId`.
2. Call `cardSession.submit(orderId, options)` to handle validations and 3D Secure.
3. If `state === "succeeded"`, capture the order on your server.

```javascript theme={null}
async function onPayClick(cardSession) {
  try {
    const orderId = await createOrder(); // returns a string id

    const {
      data,
      state
    } = await cardSession.submit(orderId, {
      billingAddress: {
        postalCode: "95131"
      }, // supply what your business needs
    });

    switch (state) {
      case "succeeded": {
        const {
          orderId,
          liabilityShift
        } = data
        // 3DS may or may not have occurred; Use liabilityShift 
        // to determine if the payment should be captured
        const capture = await captureOrder(orderId);
        // TODO: show success UI, redirect, etc.
        break;
      }
      case "canceled": {
        // Buyer dismissed 3DS modal or canceled the flow
        // TODO: show non-blocking message & allow retry
        break;
      }
      case "failed": {
        // Validation or processing failure. data.message may be present
        console.error("Card submission failed", data);
        // TODO: surface error to buyer, allow retry
        break;
      }
      default: {
        // Future-proof for other states (e.g., pending)
        console.warn("Unhandled submit state", state, data);
      }
    }
  } catch (err) {
    console.error("Payment flow error", err);
    // TODO: Show generic error and allow retry
  }
}
```

## Client helpers

[//]: # "Need introduction to this code"

```javascript theme={null}
async function createOrder() {
  const res = await fetch("/paypal-api/checkout/orders/create-with-sample-data", {
    method: "POST",
    headers: {
      "Content-Type": "application/json"
    },
  });
  const {
    id
  } = await res.json();
  return id; // return the string orderId
}

async function captureOrder(orderId) {
  const res = await fetch(`/paypal-api/checkout/orders/${orderId}/capture`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json"
    },
  });
  return res.json();
}
```

## Server examples

The following is a minimal example to support two routes. It uses the PayPal Orders v2 API. Replace placeholders and secure secrets appropriately.

```javascript theme={null}
import express from "express";
import fetch from "node-fetch";

const app = express();
app.use(express.json());

const PAYPAL_BASE = process.env.PAYPAL_BASE || "https://api-m.sandbox.paypal.com"; // use api-m.paypal.com in prod
const CLIENT_ID = process.env.PAYPAL_CLIENT_ID;
const CLIENT_SECRET = process.env.PAYPAL_CLIENT_SECRET;

async function appAccessToken(formBody) {
  const creds = Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString("base64");
  const res = await fetch(`${PAYPAL_BASE}/v1/oauth2/token`, {
    method: "POST",
    headers: {
      "Authorization": `Basic ${creds}`,
      "Content-Type": "application/x-www-form-urlencoded",
    },
    body: formBody,
  });
  const json = await res.json();
  return json.access_token;
}

// 1) Create order with sample purchase units
app.post("/paypal-api/checkout/orders/create-with-sample-data", async (_req, res) => {
  try {
    const fullScopeAccessTokenFormBody = "grant_type=client_credentials&response_type=token"
    const accessToken = await appAccessToken(fullScopeAccessTokenFormBody);
    const r = await fetch(`${PAYPAL_BASE}/v2/checkout/orders`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${accessToken}`,
      },
      body: JSON.stringify({
        intent: "CAPTURE",
        purchase_units: [{
          amount: {
            currency_code: "USD",
            value: "10.00"
          },
        }, ],
      }),
    });
    const data = await r.json();
    res.json({
      id: data.id
    });
  } catch (e) {
    console.error(e);
    res.status(500).json({
      error: "order_create_error"
    });
  }
});

// 2) Capture order
app.post("/paypal-api/checkout/orders/:orderId/capture", async (req, res) => {
  try {
    const fullScopeAccessTokenFormBody = "grant_type=client_credentials&response_type=token"
    const accessToken = await appAccessToken(fullScopeAccessTokenFormBody);
    const r = await fetch(`${PAYPAL_BASE}/v2/checkout/orders/${req.params.orderId}/capture`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${accessToken}`,
      },
    });
    const data = await r.json();
    res.json(data);
  } catch (e) {
    console.error(e);
    res.status(500).json({
      error: "order_capture_error"
    });
  }
});

app.listen(3000, () => console.log("Server listening on 3000"));
```

## Style card fields

Use the `style` option to control input styling such as font size and color. Keep contrast [AA or better](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html). Avoid setting styles that imply validation, such as red and green, unless synchronized with real validation states.

Allowed CSS selectors:

* `appearance`
* `background`
* `border`
* `borderRadius`
* `boxShadow`
* `color`
* `direction`
* `font`
* `fontFamily`
* `fontSize`
* `fontSizeAdjust`
* `fontStretch`
* `fontStyle`
* `fontVariant`
* `fontVariantAlternates`
* `fontVariantCaps`
* `fontVariantEastAsian`
* `fontVariantLigatures`
* `fontVariantNumeric`
* `fontWeight`
* `height`
* `letterSpacing`
* `lineHeight`
* `opacity`
* `outline`
* `padding`
* `paddingBottom`
* `paddingLeft`
* `paddingRight`
* `paddingTop`
* `textShadow`
* `transition`

```javascript theme={null}
const numberField = cardSession.createCardFieldsComponent({
  type: "number",
  style: {
    input: {
      fontSize: "16px",
      lineHeight: "24px",
    },
    ".invalid": {
      color: orange
    },
  },
});
```

## Handle outcomes and errors

There are 3 possible outcomes from checkout:

* `state === "succeeded"`: Proceed to capture on server and show success.
* `state === "canceled"`: Buyer closed 3DS modal. Allow retry.
* `state === "failed"`: Inspect `data.message` and field errors if provided. Keep logs server‑side with correlation IDs from API responses.

Common troubleshooting issues:

* **Button id mismatch**: Ensure your JS listens to `#pay-button` and not `#save-payment-method-button`.
* **OrderId shape**: Pass the string `orderId` to `submit()`. Do not pass an object such as `{ orderId }`.
* **Missing breaks in switch**: Include `break;` in each case to avoid fall‑through.

## Test

* Test in the PayPal sandbox environment and use [test credit cards](https://developer.paypal.com/tools/sandbox/card-testing/#link-testgeneratedcardnumbers).
* Test the following scenarios:
  * Valid payment
  * Card validation error
  * 3DS succeeded
  * 3DS canceled
  * Network or server error on capture

## Production readiness checklist

* Use production script at [https://www.paypal.com/web-sdk/v6/core](https://www.paypal.com/web-sdk/v6/core).
* Use CSRF protection on your backend routes
* Ensure your integration has robust error handling and user‑friendly retry states
* Ensure your integration logs PayPal API correlation IDs for support
* Check your site for accessibility by keyboard and screen reader
* Ensure your Content Security Policy is updated for PayPal domains

## Full working example

The following example shows a JavaScript and HTML page that renders card fields for one-time checkout. You can localize placeholder strings when creating each component.

When available, use `sdk.findEligibleMethods({ currencyCode: "USD" })` and gate Card Fields rendering accordingly. The card may not appear in the eligibility response yet. Integrate defensively.

```html theme={null}
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>One‑Time Payment — Card Fields</title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <style>
      .card-fields-container { display: flex; flex-direction: column; gap: 12px; }
      .pay-button { padding: 12px 16px; font-size: 16px; }
      .is-loading { opacity: 0.6; pointer-events: none; }
    </style>
  </head>
  <body>
    <h1>Card Fields — One‑Time Payment</h1>

   <div class="card-fields-container">
    <div class="card-field" id="paypal-card-fields-number"></div>
    <div class="card-field" id="paypal-card-fields-expiry"></div>
    <div class="card-field" id="paypal-card-fields-cvv"></div>
  </div>
<button id="pay-button" class="pay-button">Pay</button>

    <button id="pay-button" class="pay-button">Pay</button>

    <script>
      async function onPayPalWebSdkLoaded() {
        try {
          const sdk = await window.paypal.createInstance({
            clientId: "YOUR_CLIENT_ID",
            components: ["card-fields"],
            pageType: "checkout",
          });
          const paymentMethods = await sdk.findEligibleMethods();
          const isCardFieldsEligible = paymentMethods.isEligible("advanced_cards");
          if(isCardFieldsEligible){
           await setupCardFields(sdk); 
          }
        } catch (err) {
          console.error(err);
        }
      }

      async function setupCardFields(sdk) {
        const session = sdk.createCardFieldsOneTimePaymentSession();

        const numberField = session.createCardFieldsComponent({ type: "number", placeholder: "Card number" });
        const expiryField = session.createCardFieldsComponent({ type: "expiry", placeholder: "MM/YY" });
        const cvvField = session.createCardFieldsComponent({ type: "cvv", placeholder: "CVV" });
        

        document.querySelector("#paypal-card-fields-number").appendChild(numberField);
        document.querySelector("#paypal-card-fields-expiry").appendChild(expiryField);
        document.querySelector("#paypal-card-fields-cvv").appendChild(cvvField);

        const button = document.querySelector("#pay-button");
        button.addEventListener("click", async () => {
          try {
            button.classList.add("is-loading");
            const orderId = await createOrder();
            const { data, state } = await session.submit(orderId, {
              billingAddress: { postalCode: "95131" },
            });

            switch (state) {
              case "succeeded": {
                const capture = await captureOrder(data.orderId);
                alert("Payment captured");
                break;
              }
              case "canceled": {
                alert("Authentication canceled. Please try again.");
                break;
              }
              case "failed": {
                alert(data?.message || "Payment failed. Check your details and try again.");
                break;
              }
              default: {
                console.warn("Unhandled state", state);
              }
            }
          } catch (err) {
            console.error(err);
            alert("Unexpected error. Please try again.");
          } finally {
            button.classList.remove("is-loading");
          }
        });
      }

      async function createOrder() {
        const r = await fetch("/paypal-api/checkout/orders/create-with-sample-data", { method: "POST" });
        const { id } = await r.json();
        return id;
      }

      async function captureOrder(orderId) {
        const r = await fetch(`/paypal-api/checkout/orders/${orderId}/capture`, { method: "POST" });
        return r.json();
      }
    </script>

    <script async src="https://www.sandbox.paypal.com/web-sdk/v6/core" onload="onPayPalWebSdkLoaded()"></script>
  </body>
</html>
```


# Integrate standalone payment buttons with PayPal's JavaScript SDK v6
Source: https://docs.paypal.ai/payments/methods/cards/standalone-payment-button



With PayPal's JavaScript SDK v6, you can accept basic card and debit card processing without requiring payers to log in or create a PayPal account. You'll set up a test environment, add the needed frontend and backend, and then launch your standalone payment button in both sandbox and production.

## Prerequisites

Before beginning your integration, meet these requirements:

* Create a [PayPal Developer account](https://developer.paypal.com).
* Create a PayPal app in the **Apps & Credentials** section of your account.
* Use the **Sandbox** environment for testing.
* Note your **Client ID** and **Secret** for server configuration.

## Development setup

Before you run the [v6-web-sdk-sample-integration](https://github.com/paypal-examples/v6-web-sdk-sample-integration) locally, complete both server and client setup.

## Server set up

1. Navigate to your demo directory and install dependencies:

```
npm install
```

2. Create environment configuration:

```bash theme={null}
# .env file
PAYPAL_SANDBOX_CLIENT_ID=your_client_id
PAYPAL_SANDBOX_CLIENT_SECRET=your_client_secret
```

3. Start the server:

```bash theme={null}
npm start
```

To load the application, see `http://localhost:8080`.

## Client set up

1. Navigate to the demo directory:

```
cd client/components/paypalGuestPayments/html
```

2. Install dependencies:

```
npm install
```

3. Start development server:

```
npm start
```

To load the application, see `http://localhost:3000`.

## Integration patterns

The v6 SDK supports a variety of standalone payment button integration flows. The following patterns help you tailor the user experience for different requirements.

### Standard button

Use the standard button implementation for payers to select a button to start the standalone payment button flow (Recommended).

* **File**: `html/src/recommended/app.js`

```javascript theme={null}
// 1. Initialize SDK when script loads
async function onPayPalWebSdkLoaded() {
  const sdkInstance = await window.paypal.createInstance({
    clientId: "YOUR_CLIENT_ID",
    components: ["paypal-guest-payments"],
  });
  
  setupGuestPaymentButton(sdkInstance);
}

// 2. Setup the payment session
async function setupGuestPaymentButton(sdkInstance) {
  // Check eligibility
  const eligiblePaymentMethods = await sdkInstance.findEligibleMethods({
    currencyCode: "USD",
  });

  // Create payment session with callbacks
  const paypalGuestPaymentSession = 
    await sdkInstance.createPayPalGuestOneTimePaymentSession({
      onApprove,
      onCancel, 
      onComplete,
      onError,
      onWarn,
    });

  // 3. Start checkout on button click
  document.getElementById("paypal-basic-card-button")
    .addEventListener("click", async () => {
      const startOptions = {
        presentationMode: "auto",
      };
      await paypalGuestPaymentSession.start(startOptions, createOrder());
    });
}
```

#### HTML setup

```html theme={null}
<paypal-basic-card-container>
  <paypal-basic-card-button id="paypal-basic-card-button">
  </paypal-basic-card-button>
</paypal-basic-card-container>

<script src="app.js"></script>
<script 
  async
  src="https://www.sandbox.paypal.com/web-sdk/v6/core"
  onload="onPayPalWebSdkLoaded()">
</script>
```

### Auto-start on load

Use the auto-start on load integration to automatically initiate the standalone payment button.

* **File**: `html/src/onload/app.js`

```javascript theme={null}
async function onPayPalWebSdkLoaded() {
  // ... standard setup ...
  
  const checkoutButton = document.getElementById("paypal-basic-card-button");
  
  // Auto-start checkout on page load
  startGuestPaymentSession(checkoutButton, paypalGuestPaymentSession);
  
  // Also setup button for manual trigger
  setupGuestPaymentButton(checkoutButton, paypalGuestPaymentSession);
}

// Reusable function for starting checkout
async function startGuestPaymentSession(checkoutButton, paypalGuestPaymentSession) {
  const startOptions = {
    targetElement: checkoutButton,
    presentationMode: "auto",
  };
  await paypalGuestPaymentSession.start(startOptions, createOrder());
}
```

### Shipping callbacks

Use the shipping callback integration to handle address validation and shipping option changes.

* **File**: `html/src/shipping/app.js`

```javascript theme={null}
const paypalGuestPaymentSession =
  await sdkInstance.createPayPalGuestOneTimePaymentSession({
    onApprove,
    onCancel,
    onComplete, 
    onError,
    onWarn,
    onShippingAddressChange,  // New callback
    onShippingOptionsChange,  // New callback
  });

// Validate shipping address (example: US-only)
function onShippingAddressChange(data) {
  const countryCode = data?.shippingAddress?.countryCode ?? "US";
  if (countryCode !== "US") {
    throw new Error(data?.errors?.COUNTRY_ERROR);
  }
}

// Handle shipping option changes
function onShippingOptionsChange(data) {
  const selectedShippingOption = data?.selectedShippingOption?.id;
  if (selectedShippingOption === "SHIP_UNV") {
    throw new Error(data?.errors?.METHOD_UNAVAILABLE);
  }
}
```

#### Sample order creation with shipping options

```javascript theme={null}
async function createOrder() {
  const orderPayload = {
    intent: "CAPTURE",
    purchaseUnits: [{
      amount: {
        currencyCode: "USD",
        value: "10.00",
        breakdown: {
          itemTotal: { currencyCode: "USD", value: "10.00" },
        },
      },
      shipping: {
        options: [
          {
            id: "SHIP_FRE",
            label: "Free",
            type: "SHIPPING", 
            selected: true,
            amount: { value: "0.00", currencyCode: "USD" },
          },
          {
            id: "SHIP_EXP",
            label: "Expedited",
            type: "SHIPPING",
            selected: false, 
            amount: { value: "5.00", currencyCode: "USD" },
          },
        ],
      },
    }],
  };

  const response = await fetch("/paypal-api/checkout/orders/create", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(orderPayload),
  });
  
  const { id } = await response.json();
  return { orderId: id };
}
```

## Implementation support functions

These helper functions allow the client to interact with your backend for order creation and payment capture.

### Create order

```javascript theme={null}
async function createOrder() {
  const response = await fetch(
    "/paypal-api/checkout/orders/create-with-sample-data", 
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
    }
  );
  const { id } = await response.json();
  return { orderId: id };
}
```

### Capture order

```javascript theme={null}
async function captureOrder({ orderId }) {
  const response = await fetch(
    `/paypal-api/checkout/orders/${orderId}/capture`,
    {
      method: "POST", 
      headers: { "Content-Type": "application/json" },
    }
  );
  return await response.json();
}
```

## Callback functions

Define the callback functions to handle key events during the standalone payment button flow, such as approvals, cancellations, errors, and warnings.

### Required callbacks

```javascript theme={null}
// Handle successful payment approval
async function onApprove(data) {
  console.log("onApprove", data);
  const orderData = await captureOrder({ orderId: data.orderId });
  console.log("Capture result", orderData);
}

// Handle payment cancellation
function onCancel(data) {
  console.log("onCancel", data);
  // Handle cancellation logic
}

// Handle payment completion
function onComplete(data) {
  console.log("onComplete", data);
  // Handle completion logic (success page, etc.)
}

// Handle errors
function onError(data) {
  console.log("onError", data);
  // Handle error display to user
}

// Handle warnings
function onWarn(data) {
	console.log("onWarn", data);
	// Handle warnings as needed
}
```

The `data` argument to `onWarn` will always have the following shape:

```json theme={null}
{
	"message": "PayPalGuestCheckoutSession form submit failed: GUEST_CHECKOUT_INLINE_FORM_SUBMIT_FAILURE",
	"name":"PaymentFlowWarning",
	"code":"WARN_FLOW_GUEST_CHECKOUT_SUBMIT_ERROR"
}
```

When the `onWarn` callback executes, the buyer has encountered an error after they pressed the form submit button. These errors could include
card failures, first/last name formatting errors, or address errors.

## Start options

When starting a payment session, you can configure presentation mode.

```javascript theme={null}
const startOptions = {
  presentationMode: "auto", // "auto", "modal", "popup", or "redirect"
  targetElement: checkoutButton, // Optional: element to attach to
};

await paypalGuestPaymentSession.start(startOptions, createOrder());
```

## API endpoints

Your backend server must provide these endpoints:

* `POST /paypal-api/checkout/orders/create-with-sample-data` - Creates PayPal order with sample data
* `POST /paypal-api/checkout/orders/create` - Creates PayPal order with custom data
* `POST /paypal-api/checkout/orders/{order-id}/capture` - Captures the authorized payment

## Testing

See the steps for running and validating your integration.

1. Ensure both server and client are running.
2. Navigate to the demo page.
3. Use PayPal Sandbox test accounts.
4. Test all three integration patterns:
   * Standard button
   * Auto-start on load
   * Shipping callbacks

## Best practices

* **Error handling**: Always wrap PayPal API calls in try-catch blocks.
* **Eligibility check**: Call `findEligibleMethods()` to determine available payment options.
* **Security**: Never expose client secrets in frontend code.
* **User experience**: Choose the most suitable presentation mode for your use case.
* **Validation**: Validate shipping callbacks if needed.
* **Testing**: Test thoroughly in PayPal Sandbox before going live.

## Troubleshooting

Quick solutions for common issues:

* **SDK load errors**: Ensure the JavaScript SDK v6 script loads before `onPayPalWebSdkLoaded()`.

* **SDK initialization issues**: Verify that your client ID is correct and that the server endpoints are running and accessible.

* **Eligibility issues**: Check that your standalone payments are enabled in PayPal app settings.

* **CORS errors**: Confirm proper CORS configuration between client and server.


# Integrate Apple Pay with PayPal's JavaScript SDK v6
Source: https://docs.paypal.ai/payments/methods/digital-wallets/apple-pay



With PayPal's JavaScript SDK v6, you can accept Apple Pay for secure, one-tap payments. You'll set up a test environment, add the needed frontend and backend, and then launch Apple Pay in both sandbox and production.

## Prerequisites

Before beginning your integration, meet these requirements:

* Create a [PayPal Developer account](https://developer.paypal.com) with Apple Pay enabled.
* Obtain an Apple Developer Program membership for live payments.
* Set up an HTTPS environment or ngrok for local development.

## Development setup

Configure your local development environment to work with Apple Pay's HTTPS requirement and PayPal's domain validation. For reference, see this [Apple Pay demo](https://github.com/paypal-examples/v6-web-sdk-sample-integration/tree/main/client/components/applepayPayments/html).

1. Install and configure ngrok:
   ```bash theme={null}
   npm install -g ngrok
   ngrok config add-authtoken YOUR_AUTHTOKEN
   ngrok http 3000
   ```

2. Update the Vite configuration:
   ```javascript theme={null}
   // vite.config.js
   export default defineConfig({
     server: {
       allowedHosts: ["your-ngrok-domain.ngrok-free.app"],
       proxy: {
         "/paypal-api": {
           target: "http://localhost:8080",
           changeOrigin: true,
           secure: false,
         },
       },
     },
   });
   ```

3. Register your domain with PayPal:
   * Add your ngrok domain to PayPal's Apple Pay settings
   * Download and save the domain association file

## Implementation steps

Implement Apple Pay by following the detailed steps.

### Step 1: HTML structure setup

Create your basic HTML page and include the Apple Pay and PayPal SDK scripts.

```html theme={null}
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Apple Pay Integration</title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
  </head>
  <body>
    <h1>Apple Pay Payment</h1>
    <div id="apple-pay-button-container"></div>
    
    <!-- Apple Pay SDK -->
    <script src="https://applepay.cdn-apple.com/jsapi/v1/apple-pay-sdk.js"></script>
    
    <!-- PayPal JavaScript SDK -->
    <script
      async
      src="https://www.sandbox.paypal.com/web-sdk/v6/core"
      onload="onPayPalWebSdkLoaded()"
    ></script>
    
    <script src="app.js"></script>
  </body>
</html>
```

### Step 2: Initialize PayPal SDK

Set up the v6 SDK with Apple Pay components once it loads.

```javascript theme={null}
async function onPayPalWebSdkLoaded() {
  try {
    const sdkInstance = await window.paypal.createInstance({
      clientId: "YOUR_CLIENT_ID",
      components: ["applepay-payments"],
      pageType: "checkout",
    });

    setupApplePayButton(sdkInstance);
  } catch (error) {
    console.error("SDK initialization failed:", error);
  }
}
```

### Step 3: Configure Apple Pay button

Generate the Apple Pay button element and configure it for your payment flow.

```javascript theme={null}
async function setupApplePayButton(sdkInstance) {
  const paypalSdkApplePayPaymentSession = 
    await sdkInstance.createApplePayOneTimePaymentSession();

  const { merchantCapabilities, supportedNetworks } = 
    await paypalSdkApplePayPaymentSession.config();

  // Create Apple Pay button
  document.getElementById("apple-pay-button-container").innerHTML =
    '<apple-pay-button id="apple-pay-button" buttonstyle="black" type="buy" locale="en">';
  
  document.getElementById("apple-pay-button")
    .addEventListener("click", handleApplePayClick);
}
```

### Step 4: Configure payment request

Set up your payment details and start the Apple Pay session when users tap the button.

```javascript theme={null}
async function handleApplePayClick() {
  const paymentRequest = {
    countryCode: "US",
    currencyCode: "USD",
    merchantCapabilities,
    supportedNetworks,
    requiredBillingContactFields: ["name", "phone", "email", "postalAddress"],
    requiredShippingContactFields: [],
    total: {
      label: "Your Store Name",
      amount: "100.00",
      type: "final",
    },
  };

  const applePaySession = new ApplePaySession(4, paymentRequest);
  
  // Configure event handlers
  setupApplePayEventHandlers(applePaySession, paypalSdkApplePayPaymentSession);
  
  applePaySession.begin();
}
```

### Step 5: Handle Apple Pay events

Implement event handlers to process the payment through Apple Pay's workflow.

```javascript theme={null}
function setupApplePayEventHandlers(applePaySession, paypalSession) {
  // Merchant validation
  applePaySession.onvalidatemerchant = (event) => {
    paypalSession.validateMerchant({
      validationUrl: event.validationURL,
    }).then((payload) => {
      applePaySession.completeMerchantValidation(payload.merchantSession);
    }).catch((err) => {
      console.error("Merchant validation failed:", err);
      applePaySession.abort();
    });
  };

  // Payment method selection
  applePaySession.onpaymentmethodselected = () => {
    applePaySession.completePaymentMethodSelection({
      newTotal: paymentRequest.total,
    });
  };

  // Payment authorization
  applePaySession.onpaymentauthorized = async (event) => {
    try {
      // Create PayPal order
      const order = await createOrder();
      
      // Confirm order with Apple Pay token
      await paypalSession.confirmOrder({
        orderId: order.orderId,
        token: event.payment.token,
        billingContact: event.payment.billingContact,
        shippingContact: event.payment.shippingContact,
      });

      // Capture payment
      const result = await captureOrder({ orderId: order.orderId });
      
      applePaySession.completePayment({
        status: window.ApplePaySession.STATUS_SUCCESS,
      });
      
      console.log("Payment successful:", result);
    } catch (error) {
      console.error("Payment failed:", error);
      applePaySession.completePayment({
        status: window.ApplePaySession.STATUS_FAILURE,
      });
    }
  };

  // Payment cancellation
  applePaySession.oncancel = () => {
    console.log("Apple Pay cancelled");
  };
}
```

### Step 6: Add server integration

Implement server endpoints for order management.

```javascript theme={null}
// Create PayPal order
async function createOrder() {
  const response = await fetch("/paypal-api/checkout/orders/create-with-sample-data", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
  });
  const { id } = await response.json();
  return { orderId: id };
}

// Capture order
async function captureOrder({ orderId }) {
  const response = await fetch(`/paypal-api/checkout/orders/${orderId}/capture`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
  });
  return await response.json();
}
```

## Server-side requirements

Your backend needs these endpoints to support the Apple Pay integration:

* **Order creation endpoint**: Creates PayPal order and returns order ID for payment processing
* **Order capture endpoint**: Captures authorized payment and returns transaction details
* **Proper CORS and security headers**: Ensures secure communication between client and server

## Testing

Use the following steps to test your Apple Pay integration.

1. Open Safari browser on macOS or iOS device.
2. Sign into your sandbox iCloud account.
3. Add test credit cards to your Apple Pay wallet.
4. Test the complete payment flow.

## Production deployment

Deploy your Apple Pay integration to production.

1. Replace all sandbox URLs with production endpoints.
2. Update your application to use production PayPal credentials.
3. Register your production domain with Apple Pay.
4. Test the integration with a real Apple Pay setup
5. Add proper error monitoring to track payment issues

## Security considerations

* Use HTTPS in production.
* Ensure your merchant domain is valid.
* Keep domain association files current.
* Never expose client secrets in frontend code.
* Implement proper error handling.

## Troubleshooting

<table>
  <thead>
    <tr>
      <th>Issue</th>
      <th>Solution</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Button not appearing</td>

      <td>
        <ul>
          <li>Check Safari Apple Pay settings</li>
          <li>Verify domain registration</li>
          <li>Ensure HTTPS connection</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>Merchant validation fails</td>

      <td>
        <ul>
          <li>Check domain association file</li>
          <li>Verify PayPal domain registration</li>
          <li>Confirm ngrok domain in vite config</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>Payment authorization fails</td>

      <td>
        <ul>
          <li>Use sandbox iCloud account</li>
          <li>Check test credit card setup</li>
          <li>Verify server endpoints</li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

## Resources

* For more information, see the [Apple Pay HTML sample integration](https://github.com/paypal-examples/v6-web-sdk-sample-integration/tree/main/client/components/applePay/html).


# Integrate Google Pay with PayPal's JavaScript SDK v6
Source: https://docs.paypal.ai/payments/methods/digital-wallets/google-pay



Google Pay enables merchants to accept fast payments in using PayPal's Javascript SDK v6. This integration supports setup in test and production environments and provides a streamlined checkout experience for customers.

## Prerequisites

Before beginning your integration, meet these requirements:

* Create a [PayPal developer account](https://developer.paypal.com/dashboard/) and enable Google Pay in your sandbox settings.
* Enable Google Pay in your PayPal sandbox account. See [Set up your sandbox account to accept Google Pay](https://developer.paypal.com/docs/checkout/apm/google-pay/#set-up-your-sandbox-account-to-accept-google-pay) for more information.
* Set up your PayPal sandbox credentials.

> **Note:** You'll use your sandbox credentials to create a `.env` file during the **Development setup**.

## Development setup

Configure your local development environment with the required dependencies and credentials. For reference, see this [Google Pay demo](https://github.com/paypal-examples/v6-web-sdk-sample-integration/tree/main/client/components/googlepayPayments/oneTimePayment/html).

1. Install project dependencies:

```bash theme={null}
cd client/components/googlePayPayments/oneTimePayment/html
npm install
```

2. Create environment configuration:

```bash theme={null}
# .env file
PAYPAL_SANDBOX_CLIENT_ID=your_client_id
PAYPAL_SANDBOX_CLIENT_SECRET=your_client_secret
```

3. Start the development server:

```bash theme={null}
npm start
```

To load the application, see `http://localhost:3000`.

## Implementation steps

Implement Google Pay by following the detailed steps.

### Step 1: HTML structure setup

Create your basic HTML page and include the Google Pay and PayPal SDK scripts.

```html theme={null}
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>One-Time Payment - Google Pay - PayPal JavaScript SDK</title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
  </head>
  <body>
    <h1>One-Time Payment Google Pay Integration</h1>
    
    <div class="buttons-container">
      <div id="googlepay-button-container"></div>
    </div>

    <!-- Load Google Pay SDK -->
    <script src="https://pay.google.com/gp/p/js/pay.js"></script>
    <script src="app.js"></script>

    <!-- Load PayPal SDK -->
    <script
      async
      src="https://www.sandbox.paypal.com/web-sdk/v6/core"
      onload="onPayPalWebSdkLoaded()"
    ></script>
  </body>
</html>
```

### Step 2: Initialize PayPal SDK

Set up the PayPal SDK with Google Pay components once it loads.

```javascript theme={null}
async function onPayPalWebSdkLoaded() {
  try {
    // Create PayPal SDK instance with Google Pay component
    const sdkInstance = await window.paypal.createInstance({
      clientId: "YOUR_CLIENT_ID",
      components: ["googlepay-payments"],
      pageType: "checkout",
    });

    setupGooglePayButton(sdkInstance);
  } catch (error) {
    console.error(error);
  }
}
```

### Step 3: Configure Google Pay button

Create the Google Pay session and set up the payment button.

```javascript theme={null}
async function setupGooglePayButton(sdkInstance) {
  // Create Google Pay session
  const googlePaySession = sdkInstance.createGooglePayOneTimePaymentSession();
  const purchaseAmount = "10.00";

  try {
    // Initialize Google Pay client
    const paymentsClient = new google.payments.api.PaymentsClient({
      environment: "TEST", // Use "PRODUCTION" for live transactions
      paymentDataCallbacks: {
        onPaymentAuthorized: (paymentData) =>
          onPaymentAuthorized(purchaseAmount, paymentData, googlePaySession),
      },
    });

    // Get Google Pay configuration from PayPal
    const googlePayConfig = await googlePaySession.getGooglePayConfig();

    // Check if Google Pay is available
    const isReadyToPay = await paymentsClient.isReadyToPay({
      allowedPaymentMethods: googlePayConfig.allowedPaymentMethods,
      apiVersion: googlePayConfig.apiVersion,
      apiVersionMinor: googlePayConfig.apiVersionMinor,
    });

    if (isReadyToPay.result) {
      // Create and append Google Pay button
      const button = paymentsClient.createButton({
        onClick: () =>
          onGooglePayButtonClick(
            purchaseAmount,
            paymentsClient,
            googlePayConfig,
          ),
      });

      document.getElementById("googlepay-button-container").appendChild(button);
    }
  } catch (error) {
    console.error("Setup error:", error);
  }
}
```

### Step 4: Configure payment data request

Set up the Google Pay payment data request with transaction details.

```javascript theme={null}
async function getGooglePaymentDataRequest(purchaseAmount, googlePayConfig) {
  const {
    allowedPaymentMethods,
    merchantInfo,
    apiVersion,
    apiVersionMinor,
    countryCode,
  } = googlePayConfig;

  const baseRequest = {
    apiVersion,
    apiVersionMinor,
  };

  const paymentDataRequest = Object.assign({}, baseRequest);
  paymentDataRequest.allowedPaymentMethods = allowedPaymentMethods;
  paymentDataRequest.transactionInfo = getGoogleTransactionInfo(
    purchaseAmount,
    countryCode,
  );
  paymentDataRequest.merchantInfo = merchantInfo;
  paymentDataRequest.callbackIntents = ["PAYMENT_AUTHORIZATION"];

  return paymentDataRequest;
}
```

### Step 5: Set up transaction information

Define the transaction details and pricing breakdown for the Google Pay request.

```javascript theme={null}
function getGoogleTransactionInfo(purchaseAmount, countryCode) {
  const totalAmount = parseFloat(purchaseAmount);
  const subtotal = (totalAmount * 0.9).toFixed(2);
  const tax = (totalAmount * 0.1).toFixed(2);

  return {
    displayItems: [
      {
        label: "Subtotal",
        type: "SUBTOTAL",
        price: subtotal,
      },
      {
        label: "Tax",
        type: "TAX",
        price: tax,
      },
    ],
    countryCode: countryCode,
    currencyCode: "USD",
    totalPriceStatus: "FINAL",
    totalPrice: purchaseAmount,
    totalPriceLabel: "Total",
  };
}
```

### Step 6: Handle payment authorization

Process the payment authorization and complete the transaction.

```javascript theme={null}
async function onPaymentAuthorized(
  purchaseAmount,
  paymentData,
  googlePaySession,
) {
  try {
    // Create PayPal order payload
    const orderPayload = getPayPalOrderPayload(purchaseAmount);
    const id = await createOrder(orderPayload);

    // Confirm order with Google Pay payment data
    const { status } = await googlePaySession.confirmOrder({
      orderId: id,
      paymentMethodData: paymentData.paymentMethodData,
    });

    if (status !== "PAYER_ACTION_REQUIRED") {
      // Capture the order
      const orderData = await captureOrder({ orderId: id });
      console.log(JSON.stringify(orderData, null, 2));
    }

    return { transactionState: "SUCCESS" };
  } catch (err) {
    console.error("Payment authorization error:", err);
    return {
      transactionState: "ERROR",
      error: {
        message: err.message,
      },
    };
  }
}
```

### Step 7: PayPal order configuration

Configure a PayPal order with the Google Pay payment source.

```javascript theme={null}
function getPayPalOrderPayload(purchaseAmount) {
  return {
    intent: "CAPTURE",
    purchaseUnits: [
      {
        amount: {
          currencyCode: "USD",
          value: purchaseAmount,
          breakdown: {
            itemTotal: {
              currencyCode: "USD",
              value: purchaseAmount,
            },
          },
        },
      },
    ],
    paymentSource: {
      googlePay: {
        attributes: {
          verification: {
            method: "SCA_WHEN_REQUIRED",
          },
        },
      },
    },
  };
}
```

## API endpoints

The integration requires these server-side endpoints.

### Create order endpoint

```javascript theme={null}
// POST /paypal-api/checkout/orders/create
async function createOrder(orderPayload) {
  const response = await fetch("/paypal-api/checkout/orders/create", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify(orderPayload),
  });
  const { id } = await response.json();
  return id;
}
```

### Capture order endpoint

```javascript theme={null}
// POST /paypal-api/checkout/orders/{orderId}/capture
async function captureOrder({ orderId }) {
  const response = await fetch(
    `/paypal-api/checkout/orders/${orderId}/capture`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
    },
  );
  const data = await response.json();
  return data;
}
```

## Key components

<table>
  <thead>
    <tr>
      <th>Key component</th>
      <th>Purpose</th>
      <th>Details</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>PayPal SDK instance</strong></td>
      <td>Main entry point for PayPal functionality</td>

      <td>
        <ul>
          <li>Includes <code>googlepay-payments</code> component</li>
          <li>Authenticate with your client ID</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td><strong>Google Pay session</strong></td>
      <td>Manages Google Pay payment flow</td>

      <td>
        <ul>
          <li>Provides Google Pay–specific settings</li>
          <li>Handles order confirmation and capture</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td><strong>Google Pay client</strong></td>
      <td>Interface with Google Pay API</td>

      <td>
        <ul>
          <li>Set to <code>TEST</code> for sandbox</li>
          <li>Set to <code>PRODUCTION</code> for live</li>
          <li>Handles payment authorization callbacks</li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

## Security considerations

* Never expose client secrets in frontend code.
* Always process payments through PayPal’s servers.
* Use HTTPS in production.

## Error handling

* Catch and log errors in both client and server code.
* Avoid logging sensitive data.
* Show clear, user-friendly error messages.

## Testing

* Run transactions with different payment amounts.
* Verify order creation and capture flows.
* Simulate error scenarios and edge cases.

## Next steps

1. Configure your production credentials and endpoints.
2. Add 3D Secure (3DS) support if required.
3. Extend your integration to support multiple currencies.
4. Strengthen error handling and customer messaging.
5. Build a complete automated test suite.

## Resources

* [One-time payments Google Pay sample integration](https://github.com/paypal-examples/v6-web-sdk-sample-integration)
* [Integrate Google Pay with the PayPal Javascript SDK v5](https://developer.paypal.com/docs/checkout/apm/google-pay/)
* [Google Pay Web API](https://developers.google.com/pay/api/web/overview)
* [PayPal Developer Dashboard](https://developer.paypal.com/dashboard/)


# Analytics logging
Source: https://docs.paypal.ai/payments/methods/pay-later/analytics



Use callback functions in the PayPal Messages SDK to monitor key user interactions and rendering events for your <a href="https://docs.paypal.ai/payments/methods/pay-later/overview">Pay Later</a> integration. The data you collect about critical events and user interactions helps optimize your payment flow.

The following example renders a message using a JavaScript configuration. This example includes `console.log` statements in many of the configuration callback functions and events. The functions in this example log in the console when an event occurs.

For details about how to log when a custom event or hook occurs, see your analytics platform's documentation. You can put that code in the function body of the event hook properties for the Fetch Content or Learn More configuration objects. For more information about these configuration objects, see [Get started with Pay Later](/payments/methods/pay-later/get-started).

```html theme={null}
<head>
  <script src="https://www.paypal.com/web-sdk/v6/core"></script>
  <script src="https://www.paypal.com/web-sdk/v6/paypal-messages"></script>
</head>
<body>
  <paypal-message></paypal-message>
  <script>
    const sdkInstance = await window.paypal.createInstance({ clientId: "YOUR_CLIENT_ID" });
    const messagesInstance = sdkInstance.createPayPalMessages();
    const content = await messagesInstance.fetchContent({
      amount: "300.00",
      currencyCode: "USD",
      logoType: "MONOGRAM",
      textColor: "MONOCHROME",
      onTemplateReady: (content) => {
        // ANALYTICS LOG EXAMPLE
        console.log("Cached Template Rendered");
        messageElement.setContent(content);
      },
      onContentReady: (content) => {
        // ANALYTICS LOG EXAMPLE
        console.log("Fetched Content Rendered");
        messageElement.setContent(content);
      },
    });
    function triggerAmountUpdate(amount) {
      content.update({ amount });
    }
    const learnMore = await messagesInstance.createLearnMore({
      onShow: (content) => {
        // ANALYTICS LOG EXAMPLE
        console.log("Learn More Shown");
      },
      onApply: (content) => {
        // ANALYTICS LOG EXAMPLE
        console.log("Learn More Apply");
      },
      onClose: (content) => {
        // ANALYTICS LOG EXAMPLE
        console.log("Learn More Closed");
      },
    });
    messageElement.addEventListener("paypal-message-click", (event) => {
      event.preventDefault();
      learnMore.open(event.detail.config);
      // ANALYTICS LOG EXAMPLE
      console.log("Message Learn More Clicked");
    });
  </script>
</body>
```


# Get started with Pay Later
Source: https://docs.paypal.ai/payments/methods/pay-later/get-started



The PayPal Messages SDK enables you to display Pay Later messaging on your website, offering your customers flexible payment options, like Pay in 4 and Pay Monthly. For more information about Pay Later offers, including eligibility, see <a href="https://docs.paypal.ai/payments/methods/pay-later/overview">Pay Later</a>.

This JavaScript-based SDK provides a streamlined way to render customizable financing messages at strategic points in your customer journey.

With minimal code integration, you can:

* Display dynamic payment messaging that updates based on cart values.
* Customize messaging to match your site's design with various logo types, positions, and color schemes.
* Implement detailed analytics tracking.
* Support multiple integration patterns (HTML, JavaScript, or hybrid) based on your technical requirements.

Rendering a Pay Later message requires these basic steps. You can configure different options at each step, as needed.

1. [Load the SDK.](#load-the-messages-component)
2. [Add `<paypal-message>` components to the page.](#the-paypal-message-sdk-component)
3. [Initialize the PayPal Messages instance.](#javascript-interface)

For examples of some of the different configuration options, see [Message configuration examples](#message-configuration-examples).

## Configuration overview

There are 3 primary ways to add and configure messages for your website:

* **HTML configuration:** An HTML configuration uses web component  attributes and minimal JavaScript to load and render messages to the page. The only JavaScript that you need for this integration is to initialize the SDK and create a PayPal Messages instance.
* **JavaScript configuration:** A JavaScript configuration uses minimal HTML and relies on JavaScript to configure and load message content. The only HTML that you need for this integration is to add the  `paypal-messages` web component to your page.
* **Hybrid (HTML with JavaScript) configuration:** You can use a hybrid configuration (HTML and JavaScript) for advanced message options. This approach fetches and sets content using both HTML attributes and JavaScript options.

The following sections of this page explain more about how to use these approaches, including lists of attributes and other options that you can use. For examples, see [Message configuration examples](#message-configuration-examples).

For more information about the JavaScript SDK from PayPal, see <a href="https://docs.paypal.ai/payments/methods/paypal/sdk/js/v6/paypal-checkout">Integrate PayPal Checkout with PayPal's JavaScript SDK v6</a>.

## Load the messages component

There are two ways to load the `messages` component of the v6 SDK:

* Include an HTML `script` tag with the v6 SDK core script.
* Load the component through JavaScript when you create the v6 SDK instance.

<CodeGroup>
  ```html title="HTML" theme={null}
  <head>
    <!-- Load the v6 SDK core script -->
    <script src="https://www.paypal.com/web-sdk/v6/core"></script>
    <!-- Load the PayPal Messages script -->
    <script src="https://www.paypal.com/web-sdk/v6/paypal-messages"></script>
  </head>
  ```

  ```html title="Hybrid (HTML with JavaScript)" theme={null}
  // HTML 
  <head>
    <!-- Load just the v6 SDK core script -->
    <script src="https://www.paypal.com/web-sdk/v6/core"></script>
  </head>
  ```

  ```javascript theme={null}
  // Instantiate the SDK Instance
  const sdkInstance = await window.paypal.createInstance({
    clientId: "YOUR_CLIENT_ID",
    // Include paypal-messages in the components to load
    components: ["paypal-messages"],
  });
  ```
</CodeGroup>

## The paypal-message SDK component

The `paypal-message` SDK component utilizes a custom Lit web component, `<paypal-messages>`, to render Pay Later messages on a webpage. [Web component methods](#web-component-methods) and [Web component attributes](#web-component-attributes) tell you more about how to use this SDK component.

### Web component methods

Accessing the `<paypal-messages>` web component using JavaScript exposes some methods, which the following table describes.

| Method                   | Description                                                                                                       | Arguments                                                               | Return value                                                                       |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `setContent`             | An exposed method to set the content of the message component                                                     | Message content that the `payPalMessages.fetchContent()` method returns | `void`                                                                             |
| `getFetchContentOptions` | Extracts and returns the `fetchContent` configuration options from the component's HTML attributes and properties | None                                                                    | A content object that it constructs from the HTML attributes for the web component |

### Web component attributes

The `<paypal-messages>` web component accepts a variety of attributes to control how a message looks and what it does. Some options are available only through the `fetchContent` method. For more information about using  `fetchContent`, see [Fetch content options](#fetch-content-options).

| HTML attribute      | Description                                                                                                                                                                                                                                                                                                           | Default value |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `amount`            | Number string with as many as 2 decimal places to represent dollar amounts. <br /><br />Set using JavaScript as a fetch content option. <br /><br />Example inputs: <br /> `"50"` → \$50.00 <br /> `"50.5"` → \$50.50                                                                                                 | None          |
| `auto-bootstrap`    | If `true`, PayPal's data layer (`PayPalMessages`) automatically picks up this component to fetch content. <br /><br />If `false`, you must use `fetchContent`.                                                                                                                                                        | `false`       |
| `currency-code`     | A string value of length 3 to represent the currency code of the message. <br /><br />Set using JavaScript as a PayPal messages option and a fetch content option.                                                                                                                                                    | None          |
| `logo-position`     | A string value that indicates where to place the message branding. <br /><br />Set using JavaScript as a fetch content option. <br /><br />Options: <br /> `INLINE` <br /> `LEFT` <br /> `RIGHT` <br /> `TOP`                                                                                                         | `LEFT`        |
| `logo-type`         | A string value that indicates the desired branding style. <br /><br /> Set using JavaScript as a fetch content option. <br /><br />Options: <br />`MONOGRAM`: If `logo-type` is `MONOGRAM`, `logo-position` must be `LEFT`. <br />`TEXT`: If `logo-type` is `TEXT`, `logo-position` must be `INLINE`.<br />`WORDMARK` | `WORDMARK`    |
| `presentation-mode` | A string value that indicates how to load a message’s Learn More presentation. <br /><br />Set using JavaScript as a [Learn More option](#learn-more-options). <br /><br />Options: <br />`AUTO` <br />`MODAL` <br />`POPUP` <br />`REDIRECT`                                                                         | `AUTO`        |
| `text-color`        | A string value that indicates the message color to use. <br /><br />Set using JavaScript as a fetch content option. <br /><br />Options: <br />`BLACK` <br />`MONOCHROME` <br />`WHITE`                                                                                                                               | `BLACK`       |

## JavaScript interface

Create a PayPal Messages instance after you create a v6 SDK instance. The following code snippet is the minimum JavaScript requirement for rendering a message.

```javascript theme={null}
const messagesInstance = sdkInstance.createPayPalMessages();
```

The following sections describe the different methods and options that are available:

* [Instance methods](#instance-methods)
* [Instance options](#instance-options)
* [Fetch content options](#fetch-content-options)
* [Learn More options](#learn-more-options)

### Instance methods

A PayPal Messages instance has 2 primary, exposed methods. You can use these methods to configure message content and to present Learn More links.

| Method            | Description                                      | Arguments                                                                    |
| ----------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- |
| `fetchContent`    | Fetch message content from the server.           | An optional object of Fetch Content Options                                  |
| `createLearnMore` | Initialize and return a Learn More presentation. | An optional object of [Learn More presentation options](#learn-more-options) |

### Instance options

When you initialize PayPal Messages with `createPayPalMessages`, you can pass global configuration options. These options apply to content requests for each message that you configure on this page. For example, if the page contains multiple message elements, and each one has a `currency-code` attribute, then you can configure `currencyCode` in the `createPayPalMessages` call, so you don't have to configure it in each of the elements.

| Option             | Description                                                                                                                                                            | Default value |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `currencyCode`     | 2-digit string that is the currency code for the buyer's country <br /><br />Set using JavaScript as a fetch content option or using HTML as a web component attribute | None          |
| `shopperSessionId` | A string that represents the shopper's session ID in this basic format: `6B29FC40-CA47-1067-B21D-00DD010462DA`                                                         |               |

### Fetch content options

When you use the `fetchContent` method, you can pass a variety of options to configure the content of a message.

| Option            | Description                                                                                                                                                                                                                                                                                                   | Default value |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `amount`          | Number string with as many as 2 decimal places to represent dollar amounts <br /><br />Set using HTML as a web component attribute <br /><br />Example inputs: <br />`"50"` → \$50.00 <br />`"50.5"` → \$50.50 <br /> `"50.55"` → \$50.55                                                                     | None          |
| `currencyCode`    | 3-digit string that is the currency code for message <br /><br />Set using JavaScript as a fetch content option or using HTML as a web component attribute                                                                                                                                                    | None          |
| `logoPosition`    | A string value that indicates where to place the message branding. <br /><br />Set using HTML as a web component attribute. <br /><br />Options: <br />`INLINE` <br />`LEFT` <br />`RIGHT` <br />`TOP`                                                                                                        | `LEFT`        |
| `logoType`        | A string value that indicates the desired branding style. <br /><br />Set using HTML as a web component attribute. <br /><br />Options: <br />`MONOGRAM`: If `logoType` is `MONOGRAM`, `logoPosition` must be `LEFT`. <br />`TEXT`: If `logoType` is `TEXT`, `logoPosition` must be `INLINE`.<br />`WORDMARK` | `WORDMARK`    |
| `onContentReady`  | A callback to send when content is received from the server during a call to the fetch content method. This callback takes precedence over `onReady`.                                                                                                                                                         | None          |
| `onReady`         | A callback to send when content is received from the fetch content method. This could be content from the local cache or from a server. <br /><br />If you omit `onContentReady` or `onTemplateReady`, the system uses this callback.                                                                         |               |
| `onTemplateReady` | A callback to send when content is received from the local cache during a call to the fetch content method. This callback takes precedence over `onReady`.                                                                                                                                                    | None          |
| `textColor`       | A string value that indicates the message color to use. <br /><br />Set using HTML as a web content attribute. <br /><br />Options: <br />`BLACK` <br />`MONOCHROME` <br />`WHITE`                                                                                                                            | `BLACK`       |

### Learn More options

Learn More links typically follow Pay Later messages, and they link to additional information about available Pay Later offers. These links can appear as modals, popups, or redirects to a new tab.

When you call the `createLearnMore` method, you can use the following options to configure the Learn More presentation.

| Option             | Description                                                                                                                                                                                                                                                  | Default value |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
| `amount`           | Number string with as many as 2 decimal places to represent dollar amounts. <br /><br />Set using JavaScript as a fetch content option or using HTML as a web content attribute. <br /><br />Example inputs: <br />`"50"` → \$50.00 <br />`"50.5"` → \$50.50 | None          |
| `presentationMode` | A string value that indicates how to load a message’s Learn More presentation. <br /><br />Set using HTML as a web content attribute. <br /><br />Options: <br />`AUTO` <br />`MODAL` <br />`POPUP` <br />`REDIRECT`                                         | `AUTO`        |
| `onApply`          | A callback to send when the user selects the Apply button or link in a Learn More presentation.                                                                                                                                                              | None          |
| `onCalculate`      | A callback to send when the user the user enters a value in the Amount input field in a Learn More presentation.                                                                                                                                             | None          |
| `onShow`           | A callback to send when a Learn More presentation is shown.                                                                                                                                                                                                  | None          |
| `onClose`          | A callback to send when a Learn More presentation is closed.                                                                                                                                                                                                 | None          |

## SDK instance options

PayPal Messages also uses some top-level SDK instance options. The following part of your code provides these options.

```javascript lines theme={null}
const sdkInstance = await window.paypal.createInstance({
  // SDK Instance Options
});
```

This table describes the options that you can use for configuration at this level.

| Option                 | Description                                                                                                                                                                                                                                                     | Default value |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `clientId`             | **Recommended.** Your PayPal [client ID](https://developer.paypal.com/docs/api/overview/#get-your-client-id-and-secret). <br /><br />**Note:** You cannot use a client token and a client ID. You must choose 1. `clientId` is preferred for most integrations. | None          |
| `clientToken`          | A unique identifier for merchant authentication.                                                                                                                                                                                                                | None          |
| `pageType`             | A string that represents the page on which the message appears. <br /><br />Options: <br />`cart` <br />`checkout` <br />`home` <br />`mini-cart` <br />`product` <br />`product-details` <br />`product-listing` <br />`search-results`                        | None          |
| `partnerAttributionId` | An identifier for partner integrations.                                                                                                                                                                                                                         | None          |
| `shopperSessionId`     | A string that represents the shopper's session ID in this basic format: `6B29FC40-CA47-1067-B21D-00DD010462DA`                                                                                                                                                  | None          |

## Cascading Style Sheet (CSS) properties

For styling parts of messages, you can use 2 custom CSS properties.

| Option                        | Description                                                                                                                                                                                                                                                                                                | Default value |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `--paypal-message-font-size`  | Specify the font size for the message in `px` from `10px` to `16px`. If you specify a value that is outside of this range, the message will use the closest value that is in this range. For example, if you try to use `4px`, the message uses `10px`. If you try to use `24px`, the message uses `16px`. | `14px`        |
| `--paypal-message-text-align` | Alignment of the message: <br />`left` <br />`right` <br />`center`                                                                                                                                                                                                                                        | `left`        |

## Message configuration examples

These examples show how the different configurations work to create a Pay Later message with a Learn More link.

For examples of some of the different configuration options, see [Message configuration examples](#message-configuration-examples).

<Tabs>
  <Tab title="HTML">
    The HTML configuration uses web component HTML attributes and minimal JavaScript to load and render messages to a page. The only JavaScript that you need for this integration is to initialize the SDK and create a PayPal Messages instance.

    1. To use v6 SDK messages, include 2 scripts on your site: the core SDK package and the PayPal messages SDK package.

    ```html theme={null}
    <head>
      <script src="https://www.paypal.com/web-sdk/v6/core"></script>
      <script src="https://www.paypal.com/web-sdk/v6/paypal-messages"></script>
    </head>
    ```

    2. Add the `<paypal-message>` web component to your page. If you use the `auto-bootstrap` attribute, PayPal's data layer (`PayPalMessages`) automatically picks up this component to fetch content. If you do not use `auto-bootstrap`, you must use the `fetchContent` method to fetch and set content.

    ```html theme={null}
    <paypal-message
      amount="300.00"
      currency-code="USD"
      logo-type="MONOGRAM"
      text-color="MONOCHROME"
    ></paypal-message>
    ```

    3. Create the core SDK instance using your client ID, and instantiate PayPal Messages.

    ```javascript lines theme={null}
    // Add the necessary JavaScript to instantiate PayPal Messages: 

    // Option 1: Using clientId (no server-side token generation required) 
      const sdkInstance = await window.paypal.createInstance({ 
            clientId: "YOUR_CLIENT_ID" 
         }); 

    // Option 2: Using clientToken (requires server-side token generation) 
      const sdkInstance = await window.paypal.createInstance({ clientToken }); 

    const messagesInstance = sdkInstance.createPayPalMessages(); 
    ```

    > **Note:** Canadian merchants may optionally pass the locale parameter to control language behavior. Use `locale=fr-CA` on your French site and `locale=en-CA` on your English site.
    > If the customer does not pass the `locale` parameter, the customer's browser language determines the locale. If the browser language is `fr-CA`, the message renders in French `(fr-CA)`. For all other cases, messages render in English `(en-CA)`.

    ```javascript theme={null}
    const sdkInstance = await window.paypal.createInstance({
          clientToken,
          locale: "fr-CA"
        });
    }
    ```

    4. Add a way to update the PayPal Message `amount`. This code sample shows how to update the `amount` attribute on the PayPal Messages web component.

    ```javascript theme={null}
    function triggerAmountUpdate(amount) {
      const messageElement = document.querySelector('paypal-message');
      messageElement.setAttribute('amount', amount);
    }
    ```

    When you put it all together, this is the full code sample.

    ```html lines expandable theme={null}
    <head> 
      <script src="https://www.paypal.com/web-sdk/v6/core"></script> 
      <script src="https://www.paypal.com/web-sdk/v6/paypal-messages"></script> 
    </head> 
    <body> 
      <paypal-message 
        amount="300.00" 
        currency-code="USD" 
        logo-type="MONOGRAM" 
        text-color="MONOCHROME" 
      ></paypal-message> 
      <script> 
          // Option 1: Using clientId (no server-side token generation required) 
            const sdkInstance = await window.paypal.createInstance({ 
                clientId: "YOUR_CLIENT_ID" 
            }); 

          // Option 2: Using clientToken (requires server-side token generation) 
            const sdkInstance = await window.paypal.createInstance({ clientToken }); 

        const messagesInstance = sdkInstance.createPayPalMessages(); 
        function triggerAmountUpdate(amount) { 
          const messageElement = document.querySelector('paypal-message'); 
          messageElement.setAttribute('amount', amount); 
        } 
      </script> 
    </body> 
    ```
  </Tab>

  <Tab title="JavaScript">
    The JavaScript configuration option uses minimal HTML and relies on JavaScript to configure and load message content. The only HTML that you need for this integration is to add the PayPal Message web component to a page.

    1. To use v6 SDK messages, include 2 scripts on your site: the core SDK package and the PayPal messages SDK package.

    ```html theme={null}
    <head>
      <script src="https://www.paypal.com/web-sdk/v6/core"></script>
      <script src="https://www.paypal.com/web-sdk/v6/paypal-messages"></script>
    </head>
    ```

    2. Add the `<paypal-message>` web component to your page. If you use the `auto-bootstrap` attribute, PayPal's data layer (`PayPalMessages`) automatically picks up this component to fetch content. If you do not use `auto-bootstrap`, you must use the `fetchContent` method to fetch and set content.

    ```html lines theme={null}
      <paypal-message></paypal-message>
    ```

    3. Create the core SDK instance using your client ID, and instantiate PayPal Messages using JavaScript.

    ```javascript lines theme={null}
        const sdkInstance = await window.paypal.createInstance({ clientToken });
        const messagesInstance = sdkInstance.createPayPalMessages();
    ```

    4. Add JavaScript to fetch and set the message content. To fetch content, use the `fetchContent` method. This configuration does not set message content automatically. Instead, use the `onReady` callback with the `setContent()` method and `fetchContent`.

    ```javascript lines theme={null}
    const messageElement = document.querySelector('paypal-message');
    const content = await messagesInstance.fetchContent({
      amount: "300.00",
      currencyCode: "USD",
      logoType: "MONOGRAM",
      textColor: "MONOCHROME",
      onReady: (content) => messageElement.setContent(content),
    });
    ```

    5. Add a way to update the PayPal Message `amount`. This code sample shows how to update the `amount` through the `update` callback for the `fetchContent` response.

    ```javascript lines theme={null}
    function triggerAmountUpdate(amount) {
      content.update({ amount });
    }
    ```

    When you put it all together, this is the full code sample.

    ```html lines expandable theme={null}
    // Follow the Message JS Config or HTML Config Steps and add a message to your page 
    <head> 
      <script src="https://www.paypal.com/web-sdk/v6/core"></script> 
      <script src="https://www.paypal.com/web-sdk/v6/paypal-messages"></script> 
    </head> 
    <body> 
      <paypal-message></paypal-message> 
      <script> 
        // Option 1: Using clientId  
          const sdkInstance = await window.paypal.createInstance({ 
          clientId: "YOUR_CLIENT_ID" 
        }); 
        
        // Option 2: Using clientToken  
          const sdkInstance = await window.paypal.createInstance({ clientToken }); 

        const messagesInstance = sdkInstance.createPayPalMessages(); 
        const content = await messagesInstance.fetchContent({ 
          amount: "300.00", 
          currencyCode: "USD", 
          logoType: "MONOGRAM", 
          textColor: "MONOCHROME", 
          onReady: (content) => messageElement.setContent(content), 
        }); 

        function triggerAmountUpdate(amount) { 
          content.update({ amount }); 
       } 

        // Create a Learn More Instance. Include an option to change the presentation mode 
          const learnMore = await messagesInstance.createLearnMore({ 
            presentationMode: "POPUP", 
          }); 

        // Handle the Message Click Event 
        // We need to listen to the message clicked event in order to open the learn more modal when clicked 
          messageElement.addEventListener("paypal-message-click", (event) => { 
            event.preventDefault(); 
            learnMore.open(event.detail.config); 
          }); 

        </script> 
      </body> 
    ```
  </Tab>

  <Tab title="Hybrid (HTML with JavaScript)">
    You can combine the HTML and JavaScript configuration patterns for more advanced message placements. We call this a hybrid configuration. This approach fetches and sets content using both HTML attributes and JavaScript options.

    1. To use v6 SDK messages, you eventually include two scripts on your site: the core SDK package and the PayPal `paypal-messages` SDK package. Notice that we do not load the messages script in this step.  We load it in a later step.

    ```javascript lines theme={null}
    <head>
      <script src="https://www.paypal.com/web-sdk/v6/core"></script>
    </head>
    ```

    2. Include the official `<paypal-messages>` web component in your page’s HTML. Add an attribute to configure the amount.

    ```html theme={null}
    <paypal-message amount="300.00"></paypal-message>
    ```

    3. Create the core SDK instance using your client ID, load `messages`, and then instantiate PayPal Messages. We can also set the currency code at the PayPal Messages instance level, instead of on the component attributes or in the `fetchContent` options.

    ```javascript lines theme={null}
    const sdkInstance = await window.paypal.createInstance({
      clientId: "YOUR_CLIENT_ID",
      components: ["paypal-messages"],
    });
    const messagesInstance = sdkInstance.createPayPalMessages({
      currencyCode: "USD",
    });
    ```

    4. Add JavaScript to fetch and set message content. This configuration does not set message content automatically. We can use the `getFetchContentOptions()` method for the web component to extend the `fetchContent` options. This gets the `amount` attribute and includes it in the `fetchContent` request. It also includes the default `onReady` callback.

    ```javascript lines theme={null}
    const messageElement = document.querySelector('paypal-message');
    const content = await messagesInstance.fetchContent({
      ...messageElement.getFetchContentOptions(),
      currencyCode: "USD",
      logoType: "MONOGRAM",
      textColor: "MONOCHROME",
    });
    ```

    5. Add a way to update the PayPal Message `amount`. This code sample shows how to update the `amount` through the `update` callback for the `fetchContent` response.

    ```javascript lines theme={null}
    function triggerAmountUpdate(amount) {
      messageElement.setAttribute('amount', amount);
    }
    ```

    When you put it all together, this is the full code sample.

    ```html lines expandable theme={null}
    <head>
      <script src="https://www.paypal.com/web-sdk/v6/core"></script>
    </head>
    <body>
      <paypal-message amount="300.00"></paypal-message>
      <script>
        const sdkInstance = await window.paypal.createInstance({
          clientId: "YOUR_CLIENT_ID",
          components: ["paypal-messages"],
        });
        const messagesInstance = sdkInstance.createPayPalMessages({
          currencyCode: "USD",
        });
        const content = await messagesInstance.fetchContent({
          ...messageElement.getFetchContentOptions(),
          currencyCode: "USD",
          logoType: "MONOGRAM",
          textColor: "MONOCHROME",
        });
        function triggerAmountUpdate(amount) {
          messageElement.setAttribute('amount', amount);
        }
      </script>
    </body>
    ```
  </Tab>
</Tabs>

### Message styling

You can use custom CSS properties and change the logo type and text colors to customize the style of a message.

> **Note:** PayPal Debit Card and PayPal Cashback Mastercard are incompatible with the `INLINE` logo position. If you use `INLINE` for the logo position for these payment methods, messages use the default value of `LEFT` instead.

The following examples show some ways to use these styling options.

<CodeGroup>
  ```html lines expandable title="Right-aligned, 16px, top logo" theme={null}
  // Add a message to your page using any of the message configuration patterns.
  <head>
    <script src="https://www.paypal.com/web-sdk/v6/core"></script>
    <script src="https://www.paypal.com/web-sdk/v6/paypal-messages"></script>
  </head>
  <body>

  // Add CSS
    <style>
      --paypal-message-font-size: 16px;
      --paypal-message-text-align: right;
    </style>

  // Add the logo configuration
    <paypal-message
      auto-bootstrap
      amount="300.00"
      currency-code="USD"
      logo-position="TOP"
    ></paypal-message>
    <script>
      const sdkInstance = await window.paypal.createInstance({ clientId: "YOUR_CLIENT_ID" });
      const messagesInstance = sdkInstance.createPayPalMessages();
      function triggerAmountUpdate(amount) {
        const messageElement = document.querySelector('paypal-message');
        messageElement.setAttribute('amount', amount);
      }
    </script>
  </body>
  ```

  ```html lines expandable title="Centered, 10px, inline logo" theme={null}
  // Add a message to your page using any of the message configuration patterns
  <head>
    <script src="https://www.paypal.com/web-sdk/v6/core"></script>
    <script src="https://www.paypal.com/web-sdk/v6/paypal-messages"></script>
  </head>
  <body>

  // Add CSS
    <style>
      --paypal-message-font-size: 10px;
      --paypal-message-text-align: center;
    </style>

  // Add Logo Configuration
    <paypal-message
      auto-bootstrap
      amount="300.00"
      currency-code="USD"
      logo-type="TEXT"
    ></paypal-message>
    <script>
      const sdkInstance = await window.paypal.createInstance({ clientId: "YOUR_CLIENT_ID" });
      const messagesInstance = sdkInstance.createPayPalMessages();
      function triggerAmountUpdate(amount) {
        const messageElement = document.querySelector('paypal-message');
        messageElement.setAttribute('amount', amount);
      }
    </script>
  </body>
  ```
</CodeGroup>

### Learn More configuration patterns

The message configuration patterns in [Message styling](#message-styling) use the default Learn More presentation. You can use JavaScript to customize these presentations.

The following code example shows how to customize a specific PayPal message's Learn More presentation that opens when a user selects it. This sample also adds an event listener to the `paypal-message-click` event.

```html lines expandable theme={null}
// Follow the Message JS Config or HTML Config Steps and add a message to your page
<head>
  <script src="https://www.paypal.com/web-sdk/v6/core"></script>
  <script src="https://www.paypal.com/web-sdk/v6/paypal-messages"></script>
</head>
<body>
  <paypal-message></paypal-message>
  <script>
    const sdkInstance = await window.paypal.createInstance({ clientId: "YOUR_CLIENT_ID" });
    const messagesInstance = sdkInstance.createPayPalMessages();
    const content = await messagesInstance.fetchContent({
      amount: "300.00",
      currencyCode: "USD",
      logoType: "MONOGRAM",
      textColor: "MONOCHROME",
      onReady: (content) => messageElement.setContent(content),
    });
    function triggerAmountUpdate(amount) {
      content.update({ amount });
    }

// Create a Learn More Instance. Include an option to change the presentation mode
    const learnMore = await messagesInstance.createLearnMore({
      presentationMode: "POPUP",
    });

// Handle the Message Click Event
// We need to listen to the message clicked event in order to open the learn more modal when clicked. 
    messageElement.addEventListener("paypal-message-click", (event) => {
      event.preventDefault();
      learnMore.open(event.detail.config);
    });
  </script>
</body>
```

## Pay Later message examples

Using the options that this page describes, you can create a variety of Pay Later message styles. The following examples show some of the different styles that you can create.

| Description                                                                 | Settings                                                                              | Example                                                                                                          |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Monogram                                                                    | `logoType: "MONOGRAM"`                                                                | <img alt="PayPal monogram message example" />                                                                    |
| Monochrome monogram                                                         | `logotype: "MONOGRAM"` <br />`textColor: "MONOCHROME"`                                | <img alt="PayPal monochrome monogram message example" />                                                         |
| White monogram                                                              | `logoType: "MONOGRAM"` <br />`textColor: "WHITE"`                                     | <img alt="PayPal white monogram message example" />                                                              |
| Monogram and PayPal wordmark                                                | `logoType: "WORDMARK"`                                                                | <img alt="PayPal monogram and PayPal wordmark message example" />                                                |
| Monochrome monogram and monochrome wordmark                                 | `logoType: "WORDMARK"` <br />`textColor: "MONOCHROME"`                                | <img alt="PayPal monochrome monogram and monochrome wordmark message example" />                                 |
| White monogram and white wordmark                                           | `logoType: "WORDMARK"` <br />`textColor: "WHITE"`                                     | <img alt="PayPal white monogram and white wordmark message example" />                                           |
| Inline wordmark                                                             | `logoPosition: "INLINE"` <br />`logoType: "WORDMARK"`                                 | <img alt="PayPal inline wordmark message example" />                                                             |
| Inline monochrome wordmark                                                  | `logoPosition: "INLINE"` <br />`logoType: "WORDMARK"` <br />`textColor: "MONOCHROME"` | <img alt="PayPal inline monochrome wordmark message example" />                                                  |
| Inline white wordmark                                                       | `logoPosition: "INLINE"` <br />`logoType: "WORDMARK"` <br />`textColor: "WHITE"`      | <img alt="PayPal inline white wordmark message example" />                                                       |
| Text                                                                        | `logoType: "TEXT"`                                                                    | <img alt="PayPal text message example" />                                                                        |
| White text                                                                  | `logoType: "TEXT"` <br />`textColor: "WHITE"`                                         | <img alt="PayPal white text message example" />                                                                  |
| Monogram and credit wordmark                                                | `logoType: "MONOGRAM"`                                                                | <img alt="PayPal monogram and credit wordmark message example" />                                                |
| Monochrome monogram and credit monochrome wordmark                          | `logoType: "MONOGRAM"` <br />`textColor: "MONOCHROME"`                                | <img alt="PayPal monochrome monogram and credit monochrome wordmark message example" />                          |
| White monogram and white credit wordmark                                    | `logoType: "MONOGRAM"` <br />`textColor: "WHITE"`                                     | <img alt="PayPal white monogram and white credit wordmark message example" />                                    |
| Monogram wordmark and credit wordmark                                       | `logoType: "WORDMARK"`                                                                | <img alt="PayPal monogram wordmark and credit wordmark message example" />                                       |
| Monochrome monogram and monochrome wordmark with monochrome credit wordmark | `logoType: "WORDMARK"` <br />`textColor: "MONOCHROME"`                                | <img alt="PayPal monochrome monogram and monochrome wordmark with monochrome credit wordmark message example" /> |
| White monogram with white wordmark and white credit wordmark                | `logoType: "WORDMARK"` <br />`textColor: "WHITE"`                                     | <img alt="PayPal white monogram with white wordmark and white credit wordmark message example" />                |
| Inline wordmark and credit wordmark                                         | `logoPosition: "INLINE"` <br />`logoType: "WORDMARK"`                                 | <img alt="PayPal inline wordmark and credit wordmark message example" />                                         |
| Inline monochrome wordmark and monochrome credit wordmark                   | `logoPosition: "INLINE"` <br />`logoType: "WORDMARK"` <br />`textColor: "MONOCHROME"` | <img alt="PayPal inline monochrome wordmark and monochrome credit wordmark message example" />                   |
| Inline white wordmark and white credit wordmark                             | `logoPosition: "INLINE"` <br />`logoType: "WORDMARK"` <br />`textColor: "WHITE"`      | <img alt="PayPal inline white wordmark and white credit wordmark message example" />                             |
| Credit text                                                                 | `logoType: "TEXT"`                                                                    | <img alt="PayPal text credit message example" />                                                                 |
| White credit text                                                           | `logoType: "TEXT"` <br />`textColor: "WHITE"`                                         | <img alt="PayPal white text credit message example" />                                                           |


# Pay Later
Source: https://docs.paypal.ai/payments/methods/pay-later/overview



PayPal offers special financing options that payers can use to buy now and pay later, while merchants get paid up front. Specific Pay Later offers differ by country.

The following illustration shows the basic user experience with Pay Later in the US.

![Image of 3 Pay Later screens on mobile apps. Step 1 shows that a Pay Later option is available for the user to buy some headphones. Step 2 shows the customer choosing between monthly and Pay in 4 options for Pay Later. In step 3, the user sees a screen that describes the Pay in 4 payment schedule. The description of this step adds that PayPal handles the payment from here and that the merchant gets paid up front and in full.](https://www.paypalobjects.com/ppdevdocs/PL.png?quality=75\&width=1500\&format=webp\&auto=webp\&strip=1)

To add Pay Later offers to an integration with a third-party commerce platform, see <a href="https://developer.paypal.com/docs/checkout/pay-later/us/commerce-platforms/">Commerce Platforms</a>.

For information about how you can use PayPal's JavaScript SDK for a low-code Pay Later integration, see <a href="https://docs.paypal.ai/payments/methods/pay-later/get-started/">Get started with Pay Later</a>.

## Features

With Pay Later, you can get:

* **Increased conversion:** Adding "buy now, pay later" messaging to your site can improve conversion, attract new customers, and increase order values.
* **Dynamic messages:** You can show your customers a Pay Later offer that is based on the contents of their shopping cart.
* **Multiple touch points:** Add messaging throughout your site such as on product pages, the shopping cart, and checkout pages.

## Country-specific details

For information about country-specific Pay Later offers, select a tab.

<Tabs>
  <Tab title="United States">
    PayPal offers special financing options that payers can use to buy now and pay later, while merchants get paid upfront. For more information about Pay Later, see <a href="https://www.paypal.com/us/digital-wallet/ways-to-pay/buy-now-pay-later?_ga=2.37466658.365520210.1755702720-1032254505.1740765755">Buy now, pay later</a>.

    | Product     | Number of payments | Due                      | Purchase amount  |
    | ----------- | ------------------ | ------------------------ | ---------------- |
    | Pay in 4    | 4                  | Every 2 weeks (biweekly) | \$30 to \$1,500  |
    | Pay Monthly | 3, 6, 12, or 24    | Monthly                  | \$49 to \$10,000 |

    ![Example of Pay Later messaging on product pages.](https://www.paypalobjects.com/marketing/web23/us/en/quantum-leap/smb/installment/hero_size-tablet-up-v2.png?quality=75\&width=1500\&format=webp\&auto=webp\&strip=1)

    **Eligibility**

    You're eligible to integrate Pay Later offers in the US if you meet all of the following requirements:

    * Are a US-based PayPal merchant.
    * Have a US-facing website.
    * Transact in US dollars (USD).
    * Have a one-time payment integration, and Pay Later options are available through PayPal checkout.
    * Abide by the <a href="https://www.paypal.com/us/legalhub/paypal/pay-later-messaging-tnc?locale.x=en_US&_ga=2.230264284.1105075193.1757947850-1032254505.1740765755">Pay Later Messaging Center Program Terms</a>.
    * Do not edit Pay Later messages with additional content, wording, marketing, or other materials to encourage the use of this product or remove any content. Render the Pay Later messaging in its entirety with all the links and language provided by PayPal. For noncompliant messaging, PayPal reserves the right to take action in accordance with the <a href="https://developer.paypal.com/studio/checkout/pay-later/paypal.com">PayPal User Agreement</a>.
    * Do not create, display, or host your own Pay Later content. Instead, integrate only the official code that PayPal provides.

    > **Notes:**
    >
    > * Reference Transaction and Recurring Payment integrations aren't eligible for Pay Later offers.
    > * Pay in 4 loans to CA residents are made or arranged pursuant to a CA Financing Law License. PayPal, Inc., is a GA Installment Lender Licensee, NMLS #910457. RI Small Loan Lender Licensee.
    > * A Pay Monthly agreement is subject to consumer credit approval. Term lengths and fixed APR of 9.99-35.99% vary based on the customer’s creditworthiness. The lender for Pay Monthly is WebBank. PayPal, Inc. (NMLS #910457): RI Loan Broker Licensee. VT Loan Solicitation Licensee.

    **See also**

    * <a href="https://www.paypal.com/us/legalhub/paypal/pay-later-messaging-tnc?locale.x=en_US">Pay Later messaging Center Program terms</a>
    * <a href="https://www.paypal.com/us/legalhub/paypal/acceptableuse-full?locale.x=en_US&_ga=1.239760260.663165815.1628012939">PayPal Acceptable Use Policy</a>
    * <a href="https://www.paypal.com/us/legalhub/paypal/useragreement-full#advertising-program">PayPal Advertising Program terms</a>
    * <a href="https://www.paypal.com/us/legalhub/paypal/useragreement-full">PayPal User Agreement</a>
  </Tab>

  <Tab title="Australia">
    Pay Later in Australia includes **Pay in 4**, which eligible Australian buyers can use to pay in 4 interest-free payments for purchases of \$1 to \$1,999.99 AUD. The first payment is due at the time of the transaction, and subsequent payments are due every 2 weeks.

    | Product  | Number of payments | Due                      | Purchase amount       |
    | -------- | ------------------ | ------------------------ | --------------------- |
    | Pay in 4 | 4                  | Every 2 weeks (biweekly) | \$1 to \$1,999.99 AUD |

    ![Example of Pay Later messaging on product pages.](https://www.paypalobjects.com/marketing/web/au/smb/checkout-installment-payments/hero-size-tablet-up-v3.png?auto=webp\&strip=1)

    **Eligibilty**

    You're eligible to integrate Pay Later offers in Australia if you meet all of the following requirements:

    * You're an Australia-based PayPal merchant.
    * You have an Australia-facing website.
    * You transact in Australian dollars (AUD).
    * You have a one-time payment integration.
    * You abide by the <a href="https://www.paypal.com/au/legalhub/paypal/acceptableuse-full?locale.x=en_AU&_ga=2.40974690.1713818232.1760366701-1032254505.1740765755">PayPal Acceptable Use Policy</a>.
    * You do not edit Pay Later messages with additional content, wording, marketing, or other materials to encourage the use of this product or remove any content. Render the Pay Later messaging in its entirety with all the links and language provided by PayPal. For noncompliant messaging, PayPal reserves the right to take action in accordance with the <a href="https://www.paypal.com/au/legalhub/paypal/useragreement-full?locale.x=en_AU&_ga=2.141621618.1713818232.1760366701-1032254505.1740765755">PayPal User Agreement</a>.
    * You do not create, display, or host your own Pay Later content. Instead, integrate only the official code that PayPal provides.

    > **Note:** PayPal Credit Pty Limited (ABN 66 600 629 258) provides PayPal **Pay in 4**. PayPal Credit Pty Limited holds Australian Credit Licence Number 568848.

    The following illustration shows how Pay Later works for customers in Australia.

    ![Image of 3 Pay Later screens on mobile apps. Step 1 shows that a Pay Later option is available for the user to buy some headphones. Step 2 shows the customer choosing between monthly and Pay in 4 options for Pay Later. In step 3, the user sees a screen that describes the Pay in 4 payment schedule. The description of this step adds that PayPal handles the payment from here and that the merchant gets paid up front and in full.](https://www.paypalobjects.com/ppdevdocs/pl-australia.png)

    **See also**

    * <a href="https://www.paypal.com/au/legalhub/paypal/pay-later-messaging-tnc?_ga=2.207893146.989760939.1760545530-1032254505.1740765755">Pay Later messaging Center Program terms</a>
    * <a href="https://www.paypal.com/au/legalhub/paypal/acceptableuse-full?locale.x=en_AU&_ga=2.207893146.989760939.1760545530-1032254505.1740765755">PayPal Acceptable Use Policy</a>
    * <a href="https://www.paypal.com/au/legalhub/paypal/useragreement-full?_ga=2.207893146.989760939.1760545530-1032254505.1740765755#advertising-program">PayPal Advertising Program terms</a>
    * <a href="https://www.paypal.com/au/legalhub/paypal/useragreement-full?locale.x=en_AU&_ga=2.164894391.989760939.1760545530-1032254505.1740765755">PayPal User Agreement</a>
  </Tab>

  <Tab title="France">
    Pay Later in France includes **Pay in 4**, which is an installment offer that allows consumers to spread the cost of a purchases across 4 equal payments for transactions between 30€ and 2,000€. The first payment is due at the time of the transaction. The subsequent payments spread across 90 days.

    | Product  | Number of payments | Due     | Purchase amount |
    | -------- | ------------------ | ------- | --------------- |
    | Pay in 4 | 4                  | Monthly | 30€ to 2,000€   |

    ![Example of Pay Later messaging on product pages.](https://www.paypalobjects.com/marketing/web23/fr/smb/installment-payments/french/hero_size-tablet-up.png?auto=webp\&strip=1\&quality=80)

    **Eligibility**

    You're eligible to integrate Pay Later offers in France if you meet all of the following requirements:

    * You're a France-based PayPal merchant.
    * You have a France-facing website.
    * You transact in euros (EUR).
    * You have a one-time payment integration.
    * You abide by the <a href="https://www.paypal.com/fr/webapps/mpp/ua/acceptableuse-full?locale.x=fr_FR&_ga=2.37446752.1323232211.1760020831-1032254505.1740765755">PayPal Acceptable Use Policy</a>.
    * You do not edit Pay Later messages with additional content, wording, marketing, or other materials to encourage use of this product. PayPal reserves the right to take action in accordance with the <a href="https://www.paypal.com/fr/webapps/mpp/ua/useragreement-full?locale.x=fr_FR&_ga=2.189361387.1323232211.1760020831-1032254505.1740765755">PayPal User Agreement</a>.
    * You do not create, display, or host your own Pay Later content. Instead, integrate only the official code that PayPal provides.

    > **Note:** PayPal Pay Later is not available in all markets. PayPal Pay Later eligibility and availability is subject to merchant status, sector and integration. Consumer eligibility is subject to status and approval. Product features differ by market. See relevant product terms for more details. PayPal Pay Later cross-border messaging is subject to approval by PayPal.

    ![Image of 3 Pay Later screens on mobile apps. Step 1 shows that a Pay Later option is available for the user to buy some sunglasses. Step 2 shows the customer choosing a payment option. In step 3, the user sees a screen that describes the Pay in 4 payment schedule. The description of this step adds that PayPal handles the payment from here and that the merchant gets paid up front and in full.](https://www.paypalobjects.com/ppdevdocs/pl-france.png)

    **See also**

    * <a href="https://www.paypal.com/fr/legalhub/paypal/pay-later-messaging-tnc?_ga=2.172700203.989760939.1760545530-1032254505.1740765755">Pay Later messaging Center Program terms</a>
    * <a href="https://www.paypal.com/fr/legalhub/paypal/acceptableuse-full?locale.x=fr_FR&_ga=2.172700203.989760939.1760545530-1032254505.1740765755">PayPal Acceptable Use Policy</a>
    * <a href="https://www.paypal.com/fr/legalhub/paypal/useragreement-full?_ga=2.172700203.989760939.1760545530-1032254505.1740765755#receive-payment1">PayPal Advertising Program terms</a>
    * <a href="https://www.paypal.com/fr/legalhub/paypal/useragreement-full?locale.x=fr_FR&_ga=2.173768107.989760939.1760545530-1032254505.1740765755">PayPal User Agreement</a>
  </Tab>

  <Tab title="Germany">
    Pay Later in Germany includes installment options and **Pay in 30 Days**.

    | Product             | Number of payments           | Due                              | Purchase amount |
    | ------------------- | ---------------------------- | -------------------------------- | --------------- |
    | PayPal Ratenzahlung | 3, 6, 12, or 24 installments | Monthly                          | 99€ to 10,000€  |
    | Pay in 30 Days      | 1                            | Single payment due after 30 days | 1€ to 2,000€    |

    ![Example of Pay Later messaging on product pages.](https://www.paypalobjects.com/marketing/web23/de/smb/QL/accept-payments-installments/hero_size-tablet-up.png?auto=webp\&strip=1\&quality=80)

    **Eligibility**

    You're eligible to integrate Pay Later offers in Germany if you meet all of the following requirements:

    * You're a Germany-based PayPal merchant.
    * You have a Germany-facing website.
    * You transact in euros (EUR).
    * You have a one-time payment integration.
    * You abide by the <a href="https://www.paypal.com/de/webapps/mpp/ua/acceptableuse-full?locale.x=en_DE&_ga=2.96210268.1323232211.1760020831-1032254505.1740765755">PayPal Acceptable Use Policy</a>.
    * You do not edit Pay Later messages with additional content, wording, marketing, or other materials to encourage use of this product. PayPal reserves the right to take action in accordance with the <a href="https://www.paypal.com/de/webapps/mpp/ua/useragreement-full?locale.x=de_DE&_ga=2.32687486.1323232211.1760020831-1032254505.1740765755">PayPal User Agreement</a>.
    * You do not create, display, or host your own Pay Later content. Instead, integrate only the official code that PayPal provides.

    > **Note:** PayPal Pay Later is not available in all markets. PayPal Pay Later eligibility and availability is subject to merchant status, sector and integration. Consumer eligibility is subject to status and approval. Product features differ by market. See relevant product terms for more details. PayPal Pay Later cross-border messaging is subject to approval by PayPal.

    ![Image of 3 Pay Later screens on mobile apps. Step 1 shows that a Pay Later option is available for the user to buy a purse. Step 2 shows the customer choosing a payment option. In step 3, the user sees a screen that describes the payment schedule. The description of this step adds that PayPal handles the payment from here and that the merchant gets paid up front and in full.](https://www.paypalobjects.com/ppdevdocs/pl-germany.png)

    **See also**

    * <a href="https://www.paypal.com/de/legalhub/paypal/pay-later-messaging-tnc?_ga=2.173824299.989760939.1760545530-1032254505.1740765755">Pay Later messaging Center Program terms</a>
    * <a href="https://www.paypal.com/de/legalhub/paypal/acceptableuse-full?locale.x=en_DE&_ga=2.173824299.989760939.1760545530-1032254505.1740765755">PayPal Acceptable Use Policy</a>
    * <a href="https://www.paypal.com/de/legalhub/paypal/useragreement-full?_ga=2.173824299.989760939.1760545530-1032254505.1740765755#receive-payment1">PayPal Advertising Program terms</a>
    * <a href="https://www.paypal.com/de/legalhub/paypal/useragreement-full?locale.x=de_DE&_ga=2.173824299.989760939.1760545530-1032254505.1740765755">PayPal User Agreement</a>
  </Tab>

  <Tab title="Italy">
    Pay Later in Italy includes **Pay in 3** installments, which allows eligible buyers in Italy to spread the cost of a purchase across 3 interest-free payments for purchases of 30€-2,000€. The first payment is due at the time of the transaction, and subsequent payments are due every month.

    | Product  | Number of payments | Due     | Purchase amount |
    | -------- | ------------------ | ------- | --------------- |
    | Pay in 3 | 3                  | Monthly | 30€ to 2,000    |

    ![Example of Pay Later messaging on product pages.](https://www.paypalobjects.com/marketing/web23/it/smb/paypal-pay-in-3/italian/hero_size_tablet-up_v1.png?auto=webp\&strip=1\&quality=80)

    **Eligibility**

    You're eligible to integrate Pay Later offers in Italy if you meet all of the following requirements:

    * You’re an Italy-based PayPal merchant.
    * You have an Italy-facing website.
    * You transact in euros (EUR).
    * You have a one-time payment integration.
    * You abide by the <a href="https://www.paypal.com/it/legalhub/paypal/acceptableuse-full?locale.x=it_IT&_ga=2.264904015.1713818232.1760366701-1032254505.1740765755">PayPal Acceptable Use Policy</a>.
    * You don't edit Pay Later messages with additional content, wording, marketing, or other materials to encourage use of this product. PayPal reserves the right to take action in accordance with the <a href="https://www.paypal.com/it/legalhub/paypal/home?locale.x=it_IT&_ga=2.100220126.1713818232.1760366701-1032254505.1740765755">PayPal User Agreement</a>.
    * You do not create, display, or host your own Pay Later content. Instead, integrate only the official code that PayPal provides.

    > **Note:** PayPal Pay Later is not available in all markets. PayPal Pay Later eligibility and availability is subject to merchant status, sector and integration. Consumer eligibility is subject to status and approval. Product features differ by market. See relevant product terms for more details. PayPal Pay Later cross-border messaging is subject to approval by PayPal.

    ![Image of 3 Pay Later screens on mobile apps. Step 1 shows that a Pay Later option is available for the user to buy some sunglasses. Step 2 shows the customer choosing a payment option. In step 3, the user sees a screen that describes the payment schedule. The description of this step adds that PayPal handles the payment from here and that the merchant gets paid up front and in full.](https://www.paypalobjects.com/ppdevdocs/pl-italy.png)

    **See also**

    * <a href="https://www.paypal.com/it/legalhub/paypal/acceptableuse-full?locale.x=it_IT&_ga=2.167933225.989760939.1760545530-1032254505.1740765755">PayPal Acceptable Use Policy</a>
  </Tab>

  <Tab title="Spain">
    Pay Later in Spain includes **Pay in 3** installments, which allows eligible buyers in Spain to spread the cost of a purchase across 3 interest-free payments for purchases of 30€-2,000€. The first payment is due at the time of the transaction, and subsequent payments are due every month.

    | Product  | Number of payments | Due     | Purchase amount |
    | -------- | ------------------ | ------- | --------------- |
    | Pay in 3 | 3                  | Monthly | 30€ to 2,000    |

    ![Example of Pay Later messaging on product pages.](https://www.paypalobjects.com/marketing/web23/es/smb/paypal-pay-in-3/spanish/hero_size-tablet-up-v1.png?auto=webp\&strip=1\&quality=80)

    **Eligibility**

    You're eligible to integrate Pay Later offers in Spain if you meet all of the following requirements:

    * You're a Spain-based PayPal merchant.
    * You have a Spain-facing website.
    * You transact in euros (EUR).
    * You have a one-time payment integration.
    * You abide by the <a href="https://www.paypal.com/es/legalhub/paypal/acceptableuse-full?locale.x=es_ES&_ga=2.4282355.1713818232.1760366701-1032254505.1740765755">PayPal Acceptable Use Policy</a>.
    * You don't edit Pay Later messages with additional content, wording, marketing, or other materials to encourage use of this product. PayPal reserves the right to take action in accordance with the <a href="https://www.paypal.com/es/legalhub/paypal/useragreement-full?_ga=2.4282355.1713818232.1760366701-1032254505.1740765755">PayPal User Agreement</a>.
    * You do not create, display, or host your own Pay Later content. Instead, integrate only the official code that PayPal provides.

    ![Image of 3 Pay Later screens on mobile apps. Step 1 shows that a Pay Later option is available for the user to buy some sunglasses. Step 2 shows the customer choosing a payment option. In step 3, the user sees a screen that describes the payment schedule. The description of this step adds that PayPal handles the payment from here and that the merchant gets paid up front and in full.](https://www.paypalobjects.com/ppdevdocs/pl-spain.png)

    **See also**

    * <a href="https://www.paypal.com/es/legalhub/paypal/acceptableuse-full?locale.x=es_ES&_ga=2.136142137.989760939.1760545530-1032254505.1740765755">PayPal Acceptable Use Policy</a>
  </Tab>

  <Tab title="United Kingdom">
    Pay Later in the UK includes the following two products:

    * With **Pay in 3**, eligible UK buyers can pay in 3 interest-free payments for purchases of £30 to £2,000. The first payment is due at the time of purchase, and subsequent payments are due in the following 2 months.
    * With **PayPal Credit**, eligible UK buyers receive a revolving line of credit that they can use to pay over time. PayPal Credit offers either 0% interest for 4 months on purchases over £99 or a merchant-specific Installment offers. For the 0% interest for 4 months offer, any remaining balance due after the promotional period or any transactions under £99 are charged interest at the standard variable rate. Terms and conditions apply. Representative 23.9% APR (variable). FCA credit broking permission required to advertise PayPal Credit.

    ![Example of Pay Later messaging on product pages.](https://www.paypalobjects.com/dev-studio-space/hero_size-tablet-up_v1.png?auto=webp\&strip=1\&quality=80)

    **Eligibility**

    Pay Later offers are available to UK merchants on a limited basis. To be eligible to integrate Pay Later offers in the UK, you must meet all of the following requirements:

    * You're a UK-based PayPal merchant.
    * You have a UK-facing website.
    * You transact in British pounds sterling (GBP).
    * You have a one-time payment integration.
    * You abide by the <a href="https://www.paypal.com/uk/legalhub/paypal/acceptableuse-full?locale.x=en_UK&_ga=2.59455597.1713818232.1760366701-1032254505.1740765755">PayPal Acceptable Use Policy</a>.
    * You comply with the <a href="https://www.paypal.com/uk/legalhub/paypal/pay-later-messaging-tnc?_ga=2.263256268.1713818232.1760366701-1032254505.1740765755">Pay Later Messaging Center Program Terms</a> and the <a href="https://www.paypal.com/uk/legalhub/paypal/useragreement-full?_ga=2.263256268.1713818232.1760366701-1032254505.1740765755#receive-payment1">PayPal Advertiser Program Terms</a>. In particular, do not edit Pay Later messages with additional content, wording, marketing, or other materials to encourage the use of this product or remove any content. Render the Pay Later messaging in its entirety with all the links and language provided by PayPal. For noncompliant messaging, PayPal reserved the right to take action in accordance with the PayPal User Agreement.
    * You not create, display, or host your own Pay Later content. Instead, integrate only the official code that PayPal provides.

    PayPal Pay in 3 is an unregulated credit product. Merchant eligibility and availability is subject to merchant status, sector, and integration. Consumer eligibility is subject to status and approval.

    PayPal Pay Later Product features differ by market. See relevant product terms for more details. PayPal Pay Later cross-border messaging is subject to approval by PayPal.

    ![Image of 3 Pay Later screens on mobile apps. Step 1 shows that a Pay Later option is available for the user to buy some running shoes. Step 2 shows the customer choosing a payment option. In step 3, the user sees a screen that describes the payment schedule. The description of this step adds that PayPal handles the payment from here and that the merchant gets paid up front and in full.](https://www.paypalobjects.com/ppdevdocs/pl-uk.png)

    **See also**

    * <a href="https://www.paypal.com/uk/legalhub/paypal/pay-later-messaging-tnc?_ga=2.176502445.989760939.1760545530-1032254505.1740765755">Pay Later messaging Center Program terms</a>
    * <a href="https://www.paypal.com/uk/legalhub/paypal/acceptableuse-full?locale.x=en_UK&_ga=2.163935671.989760939.1760545530-1032254505.1740765755">PayPal Acceptable Use Policy</a>
    * <a href="https://www.paypal.com/uk/legalhub/paypal/useragreement-full?_ga=2.163935671.989760939.1760545530-1032254505.1740765755#receive-payment1">PayPal Advertising Program terms</a>
    * <a href="https://www.paypal.com/uk/legalhub/paypal/useragreement-full?_ga=2.163935671.989760939.1760545530-1032254505.1740765755">PayPal User Agreement</a>
  </Tab>

  <Tab title="Canada">
    PayPal offers special financing options that payers can use to buy now and pay later, while merchants get paid upfront. For more information about Pay Later, see <a href="https://developer.paypal.com/docs/checkout/pay-later/ca/">Buy now, pay later</a>.

    | Product  | Number of payments | Due                       | Purchase amount |
    | -------- | ------------------ | ------------------------- | --------------- |
    | Pay in 4 | 4                  | Every 2 weeks (Bi-weekly) | \$30 to \$1,500 |

    ![Example of Pay Later messaging on product pages.](https://www.paypalobjects.com/marketing/web/au/smb/checkout-installment-payments/hero-size-tablet-up-v3.png?auto=webp\&strip=1)

    **Eligibility**

    You're eligible to integrate Pay Later offers in Canada if you meet all of the following requirements:

    * Are a Canada-based PayPal merchant.
    * Have a Canada-facing website.
    * Transact in Canadian dollars (CAD).
    * Have a one-time payment integration, and Pay Later options are available through PayPal checkout.
    * Abide by the <a href="https://www.paypal.com/CA/legalhub/paypal/acceptableuse-full?locale.x=en_AU&_ga=2.266048202.491347162.1773069831-190704908.1758645993">Pay Later Messaging Center Program Terms</a>.
    * Do not edit Pay Later messages with additional content, wording, marketing, or other materials to encourage the use of this product or remove any content. Render the Pay Later messaging in its entirety with all the links and language provided by PayPal. For noncompliant messaging, PayPal reserves the right to take action in accordance with the <a href="https://www.paypal.com/ca/legalhub/paypal/useragreement-full?locale.x=en_AU&_ga=2.266048202.491347162.1773069831-190704908.1758645993">PayPal User Agreement</a>.
    * Do not create, display, or host your own Pay Later content. Instead, integrate only the official code that PayPal provides.

    **Enable Multilingual Support for Pay Later Buttons**

    To enable the **Pay in 4** button, include `buttons` and `enable-funding=paylater` when rendering buttons in your PayPal Checkout integration. You must also specify a value for the `locale` parameter.

    | Parameter | Description           | Setting        |
    | --------- | --------------------- | -------------- |
    | `locale`  | English-language site | `locale=en_CA` |
    | `locale`  | French-language site  | `locale=fr_CA` |

    > **Note:**
    >
    > * Reference Transaction and Recurring Payment integrations aren't eligible for Pay Later offers.

    **See also**

    * <a href="https://www.paypalobjects.com/crc-merchant-lifecycle/docs/CA_Pay_in_4_Messaging_Centre_Program_Terms.pdf">Pay Later messaging Center Program terms</a>
    * <a href="https://www.paypal.com/CA/legalhub/paypal/acceptableuse-full?locale.x=en_AU&_ga=2.237663173.491347162.1773069831-190704908.1758645993">PayPal Acceptable Use Policy</a>
    * <a href="https://www.paypal.com/ca/legalhub/paypal/useragreement-full#advertising-program">PayPal Advertising Program terms</a>
    * <a href="https://www.paypal.com/ca/legalhub/paypal/useragreement-full?locale.x=en_AU&_ga=2.237663173.491347162.1773069831-190704908.1758645993">PayPal User Agreement</a>
  </Tab>
</Tabs>


# Upgrade Pay Later to SDK v6
Source: https://docs.paypal.ai/payments/methods/pay-later/upgrade



Use this guide to upgrade Pay Later messaging from the JavaScript SDK v5 to v6.

> **Tip:** You don't have to upgrade other PayPal components, such as PayPal Checkout, before you upgrade Pay Later messaging. To upgrade everything, follow [this guide](/developer/upgrade/sdk/js/v5-v6) first.

## Pay Later messaging features in SDK v6

Among the other [benefits of SDK v6](/developer/upgrade/sdk/js/v5-v6#compare-v5-and-v6), it brings these important features to Pay Later messaging:

* Support for local, CDN, and site caching for faster content visibility
* An auto-bootstrap feature for easy integration
* Customizable logo types, text sizes, logo positions, offer types, presentation modes, and caching types
* More visibility for improved analytics and diagnostics
* Support for passing customizations through the HTML component, JavaScript, or both through `getFetchContentOptions`
* Support for flexible authentication using a client ID or a server-side client token
* Improved performance

## Upgrade Pay Later messaging to SDK v6

Pay Later messaging is a component of PayPal's SDK v6. To upgrade Pay Later messaging to SDK v6, you must first upgrade the core SDK.

### 1. Import the SDK and the `messages` script

The SDK v5 script uses a `client-id` value. It also specifies which components to use. For example, this code sample uses the `messages` and `buttons` components.

```html lines theme={null}
<script 
src="https://www.sandbox.paypal.com/sdk/js?client-id=CLIENT_ID&components=messages,buttons"
data-namespace="PayPalSDK">
</script>
```

SDK v6 supports 2 authentication types. Choose the one that best fits your integration:

* `clientId`: Pass your PayPal client ID directly to `createInstance()` with no server-side token generation required.
* `clientToken`: Generate a client token on the server side using your [client ID and client secret](https://docs.paypal.ai/developer/how-to/api/get-started#1-get-your-client-id-and-client-secret), then pass it to `createInstance()`. For more information, see [Set up JavaScript SDK v6](/developer/how-to/sdk/js/v6/configuration).

> **Tip:** If you followed the [general upgrade guide for SDK v6](/developer/upgrade/sdk/js/v5-v6/) and have the SDK core script, you only need to add `paypal-messages` to the components list when you initialize the SDK, as shown in the following example.

```javascript lines theme={null}
// Option 1: Using clientId (no server-side token generation required)  
  const sdkInstance = await window.paypal.createInstance({   
    clientId: "YOUR_CLIENT_ID",  
    components: ["paypal-payments", "venmo-payments", "paypal-messages"],  
    pageType: "checkout"  
  }); 

// Option 2: Using clientToken (requires server-side token generation)  
  const sdkInstance = await window.paypal.createInstance({ 
    clientToken, 
    components: ["paypal-payments", "venmo-payments", "paypal-messages"], 
    pageType: "checkout" 
  });
```

After you import the resources using HTML, use JavaScript to initialize the SDK and instantiate `web-sdk-messages`, as shown in the following examples.

<CodeGroup>
  ```html lines HTML  theme={null}
  <head>
    <!-- Load just the v6 SDK Core script -->
    <script src="https://www.paypal.com/web-sdk/v6/core"></script>
  </head>
  ```

  ```javascript lines expandable JavaScript theme={null}
  // Instantiate the SDK Instance, and specify paypal-messages as a component
  const sdkInstance = await window.paypal.createInstance({
    clientId: "YOUR_CLIENT_ID",
    // Include paypal-messages in the components to load
    components: ["paypal-messages"],
  });

  // Instantiate web-sdk-messages
  const messagesInstance = sdkInstance.createPayPalMessages({ buyerCountry: "US" });
  ```
</CodeGroup>

### 2. Create a container element for Pay Later messaging

Create a container element in your HTML to display the Pay Later messaging.

PayPal's SDK v5 created an element with a truthy attribute, `data-pp-message`, or you could fetch content from `paypal.Messages` in JavaScript and render it to any `div` element dynamically. In contrast, SDK v6 uses a custom Lit component called `paypal-message`. You can use this component in place of a `div` element to support more sophisticated HTML formatting, such as auto-bootstrap layouts. It also makes it easier to encapsulate the element from its containing page, provides better visibility into the lifecycle of the component, and improves reusability.

Treat `paypal-message` as a custom HTML element. The minimum requirement after you import the scripts is to include this element in your HTML.

```html theme={null}
<paypal-message></paypal-message>
```

The `paypal-message` element provides optional, customizable attributes for adjusting the logo type, logo position, and more. It also includes a boolean `auto-bootstrap` attribute that simplifies how you connect `fetchContent` and `learnMore` calls, eliminating the need to include them in your JavaScript.

For more information about setting up your integration, see [Get started with Pay Later](/payments/methods/pay-later/get-started).

### 3. Configure Pay Later messaging

You have 2 configuration options for SDk v6:

* For a streamlined approach, use the customizable `auto-bootstrap` option.
* If you do not use the `auto-bootstrap` option, use the PayPal `Messages` JavaScript interface. This interface provides 2 instance methods:
  * `fetchContent` (required)
  * `createLearnMore` (optional)

Similar to SDK v5, SDK v6 also allows you to pass your configuration through HTML or JavaScript. However, SDK v6 also enables you to pass configurations through both HTML attributes and JavaScript properties.

For more information about customizing your message and configuring with `auto-bootstrap` or JavaScript, see [Get started with Pay Later](/payments/methods/pay-later/get-started).


# Buy online, pick up in store
Source: https://docs.paypal.ai/payments/methods/paypal/buy-online-pick-up-in-store



Handle payments for orders that customers purchase online and pick up at a physical store location. This pattern authorizes payment at checkout and captures funds after verifying pickup. This ensures payment is secured and collected only when the customer receives their items.

Common scenarios include:

* Retail stores offering same-day pickup
* Grocery orders for curbside pickup
* Restaurant orders for takeout
* Click-and-collect services

<Tip>Before you begin, you'll need to complete [the quick start PayPal integration](/payments/methods/paypal/integrate).</Tip>

## Integrate server side

Add the following endpoints to your existing server file from the quick start integration.

<CodeGroup>
  ```bash cURL lines expandable theme={null}
  # Create BOPIS order (authorization)
  curl -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -d '{
      "intent": "AUTHORIZE",
      "purchase_units": [{
        "amount": {
          "currency_code": "USD",
          "value": "75.00"
        },
        "shipping": {
          "type": "PICKUP_IN_STORE",
          "address": {
            "address_line_1": "123 Orders St",
            "admin_area_2": "San Francisco",
            "admin_area_1": "CA",
            "postal_code": "94107",
            "country_code": "US"
          }
        },
        "custom_id": "YOUR-PICKUP-ORDER-ID",
        "description": "Pickup at Store 123"
      }]
    }'

  # After buyer approval, authorize the order
  curl -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER_ID/authorize \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ACCESS_TOKEN"

  # Capture payment at pickup
  curl -X POST https://api-m.sandbox.paypal.com/v2/payments/authorizations/AUTH_ID/capture \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ACCESS_TOKEN"
  ```

  ```javascript Node.js lines expandable theme={null}
  // The PayPal client and addNegativeTesting helper are already configured from the quick start integration

  // Modify create order for BOPIS (authorize instead of capture)
  app.post('/api/orders/bopis', async (req, res) => {
    const { amount, pickupLocation, pickupCode, pickupAddress } = req.body;
    const request = new paypal.orders.OrdersCreateRequest();
    request.requestBody({
      intent: 'AUTHORIZE', // Authorize for pickup verification
      purchase_units: [{
        amount: {
          currency_code: 'USD',
          value: amount || '100.00'
        },
        shipping: {
          type: 'PICKUP_IN_STORE',
          address: {
            address_line_1: pickupAddress.line1,
            admin_area_2: pickupAddress.city,
            admin_area_1: pickupAddress.state,
            postal_code: pickupAddress.postalCode,
            country_code: pickupAddress.countryCode
          }
        },
        custom_id: `PICKUP-${pickupCode}`, // Store pickup code
        description: `Pickup at ${pickupLocation}`
      }]
    });
    // Apply negative testing if enabled (reuse helper from base integration)
    addNegativeTesting(request);
    try {
      const order = await client.execute(request);
      // Store pickup details with order
      await storePickupDetails(order.result.id, pickupCode, pickupLocation);
      res.json({ id: order.result.id });
    } catch (err) {
      res.status(500).json({ error: err.message });
    }
  });

  // Capture payment after the customer picks up the order
  app.post('/api/orders/bopis/:orderId/pickup', async (req, res) => {
    const { authorizationId, pickupCode } = req.body;
    // Verify pickup code matches
    if (!await verifyPickupCode(req.params.orderId, pickupCode)) {
      return res.status(401).json({ error: 'Invalid pickup code' });
    }
    const request = new paypal.payments.AuthorizationsCaptureRequest(authorizationId);
    // Apply negative testing if enabled (reuse helper from base integration)
    addNegativeTesting(request);
    try {
      const capture = await client.execute(request);
      res.json({
        status: 'PICKED_UP',
        captureId: capture.result.id
      });
    } catch (err) {
      if (err.statusCode === 422) {
        res.status(400).json({ error: 'Authorization expired - order canceled' });
      } else {
        res.status(500).json({ error: err.message });
      }
    }
  });
  ```

  ```python Python lines expandable theme={null}
  from paypalrestsdk import Api, Order, Authorization
  import os

  # Configure PayPal SDK
  api = Api({
    'mode': 'sandbox',
    'client_id': os.environ['PAYPAL_CLIENT_ID'],
    'client_secret': os.environ['PAYPAL_CLIENT_SECRET']
  })

  # Create BOPIS order (authorization)
  @app.route('/api/orders/bopis', methods=['POST'])
  def create_bopis_order():
    try:
      amount = request.json.get('amount', '100.00')
      pickup_location = request.json.get('pickupLocation')
      pickup_code = request.json.get('pickupCode')
      pickup_address = request.json.get('pickupAddress', {})

      order_data = {
        "intent": "AUTHORIZE",
        "purchase_units": [{
          "amount": {
            "currency_code": "USD",
            "value": amount
          },
          "shipping": {
            "type": "PICKUP_IN_STORE",
            "address": {
              "address_line_1": pickup_address.get('line1'),
              "admin_area_2": pickup_address.get('city'),
              "admin_area_1": pickup_address.get('state'),
              "postal_code": pickup_address.get('postalCode'),
              "country_code": pickup_address.get('countryCode')
            }
          },
          "custom_id": f"PICKUP-{pickup_code}",
          "description": f"Pickup at {pickup_location}"
        }]
      }

      order = Order(order_data)
      if order.create():
        # Store pickup details with order
        store_pickup_details(order.id, pickup_code, pickup_location)
        return jsonify({"id": order.id})
      else:
        return jsonify({"error": order.error}), 500

    except Exception as e:
      return jsonify({"error": str(e)}), 500

  # Capture payment after pickup
  @app.route('/api/orders/bopis/<order_id>/pickup', methods=['POST'])
  def capture_at_pickup(order_id):
    try:
      authorization_id = request.json.get('authorizationId')
      pickup_code = request.json.get('pickupCode')

      # Verify pickup code matches
      if not verify_pickup_code(order_id, pickup_code):
        return jsonify({"error": "Invalid pickup code"}), 401

      authorization = Authorization.find(authorization_id)
      capture = authorization.capture()

      if capture.success():
        return jsonify({
          "status": "PICKED_UP",
          "captureId": capture.id
        })
      else:
        error = capture.error
        if error.get('name') == 'AUTHORIZATION_EXPIRED':
          return jsonify({
            "error": "Authorization expired - order canceled"
          }), 400
        else:
          return jsonify({"error": error.get('message')}), 500

    except Exception as e:
      return jsonify({"error": str(e)}), 500
  ```

  ```java Java lines expandable theme={null}
  import com.paypal.core.PayPalEnvironment;
  import com.paypal.core.PayPalHttpClient;
  import com.paypal.orders.OrdersCreateRequest;
  import com.paypal.orders.OrderRequest;
  import com.paypal.orders.PurchaseUnitRequest;
  import com.paypal.orders.AmountWithBreakdown;
  import com.paypal.payments.AuthorizationsCaptureRequest;
  import com.paypal.payments.Capture;

  HttpClient httpClient = new PayPalHttpClient(
    new SandboxEnvironment(
      System.getenv("PAYPAL_CLIENT_ID"),
      System.getenv("PAYPAL_CLIENT_SECRET")
    )
  );

  // Create BOPIS order (authorization)
  @PostMapping("/api/orders/bopis")
  public ResponseEntity<?> createBopisOrder(@RequestBody BopisOrderRequest bopisRequest) {
    try {
      OrdersCreateRequest request = new OrdersCreateRequest();

      AddressPortable address = new AddressPortable()
        .addressLine1(bopisRequest.getPickupAddress().getLine1())
        .adminArea2(bopisRequest.getPickupAddress().getCity())
        .adminArea1(bopisRequest.getPickupAddress().getState())
        .postalCode(bopisRequest.getPickupAddress().getPostalCode())
        .countryCode(bopisRequest.getPickupAddress().getCountryCode());

      OrderRequest orderRequest = new OrderRequest()
        .checkoutPaymentIntent("AUTHORIZE")
        .purchaseUnits(Arrays.asList(
          new PurchaseUnitRequest()
            .amountWithBreakdown(
              new AmountWithBreakdown()
                .currencyCode("USD")
                .value(bopisRequest.getAmount() != null ?
                  bopisRequest.getAmount() : "100.00")
            )
            .shipping(
              new ShippingDetail()
                .type("PICKUP_IN_STORE")
                .address(address)
            )
            .customId("PICKUP-" + bopisRequest.getPickupCode())
            .description("Pickup at " + bopisRequest.getPickupLocation())
        ));

      request.requestBody(orderRequest);
      HttpResponse<Order> response = httpClient.execute(request);
      Order order = response.result();

      // Store pickup details with order
      storePickupDetails(order.id(), bopisRequest.getPickupCode(),
                        bopisRequest.getPickupLocation());

      return ResponseEntity.ok(Map.of("id", order.id()));

    } catch (Exception e) {
      return ResponseEntity.status(500).body(
        Map.of("error", e.getMessage())
      );
    }
  }

  // Capture payment after pickup
  @PostMapping("/api/orders/bopis/{orderId}/pickup")
  public ResponseEntity<?> captureAtPickup(
    @PathVariable String orderId,
    @RequestBody PickupRequest pickupRequest
  ) {
    try {
      // Verify pickup code matches
      if (!verifyPickupCode(orderId, pickupRequest.getPickupCode())) {
        return ResponseEntity.status(401).body(
          Map.of("error", "Invalid pickup code")
        );
      }

      AuthorizationsCaptureRequest request =
        new AuthorizationsCaptureRequest(pickupRequest.getAuthorizationId());

      HttpResponse<Capture> response = httpClient.execute(request);
      Capture capture = response.result();

      return ResponseEntity.ok(Map.of(
        "status", "PICKED_UP",
        "captureId", capture.id()
      ));

    } catch (HttpClientException e) {
      if (e.statusCode() == 422) {
        return ResponseEntity.badRequest().body(
          Map.of("error", "Authorization expired - order canceled")
        );
      }
      return ResponseEntity.status(500).body(
        Map.of("error", e.getMessage())
      );
    }
  }
  ```

  ```php PHP lines expandable theme={null}
  <?php
  use PayPalCheckoutSdk\Core\SandboxEnvironment;
  use PayPalCheckoutSdk\Core\PayPalHttpClient;
  use PayPalCheckoutSdk\Orders\OrdersCreateRequest;
  use PayPalCheckoutSdk\Payments\AuthorizationsCaptureRequest;

  $environment = new SandboxEnvironment(
    getenv('PAYPAL_CLIENT_ID'),
    getenv('PAYPAL_CLIENT_SECRET')
  );
  $client = new PayPalHttpClient($environment);

  // Create BOPIS order (authorization)
  $app->post('/api/orders/bopis', function ($request, $response) use ($client) {
    $body = $request->getParsedBody();
    $pickupAddress = $body['pickupAddress'] ?? [];

    $orderRequest = new OrdersCreateRequest();
    $orderRequest->body = [
      "intent" => "AUTHORIZE",
      "purchase_units" => [[
        "amount" => [
          "currency_code" => "USD",
          "value" => $body['amount'] ?? "100.00"
        ],
        "shipping" => [
          "type" => "PICKUP_IN_STORE",
          "address" => [
            "address_line_1" => $pickupAddress['line1'] ?? "",
            "admin_area_2" => $pickupAddress['city'] ?? "",
            "admin_area_1" => $pickupAddress['state'] ?? "",
            "postal_code" => $pickupAddress['postalCode'] ?? "",
            "country_code" => $pickupAddress['countryCode'] ?? ""
          ]
        ],
        "custom_id" => "PICKUP-" . $body['pickupCode'],
        "description" => "Pickup at " . $body['pickupLocation']
      ]]
    ];

    try {
      $orderResponse = $client->execute($orderRequest);
      $order = $orderResponse->result;

      // Store pickup details with order
      storePickupDetails($order->id, $body['pickupCode'], $body['pickupLocation']);

      $response->getBody()->write(json_encode([
        "id" => $order->id
      ]));
      return $response->withHeader('Content-Type', 'application/json');

    } catch (HttpException $e) {
      $response->getBody()->write(json_encode([
        "error" => $e->getMessage()
      ]));
      return $response->withStatus(500)->withHeader('Content-Type', 'application/json');
    }
  });

  // Capture payment after pickup
  $app->post('/api/orders/bopis/{orderId}/pickup', function ($request, $response, $args) use ($client) {
    $orderId = $args['orderId'];
    $body = $request->getParsedBody();

    // Verify pickup code matches
    if (!verifyPickupCode($orderId, $body['pickupCode'])) {
      $response->getBody()->write(json_encode([
        "error" => "Invalid pickup code"
      ]));
      return $response->withStatus(401)->withHeader('Content-Type', 'application/json');
    }

    $captureRequest = new AuthorizationsCaptureRequest($body['authorizationId']);

    try {
      $captureResponse = $client->execute($captureRequest);
      $capture = $captureResponse->result;

      $response->getBody()->write(json_encode([
        "status" => "PICKED_UP",
        "captureId" => $capture->id
      ]));
      return $response->withHeader('Content-Type', 'application/json');

    } catch (HttpException $e) {
      $statusCode = $e->statusCode;

      if ($statusCode === 422) {
        $response->getBody()->write(json_encode([
          "error" => "Authorization expired - order canceled"
        ]));
        return $response->withStatus(400)->withHeader('Content-Type', 'application/json');
      }

      $response->getBody()->write(json_encode([
        "error" => $e->getMessage()
      ]));
      return $response->withStatus(500)->withHeader('Content-Type', 'application/json');
    }
  });
  ```

  ```ruby Ruby lines expandable theme={null}
  require 'paypal-sdk'

  # Configure PayPal SDK
  PayPal::SDK.configure(
    :mode => "sandbox",
    :app_id => ENV['PAYPAL_APP_ID'],
    :client_id => ENV['PAYPAL_CLIENT_ID'],
    :client_secret => ENV['PAYPAL_CLIENT_SECRET']
  )

  # Create BOPIS order (authorization)
  post '/api/orders/bopis' do
    request_body = JSON.parse(request.body.read)
    pickup_address = request_body['pickupAddress'] || {}

    begin
      order_data = {
        intent: 'AUTHORIZE',
        purchase_units: [{
          amount: {
            currency_code: 'USD',
            value: request_body['amount'] || '100.00'
          },
          shipping: {
            type: 'PICKUP_IN_STORE',
            address: {
              address_line_1: pickup_address['line1'],
              admin_area_2: pickup_address['city'],
              admin_area_1: pickup_address['state'],
              postal_code: pickup_address['postalCode'],
              country_code: pickup_address['countryCode']
            }
          },
          custom_id: "PICKUP-#{request_body['pickupCode']}",
          description: "Pickup at #{request_body['pickupLocation']}"
        }]
      }

      order = PayPal::SDK::Orders::Order.new(order_data)

      if order.create
        # Store pickup details with order
        store_pickup_details(order.id, request_body['pickupCode'],
                            request_body['pickupLocation'])

        content_type :json
        { id: order.id }.to_json
      else
        status 500
        { error: order.error }.to_json
      end

    rescue => e
      status 500
      { error: e.message }.to_json
    end
  end

  # Capture payment after pickup
  post '/api/orders/bopis/:order_id/pickup' do
    order_id = params['order_id']
    request_body = JSON.parse(request.body.read)

    begin
      # Verify pickup code matches
      unless verify_pickup_code(order_id, request_body['pickupCode'])
        status 401
        return { error: 'Invalid pickup code' }.to_json
      end

      authorization = PayPal::SDK::PaymentsApi::Authorization.find(
        request_body['authorizationId']
      )
      capture = authorization.capture

      if capture.success?
        content_type :json
        {
          status: 'PICKED_UP',
          captureId: capture.id
        }.to_json
      else
        error = capture.error
        if error['name'] == 'AUTHORIZATION_EXPIRED'
          status 400
          { error: 'Authorization expired - order canceled' }.to_json
        else
          status 500
          { error: error['message'] }.to_json
        end
      end

    rescue => e
      status 500
      { error: e.message }.to_json
    end
  end
  ```
</CodeGroup>

### Test endpoints

1. Create an authorization.

<Info>Endpoint: [`/v2/checkout/orders/{id}/authorize`](/reference/api/rest/orders/authorize-payment-for-order)</Info>

```bash lines theme={null}
# 1. Create BOPIS order (authorization)
curl -X POST http://localhost:3000/api/orders/bopis \
  -H "Content-Type: application/json" \
  -d '{"amount": "75.00", "pickupLocation": "Store #123", "pickupCode": "PICK789"}'
```

2. Capture payment at pickup.

<Info>Endpoint: [`/v2/payments/authorizations/{authorization_id}/capture`](/reference/api/rest/authorizations/capture-authorized-payment)</Info>

```bash lines theme={null}
# 2. Complete pickup (capture payment)
curl -X POST http://localhost:3000/api/orders/bopis/ORDER_ID/pickup \
  -H "Content-Type: application/json" \
  -d '{"authorizationId": "AUTH_ID", "pickupCode": "PICK789"}'
```

## Best practices

* **Set clear pickup timeframes:** Communicate pickup windows. Typical holds: 7 days for retail, 24 hours for restaurants or groceries. Balance customer convenience with inventory management. Automatically void expired authorizations.
* **Implement pickup verification:** Require order number and pickup code. Capture payment only after verifying the customer.
* **Handle partial pickups:** If part of the order is collected, capture the partial amount and void the remainder.
* **Train store staff:** Ensure staff know when to trigger capture and how to handle pickup exceptions.
* **Monitor unclaimed orders:** Track unclaimed orders and void authorizations promptly to release funds.

## Important details

* **Capture only after pickup verification:** Do not capture payment before verifying the customer has received their items. This protects both you and the customer from fraud.
* **Add items at pickup:** If customers want to add items at pickup, process additional items as a separate transaction at the store.
* **Handle partial pickups:** If only part of an order is available, capture only the amount for available items and void the remaining authorization.
* **Notification timing:** Email customers when orders are ready for pickup, but only capture payment after pickup. The authorization secures payment while the order waits.
* **Identity verification methods:** Verify customer identity through order number, pickup code, photo ID, or app confirmation before capturing. Works the same for in-store, curbside, or drive-up pickup.

## Test your integration

Before testing pickup flows, authorize an order to obtain an authorization ID.

### Standard testing

| Test scenario       | Setup                                     | Expected result                                         |
| :------------------ | :---------------------------------------- | :------------------------------------------------------ |
| Successful pickup   | Create order and verify with correct code | Authorization succeeds and capture completes on pickup. |
| Invalid pickup code | Use incorrect pickup code                 | Returns 401 error: invalid pickup code.                 |
| Abandoned order     | Do not pick up within timeframe           | Authorization is voided automatically.                  |
| Partial pickup      | Authorize \$100, pick up \$60             | Capture \$60 and void remaining \$40.                   |

### Negative testing

For negative testing:

1. Make sure to enable negative testing in your sandbox business account as described in the [quick start prerequisites](/payments/methods/paypal/integrate#prerequisites).
2. In the `.env` file, set `ENABLE_NEGATIVE_TESTING=true` and set `NEGATIVE_TEST_TYPE` to one of the error codes in the table.
3. Restart the server after changing the `.env` file: `node server.js`.

| Test scenario         | Error code                       | Expected result                                  |
| :-------------------- | :------------------------------- | :----------------------------------------------- |
| Expired authorization | `AUTHORIZATION_EXPIRED`          | Error: authorization expired and order canceled. |
| Already picked up     | `AUTHORIZATION_ALREADY_CAPTURED` | Error: authorization already captured.           |

## Go-live checklist

* Integrate store pickup system with payment capture.
* Test pickup verification at all store locations.
* Configure automatic voids for unclaimed orders.
* Train store staff on capture process.
* Test with a real \$1 order and pickup.

## Post-launch monitoring

These values are suggested monitoring thresholds for your integration, not performance guarantees from PayPal.

| Metric                        | Target      | Action if below target                                  |
| :---------------------------- | :---------- | :------------------------------------------------------ |
| Authorization success rate    | 95%         | Investigate authorization failures.                     |
| Capture success at pickup     | 90%         | Check for expired authorizations or staff process gaps. |
| Authorization expiration rate | \<15%       | Monitor for abnormal increases.                         |
| Void success rate (abandoned) | 98%         | Investigate void failures.                              |
| API response time             | \<2 seconds | Check PayPal API status.                                |


# Authorize and delay capture
Source: https://docs.paypal.ai/payments/methods/paypal/delayed-capture



Charge a customer after fulfilling their order, not immediately. Common use cases include:

* Reserve payment for pre-orders shipping in the future
* Charge after made-to-order items are produced
* Authorize hotels or rentals at booking, capture at check-in or check-out
* Confirm authenticity of high value items requiring verification before capturing payment

This integration uses the Orders API v2 to authorize and the Payments API v2 to capture later. To authorize first and capture later, change your integration to use `intent: "AUTHORIZE"`. This reserves funds on the customer's payment method for up to 29 days.

The highest success rate is within the first 3 days (the honor period). After 3 days, you may use reauthorization to extend the hold.

[What's the difference between authorization and capture?](/payments/methods/paypal/overview#authorization-vs-capture)

<Tip>Before you begin, you'll need to complete [the quick start PayPal integration](/payments/methods/paypal/integrate).</Tip>

## Integrate server side

Add the following to your existing server file from the quick start integration.

<CodeGroup>
  ```bash cURL lines expandable theme={null}
  # Step 1: Create order with AUTHORIZE intent
  curl -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -d '{
      "intent": "AUTHORIZE",
      "purchase_units": [{
        "amount": {
          "currency_code": "USD",
          "value": "100.00"
        }
      }]
    }'

  # Step 2: Capture the authorization later
  curl -X POST https://api-m.sandbox.paypal.com/v2/payments/authorizations/AUTHORIZATION_ID/capture \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -d '{}'
  ```

  ```javascript Node.js lines expandable theme={null}
  // Add these endpoints to your existing server.js from the quick start integration
  // The PayPal client and addNegativeTesting helper are already configured

  // Modify the create order endpoint to use AUTHORIZE intent
  app.post('/api/orders', async (req, res) => {
    const request = new paypal.orders.OrdersCreateRequest();
    request.requestBody({
      intent: 'AUTHORIZE', // Changed from 'CAPTURE'
      purchase_units: [{
        amount: {
          currency_code: 'USD',
          value: req.body.amount || '100.00'
        }
      }]
    });

    // Apply negative testing if enabled (reuse helper from base integration)
    addNegativeTesting(request);

    try {
      const order = await client.execute(request);
      res.json({ id: order.result.id });
    } catch (err) {
      res.status(500).json({ error: err.message });
    }
  });

  // Add new endpoint to capture the authorization later
  app.post('/api/orders/:orderId/capture', async (req, res) => {
    const { authorizationId } = req.body;
    const request = new paypal.payments.AuthorizationsCaptureRequest(authorizationId);

    // Apply negative testing if enabled (reuse helper from base integration)
    addNegativeTesting(request);

    try {
      const capture = await client.execute(request);
      res.json({
        status: capture.result.status,
        captureId: capture.result.id
      });
    } catch (err) {
      if (err.statusCode === 422) {
        res.status(400).json({ error: 'Authorization expired or invalid' });
      } else {
        res.status(500).json({ error: err.message });
      }
    }
  });
  ```

  ```python Python lines expandable theme={null}
  from paypalrestsdk import Api, Order, Authorization
  import os

  # Configure PayPal SDK
  api = Api({
    'mode': 'sandbox',
    'client_id': os.environ['PAYPAL_CLIENT_ID'],
    'client_secret': os.environ['PAYPAL_CLIENT_SECRET']
  })

  # Create order with AUTHORIZE intent
  @app.route('/api/orders', methods=['POST'])
  def create_order():
    try:
      order = Order({
        "intent": "AUTHORIZE",
        "purchase_units": [{
          "amount": {
            "currency_code": "USD",
            "value": request.json.get('amount', '100.00')
          }
        }]
      })

      if order.create():
        return jsonify({"id": order.id})
      else:
        return jsonify({"error": order.error}), 500

    except Exception as e:
      return jsonify({"error": str(e)}), 500

  # Capture authorization later
  @app.route('/api/orders/<order_id>/capture', methods=['POST'])
  def capture_authorization(order_id):
    try:
      authorization_id = request.json.get('authorizationId')
      authorization = Authorization.find(authorization_id)

      if authorization.capture():
        return jsonify({
          "status": authorization.state,
          "captureId": authorization.id
        })
      else:
        error = authorization.error
        if error.get('name') == 'AUTHORIZATION_EXPIRED':
          return jsonify({
            "error": "Authorization expired or invalid"
          }), 400
        else:
          return jsonify({"error": error.get('message')}), 500

    except Exception as e:
      return jsonify({"error": str(e)}), 500
  ```

  ```java Java lines expandable theme={null}
  import com.paypal.core.PayPalEnvironment;
  import com.paypal.core.PayPalHttpClient;
  import com.paypal.orders.*;
  import com.paypal.payments.AuthorizationsCaptureRequest;
  import com.paypal.payments.Capture;

  HttpClient httpClient = new PayPalHttpClient(
    new SandboxEnvironment(
      System.getenv("PAYPAL_CLIENT_ID"),
      System.getenv("PAYPAL_CLIENT_SECRET")
    )
  );

  // Create order with AUTHORIZE intent
  @PostMapping("/api/orders")
  public ResponseEntity<?> createOrder(@RequestBody OrderRequest orderRequest) {
    try {
      OrdersCreateRequest request = new OrdersCreateRequest();
      request.prefer("return=representation");
      request.body(new OrderRequest()
        .intent("AUTHORIZE")
        .purchaseUnits(List.of(
          new PurchaseUnitRequest()
            .amount(new Money()
              .currencyCode("USD")
              .value(orderRequest.getAmount() != null ?
                orderRequest.getAmount() : "100.00")
            )
        ))
      );

      HttpResponse<Order> response = httpClient.execute(request);
      return ResponseEntity.ok(Map.of("id", response.result().id()));

    } catch (Exception e) {
      return ResponseEntity.status(500).body(
        Map.of("error", e.getMessage())
      );
    }
  }

  // Capture authorization later
  @PostMapping("/api/orders/{orderId}/capture")
  public ResponseEntity<?> captureAuthorization(
    @PathVariable String orderId,
    @RequestBody Map<String, String> requestBody
  ) {
    try {
      String authorizationId = requestBody.get("authorizationId");
      AuthorizationsCaptureRequest request = new AuthorizationsCaptureRequest(authorizationId);

      HttpResponse<Capture> response = httpClient.execute(request);
      Capture capture = response.result();

      return ResponseEntity.ok(Map.of(
        "status", capture.status(),
        "captureId", capture.id()
      ));

    } catch (HttpClientException e) {
      if (e.statusCode() == 422) {
        return ResponseEntity.badRequest().body(
          Map.of("error", "Authorization expired or invalid")
        );
      }
      return ResponseEntity.status(500).body(
        Map.of("error", e.getMessage())
      );
    }
  }
  ```

  ```php PHP lines expandable theme={null}
  <?php
  use PayPalCheckoutSdk\Core\SandboxEnvironment;
  use PayPalCheckoutSdk\Core\PayPalHttpClient;
  use PayPalCheckoutSdk\Orders\OrdersCreateRequest;
  use PayPalCheckoutSdk\Payments\AuthorizationsCaptureRequest;

  $environment = new SandboxEnvironment(
    getenv('PAYPAL_CLIENT_ID'),
    getenv('PAYPAL_CLIENT_SECRET')
  );
  $client = new PayPalHttpClient($environment);

  // Create order with AUTHORIZE intent
  $app->post('/api/orders', function ($request, $response) use ($client) {
    $body = $request->getParsedBody();

    $orderRequest = new OrdersCreateRequest();
    $orderRequest->prefer("return=representation");
    $orderRequest->body = [
      "intent" => "AUTHORIZE",
      "purchase_units" => [[
        "amount" => [
          "currency_code" => "USD",
          "value" => $body['amount'] ?? "100.00"
        ]
      ]]
    ];

    try {
      $orderResponse = $client->execute($orderRequest);
      $response->getBody()->write(json_encode([
        "id" => $orderResponse->result->id
      ]));
      return $response->withHeader('Content-Type', 'application/json');

    } catch (Exception $e) {
      $response->getBody()->write(json_encode([
        "error" => $e->getMessage()
      ]));
      return $response->withStatus(500)->withHeader('Content-Type', 'application/json');
    }
  });

  // Capture authorization later
  $app->post('/api/orders/{orderId}/capture', function ($request, $response, $args) use ($client) {
    $body = $request->getParsedBody();
    $authorizationId = $body['authorizationId'];

    $captureRequest = new AuthorizationsCaptureRequest($authorizationId);

    try {
      $captureResponse = $client->execute($captureRequest);
      $capture = $captureResponse->result;

      $response->getBody()->write(json_encode([
        "status" => $capture->status,
        "captureId" => $capture->id
      ]));
      return $response->withHeader('Content-Type', 'application/json');

    } catch (HttpException $e) {
      if ($e->statusCode === 422) {
        $response->getBody()->write(json_encode([
          "error" => "Authorization expired or invalid"
        ]));
        return $response->withStatus(400)->withHeader('Content-Type', 'application/json');
      }

      $response->getBody()->write(json_encode([
        "error" => $e->getMessage()
      ]));
      return $response->withStatus(500)->withHeader('Content-Type', 'application/json');
    }
  });
  ```

  ```ruby Ruby lines expandable theme={null}
  require 'paypal-sdk'

  # Configure PayPal SDK
  PayPal::SDK.configure(
    :mode => "sandbox",
    :app_id => ENV['PAYPAL_APP_ID'],
    :client_id => ENV['PAYPAL_CLIENT_ID'],
    :client_secret => ENV['PAYPAL_CLIENT_SECRET']
  )

  # Create order with AUTHORIZE intent
  post '/api/orders' do
    request_body = JSON.parse(request.body.read)

    begin
      order = PayPal::SDK::OrdersApi::Order.new(
        intent: "AUTHORIZE",
        purchase_units: [{
          amount: {
            currency_code: "USD",
            value: request_body['amount'] || "100.00"
          }
        }]
      )

      if order.create
        content_type :json
        { id: order.id }.to_json
      else
        status 500
        { error: order.error }.to_json
      end

    rescue => e
      status 500
      { error: e.message }.to_json
    end
  end

  # Capture authorization later
  post '/api/orders/:order_id/capture' do
    order_id = params['order_id']
    request_body = JSON.parse(request.body.read)
    authorization_id = request_body['authorizationId']

    begin
      authorization = PayPal::SDK::PaymentsApi::Authorization.find(authorization_id)

      if authorization.capture
        content_type :json
        {
          status: authorization.status,
          captureId: authorization.id
        }.to_json
      else
        error = authorization.error
        if error['name'] == 'AUTHORIZATION_EXPIRED'
          status 400
          { error: 'Authorization expired or invalid' }.to_json
        else
          status 500
          { error: error['message'] }.to_json
        end
      end

    rescue => e
      status 500
      { error: e.message }.to_json
    end
  end
  ```
</CodeGroup>

## Test endpoints

<Info>
  Endpoints:

  * [`/v2/checkout/orders/{id}/authorize`](/reference/api/rest/orders/authorize-payment-for-order)
  * [`/v2/payments/authorizations/{authorization_id}/capture`](/reference/api/rest/authorizations/capture-authorized-payment)
</Info>

<CodeGroup>
  ```bash cURL lines expandable theme={null}
  # 1. Create authorization (returns orderId)
  curl -X POST http://localhost:3000/api/orders \
    -H "Content-Type: application/json" \
    -d '{"amount": "100.00"}'

  # Expected response:
  # {"id":"5O190127TN364715T"}

  # 2. Later, capture the authorization (use authorizationId from PayPal)
  curl -X POST http://localhost:3000/api/orders/ORDER_ID/capture \
    -H "Content-Type: application/json" \
    -d '{"authorizationId": "AUTH_ID_FROM_PAYPAL"}'

  # Expected response:
  # {"status":"COMPLETED","captureId":"3C679366HH908993F"}
  ```

  ```javascript Node.js lines expandable theme={null}
  // 1. Create authorization
  const createResponse = await fetch('http://localhost:3000/api/orders', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ amount: '100.00' })
  });
  const order = await createResponse.json();
  console.log('Order created:', order);
  // Expected: {"id":"5O190127TN364715T"}

  // 2. Later, capture the authorization
  const captureResponse = await fetch('http://localhost:3000/api/orders/ORDER_ID/capture', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ authorizationId: 'AUTH_ID_FROM_PAYPAL' })
  });
  const capture = await captureResponse.json();
  console.log('Capture result:', capture);
  // Expected: {"status":"COMPLETED","captureId":"3C679366HH908993F"}
  ```

  ```python Python lines expandable theme={null}
  import requests

  # 1. Create authorization
  create_response = requests.post(
    'http://localhost:3000/api/orders',
    headers={'Content-Type': 'application/json'},
    json={'amount': '100.00'}
  )
  print('Order created:', create_response.json())
  # Expected: {"id":"5O190127TN364715T"}

  # 2. Later, capture the authorization
  capture_response = requests.post(
    'http://localhost:3000/api/orders/ORDER_ID/capture',
    headers={'Content-Type': 'application/json'},
    json={'authorizationId': 'AUTH_ID_FROM_PAYPAL'}
  )
  print('Capture result:', capture_response.json())
  # Expected: {"status":"COMPLETED","captureId":"3C679366HH908993F"}
  ```

  ```java Java lines expandable theme={null}
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.net.URI;

  HttpClient client = HttpClient.newHttpClient();

  // 1. Create authorization
  String createBody = "{\"amount\":\"100.00\"}";
  HttpRequest createRequest = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:3000/api/orders"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(createBody))
    .build();

  HttpResponse<String> createResponse = client.send(
    createRequest,
    HttpResponse.BodyHandlers.ofString()
  );
  System.out.println("Order created: " + createResponse.body());
  // Expected: {"id":"5O190127TN364715T"}

  // 2. Later, capture the authorization
  String captureBody = "{\"authorizationId\":\"AUTH_ID_FROM_PAYPAL\"}";
  HttpRequest captureRequest = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:3000/api/orders/ORDER_ID/capture"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(captureBody))
    .build();

  HttpResponse<String> captureResponse = client.send(
    captureRequest,
    HttpResponse.BodyHandlers.ofString()
  );
  System.out.println("Capture result: " + captureResponse.body());
  // Expected: {"status":"COMPLETED","captureId":"3C679366HH908993F"}
  ```

  ```php PHP lines expandable theme={null}
  <?php
  // 1. Create authorization
  $createData = json_encode(['amount' => '100.00']);

  $createResponse = file_get_contents(
    'http://localhost:3000/api/orders',
    false,
    stream_context_create([
      'http' => [
        'method' => 'POST',
        'header' => 'Content-Type: application/json',
        'content' => $createData
      ]
    ])
  );
  echo "Order created: " . $createResponse . "\n";
  // Expected: {"id":"5O190127TN364715T"}

  // 2. Later, capture the authorization
  $captureData = json_encode(['authorizationId' => 'AUTH_ID_FROM_PAYPAL']);

  $captureResponse = file_get_contents(
    'http://localhost:3000/api/orders/ORDER_ID/capture',
    false,
    stream_context_create([
      'http' => [
        'method' => 'POST',
        'header' => 'Content-Type: application/json',
        'content' => $captureData
      ]
    ])
  );
  echo "Capture result: " . $captureResponse . "\n";
  // Expected: {"status":"COMPLETED","captureId":"3C679366HH908993F"}
  ```

  ```ruby Ruby lines expandable theme={null}
  require 'net/http'
  require 'json'

  # 1. Create authorization
  uri = URI('http://localhost:3000/api/orders')
  create_request = Net::HTTP::Post.new(uri)
  create_request['Content-Type'] = 'application/json'
  create_request.body = { amount: '100.00' }.to_json

  create_response = Net::HTTP.start(uri.hostname, uri.port) do |http|
    http.request(create_request)
  end
  puts "Order created: #{create_response.body}"
  # Expected: {"id":"5O190127TN364715T"}

  # 2. Later, capture the authorization
  capture_uri = URI('http://localhost:3000/api/orders/ORDER_ID/capture')
  capture_request = Net::HTTP::Post.new(capture_uri)
  capture_request['Content-Type'] = 'application/json'
  capture_request.body = { authorizationId: 'AUTH_ID_FROM_PAYPAL' }.to_json

  capture_response = Net::HTTP.start(capture_uri.hostname, capture_uri.port) do |http|
    http.request(capture_request)
  end
  puts "Capture result: #{capture_response.body}"
  # Expected: {"status":"COMPLETED","captureId":"3C679366HH908993F"}
  ```
</CodeGroup>

## Best practices

* **Capture within 3-day honor period:** Authorization success rates are highest during the 3-day honor period. After the payment is authorized, ship within 3 days.
* **Track authorization expiration:** Store the date when the authorization was created in your database. Alert when approaching day 29 and have a process to handle expiring authorizations.
* **Handle partial captures:** You can capture any amount up to the authorized total. The remainder can be voided or left to expire. For multiple shipments, use multiple partial captures.
* **Void uncaptured authorizations promptly:** If you can't fulfill an order, void the authorization immediately to release customer funds.
* **Communicate holds to customers:** Inform customers that their payment is authorized, but not yet charged. Inform them when the actual charge will occur.
* **Monitor authorization validity:** Authorizations can be voided by the customer's bank or PayPal. Handle capture failures gracefully.

## Important details

* **Find authorization IDs:** The authorization ID is in the order approval response at `purchase_units[0].payments.authorizations[0].id`. Store this value in your database immediately.
* **Authorization expiration:** You have up to 29 days to capture payment. Captures are most likely to succeed during the 3-day honor period. After 29 days, the authorization automatically expires, and you'll need to create a new order to charge the customer.
* **Partial captures:** You can capture any amount up to the authorized total.
* **Extending authorizations:** Use reauthorization between days 4-29 to extend an authorization. See [Reauthorize an authorization](/payments/methods/paypal/reauthorize).

## Test your integration

Sandbox authorizations don't expire after 29 days. Test authorizations with negative testing instead.

### Standard testing

| Test scenario            | Setup                                                                   | Expected result                             |
| :----------------------- | :---------------------------------------------------------------------- | :------------------------------------------ |
| Authorize and capture    | Create an order with `intent: "AUTHORIZE"`, then capture after 1 minute | Authorization successful, capture completes |
| Partial capture          | Authorize \$100, capture \$60                                           | \$60 captured, \$40 remains available       |
| Invalid authorization ID | Use `"INVALID_AUTH_123"` as auth ID                                     | Returns 404 error                           |
| Capture after 5 days     | Wait 5 days past honor period                                           | Capture may succeed with lower rate         |

### Negative testing

1. Make sure to enable negative testing in your sandbox business account as described in the [quick start prerequisites](/payments/methods/paypal/integrate#prerequisites).
2. In the `.env` file, set `ENABLE_NEGATIVE_TESTING=true` and set `NEGATIVE_TEST_TYPE` to one of the error codes in the table.
3. Restart the server after changing the `.env` file: `node server.js`.

| Test scenario         | Error code                       | Expected result                                           |
| :-------------------- | :------------------------------- | :-------------------------------------------------------- |
| Expired authorization | `AUTHORIZATION_EXPIRED`          | Returns 422 error with "Authorization expired or invalid" |
| Already captured      | `AUTHORIZATION_ALREADY_CAPTURED` | Returns 422 error with "Authorization already captured"   |

## Go-live checklist

* Implement authorization tracking system.
* Integrate capture process with fulfillment workflow.
* Configure authorization expiration monitoring.
* Test customer communication about holds.
* Test with real \$1 authorization and capture.

## Post-launch monitoring

These values are suggested monitoring thresholds for your integration, not performance guarantees from PayPal.

| Metric                        | Target      | Action if below target                                |
| :---------------------------- | :---------- | :---------------------------------------------------- |
| Authorization success rate    | 95%         | Investigate authorization failures with issuing banks |
| Capture rate within 3 days    | 90%         | Optimize fulfillment workflow for faster processing   |
| Authorization expiration rate | \<2%        | Improve expiration alerts and capture automation      |
| API response time             | \<2 seconds | Check PayPal API status                               |
| Capture success rate          | 98%         | Review expired or voided authorizations               |


# PayPal payments quick start integration
Source: https://docs.paypal.ai/payments/methods/paypal/integrate



Accept PayPal payments on your website with the minimum amount of code required. You might use this ultra light integration as a proof of concept, basic e-commerce checkout, or simple donation form.

This integration creates an order and captures a payment. It uses PayPal's JavaScript SDK on the client side and server SDK on the server side.

The JavaScript SDK renders the PayPal button and handles the UI. The server SDK creates and captures orders with your app credentials.

<Tip>[Check out a sample integration in GitHub](https://github.com/paypal-examples/v6-web-sdk-sample-integration).</Tip>

## Eligibility

This integration works [everywhere PayPal is available](https://www.paypal.com/webapps/mpp/country-worldwide).

<View title="JavaScript SDK">
  ## Prerequisites

  * Create a [PayPal developer account](https://developer.paypal.com/dashboard/).
  * Get a [client ID and secret](/developer/how-to/api/get-started#1-get-your-client-id-and-client-secret).
  * (Optional) Enable negative testing in the developer dashboard:
    1. Go to **Dashboard** > **Sandbox** > **Accounts**.
    2. Select **...** on your sandbox business account and select **View/Edit**.
    3. Enable **Negative Testing** and save.

  ## Create project structure

  Choose your preferred language and set up the project structure.

  <CodeGroup>
    ```bash Node.js lines expandable theme={null}
    # Create project structure
    mkdir paypal-minimal && cd paypal-minimal
    npm init -y
    npm install express @paypal/checkout-server-sdk dotenv
    mkdir public

    # Create .env file with development defaults
    cat > .env << 'EOF'
    # Development/Sandbox Configuration (Default)
    # ==========================================
    PAYPAL_CLIENT_ID=your_sandbox_client_id
    PAYPAL_CLIENT_SECRET=your_sandbox_secret
    NODE_ENV=development
    PORT=3000

    # Negative Testing (Sandbox Only)
    # --------------------------------
    # Set to true to enable error simulation in sandbox
    ENABLE_NEGATIVE_TESTING=false
    NEGATIVE_TEST_TYPE=INSUFFICIENT_FUNDS
    # Options: INSUFFICIENT_FUNDS, INSTRUMENT_DECLINED, TRANSACTION_REFUSED, 
    # INTERNAL_SERVER_ERROR, DUPLICATE_INVOICE_ID

    # Production Configuration (Uncomment to use)
    # ==========================================
    # PAYPAL_CLIENT_ID=your_production_client_id
    # PAYPAL_CLIENT_SECRET=your_production_secret
    # NODE_ENV=production
    # PORT=3000
    EOF

    # Create empty files
    touch server.js
    touch public/index.html

    echo "✅ Project structure created! Now copy the code below into the files."
    ```

    ```bash Python lines expandable theme={null}
    # Create project structure
    mkdir paypal-minimal && cd paypal-minimal
    python -m venv venv
    source venv/bin/activate  # On Windows: venv\Scripts\activate
    pip install flask paypalrestsdk python-dotenv
    mkdir templates static

    # Create .env file with development defaults
    cat > .env << 'EOF'
    # Development/Sandbox Configuration (Default)
    # ==========================================
    PAYPAL_CLIENT_ID=your_sandbox_client_id
    PAYPAL_CLIENT_SECRET=your_sandbox_secret
    FLASK_ENV=development
    PORT=3000

    # Negative Testing (Sandbox Only)
    # --------------------------------
    # Set to true to enable error simulation in sandbox
    ENABLE_NEGATIVE_TESTING=false
    NEGATIVE_TEST_TYPE=INSUFFICIENT_FUNDS
    # Options: INSUFFICIENT_FUNDS, INSTRUMENT_DECLINED, TRANSACTION_REFUSED, 
    # INTERNAL_SERVER_ERROR, DUPLICATE_INVOICE_ID

    # Production Configuration (Uncomment to use)
    # ==========================================
    # PAYPAL_CLIENT_ID=your_production_client_id
    # PAYPAL_CLIENT_SECRET=your_production_secret
    # FLASK_ENV=production
    # PORT=3000
    EOF

    # Create requirements.txt
    cat > requirements.txt << 'EOF'
    flask
    paypalrestsdk
    python-dotenv
    EOF

    # Create empty files
    touch app.py
    touch templates/index.html

    echo "✅ Project structure created! Now copy the code below into the files."
    ```

    ```bash Java lines expandable theme={null}
    # Create Maven project structure
    mkdir paypal-minimal && cd paypal-minimal
    mkdir -p src/main/java/com/paypal/demo
    mkdir -p src/main/resources
    mkdir -p src/main/resources/static

    # Create pom.xml with dependencies
    cat > pom.xml << 'EOF'
    <?xml version="1.0" encoding="UTF-8"?>
    <project xmlns="http://maven.apache.org/POM/4.0.0"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
             http://maven.apache.org/xsd/maven-4.0.0.xsd">
        <modelVersion>4.0.0</modelVersion>

        <groupId>com.paypal</groupId>
        <artifactId>paypal-minimal</artifactId>
        <version>1.0.0</version>

        <parent>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-parent</artifactId>
            <version>3.1.0</version>
        </parent>

        <dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-web</artifactId>
            </dependency>
            <dependency>
                <groupId>com.paypal.sdk</groupId>
                <artifactId>checkout-sdk</artifactId>
                <version>1.0.5</version>
            </dependency>
        </dependencies>
    </project>
    EOF

    # Create application.properties
    cat > src/main/resources/application.properties << 'EOF'
    # Development/Sandbox Configuration (Default)
    paypal.client.id=your_sandbox_client_id
    paypal.client.secret=your_sandbox_secret
    paypal.mode=sandbox
    server.port=3000

    # Negative Testing (Sandbox Only)
    # Set to true to enable error simulation in sandbox
    enable.negative.testing=false
    negative.test.type=INSUFFICIENT_FUNDS
    # Options: INSUFFICIENT_FUNDS, INSTRUMENT_DECLINED, TRANSACTION_REFUSED, 
    # INTERNAL_SERVER_ERROR, DUPLICATE_INVOICE_ID

    # Production Configuration (comment above, uncomment below)
    # paypal.client.id=your_production_client_id
    # paypal.client.secret=your_production_secret
    # paypal.mode=live
    # server.port=3000
    EOF

    # Create empty Java files
    touch src/main/java/com/paypal/demo/PayPalController.java
    touch src/main/java/com/paypal/demo/Application.java
    touch src/main/resources/static/index.html

    echo "✅ Project structure created! Now copy the code below into the files."
    ```

    ```bash PHP lines expandable theme={null}
    # Create project structure
    mkdir paypal-minimal && cd paypal-minimal
    composer init -n
    composer require paypal/paypal-checkout-sdk vlucas/phpdotenv
    mkdir public

    # Create .env file with development defaults
    cat > .env << 'EOF'
    # Development/Sandbox Configuration (Default)
    # ==========================================
    PAYPAL_CLIENT_ID=your_sandbox_client_id
    PAYPAL_CLIENT_SECRET=your_sandbox_secret
    APP_ENV=development
    PORT=3000

    # Negative Testing (Sandbox Only)
    # --------------------------------
    # Set to true to enable error simulation in sandbox
    ENABLE_NEGATIVE_TESTING=false
    NEGATIVE_TEST_TYPE=INSUFFICIENT_FUNDS
    # Options: INSUFFICIENT_FUNDS, INSTRUMENT_DECLINED, TRANSACTION_REFUSED, 
    # INTERNAL_SERVER_ERROR, DUPLICATE_INVOICE_ID

    # Production Configuration (Uncomment to use)
    # ==========================================
    # PAYPAL_CLIENT_ID=your_production_client_id
    # PAYPAL_CLIENT_SECRET=your_production_secret
    # APP_ENV=production
    # PORT=3000
    EOF

    # Create empty files
    touch index.php
    touch public/index.html

    echo "✅ Project structure created! Now copy the code below into the files."
    ```

    ```bash Ruby lines expandable theme={null}
    # Create project structure
    mkdir paypal-minimal && cd paypal-minimal
    bundle init

    # Add gems to Gemfile
    cat >> Gemfile << 'EOF'
    gem 'sinatra'
    gem 'paypal-checkout-sdk'
    gem 'dotenv'
    EOF

    bundle install
    mkdir public

    # Create .env file with development defaults
    cat > .env << 'EOF'
    # Development/Sandbox Configuration (Default)
    # ==========================================
    PAYPAL_CLIENT_ID=your_sandbox_client_id
    PAYPAL_CLIENT_SECRET=your_sandbox_secret
    RACK_ENV=development
    PORT=3000

    # Negative Testing (Sandbox Only)
    # --------------------------------
    # Set to true to enable error simulation in sandbox
    ENABLE_NEGATIVE_TESTING=false
    NEGATIVE_TEST_TYPE=INSUFFICIENT_FUNDS
    # Options: INSUFFICIENT_FUNDS, INSTRUMENT_DECLINED, TRANSACTION_REFUSED, 
    # INTERNAL_SERVER_ERROR, DUPLICATE_INVOICE_ID

    # Production Configuration (Uncomment to use)
    # ==========================================
    # PAYPAL_CLIENT_ID=your_production_client_id
    # PAYPAL_CLIENT_SECRET=your_production_secret
    # RACK_ENV=production
    # PORT=3000
    EOF

    # Create empty files
    touch app.rb
    touch public/index.html

    echo "✅ Project structure created! Now copy the code below into the files."
    ```
  </CodeGroup>

  ## Set up back end

  Choose your preferred language and copy the code into your server file:

  <CodeGroup>
    ```bash cURL lines expandable theme={null}
    # Create order
    curl -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer ACCESS_TOKEN" \
      -d '{
        "intent": "CAPTURE",
        "purchase_units": [{
          "amount": {
            "currency_code": "USD",
            "value": "10.00"
          }
        }]
      }'

    # Capture order
    curl -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER_ID/capture \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer ACCESS_TOKEN"
    ```

    ```javascript Node.js lines expandable theme={null}
    require('dotenv').config();
    const express = require('express');
    const paypal = require('@paypal/checkout-server-sdk');

    const app = express();
    app.use(express.json());
    app.use(express.static('public'));

    // PayPal configuration
    const environment = process.env.NODE_ENV === 'production'
      ? new paypal.core.LiveEnvironment(process.env.PAYPAL_CLIENT_ID, process.env.PAYPAL_CLIENT_SECRET)
      : new paypal.core.SandboxEnvironment(process.env.PAYPAL_CLIENT_ID, process.env.PAYPAL_CLIENT_SECRET);
    const client = new paypal.core.PayPalHttpClient(environment);

    // Helper for negative testing
    const addNegativeTesting = (request) => {
      if (process.env.NODE_ENV !== 'production' && process.env.ENABLE_NEGATIVE_TESTING === 'true' && process.env.NEGATIVE_TEST_TYPE) {
        request.headers['PayPal-Mock-Response'] = JSON.stringify({ mock_application_codes: process.env.NEGATIVE_TEST_TYPE });
      }
    };

    // Create order
    app.post('/api/orders', async (req, res) => {
      const request = new paypal.orders.OrdersCreateRequest();
      addNegativeTesting(request);
      request.requestBody({
        intent: 'CAPTURE',
        purchase_units: [{ amount: { currency_code: 'USD', value: req.body.amount || '10.00' } }]
      });

      try {
        const order = await client.execute(request);
        res.json({ id: order.result.id });
      } catch (err) {
        res.status(500).json({ error: err.message });
      }
    });

    // Capture order
    app.post('/api/orders/:orderID/capture', async (req, res) => {
      const request = new paypal.orders.OrdersCaptureRequest(req.params.orderID);
      addNegativeTesting(request);

      try {
        const capture = await client.execute(request);
        res.json({ id: capture.result.id, status: capture.result.status });
      } catch (err) {
        res.status(500).json({ error: err.message });
      }
    });

    app.listen(process.env.PORT || 3000, () => {
      console.log(`Server running on port ${process.env.PORT || 3000} in ${process.env.NODE_ENV === 'production' ? 'production' : 'sandbox'} mode`);
    });
    ```

    ```python Python lines expandable theme={null}
    from flask import Flask, request, jsonify
    from paypalrestsdk import Api, Order
    import os

    app = Flask(__name__)

    # Configure PayPal SDK
    api = Api({
      'mode': 'sandbox' if os.environ.get('FLASK_ENV') != 'production' else 'live',
      'client_id': os.environ['PAYPAL_CLIENT_ID'],
      'client_secret': os.environ['PAYPAL_CLIENT_SECRET']
    })

    # Create order
    @app.route('/api/orders', methods=['POST'])
    def create_order():
      try:
        order = Order({
          "intent": "CAPTURE",
          "purchase_units": [{
            "amount": {
              "currency_code": "USD",
              "value": request.json.get('amount', '10.00')
            }
          }]
        })

        if order.create():
          return jsonify({"id": order.id})
        else:
          return jsonify({"error": order.error}), 500
      except Exception as e:
        return jsonify({"error": str(e)}), 500

    # Capture order
    @app.route('/api/orders/<order_id>/capture', methods=['POST'])
    def capture_order(order_id):
      try:
        order = Order.find(order_id)

        if order.capture():
          return jsonify({
            "id": order.id,
            "status": order.status
          })
        else:
          return jsonify({"error": order.error}), 500
      except Exception as e:
        return jsonify({"error": str(e)}), 500

    if __name__ == '__main__':
      app.run(port=int(os.environ.get('PORT', 3000)))
    ```

    ```java Java lines expandable theme={null}
    import com.paypal.core.PayPalEnvironment;
    import com.paypal.core.PayPalHttpClient;
    import com.paypal.orders.OrdersCreateRequest;
    import com.paypal.orders.OrdersCaptureRequest;
    import com.paypal.orders.Order;
    import org.springframework.web.bind.annotation.*;
    import org.springframework.http.ResponseEntity;

    @RestController
    @RequestMapping("/api")
    public class PayPalController {
      private PayPalHttpClient httpClient;

      public PayPalController() {
        String env = System.getenv("NODE_ENV");
        PayPalEnvironment environment = "production".equals(env)
          ? new LiveEnvironment(
              System.getenv("PAYPAL_CLIENT_ID"),
              System.getenv("PAYPAL_CLIENT_SECRET")
            )
          : new SandboxEnvironment(
              System.getenv("PAYPAL_CLIENT_ID"),
              System.getenv("PAYPAL_CLIENT_SECRET")
            );
        this.httpClient = new PayPalHttpClient(environment);
      }

      // Create order
      @PostMapping("/orders")
      public ResponseEntity<?> createOrder(@RequestBody OrderRequest orderRequest) {
        try {
          OrdersCreateRequest request = new OrdersCreateRequest();
          request.requestBody(new OrderRequestBody()
            .intent("CAPTURE")
            .purchaseUnits(List.of(
              new PurchaseUnitRequest()
                .amount(new AmountWithBreakdown()
                  .currencyCode("USD")
                  .value(orderRequest.getAmount() != null ? orderRequest.getAmount() : "10.00")
                )
            ))
          );

          HttpResponse<Order> response = httpClient.execute(request);
          Order order = response.result();

          return ResponseEntity.ok(Map.of("id", order.id()));
        } catch (Exception e) {
          return ResponseEntity.status(500).body(Map.of("error", e.getMessage()));
        }
      }

      // Capture order
      @PostMapping("/orders/{orderId}/capture")
      public ResponseEntity<?> captureOrder(@PathVariable String orderId) {
        try {
          OrdersCaptureRequest request = new OrdersCaptureRequest(orderId);
          HttpResponse<Order> response = httpClient.execute(request);
          Order order = response.result();

          return ResponseEntity.ok(Map.of(
            "id", order.id(),
            "status", order.status()
          ));
        } catch (Exception e) {
          return ResponseEntity.status(500).body(Map.of("error", e.getMessage()));
        }
      }
    }
    ```

    ```php PHP lines expandable theme={null}
    <?php
    require __DIR__ . '/vendor/autoload.php';

    use PayPalCheckoutSdk\Core\PayPalHttpClient;
    use PayPalCheckoutSdk\Core\SandboxEnvironment;
    use PayPalCheckoutSdk\Core\ProductionEnvironment;
    use PayPalCheckoutSdk\Orders\OrdersCreateRequest;
    use PayPalCheckoutSdk\Orders\OrdersCaptureRequest;

    // PayPal configuration
    $env = getenv('APP_ENV');
    $environment = ($env === 'production')
      ? new ProductionEnvironment(getenv('PAYPAL_CLIENT_ID'), getenv('PAYPAL_CLIENT_SECRET'))
      : new SandboxEnvironment(getenv('PAYPAL_CLIENT_ID'), getenv('PAYPAL_CLIENT_SECRET'));
    $client = new PayPalHttpClient($environment);

    // Create order
    if ($_SERVER['REQUEST_METHOD'] === 'POST' && $_SERVER['REQUEST_URI'] === '/api/orders') {
      $input = json_decode(file_get_contents('php://input'), true);
      $request = new OrdersCreateRequest();
      $request->body = [
        'intent' => 'CAPTURE',
        'purchase_units' => [[
          'amount' => [
            'currency_code' => 'USD',
            'value' => $input['amount'] ?? '10.00'
          ]
        ]]
      ];

      try {
        $response = $client->execute($request);
        echo json_encode(['id' => $response->result->id]);
      } catch (Exception $e) {
        http_response_code(500);
        echo json_encode(['error' => $e->getMessage()]);
      }
    }

    // Capture order
    if ($_SERVER['REQUEST_METHOD'] === 'POST' && preg_match('/\/api\/orders\/(.+)\/capture/', $_SERVER['REQUEST_URI'], $matches)) {
      $orderId = $matches[1];
      $request = new OrdersCaptureRequest($orderId);

      try {
        $response = $client->execute($request);
        echo json_encode([
          'id' => $response->result->id,
          'status' => $response->result->status
        ]);
      } catch (Exception $e) {
        http_response_code(500);
        echo json_encode(['error' => $e->getMessage()]);
      }
    }
    ?>
    ```

    ```ruby Ruby lines expandable theme={null}
    require 'sinatra'
    require 'paypal-checkout-sdk'
    require 'json'

    # PayPal configuration
    environment = ENV['RACK_ENV'] == 'production' ?
      PayPal::LiveEnvironment.new(ENV['PAYPAL_CLIENT_ID'], ENV['PAYPAL_CLIENT_SECRET']) :
      PayPal::SandboxEnvironment.new(ENV['PAYPAL_CLIENT_ID'], ENV['PAYPAL_CLIENT_SECRET'])
    client = PayPal::PayPalHttpClient.new(environment)

    # Create order
    post '/api/orders' do
      content_type :json
      request_body = JSON.parse(request.body.read)

      order_request = PayPalCheckoutSdk::Orders::OrdersCreateRequest.new
      order_request.request_body({
        intent: 'CAPTURE',
        purchase_units: [{
          amount: {
            currency_code: 'USD',
            value: request_body['amount'] || '10.00'
          }
        }]
      })

      begin
        response = client.execute(order_request)
        { id: response.result.id }.to_json
      rescue StandardError => e
        status 500
        { error: e.message }.to_json
      end
    end

    # Capture order
    post '/api/orders/:order_id/capture' do
      content_type :json

      capture_request = PayPalCheckoutSdk::Orders::OrdersCaptureRequest.new(params[:order_id])

      begin
        response = client.execute(capture_request)
        {
          id: response.result.id,
          status: response.result.status
        }.to_json
      rescue StandardError => e
        status 500
        { error: e.message }.to_json
      end
    end
    ```
  </CodeGroup>

  ## Set up front end

  Open the `public/index.html` file in a code editor and copy and paste the following code. Replace `YOUR_CLIENT_ID` with the client ID created in the prerequisites.

  <Tip>
    If your app uses PayPal buttons across multiple pages or a modular JavaScript architecture, see [Multipage and modular app issues](/payments/methods/paypal/troubleshoot#multipage-and-modular-app-issues).
  </Tip>

  ```html lines expandable theme={null}
  <!doctype html>
  <html lang="en">
  <head>
      <meta charset="UTF-8" />
      <title>PayPal Checkout</title>
  </head>
  <body>
    <div id='paypal-button-container'></div>
    <div id="result-message"></div>
    <script>
      // Pass the createOrder, onApprove, onCancel, and onError callbacks to the SDK
      async function createOrder (data) {
          const response = await fetch(
          "/api/orders",
          {
            method: "POST",
            headers: {
              "Content-Type": "application/json",
            },
            // We don't recommend passing order amounts from the client
            // Your API should exchange a SKU for amount values
            body: JSON.stringify({ sku: 'BDUR24586' })
          },
        );
        const { id } = await response.json();
        return { orderId: id };
      };

      async function onApprove (data) {
        const { orderId } = data;
        const response = await fetch(
          `/api/orders/${orderId}/capture`,
          {
            method: "POST",
            headers: {
              "Content-Type": "application/json",
            },
          },
        );
        const orderData = await response.json();
        return orderData;
      };

      function onCancel (data) {
        document.getElementById('result-message').innerHTML = 
          `<p style="color: orange;">Payment cancelled</p>`;
      };

      function onError (err) {
        console.error('PayPal Error:', err);
        let errorMessage = 'An error occurred. Please try again.';
        // Handle specific error codes
        if (err.message && err.message.includes('INSUFFICIENT_FUNDS')) {
          errorMessage = 'Payment declined due to insufficient funds.';
        } else if (err.message && err.message.includes('INSTRUMENT_DECLINED')) {
          errorMessage = 'Your payment method was declined. Please try another.';
        } else if (err.message && err.message.includes('TRANSACTION_REFUSED')) {
          errorMessage = 'Transaction was refused. Please contact support.';
        } else if (err.message && err.message.includes('DUPLICATE_INVOICE')) {
          errorMessage = 'This order has already been processed. Please refresh and try again.';
        }
        document.getElementById('result-message').innerHTML = 
          `<p style="color: red;">${errorMessage}</p>`;
      };

      // After the browser is done downloading the SDK, it will invoke onLoad()
      // and begin the SDK setup
      async function onLoad() {
        try {
          const sdkInstance = await window.paypal.createInstance({
            clientId: "YOUR_CLIENT_ID", // clientId is safe to put in plaintext on the client
            components: ["paypal-payments"]
          });

          const eligibility = await sdkInstance.findEligibleMethods();
          const isPayPalEligible = eligibility.isEligible('paypal');

          if (isPayPalEligible) {
            const paypalButton = document.createElement('paypal-button');
            document.querySelector('#paypal-button-container').append(paypalButton);

            const paypalCheckoutSession = await sdkInstance.createPayPalOneTimePaymentSession({
              onApprove,
              onCancel,
              onError
            });

          paypalButton.addEventListener("click", async () => {
            try {
              // Get the promise reference by invoking createOrder()
              // Do not await this async function since it can cause transient activation issues
              const createOrderPromise = createOrder();
              await paypalCheckoutSession.start(
                { presentationMode: "auto" },
                createOrderPromise,
              );
            } catch (error) {
              console.error(error);
            }
          });
          }
        } catch (error) {
          console.error(error);
        }
      }
    </script>
    <script async src="https://www.sandbox.paypal.com/web-sdk/v6/core"  onload='onLoad()'></script>
  </body>
  </html>
  ```

  ## Set your client ID and secret

  Open the `.env` file in a code editor and replace `your_sandbox_client_id` and `your_sandbox_secret` with the client ID and secret you created for your app in the prerequisites.

  ## Run the application locally

  Start the server:

  ```bash lines theme={null}
  node server.js
  ```

  Open the following URL in your browser. You should see a PayPal button.

  ```
  http://localhost:3000
  ```

  [Don't see the button?](/payments/methods/paypal/troubleshoot#the-paypal-button-does-not-appear)

  ## Best practices

  Use the following best practices to ensure secure, reliable, and maintainable integrations when building your checkout experience.

  * **Start minimal and expand later:** This code works in production. Add features as needed.
  * **Use environment variables:** Never hardcode credentials. Keep the .env file out of Git.
  * **Create orders on the server:** Never create orders in the browser due to security risks. Always use the server.
  * **Test in sandbox first:** Use sandbox accounts to test payments before going live.
  * **Store transaction IDs:** Save capture IDs for refunds, disputes, and record keeping.

  ## Test your integration

  Before testing, make sure you have sandbox account credentials for both buyer and seller roles. [Get sandbox account credentials](/developer/how-to/api/get-started#3-get-sandbox-account-credentials).

  ### Standard testing

  Use the following standard test scenarios to verify your checkout handles key outcomes.

  | Test scenario      | Setup            | Expected result                                 |
  | :----------------- | :--------------- | :---------------------------------------------- |
  | Successful payment | Default settings | Green success message and transaction ID shown. |
  | Cancelled payment  | Default settings | Orange cancel message shown.                    |
  | Server error       | Stop server      | Red error message shown.                        |

  ### Negative testing

  Negative testing works only in sandbox mode. It is automatically disabled when `NODE_ENV=production`.

  For negative testing:

  1. Make sure to enable negative testing in your sandbox business account as described in the prerequisites.
  2. In the `.env` file, set `ENABLE_NEGATIVE_TESTING=true` and set `NEGATIVE_TEST_TYPE` to one of the error codes in the table.
  3. Restart the server after changing the `.env` file: `node server.js`.

  | Test scenario         | Error code              | Expected result                                 |
  | :-------------------- | :---------------------- | :---------------------------------------------- |
  | Insufficient funds    | `INSUFFICIENT_FUNDS`    | Error: buyer cannot pay at capture.             |
  | Instrument declined   | `INSTRUMENT_DECLINED`   | Error: payment method was declined at capture.  |
  | Internal server error | `INTERNAL_SERVER_ERROR` | Error: 500 error occurred at create or capture. |
  | Transaction refused   | `TRANSACTION_REFUSED`   | Error: transaction refused at capture.          |
  | Duplicate invoice ID  | `DUPLICATE_INVOICE_ID`  | Error: invoice ID must be unique at create.     |

  ## Go-live checklist

  * Test all scenarios in the sandbox.
  * In the `.env` file:
    * Comment out the development section.
    * Uncomment the production section.
  * Update HTML client ID to production.
  * Add the HTTPS certificate.
  * Test with real \$1 transaction.
  * Verify funds are received in your PayPal account.

  ## Post-launch monitoring

  These values are suggested monitoring thresholds for your integration, not performance guarantees from PayPal.

  | Metric                       | Target      | Action if below target                              |
  | :--------------------------- | :---------- | :-------------------------------------------------- |
  | Payment success rate         | 95%         | Check API errors in logs                            |
  | Cancel rate                  | \<20%       | Review checkout UX and pricing display              |
  | Error rate                   | \<2%        | Check error logs and API responses                  |
  | Order creation response time | \<2 seconds | Optimize server performance and check PayPal status |
  | Capture response time        | \<3 seconds | Review server performance                           |

  ## References

  * [PayPal JavaScript SDK v6](/reference/sdk/js/v6/reference)
  * [Orders API](https://developer.paypal.com/docs/api/orders/v2/)
  * [PayPal Server SDK](https://developer.paypal.com/serversdk/java/getting-started/how-to-get-started)
  * [Troubleshoot common issues](/payments/methods/paypal/troubleshoot#quick-start-integration-issues)

  ## Next steps

  The following use cases are common next steps after completing this quick start.

  * [Refund a payment](/payments/methods/paypal/refund): Process returns using capture IDs.
  * [Void an authorization](/payments/methods/paypal/void-an-authorization): Cancel an order before capture.
</View>

<View title="API only">
  ## PayPal Checkout flow

  A buyer following the PayPal Checkout flow has a PayPal account and uses payment methods like PayPal, Venmo, debit, and credit cards to pay for their order:

  * Buyers are aware that PayPal is processing their payments.
  * Buyers can pay for the order using any of the PayPal-associated payment methods.
  * Payment sources for these orders can be PayPal, Venmo, PayPal Pay Later, debit card, or credit card.

  ![Flow diagram showing PayPal order processing steps: Create order with capture/authorize intent, optionally confirm payment source, capture or authorize based on intent, buyer approval, tracking, then patch or show order details](https://www.paypalobjects.com/ppdevdocs/orders-api/orders-api-standard-flow.png)

  ## Orders API flows using PayPal Checkout for Pay with PayPal

  This section uses PayPal as the payment source to showcase the possible Orders v2 API flows in a PayPal Checkout integration.

  > **Note:** All of the Orders v2 API endpoints are designed for merchants and partners. The payer only comes into picture during the approval or payer action required steps.

  You need to pass an `intent` during the order creation. You can select either `CAPTURE` or `AUTHORIZE`:

  * `CAPTURE`: Use this intent to capture a payment immediately after the buyer approves the purchase.
  * `AUTHORIZE`: Use this option to authorize a buyer's funds before you capture payment and settle the purchase later. An authorization places a hold on the money and is valid for 29 days.

  ### Orders v2 API, detailed PayPal Checkout flow

  ![Sequence diagram showing PayPal checkout flow between consumers, merchant website, and PayPal. Consumer chooses PayPal (step 1), merchant creates order via API (step 2), consumer logs in and agrees to pay (steps 5-6), merchant redirects back after approval (step 7), retrieves order details (steps 8-9), and completes order (step 10). PayPal captures payment (steps 11-13). Diagram uses blue arrows for web interactions, pink arrows for API calls, and black arrows for PayPal internal processes.](https://www.paypalobjects.com/devdoc/ordersapi/standardcheckout/merchantwebsiteflow.png)

  ### Multi-step order flow with PayPal Checkout

  There are 3 different ways to complete a PayPal Checkout payment:

  #### PayPal Checkout with the payment source in a create order request

  1. Create the order: pass the `payment_source` in the payload.
  2. Payer action required: send the payer to the **Review your purchase** page.
  3. Capture or authorize payment.
  4. Set up shipment tracking for physical goods.

  #### PayPal Checkout with the confirm payment source endpoint

  1. Create the order.
  2. Confirm the payment source: pass the `payment_source` in the payload.
  3. Payer action required: send the payer to the **Review your purchase** page.
  4. Capture order.
  5. Set up shipment tracking for physical goods.

  #### PayPal Checkout with the authorize order endpoint

  Create the order.

  1. Payer action required: send the payer to the **Review your purchase** page.
  2. Authorize order.
  3. Capture payment.
  4. Set up shipment tracking for physical goods.

  #### Other API endpoints

  1. Get order details.
  2. Update order details.

  > **Note:** After you create an order, you have 3 hours to capture or modify that order. The order will remain in the `CREATED` state for only 3 hours. You can extend it up to 72 hours based on your use case. Connect with your TAM for more details.

  ## Prerequisites

  If you are a first-time user who wants to know where to get your access token, how to use the API suite, and complete Postman setup details, refer to <a href="/developer/how-to/api/get-started">Get started with PayPal REST APIs</a>.

  See PayPal's [Postman Collection](https://paypalcorp.postman.co/workspace/Test-Orders~269da256-27a0-4d00-9140-d9244798cb46/collection/31769881-80680620-c12a-4e9a-b496-a29cc1e9f1e8?action=share\&creator=31769881) for the latest Orders v2 API payloads.

  > **Note:** Set up your server to call the Orders v2 API instead of making calls directly from the browser or the client-side.

  ## Sample JSON order request 1: Single-step order flow

  This example uses PayPal as the payment source for creating a multi-step order. When the buyer chooses the payment method on the **Review Your Payment** (RYP) page and approves the purchase, you can capture the funds or authorize them for later, depending on the intent you choose during order creation.

  ### Step 1: Create order

  Set the order `intent` to `AUTHORIZE` or `CAPTURE`. A successful request returns an HTTPS `200 OK` status code with a `payer-action-required` order status. The following code samples show both the `AUTHORIZE` and `CAPTURE` intents.

  Sample create order request with intent `AUTHORIZE`:

  <CodeGroup>
    ```bash lines expandable Request theme={null}
    curl -v -X POST "https://api-m.sandbox.paypal.com/v2/checkout/orders/"
    -H 'Content-Type: application/json'
    -H 'Authorization: Bearer ACCESS-TOKEN'
    -d '{
        "intent": "AUTHORIZE",
        "purchase_units": [
            {
                "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
                "amount": {
                    "currency_code": "USD",
                    "value": "100.00"
                }
            }
        ],
        "payment_source": {
            "paypal": {
                "address": {
                    "address_line_1": "2211 N First Street",
                    "address_line_2": "17.3.160",
                    "admin_area_1": "CA",
                    "admin_area_2": "San Jose",
                    "postal_code": "95131",
                    "country_code": "US"
                },
                "email_address":"payer@example.com",
                "payment_method_preference": "IMMEDIATE_PAYMENT_REQUIRED",
                "experience_context": {
                    "return_url": "https://example.com/returnUrl",
                    "cancel_url": "https://example.com/cancelUrl"
                }
            }
        }
    }'
    ```

    ```json lines expandable Response theme={null}
    {
        "id": "ORDER-ID",
        "status": "PAYER_ACTION_REQUIRED",
        "payment_source": {
            "paypal": {
                "email_address": "payer@example.com",
                "address": {
                    "address_line_1": "2211 N First Street",
                    "address_line_2": "17.3.160",
                    "admin_area_2": "San Jose",
                    "admin_area_1": "CA",
                    "postal_code": "95131",
                    "country_code": "US"
                }
            }
        },
        "payer": {
            "email_address": "payer@example.com",
            "address": {
                "address_line_1": "2211 N First Street",
                "address_line_2": "17.3.160",
                "admin_area_2": "San Jose",
                "admin_area_1": "CA",
                "postal_code": "95131",
                "country_code": "US"
            }
        },
        "links": [
            {
                "href": "https://api.sandbox.paypal.com/v2/checkout/orders/0KD30046EH157382X",
                "rel": "self",
                "method": "GET"
            },
            {
                "href": "https://www.sandbox.paypal.com/checkoutnow?token=0KD30046EH157382X",
                "rel": "payer-action",
                "method": "GET"
            }
        ]
    }
    ```
  </CodeGroup>

  Sample create order request with intent `CAPTURE`:

  <CodeGroup>
    ```bash lines expandable Request theme={null}
    curl -v -X POST "https://api-m.sandbox.paypal.com/v2/checkout/orders/"
    -H 'Content-Type: application/json'
    -H 'Authorization: Bearer ACCESS-TOKEN'
    -d '{
        "intent": "CAPTURE",
        "purchase_units": [
            {
                "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
                "amount": {
                    "currency_code": "USD",
                    "value": "100.00"
                }
            }
        ],
        "payment_source": {
            "paypal": {
                "address": {
                    "address_line_1": "2211 N First Street",
                    "address_line_2": "17.3.160",
                    "admin_area_1": "CA",
                    "admin_area_2": "San Jose",
                    "postal_code": "95131",
                    "country_code": "US"
                },
                "email_address":"payer@example.com",
                "payment_method_preference": "IMMEDIATE_PAYMENT_REQUIRED",
                "experience_context": {
                    "return_url": "https://example.com/returnUrl",
                    "cancel_url": "https://example.com/cancelUrl"
                }
            }
        }
    }'
    ```

    ```json lines expandable Response theme={null}
    {
        "id": "0KD30046EH157382X",
        "status": "PAYER_ACTION_REQUIRED",
        "payment_source": {
            "paypal": {
                "email_address": "payer@example.com",
                "address": {
                    "address_line_1": "2211 N First Street",
                    "address_line_2": "17.3.160",
                    "admin_area_2": "San Jose",
                    "admin_area_1": "CA",
                    "postal_code": "95131",
                    "country_code": "US"
                }
            }
        },
        "payer": {
            "email_address": "payer@example.com",
            "address": {
                "address_line_1": "2211 N First Street",
                "address_line_2": "17.3.160",
                "admin_area_2": "San Jose",
                "admin_area_1": "CA",
                "postal_code": "95131",
                "country_code": "US"
            }
        },
        "links": [
            {
                "href": "https://api.sandbox.paypal.com/v2/checkout/orders/0KD30046EH157382X",
                "rel": "self",
                "method": "GET"
            },
            {
                "href": "https://www.sandbox.paypal.com/checkoutnow?token=0KD30046EH157382X",
                "rel": "payer-action",
                "method": "GET"
            }
        ]
    }
    ```
  </CodeGroup>

  ### Include shipping details

  Manage the shipping details for an order by including `shipping_preference` in the `experience_context` for the payment method defined in the `payment_source` object. For example, `payment_source.paypal.experience_context.shipping_preference` or `payment_source.venmo.experience_context.shipping_preference`.

  The `shipping_preference` parameter accepts 3 options:

  1. **Use buyer's PayPal shipping address (default):** When you set the `shipping_preference` parameter to `GET_FROM_FILE`, PayPal uses the buyer's shipping address directly from their PayPal account. This is the default option when there is no `shipping_preference` value.
  2. **Ask buyer to provide address:** When you have the buyer’s address while creating the order and want to pass it as part of the request, add the `shipping_preference` field to `payment_source.paypal.experience_context` and set its value to `SET_FROM_PROVIDER`. You need to pass that address in the `purchase_units` section of the request. The following **Sample shipping request** payload shows how to include the shipping address. An important note: buyers cannot edit this address on the PayPal side.
  3. **No shipping:** For digital goods or gift cards that have no physical delivery address, set the `shipping_preference` parameter to `NO_SHIPPING`.

  See the <a href="https://developer.paypal.com/docs/api/orders/v2/#definition-experience_context_base">Orders v2 API</a> for more information.

  #### Sample shipping request

  This sample request passes the shipping details using the the `purchase_units.shipping` object.

  ```bash lines expandable theme={null}
  curl -v -X POST "https://api-m.sandbox.paypal.com/v2/checkout/orders/"
  -H 'Content-Type: application/json'
  -H 'Authorization: Bearer ACCESS-TOKEN'
  -d '{
      "intent": "CAPTURE",
      "purchase_units": [
          {
              "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
              "amount": {
                  "currency_code": "USD",
                  "value": "100.00"
              },
               "shipping": {
                  "name": {
                    "full_name": "Firstname Lastname"
                  },
                  "address": {
                    "address_line_1": "2211 N First Street",
                    "address_line_2": "Building 17",
                    "admin_area_2": "San Jose",
                    "admin_area_1": "CA",
                    "postal_code": "95131",
                    "country_code": "US"
                  }
             }
          }
      ],
      "payment_source": {
          "paypal": {
              "address": {
                  "address_line_1": "2211 N First Street",
                  "address_line_2": "17.3.160",
                  "admin_area_1": "CA",
                  "admin_area_2": "San Jose",
                  "postal_code": "95131",
                  "country_code": "US"
              },
              "email_address":"payer@example.com",
              "payment_method_preference": "IMMEDIATE_PAYMENT_REQUIRED",
              "experience_context": {
                  "return_url": "https://example.com/returnUrl",
                  "cancel_url": "https://example.com/cancelUrl",
                  "shipping_preference": "SET_FROM_PROVIDER"
              }
          }
      }
  }'
  ```

  ### Step 2: Buyer approval

  After successfully creating the order, redirect the buyer to the RYP page. The Create order API response passes the RYP page URL as a HATEOS link using the `payer-action` parameter in the `links` section.

  <Accordion title="See example buyer approval page">
    ![PayPal checkout page showing payment options including saved Visa card, PayPal Credit, and Pay in 4, with shipping address and total amount of \$100.00](https://www.paypalobjects.com/ppdevdocs/orders-api/orders-api-single-step-buyer-approval.png)
  </Accordion>

  When the buyer selects **Continue to Review Order**, they will be redirected to the `return_url` in the `experience_context` object. Replace it with the URL of the page where the buyer:

  * Sees the final order amount.
  * Reviews their final order.

  **Continue to Review Order** is the default behavior. If you know the final order amount upfront while creating the order, such as shipping and taxes, and will not modify the order later, use the `PAY_NOW` flow to complete the payment in one go without requiring further action from the buyer on the merchant site.

  Set this option in `paypal.experience_context.user_action`:

  * `CONTINUE` is the default value for `user_action`.
  * Choose `PAY_NOW` if you know the final amount before the buyer reaches the first review page.

  ### Step 3: Authorize or capture order

  Both authorize and capture API requests accept `payment_source` as an input, but it's optional. See the preceding create order payload for the payment source. Learn more about <a href="https://developer.paypal.com/docs/checkout/standard/customize/authorization/">authorize and capture</a>.

  #### Capture order

  After the order has been created and the payer approves the purchase, capture the order by sending a `POST` request and the order ID to the `/v2/checkout/orders/ORDER-ID/capture` endpoint. The following sample request and response show the result of sending a capture order request without a request body:

  Sample capture order request:

  <CodeGroup>
    ```bash Request theme={null}
    curl -v -X POST "https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER-ID/capture"
    -H 'Content-Type: application/json'
    -H 'Authorization: Bearer ACCESS-TOKEN'
    -d '{}'
    ```

    ```json lines expandable Response theme={null}
    {
        "id": "0KD30046EH157382X",
        "intent": "CAPTURE",
        "status": "COMPLETED",
        "payment_source": {
            "paypal": {
                "email_address": "payer@example.com",
                "account_id": "PAYER-ID",
                "account_status": "UNVERIFIED",
                "name": {
                    "given_name": "Firstname",
                    "surname": "Lastname"
                },
                "address": {
                    "address_line_1": "2211 N First Street",
                    "address_line_2": "17.3.160",
                    "admin_area_2": "San Jose",
                    "admin_area_1": "CA",
                    "postal_code": "95131",
                    "country_code": "US"
                }
            }
        },
        "purchase_units": [
            {
                "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
                "amount": {
                    "currency_code": "USD",
                    "value": "100.00"
                },
                "payee": {
                    "email_address": "payee@example.com",
                    "merchant_id": "MERCHANT-ID"
                },
                "soft_descriptor": "PAYPAL *TEST STORE",
                "shipping": {
                    "name": {
                        "full_name": "Firstname Lastname"
                    },
                    "address": {
                        "address_line_1": "123 Main St.",
                        "admin_area_1": "CA",
                        "admin_area_2": "Anytown",
                        "postal_code": "12345",
                        "country_code": "US"
                    }
                },
                "payments": {
                    "captures": [
                        {
                            "id": "CAPTURE-ID",
                            "status": "COMPLETED",
                            "amount": {
                                "currency_code": "USD",
                                "value": "100.00"
                            },
                            "final_capture": true,
                            "seller_protection": {
                                "status": "ELIGIBLE",
                                "dispute_categories": [
                                    "ITEM_NOT_RECEIVED",
                                    "UNAUTHORIZED_TRANSACTION"
                                ]
                            },
                            "seller_receivable_breakdown": {
                                "gross_amount": {
                                    "currency_code": "USD",
                                    "value": "100.00"
                                },
                                "paypal_fee": {
                                    "currency_code": "USD",
                                    "value": "3.98"
                                },
                                "net_amount": {
                                    "currency_code": "USD",
                                    "value": "96.02"
                                }
                            },
                            "links": [
                                {
                                    "href": "https://api.sandbox.paypal.com/v2/payments/captures/CAPTURE-ID",
                                    "rel": "self",
                                    "method": "GET"
                                },
                                {
                                    "href": "https://api.sandbox.paypal.com/v2/payments/captures/CAPTURE-ID/refund",
                                    "rel": "refund",
                                    "method": "POST"
                                },
                                {
                                    "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
                                    "rel": "up",
                                    "method": "GET"
                                }
                            ],
                            "create_time": "2024-03-15T20:41:04Z",
                            "update_time": "2024-03-15T20:41:04Z"
                        }
                    ]
                }
            }
        ],
        "payer": {
            "name": {
                "given_name": "Firstname",
                "surname": "Lastname"
            },
            "email_address": "payer@example.com",
            "payer_id": "PAYER-ID",
            "address": {
                "address_line_1": "123 Main St.",
                "admin_area_1": "CA",
                "admin_area_2": "Anytown",
                "postal_code": "12345",
                "country_code": "US"
            }
        },
        "create_time": "2024-03-15T19:57:25Z",
        "update_time": "2024-03-15T20:41:04Z",
        "links": [
            {
                "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
                "rel": "self",
                "method": "GET"
            }
        ]
    }
    ```
  </CodeGroup>

  After the order has been created, call the Authorize payment for order endpoint of the Orders v2 API by passing the order ID in a `POST` request to `/v2/checkout/orders/ORDER-ID/authorize`. The following sample request and response show the result of calling the authorize order endpoint without a request body:

  Sample authorize order request with intent `AUTHORIZE`:

  <CodeGroup>
    ```bash Request theme={null}
    curl -v -X POST "https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER-ID/authorize"
    -H 'Content-Type: application/json'
    -H 'Authorization: Bearer ACCESS-TOKEN'
    -d '{}'
    ```

    ```json expandable lines Response theme={null}
    {
        "id": "ORDER-ID",
        "intent": "AUTHORIZE",
        "status": "COMPLETED",
        "payment_source": {
            "paypal": {
                "email_address": "payer@example.com",
                "account_id": "PAYER-ID",
                "account_status": "UNVERIFIED",
                "name": {
                    "given_name": "Firstname",
                    "surname": "Lastname"
                },
                "address": {
                    "address_line_1": "2211 N First Street",
                    "address_line_2": "17.3.160",
                    "admin_area_2": "San Jose",
                    "admin_area_1": "CA",
                    "postal_code": "95131",
                    "country_code": "US"
                }
            }
        },
        "purchase_units": [
            {
                "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
                "amount": {
                    "currency_code": "USD",
                    "value": "100.00"
                },
                "payee": {
                    "email_address": "payee@example.com",
                    "merchant_id": "MERCHANT-ID"
                },
                "soft_descriptor": "PAYPAL *TEST STORE",
                "shipping": {
                    "name": {
                        "full_name": "Firstname Lastname"
                    },
                    "address": {
                        "address_line_1": "2211 North First Street",
                        "admin_area_2": "San Jose",
                        "admin_area_1": "CA",
                        "postal_code": "95131",
                        "country_code": "US"
                    }
                },
                "payments": {
                    "authorizations": [
                        {
                            "status": "CREATED",
                            "id": "AUTHORIZATION-ID",
                            "amount": {
                                "currency_code": "USD",
                                "value": "100.00"
                            },
                            "seller_protection": {
                                "status": "ELIGIBLE",
                                "dispute_categories": [
                                    "ITEM_NOT_RECEIVED",
                                    "UNAUTHORIZED_TRANSACTION"
                                ]
                            },
                            "expiration_time": "2024-04-13T20:57:44Z",
                            "links": [
                                {
                                    "href": "https://api.sandbox.paypal.com/v2/payments/authorizations/AUTHORIZATION-ID",
                                    "rel": "self",
                                    "method": "GET"
                                },
                                {
                                    "href": "https://api.sandbox.paypal.com/v2/payments/authorizations/AUTHORIZATION-ID/capture",
                                    "rel": "capture",
                                    "method": "POST"
                                },
                                {
                                    "href": "https://api.sandbox.paypal.com/v2/payments/authorizations/AUTHORIZATION-ID/void",
                                    "rel": "void",
                                    "method": "POST"
                                },
                                {
                                    "href": "https://api.sandbox.paypal.com/v2/payments/authorizations/AUTHORIZATION-ID/reauthorize",
                                    "rel": "reauthorize",
                                    "method": "POST"
                                },
                                {
                                    "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
                                    "rel": "up",
                                    "method": "GET"
                                }
                            ],
                            "create_time": "2024-03-15T20:57:44Z",
                            "update_time": "2024-03-15T20:57:44Z"
                        }
                    ]
                }
            }
        ],
        "payer": {
            "name": {
                "given_name": "Firstname",
                "surname": "Lastname"
            },
            "email_address": "payer@example.com",
            "payer_id": "PAYER-ID",
            "address": {
                "address_line_1": "123 Main St.",
                "admin_area_1": "CA",
                "admin_area_2": "Anytown",
                "postal_code": "12345",
                "country_code": "US"
            }
        },
        "create_time": "2024-03-15T20:54:21Z",
        "update_time": "2024-03-15T20:57:44Z",
        "links": [
            {
                "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
                "rel": "self",
                "method": "GET"
            }
        ]
    }
    ```
  </CodeGroup>

  Authorization requires an additional step to complete the payment.

  Complete the authorization process and the transaction by sending a `POST` request to `v2/payments/authorizations/AUTHORIZATION-ID/capture` to call the <a href="/reference/api/rest/authorizations/capture-authorized-payment">Capture authorized payment</a> endpoint of the Payments v2 API. This step triggers a call to the payment gateway to capture the payment.

  > **Note:** You can authorize the total amount or a part of the total amount. To authorize a partial payment, pass the amount in the request payload. For more information, refer to the <a href="/reference/api/rest/authorizations/capture-authorized-payment">Capture authorized payment</a> endpoint of the Payments v2 API.

  The following sample request and response show the result of calling the capture API endpoint without a request body.

  > **Note:** The Payments capture is not the Order capture call.

  Sample capture authorized order request:

  <CodeGroup>
    ```bash Request theme={null}
    curl -v -X POST "https://api-m.sandbox.paypal.com/v2/payments/authorizations/AUTHORIZATION-ID/capture"
    -H 'Content-Type: application/json'
    -H 'Authorization: Bearer ACCESS-TOKEN'
    -d '{}'
    ```

    ```json lines expandable Response theme={null}
    {
        "id": "AUTHORIZATION-ID",
        "amount": {
            "currency_code": "USD",
            "value": "100.00"
        },
        "final_capture": true,
        "seller_protection": {
            "status": "ELIGIBLE",
            "dispute_categories": [
                "ITEM_NOT_RECEIVED",
                "UNAUTHORIZED_TRANSACTION"
            ]
        },
        "seller_receivable_breakdown": {
            "gross_amount": {
                "currency_code": "USD",
                "value": "100.00"
            },
            "paypal_fee": {
                "currency_code": "USD",
                "value": "3.98"
            },
            "net_amount": {
                "currency_code": "USD",
                "value": "96.02"
            },
            "exchange_rate": {}
        },
        "status": "COMPLETED",
        "create_time": "2024-03-15T20:59:52Z",
        "update_time": "2024-03-15T20:59:52Z",
        "links": [
            {
                "href": "https://api.sandbox.paypal.com/v2/payments/captures/CAPTURE-ID",
                "rel": "self",
                "method": "GET"
            },
            {
                "href": "https://api.sandbox.paypal.com/v2/payments/captures/CAPTURE-ID/refund",
                "rel": "refund",
                "method": "POST"
            },
            {
                "href": "https://api.sandbox.paypal.com/v2/payments/authorizations/AUTHORIZATION-ID",
                "rel": "up",
                "method": "GET"
            }
        ]
    }
    ```
  </CodeGroup>

  #### Step 4: Shipment tracking

  If you have physical goods in your order, you can use the Shipment Tracking API to add tracking information to your packages, such as carrier, item, and SKU details.

  * If the `intent` is set to `CAPTURE`, replace `CAPTURE-ID` with the `payments.captures.id` field that is found in the Order capture's API response.
  * If the `intent` is set to `AUTHORIZE`, replace `CAPTURE-ID` with the ID field found in the Payment capture API response, not the Order API’s capture call.

  The `capture_id` field is automatically populated if you're using the PayPal Postman collection.

  > **Note:** See the <a href="/reference/api/rest/orders/add-tracking-information-for-an-order">Add tracking information for an order</a> endpoint of the Orders v2 API for more information about each field in the payload.

  Sample shipment tracking request and response:

  <CodeGroup>
    ```bash expandable lines Request theme={null}
    curl -v -X POST "https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER-ID/track"
    -H 'Content-Type: application/json'
    -H 'Authorization: Bearer ACCESS-TOKEN'
    -d '{
      "capture_id": "CAPTURE-ID",
      "tracking_number": "TRACKING-ID",
      "carrier": "FEDEX",
      "notify_payer": true,
      "items": [
        {
          "name": "T-Shirt",
          "sku": "sku02",
          "quantity": "1",
          "upc": {
            "type": "UPC-A",
            "code": "upc001"
          },
          "image_url": "https://www.example.com/example.jpg",
          "url": "https://www.example.com/example"
        }
      ]
    }'
    ```

    ```json expandable lines Response theme={null}
    {
        "id": "ORDER-ID",
        "intent": "CAPTURE",
        "status": "COMPLETED",
        "payment_source": {
            "paypal": {
                "email_address": "payer@example.com",
                "account_id": "PAYER-ID",
                "account_status": "UNVERIFIED",
                "name": {
                    "given_name": "Firstname",
                    "surname": "Lastname"
                },
                "address": {
                    "address_line_1": "2211 N First Street",
                    "address_line_2": "17.3.160",
                    "admin_area_2": "San Jose",
                    "admin_area_1": "CA",
                    "postal_code": "95131",
                    "country_code": "US"
                }
            }
        },
        "purchase_units": [
            {
                "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
                "amount": {
                    "currency_code": "USD",
                    "value": "100.00"
                },
                "payee": {
                    "email_address": "payee@example.com",
                    "merchant_id": "MERCHANT-ID"
                },
                "soft_descriptor": "PAYPAL *TEST STORE",
                "shipping": {
                    "name": {
                        "full_name": "Firstname Lastname"
                    },
                    "address": {
                        "address_line_1": "123 Main St.",
                        "admin_area_1": "CA",
                        "admin_area_2": "Anytown",
                        "postal_code": "12345",
                        "country_code": "US"
                    },
                    "trackers": [
                        {
                            "id": "TRACKING-ID",
                            "items": [
                                {
                                    "name": "T-Shirt",
                                    "sku": "sku02",
                                    "quantity": "1",
                                    "image_url": "https://www.example.com/example.jpg",
                                    "upc": {
                                        "type": "UPC-A",
                                        "code": "upc001"
                                    },
                                    "url": "https://www.example.com/example"
                                }
                            ],
                            "links": [
                                {
                                    "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
                                    "rel": "up",
                                    "method": "GET"
                                },
                                {
                                    "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID/trackers/TRACKING-ID",
                                    "rel": "update",
                                    "method": "PATCH"
                                }
                            ],
                            "status": "SHIPPED"
                        }
                    ]
                },
                "payments": {
                    "captures": [
                        {
                            "id": "CAPTURE-ID",
                            "status": "COMPLETED",
                            "amount": {
                                "currency_code": "USD",
                                "value": "100.00"
                            },
                            "final_capture": true,
                            "seller_protection": {
                                "status": "ELIGIBLE",
                                "dispute_categories": [
                                    "ITEM_NOT_RECEIVED",
                                    "UNAUTHORIZED_TRANSACTION"
                                ]
                            },
                            "seller_receivable_breakdown": {
                                "gross_amount": {
                                    "currency_code": "USD",
                                    "value": "100.00"
                                },
                                "paypal_fee": {
                                    "currency_code": "USD",
                                    "value": "3.98"
                                },
                                "net_amount": {
                                    "currency_code": "USD",
                                    "value": "96.02"
                                }
                            },
                            "links": [
                                {
                                    "href": "https://api.sandbox.paypal.com/v2/payments/captures/CAPTURE-ID",
                                    "rel": "self",
                                    "method": "GET"
                                },
                                {
                                    "href": "https://api.sandbox.paypal.com/v2/payments/captures/CAPTURE-ID/refund",
                                    "rel": "refund",
                                    "method": "POST"
                                },
                                {
                                    "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
                                    "rel": "up",
                                    "method": "GET"
                                }
                            ],
                            "create_time": "2024-03-15T21:14:36Z",
                            "update_time": "2024-03-15T21:14:36Z"
                        }
                    ]
                }
            }
        ],
        "payer": {
            "name": {
                "given_name": "Firstname",
                "surname": "Lastname"
            },
            "email_address": "payer@example.com",
            "payer_id": "PAYER-ID",
            "address": {
                "address_line_1": "2211 N First Street",
                "address_line_2": "17.3.160",
                "admin_area_2": "San Jose",
                "admin_area_1": "CA",
                "postal_code": "95131",
                "country_code": "US"
            }
        },
        "create_time": "2024-03-15T21:14:07Z",
        "update_time": "2024-03-15T21:14:36Z",
        "links": [
            {
                "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
                "rel": "self",
                "method": "GET"
            }
        ]
    }
    ```
  </CodeGroup>

  > **Note:** See <a href="https://developer.paypal.com/docs/tracking/orders-api/integrate/">Integrate package tracking</a> for more details about adding package tracking numbers to your orders with the Orders v2 API.

  #### Step 5: Show the order details

  You can get the details of an order at any stage by sending a `GET` call to the <a href="/reference/api/rest/orders/show-order-details">Show order details</a> endpoint of the Orders v2 API.

  Sample show order details request with an authorization token:

  <CodeGroup>
    ```bash Request theme={null}
    curl -v -X GET "https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER-ID" \
    -H 'Authorization: Bearer ACCESS-TOKEN'
    ```

    ```json lines expandable Response theme={null}
    {
       "id": "ORDER-ID",
       "intent": "AUTHORIZE",
       "status": "COMPLETED",
       "payment_source": {
           "paypal": {
               "email_address": "payer@example.com",
               "account_id": "PAYER-ID",
               "account_status": "UNVERIFIED",
               "name": {
                   "given_name": "Firstname",
                   "surname": "Lastname"
               },
               "address": {
                   "address_line_1": "123 Main St.",
                   "admin_area_1": "CA",
                   "admin_area_2": "Anytown",
                   "postal_code": "12345",
                   "country_code": "US"
               }
           }
       },
       "purchase_units": [
           {
               "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
               "amount": {
                   "currency_code": "USD",
                   "value": "100.00"
               },
               "payee": {
                   "email_address": "payee@example.com",
                   "merchant_id": "MERCHANT-ID"
               },
               "soft_descriptor": "PAYPAL *TEST STORE",
               "shipping": {
                   "name": {
                       "full_name": "Firstname Lastname"
                   },
                   "address": {
                       "address_line_1": "123 Main St.",
                       "admin_area_1": "CA",
                       "admin_area_2": "Anytown",
                       "postal_code": "12345",
                       "country_code": "US"
                   }
               },
               "payments": {
                   "authorizations": [
                       {
                           "status": "CAPTURED",
                           "id": "AUTHORIZATION-ID",
                           "amount": {
                               "currency_code": "USD",
                               "value": "100.00"
                           },
                           "seller_protection": {
                               "status": "ELIGIBLE",
                               "dispute_categories": [
                                   "ITEM_NOT_RECEIVED",
                                   "UNAUTHORIZED_TRANSACTION"
                               ]
                           },
                           "expiration_time": "2024-04-13T20:57:44Z",
                           "links": [
                               {
                                   "href": "https://api-m.sandbox.paypal.com/v2/payments/authorizations/AUTHORIZATION-ID",
                                   "rel": "self",
                                   "method": "GET"
                               },
                               {
                                   "href": "https://api-m.sandbox.paypal.com/v2/payments/authorizations/AUTHORIZATION-ID/capture",
                                   "rel": "capture",
                                   "method": "POST"
                               },
                               {
                                   "href": "https://api-m.sandbox.paypal.com/v2/payments/authorizations/AUTHORIZATION-ID/void",
                                   "rel": "void",
                                   "method": "POST"
                               },
                               {
                                   "href": "https://api-m.sandbox.paypal.com/v2/payments/authorizations/AUTHORIZATION-ID/reauthorize",
                                   "rel": "reauthorize",
                                   "method": "POST"
                               },
                               {
                                   "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
                                   "rel": "up",
                                   "method": "GET"
                               }
                           ],
                           "create_time": "2024-03-15T20:57:44Z",
                           "update_time": "2024-03-15T20:59:52Z"
                       }
                   ],
                   "captures": [
                       {
                           "id": "CAPTURE-ID",
                           "status": "COMPLETED",
                           "amount": {
                               "currency_code": "USD",
                               "value": "100.00"
                           },
                           "final_capture": true,
                           "disbursement_mode": "INSTANT",
                           "seller_protection": {
                               "status": "ELIGIBLE",
                               "dispute_categories": [
                                   "ITEM_NOT_RECEIVED",
                                   "UNAUTHORIZED_TRANSACTION"
                               ]
                           },
                           "seller_receivable_breakdown": {
                               "gross_amount": {
                                   "currency_code": "USD",
                                   "value": "100.00"
                               },
                               "paypal_fee": {
                                   "currency_code": "USD",
                                   "value": "3.98"
                               },
                               "net_amount": {
                                   "currency_code": "USD",
                                   "value": "96.02"
                               }
                           },
                           "links": [
                               {
                                   "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/CAPTURE-ID",
                                   "rel": "self",
                                   "method": "GET"
                               },
                               {
                                   "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/CAPTURE-ID/refund",
                                   "rel": "refund",
                                   "method": "POST"
                               },
                               {
                                   "href": "https://api-m.sandbox.paypal.com/v2/payments/authorizations/AUTHORIZATION-ID",
                                   "rel": "up",
                                   "method": "GET"
                               }
                           ],
                           "create_time": "2024-03-15T20:59:52Z",
                           "update_time": "2024-03-15T20:59:52Z"
                       }
                   ]
               }
           }
       ],
       "payer": {
           "name": {
               "given_name": "Firstname",
               "surname": "Lastname"
           },
           "email_address": "payer@example.com",
           "payer_id": "PAYER-ID",
           "address": {
               "address_line_1": "123 Main St.",
               "admin_area_1": "CA",
               "admin_area_2": "Anytown",
               "postal_code": "12345",
               "country_code": "US"
           }
       },
       "create_time": "2024-03-15T20:54:21Z",
       "update_time": "2024-03-15T20:59:52Z",
       "links": [
           {
               "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
               "rel": "self",
               "method": "GET"
           }
       ]
    }
    ```
  </CodeGroup>

  ### Sample JSON order request 2: Multi-step order flow with confirm order API endpoint

  This example also demonstrates multi-step order creation using PayPal as the payment method. But unlike the preceding example, you can create an order without any payment source information. When the buyer chooses the payment method on the RYP page and approves the purchase, you can confirm their intent to pay, capture the funds, or authorize them for later, depending on the intent you choose during order creation.

  #### Step 1: Create order

  Set the order `intent` to `CAPTURE`. A successful capture order request returns an HTTPS `201 Created` status code:

  Sample capture order request and response:

  <CodeGroup>
    ```bash lines expandable Request theme={null}
    curl -v -X POST "https://api-m.sandbox.paypal.com/v2/checkout/orders/"
    -H 'Content-Type: application/json'
    -H 'Authorization: Bearer ACCESS-TOKEN'
    -d '
    {
        "intent": "CAPTURE",
        "purchase_units": [
            {
                "items": [
                    {
                        "name": "T-Shirt",
                        "description": "Green XL",
                        "quantity": "1",
                        "unit_amount": {
                            "currency_code": "USD",
                            "value": "100.00"
                        }
                    }
                ],
                "amount": {
                    "currency_code": "USD",
                    "value": "100.00",
                    "breakdown": {
                        "item_total": {
                            "currency_code": "USD",
                            "value": "100.00"
                        }
                    }
                }
            }
        ]
    }'
    ```

    ```json lines expandable Response theme={null}
    {
        "id": "ORDER-ID",
        "status": "CREATED",
        "create_time": "2024-03-20T16:38:38Z",
        "links": [
            {
                "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
                "rel": "self",
                "method": "GET"
            },
            {
                "href": "https://www.sandbox.paypal.com/checkoutnow?token=ORDER-ID",
                "rel": "approve",
                "method": "GET"
            },
            {
                "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
                "rel": "update",
                "method": "PATCH"
            },
            {
                "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID/capture",
                "rel": "capture",
                "method": "POST"
            }
        ]
    }
    ```
  </CodeGroup>

  #### Step 2: Confirm payment

  The buyer can confirm their intent to pay for the order using a PayPal Checkout payment source: in this case, PayPal.

  > **Note:** The `payment_source` parameter is required.

  Sample confirm payment request and response:

  <CodeGroup>
    ```bash lines expandable Request theme={null}
    curl -v -X POST "https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER-ID/confirm-payment-source"
    -H 'Authorization: Bearer ACCESS-TOKEN'
    -d '
    {
      "payment_source": {
        "paypal": {
          "experience_context": {
            "payment_method_preference": "IMMEDIATE_PAYMENT_REQUIRED",
            "email_address": "payer@example.com",
            "brand_name": "EXAMPLE INC",
            "locale": "en-US",
            "landing_page": "LOGIN",
            "shipping_preference": "GET_FROM_FILE",
            "user_action": "PAY_NOW",
            "return_url": "https://example.com/returnUrl",
            "cancel_url": "https://example.com/cancelUrl"
          }
        }
      }
    }'
    ```

    ```json lines expandable Response theme={null}
    {
        "id": "ORDER-ID",
        "intent": "CAPTURE",
        "status": "PAYER_ACTION_REQUIRED",
        "payment_source": {
            "paypal": {}
        },
        "purchase_units": [
            {
                "reference_id": "default",
                "amount": {
                    "currency_code": "USD",
                    "value": "100.00",
                    "breakdown": {
                        "item_total": {
                            "currency_code": "USD",
                            "value": "100.00"
                        }
                    }
                },
                "payee": {
                    "email_address": "payee@example.com",
                    "merchant_id": "MERCHANT-ID",
                    "display_data": {
                        "brand_name": "EXAMPLE INC"
                    }
                },
                "items": [
                    {
                        "name": "T-Shirt",
                        "unit_amount": {
                            "currency_code": "USD",
                            "value": "100.00"
                        },
                        "quantity": "1",
                        "description": "Green XL"
                    }
                ]
            }
        ],
        "links": [
            {
                "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
                "rel": "self",
                "method": "GET"
            },
            {
                "href": "https://www.sandbox.paypal.com/checkoutnow?token=ORDER-ID",
                "rel": "payer-action",
                "method": "GET"
            }
        ]
    }
    ```
  </CodeGroup>

  #### Step 3: Buyer approval

  The buyer approves or cancels the payment in this step. For more information refer to **Step 2: Buyer Approval** in the preceding **Sample JSON order request 2: Multi-step order flow** section.

  #### Step 4: Capture payment

  The last step to complete the order is to capture the payment. You can capture an order without any payment source information.

  > **Note:** If you want to provide the buyer with an option to change the payment source after the approval, you can pass the new payment method details in the Capture API call. However, this would need buyer approval again as it's a different payment source.

  Sample capture payment request and response:

  <CodeGroup>
    ```bash Request theme={null}
    curl -v -X POST "https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER-ID/capture"
    -H 'Content-Type: application/json'
    -H 'Authorization: Bearer ACCESS-TOKEN'
    -d '{}'
    ```

    ```json lines expandable Response theme={null}
    {
        "id": "ORDER-ID",
        "intent": "CAPTURE",
        "status": "COMPLETED",
        "payment_source": {
            "paypal": {
                "email_address": "payer@example.com",
                "account_id": "PAYER-ID",
                "account_status": "UNVERIFIED",
                "name": {
                    "given_name": "Firstname",
                    "surname": "Lastname"
                },
                "address": {
                    "country_code": "US"
                }
            }
        },
        "purchase_units": [
            {
                "reference_id": "default",
                "amount": {
                    "currency_code": "USD",
                    "value": "100.00",
                    "breakdown": {
                        "item_total": {
                            "currency_code": "USD",
                            "value": "100.00"
                        },
                        "shipping": {
                            "currency_code": "USD",
                            "value": "0.00"
                        },
                        "handling": {
                            "currency_code": "USD",
                            "value": "0.00"
                        },
                        "insurance": {
                            "currency_code": "USD",
                            "value": "0.00"
                        },
                        "shipping_discount": {
                            "currency_code": "USD",
                            "value": "0.00"
                        }
                    }
                },
                "payee": {
                    "email_address": "payee@example.com",
                    "merchant_id": "MERCHANT-ID"
                },
                "description": "T-Shirt",
                "soft_descriptor": "PAYPAL *TEST STORE",
                "items": [
                    {
                        "name": "T-Shirt",
                        "unit_amount": {
                            "currency_code": "USD",
                            "value": "100.00"
                        },
                        "tax": {
                            "currency_code": "USD",
                            "value": "0.00"
                        },
                        "quantity": "1",
                        "description": "Green XL"
                    }
                ],
                "shipping": {
                    "name": {
                        "full_name": "Firstname Lastname"
                    },
                    "address": {
                        "address_line_1": "123 Main St.",
                        "admin_area_1": "CA",
                        "admin_area_2": "Anytown",
                        "postal_code": "12345",
                        "country_code": "US"
                    }
                },
                "payments": {
                    "captures": [
                        {
                            "id": "CAPTURE-ID",
                            "status": "COMPLETED",
                            "amount": {
                                "currency_code": "USD",
                                "value": "100.00"
                            },
                            "final_capture": true,
                            "seller_protection": {
                                "status": "ELIGIBLE",
                                "dispute_categories": [
                                    "ITEM_NOT_RECEIVED",
                                    "UNAUTHORIZED_TRANSACTION"
                                ]
                            },
                            "seller_receivable_breakdown": {
                                "gross_amount": {
                                    "currency_code": "USD",
                                    "value": "100.00"
                                },
                                "paypal_fee": {
                                    "currency_code": "USD",
                                    "value": "3.98"
                                },
                                "net_amount": {
                                    "currency_code": "USD",
                                    "value": "96.02"
                                }
                            },
                            "links": [
                                {
                                    "href": "https://api.sandbox.paypal.com/v2/payments/captures/CAPTURE-ID",
                                    "rel": "self",
                                    "method": "GET"
                                },
                                {
                                    "href": "https://api.sandbox.paypal.com/v2/payments/captures/CAPTURE-ID/refund",
                                    "rel": "refund",
                                    "method": "POST"
                                },
                                {
                                    "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
                                    "rel": "up",
                                    "method": "GET"
                                }
                            ],
                            "create_time": "2024-03-20T16:47:58Z",
                            "update_time": "2024-03-20T16:47:58Z"
                        }
                    ]
                }
            }
        ],
        "payer": {
            "name": {
                "given_name": "Firstname",
                "surname": "Lastname"
            },
            "email_address": "payer@example.com",
            "payer_id": "PAYER-ID",
            "address": {
                "country_code": "US"
            }
        },
        "create_time": "2024-03-20T16:38:38Z",
        "update_time": "2024-03-20T16:47:58Z",
        "links": [
            {
                "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
                "rel": "self",
                "method": "GET"
            }
        ]
    }
    ```
  </CodeGroup>

  #### Step 5: Shipment tracking

  If you have physical goods in your order, you can use the Shipment Tracking API to add tracking information to your packages, such as carrier, item, and SKU details. For more information, refer to **Step 4: Shipment tracking** in the preceding **Sample JSON order request 2: Multi-step order flow** section.

  ### Sample JSON order request 3: Multi-step order flow with authorize API

  This is similar to the previous examples which pass the intent as `CAPTURE`, but you need to use one of the Payments v2 API endpoints to complete the order. For more details, refer to the “Authorize” example of **Step 3: Authorize or capture order** in the preceding **Sample JSON order request 2: Multi-step order flow** section.

  #### Step 1: Create order

  Set the order `intent` to `AUTHORIZE`. A successful capture order request returns an HTTPS `200 OK` status code.

  #### Step 2: Buyer approval

  The buyer approves or cancels the payment in this step. For more information refer to **Step 2: Buyer Approval** in the preceding **Sample JSON order request 2: Single-step order flow** section.

  #### Step 3: Authorize order

  An authorize order request accepts `payment_source` as an optional input, like a capture order request.

  Sample authorize order request with payment source:

  ```bash lines expandable Request theme={null}
  curl -v -X POST "https://api-m.sandbox.paypal.com/v2/checkout/orders/"
  -H 'Content-Type: application/json'
  -H 'Authorization: Bearer ACCESS-TOKEN'
  -d '{
      "intent": "AUTHORIZE",
      "purchase_units": [
          {
              "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
              "amount": {
                  "currency_code": "USD",
                  "value": "100.00"
              }
          }
      ],
      "payment_source": {
          "card": {
              "number": "1111111111111111",
               "expiry": "2028-12",
               "name": "Firstname Lastname",
              "billing_address": {
                  "address_line_1": "123 Main St.",
                  "admin_area_1": "CA",
                  "admin_area_2": "Anytown",
                  "postal_code": "12345",
                  "country_code": "US"
              },
              "attributes": {
                  "customer": {
                      "email_address": "payer@example.com",
                      "phone": {
                          "phone_number": {
                              "national_number": "5555555555"
                          }
                      }
                  }
              }
          }
      }
  }'
  ```

  #### Step 4: Capture payment

  Capture the authorized payment by calling the Capture authorized payment endpoint of the Payments v2 API using a `POST` request to `/v2/payments/authorizations/AUTHORIZATION-ID/capture`. Replace `AUTHORIZATION-ID` with the authorization ID returned in **Step 3: Authorize order**. This step triggers a call to the payment gateway to capture the payment.

  > **Note:** The Payments capture is not the Order capture call, and the request body isn't mandatory.

  #### Step 5: Shipment tracking

  If you have physical goods in your order, you can use the Shipment Tracking API to add tracking information to your packages, such as carrier, item, and SKU details. For more information, refer to **Step 4: Shipment tracking** in the preceding **Sample JSON order request 2: Multi-step order flow**.

  ### Sample JSON order request 4: Pay with Venmo

  The previous workflows and samples that used PayPal as the payment method also apply to Venmo. Use the same code samples, but change the `payment_source` to Venmo.

  Sample create order request and response using Venmo:

  <CodeGroup>
    ```bash lines expandable Request theme={null}
    curl -v -X POST "https://api-m.sandbox.paypal.com/v2/checkout/orders/"
    -H 'Content-Type: application/json'
    -H 'Authorization: Bearer ACCESS-TOKEN'
    -d '
    {
        "intent": "CAPTURE",
        "purchase_units": [
            {
                "amount": {
                    "currency_code": "USD",
                    "value": "100.00"
                }
            }
        ],
        "payment_source": {
            "venmo": {
                "email_address": "payer@example.com",
                "experience_context": {
                    "shipping_preference": "GET_FROM_FILE",
                    "brand_name": "EXAMPLE INC"
                }
            }
        }
    }'
    ```

    ```json lines expandable Response theme={null}
    {
        "id": "ORDER-ID",
        "status": "PAYER_ACTION_REQUIRED",
        "payment_source": {
            "venmo": {
                "email_address": "payer@example.com"
            }
        },
        "links": [
            {
                "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
                "rel": "self",
                "method": "GET"
            }
        ]
    }
    ```
  </CodeGroup>
</View>


# PayPal standard payments
Source: https://docs.paypal.ai/payments/methods/paypal/overview



Accept PayPal payments on your website. Customers can select the PayPal button on your site and pay with any funding source linked to their PayPal account.

Use the quickstart integration to get a localhost demo up and running. The quickstart includes sample code for:

* server-side integration using the [Orders v2 API](/reference/api/rest/orders/create-order)
* client-side integration using the [PayPal JavaScript SDK v6](/reference/sdk/js/v6/reference)

After completing the quickstart, extend your PayPal integration with additional features such as order management, authorization handling, and specialized payment flows. Choose the features that match your business needs.

Add server-side endpoints to handle refunds, voids, delayed captures, and specialized checkout flows. Each feature builds on the [quickstart integration](/payments/methods/paypal/integrate).

## Common use cases

Choose the features that match your business model. You can implement all of these programmatically.

<Tip>
  Merchants can also add tracking, mark shipments, and issue refunds directly in the PayPal business dashboard.
</Tip>

### Retail and ecommerce

* [Refund a payment](/payments/methods/paypal/refund) - Handle returns and cancellations.

### Services and hospitality

* [Delay capture](/payments/methods/paypal/delayed-capture): Charge after service delivery.
* [Void an authorization](/payments/methods/paypal/void-an-authorization): Cancel holds before charging.
* [Buy online, pick up in store](/payments/methods/paypal/buy-online-pick-up-in-store): Verify pickup before capturing.

### Recurring payments and extended fulfillment

* [Recurring payments](/payments/methods/paypal/save): Save and reuse stored payment methods.
* [Reauthorize an authorization](/payments/methods/paypal/reauthorize): Extend payment holds beyond 3 days.

## Authorization vs. capture

Authorization holds funds on the buyer's payment method to confirm they can pay, but doesn't transfer money.

Capture moves the funds from the buyer to the merchant account. There are two capture flows:

* Immediate capture: Authorization and capture occur in one step.
* Authorize then capture: Authorization occurs first, then capture occurs later when the merchant is ready to fulfill the order.

| Flow                   | When to use                                      | Features available                                                  |
| :--------------------- | :----------------------------------------------- | :------------------------------------------------------------------ |
| Immediate capture      | Ship within 3 days                               | Refunds, shipping and tax, split shipments                          |
| Authorize then capture | Ship after 3+ days or require order verification | Void, delayed capture, reauthorization, buy online pick up in store |

## Next steps

Complete the quickstart PayPal integration, then add features to match your business needs.


# Extend an authorization
Source: https://docs.paypal.ai/payments/methods/paypal/reauthorize



Extend the validity of an existing authorization when fulfillment takes longer than the initial authorization period. In the United States, authorizations are valid for 3 days, and up to 29 days in other regions. Reauthorization allows the merchant to keep funds available without requiring the buyer to re-approve payment.

Common scenarios include:

* Custom or made-to-order items with extended production times
* Backorders with delayed inventory availability
* International shipments with longer fulfillment windows
* Pre-orders for unreleased products
* Fulfillment delays due to operational or external factors
* High-value orders requiring additional verification before shipping

This integration uses the Payments API v2 to reauthorize an existing authorization and generate a new authorization with a refreshed expiration date.

## Prerequisites

* Complete [the quick start PayPal integration](/payments/methods/paypal/integrate).
* An existing authorization ID that is past the initial honor period (3+ days old).
* A server environment capable of securely calling PayPal REST APIs.

## Integrate server side

Add the following endpoint to your existing server file from the quick start integration.

<CodeGroup>
  ```bash cURL lines expandable theme={null}
  # Reauthorize for the same amount
  curl -X POST https://api-m.sandbox.paypal.com/v2/payments/authorizations/AUTHORIZATION_ID/reauthorize \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -d '{}'

  # Reauthorize for a higher amount (up to 115% of original)
  curl -X POST https://api-m.sandbox.paypal.com/v2/payments/authorizations/AUTHORIZATION_ID/reauthorize \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -d '{
      "amount": {
        "currency_code": "USD",
        "value": "115.00"
      }
    }'

  # Get reauthorization status
  curl -X GET https://api-m.sandbox.paypal.com/v2/payments/authorizations/NEW_AUTHORIZATION_ID \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ACCESS_TOKEN"
  ```

  ```javascript Node.js lines expandable theme={null}
  // Add endpoint for reauthorization
  app.post('/api/paypal/reauthorize-payment', async (req, res) => {
    const { authorizationID, amount } = req.body;
    if (!authorizationID) {
      return res.status(400).json({ error: 'Missing authorizationID' });
    }
    const accessToken = await getPayPalAccessToken();
    const apiBase = process.env.PAYPAL_API_BASE || 'https://api-m.sandbox.paypal.com';
    const reauthorizeRequest = {
      amount: amount || undefined // Optional: up to 115% of original amount
    };
    try {
      const response = await fetch(
        `${apiBase}/v2/payments/authorizations/${authorizationID}/reauthorize`,
        {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${accessToken}`,
          },
          body: JSON.stringify(reauthorizeRequest),
        }
      );
      if (!response.ok) {
        const error = await response.json();
        throw new Error(error.message || 'Reauthorization failed');
      }
      const reauthorization = await response.json();
      res.json({
        status: 'REAUTHORIZED',
        newAuthorizationId: reauthorization.id,
        amount: reauthorization.amount,
        expirationTime: reauthorization.expiration_time
      });
    } catch (err) {
      if (err.message.includes('AUTHORIZATION_ALREADY_COMPLETED')) {
        res.status(400).json({ error: 'Authorization already captured or voided' });
      } else if (err.message.includes('REAUTHORIZE_NOT_ALLOWED')) {
        res.status(400).json({ error: 'Reauthorization not allowed (too soon or expired)' });
      } else {
        res.status(500).json({ error: err.message });
      }
    }
  });
  ```

  ```python Python lines expandable theme={null}
  from paypalrestsdk import Api, Authorization
  import os

  # Configure PayPal SDK
  api = Api({
    'mode': 'sandbox',
    'client_id': os.environ['PAYPAL_CLIENT_ID'],
    'client_secret': os.environ['PAYPAL_CLIENT_SECRET']
  })

  # Process reauthorization
  @app.route('/api/paypal/reauthorize-payment', methods=['POST'])
  def reauthorize_payment():
    try:
      authorization_id = request.json.get('authorizationID')
      amount = request.json.get('amount')

      if not authorization_id:
        return jsonify({'error': 'Missing authorizationID'}), 400

      # Get authorization
      authorization = Authorization.find(authorization_id)

      # Reauthorize with optional amount
      reauthorize_data = {}
      if amount:
        reauthorize_data['amount'] = {
          'value': amount['value'],
          'currency_code': amount.get('currency_code', 'USD')
        }

      # Execute reauthorization
      reauthorization = authorization.reauthorize(reauthorize_data)

      if reauthorization.success():
        return jsonify({
          'status': 'REAUTHORIZED',
          'newAuthorizationId': reauthorization.id,
          'amount': reauthorization.amount,
          'expirationTime': reauthorization.expiration_time
        })
      else:
        error = reauthorization.error
        if error.get('name') == 'AUTHORIZATION_ALREADY_COMPLETED':
          return jsonify({
            'error': 'Authorization already captured or voided'
          }), 400
        elif error.get('name') == 'REAUTHORIZE_NOT_ALLOWED':
          return jsonify({
            'error': 'Reauthorization not allowed (too soon or expired)'
          }), 400
        else:
          return jsonify({'error': error.get('message')}), 500

    except Exception as e:
      return jsonify({'error': str(e)}), 500
  ```

  ```java Java lines expandable theme={null}
  import com.paypal.core.PayPalEnvironment;
  import com.paypal.core.PayPalHttpClient;
  import com.paypal.payments.AuthorizationsReauthorizeRequest;
  import com.paypal.payments.Authorization;
  import com.paypal.payments.Money;

  HttpClient httpClient = new PayPalHttpClient(
    new SandboxEnvironment(
      System.getenv("PAYPAL_CLIENT_ID"),
      System.getenv("PAYPAL_CLIENT_SECRET")
    )
  );

  // Process reauthorization
  @PostMapping("/api/paypal/reauthorize-payment")
  public ResponseEntity<?> reauthorizePayment(
    @RequestBody ReauthorizeRequest reauthorizeRequest
  ) {
    try {
      String authorizationId = reauthorizeRequest.getAuthorizationID();

      if (authorizationId == null || authorizationId.isEmpty()) {
        return ResponseEntity.badRequest().body(
          Map.of("error", "Missing authorizationID")
        );
      }

      AuthorizationsReauthorizeRequest request =
        new AuthorizationsReauthorizeRequest(authorizationId);

      // Set reauthorization amount if provided (up to 115% of original)
      if (reauthorizeRequest.getAmount() != null) {
        ReauthorizeRequestBody body = new ReauthorizeRequestBody()
          .amount(new Money()
            .value(reauthorizeRequest.getAmount().getValue())
            .currencyCode(reauthorizeRequest.getAmount()
              .getCurrencyCode() != null ?
              reauthorizeRequest.getAmount().getCurrencyCode() : "USD")
          );
        request.requestBody(body);
      }

      HttpResponse<Authorization> response = httpClient.execute(request);
      Authorization reauthorization = response.result();

      return ResponseEntity.ok(Map.of(
        "status", "REAUTHORIZED",
        "newAuthorizationId", reauthorization.id(),
        "amount", reauthorization.amount(),
        "expirationTime", reauthorization.expirationTime()
      ));

    } catch (HttpClientException e) {
      String issue = extractIssue(e);
      if ("AUTHORIZATION_ALREADY_COMPLETED".equals(issue)) {
        return ResponseEntity.badRequest().body(
          Map.of("error", "Authorization already captured or voided")
        );
      } else if ("REAUTHORIZE_NOT_ALLOWED".equals(issue)) {
        return ResponseEntity.badRequest().body(
          Map.of("error", "Reauthorization not allowed (too soon or expired)")
        );
      }
      return ResponseEntity.status(500).body(
        Map.of("error", e.getMessage())
      );
    }
  }
  ```

  ```php PHP lines expandable theme={null}
  <?php
  use PayPalCheckoutSdk\Core\SandboxEnvironment;
  use PayPalCheckoutSdk\Core\PayPalHttpClient;
  use PayPalCheckoutSdk\Payments\AuthorizationsReauthorizeRequest;

  $environment = new SandboxEnvironment(
    getenv('PAYPAL_CLIENT_ID'),
    getenv('PAYPAL_CLIENT_SECRET')
  );
  $client = new PayPalHttpClient($environment);

  // Process reauthorization
  $app->post('/api/paypal/reauthorize-payment', function ($request, $response) use ($client) {
    $body = $request->getParsedBody();
    $authorizationID = $body['authorizationID'] ?? null;

    if (!$authorizationID) {
      $response->getBody()->write(json_encode([
        'error' => 'Missing authorizationID'
      ]));
      return $response->withStatus(400)->withHeader('Content-Type', 'application/json');
    }

    $reauthorizeRequest = new AuthorizationsReauthorizeRequest($authorizationID);

    // Set reauthorization amount if provided (up to 115% of original)
    if (isset($body['amount'])) {
      $reauthorizeRequest->body = [
        'amount' => [
          'value' => $body['amount']['value'],
          'currency_code' => $body['amount']['currency_code'] ?? 'USD'
        ]
      ];
    }

    try {
      $reauthorizeResponse = $client->execute($reauthorizeRequest);
      $reauthorization = $reauthorizeResponse->result;

      $response->getBody()->write(json_encode([
        'status' => 'REAUTHORIZED',
        'newAuthorizationId' => $reauthorization->id,
        'amount' => $reauthorization->amount,
        'expirationTime' => $reauthorization->expiration_time
      ]));
      return $response->withHeader('Content-Type', 'application/json');

    } catch (HttpException $e) {
      $statusCode = $e->statusCode;
      $errorData = json_decode($e->getMessage(), true);
      $issue = $errorData['details'][0]['issue'] ?? '';

      if ($issue === 'AUTHORIZATION_ALREADY_COMPLETED') {
        $response->getBody()->write(json_encode([
          'error' => 'Authorization already captured or voided'
        ]));
        return $response->withStatus(400)->withHeader('Content-Type', 'application/json');
      } else if ($issue === 'REAUTHORIZE_NOT_ALLOWED') {
        $response->getBody()->write(json_encode([
          'error' => 'Reauthorization not allowed (too soon or expired)'
        ]));
        return $response->withStatus(400)->withHeader('Content-Type', 'application/json');
      }

      $response->getBody()->write(json_encode([
        'error' => $e->getMessage()
      ]));
      return $response->withStatus(500)->withHeader('Content-Type', 'application/json');
    }
  });
  ```

  ```ruby Ruby lines expandable theme={null}
  require 'paypal-sdk'

  # Configure PayPal SDK
  PayPal::SDK.configure(
    :mode => "sandbox",
    :app_id => ENV['PAYPAL_APP_ID'],
    :client_id => ENV['PAYPAL_CLIENT_ID'],
    :client_secret => ENV['PAYPAL_CLIENT_SECRET']
  )

  # Process reauthorization
  post '/api/paypal/reauthorize-payment' do
    request_body = JSON.parse(request.body.read)
    authorization_id = request_body['authorizationID']

    if authorization_id.nil? || authorization_id.empty?
      status 400
      return { error: 'Missing authorizationID' }.to_json
    end

    begin
      # Get authorization
      authorization = PayPal::SDK::PaymentsApi::Authorization.find(authorization_id)

      # Prepare reauthorization data
      reauthorize_data = {}
      if request_body['amount']
        reauthorize_data[:amount] = {
          value: request_body['amount']['value'],
          currency_code: request_body['amount']['currency_code'] || 'USD'
        }
      end

      # Execute reauthorization
      reauthorization = authorization.reauthorize(reauthorize_data)

      if reauthorization.success?
        content_type :json
        {
          status: 'REAUTHORIZED',
          newAuthorizationId: reauthorization.id,
          amount: reauthorization.amount,
          expirationTime: reauthorization.expiration_time
        }.to_json
      else
        error = reauthorization.error
        if error['name'] == 'AUTHORIZATION_ALREADY_COMPLETED'
          status 400
          { error: 'Authorization already captured or voided' }.to_json
        elsif error['name'] == 'REAUTHORIZE_NOT_ALLOWED'
          status 400
          { error: 'Reauthorization not allowed (too soon or expired)' }.to_json
        else
          status 500
          { error: error['message'] }.to_json
        end
      end

    rescue => e
      status 500
      { error: e.message }.to_json
    end
  end
  ```
</CodeGroup>

## Test endpoint

<Info>
  Endpoint: [`/v2/payments/authorizations/{authorization_id}/reauthorize`](/reference/api/rest/authorizations/reauthorize-authorized-payment)
</Info>

<CodeGroup>
  ```bash cURL lines expandable theme={null}
  # Reauthorize for the same amount
  curl -X POST http://localhost:3000/api/paypal/reauthorize-payment \
    -H "Content-Type: application/json" \
    -d '{"authorizationID": "5AB67890CD123456E"}'

  # Expected success response:
  # {"status":"REAUTHORIZED","newAuthorizationId":"8CD12345EF678901A","amount":{"currency_code":"USD","value":"100.00"},"expirationTime":"2024-02-05T10:23:23Z"}

  # Reauthorize for a higher amount (up to 115% of original)
  curl -X POST http://localhost:3000/api/paypal/reauthorize-payment \
    -H "Content-Type: application/json" \
    -d '{
      "authorizationID": "5AB67890CD123456E",
      "amount": {
        "currency_code": "USD",
        "value": "115.00"
      }
    }'

  # Expected success response:
  # {"status":"REAUTHORIZED","newAuthorizationId":"8CD12345EF678901A","amount":{"currency_code":"USD","value":"115.00"},"expirationTime":"2024-02-05T10:23:23Z"}
  ```

  ```javascript Node.js lines expandable theme={null}
  // Test reauthorize for the same amount
  const sameAmountResponse = await fetch('http://localhost:3000/api/paypal/reauthorize-payment', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      authorizationID: '5AB67890CD123456E'
    })
  });
  const sameAmount = await sameAmountResponse.json();
  console.log('Reauthorized:', sameAmount);
  // Expected: {"status":"REAUTHORIZED","newAuthorizationId":"8CD12345EF678901A","amount":{"currency_code":"USD","value":"100.00"},"expirationTime":"2024-02-05T10:23:23Z"}

  // Test reauthorize for a higher amount (up to 115% of original)
  const higherAmountResponse = await fetch('http://localhost:3000/api/paypal/reauthorize-payment', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      authorizationID: '5AB67890CD123456E',
      amount: {
        currency_code: 'USD',
        value: '115.00'
      }
    })
  });
  const higherAmount = await higherAmountResponse.json();
  console.log('Reauthorized with higher amount:', higherAmount);
  // Expected: {"status":"REAUTHORIZED","newAuthorizationId":"8CD12345EF678901A","amount":{"currency_code":"USD","value":"115.00"},"expirationTime":"2024-02-05T10:23:23Z"}
  ```

  ```python Python lines expandable theme={null}
  import requests

  # Test reauthorize for the same amount
  same_amount_response = requests.post(
    'http://localhost:3000/api/paypal/reauthorize-payment',
    headers={'Content-Type': 'application/json'},
    json={'authorizationID': '5AB67890CD123456E'}
  )
  print('Reauthorized:', same_amount_response.json())
  # Expected: {"status":"REAUTHORIZED","newAuthorizationId":"8CD12345EF678901A","amount":{"currency_code":"USD","value":"100.00"},"expirationTime":"2024-02-05T10:23:23Z"}

  # Test reauthorize for a higher amount (up to 115% of original)
  higher_amount_response = requests.post(
    'http://localhost:3000/api/paypal/reauthorize-payment',
    headers={'Content-Type': 'application/json'},
    json={
      'authorizationID': '5AB67890CD123456E',
      'amount': {
        'currency_code': 'USD',
        'value': '115.00'
      }
    }
  )
  print('Reauthorized with higher amount:', higher_amount_response.json())
  # Expected: {"status":"REAUTHORIZED","newAuthorizationId":"8CD12345EF678901A","amount":{"currency_code":"USD","value":"115.00"},"expirationTime":"2024-02-05T10:23:23Z"}
  ```

  ```java Java lines expandable theme={null}
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.net.URI;

  HttpClient client = HttpClient.newHttpClient();

  // Test reauthorize for the same amount
  String sameAmountBody = "{\"authorizationID\":\"5AB67890CD123456E\"}";
  HttpRequest sameAmountRequest = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:3000/api/paypal/reauthorize-payment"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(sameAmountBody))
    .build();

  HttpResponse<String> sameAmountResponse = client.send(
    sameAmountRequest,
    HttpResponse.BodyHandlers.ofString()
  );
  System.out.println("Reauthorized: " + sameAmountResponse.body());
  // Expected: {"status":"REAUTHORIZED","newAuthorizationId":"8CD12345EF678901A","amount":{"currency_code":"USD","value":"100.00"},"expirationTime":"2024-02-05T10:23:23Z"}

  // Test reauthorize for a higher amount (up to 115% of original)
  String higherAmountBody = "{\"authorizationID\":\"5AB67890CD123456E\",\"amount\":{\"currency_code\":\"USD\",\"value\":\"115.00\"}}";
  HttpRequest higherAmountRequest = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:3000/api/paypal/reauthorize-payment"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(higherAmountBody))
    .build();

  HttpResponse<String> higherAmountResponse = client.send(
    higherAmountRequest,
    HttpResponse.BodyHandlers.ofString()
  );
  System.out.println("Reauthorized with higher amount: " + higherAmountResponse.body());
  // Expected: {"status":"REAUTHORIZED","newAuthorizationId":"8CD12345EF678901A","amount":{"currency_code":"USD","value":"115.00"},"expirationTime":"2024-02-05T10:23:23Z"}
  ```

  ```php PHP lines expandable theme={null}
  <?php
  // Test reauthorize for the same amount
  $sameAmountData = json_encode([
    'authorizationID' => '5AB67890CD123456E'
  ]);

  $sameAmountResponse = file_get_contents(
    'http://localhost:3000/api/paypal/reauthorize-payment',
    false,
    stream_context_create([
      'http' => [
        'method' => 'POST',
        'header' => 'Content-Type: application/json',
        'content' => $sameAmountData
      ]
    ])
  );
  echo "Reauthorized: " . $sameAmountResponse . "\n";
  // Expected: {"status":"REAUTHORIZED","newAuthorizationId":"8CD12345EF678901A","amount":{"currency_code":"USD","value":"100.00"},"expirationTime":"2024-02-05T10:23:23Z"}

  // Test reauthorize for a higher amount (up to 115% of original)
  $higherAmountData = json_encode([
    'authorizationID' => '5AB67890CD123456E',
    'amount' => [
      'currency_code' => 'USD',
      'value' => '115.00'
    ]
  ]);

  $higherAmountResponse = file_get_contents(
    'http://localhost:3000/api/paypal/reauthorize-payment',
    false,
    stream_context_create([
      'http' => [
        'method' => 'POST',
        'header' => 'Content-Type: application/json',
        'content' => $higherAmountData
      ]
    ])
  );
  echo "Reauthorized with higher amount: " . $higherAmountResponse . "\n";
  // Expected: {"status":"REAUTHORIZED","newAuthorizationId":"8CD12345EF678901A","amount":{"currency_code":"USD","value":"115.00"},"expirationTime":"2024-02-05T10:23:23Z"}
  ```

  ```ruby Ruby lines expandable theme={null}
  require 'net/http'
  require 'json'

  # Test reauthorize for the same amount
  uri = URI('http://localhost:3000/api/paypal/reauthorize-payment')
  same_amount_request = Net::HTTP::Post.new(uri)
  same_amount_request['Content-Type'] = 'application/json'
  same_amount_request.body = {
    authorizationID: '5AB67890CD123456E'
  }.to_json

  same_amount_response = Net::HTTP.start(uri.hostname, uri.port) do |http|
    http.request(same_amount_request)
  end
  puts "Reauthorized: #{same_amount_response.body}"
  # Expected: {"status":"REAUTHORIZED","newAuthorizationId":"8CD12345EF678901A","amount":{"currency_code":"USD","value":"100.00"},"expirationTime":"2024-02-05T10:23:23Z"}

  # Test reauthorize for a higher amount (up to 115% of original)
  higher_amount_request = Net::HTTP::Post.new(uri)
  higher_amount_request['Content-Type'] = 'application/json'
  higher_amount_request.body = {
    authorizationID: '5AB67890CD123456E',
    amount: {
      currency_code: 'USD',
      value: '115.00'
    }
  }.to_json

  higher_amount_response = Net::HTTP.start(uri.hostname, uri.port) do |http|
    http.request(higher_amount_request)
  end
  puts "Reauthorized with higher amount: #{higher_amount_response.body}"
  # Expected: {"status":"REAUTHORIZED","newAuthorizationId":"8CD12345EF678901A","amount":{"currency_code":"USD","value":"115.00"},"expirationTime":"2024-02-05T10:23:23Z"}
  ```
</CodeGroup>

## Best practices

* **Reauthorize within the valid window:** Reauthorization is allowed only between days 4-29 after the original authorization, depending on region.
* **Reauthorize only once:** Each authorization can be reauthorized a single time. If more time is required, create a new order.
* **Monitor authorization expiration:** Track expiration dates and trigger reauthorization before the authorization lapses.
* **Respect amount limits:** You can reauthorize for up to 115% of the original amount in most regions. Regional limits may vary.
* **Handle failures gracefully:** If reauthorization fails, void the original authorization and request a new payment from the customer.

## Important details

* **Authorization validity periods:** Authorizations are valid for 3 days in the US and up to 29 days in most other regions. After expiration, funds are automatically released to the customer.
* **Reauthorization timing window:** You can only reauthorize between days 4-29 after the initial authorization. Attempts before day 3 or after day 29 will fail.
* **Single reauthorization limit:** Each authorization can be reauthorized only once. If you need more time after reauthorization, void the authorization and create a new order.
* **No customer interaction required:** Reauthorization happens server-side without customer approval. However, consider notifying customers as a courtesy when extending payment holds.
* **Handling reauthorization failures:** If reauthorization fails, void the original authorization and request new payment from the customer. Common failures include insufficient funds, authorization already captured or voided, or attempting outside the valid window.

## Test your integration

Run the following standard tests on your integration.

| Test scenario                     | Setup                                                           | Expected result                                          |
| :-------------------------------- | :-------------------------------------------------------------- | :------------------------------------------------------- |
| Successful reauthorization        | Create authorization, wait 4+ days, reauthorize for same amount | New authorization created with a fresh expiration date.  |
| Reauthorize for higher amount     | Reauthorize for 110% of original amount                         | New authorization created for increased amount.          |
| Reauthorize too soon              | Attempt within 3 days of original authorization                 | Error: reauthorization not available yet.                |
| Reauthorize expired authorization | Attempt after 30+ days                                          | Error: authorization expired and cannot be reauthorized. |
| Reauthorize more than once        | Reauthorize successfully, then attempt again                    | Error: cannot reauthorize more than once.                |

## Go-live checklist

* Test reauthorization in sandbox using the time machine.
* Verify handling of amount limits (up to 115%).
* Test error handling for all reauthorization error cases.
* Implement authorization expiration monitoring.
* Switch to production API credentials.


# Refund a payment
Source: https://docs.paypal.ai/payments/methods/paypal/refund



Refund captured payments to customers after an initial transaction. Common scenarios include:

* Customer returns a product or requests a refund from a service
* Customer cancels an order after payment
* Customer requests a partial refund

This integration uses the Payments API v2 to process full or partial refunds with the capture ID from the original payment. Add refund endpoints to your existing PayPal integration with comprehensive error handling and negative testing capabilities.

<Tip>
  If you've [authorized a payment but not captured it yet](/payments/methods/paypal/overview#authorization-vs-capture), use [void instead of refund to avoid processing fees](/payments/methods/paypal/void-an-authorization).
</Tip>

## Prerequisites

* Complete [the quick start PayPal integration](/payments/methods/paypal/integrate).
* You have a capture ID from the original payment transaction.
* You have a database or system to track payment and refund history.

## Integrate server side

Add the following to your existing server file from the quick start integration.

<CodeGroup>
  ```bash cURL expandable lines theme={null}
  # Refund a captured payment
  curl -X POST https://api-m.sandbox.paypal.com/v2/payments/captures/CAPTURE_ID/refund \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -d '{
      "amount": {
        "value": "25.00",
        "currency_code": "USD"
      },
      "note_to_payer": "Refund processed"
    }'

  # Get refund status
  curl -X GET https://api-m.sandbox.paypal.com/v2/payments/refunds/REFUND_ID \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ACCESS_TOKEN"
  ```

  ```javascript Node.js lines expandable theme={null}
  // Add these endpoints to your existing server.js from the quick start integration
  // The PayPal client and addNegativeTesting helper are already configured

  // Process refund
  app.post('/api/captures/:captureID/refund', async (req, res) => {
    const request = new paypal.payments.CapturesRefundRequest(req.params.captureID);

    // Optional: Set refund amount (if not set, refunds full amount)
    if (req.body.amount) {
      request.requestBody({
        amount: {
          value: req.body.amount,
          currency_code: 'USD'
        },
        note_to_payer: req.body.note || 'Refund processed'
      });
    }

    // Apply negative testing if enabled (reuse helper from base integration)
    addNegativeTesting(request);

    try {
      const refund = await client.execute(request);
      res.json({
        id: refund.result.id,
        status: refund.result.status,
        amount: refund.result.amount.value
      });
    } catch (err) {
      // Handle specific refund errors
      if (err.statusCode === 422) {
        const errorDetail = err.details?.[0];
        if (errorDetail?.issue === 'CAPTURE_FULLY_REFUNDED') {
          res.status(400).json({
            error: 'Cannot refund - already refunded. Check capture status.',
            captureId: req.params.captureID
          });
        } else if (errorDetail?.issue === 'REFUND_AMOUNT_EXCEEDED') {
          res.status(400).json({
            error: 'Refund amount exceeds available balance',
            maxRefundable: errorDetail.description
          });
        } else {
          res.status(400).json({
            error: 'Invalid refund request'
          });
        }
      } else {
        res.status(500).json({
          error: err.message
        });
      }
    }
  });

  // Get refund status (optional but useful)
  app.get('/api/refunds/:refundID', async (req, res) => {
    const request = new paypal.payments.RefundsGetRequest(req.params.refundID);
    addNegativeTesting(request);

    try {
      const refund = await client.execute(request);
      res.json({
        id: refund.result.id,
        status: refund.result.status,
        amount: refund.result.amount.value
      });
    } catch (err) {
      res.status(404).json({
        error: 'Refund not found'
      });
    }
  });
  ```

  ```python Python lines expandable theme={null}
  from paypalrestsdk import Api, Refund, Capture
  import os

  # Configure PayPal SDK
  api = Api({
    'mode': 'sandbox',
    'client_id': os.environ['PAYPAL_CLIENT_ID'],
    'client_secret': os.environ['PAYPAL_CLIENT_SECRET']
  })

  # Process refund
  @app.route('/api/captures/<capture_id>/refund', methods=['POST'])
  def process_refund(capture_id):
    try:
      refund_data = {
        "amount": {
          "value": request.json.get('amount'),
          "currency": "USD"
        },
        "note_to_payer": request.json.get('note', 'Refund processed')
      }

      # Create refund
      refund = Refund({
        "capture_id": capture_id,
        **refund_data
      })

      if refund.create():
        return jsonify({
          "id": refund.id,
          "status": refund.state,
          "amount": refund.amount.total
        })
      else:
        # Handle errors
        error = refund.error
        if error.get('name') == 'CAPTURE_FULLY_REFUNDED':
          return jsonify({
            "error": "Cannot refund - already refunded"
          }), 400
        elif error.get('name') == 'REFUND_AMOUNT_EXCEEDED':
          return jsonify({
            "error": "Refund amount exceeds available balance"
          }), 400
        else:
          return jsonify({"error": error.get('message')}), 500

    except Exception as e:
      return jsonify({"error": str(e)}), 500

  # Get refund status
  @app.route('/api/refunds/<refund_id>', methods=['GET'])
  def get_refund_status(refund_id):
    try:
      refund = Refund.find(refund_id)
      return jsonify({
        "id": refund.id,
        "status": refund.state,
        "amount": refund.amount.total
      })
    except Exception as e:
      return jsonify({"error": "Refund not found"}), 404
  ```

  ```java Java lines expandable theme={null}
  import com.paypal.core.PayPalEnvironment;
  import com.paypal.core.PayPalHttpClient;
  import com.paypal.payments.CapturesRefundRequest;
  import com.paypal.payments.RefundsGetRequest;
  import com.paypal.payments.Refund;

  HttpClient httpClient = new PayPalHttpClient(
    new SandboxEnvironment(
      System.getenv("PAYPAL_CLIENT_ID"),
      System.getenv("PAYPAL_CLIENT_SECRET")
    )
  );

  // Process refund
  @PostMapping("/api/captures/{captureId}/refund")
  public ResponseEntity<?> processRefund(
    @PathVariable String captureId,
    @RequestBody RefundRequest refundRequest
  ) {
    try {
      CapturesRefundRequest request = new CapturesRefundRequest(captureId);

      // Set refund amount if provided
      if (refundRequest.getAmount() != null) {
        RefundRequestBody body = new RefundRequestBody()
          .amount(new Money()
            .value(refundRequest.getAmount())
            .currencyCode("USD")
          )
          .noteToPayer(refundRequest.getNote() != null ?
            refundRequest.getNote() : "Refund processed"
          );
        request.requestBody(body);
      }

      HttpResponse<Refund> response = httpClient.execute(request);
      Refund refund = response.result();

      return ResponseEntity.ok(Map.of(
        "id", refund.id(),
        "status", refund.status(),
        "amount", refund.amount().value()
      ));

    } catch (HttpClientException e) {
      if (e.statusCode() == 422) {
        String issue = extractIssue(e);
        if ("CAPTURE_FULLY_REFUNDED".equals(issue)) {
          return ResponseEntity.badRequest().body(
            Map.of("error", "Cannot refund - already refunded")
          );
        } else if ("REFUND_AMOUNT_EXCEEDED".equals(issue)) {
          return ResponseEntity.badRequest().body(
            Map.of("error", "Refund amount exceeds available balance")
          );
        }
      }
      return ResponseEntity.status(500).body(
        Map.of("error", e.getMessage())
      );
    }
  }

  // Get refund status
  @GetMapping("/api/refunds/{refundId}")
  public ResponseEntity<?> getRefundStatus(@PathVariable String refundId) {
    try {
      RefundsGetRequest request = new RefundsGetRequest(refundId);
      HttpResponse<Refund> response = httpClient.execute(request);
      Refund refund = response.result();

      return ResponseEntity.ok(Map.of(
        "id", refund.id(),
        "status", refund.status(),
        "amount", refund.amount().value()
      ));
    } catch (Exception e) {
      return ResponseEntity.status(404).body(
        Map.of("error", "Refund not found")
      );
    }
  }
  ```

  ```php PHP lines expandable theme={null}
  <?php
  use PayPalCheckoutSdk\Core\SandboxEnvironment;
  use PayPalCheckoutSdk\Core\PayPalHttpClient;
  use PayPalCheckoutSdk\Payments\CapturesRefundRequest;
  use PayPalCheckoutSdk\Payments\RefundsGetRequest;

  $environment = new SandboxEnvironment(
    getenv('PAYPAL_CLIENT_ID'),
    getenv('PAYPAL_CLIENT_SECRET')
  );
  $client = new PayPalHttpClient($environment);

  // Process refund
  $app->post('/api/captures/{captureID}/refund', function ($request, $response, $args) use ($client) {
    $captureID = $args['captureID'];
    $body = $request->getParsedBody();

    $refundRequest = new CapturesRefundRequest($captureID);

    // Set refund amount if provided
    if (isset($body['amount'])) {
      $refundRequest->body = [
        "amount" => [
          "value" => $body['amount'],
          "currency_code" => "USD"
        ],
        "note_to_payer" => $body['note'] ?? "Refund processed"
      ];
    }

    try {
      $refundResponse = $client->execute($refundRequest);
      $refund = $refundResponse->result;

      $response->getBody()->write(json_encode([
        "id" => $refund->id,
        "status" => $refund->status,
        "amount" => $refund->amount->value
      ]));
      return $response->withHeader('Content-Type', 'application/json');

    } catch (HttpException $e) {
      $statusCode = $e->statusCode;
      $errorData = json_decode($e->getMessage(), true);

      if ($statusCode === 422) {
        $issue = $errorData['details'][0]['issue'] ?? '';
        if ($issue === 'CAPTURE_FULLY_REFUNDED') {
          $response->getBody()->write(json_encode([
            "error" => "Cannot refund - already refunded"
          ]));
          return $response->withStatus(400)->withHeader('Content-Type', 'application/json');
        } else if ($issue === 'REFUND_AMOUNT_EXCEEDED') {
          $response->getBody()->write(json_encode([
            "error" => "Refund amount exceeds available balance"
          ]));
          return $response->withStatus(400)->withHeader('Content-Type', 'application/json');
        }
      }

      $response->getBody()->write(json_encode([
        "error" => $e->getMessage()
      ]));
      return $response->withStatus(500)->withHeader('Content-Type', 'application/json');
    }
  });

  // Get refund status
  $app->get('/api/refunds/{refundID}', function ($request, $response, $args) use ($client) {
    $refundID = $args['refundID'];

    try {
      $refundRequest = new RefundsGetRequest($refundID);
      $refundResponse = $client->execute($refundRequest);
      $refund = $refundResponse->result;

      $response->getBody()->write(json_encode([
        "id" => $refund->id,
        "status" => $refund->status,
        "amount" => $refund->amount->value
      ]));
      return $response->withHeader('Content-Type', 'application/json');

    } catch (Exception $e) {
      $response->getBody()->write(json_encode([
        "error" => "Refund not found"
      ]));
      return $response->withStatus(404)->withHeader('Content-Type', 'application/json');
    }
  });
  ```

  ```ruby Ruby lines expandable theme={null}
  require 'paypal-sdk'

  # Configure PayPal SDK
  PayPal::SDK.configure(
    :mode => "sandbox",
    :app_id => ENV['PAYPAL_APP_ID'],
    :client_id => ENV['PAYPAL_CLIENT_ID'],
    :client_secret => ENV['PAYPAL_CLIENT_SECRET']
  )

  # Process refund
  post '/api/captures/:capture_id/refund' do
    capture_id = params['capture_id']
    request_body = JSON.parse(request.body.read)

    begin
      refund_data = {
        amount: {
          value: request_body['amount'],
          currency_code: 'USD'
        },
        note_to_payer: request_body['note'] || 'Refund processed'
      }

      # Create refund
      refund = PayPal::SDK::PaymentsApi::Refund.new(
        capture_id: capture_id,
        **refund_data
      )

      if refund.create
        content_type :json
        {
          id: refund.id,
          status: refund.status,
          amount: refund.amount.value
        }.to_json
      else
        error = refund.error
        if error['name'] == 'CAPTURE_FULLY_REFUNDED'
          status 400
          { error: 'Cannot refund - already refunded' }.to_json
        elsif error['name'] == 'REFUND_AMOUNT_EXCEEDED'
          status 400
          { error: 'Refund amount exceeds available balance' }.to_json
        else
          status 500
          { error: error['message'] }.to_json
        end
      end

    rescue => e
      status 500
      { error: e.message }.to_json
    end
  end

  # Get refund status
  get '/api/refunds/:refund_id' do
    refund_id = params['refund_id']

    begin
      refund = PayPal::SDK::PaymentsApi::Refund.find(refund_id)
      content_type :json
      {
        id: refund.id,
        status: refund.status,
        amount: refund.amount.value
      }.to_json
    rescue => e
      status 404
      { error: 'Refund not found' }.to_json
    end
  end
  ```
</CodeGroup>

### Test endpoints

<Info>
  Endpoints:

  * [`/v2/payments/captures/{capture_id}/refund`](/reference/api/rest/captures/refund-captured-payment)
  * [`/v2/payments/refunds/{refund_id}`](/reference/api/rest/refunds/show-refund-details)
</Info>

<CodeGroup>
  ```bash cURL theme={null}
  # Test full refund (replace with actual capture ID)
  curl -X POST http://localhost:3000/api/captures/3C679366HH908993F/refund \
    -H "Content-Type: application/json"

  # Expected success response:
  # {"id":"WH4YN4SYEDZJA","status":"COMPLETED","amount":"100.00"}

  # Test partial refund with note
  curl -X POST http://localhost:3000/api/captures/3C679366HH908993F/refund \
    -H "Content-Type: application/json" \
    -d '{"amount": "25.00", "note": "Partial refund for damaged item"}'

  # Test refund status check
  curl http://localhost:3000/api/refunds/WH4YN4SYEDZJA

  # Expected response:
  # {"id":"WH4YN4SYEDZJA","status":"COMPLETED","amount":"25.00"}
  ```

  ```javascript Node.js lines expandable theme={null}
  // Test full refund
  const fullRefundResponse = await fetch('http://localhost:3000/api/captures/3C679366HH908993F/refund', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' }
  });
  const fullRefund = await fullRefundResponse.json();
  console.log('Full refund:', fullRefund);
  // Expected: {"id":"WH4YN4SYEDZJA","status":"COMPLETED","amount":"100.00"}

  // Test partial refund with note
  const partialRefundResponse = await fetch('http://localhost:3000/api/captures/3C679366HH908993F/refund', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      amount: '25.00',
      note: 'Partial refund for damaged item'
    })
  });
  const partialRefund = await partialRefundResponse.json();
  console.log('Partial refund:', partialRefund);

  // Test refund status check
  const statusResponse = await fetch('http://localhost:3000/api/refunds/WH4YN4SYEDZJA');
  const status = await statusResponse.json();
  console.log('Refund status:', status);
  // Expected: {"id":"WH4YN4SYEDZJA","status":"COMPLETED","amount":"25.00"}
  ```

  ```python Python theme={null}
  import requests

  # Test full refund
  full_refund_response = requests.post(
    'http://localhost:3000/api/captures/3C679366HH908993F/refund',
    headers={'Content-Type': 'application/json'}
  )
  print('Full refund:', full_refund_response.json())
  # Expected: {"id":"WH4YN4SYEDZJA","status":"COMPLETED","amount":"100.00"}

  # Test partial refund with note
  partial_refund_response = requests.post(
    'http://localhost:3000/api/captures/3C679366HH908993F/refund',
    headers={'Content-Type': 'application/json'},
    json={
      'amount': '25.00',
      'note': 'Partial refund for damaged item'
    }
  )
  print('Partial refund:', partial_refund_response.json())

  # Test refund status check
  status_response = requests.get(
    'http://localhost:3000/api/refunds/WH4YN4SYEDZJA'
  )
  print('Refund status:', status_response.json())
  # Expected: {"id":"WH4YN4SYEDZJA","status":"COMPLETED","amount":"25.00"}
  ```

  ```java Java theme={null}
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.net.URI;

  HttpClient client = HttpClient.newHttpClient();

  // Test full refund
  HttpRequest fullRefundRequest = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:3000/api/captures/3C679366HH908993F/refund"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.noBody())
    .build();

  HttpResponse<String> fullRefundResponse = client.send(
    fullRefundRequest,
    HttpResponse.BodyHandlers.ofString()
  );
  System.out.println("Full refund: " + fullRefundResponse.body());
  // Expected: {"id":"WH4YN4SYEDZJA","status":"COMPLETED","amount":"100.00"}

  // Test partial refund with note
  String partialRefundBody = "{\"amount\":\"25.00\",\"note\":\"Partial refund for damaged item\"}";
  HttpRequest partialRefundRequest = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:3000/api/captures/3C679366HH908993F/refund"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(partialRefundBody))
    .build();

  HttpResponse<String> partialRefundResponse = client.send(
    partialRefundRequest,
    HttpResponse.BodyHandlers.ofString()
  );
  System.out.println("Partial refund: " + partialRefundResponse.body());

  // Test refund status check
  HttpRequest statusRequest = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:3000/api/refunds/WH4YN4SYEDZJA"))
    .GET()
    .build();

  HttpResponse<String> statusResponse = client.send(
    statusRequest,
    HttpResponse.BodyHandlers.ofString()
  );
  System.out.println("Refund status: " + statusResponse.body());
  // Expected: {"id":"WH4YN4SYEDZJA","status":"COMPLETED","amount":"25.00"}
  ```

  ```php PHP theme={null}
  <?php
  // Test full refund
  $fullRefundResponse = file_get_contents(
    'http://localhost:3000/api/captures/3C679366HH908993F/refund',
    false,
    stream_context_create([
      'http' => [
        'method' => 'POST',
        'header' => 'Content-Type: application/json'
      ]
    ])
  );
  echo "Full refund: " . $fullRefundResponse . "\n";
  // Expected: {"id":"WH4YN4SYEDZJA","status":"COMPLETED","amount":"100.00"}

  // Test partial refund with note
  $partialRefundData = json_encode([
    'amount' => '25.00',
    'note' => 'Partial refund for damaged item'
  ]);

  $partialRefundResponse = file_get_contents(
    'http://localhost:3000/api/captures/3C679366HH908993F/refund',
    false,
    stream_context_create([
      'http' => [
        'method' => 'POST',
        'header' => 'Content-Type: application/json',
        'content' => $partialRefundData
      ]
    ])
  );
  echo "Partial refund: " . $partialRefundResponse . "\n";

  // Test refund status check
  $statusResponse = file_get_contents(
    'http://localhost:3000/api/refunds/WH4YN4SYEDZJA'
  );
  echo "Refund status: " . $statusResponse . "\n";
  // Expected: {"id":"WH4YN4SYEDZJA","status":"COMPLETED","amount":"25.00"}
  ```

  ```ruby Ruby lines expandable theme={null}
  require 'net/http'
  require 'json'

  # Test full refund
  uri = URI('http://localhost:3000/api/captures/3C679366HH908993F/refund')
  full_refund_request = Net::HTTP::Post.new(uri)
  full_refund_request['Content-Type'] = 'application/json'

  full_refund_response = Net::HTTP.start(uri.hostname, uri.port) do |http|
    http.request(full_refund_request)
  end
  puts "Full refund: #{full_refund_response.body}"
  # Expected: {"id":"WH4YN4SYEDZJA","status":"COMPLETED","amount":"100.00"}

  # Test partial refund with note
  partial_refund_request = Net::HTTP::Post.new(uri)
  partial_refund_request['Content-Type'] = 'application/json'
  partial_refund_request.body = {
    amount: '25.00',
    note: 'Partial refund for damaged item'
  }.to_json

  partial_refund_response = Net::HTTP.start(uri.hostname, uri.port) do |http|
    http.request(partial_refund_request)
  end
  puts "Partial refund: #{partial_refund_response.body}"

  # Test refund status check
  status_uri = URI('http://localhost:3000/api/refunds/WH4YN4SYEDZJA')
  status_response = Net::HTTP.get_response(status_uri)
  puts "Refund status: #{status_response.body}"
  # Expected: {"id":"WH4YN4SYEDZJA","status":"COMPLETED","amount":"25.00"}
  ```
</CodeGroup>

### Best practices

Use the following best practices to ensure refunds are processed safely, accurately, and in compliance with operational and regulatory requirements.

* **Store capture IDs:** Always save capture IDs from successful payments in your database for future refunds.
* **Use idempotency keys:** Use idempotency keys when processing refunds to avoid duplicate refunds in case of network issues.
* **Validate refund amounts:** Check the refund amount doesn't exceed original payment or remaining refundable balance.
* **Log all refunds:** Keep an audit trail of who initiated refunds, when, and why. This is critical for compliance.
* **Provide refund notes:** Include clear explanation in the `note_to_payer` field for customer clarity.
* **Handle partial refunds:** Track cumulative refunded amounts to prevent over-refunding.
* **Process refunds within 180 days:** Process refunds within 180 days of the original capture date. Your customer's bank may have shorter windows. After extended periods, manual intervention through PayPal support may be required.
* **Implement approval workflows:** Processed refunds cannot be cancelled. Build approval workflows for refunds over a certain threshold.
* **Have backup manual refund process:** Have a manual refund process as backup. Log failed attempts and escalate to PayPal support with the error details.

## Important details

* **Find capture IDs:** The capture ID is returned as `capture.result.id` when you capture a payment. Store this value in your database immediately. You'll need it for any future refunds on that transaction.
* **Refund processing time:** In sandbox mode, refunds complete instantly. In production, customers see refunds in their account within 3-5 business days, though timing varies by payment method.
* **Webhook notifications:** Set up webhooks to receive `PAYMENT.CAPTURE.REFUNDED` events for real-time status updates. Always verify webhook signatures for security.
* **No refunds to different payment methods:** Refunds always go back to the customer's original payment method.
* **No currency conversion:** Always refund in the same currency as the original payment. PayPal handles any exchange rate adjustments automatically.

## Test your integration

Make sure you have [sandbox account credentials for both buyer and seller roles](/developer/how-to/api/get-started#3-get-sandbox-account-credentials). Complete a test payment to get a valid capture ID.

### Standard testing

| Test scenario                   | Setup            | Expected result                    |
| :------------------------------ | :--------------- | :--------------------------------- |
| Full refund success             | Default settings | Entire payment amount refunded.    |
| Partial refund success          | Default settings | Specified amount refunded.         |
| Multiple partial refund success | Default settings | Each refunds succeeds until limit. |
| Invalid capture ID              | Fake IDL XXX123  | 404 error: capture not found.      |
| Refund after 3 days             | Wait 3 days      | Success if within 180 days         |

### Negative testing

For negative testing:

1. Make sure to enable negative testing in your sandbox business account as described in the [quick start prerequisites](/payments/methods/paypal/integrate#prerequisites).
2. In the `.env` file, set `ENABLE_NEGATIVE_TESTING=true` and set `NEGATIVE_TEST_TYPE` to one of the error codes in the table.
3. Restart the server after changing the `.env` file: `node server.js`.

| Test scenario          | Error code                          | Expected result                       |
| :--------------------- | :---------------------------------- | :------------------------------------ |
| Exceed original amount | `REFUND_AMOUNT_EXCEEDED`            | Error: refund amount exceeds capture. |
| Already fully refunded | `CAPTURE_FULLY_REFUNDED`            | Error: already fully refunded.        |
| Refund after 180 days  | `REFUND_NOT_ALLOWED_AFTER_180_DAYS` | Error: refund period expired.         |
| Permission denied      | `PERMISSION_DENIED`                 | 403 error: no refund permission.      |
| Internal server error  | `INTERNAL_SERVER_ERROR`             | Error: 500 error occurred at refund.  |

## Go-live checklist

* Test full and partial refunds in sandbox.
* Implement refund approval workflow.
* Set up refund logging and audit trail.
* Add authentication to refund endpoints.
* Configure refund permission roles.
* Set up webhook listeners for refund events.
* Test with real \$1 payment and refund it.

## Post-launch monitoring

These values are suggested monitoring thresholds for your integration, not performance guarantees from PayPal.

| Metric                  | Target      | Action if below target                         |
| :---------------------- | :---------- | :--------------------------------------------- |
| Refund success rate     | 98%         | Check API errors and validate capture IDs.     |
| Refund processing time  | \<5 seconds | Optimize database queries.                     |
| Failed refund rate      | \<2%        | Review error logs, check amounts.              |
| Refund-to-payment ratio | \<5%        | Analyze if high - may indicate quality issues. |
| API response time       | \<2 seconds | Check PayPal API status.                       |


# Save PayPal information for future payments
Source: https://docs.paypal.ai/payments/methods/paypal/save



Charge a customer's saved PayPal account without requiring the customer to approve each payment. Common scenarios include:

* Subscription renewals
* On-demand services billed after usage
* Automatic bill payments
* One-click purchases for returning customers

Use PayPal's vault parameter to save the customer's PayPal information. The customer approves once. Then you can charge their PayPal account without them present.

<Note>
  This guide covers the basics of saving a PayPal payment method. For more details, such as customer management, payment tokens, and advanced vault options, review the [Save payment methods documentation](https://developer.paypal.com/docs/checkout/save-payment-methods/).
</Note>

## Prerequisites

* Complete [the quick start PayPal integration](/payments/methods/paypal/integrate).
* Have a secure database to store payment tokens.
* Build a mechanism to collect customer consent.

## Integrate server side

<Info>
  Endpoint: [`POST /v2/checkout/orders`](/reference/api/rest/orders/)
</Info>

<CodeGroup>
  ```bash cURL expandable lines theme={null}
  # Step 1: Create order with vault=true
  curl -X POST https://api-m.paypal.com/v2/checkout/orders \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -d '{
      "intent": "CAPTURE",
      "payment_source": {
        "paypal": {
          "experience_context": {
            "return_url": "https://example.com/return",
            "cancel_url": "https://example.com/cancel"
          },
          "attributes": {
            "vault": {
              "store_in_vault": "ON_SUCCESS",
              "usage_type": "MERCHANT",
              "customer_type": "CONSUMER"
            }
          }
        }
      },
      "purchase_units": [{
        "amount": {
          "currency_code": "USD",
          "value": "10.00"
        }
      }]
    }'

  # Step 2: After customer approval, capture the order
  curl -X POST https://api-m.paypal.com/v2/checkout/orders/{order_id}/capture \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ACCESS_TOKEN"

  # Extract payment token from response:
  # payment_source.paypal.attributes.vault.id

  # Step 3: Later, charge using saved token
  curl -X POST https://api-m.paypal.com/v2/checkout/orders \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -d '{
      "intent": "CAPTURE",
      "payment_source": {
        "paypal": {
          "vault_id": "PAYMENT_TOKEN_ID"
        }
      },
      "purchase_units": [{
        "amount": {
          "currency_code": "USD",
          "value": "29.99"
        }
      }]
    }'
  ```

  ```javascript Node.js expandable lines theme={null}
  const paypal = require('@paypal/checkout-server-sdk');

  // Step 1: Create order with vault=true
  async function createVaultOrder() {
    const request = new paypal.orders.OrdersCreateRequest();
    request.prefer("return=representation");
    request.requestBody({
      intent: 'CAPTURE',
      payment_source: {
        paypal: {
          experience_context: {
            return_url: 'https://example.com/return',
            cancel_url: 'https://example.com/cancel'
          },
          attributes: {
            vault: {
              store_in_vault: 'ON_SUCCESS',
              usage_type: 'MERCHANT',
              customer_type: 'CONSUMER'
            }
          }
        }
      },
      purchase_units: [{
        amount: {
          currency_code: 'USD',
          value: '10.00'
        }
      }]
    });

    const response = await client.execute(request);
    return response.result.id;
  }

  // Step 2: After capture, extract payment token
  async function captureAndSaveToken(orderID) {
    const request = new paypal.orders.OrdersCaptureRequest(orderID);
    request.prefer("return=representation");

    const capture = await client.execute(request);
    const paymentToken = capture.result.payment_source.paypal.attributes.vault.id;

    // Save paymentToken to your database
    await saveToDatabase({ paymentToken, customerId });

    return paymentToken;
  }

  // Step 3: Later, charge using saved token
  async function chargeWithToken(paymentToken) {
    const request = new paypal.orders.OrdersCreateRequest();
    request.prefer("return=representation");
    request.requestBody({
      intent: 'CAPTURE',
      payment_source: {
        paypal: {
          vault_id: paymentToken
        }
      },
      purchase_units: [{
        amount: {
          currency_code: 'USD',
          value: '29.99'
        }
      }]
    });

    const response = await client.execute(request);
    return response.result;
  }
  ```

  ```python Python expandable lines theme={null}
  from paypalcheckoutsdk.orders import OrdersCreateRequest, OrdersCaptureRequest

  # Step 1: Create order with vault=true
  def create_vault_order():
      request = OrdersCreateRequest()
      request.prefer('return=representation')
      request.request_body({
          'intent': 'CAPTURE',
          'payment_source': {
              'paypal': {
                  'experience_context': {
                      'return_url': 'https://example.com/return',
                      'cancel_url': 'https://example.com/cancel'
                  },
                  'attributes': {
                      'vault': {
                          'store_in_vault': 'ON_SUCCESS',
                          'usage_type': 'MERCHANT',
                          'customer_type': 'CONSUMER'
                      }
                  }
              }
          },
          'purchase_units': [{
              'amount': {
                  'currency_code': 'USD',
                  'value': '10.00'
              }
          }]
      })

      response = client.execute(request)
      return response.result.id

  # Step 2: After capture, extract payment token
  def capture_and_save_token(order_id):
      request = OrdersCaptureRequest(order_id)
      request.prefer('return=representation')

      capture = client.execute(request)
      payment_token = capture.result.payment_source.paypal.attributes.vault.id

      # Save payment_token to your database
      save_to_database(payment_token, customer_id)

      return payment_token

  # Step 3: Later, charge using saved token
  def charge_with_token(payment_token):
      request = OrdersCreateRequest()
      request.prefer('return=representation')
      request.request_body({
          'intent': 'CAPTURE',
          'payment_source': {
              'paypal': {
                  'vault_id': payment_token
              }
          },
          'purchase_units': [{
              'amount': {
                  'currency_code': 'USD',
                  'value': '29.99'
              }
          }]
      })

      response = client.execute(request)
      return response.result
  ```

  ```java Java expandable lines theme={null}
  import com.paypal.orders.*;
  import com.paypal.core.PayPalHttpClient;
  import com.paypal.http.HttpResponse;

  // Step 1: Create order with vault=true
  public String createVaultOrder() throws IOException {
      OrderRequest orderRequest = new OrderRequest();
      orderRequest.checkoutPaymentIntent("CAPTURE");

      PaymentSourceDefinition paymentSource = new PaymentSourceDefinition();
      PayPalWallet paypalWallet = new PayPalWallet();

      ExperienceContext experienceContext = new ExperienceContext();
      experienceContext.returnUrl("https://example.com/return");
      experienceContext.cancelUrl("https://example.com/cancel");
      paypalWallet.experienceContext(experienceContext);

      VaultAttributes vaultAttributes = new VaultAttributes();
      vaultAttributes.storeInVault("ON_SUCCESS");
      vaultAttributes.usageType("MERCHANT");
      vaultAttributes.customerType("CONSUMER");

      PayPalAttributes paypalAttributes = new PayPalAttributes();
      paypalAttributes.vault(vaultAttributes);
      paypalWallet.attributes(paypalAttributes);

      paymentSource.paypal(paypalWallet);
      orderRequest.paymentSource(paymentSource);

      PurchaseUnitRequest purchaseUnit = new PurchaseUnitRequest();
      AmountWithBreakdown amount = new AmountWithBreakdown();
      amount.currencyCode("USD");
      amount.value("10.00");
      purchaseUnit.amountWithBreakdown(amount);

      orderRequest.purchaseUnits(Arrays.asList(purchaseUnit));

      OrdersCreateRequest request = new OrdersCreateRequest();
      request.prefer("return=representation");
      request.requestBody(orderRequest);

      HttpResponse<Order> response = client.execute(request);
      return response.result().id();
  }

  // Step 2: After capture, extract payment token
  public String captureAndSaveToken(String orderId) throws IOException {
      OrdersCaptureRequest request = new OrdersCaptureRequest(orderId);
      request.prefer("return=representation");

      HttpResponse<Order> capture = client.execute(request);
      String paymentToken = capture.result()
          .paymentSource()
          .paypal()
          .attributes()
          .vault()
          .id();

      // Save paymentToken to your database
      saveToDatabase(paymentToken, customerId);

      return paymentToken;
  }

  // Step 3: Later, charge using saved token
  public Order chargeWithToken(String paymentToken) throws IOException {
      OrderRequest orderRequest = new OrderRequest();
      orderRequest.checkoutPaymentIntent("CAPTURE");

      PaymentSourceDefinition paymentSource = new PaymentSourceDefinition();
      PayPalWallet paypalWallet = new PayPalWallet();
      paypalWallet.vaultId(paymentToken);
      paymentSource.paypal(paypalWallet);
      orderRequest.paymentSource(paymentSource);

      PurchaseUnitRequest purchaseUnit = new PurchaseUnitRequest();
      AmountWithBreakdown amount = new AmountWithBreakdown();
      amount.currencyCode("USD");
      amount.value("29.99");
      purchaseUnit.amountWithBreakdown(amount);

      orderRequest.purchaseUnits(Arrays.asList(purchaseUnit));

      OrdersCreateRequest request = new OrdersCreateRequest();
      request.prefer("return=representation");
      request.requestBody(orderRequest);

      HttpResponse<Order> response = client.execute(request);
      return response.result();
  }
  ```

  ```php PHP expandable lines theme={null}
  <?php
  use PayPalCheckoutSdk\Orders\OrdersCreateRequest;
  use PayPalCheckoutSdk\Orders\OrdersCaptureRequest;

  // Step 1: Create order with vault=true
  function createVaultOrder() {
      $request = new OrdersCreateRequest();
      $request->prefer('return=representation');
      $request->body = [
          'intent' => 'CAPTURE',
          'payment_source' => [
              'paypal' => [
                  'experience_context' => [
                      'return_url' => 'https://example.com/return',
                      'cancel_url' => 'https://example.com/cancel'
                  ],
                  'attributes' => [
                      'vault' => [
                          'store_in_vault' => 'ON_SUCCESS',
                          'usage_type' => 'MERCHANT',
                          'customer_type' => 'CONSUMER'
                      ]
                  ]
              ]
          ],
          'purchase_units' => [[
              'amount' => [
                  'currency_code' => 'USD',
                  'value' => '10.00'
              ]
          ]]
      ];

      $response = $client->execute($request);
      return $response->result->id;
  }

  // Step 2: After capture, extract payment token
  function captureAndSaveToken($orderId) {
      global $client;

      $request = new OrdersCaptureRequest($orderId);
      $request->prefer('return=representation');

      $capture = $client->execute($request);
      $paymentToken = $capture->result->payment_source->paypal->attributes->vault->id;

      // Save paymentToken to your database
      saveToDatabase($paymentToken, $customerId);

      return $paymentToken;
  }

  // Step 3: Later, charge using saved token
  function chargeWithToken($paymentToken) {
      global $client;

      $request = new OrdersCreateRequest();
      $request->prefer('return=representation');
      $request->body = [
          'intent' => 'CAPTURE',
          'payment_source' => [
              'paypal' => [
                  'vault_id' => $paymentToken
              ]
          ],
          'purchase_units' => [[
              'amount' => [
                  'currency_code' => 'USD',
                  'value' => '29.99'
              ]
          ]]
      ];

      $response = $client->execute($request);
      return $response->result;
  }
  ?>
  ```

  ```ruby Ruby expandable lines theme={null}
  require 'paypal-checkout-sdk'

  # Step 1: Create order with vault=true
  def create_vault_order
    request = PayPalCheckoutSdk::Orders::OrdersCreateRequest.new
    request.prefer('return=representation')
    request.request_body({
      intent: 'CAPTURE',
      payment_source: {
        paypal: {
          experience_context: {
            return_url: 'https://example.com/return',
            cancel_url: 'https://example.com/cancel'
          },
          attributes: {
            vault: {
              store_in_vault: 'ON_SUCCESS',
              usage_type: 'MERCHANT',
              customer_type: 'CONSUMER'
            }
          }
        }
      },
      purchase_units: [{
        amount: {
          currency_code: 'USD',
          value: '10.00'
        }
      }]
    })

    response = client.execute(request)
    response.result.id
  end

  # Step 2: After capture, extract payment token
  def capture_and_save_token(order_id)
    request = PayPalCheckoutSdk::Orders::OrdersCaptureRequest.new(order_id)
    request.prefer('return=representation')

    capture = client.execute(request)
    payment_token = capture.result.payment_source.paypal.attributes.vault.id

    # Save payment_token to your database
    save_to_database(payment_token, customer_id)

    payment_token
  end

  # Step 3: Later, charge using saved token
  def charge_with_token(payment_token)
    request = PayPalCheckoutSdk::Orders::OrdersCreateRequest.new
    request.prefer('return=representation')
    request.request_body({
      intent: 'CAPTURE',
      payment_source: {
        paypal: {
          vault_id: payment_token
        }
      },
      purchase_units: [{
        amount: {
          currency_code: 'USD',
          value: '29.99'
        }
      }]
    })

    response = client.execute(request)
    response.result
  end
  ```
</CodeGroup>


# Troubleshoot
Source: https://docs.paypal.ai/payments/methods/paypal/troubleshoot



Find solutions to common PayPal integration issues.

## The PayPal button does not appear

* Check that the client ID in your HTML matches the client ID in the .env file.
* Make sure to use sandbox credentials for development and production credentials for live.

## 404 Page Not Found error

Make sure `index.html` is in the `public` folder. Express serves static files from there.

## Invalid Client error

The client ID and secret don't match, or there's a mix of sandbox and production credentials. PayPal provides separate credentials for sandbox and production. Make sure your client ID and secret are both from the same environment.

## Multipage and modular app issues

If your app uses PayPal buttons across multiple pages or a modular JavaScript architecture, errors typically stem from one root cause: the SDK instance isn't accessible where your code expects it. The following errors are related symptoms of the same scoping problem.

### `window.paypalSdkInstance` is undefined

This browser console error means the SDK instance was created but never exposed outside of `onLoad()`.

In the file where you define `onLoad()` (usually `paypal-init.js` or `index.html`), add the following two lines after creating the instance:

```js lines expandable theme={null}
async function onLoad() {
  try {
    const sdkInstance = await window.paypal.createInstance({...});

    // ⚠️ ADD THIS LINE
    window.paypalSdkInstance = sdkInstance;

    // ⚠️ ALSO ADD THIS (required for the waiting pattern)
    window.dispatchEvent(new CustomEvent('paypalReady', {
      detail: { instance: sdkInstance }
    }));
  }
}
```

To verify the fix, open the browser console and run:

```js theme={null}
window.paypalSdkInstance
```

You should see an object with methods such as `createPayPalOneTimePaymentSession`.

### PayPal button appears on one page but not others

These symptoms indicate the SDK instance isn't accessible to pages other than the one where it was initialized:

* Buttons work on your main page but not on product, cart, or checkout pages
* Console shows errors about an undefined SDK instance

To fix this, include the SDK script and initialization on every page that has PayPal buttons. The cleanest way to do this is through a shared layout or template:

```html lines theme={null}
<!-- Include in your shared layout, or add to EVERY page with PayPal buttons -->
<script async
        src="https://www.sandbox.paypal.com/web-sdk/v6/core"
        onload='onLoad()'>
</script>
<script src="/js/paypal-init.js"></script>
```

For Single-Page Applications (SPAs), set `window.paypalSdkInstance` during initialization and ensure it persists across route changes.

A typical file structure for multipage apps looks like this:

```text theme={null}
your-app/
├── public/
│   ├── index.html              # Loads SDK script
│   ├── js/
│   │   ├── paypal-init.js      # Contains onLoad() and initPayPalButton()
│   │   ├── products.js         # Product page buttons
│   │   ├── cart.js             # Cart page button
│   │   └── checkout.js         # Checkout page button
├── server.js
└── .env
```

### SDK initialization timing errors

These symptoms indicate your code is trying to access `window.paypalSdkInstance` before `onLoad()` has finished creating it:

* Buttons appear intermittently
* Buttons work sometimes but fail on page load
* Errors occur randomly

The problem is a race condition between when the SDK loads and when your page scripts run:

```text theme={null}
Timeline 1 (Success):  SDK loads → onLoad() → createInstance() → Your code runs ✓
Timeline 2 (Failure):  Your code runs → Error! → SDK loads (too late) ✗
```

In any file other than your main initialization file, use this waiting pattern instead of accessing `window.paypalSdkInstance` directly:

```js lines expandable theme={null}
function initButtonWhenReady(containerId) {
  if (window.paypalSdkInstance) {
    // SDK already loaded, initialize immediately
    initPayPalButton(containerId);
  } else {
    // SDK still loading, wait for it
    window.addEventListener('paypalReady', () => {
      initPayPalButton(containerId);
    }, { once: true });
  }
}

document.addEventListener('DOMContentLoaded', () => {
  initButtonWhenReady('#my-button');
});
```

This pattern handles both timelines:

* If the SDK is already loaded, it runs immediately.
* If the SDK is still loading, it waits for the `paypalReady` event dispatched in `onLoad()`.

### Debugging checklist

On the page where buttons aren't appearing, open the browser console and run:

```js theme={null}
console.log('SDK loaded:', !!window.paypal);
console.log('Instance ready:', !!window.paypalSdkInstance);
```

If either value is `false`:

* `window.paypal` is `false`: the SDK script isn't loading on this page.
* `window.paypalSdkInstance` is `false`: `onLoad()` isn't running, or `window.paypalSdkInstance = sdkInstance` is missing.


# Void an authorized payment
Source: https://docs.paypal.ai/payments/methods/paypal/void-an-authorization



Cancel an authorized payment before capturing it to release the customer's held funds. Voiding an authorized payment saves processing fees compared to refunding a captured payment. Common scenarios include:

* Customer cancels an order before shipment
* Item is out of stock after authorization
* Order fails fraud verification
* Customer requests cancellation during fulfillment

Add the void endpoint to cancel authorizations. This integration uses the Payments API v2 and requires an authorized payment that hasn't been captured yet.

[What's the difference between authorization and capture?](/payments/methods/paypal/overview#authorization-vs-capture)

## Prerequisites

* Complete [the quick start PayPal integration](/payments/methods/paypal/integrate).
* Implement an authorization and capture flow that doesn't use immediate capture.
* Have an authorization ID from an order creation. Store authorization IDs in your database when creating orders. You'll need them to void the authorization.
* Optional for production:
  * Automated void triggers for inventory and fraud checks
  * Customer notifications on voided payments
  * Void reason tracking for analytics

## Integrate server side

Add the following to your existing server file from the quick start integration.

<CodeGroup>
  ```bash cURL lines theme={null}
  # Void an authorization
  curl -X POST https://api-m.sandbox.paypal.com/v2/payments/authorizations/AUTHORIZATION_ID/void \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -d '{}'
  ```

  ```javascript Node.js expandable lines theme={null}
  // Add this endpoint to your existing server.js from the quick start integration
  // The PayPal client and addNegativeTesting helper are already configured

  // Void an authorization (cancel before capture)
  app.post('/api/authorizations/:authID/void', async (req, res) => {
    const request = new paypal.payments.AuthorizationsVoidRequest(req.params.authID);

    // Apply negative testing if enabled (reuse helper from base integration)
    addNegativeTesting(request);

    try {
      const voidResult = await client.execute(request);
      res.json({
        id: voidResult.result.id,
        status: voidResult.result.status
      });
    } catch (err) {
      // Handle specific void errors
      if (err.statusCode === 422) {
        const errorDetail = err.details?.[0];
        if (errorDetail?.issue === 'AUTHORIZATION_ALREADY_CAPTURED') {
          res.status(400).json({
            error: 'Cannot void - already captured. Use refund instead.',
            captureId: errorDetail.description
          });
        } else if (errorDetail?.issue === 'AUTHORIZATION_VOIDED') {
          res.status(400).json({ error: 'Authorization already voided' });
        } else {
          res.status(400).json({ error: 'Invalid authorization state' });
        }
      } else {
        res.status(500).json({ error: err.message });
      }
    }
  });
  ```

  ```python Python expandable lines theme={null}
  from paypalrestsdk import Api, Authorization
  import os

  # Configure PayPal SDK
  api = Api({
    'mode': 'sandbox',
    'client_id': os.environ['PAYPAL_CLIENT_ID'],
    'client_secret': os.environ['PAYPAL_CLIENT_SECRET']
  })

  # Void an authorization
  @app.route('/api/authorizations/<auth_id>/void', methods=['POST'])
  def void_authorization(auth_id):
    try:
      authorization = Authorization.find(auth_id)

      if authorization.void():
        return jsonify({
          "id": authorization.id,
          "status": authorization.state
        })
      else:
        # Handle errors
        error = authorization.error
        if error.get('name') == 'AUTHORIZATION_ALREADY_CAPTURED':
          return jsonify({
            "error": "Cannot void - already captured. Use refund instead."
          }), 400
        elif error.get('name') == 'AUTHORIZATION_VOIDED':
          return jsonify({
            "error": "Authorization already voided"
          }), 400
        else:
          return jsonify({
            "error": "Invalid authorization state"
          }), 400

    except Exception as e:
      return jsonify({"error": str(e)}), 500
  ```

  ```java Java theme={null}
  import com.paypal.core.PayPalEnvironment;
  import com.paypal.core.PayPalHttpClient;
  import com.paypal.payments.AuthorizationsVoidRequest;
  import com.paypal.payments.Authorization;

  HttpClient httpClient = new PayPalHttpClient(
    new SandboxEnvironment(
      System.getenv("PAYPAL_CLIENT_ID"),
      System.getenv("PAYPAL_CLIENT_SECRET")
    )
  );

  // Void an authorization
  @PostMapping("/api/authorizations/{authId}/void")
  public ResponseEntity<?> voidAuthorization(@PathVariable String authId) {
    try {
      AuthorizationsVoidRequest request = new AuthorizationsVoidRequest(authId);

      HttpResponse<Authorization> response = httpClient.execute(request);
      Authorization authorization = response.result();

      return ResponseEntity.ok(Map.of(
        "id", authorization.id(),
        "status", authorization.status()
      ));

    } catch (HttpClientException e) {
      if (e.statusCode() == 422) {
        String issue = extractIssue(e);
        if ("AUTHORIZATION_ALREADY_CAPTURED".equals(issue)) {
          return ResponseEntity.badRequest().body(
            Map.of("error", "Cannot void - already captured. Use refund instead.")
          );
        } else if ("AUTHORIZATION_VOIDED".equals(issue)) {
          return ResponseEntity.badRequest().body(
            Map.of("error", "Authorization already voided")
          );
        } else {
          return ResponseEntity.badRequest().body(
            Map.of("error", "Invalid authorization state")
          );
        }
      }
      return ResponseEntity.status(500).body(
        Map.of("error", e.getMessage())
      );
    }
  }
  ```

  ```php PHP expandable lines theme={null}
  <?php
  use PayPalCheckoutSdk\Core\SandboxEnvironment;
  use PayPalCheckoutSdk\Core\PayPalHttpClient;
  use PayPalCheckoutSdk\Payments\AuthorizationsVoidRequest;

  $environment = new SandboxEnvironment(
    getenv('PAYPAL_CLIENT_ID'),
    getenv('PAYPAL_CLIENT_SECRET')
  );
  $client = new PayPalHttpClient($environment);

  // Void an authorization
  $app->post('/api/authorizations/{authID}/void', function ($request, $response, $args) use ($client) {
    $authID = $args['authID'];

    $voidRequest = new AuthorizationsVoidRequest($authID);

    try {
      $voidResponse = $client->execute($voidRequest);
      $authorization = $voidResponse->result;

      $response->getBody()->write(json_encode([
        "id" => $authorization->id,
        "status" => $authorization->status
      ]));
      return $response->withHeader('Content-Type', 'application/json');

    } catch (HttpException $e) {
      $statusCode = $e->statusCode;
      $errorData = json_decode($e->getMessage(), true);

      if ($statusCode === 422) {
        $issue = $errorData['details'][0]['issue'] ?? '';
        if ($issue === 'AUTHORIZATION_ALREADY_CAPTURED') {
          $response->getBody()->write(json_encode([
            "error" => "Cannot void - already captured. Use refund instead."
          ]));
          return $response->withStatus(400)->withHeader('Content-Type', 'application/json');
        } else if ($issue === 'AUTHORIZATION_VOIDED') {
          $response->getBody()->write(json_encode([
            "error" => "Authorization already voided"
          ]));
          return $response->withStatus(400)->withHeader('Content-Type', 'application/json');
        } else {
          $response->getBody()->write(json_encode([
            "error" => "Invalid authorization state"
          ]));
          return $response->withStatus(400)->withHeader('Content-Type', 'application/json');
        }
      }

      $response->getBody()->write(json_encode([
        "error" => $e->getMessage()
      ]));
      return $response->withStatus(500)->withHeader('Content-Type', 'application/json');
    }
  });
  ```

  ```ruby Ruby expandable lines theme={null}
  require 'paypal-sdk'

  # Configure PayPal SDK
  PayPal::SDK.configure(
    :mode => "sandbox",
    :app_id => ENV['PAYPAL_APP_ID'],
    :client_id => ENV['PAYPAL_CLIENT_ID'],
    :client_secret => ENV['PAYPAL_CLIENT_SECRET']
  )

  # Void an authorization
  post '/api/authorizations/:auth_id/void' do
    auth_id = params['auth_id']

    begin
      authorization = PayPal::SDK::PaymentsApi::Authorization.find(auth_id)

      if authorization.void
        content_type :json
        {
          id: authorization.id,
          status: authorization.status
        }.to_json
      else
        error = authorization.error
        if error['name'] == 'AUTHORIZATION_ALREADY_CAPTURED'
          status 400
          { error: 'Cannot void - already captured. Use refund instead.' }.to_json
        elsif error['name'] == 'AUTHORIZATION_VOIDED'
          status 400
          { error: 'Authorization already voided' }.to_json
        else
          status 400
          { error: 'Invalid authorization state' }.to_json
        end
      end

    rescue => e
      status 500
      { error: e.message }.to_json
    end
  end
  ```
</CodeGroup>

## Test endpoint

<Info>
  Endpoint: [`/v2/payments/authorizations/{authorization_id}/void`](/reference/api/rest/authorizations/void-authorized-payment)
</Info>

<CodeGroup>
  ```bash cURL expandable lines theme={null}
  # Test voiding an authorization (replace with actual authorization ID)
  curl -X POST http://localhost:3000/api/authorizations/8AA831015G517922L/void \
    -H "Content-Type: application/json"

  # Expected success response:
  # {"id":"8AA831015G517922L","status":"VOIDED"}

  # Test voiding already captured authorization (should fail)
  curl -X POST http://localhost:3000/api/authorizations/CAPTURED_AUTH_ID/void \
    -H "Content-Type: application/json"

  # Expected error response:
  # {"error":"Cannot void - already captured. Use refund instead."}
  ```

  ```javascript Node.js expandable lines theme={null}
  // Test voiding an authorization
  const voidResponse = await fetch('http://localhost:3000/api/authorizations/8AA831015G517922L/void', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' }
  });
  const voidResult = await voidResponse.json();
  console.log('Void result:', voidResult);
  // Expected: {"id":"8AA831015G517922L","status":"VOIDED"}

  // Test voiding already captured authorization (should fail)
  const capturedVoidResponse = await fetch('http://localhost:3000/api/authorizations/CAPTURED_AUTH_ID/void', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' }
  });
  const capturedVoidResult = await capturedVoidResponse.json();
  console.log('Error result:', capturedVoidResult);
  // Expected: {"error":"Cannot void - already captured. Use refund instead."}
  ```

  ```python Python expandable lines theme={null}
  import requests

  # Test voiding an authorization
  void_response = requests.post(
    'http://localhost:3000/api/authorizations/8AA831015G517922L/void',
    headers={'Content-Type': 'application/json'}
  )
  print('Void result:', void_response.json())
  # Expected: {"id":"8AA831015G517922L","status":"VOIDED"}

  # Test voiding already captured authorization (should fail)
  captured_void_response = requests.post(
    'http://localhost:3000/api/authorizations/CAPTURED_AUTH_ID/void',
    headers={'Content-Type': 'application/json'}
  )
  print('Error result:', captured_void_response.json())
  # Expected: {"error":"Cannot void - already captured. Use refund instead."}
  ```

  ```java Java lines expandable theme={null}
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.net.URI;

  HttpClient client = HttpClient.newHttpClient();

  // Test voiding an authorization
  HttpRequest voidRequest = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:3000/api/authorizations/8AA831015G517922L/void"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.noBody())
    .build();

  HttpResponse<String> voidResponse = client.send(
    voidRequest,
    HttpResponse.BodyHandlers.ofString()
  );
  System.out.println("Void result: " + voidResponse.body());
  // Expected: {"id":"8AA831015G517922L","status":"VOIDED"}

  // Test voiding already captured authorization (should fail)
  HttpRequest capturedVoidRequest = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:3000/api/authorizations/CAPTURED_AUTH_ID/void"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.noBody())
    .build();

  HttpResponse<String> capturedVoidResponse = client.send(
    capturedVoidRequest,
    HttpResponse.BodyHandlers.ofString()
  );
  System.out.println("Error result: " + capturedVoidResponse.body());
  // Expected: {"error":"Cannot void - already captured. Use refund instead."}
  ```

  ```php PHP lines expandable theme={null}
  <?php
  // Test voiding an authorization
  $voidResponse = file_get_contents(
    'http://localhost:3000/api/authorizations/8AA831015G517922L/void',
    false,
    stream_context_create([
      'http' => [
        'method' => 'POST',
        'header' => 'Content-Type: application/json'
      ]
    ])
  );
  echo "Void result: " . $voidResponse . "\n";
  // Expected: {"id":"8AA831015G517922L","status":"VOIDED"}

  // Test voiding already captured authorization (should fail)
  $capturedVoidResponse = file_get_contents(
    'http://localhost:3000/api/authorizations/CAPTURED_AUTH_ID/void',
    false,
    stream_context_create([
      'http' => [
        'method' => 'POST',
        'header' => 'Content-Type: application/json'
      ]
    ])
  );
  echo "Error result: " . $capturedVoidResponse . "\n";
  // Expected: {"error":"Cannot void - already captured. Use refund instead."}
  ```

  ```ruby Ruby lines expandable theme={null}
  require 'net/http'
  require 'json'

  # Test voiding an authorization
  uri = URI('http://localhost:3000/api/authorizations/8AA831015G517922L/void')
  void_request = Net::HTTP::Post.new(uri)
  void_request['Content-Type'] = 'application/json'

  void_response = Net::HTTP.start(uri.hostname, uri.port) do |http|
    http.request(void_request)
  end
  puts "Void result: #{void_response.body}"
  # Expected: {"id":"8AA831015G517922L","status":"VOIDED"}

  # Test voiding already captured authorization (should fail)
  captured_uri = URI('http://localhost:3000/api/authorizations/CAPTURED_AUTH_ID/void')
  captured_void_request = Net::HTTP::Post.new(captured_uri)
  captured_void_request['Content-Type'] = 'application/json'

  captured_void_response = Net::HTTP.start(captured_uri.hostname, captured_uri.port) do |http|
    http.request(captured_void_request)
  end
  puts "Error result: #{captured_void_response.body}"
  # Expected: {"error":"Cannot void - already captured. Use refund instead."}
  ```
</CodeGroup>

## Best practices

* **Void promptly:** Cancel authorizations immediately when an order won't be fulfilled to release customer funds. Don't let an authorization expire.
* **Void before capture:** Always void instead of refund when possible. Voiding can save up to 3% in processing fees.
* **Automate cancellations:** Trigger voids automatically for out-of-stock scenarios or fraud detection.
* **Handle timing:** Authorizations expire after 3 days (standard) or 29 days (honor period).

## Important details

* **Void vs. refund:** Void cancels an authorization before capture. Refund returns money after a payment has been captured. Voiding saves processing fees.
* **Finding authorization IDs:** You need the authorization ID to void, not the order ID. The authorization ID is returned when you create an order with `AUTHORIZE` intent. Store this value in your database immediately.
* **All-or-nothing operation:** You cannot partially void an authorization. Voids cancel the entire authorized amount.
* **Voided authorizations cannot be captured:** Once voided, an authorization is permanently cancelled and cannot be captured. Attempting to capture will fail with an error.
* **Fund release time:** In sandbox mode, funds release immediately. In production, funds can take up to 24 hours depending on the customer's bank.

## Test your integration

* Create test authorizations with `AUTHORIZE` intent.
* Test at different intervals: immediately after authorization, after 1 day, and after 3 days.
* Verify funds are released in the sandbox buyer account after voiding.

### Standard testing

| Test scenario            | Setup                          | Expected result                 |
| :----------------------- | :----------------------------- | :------------------------------ |
| Void fresh authorization | Default settings               | Status: `VOIDED` returned       |
| Void after capture       | Capture first                  | Error: Already captured         |
| Void already voided      | Void twice                     | Error: Already voided           |
| Void after 3 days        | Wait 3 days post-authorization | Success if honor period enabled |

### Negative testing

For negative testing:

1. Make sure to enable negative testing in your sandbox business account as described in the [quick start prerequisites](/payments/methods/paypal/integrate#prerequisites).
2. In the `.env` file, set `ENABLE_NEGATIVE_TESTING=true` and set `NEGATIVE_TEST_TYPE` to one of the error codes in the table.
3. Restart the server after changing the `.env` file: `node server.js`.

| Test scenario              | Error code              | Expected result                |
| :------------------------- | :---------------------- | :----------------------------- |
| Void expired authorization | `AUTHORIZATION_EXPIRED` | Error: Authorization expired   |
| Void not found             | `RESOURCE_NOT_FOUND`    | Error: Authorization not found |
| Permission denied          | `PERMISSION_DENIED`     | Error: not authorized to void  |
| Internal server error      | `INTERNAL_SERVER_ERROR` | 500 error returned             |

## Go-live checklist

* Test void flow in sandbox with real authorization IDs.
* Implement void reason tracking.
* Set up customer cancellation notifications.
* Train support team on void vs refund scenarios.
* Configure automatic void triggers, such as out of inventory or a fraudulent transaction.
* Monitor void success rates.
* Test with real \$1 authorization and void it.

## Post-launch monitoring

These values are suggested monitoring thresholds for your integration, not performance guarantees from PayPal.

| Metric               | Target      | Action if below target             |
| :------------------- | :---------- | :--------------------------------- |
| Void success rate    | 99%         | Check for expired authorizations.  |
| Time to void         | \<1 hour    | Automate cancellation workflow.    |
| Void vs refund ratio | 80% void    | Train team to void before capture. |
| Failed void rate     | \<1%        | Review error patterns.             |
| API response time    | \<2 seconds | Check PayPal API status.           |


# Integrate Venmo with PayPal's JavaScript SDK v6
Source: https://docs.paypal.ai/payments/methods/venmo/integrate



You can accept Venmo for secure payments from US customers with the JavaScript SDK v6. This guide shows you how to set up your environment, review eligibility requirements, add Venmo payments, and work with advanced features.

## Prerequisites

Before beginning your integration, meet these requirements:

* Create a [PayPal developer account](https://developer.paypal.com/dashboard/).
* Use a **PayPal business account** to accept Venmo payments
* Set up your sandbox credentials.

> **Note:** You'll use your sandbox credentials to create a `.env` file during the **Development setup**.

## Eligibility

* US-based merchants and US-based consumers only.
* Payment must be in USD.

## Development setup

Before continuing, complete the steps in the [JavaScript SDK v6 sample integration README](https://github.com/paypal-examples/v6-web-sdk-sample-integration).

Once setup is complete, verify the JavaScript SDK v6 examples are running at `http://localhost:8080`.

To view the Venmo one-time payment example, navigate to: `http://localhost:8080/client/components/venmoPayments/oneTimePayment/html/src/index.html`.

## Implementation steps

### Step 1: HTML structure setup

Create your HTML page and include the PayPal SDK script.

```html theme={null}
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>One-Time Payment - Venmo - PayPal JavaScript SDK</title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <style>
      .buttons-container {
        display: flex;
        flex-direction: column;
        gap: 12px;
      }
    </style>
  </head>
  <body>
    <h1>One-Time Payment Venmo Integration</h1>

    <div class="buttons-container">
      <!-- Venmo button is initially hidden until eligibility is confirmed -->
      <venmo-button id="venmo-button" type="pay" hidden></venmo-button>
    </div>
    
    <script src="app.js"></script>

    <!-- Load PayPal SDK -->
    <script
      async
      src="https://www.sandbox.paypal.com/web-sdk/v6/core"
      onload="onPayPalWebSdkLoaded()"
    ></script>
  </body>
</html>
```

### Step 2: Initialize PayPal SDK

Set up the PayPal SDK with the Venmo component after it loads.

```javascript theme={null}
async function onPayPalWebSdkLoaded() {
  try {
    // Create PayPal SDK instance with Venmo component
    const sdkInstance = await window.paypal.createInstance({
      clientId: "YOUR_CLIENT_ID",
      components: ["venmo-payments"],
      pageType: "checkout",
    });

    // Check payment method eligibility
    const paymentMethods = await sdkInstance.findEligibleMethods({
      currencyCode: "USD",
    });

    // Only setup Venmo button if eligible
    if (paymentMethods.isEligible("venmo")) {
      setupVenmoButton(sdkInstance);
    } else {
      console.log("Venmo is not eligible for this session");
    }
  } catch (error) {
    console.error("SDK initialization error:", error);
  }
}
```

### Step 3: Configure Venmo button

Create the Venmo payment session and set up the button.

```javascript theme={null}
async function setupVenmoButton(sdkInstance) {
  // Create Venmo payment session with callback options
  const venmoPaymentSession = sdkInstance.createVenmoOneTimePaymentSession(
    paymentSessionOptions,
  );
  
  // Get reference to the Venmo button element
  const venmoButton = document.querySelector("#venmo-button");
  
  // Show the button since Venmo is eligible
  venmoButton.removeAttribute("hidden");

  // Add click handler to start payment flow
  venmoButton.addEventListener("click", async () => {
    try {
      // Start the payment session
      await venmoPaymentSession.start(
        { 
          presentationMode: "auto" // Auto-detects best presentation mode
        },
        createOrder() // Create order and return order details
      );
    } catch (error) {
      console.error("Payment start error:", error);
      handlePaymentError(error);
    }
  });
}
```

### Step 4. Configure payment session callbacks

Define callback handlers for payment approval, cancellation, and error scenarios.

```javascript theme={null}
const paymentSessionOptions = {
  // Called when payment is approved by the user
  async onApprove(data) {
    console.log("Payment approved:", data);
    try {
      // Capture the order on your server
      const orderData = await captureOrder({
        orderId: data.orderId,
      });
      console.log("Payment captured successfully:", orderData);
      
      // Handle successful payment (e.g., redirect, show success message)
      handlePaymentSuccess(orderData);
    } catch (error) {
      console.error("Payment capture failed:", error);
      handlePaymentError(error);
    }
  },
  
  // Called when user cancels the payment
  onCancel(data) {
    console.log("Payment cancelled:", data);
    // Handle cancellation (e.g., show message, return to cart)
    handlePaymentCancellation();
  },
  
  // Called when an error occurs during payment
  onError(error) {
    console.error("Payment error:", error);
    // Handle error (e.g., show error message, retry option)
    handlePaymentError(error);
  },
};
```

### Step 5. Choose presentation mode

The presentation mode determines how the payment UI appears for the customer.

```javascript theme={null}
// Auto mode - automatically chooses the best presentation mode
await venmoPaymentSession.start(
  { presentationMode: "auto" },
  createOrder()
);
```

> **Note:** For Venmo, `"auto"` is the only supported presentation mode.

## API endpoints

The integration requires these server-side endpoints.

## Create order endpoint

```javascript theme={null}
// POST /paypal-api/checkout/orders/create-with-sample-data
async function createOrder() {
  const response = await fetch(
    "/paypal-api/checkout/orders/create-with-sample-data",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
    },
  );
  const { id } = await response.json();
  
  return { orderId: id };
}
```

## Capture order endpoint

```javascript theme={null}
// POST /paypal-api/checkout/orders/{orderId}/capture
async function captureOrder({ orderId }) {
  const response = await fetch(
    `/paypal-api/checkout/orders/${orderId}/capture`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
    },
  );
  const data = await response.json();
  return data;
}
```

## Key components

Integrate Venmo effectively by understanding the essential parts of the JavaScript SDK v6 workflow.

<table>
  <thead>
    <tr>
      <th>Key component</th>
      <th>Purpose</th>
      <th>Details</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>PayPal SDK instance</strong></td>
      <td>Main entry point for PayPal functionality</td>

      <td>
        <ul>
          <li>Includes <code>venmo-payments</code> component</li>
          <li>Authenticate with your client ID</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td><strong>Eligibility check</strong></td>
      <td>Determines if Venmo is available</td>

      <td>
        <ul>
          <li>Based on user location, device type, currency, and account status</li>
          <li>Always check before showing Venmo button</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td><strong>Payment session</strong></td>
      <td>Manages Venmo payment flow and callbacks</td>

      <td>
        <ul>
          <li>Handles approve, cancel, and error scenarios</li>
          <li>Created once and reused for multiple payment attempts</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td><strong>Presentation modes</strong></td>
      <td>Defines how Venmo is displayed</td>

      <td>
        <ul>
          <li><strong>Auto</strong> — Only available presentation mode for Venmo</li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

## Security considerations

* Never expose client secrets in frontend code.
* Process all payments through PayPal’s servers.
* Use HTTPS in production.

## Testing

* Run transactions across desktop and mobile devices.
* Verify eligibility logic and Venmo button rendering.
* Test payment approval, cancellation, and error handling.

## Resources

* [Pay with Venmo](https://developer.paypal.com/docs/checkout/pay-with-venmo/)
* [Pay with Venmo integration](https://developer.paypal.com/docs/checkout/pay-with-venmo/integrate/)
* [JavaScript SDK](https://developer.paypal.com/sdk/js/)
* [PayPal Developer Dashboard](https://developer.paypal.com/dashboard/)


# Payment Links and Buttons
Source: https://docs.paypal.ai/payments/pay-links-buttons



Use PayPal Payment Links and Buttons to accept payments without building your own payment flow. Create shareable payment links, add buy buttons to your website, or generate QR codes for in-person sales. Customers complete their purchase on a secure PayPal payment page, and funds are deposited into your PayPal business account.

Payment Links and Buttons support PayPal, Pay Later, Venmo, Apple Pay, and major debit and credit cards. Payments are available in more than 200 [countries and regions](https://docs.paypal.ai/reference/codes/country-codes), across multiple [languages](https://docs.paypal.ai/reference/codes/locale-codes), and in more than 23 [currencies](https://docs.paypal.ai/reference/codes/currency-codes). You can customize the payment page with product details and images, allow customers to set an amount when appropriate, and rely on PayPal to handle PCI compliance requirements.

## Choose a payment option

Each option supports different payment scenarios and integration approaches.

| **Options**              | **Best for**                                                                                  | Setup requirement                                                    | **Use case**                                                                                                                                   |
| :----------------------- | :-------------------------------------------------------------------------------------------- | :------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- |
| **Payment Link**         | Accepting payments by sharing a link on social media, email, or through messages              | No-code                                                              | Share a payment link with customers so they can complete payments online.​                                                                     |
| **Buy Button**           | Selling a specific product or service with a direct payment option on your website            | No-code<br /> Requires a website and basic knowledge of editing HTML | Copy the generated Buy Button code into your website so customers can proceed directly to payment for a specific item.​                        |
| **Shopping Cart Button** | Selling multiple products and allowing customers to purchase them together in one transaction | No-code<br /> Requires a website and basic knowledge of editing HTML | Copy the generated Add to Cart and View Cart button code into your website so customers can purchase multiple items in a single transaction.​​ |
| **QR Code**              | Accepting in-person or contactless payments without building a website                        | No-code                                                              | Generate QR codes that link to PayPal-hosted checkout for contactless payments.​                                                               |

To get started, [build now](https://www.paypal.com/signin?returnUri=https%3A%2F%2Fwww.paypal.com%2Fncp%2Flinks%2Fcreate) with Payment Links and Buttons.

## Choose between Invoicing and Payment Links

If you send bills or collect payments, compare Payment Links and Invoicing in the following table and choose the option that best fits your workflow.

|                                                                                                | Payment Links                                                             | Invoicing                                                                                 |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **Description**                                                                                | Use Payment Links to sell a product, service, or accept a donation or tip | Use Invoicing to collect one-time or recurring payments from a specific customer          |
| **Customer**                                                                                   | Anyone with the link                                                      | Specific individual or business                                                           |
| **Reusability**                                                                                | Reuse the same link multiple times                                        | One invoice per transaction                                                               |
| **Integration options**                                                                        | Business Dashboard or API                                                 | Business Dashboard or API                                                                 |
| **Sharing options**                                                                            | Share link through email, SMS, or social channels                         | Email invoice, share the hosted invoice link, or provide a QR code that opens the invoice |
| **Customization**                                                                              | Basic checkout customization is available                                 | Invoice branding and business details                                                     |
| **Payment methods**                                                                            | PayPal, Pay Later, Venmo, Apple Pay, and major debit and credit cards     | PayPal, Pay Later, Venmo, Debit or Credit Cards, Apple Pay, and Pay by Bank (ACH)         |
| **Recurring payments**                                                                         | One-time payments only                                                    | One-time invoices                                                                         |
| **Collection tools**                                                                           | Not supported                                                             | Invoice reminders and status tracking                                                     |
| **Customers can choose what to pay**                                                           | ✓                                                                         | ✕                                                                                         |
| **Hosted payment page**                                                                        | ✓                                                                         | ✓                                                                                         |
| **Partial payments**                                                                           | ✕                                                                         | ✓                                                                                         |
| **Discounts**                                                                                  | ✓                                                                         | ✓                                                                                         |
| **Taxes**                                                                                      | ✓                                                                         | ✓                                                                                         |
| **[PCI compliance handling](https://www.paypal.com/us/brc/article/pci-dss-compliance-basics)** | ✓                                                                         | ✓                                                                                         |

<Columns>
  <Card title="Choose your integration option" href="/payments/choose-integration-option">
    Compare dashboard and API options for creating and managing payment links so you can pick the right balance of control, effort, and automation for your setup.
  </Card>

  <Card title="Create a payment link" href="/payments/create-pay-link">
    Create payment links in your PayPal business account and use them in emails, social posts, or on your site without writing code.
  </Card>
</Columns>


# Use API to create payment links
Source: https://docs.paypal.ai/payments/pay-links-buttons-api



Create and manage reusable Payment Links through a REST API so your systems can generate, update, and delete payment links programmatically. Payment links collect payments by sharing a URL with customers. You can send a payment link directly through text or email and embed it on your website. The Payment Links and Buttons API currently supports payment links only and does not return button code.

This API is available in all countries where PayPal operates. See [Countries and Currencies](https://docs.paypal.ai/reference/codes/country-codes) for a list of supported currencies.

## Prerequisites

* Set up a [PayPal Business Account](https://www.paypal.com/business/open-business-account?_ga=2.49411041.673139926.1760916697-1259758161.1760473483).
* Navigate to the **Apps and Credentials** section on the [PayPal Developer Dashboard](https://www.paypal.com/signin?returnUri=https%3A%2F%2Fdeveloper.paypal.com%2Fdashboard%2F\&intent=developer\&ctxId=ul1761161497704) and select **Create App** or select an existing one.
* Confirm **Payment Links & Buttons** is enabled for the selected credentials.
* Implement OAuth 2.0 to obtain an access token for each API call.
* Use `https://api-m.sandbox.paypal.com` for sandbox or `https://api.paypal.com` for production. Payloads and steps are the same for both environments.

## Quick start

Follow these steps to create your first payment link using the sandbox environment.

### 1. Get an access token

Send a `POST` request to get an OAuth 2.0 bearer token.

```bash theme={null}
curl -v -X POST 'https://api-m.sandbox.paypal.com/v1/oauth2/token' \
  -u '<CLIENT_ID>:<CLIENT_SECRET>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials'
```

The response includes an `access_token` that you pass in the `Authorization` header for subsequent calls.

### 2. Create a payment link

Send a `POST` request with the minimal required product details.

```bash [expandable] theme={null}
curl -v -X POST 'https://api-m.sandbox.paypal.com/v1/checkout/payment-resources' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'PayPal-Request-Id: PAYPAL_REQUEST_ID' \
  -d '{
    "integration_mode": "LINK",
    "type": "BUY_NOW",
    "reusable": "MULTIPLE",
    "return_url": "https://merchant.example.com/thank-you",
    "line_items": [
      {
        "name": "Wireless Mouse",
        "unit_amount": {
          "currency_code": "USD",
          "value": "39.99"
        }
      }
    ]
  }'
```

### 3. Use the `payment_link` URL

The API returns HTTP status `201 Created`, the payment resource `id`, and a `payment_link` URL. Share this URL with customers or embed it behind a button on your site.

### 4. Verify the link

Open the `payment_link` URL in a browser, confirm the product name and price, and complete a test checkout using a sandbox buyer account. Use the `payment_link` value from the `links` array in the response.

```bash [expandable] theme={null}
{
    "id": "PLB-A87RKBMWWFHM",
    "integration_mode": "LINK",
    "type": "BUY_NOW",
    "reusable": "MULTIPLE",
    "return_url": "https://merchant.example.com/thank-you",
    "line_items": [
        {
            "name": "Wireless Mouse",
            "description": "LIGHTSPEED wireless technology: Delivers a 1-millisecond response time for performance that matches wired gaming mice.\nExtended battery life: Offers up to 250 hours of gameplay on a single AA battery, supporting prolonged usage.",
            "unit_amount": {
                "currency_code": "USD",
                "value": "39.99"
            },
            "collect_shipping_address": true
        }
    ],
    "status": "ACTIVE",
    "create_time": "2026-04-02T21:36:12Z",
    "update_time": "2026-04-02T21:36:12Z",
    "links": [
        {
            "href": "https://api-m.sandbox.paypal.com/v1/checkout/payment-resources/PLB-A87RKBMWWFHM",
            "rel": "self",
            "method": "GET"
        },
        {
            "href": "https://api-m.sandbox.paypal.com/v1/checkout/payment-resources/PLB-A87RKBMWWFHM",
            "rel": "replace",
            "method": "PUT"
        },
        {
            "href": "https://api-m.sandbox.paypal.com/v1/checkout/payment-resources/PLB-A87RKBMWWFHM",
            "rel": "delete",
            "method": "DELETE"
        },
        {
            "href": "https://www.sandbox.paypal.com/ncp/payment/PLB-A87RKBMWWFHM",
            "rel": "payment_link",
            "method": "GET"
        }
    ]
}
```

## How it works

The Payment Links and Buttons API exposes a simple lifecycle for Payment Links:

1. Get an OAuth access token for your PayPal Business account.
2. Create a payment resource by calling `POST /v1/checkout/payment-resources`.
3. Share the returned `payment_link` URL with customers.
4. Optionally list, retrieve, update, or delete existing payment resources as your catalog changes.

```mermaid theme={null}
graph LR
    Start([Start]) --> Auth[Get Access Token<br/>POST v1/oauth2/token]
    Auth --> Create[Create Resource<br/>POST v1/checkout/payment-resources]
    Create --> Active[Payment Resource<br/>Status: ACTIVE]
    Active --> Update[Update Resource<br/>PUT v1/checkout/payment-resources/id]
    Update --> Active
    Active --> Delete[Delete Resource<br/>DELETE v1/checkout/payment-resources/id]
    Delete --> Removed([Resource Removed])
    Active -.->|Query| List[List Resources<br/>GET v1/checkout/payment-resources]
    Active -.->|Query| Get[Get Details<br/>GET v1/checkout/payment-resources/id]
    List -.-> Active
    Get -.-> Active
    %% Styling
    classDef lifecycleStyle fill:#d1ecf1,stroke:#0c5460,stroke-width:3px,color:#000
    classDef stateStyle fill:#fff3cd,stroke:#856404,stroke-width:4px,color:#000
    classDef queryStyle fill:#e7d4f7,stroke:#6f42c1,stroke-width:2px,color:#000
    classDef authStyle fill:#cfe2ff,stroke:#084298,stroke-width:3px,color:#000
    classDef endStyle fill:#f8d7da,stroke:#dc3545,stroke-width:3px,color:#000
    class Create,Update,Delete lifecycleStyle
    class Active stateStyle
    class List,Get queryStyle
    class Auth authStyle
    class Removed endStyle
```

## Endpoints

This section summarizes each endpoint. See the full [API reference](https://docs.paypal.ai/reference/api/rest/payment-resources/list-payment-resources) for the complete schema and additional examples.

| Use case                 | Endpoint                                                                                                                              | Request                                                                                                                                                             | Response                                                                                            |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Create payment links     | [`POST /v1/checkout/payment-resources`](https://docs.paypal.ai/reference/api/rest/payment-resources/list-payment-resources)           | Include product details in the request body, such as name, price, description, variants, taxes, shipping information, discounts, handling fees, and the return URL. | Returns `201 Created` with the payment link ID, shareable link URL, status, and creation timestamp. |
| List all payment links   | [`GET /v1/checkout/payment-resources`](https://docs.paypal.ai/reference/api/rest/payment-resources/list-payment-resources)            | This endpoint does not require a payload. Use optional query parameters such as `page_size` to control results per page and `page_token` for pagination.            | Returns `200 OK` with an array of payment links and pagination metadata.                            |
| Get payment link details | [`GET /v1/checkout/payment-resources/{id}`](https://docs.paypal.ai/reference/api/rest/payment-resources/retrieve-a-payment-resource)  | Use the payment link ID in the URL path to retrieve details.                                                                                                        | Returns `200 OK` with complete details for the specified payment link.                              |
| Update payment link      | [`PUT /v1/checkout/payment-resources/{id}`](https://docs.paypal.ai/reference/api/rest/payment-resources/replace-a-payment-resource)   | Use the payment link ID in the URL path. Include the complete, updated product information in the request body.                                                     | Returns `204 No Content` to confirm successful update.                                              |
| Delete payment link      | [`DELETE /v1/checkout/payment-resources/{id}`](https://docs.paypal.ai/reference/api/rest/payment-resources/delete-a-payment-resource) | Use the payment link ID in the URL path to delete it permanently.                                                                                                   | Returns `204 No Content` to confirm successful deletion.                                            |

## Use cases

See how to create payment links that address common scenarios and requirements.

### Create a payment link (`POST /v1/checkout/payment-resources`)

Create a payment link that points to a PayPal‑hosted checkout experience. Use this endpoint to generate shareable payment URLs for your products.

#### Request

```json [expandable] theme={null}
{
  "integration_mode": "LINK",
  "type": "BUY_NOW",
  "reusable": "MULTIPLE",
  "return_url": "https://example-merchant.com/payment/return-success",
  "line_items": [
    {
      "name": "Premium Wireless Headphones with Noise Cancellation",
      "product_id": "PROD-WH-NC-2024-12345",
      "description": "Experience crystal-clear sound with our premium wireless headphones featuring active noise cancellation, 30-hour battery life",
      "taxes": [
        {
          "name": "State Sales Tax",
          "type": "PERCENTAGE",
          "value": "8.25"
        }
      ],
      "shipping": [
        {
          "type": "FLAT",
          "value": "12.50",
          "additional_unit_value": "3.00"
        }
      ],
      "discounts": [
        {
          "type": "PERCENTAGE",
          "value": "10"
        }
      ],
      "handling": [
        {
          "type": "FLAT",
          "value": "5.00"
        }
      ],
      "collect_shipping_address": true,
      "customer_notes": [
        {
          "label": "Gift Message (Optional)",
          "required": false
        }
      ],
      "variants": {
        "dimensions": [
          {
            "name": "Color",
            "primary": true,
            "options": [
              {
                "label": "Midnight Black",
                "unit_amount": {
                  "currency_code": "USD",
                  "value": "149.99"
                }
              },
              {
                "label": "Silver Gray",
                "unit_amount": {
                  "currency_code": "USD",
                  "value": "149.99"
                }
              },
              {
                "label": "Rose Gold",
                "unit_amount": {
                  "currency_code": "USD",
                  "value": "169.99"
                }
              },
              {
                "label": "Navy Blue",
                "unit_amount": {
                  "currency_code": "USD",
                  "value": "159.99"
                }
              }
            ]
          },
          {
            "name": "Warranty",
            "primary": false,
            "options": [
              { "label": "Standard 1-Year" },
              { "label": "Extended 2-Year" },
              { "label": "Premium 3-Year" }
            ]
          },
          {
            "name": "Package Type",
            "primary": false,
            "options": [
              { "label": "Standard Box" },
              { "label": "Gift Wrapped" }
            ]
          }
        ]
      },
      "adjustable_quantity": {
        "maximum": 10
      }
    }
  ]
}
```

#### Response

The response includes the payment resource ID, shareable payment link, product details, and configuration. The API returns HTTP status 201 Created with content type `application/json`.

```json [expandable] theme={null}
{
    "id": "PLB-HL9U6YXUMCGB",
    "integration_mode": "LINK",
    "type": "BUY_NOW",
    "reusable": "MULTIPLE",
    "return_url": "https://example-merchant.com/payment/return-success",
    "line_items": [
        {
            "name": "Premium Wireless Headphones with Noise Cancellation",
            "product_id": "PROD-WH-NC-2024-12345",
            "description": "Experience crystal-clear sound with our premium wireless headphones featuring active noise cancellation, 30-hour battery life",
            "taxes": [
                {
                    "name": "State Sales Tax",
                    "type": "PERCENTAGE",
                    "value": "8.25"
                }
            ],
            "shipping": [
                {
                    "type": "FLAT",
                    "value": "12.50",
                    "additional_unit_value": "3.00"
                }
            ],
            "collect_shipping_address": true,
            "customer_notes": [
                {
                    "required": false,
                    "label": "Gift Message (Optional)"
                }
            ],
            "variants": {
                "dimensions": [
                    {
                        "name": "Color",
                        "primary": true,
                        "options": [
                            {
                                "label": "Midnight Black",
                                "unit_amount": {
                                    "currency_code": "USD",
                                    "value": "149.99"
                                }
                            },
                            {
                                "label": "Silver Gray",
                                "unit_amount": {
                                    "currency_code": "USD",
                                    "value": "149.99"
                                }
                            },
                            {
                                "label": "Rose Gold",
                                "unit_amount": {
                                    "currency_code": "USD",
                                    "value": "169.99"
                                }
                            },
                            {
                                "label": "Navy Blue",
                                "unit_amount": {
                                    "currency_code": "USD",
                                    "value": "159.99"
                                }
                            }
                        ]
                    },
                    {
                        "name": "Warranty",
                        "primary": false,
                        "options": [
                            {
                                "label": "Standard 1-Year"
                            },
                            {
                                "label": "Extended 2-Year"
                            },
                            {
                                "label": "Premium 3-Year"
                            }
                        ]
                    },
                    {
                        "name": "Package Type",
                        "primary": false,
                        "options": [
                            {
                                "label": "Standard Box"
                            },
                            {
                                "label": "Gift Wrapped"
                            }
                        ]
                    }
                ]
            },
            "adjustable_quantity": {
                "maximum": 10
            }
        }
    ],
    "status": "ACTIVE",
    "create_time": "2026-04-02T21:42:42Z",
    "update_time": "2026-04-02T21:42:42Z",
    "links": [
        {
            "href": "https://api-m.sandbox.paypal.com/v1/checkout/payment-resources/PLB-HL9U6YXUMCGB",
            "rel": "self",
            "method": "GET"
        },
        {
            "href": "https://api-m.sandbox.paypal.com/v1/checkout/payment-resources/PLB-HL9U6YXUMCGB",
            "rel": "replace",
            "method": "PUT"
        },
        {
            "href": "https://api-m.sandbox.paypal.com/v1/checkout/payment-resources/PLB-HL9U6YXUMCGB",
            "rel": "delete",
            "method": "DELETE"
        },
        {
            "href": "https://www.sandbox.paypal.com/ncp/payment/PLB-HL9U6YXUMCGB",
            "rel": "payment_link",
            "method": "GET"
        }
    ]
}
```

### List payment resources (`GET /v1/checkout/payment-resources`)

Retrieve a paginated list of all payment resources created by the merchant. This endpoint supports filtering through query parameters, such as `status`.

#### Request

```bash theme={null}
curl -v -k -X GET 'https://api-m.sandbox.paypal.com/v1/checkout/payment-resources?page_size=2' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json'
```

#### Response

The response contains an array of payment resources and pagination links. The API returns HTTP status `200 OK` with content type `application/json`.

```json [expandable] theme={null}
{
  "resources": [
    {
      "id": "PLB-X7MNK9P2QR8T",
      "integration_mode": "LINK",
      "create_time": "2025-11-29T13:13:25.832592Z",
      "status": "ACTIVE",
      "payment_link": "https://www.paypal.com/ncp/payment/PLB-X7MNK9P2QR8T",
      "type": "BUY_NOW",
      "reusable": "MULTIPLE",
      "line_items": [
        {
          "name": "Wireless Mouse",
          "unit_amount": {
            "currency_code": "USD",
            "value": "29.99"
          }
        }
      ],
      "links": [
        {
          "href": "https://api.paypal.com/v1/checkout/payment-resources/PLB-X7MNK9P2QR8T",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://api.paypal.com/v1/checkout/payment-resources/PLB-X7MNK9P2QR8T",
          "rel": "replace",
          "method": "PUT"
        },
        {
          "href": "https://api.paypal.com/v1/checkout/payment-resources/PLB-X7MNK9P2QR8T",
          "rel": "delete",
          "method": "DELETE"
        },
        {
          "href": "https://www.paypal.com/ncp/payment/PLB-X7MNK9P2QR8T",
          "rel": "payment_link",
          "method": "GET"
        }
      ]
    },
    {
      "id": "PLB-P2QR8TX7MNK9",
      "integration_mode": "LINK",
      "create_time": "2025-11-29T13:13:25.832592Z",
      "status": "ACTIVE",
      "payment_link": "https://www.paypal.com/ncp/payment/PLB-P2QR8TX7MNK9",
      "type": "BUY_NOW",
      "reusable": "MULTIPLE",
      "line_items": [
        {
          "name": "Wireless Keyboard",
          "unit_amount": {
            "currency_code": "USD",
            "value": "99.99"
          }
        }
      ],
      "links": [
        {
          "href": "https://api.paypal.com/v1/checkout/payment-resources/PLB-P2QR8TX7MNK9",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://api.paypal.com/v1/checkout/payment-resources/PLB-P2QR8TX7MNK9",
          "rel": "replace",
          "method": "PUT"
        },
        {
          "href": "https://api.paypal.com/v1/checkout/payment-resources/PLB-P2QR8TX7MNK9",
          "rel": "delete",
          "method": "DELETE"
        },
        {
          "href": "https://www.paypal.com/ncp/payment/PLB-P2QR8TX7MNK9",
          "rel": "payment_link",
          "method": "GET"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "https://api.paypal.com/v1/checkout/payment-resources?page_size=2",
      "rel": "self"
    },
    {
      "href": "https://api.paypal.com/v1/checkout/payment-resources?page_token=eyJleGNsdXNpdmVfc3RhcnRfa2V5Ijp7ImlkIjoiUExCLVAyUVI4VFg3TU5LOSJ9LCJwYWdlX3NpemUiOjJ9",
      "rel": "next"
    }
  ]
}
```

### Get payment resource details (`GET /v1/checkout/payment-resources/{id}`)

Get the details of a specific payment resource by its unique ID. This endpoint returns all metadata, including payment status, link URL, reusable type, and line item details.

#### Request

```bash theme={null}
curl -v -k -X GET 'https://api-m.sandbox.paypal.com/v1/checkout/payment-resources/PLB-X7MNK9P2QR8T' \
 -H 'Authorization: Bearer ACCESS-TOKEN' \
 -H 'Accept: application/json' \
 -H 'Content-Type: application/json'
```

#### Response

```json [expandable] theme={null}
{
  "id": "PLB-X7MNK9P2QR8T",
  "integration_mode": "LINK",
  "create_time": "2025-11-29T13:13:25.832592Z",
  "status": "ACTIVE",
  "payment_link": "https://www.paypal.com/ncp/payment/PLB-X7MNK9P2QR8T",
  "type": "BUY_NOW",
  "reusable": "MULTIPLE",
  "return_url": "https://merchant.example.com/thank-you",
  "line_items": [
    {
      "name": "Wireless Mouse",
      "unit_amount": {
        "currency_code": "USD",
        "value": "29.99"
      }
    }
  ],
  "links": [
    {
      "href": "https://api.paypal.com/v1/checkout/payment-resources/PLB-X7MNK9P2QR8T",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.paypal.com/v1/checkout/payment-resources/PLB-X7MNK9P2QR8T",
      "rel": "replace",
      "method": "PUT"
    },
    {
      "href": "https://api.paypal.com/v1/checkout/payment-resources/PLB-X7MNK9P2QR8T",
      "rel": "delete",
      "method": "DELETE"
    },
    {
      "href": "https://www.paypal.com/ncp/payment/PLB-X7MNK9P2QR8T",
      "rel": "payment_link",
      "method": "GET"
    }
  ]
}
```

### Update payment resource (`PUT /v1/checkout/payment-resources/{id}`)

Replace the configuration of a specific payment resource with new product and checkout details.

#### Request

```bash [expandable] theme={null}
curl -v -k -X PUT 'https://api-m.sandbox.paypal.com/v1/checkout/payment-resources/PLB-X7MNK9P2QR8T' \
 -H 'Authorization: Bearer ACCESS-TOKEN' \
 -H 'Accept: application/json' \
 -H 'Content-Type: application/json' \
 -d '{
    "type": "BUY_NOW",
    "integration_mode": "LINK",
    "reusable": "MULTIPLE",
    "return_url": "https://merchant.example.com/thank-you",
    "line_items": [
        {
            "name": "Wireless Mouse",
            "unit_amount": {
                "currency_code": "USD",
                "value": "29.99"
            }
        }
    ]
}'
```

#### Response

The API returns HTTP status `204 No Content` with no response body.

### Delete payment resources (`DELETE /v1/checkout/payment-resources/{id}`)

Permanently delete a payment resource by its unique ID.

#### Request

```bash theme={null}
curl -v -k -X DELETE 'https://api-m.sandbox.paypal.com/v1/checkout/payment-resources/PLB-X7MNK9P2QR8T' \
 -H 'Authorization: Bearer ACCESS-TOKEN' \
 -H 'Accept: application/json' \
 -H 'Content-Type: application/json'
```

#### Response

The API returns HTTP status `204 No Content` with no response body.

## Error handling

| HTTP code | Error name              | Error message                                                                                          | Common cause                                                                                                                                  |
| --------- | ----------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`     | `INVALID_REQUEST`       | Request is not well-formed, syntactically incorrect, or violates the schema.                           | Missing required payment resource fields such as item name, amount, and return URL in the body.                                               |
| `403`     | `NOT_AUTHORIZED`        | Authorization failed due to insufficient permissions.                                                  | The access token has expired or lacks the correct OAuth scopes, and the merchant account doesn't have permission for payment buttons.         |
| `404`     | `RESOURCE_NOT_FOUND`    | The specified resource does not exist.                                                                 | The payment resource ID is wrong, expired, or deleted. You may have tried to fetch, update, or delete a link or button that no longer exists. |
| `422`     | `UNPROCESSABLE_ENTITY`  | The requested action could not be performed, is semantically incorrect, or failed business validation. | Invalid payment amount, unsupported currency, or business rule violation, such as a duplicate payment link.                                   |
| `500`     | `INTERNAL_SERVER_ERROR` | An internal server error has occurred.                                                                 | Temporary disruption during payment link or button processing. Retry the request or contact support if the issue persists.                    |

For more information, see [Common errors](https://docs.paypal.ai/developer/how-to/api/troubleshooting/common-errors/overview).

## Test

* Create a sandbox account through the PayPal Developer Portal.
* Use your sandbox environment for all development and testing. All endpoints are duplicated for the sandbox (`api-m.sandbox.paypal.com`) and live environments. See [Card testing](https://developer.paypal.com/tools/sandbox/card-testing/) to simulate transactions in the sandbox.
* To test live behavior, create a low‑value payment link, complete a test purchase, and verify the transaction in the **Activity** section of your PayPal account. Refund the test transaction after verification.


# Save payment methods directly with the Payment Method Tokens API
Source: https://docs.paypal.ai/payments/save/api/vault-api-integration



No transaction is required when payment methods are saved with the [Payment Method Tokens API](https://developer.paypal.com/docs/api/payment-tokens/v3/). You can save payment methods and charge payers after a set amount of time. Payers don't need to be present when charged. Common use cases include offering free trials, subscription billing, and storing payment methods for faster checkout.

The Payment Method Tokens API supports saving credit and debit cards, and PayPal Wallets. When you save a payer's card or wallet, the API provides a setup token associated with the payment method. You'll exchange this setup token for a permanent token from the API.

You can choose to save cards, PayPal, or both.

## Key differences between PayPal and cards integrations

* Saving a card requires no payer interaction.
* Saving a PayPal Wallet requires payers to approve a billing agreement once.
* Calls to save PayPal or cards require different fields in the request body.
* Cards integrations support cards with the following verification methods:
  * no verification
  * smart authorization
  * 3D Secure

## Country availability

<Accordion title="Supported countries">
  * Australia
  * Austria
  * Belgium
  * Bulgaria
  * Canada
  * China
  * Cyprus
  * Czech Republic
  * Denmark
  * Estonia
  * Finland
  * France
  * Germany
  * Hong Kong
  * Hungary
  * Ireland
  * Italy
  * Japan
  * Latvia
  * Liechtenstein
  * Lithuania
  * Luxembourg
  * Malta
  * Netherlands
  * Norway
  * Poland
  * Portugal
  * Romania
  * Singapore
  * Slovakia
  * Slovenia
  * Spain
  * Sweden
  * United Kingdom
  * United States
</Accordion>

## Prerequisites

Complete the steps in [Get started](https://developer.paypal.com/api/rest/) to get the following information:

* Your business sandbox account login and password.
* Your app's client ID and client secret. Exchange these for an OAuth access token.

To save credit and debit cards, you'll need:

* A [PayPal Expanded Checkout integration](https://developer.paypal.com/studio/checkout/advanced)
* [SAQ D PCI Compliance](https://listings.pcisecuritystandards.org/documents/SAQ_D_v3_Merchant.pdf)

### Enable your business account

<Tip>You can continue to test this integration in the sandbox while waiting for PayPal to approve your eligibility.</Tip>

1. Go to [paypal.com](https://www.paypal.com) and sign in with your business account.
2. Go to **Account Settings** > **Payment Preferences** > **Save PayPal and Venmo payment methods**.
3. In the Save PayPal and Venmo payment methods section, select **Get Started**.
4. When you submit business profile details, PayPal reviews your eligibility to save PayPal and Venmo accounts.
5. After PayPal reviews your eligibility, you'll see one of the following statuses:

* **Success**
* **Need more information**
* **Denied**

### Enable your developer dashboard

Before implementing vaulted payments, enable vaulting features in the PayPal Developer Dashboard.

1. Log in to the [PayPal Developer Dashboard](https://developer.paypal.com/home/).
2. In the navigation menu, use the **Sandbox | Live** toggle to select **Live**.
3. Under **Apps & Credentials** > **REST API apps**, select your app name.
4. To enable vaulting:
   * Go to **Features** > **Payment capabilities**.
   * Toggle on **Save payment methods**.
5. To enable PayPal and Venmo vaulting:
   * Go to **Features** > **Payment methods**.
   * Toggle on **PayPal and Venmo**.

<Info>**Important:** If you're already using the [Billing Agreements API](https://developer.paypal.com/docs/api/payments.billing-agreements/v1/), contact [PayPal customer support](https://www.paypal.com/us/cshelp/contact-us) to save payment methods with the [Payment Method Tokens API](https://developer.paypal.com/docs/api/payment-tokens/v3/).</Info>

<Warning>PayPal requires Risk Data Acquisition (RDA) to reduce fraud. You must implement risk data collection for all customer-initiated transactions (CIT) that use PayPal and Venmo Payment Tokens. Payment attempts that are missing RDA data are likely to be declined due to insufficient risk identifiers. Use the PayPal [FraudNet](https://developer.paypal.com/docs/checkout/apm/pay-upon-invoice/fraudnet/) and [Magnes](https://developer.paypal.com/limited-release/magnes/) libraries to collect and pass RDA data during payment processing.</Warning>

## Create setup token for PayPal

Before you create a setup token, a payer must:

* Log in to their PayPal account
* Approve a billing agreement

Make a `POST` call on the `setup-tokens` endpoint to complete the following actions:

* Receive a `PAYER_ACTION_REQUIRED` status
* Create a temporary setup token
* Redirect the payer after they approve or deny the billing agreement

### Get setup token request

1. Change `ACCESS-TOKEN` to your sandbox access token.
2. Change `REQUEST-ID` to a set of unique alphanumeric characters such as a timestamp.
3. Set the `payment_source` to `paypal`. Complete the rest of the source object for your use case and business.
4. Update the `return_url` value with the URL where the payer is redirected if they approve the flow.
5. Update the `cancel_url` value with the URL where the payer is redirected if they cancel the flow.
6. Optional: For existing customers, pass the `customer.id` to link additional information such as `payment_source` to the customer. For new customers, the customer ID is returned in the setup token response.

Copy and modify the following code sample to create a setup token for PayPal that triggers a flow to approve a billing agreement:

Endpoint: [Create a setup token](https://developer.paypal.com/docs/api/payment-tokens/v3/#setup-tokens_create)

```bash theme={null}
curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v3/vault/setup-tokens' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS-TOKEN" \
  -H "PayPal-Request-Id: REQUEST-ID" \
  -d '{
        "payment_source": {
          "paypal": {
            "description": "Description for PayPal to be shown to PayPal payer",
            "shipping": {
              "name": {
                "full_name": "Firstname Lastname"
              },
              "address": {
                "address_line_1": "2211 N First Street",
                "address_line_2": "Building 17",
                "admin_area_2": "San Jose",
                "admin_area_1": "CA",
                "postal_code": "95131",
                "country_code": "US"
              }
            },
            "permit_multiple_payment_tokens": false,
            "usage_pattern": "IMMEDIATE",
            "usage_type": "MERCHANT",
            "customer_type": "CONSUMER",
            "experience_context": {
              "shipping_preference": "SET_PROVIDED_ADDRESS",
              "payment_method_preference": "IMMEDIATE_PAYMENT_REQUIRED",
              "brand_name": "EXAMPLE INC",
              "locale": "en-US",
              "return_url": "https://example.com/returnUrl",
              "cancel_url": "https://example.com/cancelUrl"
            }
          }
        },
        "customer": {
          "id": "CUSTOMER-ID-TO-LINK-ADDITIONAL-PAYMENT-SOURCE"
        }
      }'
```

### PayPal setup token response

A successful request returns the following:

* An HTTP response code of `200` or `201`. Returns `200` for an idempotent request.
* When saving a payer's PayPal Wallet for first time, the response to the `setup-token` request returns the PayPal-generated `customer.id` and the `setup_token_id`.
* A status of `PAYER_ACTION_REQUIRED`.
* The following HATEOAS links:

| Rel       | Method | Description                                                                         |
| --------- | ------ | ----------------------------------------------------------------------------------- |
| `approve` | `GET`  | Take your payer through a PayPal-hosted approval flow.                              |
| `confirm` | `POST` | Use an approved setup token to save the PayPal Wallet and generate a payment token. |
| `self`    | `GET`  | View the state of your setup token and payment method details.                      |

The setup token expires after 3 days. After the payer completes the approval flow, you can [swap the setup token for a payment token](#swap-setup-token-for-payment-token).

## Create setup token for card

The Payment Method Tokens API can create a setup token for cards that have:

* No verification - checks that card data is formatted correctly when passed to the API.
* Smart authorization - runs a zero-value or minimal-value authorization to validate the card is real and active.
* 3D Secure verification - requires two-factor authentication where the cardholder must authenticate before the transaction.

The card verification method depends on the card, issuing bank, and geographic locale.

1. Change `ACCESS-TOKEN` to your sandbox access token.
2. Change `REQUEST-ID` to a set of unique alphanumeric characters such as a time stamp.
3. Use the card as the payment source and complete the rest of the source object for your use case and business.
4. Pass the `verification_method` parameter with `SCA_WHEN_REQUIRED` for PayPal to automatically trigger the appropriate verification method for the card.
5. Update the `return_url` value with the URL where the payer is redirected after they approve the flow.
6. Update the `cancel_url` value with the URL where the payer is redirected after they cancel the flow.
7. Optional: For existing customers, pass the `customer.id` to link additional information such as `payment_source` to the customer. For new customers, the customer ID is returned in the setup token response.

Copy and modify the following code sample to create a setup token associated with a credit or debit card.

Endpoint: [Create a setup token](https://developer.paypal.com/docs/api/payment-tokens/v3/#setup-tokens_create)

```bash theme={null}
curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v3/vault/setup-tokens' \
  -H "Authorization: Bearer ACCESS-TOKEN" \
  -H "PayPal-Request-Id: REQUEST-ID" \
  -H "Content-Type: application/json" \
  -d '{
        "payment_source": {
          "card": {
            "number": "4111111111111111",
            "expiry": "2027-02",
            "name": "Firstname Lastname",
            "billing_address": {
              "address_line_1": "2211 N First Street",
              "address_line_2": "17.3.160",
              "admin_area_1": "CA",
              "admin_area_2": "San Jose",
              "postal_code": "95131",
              "country_code": "US"
            },
            "verification_method": "SCA_WHEN_REQUIRED",
            "experience_context": {
              "brand_name": "YourBrandName",
              "locale": "en-US",
              "return_url": "https://example.com/returnUrl",
              "cancel_url": "https://example.com/cancelUrl"
            }
          }
        },
        "customer": {
          "id": "CUSTOMER-ID-TO-LINK-ADDITIONAL-PAYMENT-SOURCE"
        }
      }'
```

### Cards setup token response

A successful request returns the following:

* An HTTP response code of `200` or `201`. Returns `200` for an idempotent request.
* When saving a card for the first time for a payer, the response to the setup token request returns the `customer.id` and the `setup_token_id`.
* A status of `PAYER_ACTION_REQUIRED`.
* The following HATEOAS links:

| Rel       | Method | Description                                                                | Verification methods |
| --------- | ------ | -------------------------------------------------------------------------- | -------------------- |
| `approve` | `GET`  | Take the payer through the card approval flow.                             | 3D secure only       |
| `confirm` | `POST` | Use an approved setup token to save the card and generate a payment token. | All methods          |
| `self`    | `GET`  | View the state of your setup token and payment source data.                | All methods          |

## Swap setup token for payment token

Exchange a temporary setup token for a permanent payment token.

### Swap setup token call

Copy and modify the following code:

1. Change `ACCESS-TOKEN` to your sandbox access token.
2. Change `REQUEST-ID` to a unique alphanumeric set of characters such as a time stamp.
3. Use `token` as the `payment_source` and complete the rest of the source object for your use case and business.
4. Pass the ID of the setup token you obtained from the previous step in the `payment_source` parameter. Set the type as `SETUP_TOKEN`.

Endpoint: [Create payment token for a given payment source](https://developer.paypal.com/docs/api/payment-tokens/v3/#payment-tokens_create)

```bash theme={null}
curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v3/vault/payment-tokens' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS-TOKEN" \
  -H "PayPal-Request-Id: REQUEST-ID" \
  -d '{
        "payment_source": {
          "token": {
            "id": "YOUR-SETUP-TOKEN-ID-GOES-HERE",
            "type": "SETUP_TOKEN"
          }
        }
      }'
```

### Swap setup token response

A successful request returns:

* An HTTP response code of `200` or `201`. Returns `200` for an idempotent request
* `id` of the payment token and associated payment method information.
* The following HATEOAS links:

| Rel      | Method   | Description                                  |
| -------- | -------- | -------------------------------------------- |
| `self`   | `GET`    | Retrieve data about the saved payment method |
| `delete` | `DELETE` | Delete the payment token                     |

## Use saved payment token for purchase

After you create a payment method token, use the token instead of the payment method to create a purchase and capture the payment with the Orders API.

You can use the payment method token to create an order on behalf of the payer when the payer isn't present.

You can store a merchant customer ID to help match your customer information across your system and PayPal. This is an optional field that returns the value shared in the response.

### Call the Orders v2 API with saved payment token

<Warning>PayPal requires Risk Data Acquisition (RDA) to reduce fraud. You must implement risk data collection for all customer-initiated transactions (CIT) that use PayPal and Venmo Payment Tokens. Payment attempts that are missing RDA data are likely to be declined due to insufficient risk identifiers. Use the PayPal [FraudNet](https://developer.paypal.com/docs/checkout/apm/pay-upon-invoice/fraudnet/) and [Magnes](https://developer.paypal.com/limited-release/magnes/) libraries to collect and pass RDA data during payment processing.</Warning>

Copy and modify the following code:

1. Change `ACCESS-TOKEN` to your sandbox access token.
2. Change `REQUEST-ID` to a set of unique alphanumeric characters such as a time stamp.
3. Set the `payment_source` to `card` or `paypal`.
4. For `vault_id`, enter the ID of the payment method token you received in the previous step.

The following request creates an order with a payment token associated with a card.

Endpoint: [Create order](https://developer.paypal.com/docs/api/orders/v2/#orders_create)

```curl theme={null}
curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v2/checkout/orders' \
  -H "PayPal-Request-Id: REQUEST-ID" \
  -H "Authorization: Bearer ACCESS-TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "intent": "CAPTURE",
        "purchase_units": [
          {
            "amount": {
              "currency_code": "USD",
              "value": "100.00"
            }
          }
        ],
        "payment_source": {
          "card": {
            "vault_id": "ID-FROM-PREVIOUS-STEP"
          }
        }
      }'
```

### Optional: Retrieve saved payment token

If you stored the payment token the payer created on your site, skip this step.

To make a payment on behalf of the payer, retrieve the payment token they created. You'll need the customer ID that you assigned to this payer when saving the payment method.

Copy and modify the following code:

* Change `ACCESS-TOKEN` to your sandbox access token
* Pass the PayPal-generated `customer_id` to retrieve the payment token details associated with the payer.

Endpoint: [Retrieve a payment token](https://developer.paypal.com/docs/api/payment-tokens/v3/#payment-tokens_get)

```bash theme={null}
curl -v -k -X GET 'https://api-m.sandbox.paypal.com/v3/vault/payment-tokens?customer_id=customer_YOUR-CUSTOMER-ID' \
 -H 'Authorization: Bearer ACCESS-TOKEN' \
 -H 'Content-Type: application/json'
```

After you retrieve the `payment_tokens.id`, you can use the payment method token with checkout to create an order.


# Test saving cards with a direct Payment Method Tokens API integration
Source: https://docs.paypal.ai/payments/save/api/vault-api-integration-test



The Payment Method Tokens API can create a setup token for credit or debit cards that have:

* No verification
* Smart authorization
* 3D Secure verification

Send a call for each card type to test your integration works as expected.

## Prerequisites

You'll need a [Payment Method Tokens API cards integration](https://developer.paypal.com/docs/checkout/save-payment-methods/purchase-later/payment-tokens-api/cards/).

## No verification

For cards with no verification, the card data passed to the API is checked only for format.

### Sample request for setup token with no verification

1. Change `ACCESS-TOKEN` to your sandbox access token.
2. Change `REQUEST-ID` to a unique alphanumeric set of characters, for example, a time stamp.

Copy and modify the following code sample to create a setup token associated with a credit or debit card with no verification.

Endpoint: [Create a setup token](https://developer.paypal.com/docs/api/payment-tokens/v3/#setup-tokens_create)

```bash theme={null}
curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v3/vault/setup-tokens' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS-TOKEN" \
  -H "PayPal-Request-Id: REQUEST-ID" \
  -d '{
        "payment_source": {
          "card": {
            "number": "4111111111111111",
            "expiry": "2027-02",
            "name": "Firstname Lastname",
            "billing_address": {
              "address_line_1": "2211 N First Street",
              "address_line_2": "17.3.160",
              "admin_area_1": "CA",
              "admin_area_2": "San Jose",
              "postal_code": "95131",
              "country_code": "US"
            },
            "experience_context": {
              "brand_name": "YourBrandName",
              "locale": "en-US",
              "return_url": "https://example.com/returnUrl",
              "cancel_url": "https://example.com/cancelUrl"
            }
          }
        }
      }'
```

### Sample response for setup token with no verification

A successful request returns the following:

* An HTTP response code of `200` or `201`. Returns `200` for an idempotent request.
* The ID of the token in the `id` field.
* [HATEOAS links](/payments/save/api/vault-api-integration#cards-setup-token-response)

```bash theme={null}
{
  "id": "5C991763VB2781612",
  "customer": {
    "id": "customer_4029352050"
  },
  "status": "APPROVED",
  "payment_source": {
    "card": {
      "last_digits": "1111",
      "expiry": "2027-02",
      "name": "Firstname Lastname",
      "billing_address": {
        "address_line_1": "2211 N First Street",
        "address_line_2": "17.3.160",
        "admin_area_2": "San Jose",
        "admin_area_1": "CA",
        "postal_code": "95131",
        "country_code": "US"
      }
    }
  },
  "links": [{
      "href": "https://api-m.sandbox.paypal.com/v3/vault/setup-tokens/5C991763VB2781612",
      "rel": "self",
      "method": "GET",
      "encType": "application/json"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens",
      "rel": "confirm",
      "method": "POST",
      "encType": "application/json"
    }
  ]
}
```

## Smart authorization

Smart authorization runs a zero-value or minimal-value authorization to validate the card is real and active.

Some issuing banks or regions don't support zero-value authorization, so a minimal-value authorization is run. The seller must manually cancel minimal-value authorizations or the customer will have a small pending charge on their card.

### Sample request for setup token with smart authorization

1. Change `ACCESS-TOKEN` to your sandbox access token.
2. Change `REQUEST-ID` to a set of unique alphanumeric characters such as a time stamp.
3. Use the card as the payment source and complete the rest of the source object for your use case and business.
4. Pass the `verification_method` parameter with `SCA_WHEN_REQUIRED` to verify card data.
5. Update the `return_url` value with the URL where the payer is redirected after they approve the flow.
6. Update the `cancel_url` value with the URL where the payer is redirected after they cancel the flow.

Copy and modify the following code:

Endpoint: [Create a setup token](https://developer.paypal.com/docs/api/payment-tokens/v3/#setup-tokens_create)

```bash theme={null}
curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v3/vault/setup-tokens' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS-TOKEN" \
  -H "PayPal-Request-Id: REQUEST-ID" \
  -d '{
        "payment_source": {
          "card": {
            "number": "4111111111111111",
            "expiry": "2027-02",
            "name": "Firstname Lastname",
            "billing_address": {
              "address_line_1": "2211 N First Street",
              "address_line_2": "17.3.160",
              "admin_area_1": "CA",
              "admin_area_2": "San Jose",
              "postal_code": "95131",
              "country_code": "US"
            },
            "experience_context": {
              "brand_name": "YourBrandName",
              "locale": "en-US",
              "return_url": "https://example.com/returnUrl",
              "cancel_url": "https://example.com/cancelUrl"
            }
          }
        }
      }'
```

### Sample response for setup token with smart authorization

A successful request returns the following:

* An HTTP response code of `200` or `201`. Returns `200` for an idempotent request.
* A status of `APPROVED`
* The ID of the token in the `id` field.
* [HATEOAS links](/payments/save/api/vault-api-integration#cards-setup-token-response)

```json theme={null}
{
  "id": "5C991763VB2781612",
  "status": "APPROVED",
  "payment_source": {
    "card": {
      "brand": "VISA",
      "last_digits": "1111",
      "verification_status": "VERIFIED",
      "verification": {
        "network_transaction_id": "20286098380002303",
        "time": "2020-10-07T22:44:41.000Z",
        "amount": {
          "value": "0.00",
          "currency_code": "USD"
        },
        "processor_response": {
          "avs_code": "M",
          "cvv_code": "P"
        }
      }
    }
  },
  "links": [{
      "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-token",
      "rel": "confirm",
      "method": "POST",
      "encType": "application/json"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v3/vault/setup-tokens/5C991763VB2781612",
      "rel": "self",
      "method": "GET",
      "encType": "application/json"
    }
  ]
}
```

## 3D Secure

Use 3D Secure authentication to reduce the likelihood of fraud and improve transaction performance with supported cards. In some countries, authorizing a card can trigger a 3D Secure contingency.

3D Secure verification may occur in PSD2 countries, including members of the EU. For 3D Secure verification, pass  `SCA_ALWAYS` or `SCA_WHEN_REQUIRED` in the `payment_source.card.attributes.verification`.method field for the create order request. The API response returns the order status as `PAYER_ACTION_REQUIRED`.

### Sample request for setup token with 3D Secure

1. Change `ACCESS-TOKEN` to your sandbox access token.
2. Change `REQUEST-ID` to a set of unique alphanumeric characters such as a time stamp.
3. Use the card as the payment source and complete the rest of the source object for your use case and business.
4. Pass the `verification_method` parameter with `SCA_ALWAYS` to verify card data.
5. Update the `return_url` value with the URL where the payer is redirected after they approve the flow.
6. Update the `cancel_url` value with the URL where the payer is redirected after they cancel the flow.

Copy and modify the following code:

```bash theme={null}
curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v3/vault/setup-tokens'\
 -H "Content-Type: application/json"\
 -H "Authorization: Bearer ACCESS-TOKEN"\
 -H "PayPal-Request-Id: REQUEST-ID"\
 -d '{
     "payment_source": {
       "card": {
         "number": "4111111111111111",
         "expiry": "2027-02",
         "name": "Firstname Lastname",
         "billing_address": {
           "address_line_1": "2211 N First Street",
           "address_line_2": "17.3.160",
           "admin_area_1": "CA",
           "admin_area_2": "San Jose",
           "postal_code": "95131",
           "country_code": "US"
         },
         "verification_method": "SCA_WHEN_REQUIRED",
         "experience_context": {
           "brand_name": "YourBrandName",
           "locale": "en-US",
           "return_url": "https://example.com/returnUrl",
           "cancel_url": "https://example.com/cancelUrl"
         }
       }
     }
    }'
```

### Sample response for setup token with 3D Secure

A successful request returns the following:

* An HTTP response code of `200` or `201`. Returns `200` for an idempotent request.
* A status of `PAYER_ACTION_REQUIRED`
* [HATEOAS links](/payments/save/api/vault-api-integration#cards-setup-token-response)

```json theme={null}
{
  "id": "5C991763VB2781612",
  "customer": {
    "id": "customer_4029352050"
  },
  "status": "PAYER_ACTION_REQUIRED",
  "payment_source": {
    "card": {
      "last_digits": "1111",
      "brand": "VISA",
      "type": "CREDIT",
      "expiry": "2027-02"
    }
  },
  "links": [{
      "href": "https://paypal.com/webapps/helios?action=authenticate&validate_session_id=82cf4a87-5c40-0a27-1a09-4ffbb0d05fdc",
      "rel": "approve",
      "method": "GET",
      "encType": "application/json"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-token",
      "rel": "confirm",
      "method": "POST",
      "encType": "application/json"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v3/vault/setup-tokens/5C991763VB2771612",
      "rel": "self",
      "method": "GET",
      "encType": "application/json"
    }
  ]
}
```

### Convert approved setup token to payment token

After the payer completes verification, make a `POST` request on the [payment token endpoint](https://developer.paypal.com/docs/api/payment-tokens/v3/#create-a-payment-token) to convert the approved setup token to a payment token.

To retrieve 3D secure verification data associated with a setup token, make a `GET` request on the [setup token endpoint](https://developer.paypal.com/docs/api/payment-tokens/v3/#setup-token).

#### Sample request

```bash theme={null}
curl -v -k -X GET 'https://api-m.sandbox.paypal.com/v3/vault/setup-tokens/5C991763VB2781612'\
  -H "Content-Type: application/json"\
  -H "Authorization: Bearer ACCESS-TOKEN"\
  -H "PayPal-Request-Id: REQUEST-ID"\
```

#### Sample response

A successful request returns the following:

* An HTTP response code of `200 OK`
* A status of `APPROVED`

| Parameter             | Description                                                                                                                                                                         |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `verification_method` | The verification method value from the request is included in the response.                                                                                                         |
| `verification_status` | If the card is authorized, the status is set to `VERIFIED`.                                                                                                                         |
| `authorization`       | Details from the authorization are returned in an `authorization` object. This includes the amount and currency requested, and the AVS and CVV results from the processor response. |

The issuing bank can still issue an authorization if a card fails the AVS and CVV checks. In this case, the setup token is created with an `APPROVED` status and the processor responses are returned to you. The `eci_flag` parameter indicates that 3D Secure was not completed.

You can choose whether to use a card that did not complete 3D Secure or failed AVS and CVV checks:

* To use the card, make a `POST` request on [add-payment-token](https://developer.paypal.com/docs/api/payment-tokens/v3/#payment-tokens_create). Convert the approved setup token to a full payment token.
* To reject the card, don't add the payment token or convert it to a full payment token.

In the sandbox, create a setup token and a 3D Secure token. Validate a card with card data from [3D Secure test scenarios](https://developer.paypal.com/docs/checkout/advanced/customize/3d-secure/test/).

```json theme={null}
{
  "id": "5C991763VB2771612",
  "status": "APPROVED",
  "payment_source": {
    "card": {
      "brand": "VISA",
      "last_digits": "1111",
      "verification_status": "VERIFIED",
      "verification": {
        "network_transaction_id": "20286098380002303",
        "time": "2020-10-07T22:44:41.000Z",
        "amount": {
          "value": "0.00",
          "currency_code": "USD"
        },
        "processor_response": {
          "avs_code": "M",
          "cvv_code": "P"
        },
        "three_d_secure": {
          "type": "THREE_DS_AUTHENTICATION",
          "eci_flag": "FULLY_AUTHENTICATED_TRANSACTION",
          "card_brand": "VISA",
          "enrolled": "Y",
          "pares_status": "Y",
          "three_ds_version": "2",
          "authentication_type": "DYNAMIC",
          "three_ds_server_transaction_id": "3d-secure-txn-id"
        }
      }
    }
  },
  "links": [{
      "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-token",
      "rel": "confirm",
      "method": "POST",
      "encType": "application/json"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v3/vault/setup-tokens/5C991763VB2771612",
      "rel": "self",
      "method": "GET",
      "encType": "application/json"
    }
  ]
}
```

## Test AVS and CVV response codes

Generate AVS and CVV response codes when running tests in the PayPal sandbox.

Use [test card numbers](https://developer.paypal.com/tools/sandbox/card-testing/#link-teststaticcardnumbers).

### Generate AVS response

Set `address_line_1` to  the following values to generate an AVS response.

| Address Line 1 | AVS Response | Visa | Mastercard | American Express | Discover |
| -------------- | ------------ | ---- | ---------- | ---------------- | -------- |
| AVS\_A\_971    | A            | Yes  | Yes        | Yes              | Yes      |
| AVS\_B\_972    | B            | Yes  | No         | No               | No       |
| AVS\_C\_973    | C            | Yes  | No         | No               | No       |
| AVS\_D\_974    | D            | Yes  | No         | Yes              | No       |
| AVS\_E\_975    | E            | No   | Yes        | Yes              | No       |
| AVS\_F\_976    | F            | Yes  | No         | Yes              | No       |
| AVS\_G\_977    | G            | Yes  | No         | No               | Yes      |
| AVS\_I\_979    | I            | Yes  | No         | No               | No       |
| AVS\_K\_981    | K            | No   | No         | Yes              | No       |
| AVS\_L\_982    | L            | No   | No         | Yes              | No       |
| AVS\_M\_983    | M            | Yes  | No         | Yes              | No       |
| AVS\_N\_984    | N            | Yes  | Yes        | Yes              | Yes      |
| AVS\_O\_985    | O            | No   | No         | Yes              | No       |
| AVS\_P\_986    | P            | Yes  | No         | No               | No       |
| AVS\_R\_988    | R            | Yes  | Yes        | Yes              | Yes      |
| AVS\_S\_989    | S            | Yes  | Yes        | Yes              | Yes      |
| AVS\_U\_991    | U            | Yes  | Yes        | Yes              | Yes      |
| AVS\_W\_993    | W            | Yes  | Yes        | Yes              | Yes      |
| AVS\_X\_994    | X            | Yes  | Yes        | No               | Yes      |
| AVS\_Y\_995    | Y            | Yes  | Yes        | Yes              | Yes      |
| AVS\_Z\_996    | Z            | Yes  | Yes        | Yes              | Yes      |

### Generate CVV response

Set the CVV to the following values to generate a CVV response:

| CVV | CVV response | Description                                                        |
| --- | ------------ | ------------------------------------------------------------------ |
| 115 | M            | CVV2/CVC2/CID Match                                                |
| 116 | N            | CVV2/CVC2/CID No Match                                             |
| 120 | P            | Not Processed                                                      |
| 123 | S            | CVV2 should be on the card, but merchant indicated that it was not |
| 125 | U            | Unknown/Issuer does not participate                                |
| 130 | X            | Server provider did not respond (default)                          |


# Save cards with purchase with the JavaScript SDK
Source: https://docs.paypal.ai/payments/save/sdk/cards/js-sdk-v6-vault



After customers save their credit or debit card, they can select it for faster checkout. Customers won't have to enter payment details for future transactions.

Use the JavaScript SDK to save a payer's card if you aren't <a href="https://www.pcisecuritystandards.org/pci_security/completing_self_assessment">PCI Compliant - SAQ A</a> but want to save credit or debit cards during checkout.

## Availability

<Accordion title="Supported countries">
  * Australia
  * Austria
  * Belgium
  * Bulgaria
  * Canada
  * China
  * Cyprus
  * Czech Republic
  * Denmark
  * Estonia
  * Finland
  * France
  * Germany
  * Hong Kong
  * Hungary
  * Ireland
  * Italy
  * Japan
  * Latvia
  * Liechtenstein
  * Lithuania
  * Luxembourg
  * Malta
  * Netherlands
  * Norway
  * Poland
  * Portugal
  * Romania
  * Singapore
  * Slovakia
  * Slovenia
  * Spain
  * Sweden
  * United Kingdom
  * United States
</Accordion>

## Prerequisites

* This integration requires a PayPal Developer account.
* You'll need to have an existing [credit and debit card payments integration](https://developer.paypal.com/docs/checkout/advanced/). PayPal must approve your account to process advanced credit and debit card payments.
* Complete the steps in [Get started](https://developer.paypal.com/api/rest/) to get the following sandbox account information from the Developer Dashboard:
  * The sandbox client ID and secret of your REST app.
  * An access token to use the PayPal REST API server.
* This client-side and server-side integration uses the following:
  * [PayPal JavaScript SDK](https://docs.paypal.ai/reference/sdk-v6-reference)
  * [Orders REST API](https://developer.paypal.com/docs/api/orders/v2/)

## How it works

PayPal encrypts payment method information and stores it in a digital vault for that customer.

1. The payer saves their payment method.
2. For a first-time payer, PayPal creates a customer ID. Store this within your system for future use.
3. When the customer returns to your website and is ready to check out, pass their PayPal-generated customer ID to the JavaScript SDK. The customer ID tells the JavaScript SDK to save or reuse a saved payment method.
4. The payer completes a billing agreement.
5. The JavaScript SDK populates the checkout page with each saved payment method. Each payment method appears as a one-click button next to other ways to pay.

The checkout process is now shorter because it uses saved payment information.

## Use cases

Businesses save payment methods if they want customers to:

* Check out without re-entering a payment method
* Pay after use, for example, ride-sharing and food delivery

You can charge now and save the card in a single flow. Keep your one-time payment session on the client and add a vault directive on your server when creating the order.

## 1. Set up your sandbox to save payment methods

Set up your sandbox and live business accounts to save payment methods:

1. Log in to the Developer Dashboard.
2. Under **REST API apps**, select your app name.
3. Under **Sandbox App Settings** > **App Feature Options**, check **Accept payments**.
4. Expand **Advanced options**. Confirm that **Vault** is selected.

<Warning>PayPal requires Risk Data Acquisition (RDA) to reduce fraud. You must implement risk data collection for all customer-initiated transactions (CIT) that use PayPal and Venmo Payment Tokens. Payment attempts that are missing RDA data are likely to be declined due to insufficient risk identifiers. Use the PayPal [FraudNet](https://developer.paypal.com/docs/checkout/apm/pay-upon-invoice/fraudnet/) and [Magnes](https://developer.paypal.com/limited-release/magnes/) libraries to collect and pass RDA data during payment processing.</Warning>

## 2. Add a checkbox for payers to save their card

Add a `checkbox` element grouped with your card collection fields to give payers the option to save their card.

```html theme={null}
  <input type="checkbox" id="save" name="save">
  <label for="save">Save your card</label>
</div>
```

## 3. Pass the checkbox value

Pass `document.getElementById("save").checked` to your server with the following details in the `createOrder()` method:

* Value of the checkbox
* Optional: Card name
* Optional: Billing address

<Tabs>
  <Tab title="No verification">
    ```javascript theme={null}
    // Initialize the v6 SDK with card-fields component
    const sdk = await window.paypal.createInstance({ 
      clientId: "YOUR_CLIENT_ID",
      components: ["card-fields"] 
    });

    // Create a one-time payment session using v6 SDK
    const session = sdk.createCardFieldsOneTimePaymentSession();

    // Check eligibility and render card fields
    if (session.isEligible()) {
      session.NameField().render("#card-name-field-container");
      session.NumberField().render("#card-number-field-container");
      session.ExpiryField().render("#card-expiry-field-container");
      session.CVVField().render("#card-cvv-field-container");
    } else {
      // Handle the workflow when credit and debit cards are not available
    }

    // Submit button event handler
    const submitButton = document.getElementById("submit-button");
    submitButton.addEventListener("click", async () => {
      try {
        // Create order - server determines verification settings
        const saveCheckbox = document.getElementById("save");
        
        const orderResponse = await fetch("/api/paypal/order/create/", {
          method: "POST",
          headers: {
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            saveCard: saveCheckbox.checked,
          }),
        });
        
        const orderData = await orderResponse.json();
        const orderId = orderData.id;

        // Submit the session with billing address
        const { state, data } = await session.submit(orderId, {
          billingAddress: { 
            postalCode: "95131"
          },
        });

        // Handle successful transaction
        if (state === "succeeded") {
          // Capture the order
          const captureResponse = await fetch(`/api/paypal/orders/${data.orderId}/capture/`, {
            method: "POST"
          });
          
          const captureData = await captureResponse.json();
          
          // Handle vault details if card was saved
          const vault = captureData?.paymentSource?.card?.attributes?.vault;
          if (vault) {
            // Save the vault.id and vault.customer.id for future use
            console.log('Vault ID:', vault.id);
            console.log('Customer ID:', vault.customer.id);
          }
          
          // Handle successful transaction completion
          console.log('Payment completed successfully');
        }
        
      } catch (error) {
        // Handle any error that may occur
        console.error('Payment error:', error);
      }
    });
    ```
  </Tab>

  <Tab title="3D Secure">
    To trigger the authentication, pass the required contingency with the verification method in the create orders payload. The verification method can be contingencies parameter with `SCA_ALWAYS` or `SCA_WHEN_REQUIRED`.

    `SCA_ALWAYS` triggers an authentication for every transaction, while `SCA_WHEN_REQUIRED` triggers an authentication only when a regional compliance mandate such as PSD2 is required. 3D Secure is supported only in countries with a <a href="https://www.paypal.com/uk/webapps/mpp/PSD2?_ga=1.51925228.43968804.1640649786PSD2">PSD2 compliance mandate</a>.

    ```javascript theme={null}
    // Initialize the v6 SDK with card-fields component
    const sdk = await window.paypal.createInstance({ 
      clientId: "YOUR_CLIENT_ID",
      components: ["card-fields"] 
    });

    // Create a one-time payment session using v6 SDK
    const session = sdk.createCardFieldsOneTimePaymentSession();

    // Check eligibility and render card fields
    if (session.isEligible()) {
      session.NameField().render("#card-name-field-container");
      session.NumberField().render("#card-number-field-container");
      session.ExpiryField().render("#card-expiry-field-container");
      session.CVVField().render("#card-cvv-field-container");
    } else {
      // Handle the workflow when credit and debit cards are not available
    }

    // Submit button event handler
    const submitButton = document.getElementById("submit-button");
    submitButton.addEventListener("click", async () => {
      try {
        // Create order with 3DS verification directly in client payload
        const saveCheckbox = document.getElementById("save");
        
        const orderResponse = await fetch("/api/paypal/order/create/", {
          method: "POST",
          headers: {
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            saveCard: saveCheckbox.checked,
            // Direct 3DS configuration in client payload
            card: {
              attributes: {
                verification: {
                  method: "SCA_ALWAYS" // or "SCA_WHEN_REQUIRED"
                },
              },
              experience_context: {
                shipping_preference: "NO_SHIPPING",
                return_url: "https://example.com/returnUrl",
                cancel_url: "https://example.com/cancelUrl",
              },
            }
          }),
        });
        
        const orderData = await orderResponse.json();
        const orderId = orderData.id;

        // Submit the session with billing address
        const { state, data } = await session.submit(orderId, {
          billingAddress: { 
            postalCode: "95131"
          },
        });

        // Handle successful transaction
        if (state === "succeeded") {
          // Capture the order
          const captureResponse = await fetch(`/api/paypal/orders/${data.orderId}/capture/`, {
            method: "POST"
          });
          
          const captureData = await captureResponse.json();
          
          // Handle vault details if card was saved
          const vault = captureData?.paymentSource?.card?.attributes?.vault;
          if (vault) {
            // Save the vault.id and vault.customer.id for future use
            console.log('Vault ID:', vault.id);
            console.log('Customer ID:', vault.customer.id);
          }
          
          // Handle successful transaction completion
          console.log('Payment completed successfully');
        }
        
      } catch (error) {
        // Handle any error that may occur
        console.error('Payment error:', error);
      }
    });
    ```
  </Tab>
</Tabs>

## 4. Create an order and save the card

Use the Orders API to create a transaction and save the payer's card in a single step.

### Server side

Set up your server to call the Orders API. The button that the payer selects determines the `payment_source` sent in the following sample.

This SDK uses the Orders v2 API to save payment methods in the background. Use the following request using the Orders API to add attributes needed to save a card.

<Warning>PayPal requires Risk Data Acquisition (RDA) to reduce fraud. You must implement risk data collection for all customer-initiated transactions (CIT) that use PayPal and Venmo Payment Tokens. Payment attempts that are missing RDA data are likely to be declined due to insufficient risk identifiers. Use the PayPal [FraudNet](https://developer.paypal.com/docs/checkout/apm/pay-upon-invoice/fraudnet/) and [Magnes](https://developer.paypal.com/limited-release/magnes/) libraries to collect and pass RDA data during payment processing.</Warning>

<Tabs>
  <Tab title="First-time payer">
    #### Save a payment method for first-time payers

    This request is for payers who:

    * Don't have a payment source saved into the vault.
    * Selected the save checkbox. The `document.getElementById("save").checked` value is `true`.

    To run 3D Secure on the card, set the  `payment_source.card.attributes.verification.method` to `SCA_ALWAYS` or `SCA_WHEN_REQUIRED`.

    `SCA_ALWAYS` triggers an authentication for every transaction, while `SCA_WHEN_REQUIRED` triggers an authentication only when a regional compliance mandate such as PSD2 is required. 3D Secure is supported only in countries with a <a href="https://www.paypal.com/uk/webapps/mpp/PSD2?_ga=1.51925228.43968804.1640649786PSD2">PSD2 compliance mandate</a>.

    > **Note:** In the following requests, the `payment_source.attributes.vault.store_in_vault` with the value `ON_SUCCESS` means the card is saved with a successful authorization or capture.

    ```bash theme={null}
    curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders 
    -H "Content-Type: application/json"
    -H "Authorization: Bearer 'ACCESS-TOKEN'"
    -d '{
      "intent": "CAPTURE",
      "purchase_units": [{
        "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
        "amount": {
          "currency_code": "USD",
          "value": "100.00"
        }
      }],
      "payment_source": {
        "card": {
          "name": "Firstname Lastname",
          "billing_address": {
            "address_line_1": "123 Main St.",
            "address_line_2": "Unit B",
            "admin_area_2": "Anytown",
            "admin_area_1": "CA",
            "postal_code": "12345",
            "country_code": "US"
          },
            "attributes": {
            "customer" : {
                "id": "'PayPal-generated customer id'"
            },
            "vault": {
              "store_in_vault": "ON_SUCCESS"
            },
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Returning payer">
    #### Save payment method for returning payers

    This request is for payers who:

    * Already have a payment method saved in the vault.
    * Want to save another payment method to the vault.
    * Selected the save checkbox. The `document.getElementById("save").checked` value is `true`.

    Pass the PayPal-generated `customer.id` as part of this request. Link additional `payment_sources` to this customer through their `customer.id`. The `customer.id` is returned in the response from an `authorize` or `capture` request.

    ```bash theme={null}
    curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders  
    -H "Content-Type: application/json" 
    -H "Authorization: Bearer 'ACCESS-TOKEN'" 
    -d '{
          "intent": "CAPTURE",
          "purchase_units": [{
            "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
            "amount": {
              "currency_code": "USD",
              "value": "100.00"
            }
          }],
          "payment_source": {
            "card": {
              "name": "Firstname Lastname",
              "billing_address": {
                "address_line_1": "123 Main St.",
                "address_line_2": "Unit B",
                "admin_area_2": "Anytown",
                "admin_area_1": "CA",
                "postal_code": "12345",
                "country_code": "US"
              },
              "attributes": {
                "customer" : {
                    "id": "'PayPal-generated customer id'"
                },
                "vault": {
                  "store_in_vault": "ON_SUCCESS"
                },
              }
            }
          }
        }
    ```
  </Tab>
</Tabs>

#### Response

Pass the order `id` to the JavaScript SDK. The SDK updates the order with the new card details. PayPal handles any PCI compliance issues.

After the SDK is updated, it triggers the `onApprove()` method, which receives an object containing the `orderID`. You can authorize or capture the order when you have the `orderID`.

> **Note:** The request to save the payment method is made when the order is created through `payment_source.attributes.vault.store_in_vault`. Vault details are available only after an order is authorized or captured.

```json theme={null}
  {
    "id": "5O190127TN364715T",
    "status": "CREATED",
    "intent": "CAPTURE",
    "payment_source": {
      "card": {
        "brand": "VISA",
        "last-digits": "1881",
        "billing_address": {
          "address_line_1": "123 Main St.",
          "address_line_2": "Unit B",
          "admin_area_2": "Anytown",
          "admin_area_1": "CA",
          "postal_code": "12345",
          "country_code": "US"
        }
      }
    },
    "purchase_units": [{
      "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
      "amount": {
        "currency_code": "USD",
        "value": "100.00"
      }
    }],
    "create_time": "2021-10-28T21:18:49Z",
    "links": [{
        "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
        "rel": "self",
        "method": "GET"
      },
      {
        "href": "https://www.sandbox.paypal.com/checkoutnow?token=5O190127TN364715T",
        "rel": "approve",
        "method": "GET"
      },
      {
        "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
        "rel": "update",
        "method": "PATCH"
      },
      {
        "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/capture",
        "rel": "capture",
        "method": "POST"
      }
    ]
  }
```

## 5. Authorize or capture the order and save the card

After the payer submits their card details, authorize or capture the order to complete the payment and save the card to the vault.

### Server side

Set up your server to call the <a href="/reference/api/rest/orders/create-order">Orders v2 API</a>:

* Call the [authorize order endpoint](https://developer.paypal.com/docs/api/orders/v2/#orders_authorize) if the `intent` passed was `AUTHORIZE`.
* Call the [capture order endpoint](https://developer.paypal.com/docs/api/orders/v2/#orders_capture) if the `intent` passed was `CAPTURE`.

### Request

Add a `payment_source.card` instruction for vault. Use your desired amounts, URLs, and business policy.

```bash theme={null}
curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/YOUR-ORDER-ID/{authorize or capture}
-H "Content-Type: application/json"
-H "Authorization: Bearer 'YOUR-ACCESS-TOKEN'"
-d
'{
  "intent": "CAPTURE",
  "purchase_units": [{
    "amount": { "currency_code": "USD", "value": "100.00" }
  }],
  "payment_source": {
    "card": {
      // 3DS (optional): see 3DS guide for attributes.verification + experience_context
      "attributes": {
        // "verification": { "method": "SCA_WHEN_REQUIRED" },
        "vault": {
          "store_in_vault": "ON_SUCCESS" // or "ALWAYS" per your business policy
        }
      }
    }
  }'
```

### Response

A successful request returns the order details, including the vault status and payment token for the saved card.

```json theme={null}
  {
    "id": "5O190127TN364715T",
    "status": "COMPLETED",
    "payment_source": {
      "card": {
        "brand": "VISA",
        "last_digits": "4949",
        "attributes": {
          "vault": {
            "id": "nkq2y9g",
            "customer": {
                "id": "695922590"
            },
            "status": "VAULTED",
            "links": [{
                "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/nkq2y9g",
                "rel": "self",
                "method": "GET"
              },
              {
                "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/nkq2y9g",
                "rel": "delete",
                "method": "DELETE"
              },
              {
                "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
                "rel": "up",
                "method": "GET"
              }
            ]
          }
        }
      }
    },
    "purchase_units": [{
      "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
      "payments": {
        "captures": [{
          "id": "3C679366HH908993F",
          "status": "COMPLETED",
          "amount": {
            "currency_code": "USD",
            "value": "100.00"
          },
          "seller_protection": {
            "status": "NOT_ELIGIBLE"
          },
          "final_capture": true,
          "seller_receivable_breakdown": {
            "gross_amount": {
              "currency_code": "USD",
              "value": "100.00"
            },
            "paypal_fee": {
              "currency_code": "USD",
              "value": "3.00"
            },
            "net_amount": {
              "currency_code": "USD",
              "value": "97.00"
            }
          },
          "create_time": "2022-01-01T21:20:49Z",
          "update_time": "2022-01-01T21:20:49Z",
          "processor_response": {
              "avs_code": "Y",
              "cvv_code": "M",
              "response_code": "0000"
          },
          "links": [{
              "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/3C679366HH908993F",
              "rel": "self",
              "method": "GET"
            },
            {
              "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/3C679366HH908993F/refund",
              "rel": "refund",
              "method": "POST"
            }
          ]
        }]
      }
    }],
    "links": [{
      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
      "rel": "self",
      "method": "GET"
    }]
}
```

In the response from the Authorize or Capture request, the Orders v2 API interacts with the Payment Method Tokens v3 API to save the card.

The `payment_source.card.attributes.vault` stores the card information as the `vault.id`, which can be used for future payments when the `vault.status` is `VAULTED`.

#### Save an approved payment source

If the payment has been authorized or captured, the payer doesn't need to be present to save a `payment_source`. To keep checkout times as short as possible, the Orders API responds as soon as payment is captured.

If the `attributes.vault.status` returned after payment is `APPROVED`, you won't have a `vault.id` yet. An example of the `attributes` object from this scenario is in the following sample:

```json theme={null}
  "attributes": {
    "vault": {
      "status": "APPROVED",
      "links": [
        {
          "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
          "rel": "up",
          "method": "GET"
        }
      ]
    }
  }
```

The Payment Method Tokens API still saves the payment source even after the Orders API returns its response and sends a webhook after the payment source is saved.

In order to retrieve a `vault_id` when an `APPROVED` status is returned, you'll need to subscribe to the `VAULT.PAYMENT-TOKEN.CREATED` [webhook](https://developer.paypal.com/api/rest/webhooks/).

The Payment Method Tokens API sends a webhook after the payment source is saved. An example of the `VAULT.PAYMENT-TOKEN.CREATED` webhook payload is shown in the following sample:

```json theme={null}
  {
     "id":"WH-1KN88282901968003-82E75604WM969463F",
     "event_version":"1.0",
     "create_time":"2022-08-15T14:13:48.978Z",
     "resource_type":"payment_token",
     "resource_version":"3.0",
     "event_type":"VAULT.PAYMENT-TOKEN.CREATED",
     "summary":"A payment token has been created.",
     "resource":{
        "time_created":"2022-08-15T07:13:48.964PDT",
        "links":[
           {
              "href":"https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/9n6724m",
              "rel":"self",
              "method":"GET",
              "encType":"application/json"
           },
           {
              "href":"https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/9n6724m",
              "rel":"delete",
              "method":"DELETE",
              "encType":"application/json"
           }
        ],
        "id":"nkq2y9g",
        "payment_source":{
           "card":{
              "last_digits":"1111",
              "brand":"VISA",
              "expiry":"2027-02",
              "billing_address":{
                 "address_line_1":"123 Main St.",
                 "address_line_2":"Unit B",
                 "admin_area_2":"Anytown",
                 "admin_area_1":"CA",
                 "postal_code":"12345",
                 "country_code":"US"
              }
           }
        },
        "customer":{
           "id":"695922590"
        }
     },
     "links":[
        {
           "href":"https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-1KN88282901968003-82E75604WM969463F",
           "rel":"self",
           "method":"GET"
        },
        {
           "href":"https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-1KN88282901968003-82E75604WM969463F/resend",
           "rel":"resend",
           "method":"POST"
        }
     ]
  }
```

In this example, the `resource.id` field is the vault ID, and `resource.customer.id` is the PayPal-generated customer ID.

You can now style your card fields and test a purchase.

#### Payment processor codes

Payment processors return the following codes when they receive a transaction request. For advanced card payments, the code displays in the authorization object under the `response_code` field.

The following sample shows the processor response codes returned in an authorization (`avs_code`) and capture call (`cvv_code`) response:

```json theme={null}
  "processor_response": {
    "avs_code": "Y",
    "cvv_code": "S",
    "response_code": "0000"
  }
```

See the Orders API `response_code` object to get the [processor response code for the non-PayPal payment processor errors](https://developer.paypal.com/docs/api/orders/v2/#definition-processor_response).

## 6. Pay with saved payment methods

When a payer returns to your site, you can show the payer's saved payment methods with the Payment Method Tokens API.

### List all saved payment methods

Make the server-side [list all payment tokens API call](https://developer.paypal.com/docs/api/payment-tokens/v3/#customer_payment-tokens_get) to retrieve payment methods saved to a payer's PayPal-generated customer ID. Based on this list, you can show all saved payment methods to a payer to select during checkout.

### Show the saved card to the payer

Display the saved card to the payer and use the Orders API to make another transaction. Use the vault ID the payer selects as an input to the Orders API.

Use [supported CSS properties](https://developer.paypal.com/docs/checkout/advanced/customize/card-field-style/) to style the card fields.

## 7. Test your integration

Test your vault integration in the PayPal sandbox.

1. Copy the sample request code.
2. Change `'ACCESS_TOKEN'` to your
   access token.

### Save a payment method

1. On the checkout page, enter the card information and select the option to save the card. You can use [test card numbers](#test-cards) for testing.
2. Capture the transaction.
3. Log in to [sandbox](https://www.sandbox.paypal.com/) with your merchant account and verify the transaction.

### Pay with a saved payment method

1. Use the [list all payment tokens](https://developer.paypal.com/docs/api/payment-tokens/v3/#payment-tokens_payment-tokens) API to retrieve all the payment methods saved for the payer.
2. Capture the payment by passing the payer-selected vault ID to the Orders API.
3. Log in to the [sandbox](https://www.sandbox.paypal.com/) with your merchant account and verify the transaction.

## 8. Integrate the front end

The following sample shows how a full script to save cards might appear in HTML:

```html theme={null}
<head>
  <!-- Add meta tags for mobile and IE -->
  <meta charset="utf-8" />
</head>
<body>
  <script src="https://www.paypal.com/sdk/js?components=card-fields&client-id=YOUR-CLIENT-ID&currency=USD&intent=capture&merchant-id=YOUR-MERCHANT-ID"></script>
  <div align="center"> or </div>
  <!-- Advanced credit and debit card payments form -->
  <div class='card_container'>
    <div id='card-number'></div>
    <div id='expiration-date'></div>
    <div id='cvv'></div>
    <div id='card-holder-name'></div>
    <label>
<input type='checkbox' id='vault' name='vault' /> Vault
    </label>
    <br /><br />
    <button value='submit' id='submit' class='btn'>Pay</button>
  </div>
  <!-- Implementation -->
  <script>
    // Create the card fields component and define callbacks
    const cardFields = paypal.CardFields({
createOrder: async (data) => {
  const result = await fetch("https://api-m.sandbox.paypal.com/v2/checkout/orders", {
    method: "POST",
    body: JSON.stringify({
intent: "CAPTURE",
purchase_units: [{
  amount: {
    currency_code: "USD",
    value: "100.00"
  }
}],
payment_source: {
  card: {
    attributes: {
verification: {
  method: "SCA_ALWAYS"
},
vault: {
  store_in_vault: "ON_SUCCESS",
  usage_type: "PLATFORM",
  customer_type: "CONSUMER",
  permit_multiple_payment_tokens: true,
},
    }
  },
  experience_context: {
    shipping_preference: "NO_SHIPPING",
    return_url: "https://example.com/returnUrl",
    cancel_url: "https://example.com/cancelUrl",
  },
},
    }),
    headers: {
"Content-Type": "application/json",
"Authorization": "Bearer ACCESS_TOKEN",
"PayPal-Request-Id": "UNIQUE_ALPHANUMERIC_KEY"
    },
  })
  const {
    id
  } = await result.json();
  return id;
},
onApprove: async (data) => {
  const {
    orderID
  } = data;
  return fetch('https://api-m.sandbox.paypal.com/v2/checkout/orders/\${orderID}/capture/', {
    method: "POST",
    body: JSON.stringify({
payment_source: {
  attributes: {
    vault: {
store_in_vault: "ON_SUCCESS",
usage_type: "PLATFORM",
customer_type: "CONSUMER",
permit_multiple_payment_tokens: true,
    },
  },
  experience_context: {
    shipping_preference: "NO_SHIPPING",
    return_url: "https://example.com/returnUrl",
    cancel_url: "https://example.com/cancelUrl",
  },
},
    }),
    headers: {
"Content-Type": "application/json",
"Authorization": "Bearer ACCESS_TOKEN",
"PayPal-Request-Id": "UNIQUE_ALPHANUMERIC_KEY"
    },
  })
  // Retrieve vault details from the response and
  // save vault.id and customer.id for the buyer's return experience
  return await res.json();
},
onError: (error) => console.error('Something went wrong:', error)
    });
    // Render each field after checking for eligibility
    // Check eligibility and display advanced credit and debit card payments
    if (cardFields.isEligible()) {
cardFields.NameField().render("#card-holder-name");
cardFields.NumberField().render("#card-number");
cardFields.ExpiryField().render("#expiration-date");
cardFields.CVVField().render("#cvv");
    } else {
// Handle workflow when credit and debit cards are not available
    }
    const submitButton = document.getElementById("submit");
    submitButton.addEventListener("click", () => {
cardFields
  .submit()
  .then(() => {
    console.log("submit was successful");
  })
  .catch((error) => {
    console.error("submit erred:", error);
  });
    });
  </script>
  </html>
```

## Testing

Use the following card numbers to test transactions in the sandbox:

| Test number        | Card type        |
| ------------------ | ---------------- |
| `371449635398431`  | American Express |
| `376680816376961`  | American Express |
| `36259600000004`   | Diners Club      |
| `6304000000000000` | Maestro          |
| `5063516945005047` | Maestro          |
| `2223000048400011` | Mastercard       |
| `4005519200000004` | Visa             |
| `4012000033330026` | Visa             |
| `4012000077777777` | Visa             |
| `4012888888881881` | Visa             |
| `4217651111111119` | Visa             |
| `4500600000000061` | Visa             |
| `4772129056533503` | Visa             |
| `4915805038587737` | Visa             |

Test the following scenarios:

* Transaction succeeds and card is saved to the vault. Verify in the merchant dashboard.
* Transaction fails and the instrument is not saved with `ON_SUCCESS`.
* 3DS success, cancellations, and failures behave as expected

## Troubleshooting

* Make sure you've placed the vault directive under `payment_source.card.attributes` during order creation.
* Verify currency and amount consistency between session context and server payloads.
* Add missing `break;` statements in client `switch` handling of `state`.

## Next steps

* [Go live](https://developer.paypal.com/api/rest/production/) with this integration.
  * Complete [production onboarding](https://www.paypal.com/bizsignup/entry/product/ppcp) to be eligible to process cards with your live PayPal account.
  * Be sure to swap the credentials and API URL from sandbox to production when going live with your integration.
* Follow [Use payment method token with checkout](https://developer.paypal.com/docs/checkout/save-payment-methods/purchase-later/cards/#link-usesavedpaymenttoken) for subsequent or recurring transactions.
* You can [get a payment token](https://developer.paypal.com/docs/api/payment-tokens/v3/#payment-tokens_get), [list all payment tokens](https://developer.paypal.com/docs/api/payment-tokens/v3/#payment-tokens_payment-tokens), [delete a payment token](https://developer.paypal.com/docs/api/payment-tokens/v3/#payment-tokens_delete), and more with the Payment Method Tokens API.
* Keep saved cards up-to-date with the [real-time account updater](https://developer.paypal.com/docs/checkout/advanced/customize/rtau/).


# Save cards without purchase with the JavaScript SDK
Source: https://docs.paypal.ai/payments/save/sdk/cards/js-sdk-v6-vault-no-purchase



Save payment methods to charge payers after a set amount of time. For example, you can offer a free trial and charge payers after the trial expires. Payers don't need to be present when charged. No checkout required.

Use the JavaScript SDK to save a payer's card if you aren't <a href="https://www.pcisecuritystandards.org/pci_security/completing_self_assessment">PCI Compliant - SAQ A</a> but want to save credit or debit cards during checkout.

## Availability

<Accordion title="Supported countries">
  * Australia
  * Austria
  * Belgium
  * Bulgaria
  * Canada
  * China
  * Cyprus
  * Czech Republic
  * Denmark
  * Estonia
  * Finland
  * France
  * Germany
  * Hong Kong
  * Hungary
  * Ireland
  * Italy
  * Japan
  * Latvia
  * Liechtenstein
  * Lithuania
  * Luxembourg
  * Malta
  * Netherlands
  * Norway
  * Poland
  * Portugal
  * Romania
  * Singapore
  * Slovakia
  * Slovenia
  * Spain
  * Sweden
  * United Kingdom
  * United States
</Accordion>

## Prerequisites

* You are responsible for the front-end user experience. The JavaScript  SDK provides back-end support.
* To save payment methods, you must be able to identify payers uniquely. For example, payers create an account and log in to your site.
* Complete the steps in [Get started](https://developer.paypal.com/api/rest) to get the following sandbox account information from the Developer Dashboard:
  * Your sandbox account login information
  * Your access token
* This client-side integration uses the `createCardFieldsSavePaymentSession()` method to save a card without a transaction.
* The JavaScript SDK saves the following card types for purchase later:
  * American Express
  * Discover
  * Mastercard
  * Visa
    You'll need an existing [advanced credit and debit integration](https://developer.paypal.com/studio/checkout/advanced). PayPal must approve your business account for advanced credit and debit card payments.

## How it works

PayPal encrypts payment method information and stores it in a digital vault for that customer.

1. The payer saves their payment method.
2. For a first-time payer, PayPal creates a customer ID. Store this within your system for future use.
3. When the customer returns to your website and is ready to check out, pass their PayPal-generated customer ID to your server to retrieve saved instruments.
4. The payer completes any required verification (for example, 3DS) per your SCA policy.
5. Your UI can display saved payment methods as a one-click button alongside other ways to pay.

## 1. Set up your account to save payments

Set up your sandbox and live business accounts to save payment methods:

1. Log in to the Developer Dashboard.
2. Under **REST API apps**, select your app name.
3. Under **Sandbox App Settings** > **App Feature Options**, check **Accept payments**.
4. Expand **Advanced options**. Confirm that **Vault** is selected.

<Warning>PayPal requires Risk Data Acquisition (RDA) to reduce fraud. You must implement risk data collection for all customer-initiated transactions (CIT) that use PayPal and Venmo Payment Tokens. Payment attempts that are missing RDA data are likely to be declined due to insufficient risk identifiers. Use the PayPal [FraudNet](https://developer.paypal.com/docs/checkout/apm/pay-upon-invoice/fraudnet/) and [Magnes](https://developer.paypal.com/limited-release/magnes/) libraries to collect and pass RDA data during payment processing.</Warning>

## 2. Add the SDK to an HTML page

Pass your client ID to the SDK to identify yourself.
Replace `CLIENT-ID` with your app's client ID in the following sample:

```html theme={null}
<script async src="https://sandbox.paypal.com/web-sdk/v6/core" onload="onPayPalWebSdkLoaded()"></script>
```

## 3. Create a setup token

You request a setup token from your server. The setup token creation for v6 now supports optional 3D Secure verification per your SCA policy.

<Warning>PayPal requires Risk Data Acquisition (RDA) to reduce fraud. You must implement risk data collection for all customer-initiated transactions (CIT) that use PayPal and Venmo Payment Tokens. Payment attempts that are missing RDA data are likely to be declined due to insufficient risk identifiers. Use the PayPal [FraudNet](https://developer.paypal.com/docs/checkout/apm/pay-upon-invoice/fraudnet/) and [Magnes](https://developer.paypal.com/limited-release/magnes/) libraries to collect and pass RDA data during payment processing.</Warning>

### Create a vault setup token on your server

This example for v6 includes optional 3DS or SCA behavior:

```bash theme={null}
curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v3/vault/setup-tokens' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ACCESS-TOKEN" \
-H "PayPal-Request-Id: REQUEST-ID" \
-d '{
      "payment_source": {
        "card": {
          "verification_method": "SCA_WHEN_REQUIRED",
          "experience_context": {
            "return_url": "https://example.com/returnUrl",
            "cancel_url": "https://example.com/cancelUrl"
          }
        }
      }
  }'
```

Create a setup token for cards that have:

* No verification - omit `verification_method`
* 3D Secure verification - `"SCA_ALWAYS"` or `"SCA_WHEN_REQUIRED"`

### Front-end sample

Use the setup token from your server to start the save payment session on the client.

```javascript theme={null}
const sdk = await window.paypal.createInstance({ clientId: "YOUR_CLIENT_ID", components: ["card-fields"] });
const session = sdk.createCardFieldsSavePaymentSession();
// ... render number/cvv/expiry as usual

const { setupToken } = await createVaultSetupToken({ enable3DS, scaMethod });
const { state, data } = await session.submit(setupToken);

switch (state) {
  case "succeeded": {
    // Persist data.vaultSetupToken (or returned instrument id) on your server
    break;
  }
  case "canceled": {
    // Buyer dismissed challenge
    break;
  }
  case "failed": {
    // Show retry message, inspect data.message
    break;
  }
}
```

### Back-end sample

Make this request from your server.

This setup token is generated with an empty `card` in the `payment_source` object. PayPal hosted fields use this token to securely update the setup token with card details.

Copy and modify the following code:

1. Change `ACCESS-TOKEN` to your sandbox app's access token.
2. Change `REQUEST-ID` to a set of unique alphanumeric characters such as a time stamp.
3. In the `createVaultSetupToken`, call the endpoint on your server to create a setup token with the [Payment Method Tokens API](https://developer.paypal.com/docs/api/payment-tokens/v3/). `createVaultSetupToken` returns the setup token as a string.

```bash theme={null}
curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v3/vault/setup-tokens' 
-H "Content-Type: application/json"
-H "Authorization: Bearer ACCESS-TOKEN" 
-H "PayPal-Request-Id: REQUEST-ID" 
-d '{
      "payment_source": {
        "card": {}
      }
  }'
```

## 4. Initialize card fields to save data

When you want to vault a card without taking a payment, use the Save Payment Session on the client: `sdk.createCardFieldsSavePaymentSession()`.

### Front-end sample

Render the card fields and handle the submit flow based on your verification preference.

<Tabs>
  <Tab title="No verification">
    ```javascript theme={null}
    // Initialize the v6 SDK
    const sdk = await window.paypal.createInstance({ 
      clientId: "YOUR_CLIENT_ID",
      components: ["card-fields"] 
    });

    // Create the session
    const session = sdk.createCardFieldsSavePaymentSession();

    // Render the card fields (you still need this part)
    session.render({
      fields: {
        number: { selector: '#card-number' },
        cvv: { selector: '#card-cvv' },
        expirationDate: { selector: '#card-expiry' }
      }
    });

    // When user submits the form (replace the automatic callbacks)
    async function handleSubmit() {
      try {
        // This replaces your createVaultSetupToken callback
        const result = await fetch("example.com/create/setup/token");
        const setupToken = result.token;

        // Submit with the session (this is the new way)
        const { state, data } = await session.submit(setupToken);

        switch (state) {
          case "succeeded": {
            // This replaces your onApprove callback
            await fetch("example.com/create/payment/token", { 
              body: JSON.stringify({ vaultSetupToken: data.vaultSetupToken })
            });
            break;
          }
          case "canceled": {
            // Handle when user cancels
            break;
          }
          case "failed": {
            // Handle errors
            console.error(data.message);
            break;
          }
        }
      } catch (error) {
        console.error("Error:", error);
      }
    }
    ```
  </Tab>

  <Tab title="3D Secure">
    ```javascript theme={null}
    // Initialize the v6 SDK
    const sdk = await window.paypal.createInstance({ 
      clientId: "YOUR_CLIENT_ID",
      components: ["card-fields"] 
    });

    // Create the session
    const session = sdk.createCardFieldsSavePaymentSession();

    // Render the card fields (you still need this part)
    session.render({
      fields: {
        number: { selector: '#card-number' },
        cvv: { selector: '#card-cvv' },
        expirationDate: { selector: '#card-expiry' }
      }
    });

    // When user submits the form (replace the automatic callbacks)
    async function handleSubmit() {
      try {
        // This replaces your createVaultSetupToken callback
        const result = await fetch("example.com/create/setup/token");
        const setupToken = result.token;

        // Submit with the session (this is the new way)
        const { state, data } = await session.submit(setupToken);

        switch (state) {
          case "succeeded": {
            // This replaces your onApprove callback
            // Send the vaultSetupToken to your server for later use
            const vaultSetupToken = data.vaultSetupToken;
            // Do whatever you need with the token here
            console.log("Vault setup token:", vaultSetupToken);
            break;
          }
          case "canceled": {
            // Handle when user cancels
            break;
          }
          case "failed": {
            // This replaces your onError callback
            console.error('Something went wrong:', data.message);
            break;
          }
        }
      } catch (error) {
        // This also replaces your onError callback for network/other errors
        console.error('Something went wrong:', error);
      }
    }
    ```
  </Tab>
</Tabs>

### Back-end sample

Make this request from your server. Copy and modify the following code.

1. Pass the `vaultSetupToken` returned by `onApprove` to your server.
2. Change `ACCESS-TOKEN` to your sandbox app's access token.
3. Change `REQUEST-ID` to a set of unique alphanumeric characters such as a time stamp.
4. Change `VAULT-SETUP-TOKEN` to the value passed from the client.
5. Save the resulting `payment token` returned from the API to use in future transactions.

```bash theme={null}
curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v3/vault/payment-tokens' 
-H "Content-Type: application/json" 
-H "Authorization: Bearer ACCESS-TOKEN" 
-H "PayPal-Request-Id: REQUEST-ID"
-d '{
      "payment_source": {
          "token": {
              "id": "VAULT-SETUP-TOKEN",
              "type": "SETUP_TOKEN"
          }
      }
  }'
```

### Avoid validation errors

`sdk.createCardFieldsSavePaymentSession()` cannot be used alongside `sdk.createCardFieldsPaymentSession()` on the same page. Create separate sessions for different use cases:

```javascript theme={null}
// Initialize the v6 SDK
const sdk = await window.paypal.createInstance({ 
  clientId: "YOUR_CLIENT_ID",
  components: ["card-fields"] 
});

// Option 1: For vaulting (saving cards)
const vaultSession = sdk.createCardFieldsSavePaymentSession();

// Option 2: For immediate payments
const paymentSession = sdk.createCardFieldsPaymentSession();

// Render the same card fields (they can be reused)
const cardFieldsConfig = {
  fields: {
    number: { selector: '#card-number' },
    cvv: { selector: '#card-cvv' },
    expirationDate: { selector: '#card-expiry' }
  }
};

// You can render with either session
vaultSession.render(cardFieldsConfig);
// OR
// paymentSession.render(cardFieldsConfig);

// Then use the appropriate session based on user intent:

// For vaulting:
async function handleVault() {
  const result = await fetch("example.com/create/setup/token");
  const setupToken = result.token;
  const { state, data } = await vaultSession.submit(setupToken);
  // Handle vault result...
}

// For immediate payment:
async function handlePayment() {
  const result = await fetch("example.com/create/order");
  const orderId = result.id;
  const { state, data } = await paymentSession.submit(orderId);
  // Handle payment result...
```

## 5. Show an error page

If an error prevents checkout, alert the payer that an error has occurred using the `console.error()` method call.

> **Note:** This script doesn't handle specific errors. It shows a specified error page for all errors.

```javascript theme={null}
// Initialize the v6 SDK
const sdk = await window.paypal.createInstance({ 
  clientId: "YOUR_CLIENT_ID",
  components: ["card-fields"] 
});

// Create a session (choose based on your use case)
const session = sdk.createCardFieldsSavePaymentSession();
// OR
// const session = sdk.createCardFieldsPaymentSession();

// Render the card fields
session.render({
  fields: {
    number: { selector: '#card-number' },
    cvv: { selector: '#card-cvv' },
    expirationDate: { selector: '#card-expiry' }
  }
});

// Error handling is now done in your submit function
async function handleSubmit() {
  try {
    // Your token/order creation logic here
    const setupToken = "your-setup-token"; // or orderId for payments
    
    const { state, data } = await session.submit(setupToken);

    switch (state) {
      case "succeeded": {
        // Handle success
        break;
      }
      case "canceled": {
        // Handle cancellation
        break;
      }
      case "failed": {
        // This replaces your onError callback
        console.error('Something went wrong:', data.message);
        break;
      }
    }
  } catch (error) {
    // This also handles errors (like the onError callback)
    console.error('Something went wrong:', error);
  }
}
```

## 6. Show saved payment methods to returning payers

When a payer returns to your site, you can show the payer's saved payment methods with the Payment Method Tokens API.

### List all saved payment methods

Make the server-side [list all payment tokens API call](https://developer.paypal.com/docs/api/payment-tokens/v3/#customer_payment-tokens_get) to retrieve payment methods saved to a payer's PayPal-generated customer ID. Based on this list, you can show all saved payment methods to a payer to select during checkout.

> **Important:** Don't expose payment method token IDs on the client side. To protect your payers, create separate IDs for each token and use your server to correlate them.

#### Sample request: List all saved payment methods

Copy and modify the following code.

* Change `CUSTOMER-ID` to a PayPal-generated customer ID.
* Change `ACCESS-TOKEN` to your sandbox app's access token.
* Change `REQUEST-ID` to a set of unique alphanumeric characters such as a time stamp.

```bash theme={null}
curl -L -X GET "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens?customer_id=CUSTOMER-ID"
-H "Content-Type: application/json" 
-H "Accept-Language: en_US" 
-H "Authorization: Bearer ACCESS-TOKEN"
-H "PayPal-Request-Id: REQUEST-ID" \
```

### Show the saved card to the payer

Display the saved card to the payer and use the Orders API to make another transaction. Use the vault ID the payer selects as an input to the [Orders API to capture the payment](https://developer.paypal.com/docs/checkout/save-payment-methods/purchase-later/cards/#link-usesavedpaymenttoken).

Use [supported CSS properties](https://developer.paypal.com/docs/checkout/advanced/customize/card-field-style/) to style the card fields. We recommend showing the card brand and last 4 digits.

![Visa ending in 1234](https://www.paypalobjects.com/devdoc/visa-example.png)

## 7. Integrate the back end

The following sample shows a complete back-end integration to save cards for purchase later:

```javascript theme={null}
import "dotenv/config";
import express from "express";
const {
  PORT = 8888
} = process.env;
const app = express();
app.set("view engine", "ejs");
app.use(express.static("public"));
// Create setup token
app.post("/api/vault/token", async (req, res) => {
  try {
    // Use your access token to securely generate a setup token
    // with an empty payment_source
    const vaultResponse = await fetch("https://api-m.sandbox.paypal.com/v3/vault/setup-tokens", {
      method: "POST",
      body: JSON.stringify({
        payment_source: {
          card: {}
        }
      }),
      headers: {
        Authorization: 'Bearer \${ACCESS-TOKEN}',
        "PayPal-Request-Id": Date.now()
      }
    })
    // Return the reponse to the client
    res.json(vaultResponse);
  } catch (err) {
    res.status(500).send(err.message);
  }
})
// Create payment token from a setup token
app.post("/api/vault/payment-token", async (req, res) => {
  try {
    const paymentTokenResult = await fetch("https://api-m.sandbox.paypal.com/v3/vault/payment-tokens", {
      method: "POST",
      body: {
        payment_source: {
          token: {
            id: req.body.vaultSetupToken,
            type: "SETUP_TOKEN"
          }
        }
      },
      headers: {
        Authorization: 'Bearer \${ACCESS-TOKEN}',
        "PayPal-Request-Id": Date.now()
      }
    })
    const paymentMethodToken = paymentTokenResult.id
    const customerId = paymentTokenResult.customer.id
    await save(paymentMethodToken, customerId)
    res.json(captureData);
  } catch (err) {
    res.status(500).send(err.message);
  }
})
const save = async function(paymentMethodToken, customerId) {
  // Specify where to save the payment method token
}
app.listen(PORT, () => {
  console.log('Server listening at http://localhost:\${PORT}/');
})
```

## 8. Test saving cards

Use the following card numbers to test transactions in the sandbox:

<Accordion title="See test card numbers and types">
  <table>
    <thead>
      <tr>
        <th>Test number</th>
        <th>Card type</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>`371449635398431`</td>
        <td>American Express</td>
      </tr>

      <tr>
        <td>`376680816376961`</td>
        <td>American Express</td>
      </tr>

      <tr>
        <td>`36259600000004`</td>
        <td>Diners Club</td>
      </tr>

      <tr>
        <td>`6304000000000000`</td>
        <td>Maestro</td>
      </tr>

      <tr>
        <td>`5063516945005047`</td>
        <td>Maestro</td>
      </tr>

      <tr>
        <td>`2223000048400011`</td>
        <td>Mastercard</td>
      </tr>

      <tr>
        <td>`4005519200000004`</td>
        <td>Visa</td>
      </tr>

      <tr>
        <td>`4012000033330026`</td>
        <td>Visa</td>
      </tr>

      <tr>
        <td>`4012000077777777`</td>
        <td>Visa</td>
      </tr>

      <tr>
        <td>`4012888888881881`</td>
        <td>Visa</td>
      </tr>

      <tr>
        <td>`4217651111111119`</td>
        <td>Visa</td>
      </tr>

      <tr>
        <td>`4500600000000061`</td>
        <td>Visa</td>
      </tr>

      <tr>
        <td>`4772129056533503`</td>
        <td>Visa</td>
      </tr>

      <tr>
        <td>`4915805038587737`</td>
        <td>Visa</td>
      </tr>
    </tbody>
  </table>
</Accordion>

Test your integration to see if it saves credit and debit cards as expected. Any errors that occur appear in the `console.error()` method call provided to the `CardFields` component. Test 3DS success, cancel, and fail cases behave as expected.

1. Render the card fields.
2. Create a save button in your UI.
3. When the save button is selected, `session.submit(setupToken)` returns `succeeded` and provides a reference you can store. Update the setup token with card details.
4. On your server, use a server-side call to swap your setup token for a payment token from the Payment Method Tokens API.
   1. For a first-time payer, save the PayPal-generated `customer.id`.
   2. For a returning payer, use the PayPal-generated `customer.id` to swap the `setup-token` for a `payment-token`.
5. Save the `payment-token` for future use. Test a purchase with the payment token.
6. Show saved payment methods:
   1. Make a server-side call to the [list all payment tokens endpoint](https://developer.paypal.com/docs/api/payment-tokens/v3/#customer_payment-tokens_get). Include the PayPal-generated `customer.id`.
   2. Style the card fields.

## Troubleshooting

| Issue                                               | Resolution                                                                                                                                                                                                                             |
| :-------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Vault setup is failing                              | **Check session type:** Verify you're using `createCardFieldsSavePaymentSession()` for vault-only flows, not `createCardFieldsOneTimePaymentSession()`. One-time sessions are for transactions, not vaulting.                          |
| 3D Secure verification is not completing properly   | **Check URLs:** Ensure you've included `return_url` and `cancel_url` in your `experience_context` when requesting SCA verification. These are required for the 3DS challenge flow to redirect users back to your application.          |
| Cannot use vaulted payment methods for transactions | **Check vault reference storage:** Verify that your server is capturing and persisting the payment token returned in the API response after vaulting. Without storing this reference, you won't be able to use the vaulted card later. |

## Optional: Show saved payment methods

We recommend creating a page on your site where payers can see their saved payment methods as in the following example:

![A website showing a payment methods page. The page shows the payer saved a PayPal Wallet and a credit card. The card option is highlighted.](https://www.paypalobjects.com/devdoc/save_card_wo_purchase.png)

## Next step

[Go live](https://developer.paypal.com/api/rest/production/) with your integration.


# Save PayPal without purchase with the JavaScript SDK
Source: https://docs.paypal.ai/payments/save/sdk/paypal/js-sdk-v6-vault



This guide demonstrates how to integrate PayPal save payment functionality using the JavaScript SDK v6. Customers can securely save their PayPal payment methods for future transactions without making an immediate purchase. A common use case is offering a free trial and charging customers after the trial period ends.

The PayPal Save Payment integration enables you to:

* Collect and securely store PayPal payment methods without charging the customer.
* Create payment tokens for future use in subsequent transactions.
* Maintain PCI compliance by leveraging PayPal's secure vault system.

## Prerequisites

Before implementing vaulted payments, obtain your credentials and enable vaulting features in the PayPal Developer Dashboard.

1. Log in to the [PayPal Developer Dashboard](https://developer.paypal.com/home/).
2. In the navigation menu, use the **Sandbox | Live** toggle to select **Live**.
3. Under **Apps & Credentials** > **REST API apps**, select your app name.
4. Under **API credentials**, obtain the **client ID** and **secret**.
5. To enable vaulting:
   * Go to **Features** > **Payment capabilities**.
   * Toggle on **Save payment methods**.
6. To enable PayPal and Venmo vaulting:
   * Go to **Features** > **Payment methods**.
   * Toggle on **PayPal and Venmo**.

### Set up your environment variables

In your project root, create a `.env` file and add your PayPal credentials:

```bash theme={null}
PAYPAL_SANDBOX_CLIENT_ID=your_client_id
PAYPAL_SANDBOX_CLIENT_SECRET=your_client_secret
```

<Warning>PayPal requires Risk Data Acquisition (RDA) to reduce fraud. You must implement risk data collection for all customer-initiated transactions (CIT) that use PayPal and Venmo Payment Tokens. Payment attempts that are missing RDA data are likely to be declined due to insufficient risk identifiers. Use the PayPal [FraudNet](https://developer.paypal.com/docs/checkout/apm/pay-upon-invoice/fraudnet/) and [Magnes](https://developer.paypal.com/limited-release/magnes/) libraries to collect and pass RDA data during payment processing.</Warning>

## Key concepts

Setup token vs payment token:

* **Setup Token**: Temporary token used during the save payment flow
* **Payment Token**: Permanent token stored in PayPal's vault for future use
* **Conversion**: Setup tokens are converted to payment tokens after customer approval

Payment flows:

* **VAULT\_WITHOUT\_PAYMENT**: Save payment method without making a purchase
* **VAULT\_WITH\_PAYMENT**: Save payment method while making a purchase (not covered in this doc)

Usage patterns:

* **IMMEDIATE**: Token will be used right away
* **DEFERRED**: Token will be used at a future date

## Integration flow

The PayPal save payment integration follows a specific flow:

1. Initialize PayPal SDK with your browser-safe client token.
2. Check eligibility for save payment functionality.
3. Create save payment session using vault-specific session options.
4. Create setup token on your server.
5. Start save payment session to collect payment method.
6. Create payment token from vault setup token for future use.

## Set up your front end

Build an HTML page and a JavaScript file to set up your front end.

### Build an HTML page

Build an HTML page that loads the PayPal JavaScript SDK and renders the save payment button.

```html lines expandable theme={null}
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Save Payment - PayPal JavaScript SDK</title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <style>
      .buttons-container {
        display: flex;
        flex-direction: column;
        gap: 12px;
      }
    </style>
  </head>
  <body>
    <h1>Save Payment Integration</h1>

    <div class="buttons-container">
      <!-- PayPal save payment button, initially hidden -->
      <paypal-button id="paypal-button" hidden></paypal-button>
    </div>
    
    <script src="app.js"></script>

    <!-- Load PayPal SDK -->
    <script
      async
      src="https://www.sandbox.paypal.com/web-sdk/v6/core"
      onload="onPayPalWebSdkLoaded()"
    ></script>
  </body>
</html>
```

### Initialize the SDK to save payment methods

Initialize the SDK using a browser-safe client token, check eligibility for the vault flow, and render the save payment button if PayPal is eligible.

```javascript lines expandable theme={null}
async function onPayPalWebSdkLoaded() {
  try {
    // Get client token for authentication
    const clientToken = await getBrowserSafeClientToken();
    
    // Create PayPal SDK instance
    const sdkInstance = await window.paypal.createInstance({
      clientToken,
      components: ["paypal-payments"],
      pageType: "checkout",
    });

    // Check eligibility for save payment with vault flow
    const paymentMethods = await sdkInstance.findEligibleMethods({
      currencyCode: "USD",
      paymentFlow: "VAULT_WITHOUT_PAYMENT", // Specify vault flow without payment
    });

    // Set up save payment button if eligible
    if (paymentMethods.isEligible("paypal")) {
      configurePayPalButton(sdkInstance);
    } else {
      console.log("PayPal save payment is not eligible for this session");
    }
  } catch (error) {
    console.error(error);
  }
}

async function getBrowserSafeClientToken() {
  const response = await fetch("/paypal-api/auth/browser-safe-client-token", {
    method: "GET",
    headers: {
      "Content-Type": "application/json",
    },
  });
  const { accessToken } = await response.json();
  return accessToken;
}
```

### Configure the payment session

Define the session callbacks that handle approval, cancellation, and errors during the save payment flow.

```javascript lines expandable theme={null}
const paymentSessionOptions = {
  // Called when customer approves saving their payment method
  async onApprove(data) {
    console.log("Save payment approved:", data);
    
    try {
      // Create payment token from vault setup token and store payment token ID securely (server-side recommended)
      const createPaymentTokenResponse = await createPaymentToken(
        data.vaultSetupToken,
      );
      
      console.log("Payment token created:", createPaymentTokenResponse);
      
      // Handle successful save payment: show success message, etc.
    } catch (error) {
      console.error("Payment token creation failed:", error);
      // Show user-friendly error messages, optionally provide retry mechanism, etc.
    }
  },
  
  // Called when customer cancels the save payment flow
  onCancel(data) {
    console.log("Save payment cancelled:", data);
    // Show cancellation message, return user to appropriate flow, etc.
  },
  
  // Called when an error occurs during save payment
  onError(error) {
    console.error("Save payment error:", error);
  },
};

async function createPaymentToken(vaultSetupToken) {
  const response = await fetch("/paypal-api/vault/payment-token/create", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ vaultSetupToken }),
  });
  const data = await response.json();
  
  return data;
}
```

### Set up button to save payments

Create the save payment session and attach a click handler that starts the vault flow when the customer selects the PayPal button.

```javascript lines expandable theme={null}
async function configurePayPalButton(sdkInstance) {
  // Create PayPal save payment session
  const paypalPaymentSession = sdkInstance.createPayPalSavePaymentSession(
    paymentSessionOptions,
  );

  // Get reference to PayPal button
  const paypalButton = document.querySelector("#paypal-button");
  paypalButton.removeAttribute("hidden");

  // Add click handler to start save payment flow
  paypalButton.addEventListener("click", async () => {
    try {
      // Get the promise reference by invoking createVaultSetupToken()
      // Do not await this async function - it can cause transient activation issues
      // Read about transient activation at https://developer.mozilla.org/en-US/docs/Glossary/Transient_activation
      const createVaultSetupTokenPromise = createVaultSetupToken();

      // Start the save payment session
      await paypalPaymentSession.start(
        { 
          presentationMode: "auto" // Auto-detects best presentation mode
        },
        createVaultSetupTokenPromise
      );
    } catch (error) {
      console.error("Save payment start error:", error);
    }
  });
}

async function createVaultSetupToken() {
  const response = await fetch("/paypal-api/vault/setup-token/create", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
  });
  const { id } = await response.json();
  
  return { setupToken: id };
}
```

## Set up your backend

PayPal APIs can either be called directly, or by using the [PayPal TypeScript Server SDK](https://github.com/paypal/PayPal-TypeScript-Server-SDK). The following examples use the `@paypal/paypal-server-sdk` npm package.

### Set up the PayPal TypeScript Server SDK

**Step 1:** Install the package.

```javascript theme={null}
npm install @paypal/paypal-server-sdk
```

**Step 2:** Create and initialize the client and controllers using the **client ID** and **secret** you set in your environment variables.

```typescript lines expandable theme={null}
import {
  ApiError,
  Client,
  CustomError,
  Environment,
  OAuthAuthorizationController,
  PaypalPaymentTokenUsageType,
  VaultController,
  VaultInstructionAction,
  VaultTokenRequestType
} from '@paypal/paypal-server-sdk';

import type {
  OAuthProviderError,
  PaymentTokenResponse,
  SetupTokenRequest
} from "@paypal/paypal-server-sdk";

const client = new Client({
  clientCredentialsAuthCredentials: {
    oAuthClientId: PAYPAL_SANDBOX_CLIENT_ID,
    oAuthClientSecret: PAYPAL_SANDBOX_CLIENT_SECRET
  },
  environment: Environment.Sandbox, // Use Environment.Production for live
});

const oAuthAuthorizationController = new OAuthAuthorizationController(client);
const vaultController = new VaultController(client);
```

### Client token endpoint

Create a server-side endpoint that generates a browser-safe client token for authenticating the front end with the PayPal SDK.

```typescript lines expandable theme={null}
app.get(
  "/paypal-api/auth/browser-safe-client-token",
  async (_req: Request, res: Response) => {
    try {
      const { jsonResponse, httpStatusCode } =
        await getBrowserSafeClientToken();
      res.status(httpStatusCode).json(jsonResponse);
    } catch (error) {
      console.error("Failed to create browser safe access token:", error);
      res
        .status(500)
        .json({ error: "Failed to create browser safe access token." });
    }
  },
);

export async function getBrowserSafeClientToken() {
  try {
    const auth = Buffer.from(
      `${PAYPAL_SANDBOX_CLIENT_ID}:${PAYPAL_SANDBOX_CLIENT_SECRET}`,
    ).toString("base64");

    const fieldParameters = {
      response_type: "client_token",
    };

    const { result, statusCode } =
      await oAuthAuthorizationController.requestToken(
        {
          authorization: `Basic ${auth}`,
        },
        fieldParameters,
      );

    // this interface is specific to the "client_token" response type
    interface ClientToken {
      accessToken: string;
      expiresIn: number;
      scope: string;
      tokenType: string;
    }

    const { accessToken, expiresIn, scope, tokenType } = result;
    const transformedResult: ClientToken = {
      accessToken,
      // expiresIn is a BigInt and must be converted to a Number
      expiresIn: Number(expiresIn),
      scope: String(scope),
      tokenType,
    };

    return {
      jsonResponse: transformedResult,
      httpStatusCode: statusCode,
    };
  } catch (error) {
    if (error instanceof ApiError) {
      const { result, statusCode } = error;
      type OAuthError = {
        error: OAuthProviderError;
        error_description?: string;
      };
      return {
        jsonResponse: result as OAuthError,
        httpStatusCode: statusCode,
      };
    } else {
      throw error;
    }
  }
}
```

### Create setup token endpoint

Create a server-side endpoint that generates a setup token to start the customer-initiated vault flow.

<Warning>PayPal requires Risk Data Acquisition (RDA) to reduce fraud. You must implement risk data collection for all customer-initiated transactions (CIT) that use PayPal and Venmo Payment Tokens. Payment attempts that are missing RDA data are likely to be declined due to insufficient risk identifiers. Use the PayPal [FraudNet](https://developer.paypal.com/docs/checkout/apm/pay-upon-invoice/fraudnet/) and [Magnes](https://developer.paypal.com/limited-release/magnes/) libraries to collect and pass RDA data during payment processing.</Warning>

```typescript lines expandable theme={null}
app.post(
  "/paypal-api/vault/setup-token/create",
  async (_req: Request, res: Response) => {
    try {
      const { jsonResponse, httpStatusCode } =
        await createSetupTokenWithSampleDataForPayPal();
      res.status(httpStatusCode).json(jsonResponse);
    } catch (error) {
      console.error("Failed to create setup token:", error);
      res.status(500).json({ error: "Failed to create setup token." });
    }
  },
);

export async function createSetupTokenWithSampleDataForPayPal() {
  const defaultSetupTokenRequestBody = {
    paymentSource: {
      paypal: {
        experienceContext: {
          cancelUrl: "https://example.com/cancelUrl",
          returnUrl: "https://example.com/returnUrl",
          vaultInstruction: VaultInstructionAction.OnPayerApproval,
        },
        usageType: PaypalPaymentTokenUsageType.Merchant,
      },
    },
  };

  return createSetupToken(defaultSetupTokenRequestBody, Date.now().toString());
}

export async function createSetupToken(
  setupTokenRequestBody: SetupTokenRequest,
  paypalRequestId?: string,
) {
  try {
    const { result, statusCode } = await vaultController.createSetupToken({
      body: setupTokenRequestBody,
      paypalRequestId,
    });

    return {
      jsonResponse: result,
      httpStatusCode: statusCode,
    };
  } catch (error) {
    if (error instanceof ApiError) {
      const { result, statusCode } = error;

      return {
        jsonResponse: result as CustomError,
        httpStatusCode: statusCode,
      };
    } else {
      throw error;
    }
  }
}
```

### Create payment token endpoint

Payment tokens are long-lived values for making future payments. PayPal recommends storing them in your database. Do not pass them to the browser.

```typescript lines expandable theme={null}
app.post(
  "/paypal-api/vault/payment-token/create",
  async (req: Request, res: Response) => {
    try {
      const { jsonResponse, httpStatusCode } = await createPaymentToken(
        req.body.vaultSetupToken as string,
      );

      const paymentTokenResponse = jsonResponse as PaymentTokenResponse;

      if (paymentTokenResponse.id) {
        // This payment token id is a long-lived value for making future payments.
        // PayPal recommends storing this value in your database
        // and NOT returning it back to the browser.
        await savePaymentTokenToDatabase(paymentTokenResponse);
        res.status(httpStatusCode).json({
          status: "SUCCESS",
          description:
            "Payment token saved to database for future transactions",
        });
      } else {
        res.status(httpStatusCode).json({
          status: "ERROR",
          description: "Failed to create payment token",
        });
      }
    } catch (error) {
      console.error("Failed to create payment token:", error);
      res.status(500).json({ error: "Failed to create payment token." });
    }
  },
);

export async function createPaymentToken(
  vaultSetupToken: string,
  paypalRequestId?: string,
) {
  try {
    const { result, statusCode } = await vaultController.createPaymentToken({
      paypalRequestId: paypalRequestId ?? Date.now().toString(),
      body: {
        paymentSource: {
          token: {
            id: vaultSetupToken,
            type: VaultTokenRequestType.SetupToken,
          },
        },
      },
    });

    return {
      jsonResponse: result,
      httpStatusCode: statusCode,
    };
  } catch (error) {
    if (error instanceof ApiError) {
      const { result, statusCode } = error;

      return {
        jsonResponse: result as CustomError,
        httpStatusCode: statusCode,
      };
    } else {
      throw error;
    }
  }
}

async function savePaymentTokenToDatabase(
  paymentTokenResponse: PaymentTokenResponse,
) {
  // example function to teach saving the paymentToken to a database
  // to be used for future transactions
  return Promise.resolve();
}
```

## Advanced features

The following code sample demonstrates how to configure a custom setup token.

### Configure custom setup token

Use a custom setup token to pass additional payer and merchant configuration to the vault flow.

```javascript lines expandable theme={null}
async function createCustomSetupToken(customerInfo = {}) {
  const customSetupTokenRequestBody = {
    payment_source: {
      paypal: {
        description: customerInfo.description || "Save PayPal payment method",
        usagePattern: customerInfo.usagePattern || "IMMEDIATE",
        usageType: customerInfo.usageType || "MERCHANT",
        customerType: customerInfo.customerType || "CONSUMER",
        permitMultiplePaymentTokens: customerInfo.allowMultiple || false,
      }
    },
    // Optional: Add customer information
    ...(customerInfo.customerId && {
      customer: {
        id: customerInfo.customerId
      }
    })
  };

  const response = await fetch("/paypal-api/vault/setup-token/create", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    // set up endpoint to parse request body
    body: JSON.stringify(customSetupTokenRequestBody),
  });

  const { id } = await response.json();
  return { setupToken: id };
}
```

## Resources

* [PayPal Payment Method Tokens (vault) API reference](https://developer.paypal.com/docs/api/payment-tokens/v3/)
* [PayPal Developer Dashboard](https://developer.paypal.com/dashboard/)
* [PCI Compliance Guidelines](https://www.pcisecuritystandards.org/)

## Support

For additional support and questions:

* Visit [PayPal Developer Community](https://developer.paypal.com/community/)
* Check [PayPal Developer Documentation](https://developer.paypal.com/docs/)
* Review the complete implementation:
  * [Client code](https://github.com/paypal-examples/v6-web-sdk-sample-integration/tree/main/client/components/paypalPayments/savePayment/html)
  * [Server code](https://github.com/paypal-examples/v6-web-sdk-sample-integration/tree/main/server/node)


# Save PayPal with purchase with the JavaScript SDK
Source: https://docs.paypal.ai/payments/save/sdk/paypal/js-sdk-v6-vault-w-purchase



Use the PayPal JavaScript SDK v6 to save a buyer's PayPal information when they complete a one-time payment. PayPal stores the buyer's information in a secure data store called a vault. When a returning buyer selects PayPal at checkout, they can pay with their saved account without re-entering credentials or payment details.

With this integration, you can:

* Collect and securely store a buyer's PayPal account at checkout
* Retrieve a vault token after a successful capture
* Use `clientId` authentication (the standard path for saving to the vault)

## Prerequisites

To save PayPal accounts with a one-time purchase, you need:

* Complete the steps in [get started](/developer/how-to/api/get-started) to get:
  * An app in the PayPal Developer Dashboard with **Save payment methods** enabled
  * A client ID
  * A client secret
* A server-side environment that can make HTTPS requests to the PayPal API

## Key concepts

The following concepts are central to the vault-with-purchase flow.

### Use `clientId`

The PayPal JavaScript SDK v6 initializes with your `clientId`. Your `clientId` is safe to expose in the browser and is the standard authentication path for PayPal one-time payments, vaulting, and return-buyer flows. Only [Fastlane](https://developer.paypal.com/studio/checkout/fastlane) integrations require the alternate [`clientToken` authentication path](https://developer.paypal.com/studio/checkout/fastlane/integrate#generate-client-token).

### Vault attributes

Use the following vault attributes to support saving PayPal accounts with a purchase:

* `store_in_vault: "ON_SUCCESS"` saves the payment method when the order is successfully captured.
* `usage_type: "MERCHANT"` indicates that the merchant manages the vault.
* `customer_type: "CONSUMER"` identifies the buyer as a consumer to present a consumer vaulting experience.

### Vault token

After a successful capture, retrieve the vault token ID by calling `GET /v2/checkout/orders/:id`. Link the token at `payment_source.paypal.attributes.vault.id` to the customer ID and store it on your server side for future use.

## Integration flow

The following steps describe the end-to-end vault-with-purchase flow.

1. The page loads, and the SDK script fires [`onPayPalWebSdkLoaded()`](#load-the-sdk).
2. The SDK [initializes with `createInstance({ clientId })`](#initialize-the-sdk).
3. The buyer selects the PayPal button, which calls [`session.start()`](#create-a-payment-session).
4. The client calls `POST /api/orders` with [`paymentMethod: "paypal"`](#create-an-order-client).
5. The server [creates the order with `store_in_vault: "ON_SUCCESS"`](#create-an-order-with-vault-attributes) in the PayPal payment source.
6. The buyer authenticates in the PayPal window.
7. [`onApprove` fires](#create-a-payment-session), and the client calls [`POST /api/orders/:id/capture`](#capture-the-order).
8. The client calls [`GET /api/orders/:id`](#retrieve-the-vault-token) and retrieves the vault token.

## Set up your front end

To set up the front end:

* [Load the SDK](#load-the-sdk)
* [Add a PayPal button](#add-the-button-element-to-the-page) to your page
* [Initialize an SDK instance](#initialize-the-sdk) with your `clientId`
* [Create a payment session](#create-a-payment-session) that supports saving the buyer's PayPal information with the purchase
* [Create a client-side order helper](#create-an-order-client) that communicates with your [back end](#set-up-your-back-end)

### Load the SDK

Add the SDK script tag to your page. The `onload` callback fires when the script is ready.

```html lines theme={null}
<!-- Sandbox -->
<script
  async
  src="https://www.sandbox.paypal.com/web-sdk/v6/core"
  onload="onPayPalWebSdkLoaded()">
</script>
```

```html lines theme={null}
<!-- Production -->
<script
  async
  src="https://www.paypal.com/web-sdk/v6/core"
  onload="onPayPalWebSdkLoaded()">
</script>
```

### Add the button element to the page

Place the custom element where you want the button to render:

```html theme={null}
<paypal-button id="paypal-button" type="pay"></paypal-button>
```

### Initialize the SDK

After the SDK loads, use your `clientId` to create an instance and register the PayPal payments component.

```javascript lines theme={null}
async function onPayPalWebSdkLoaded() {
  const sdkInstance = await window.paypal.createInstance({
    clientId: "YOUR_CLIENT_ID",
    components: ["paypal-payments"],
    pageType: "checkout",
  });

  await setupPayPalButton(sdkInstance);
}
```

### Create a payment session

Set up a one-time payment session that includes vault support. The `onApprove` callback captures the order and retrieves the vault token.

The SDK uses `presentationMode: "auto"` to determine whether to use a popup or redirect to display the payment interface based on the buyer's device and browser.

```javascript lines expandable theme={null}
async function setupPayPalButton(sdkInstance) {
  const session = sdkInstance.createPayPalOneTimePaymentSession({
    onApprove: async ({ orderId }) => {
      // Capture the approved order
      await fetch(`/api/orders/${orderId}/capture`, { method: "POST" });

      // GET the order to surface the vault token
      const orderRes = await fetch(`/api/orders/${orderId}`);
      const { response: order } = await orderRes.json();

      const vaultToken = order?.payment_source?.paypal?.attributes?.vault?.id;
      console.log("Vault token:", vaultToken);
      // Store vaultToken server-side linked to the customer ID
    },
    onCancel: ({ orderId }) => {
      console.log("Buyer cancelled:", orderId);
    },
    onError: (err) => {
      console.error("PayPal error:", err.code, err.message);
    },
  });

  document.getElementById("paypal-button").addEventListener("click", async () => {
    await session.start(
      { presentationMode: "auto" },
      createOrder("paypal")
    );
  });
}
```

### Create an order (client)

This helper calls your server to create an order and returns the `orderId` for the SDK to start the checkout flow.

```javascript lines expandable theme={null}
async function createOrder(paymentMethod) {
  const res = await fetch("/api/orders", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ paymentMethod }),
  });
  const data = await res.json();
  if (!data.id) throw new Error("Order creation failed");
  return { orderId: data.id };
}
```

## Set up your back end

Your server handles authentication, order creation with [vault attributes](#vault-attributes), order capture, and vault token retrieval.

### Environment variables

Paste the following variables in an environment (`.env`) file in your project root. Replace `your_client_id` and `your_client_secret` with your app's client ID and client secret.

```bash lines theme={null}
PAYPAL_CLIENT_ID=your_client_id
PAYPAL_CLIENT_SECRET=your_client_secret
PORT=3000
```

### Server setup

Set up an [Express](https://expressjs.com/) server with JSON parsing and static file serving.

```javascript lines expandable theme={null}
const express = require("express");
const path = require("path");
require("dotenv").config();

const app = express();
app.use(express.json());
app.use(express.static(path.join(__dirname, "public")));

// ... route handlers below ...

app.listen(process.env.PORT || 3000, () => {
  console.log(`Server running on port ${process.env.PORT || 3000}`);
});
```

### Get an access token

The order and capture endpoints need a server-side access token. This helper fetches one from the OAuth endpoint:

```javascript lines expandable theme={null}
async function getAccessToken() {
  const credentials = Buffer.from(
    `${process.env.PAYPAL_CLIENT_ID}:${process.env.PAYPAL_CLIENT_SECRET}`
  ).toString("base64");

  const tokenRes = await fetch("https://api-m.sandbox.paypal.com/v1/oauth2/token", {
    method: "POST",
    headers: {
      Authorization: `Basic ${credentials}`,
      "Content-Type": "application/x-www-form-urlencoded",
    },
    body: "grant_type=client_credentials",
  });

  const { access_token } = await tokenRes.json();
  return access_token;
}
```

### Create an order with vault attributes

This endpoint creates an order with `store_in_vault: "ON_SUCCESS"` in the PayPal payment source, which tells the system to save the buyer's payment method to the vault after a successful capture.

```javascript lines expandable theme={null}
app.post("/api/orders", async (req, res) => {
  const { paymentMethod } = req.body;
  const origin = req.headers.origin ?? `http://${req.headers.host}`;
  const accessToken = await getAccessToken();

  const orderRes = await fetch("https://api-m.sandbox.paypal.com/v2/checkout/orders", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      intent: "CAPTURE",
      payment_source: {
        paypal: {
          experience_context: {
            return_url: `${origin}/`,
            cancel_url: `${origin}/`,
            shipping_preference: "GET_FROM_FILE",
            user_action: "CONTINUE",
          },
          attributes: {
            vault: {
              store_in_vault: "ON_SUCCESS",
              usage_type: "MERCHANT",
              customer_type: "CONSUMER",
            },
          },
        },
      },
      purchase_units: [{
        amount: {
          currency_code: "USD",
          value: "100.00",
        },
      }],
    }),
  });

  const order = await orderRes.json();
  res.json({ id: order.id });
});
```

### Capture the order

After the buyer approves payment, call the Orders API to capture the funds.

```javascript lines expandable theme={null}
app.post("/api/orders/:orderID/capture", async (req, res) => {
  const accessToken = await getAccessToken();

  const captureRes = await fetch(
    `https://api-m.sandbox.paypal.com/v2/checkout/orders/${req.params.orderID}/capture`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "Content-Type": "application/json",
      },
    }
  );

  res.json(await captureRes.json());
});
```

### Retrieve the vault token

Fetch the completed order to extract the vault token from the response. The token is at `payment_source.paypal.attributes.vault.id`. When you have the token, store it in your database, linked to the customer's account. After you do that, returning customers can check out without re-entering payment details.

```javascript lines expandable theme={null}
app.get("/api/orders/:orderID", async (req, res) => {
  const accessToken = await getAccessToken();

  const orderRes = await fetch(
    `https://api-m.sandbox.paypal.com/v2/checkout/orders/${req.params.orderID}`,
    { headers: { Authorization: `Bearer ${accessToken}` } }
  );

  const order = await orderRes.json();
  // Vault token at: order.payment_source.paypal.attributes.vault.id
  res.json({ response: order });
});
```

## Troubleshooting

Use this section to diagnose errors in the vault-with-purchase flow.

### `onPayPalWebSdkLoaded` doesn't fire

* **Cause:** The script tag doesn't include the `onload` attribute, or the script URL points to the wrong environment, for example, sandbox instead of production.
* **Fix:** Add `onload="onPayPalWebSdkLoaded()"` to the script tag. Use `sandbox.paypal.com` for testing. Remove the `sandbox.` subdomain for the production environment.

### `createInstance` throws or returns an error

* **Cause:** The `clientId` doesn't match the app, the app doesn't have **Save payment methods** enabled, or the `components` array doesn't include `"paypal-payments"`.
* **Fix:** Verify that the `clientId` matches the app in the PayPal Developer Dashboard. Verify the toggle is set to **Save payment methods** on under the app's features. Include `components: ["paypal-payments"]` in the `createInstance` call.

### The popup is blocked

* **Cause:** Your code calls `session.start()`, but the user has not selected a payment method. Browsers block popups that don't originate from a user action.
* **Fix:** Call `session.start()` inside the button's `click` event listener without any `await` calls before it. Move async work, such as order creation, into the `createOrder` callback that `session.start()` accepts as its second argument.

### `onApprove` fires with missing vault token

* **Cause:** Your server created the order without `store_in_vault: "ON_SUCCESS"` in the payment source, or the capture failed before vaulting could complete.
* **Fix:** Confirm that the server-side order body includes the full `attributes.vault` block. Check the capture response for errors before calling `GET /api/orders/:id`. The vault token appears after a successful capture.

### Order creation returns a 401 or 403

* **Cause:** The server-side access token expired, the credentials are wrong, or your server fetched the token from the wrong environment endpoint.
* **Fix:** Confirm `PAYPAL_CLIENT_ID` and `PAYPAL_CLIENT_SECRET` match the app in the Developer Dashboard. For testing, fetch the token from `api-m.sandbox.paypal.com`. Remove the `sandbox.` subdomain for the production environment.

## Related content

* [Orders v2 API](/api/payment-tokens/v3/customer-payment-tokens-get)
* [Payment Method Tokens v3 API](https://developer.paypal.com/docs/api/payment-tokens/v3/)
* [PayPal JavaScript SDK v6](/reference/sdk/js/v6/reference)


# Save Venmo with purchase with the JavaScript SDK
Source: https://docs.paypal.ai/payments/save/sdk/venmo/js-sdk-v6-vault-w-purchase



Use the PayPal JavaScript SDK v6 to save a buyer's Venmo information when they complete a one-time payment. PayPal stores the buyer's information in a secure data store called a vault. When a returning buyer selects Venmo at checkout, they can pay with their saved account without re-entering credentials or payment details.

With this integration you can:

* Collect and securely store a buyer's Venmo account at checkout
* Retrieve a vault token after a successful capture
* Use `clientId` authentication (the standard path for saving to the vault)

## Prerequisites

To save Venmo accounts with a one-time purchase, you need:

* Complete the steps in [get started](/developer/how-to/api/get-started) to get:
  * An app in the PayPal Developer Dashboard with **Save payment methods** enabled
  * A client ID
  * A client secret
  * Sandbox Venmo buyer and seller accounts
* A server-side environment that can make HTTPS requests to the PayPal API

## Key concepts

The following concepts are central to the vault-with-purchase flow.

### Use `clientId`

The PayPal JavaScript SDK v6 initializes with your `clientId`. Your `clientId` is safe to expose in the browser and is the standard authentication path for Venmo one-time payments, vaulting, and return-buyer flows. Only [Fastlane](https://developer.paypal.com/studio/checkout/fastlane) integrations require the alternate [`clientToken` authentication path](https://developer.paypal.com/studio/checkout/fastlane/integrate#generate-client-token).

### Vault attributes

Use the following vault attributes to support saving Venmo accounts with a purchase:

* `store_in_vault: "ON_SUCCESS"` saves the payment method when the order is successfully captured.
* `usage_type: "MERCHANT"` indicates that the merchant manages the vault.
* `customer_type: "CONSUMER"` identifies the buyer as a consumer to present a consumer vaulting experience.
* `permit_multiple_payment_tokens: false` prevents creating duplicate vault tokens for the same Venmo account.

### Vault token

After a successful capture, retrieve the vault token ID by calling `GET /v2/checkout/orders/:id`. Link the token at `payment_source.venmo.attributes.vault.id` to the customer ID and store it on your server side for future use.

## Integration flow

The following steps describe the end-to-end vault-with-purchase flow.

1. The page loads, and the SDK script fires [`onPayPalWebSdkLoaded()`](#load-the-sdk).
2. The SDK [initializes with `createInstance({ clientId })`](#initialize-the-sdk).
3. The buyer selects the Venmo button, which calls [`session.start()`](#create-a-payment-session).
4. The client calls `POST /api/orders` with [`paymentMethod: "venmo"`](#create-an-order-client).
5. The server [creates the order with `store_in_vault: "ON_SUCCESS"`](#create-an-order-with-vault-attributes) in the Venmo payment source.
6. The buyer authenticates in the Venmo app.
7. [`onApprove` fires](#create-a-payment-session), and the client calls [`POST /api/orders/:id/capture`](#capture-the-order).
8. The client calls [`GET /api/orders/:id`](#retrieve-the-vault-token) and retrieves the vault token.

## Set up your front end

To set up the front end:

* [Load the SDK](#load-the-sdk)
* [Add a Venmo button](#add-the-button-element-to-the-page) to your page
* [Initialize an SDK instance](#initialize-the-sdk) with your `clientId`
* [Create a payment session](#create-a-payment-session) that supports saving the buyer's Venmo information with the purchase
* [Create a client-side order helper](#create-an-order-client) that communicates with your [back end](#set-up-your-back-end)

### Load the SDK

Add the SDK script tag to your page. The `onload` callback fires when the script is ready.

```html lines theme={null}
<!-- Sandbox -->
<script
  async
  src="https://www.sandbox.paypal.com/web-sdk/v6/core"
  onload="onPayPalWebSdkLoaded()">
</script>
```

```html lines theme={null}
<!-- Production -->
<script
  async
  src="https://www.paypal.com/web-sdk/v6/core"
  onload="onPayPalWebSdkLoaded()">
</script>
```

### Add the button element to the page

Place the custom element where you want the button to render:

```html theme={null}
<venmo-button id="venmo-button" type="pay"></venmo-button>
```

### Initialize the SDK

After the SDK loads, use your `clientId` to create an instance and register the Venmo payments component.

```javascript lines theme={null}
async function onPayPalWebSdkLoaded() {
  const sdkInstance = await window.paypal.createInstance({
    clientId: "YOUR_CLIENT_ID",
    components: ["venmo-payments"],
    pageType: "checkout",
  });

  await setupVenmoButton(sdkInstance);
}
```

### Create a payment session

Set up a one-time payment session that includes vault support. The `onApprove` callback captures the order and retrieves the vault token.

The SDK uses `presentationMode: "auto"` to determine whether to use a popup or redirect to display the payment interface based on the buyer's device and browser.

```javascript lines expandable theme={null}
async function setupVenmoButton(sdkInstance) {
  const session = sdkInstance.createVenmoOneTimePaymentSession({
    onApprove: async ({ orderId }) => {
      // Capture the approved order
      await fetch(`/api/orders/${orderId}/capture`, { method: "POST" });

      // GET the order to surface the vault token
      const orderRes = await fetch(`/api/orders/${orderId}`);
      const { response: order } = await orderRes.json();

      const vaultToken = order?.payment_source?.venmo?.attributes?.vault?.id;
      console.log("Vault token:", vaultToken);
      // Store vaultToken server-side linked to the customer ID
    },
    onCancel: ({ orderId }) => {
      console.log("Buyer cancelled:", orderId);
    },
    onError: (err) => {
      console.error("Venmo error:", err.code, err.message);
    },
  });

  document.getElementById("venmo-button").addEventListener("click", async () => {
    await session.start(
      {
        presentationMode: "auto",
      },
      createOrder("venmo")
    );
  });
}
```

### Create an order (client)

This helper calls your server to create an order and returns the `orderId` for the SDK to start the checkout flow.

```javascript lines expandable theme={null}
async function createOrder(paymentMethod) {
  const res = await fetch("/api/orders", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ paymentMethod }),
  });
  const data = await res.json();
  if (!data.id) throw new Error("Order creation failed");
  return { orderId: data.id };
}
```

## Set up your back end

Your server handles authentication, order creation with [vault attributes](#vault-attributes), order capture, and vault token retrieval.

### Environment variables

Paste the following variables in an environment (`.env`) file in your project root. Replace `your_client_id` and `your_client_secret` with your app's client ID and client secret.

```bash lines theme={null}
PAYPAL_CLIENT_ID=your_client_id
PAYPAL_CLIENT_SECRET=your_client_secret
PORT=3000
```

### Server setup

Set up an [Express](https://expressjs.com/) server with JSON parsing and static file serving.

```javascript lines expandable theme={null}
const express = require("express");
const path = require("path");
require("dotenv").config();

const app = express();
app.use(express.json());
app.use(express.static(path.join(__dirname, "public")));

// ... route handlers below ...

app.listen(process.env.PORT || 3000, () => {
  console.log(`Server running on port ${process.env.PORT || 3000}`);
});
```

### Get an access token

The order and capture endpoints need a server-side access token. This helper fetches one from the OAuth endpoint:

```javascript lines expandable theme={null}
async function getAccessToken() {
  const credentials = Buffer.from(
    `${process.env.PAYPAL_CLIENT_ID}:${process.env.PAYPAL_CLIENT_SECRET}`
  ).toString("base64");

  const tokenRes = await fetch("https://api-m.sandbox.paypal.com/v1/oauth2/token", {
    method: "POST",
    headers: {
      Authorization: `Basic ${credentials}`,
      "Content-Type": "application/x-www-form-urlencoded",
    },
    body: "grant_type=client_credentials",
  });

  const { access_token } = await tokenRes.json();
  return access_token;
}
```

### Create an order with vault attributes

This endpoint creates an order with `store_in_vault: "ON_SUCCESS"` in the Venmo payment source, which tells the system to save the buyer's payment method to the vault after a successful capture. The `permit_multiple_payment_tokens: false` attribute prevents creating duplicate vault tokens when the same Venmo account is used across multiple sessions.

```javascript lines expandable theme={null}
app.post("/api/orders", async (req, res) => {
  const { paymentMethod } = req.body;
  const origin = req.headers.origin ?? `http://${req.headers.host}`;
  const accessToken = await getAccessToken();

  const orderRes = await fetch("https://api-m.sandbox.paypal.com/v2/checkout/orders", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      intent: "CAPTURE",
      payment_source: {
        venmo: {
          experience_context: {
            return_url: `${origin}/`,
            cancel_url: `${origin}/`,
            shipping_preference: "GET_FROM_FILE",
            user_action: "CONTINUE",
          },
          attributes: {
            vault: {
              store_in_vault: "ON_SUCCESS",
              usage_type: "MERCHANT",
              customer_type: "CONSUMER",
              permit_multiple_payment_tokens: false,
            },
          },
        },
      },
      purchase_units: [{
        amount: {
          currency_code: "USD",
          value: "100.00",
        },
      }],
    }),
  });

  const order = await orderRes.json();
  res.json({ id: order.id });
});
```

### Capture the order

After the buyer approves payment, call the Orders API to capture the funds.

```javascript lines expandable theme={null}
app.post("/api/orders/:orderID/capture", async (req, res) => {
  const accessToken = await getAccessToken();

  const captureRes = await fetch(
    `https://api-m.sandbox.paypal.com/v2/checkout/orders/${req.params.orderID}/capture`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "Content-Type": "application/json",
      },
    }
  );

  res.json(await captureRes.json());
});
```

### Retrieve the vault token

Fetch the completed order to extract the vault token from the response. The token is at `payment_source.venmo.attributes.vault.id`. When you have the token, store it in your database, linked to the customer's account. After you do that, returning customers can check out without re-entering payment details.

```javascript lines expandable theme={null}
app.get("/api/orders/:orderID", async (req, res) => {
  const accessToken = await getAccessToken();

  const orderRes = await fetch(
    `https://api-m.sandbox.paypal.com/v2/checkout/orders/${req.params.orderID}`,
    { headers: { Authorization: `Bearer ${accessToken}` } }
  );

  const order = await orderRes.json();
  // Vault token at: order.payment_source.venmo.attributes.vault.id
  res.json({ response: order });
});
```

## Troubleshooting

Use this section to diagnose errors in the vault-with-purchase flow.

### `onPayPalWebSdkLoaded` doesn't fire

* **Cause:** The script tag doesn't include the `onload` attribute, or the script URL points to the wrong environment, for example, sandbox instead of production.
* **Fix:** Add `onload="onPayPalWebSdkLoaded()"` to the script tag. Use `sandbox.paypal.com` for testing. Remove the `sandbox.` subdomain for the production environment.

### `createInstance` throws or returns an error

* **Cause:** The `clientId` doesn't match the app, the app doesn't have **Save payment methods** enabled, or the `components` array doesn't include `"venmo-payments"`.
* **Fix:** Verify that the `clientId` matches the app in the PayPal Developer Dashboard. Verify the toggle is set to **Save payment methods** on under the app's features. Include `components: ["venmo-payments"]` in the `createInstance` call.

### The popup is blocked

* **Cause:** Your code calls `session.start()`, but the user has not selected a payment method. Browsers block popups that don't originate from a user action.
* **Fix:** Call `session.start()` inside the button's `click` event listener without any `await` calls before it. Move async work, such as order creation, into the `createOrder` callback that `session.start()` accepts as its second argument.

### `onApprove` fires with missing vault token

* **Cause:** Your server created the order without `store_in_vault: "ON_SUCCESS"` in the payment source, or the capture failed before vaulting could complete.
* **Fix:** Confirm that the server-side order body includes the full `attributes.vault` block. Check the capture response for errors before calling `GET /api/orders/:id`. The vault token appears after a successful capture.

### Order creation returns a 401 or 403

* **Cause:** The server-side access token expired, the credentials are wrong, or your server fetched the token from the wrong environment endpoint.
* **Fix:** Confirm `PAYPAL_CLIENT_ID` and `PAYPAL_CLIENT_SECRET` match the app in the Developer Dashboard. For testing, fetch the token from `api-m.sandbox.paypal.com`. Remove the `sandbox.` subdomain for the production environment.

## Related content

* [Orders v2 API](/api/payment-tokens/v3/customer-payment-tokens-get)
* [Payment Method Tokens v3 API](https://developer.paypal.com/docs/api/payment-tokens/v3/)
* [PayPal JavaScript SDK v6](/reference/sdk/js/v6/reference)


# Share a payment link
Source: https://docs.paypal.ai/payments/share-pay-links



Share a payment link with customers through email, text message, social media, or your website. When customers open the link, they are directed to the PayPal payment page where they can complete their payment.

## Prerequisites

* PayPal Business Account
* (Optional) PayPal sandbox account to test the payment link before using it in production

## Share a payment link

1. Log in to your [PayPal Business Account](https://www.paypal.com/business/open-business-account?_ga=2.49411041.673139926.1760916697-1259758161.1760473483).
2. From the left navigation, select **Sales** > **Payment Links and Buttons**.
3. Locate the payment link you want to share and select **Open**.
4. Select **View** > **Payment Link**, then copy the link to share with customers.

## Generate QR code

Customers can scan a QR code to open the same payment page as your payment link.

1. Log in to your PayPal Business Account.
2. From the left navigation, select **Sales** > **Payment Links and Buttons**.
3. Locate the payment link you want to share and select **Open**.
4. Select the **QR code** > **Download QR code** to share the QR code with customers for in-person or offline payments.

The QR code does not expire. If you delete the payment link, customers who scan the code are redirected to an expiration page.

## Test your payment link or QR code

Test your payment link or QR code by following these steps before sharing it with customers:

1. Open the payment link or scan the QR code to confirm the the correct product name, price, and payment options appear.
2. Complete a test payment:
   * Use a low-value transaction if testing in live mode.
   * Use a sandbox buyer account if testing in sandbox.
3. Confirm the payment completes successfully and appears in your Dashboard activity.
4. If **Auto-return** is set, confirm customers are redirected to the correct URL.

## Common issues

**Customer cannot see all payment methods**

* Payment method availability depends on the customer's country and eligibility. Not all payment methods appear for every buyer.


# Troubleshooting
Source: https://docs.paypal.ai/payments/troubleshooting



Use this guide to identify and fix common issues that prevent Payment Links and Buttons from displaying or working as expected.

## Issues with account eligibility and access

Review the following solutions if you cannot access Payment Links and Buttons or if customers experience problems completing payments.

### Payment Links and Buttons are missing from my account

Payment Links and Buttons are available only for Business accounts. To access this feature, upgrade your existing account or create a new [Business account](https://www.paypal.com/webapps/mpp/account-selection).

### Customer cannot see all payment methods

Payment method availability depends on the customer's country and eligibility. Not all payment methods appear for every buyer.

### Payment Links and Buttons are not working

Account restrictions can prevent customers from completing payments. Common symptoms include a generic "something went wrong" message or a `payment_denied` error.

To resolve this:

1. Log in to your PayPal account and check for any notifications or required action items.
2. Contact PayPal support to identify and resolve the specific restriction on your account.

## Issues with button display

Review the following solutions if a button does not appear on your page or shows an error in the browser console.

### Button does not appear on my page

The button might not display if your site cannot load required PayPal resources because of your Content Security Policy (CSP) or connectivity issues.

#### Check basic connectivity

* Make sure your internet connection works by loading a few other websites.
* Open other pages on your site, and confirm that they load as expected.

#### Confirm the button exists in your PayPal account

1. Sign in to your [PayPal Business account](https://www.paypal.com/business/open-business-account?_ga=2.49411041.673139926.1760916697-1259758161.1760473483).
2. In the left navigation, select **Pay & Get Paid** > **Create Payment Links and Buttons**.
3. Select **More actions** > **Saved links and buttons**.
4. In the list, find the button, and then select **Open** to expand options.
5. Select **View**, and verify that the button code in the UI matches the code you pasted into your page.\
   If the button still does not appear, continue with CSP checks in the next section.

### Button shows an error in the browser

The button can fail if your CSP blocks PayPal scripts, frames, images, or network calls.

#### Check the browser console for CSP errors

1. Open your product page where you pasted the button code.
2. Right-click the page, and then select **Inspect**.
3. Select the **Console** tab.
4. Look for CSP errors that mention PayPal domains or the PayPal JavaScript SDK, such as errors that refuse to load `https://www.paypal.com/sdk/js` or frame `https://www.paypal.com/`.
5. If you see these errors, update your CSP to allow the required PayPal domains.

#### Fix CSP defined in HTML

If you set your CSP in a `<meta>` tag in your HTML, replace your current CSP meta tag with this example so your page can load PayPal resources:

```html theme={null}
<meta http-equiv="Content-Security-Policy" content="default-src 'self';
script-src 'unsafe-inline' https://*.paypal.com https://*.paypalobjects.com;
style-src 'unsafe-inline' https://*.paypal.com;
connect-src https://*.paypal.com;
frame-src https://*.paypal.com;
img-src https://*.paypal.com https://*.paypalobjects.com">
```

This policy allows the PayPal JavaScript SDK, frames, images, and network calls, and restricts other sources to your own origin.

#### Fix CSP defined on the server

If you configure your CSP in HTTP response headers, update your headers to include PayPal as an allowed source. Use this example as a starting point and merge it into your existing CSP header:

```text theme={null}
Content-Security-Policy: default-src 'self';
script-src 'unsafe-inline' https://*.paypal.com https://*.paypalobjects.com;
style-src 'unsafe-inline' https://*.paypal.com;
connect-src https://*.paypal.com;
frame-src https://*.paypal.com;
img-src https://*.paypal.com https://*.paypalobjects.com;
```

After you update your CSP:

1. Reload your product page.
2. Open the console again, and confirm that CSP errors related to PayPal no longer appear.
3. Verify that the button now renders correctly.

### Some buttons do not display on my page

Conflicting IDs, currencies, or scripts can prevent buttons from rendering.

* Do not reuse the same button ID on a single page. If you paste the same button ID multiple times, only the first button renders.
* Do not mix buttons that use different currencies on the same page. If you use different button IDs with different currencies, only the first button renders.
* If you add several different button IDs and the page is slow or buttons do not appear, make sure you include the PayPal JavaScript SDK script with your client ID only once on the page. The script should look like this, with your own client ID and currency value:

```xml theme={null}
<script src="https://www.paypal.com/sdk/js?client-id=XYZ&components=hosted-buttons&enable-funding=venmo&currency=USD"></script>
```

## Issues at checkout

Review the following solutions if customers encounter unexpected behavior during the checkout process.

### Continue Shopping link appears on the payment page

To remove the **Continue Shopping** link, remove the Homepage URL from your Payment Link settings.

### Billing address country incorrectly set to US

When a customer selects the credit or debit card option, the billing address country defaults to US regardless of the customer's actual location. This happens because the billing address is determined by the buyer's browser locale settings.

The fix depends on the product you are using:

| Product               | Fix                                                                                                                                                       | Notes                                                                                                                                  |
| :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------- |
| Payment Links         | Append `locale.x` and `country.x` query parameters to the payment link URL: `https://www.paypal.com/ncp/payment/YOUR_LINK_ID?locale.x=en_CA&country.x=CA` | This fix applies to all buyers regardless of locale or country settings. A US buyer accessing this link is also treated as a CA buyer. |
| Buy Buttons           | Not currently supported                                                                                                                                   | —                                                                                                                                      |
| Shopping Cart Buttons | Not currently supported                                                                                                                                   | —                                                                                                                                      |

### Locale and language issues

The `LANG` cookie set during a buyer's previous PayPal.com visit takes priority over their browser locale preference, which can cause the checkout page to display in an unexpected language.

The fix depends on the product you are using:

| Product               | Fix                                                                                                                                                       | Notes                                                                                                                                  |
| :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------- |
| Payment Links         | Append `locale.x` and `country.x` query parameters to the payment link URL: `https://www.paypal.com/ncp/payment/YOUR_LINK_ID?locale.x=en_CA&country.x=CA` | This fix applies to all buyers regardless of locale or country settings. A US buyer accessing this link is also treated as a CA buyer. |
| Buy Buttons           | Not currently supported                                                                                                                                   | —                                                                                                                                      |
| Shopping Cart Buttons | Not currently supported                                                                                                                                   | —                                                                                                                                      |


# Use cases
Source: https://docs.paypal.ai/payments/use-cases-api



Explore key ways to apply the [Payment Links and Buttons API](/payments/pay-links-buttons-api) in your checkout and order flows. See how different configuration options map to common business scenarios so you can choose the pattern that best fits your integration.

The Payment Links and Buttons API currently supports payment links only and does not return button code.

| Use case                                                                                                                                                  | Endpoint                                     |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| [**Create payment links and buttons**](https://docs.paypal.ai/reference/api/rest/payment-resources/creates-a-payment-resource-for-a-single-item-purchase) | `POST /v1/checkout/payment-resources`        |
| [**List payment links**](https://docs.paypal.ai/reference/api/rest/payment-resources/list-payment-resources)                                              | `GET /v1/checkout/payment-resources`         |
| [**Get payment link details**](https://docs.paypal.ai/reference/api/rest/payment-resources/retrieve-a-payment-resource)                                   | `GET /v1/checkout/payment-resources/{id}`    |
| [**Update payment link**](https://docs.paypal.ai/reference/api/rest/payment-resources/replace-a-payment-resource)                                         | `PUT /v1/checkout/payment-resources/{id}`    |
| [**Delete payment link**](https://docs.paypal.ai/reference/api/rest/payment-resources/delete-a-payment-resource)                                          | `DELETE /v1/checkout/payment-resources/{id}` |

## Prerequisites

* Set up a [PayPal Business Account](https://www.paypal.com/business/open-business-account?_ga=2.49411041.673139926.1760916697-1259758161.1760473483).
* Navigate to the **Apps and Credentials** section on the [PayPal Developer Dashboard](https://www.paypal.com/signin?returnUri=https%3A%2F%2Fdeveloper.paypal.com%2Fdashboard%2F\&intent=developer\&ctxId=ul1761161497704) to ensure the **Payment Links and Buttons** option is checked.
* Implement OAuth 2.0 to obtain an access token for each API call.

## Create payment links and buttons (`POST`)

Create a buy now payment URL that links directly to a PayPal-hosted checkout experience. Use this endpoint to generate shareable payment URLs or various purchase flows.

Endpoint: `POST /v1/checkout/payment-resources`

### Request

The following sample request includes these key settings:

* Creates a reusable payment link for Premium Wireless Headphones with Noise Cancellation.
* Includes variant-specific pricing for four primary colors.
* Includes three variants where the color dimension is marked as primary and includes four options. The other two variants are `Warranty`, which has three options, and `Package Type`, which has two options. These variants do not affect pricing.
* Adds an 8.25% tax, applies a flat shipping rate, with an additional per-unit shipping charge, and requires customers to provide a shipping address.
* Provides customers with the option to add a gift message at checkout.
* Sets a maximum order quantity of 10 units.
* Redirects customers to a return URL after the transaction.

```json [expandable] theme={null}
{
  "integration_mode": "LINK",
  "type": "BUY_NOW",
  "reusable": "MULTIPLE",
  "return_url": "https://example-merchant.com/payment/return-success",
  "line_items": [
    {
      "name": "Premium Wireless Headphones with Noise Cancellation",
      "product_id": "PROD-WH-NC-2024-12345",
      "description": "Experience crystal-clear sound with our premium wireless headphones featuring active noise cancellation, 30-hour battery life",
      "taxes": [
        {
          "name": "State Sales Tax",
          "type": "PERCENTAGE",
          "value": "8.25"
        }
      ],
      "shipping": [
        {
          "type": "FLAT",
          "value": "12.50",
          "additional_unit_value": "3.00"
        }
      ],
      "collect_shipping_address": true,
      "customer_notes": [
        {
          "label": "Gift Message (Optional)",
          "required": false
        }
      ],
      "variants": {
        "dimensions": [
          {
            "name": "Color",
            "primary": true,
            "options": [
              {
                "label": "Midnight Black",
                "unit_amount": {
                  "currency_code": "USD",
                  "value": "149.99"
                }
              },
              {
                "label": "Silver Gray",
                "unit_amount": {
                  "currency_code": "USD",
                  "value": "149.99"
                }
              },
              {
                "label": "Rose Gold",
                "unit_amount": {
                  "currency_code": "USD",
                  "value": "169.99"
                }
              },
              {
                "label": "Navy Blue",
                "unit_amount": {
                  "currency_code": "USD",
                  "value": "159.99"
                }
              }
            ]
          },
          {
            "name": "Warranty",
            "primary": false,
            "options": [
              { "label": "Standard 1-Year" },
              { "label": "Extended 2-Year" },
              { "label": "Premium 3-Year" }
            ]
          },
          {
            "name": "Package Type",
            "primary": false,
            "options": [
              { "label": "Standard Box" },
              { "label": "Gift Wrapped" }
            ]
          }
        ]
      },
      "adjustable_quantity": {
        "maximum": 10
      }
    }
  ]
}
```

### Response

The following response contains a fixed-price payment resource link with product details and variants. The API returns HTTP status code `201 Created` and content type `application/json`.

```json [expandable] theme={null}
{
  "id": "PLB-HL9U6YXUMCGB",
  "integration_mode": "LINK",
  "type": "BUY_NOW",
  "reusable": "MULTIPLE",
  "return_url": "https://example-merchant.com/payment/return-success",
  "line_items": [
    {
      "name": "Premium Wireless Headphones with Noise Cancellation",
      "product_id": "PROD-WH-NC-2024-12345",
      "description": "Experience crystal-clear sound with our premium wireless headphones featuring active noise cancellation, 30-hour battery life",
      "taxes": [
        {
          "name": "State Sales Tax",
          "type": "PERCENTAGE",
          "value": "8.25"
        }
      ],
      "shipping": [
        {
          "type": "FLAT",
          "value": "12.50",
          "additional_unit_value": "3.00"
        }
      ],
      "collect_shipping_address": true,
      "customer_notes": [
        {
          "required": false,
          "label": "Gift Message (Optional)"
        }
      ],
      "variants": {
        "dimensions": [
          {
            "name": "Color",
            "primary": true,
            "options": [
              {
                "label": "Midnight Black",
                "unit_amount": { "currency_code": "USD", "value": "149.99" }
              },
              {
                "label": "Silver Gray",
                "unit_amount": { "currency_code": "USD", "value": "149.99" }
              },
              {
                "label": "Rose Gold",
                "unit_amount": { "currency_code": "USD", "value": "169.99" }
              },
              {
                "label": "Navy Blue",
                "unit_amount": { "currency_code": "USD", "value": "159.99" }
              }
            ]
          },
          {
            "name": "Warranty",
            "primary": false,
            "options": [
              { "label": "Standard 1-Year" },
              { "label": "Extended 2-Year" },
              { "label": "Premium 3-Year" }
            ]
          },
          {
            "name": "Package Type",
            "primary": false,
            "options": [
              { "label": "Standard Box" },
              { "label": "Gift Wrapped" }
            ]
          }
        ]
      },
      "adjustable_quantity": {
        "maximum": 10
      }
    }
  ],
  "status": "ACTIVE",
  "create_time": "2026-04-02T21:42:42Z",
  "update_time": "2026-04-02T21:42:42Z",
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/checkout/payment-resources/PLB-HL9U6YXUMCGB",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/checkout/payment-resources/PLB-HL9U6YXUMCGB",
      "rel": "replace",
      "method": "PUT"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/checkout/payment-resources/PLB-HL9U6YXUMCGB",
      "rel": "delete",
      "method": "DELETE"
    },
    {
      "href": "https://www.sandbox.paypal.com/ncp/payment/PLB-HL9U6YXUMCGB",
      "rel": "payment_link",
      "method": "GET"
    }
  ]
}
```

### Additional use cases

The following use cases demonstrate how to create payment links for additional scenarios.

#### Create a payment link with a return URL

Create a payment link for a wireless mouse priced at \$39.99 USD. After completing payment, customers are redirected to the specified return URL, such as `https://merchant.example.com/thank-you`.

```bash [expandable] theme={null}
curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v1/checkout/payment-resources' \
 -H 'Authorization: Bearer ACCESS-TOKEN' \
 -H 'Accept: application/json' \
 -H 'Content-Type: application/json' \
 -d '{
    "type": "BUY_NOW",
    "integration_mode": "LINK",
    "reusable": "MULTIPLE",
    "return_url": "https://merchant.example.com/thank-you",
    "line_items": [
        {
            "name": "Wireless Mouse",
            "unit_amount": {
                "currency_code": "USD",
                "value": "39.99"
            }
        }
    ]
}'
```

#### Create a payment link with variants

Create a payment link for a T-shirt priced at \$20.00 USD. The `Color` dimension is marked as primary and includes two options: `White` and `Black`. The `Size` dimension is secondary and includes `11oz` and `15oz` options. The base price of \$20.00 applies to all variant combinations.

```bash [expandable] theme={null}
curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v1/checkout/payment-resources' \
 -H 'Authorization: Bearer ACCESS-TOKEN' \
 -H 'Accept: application/json' \
 -H 'Content-Type: application/json' \
 -d '{
    "type": "BUY_NOW",
    "integration_mode": "LINK",
    "reusable": "MULTIPLE",
    "line_items": [
        {
            "name": "T-Shirt",
            "unit_amount": {
                "currency_code": "USD",
                "value": "20.00"
            },
            "variants": {
                "dimensions": [
                    {
                        "name": "Color",
                        "primary": true,
                        "options": [
                            {
                                "label": "White"
                            },
                            {
                                "label": "Black"
                            }
                        ]
                    },
                    {
                        "name": "Size",
                        "primary": false,
                        "options": [
                            {
                                "label": "11oz"
                            },
                            {
                                "label": "15oz"
                            }
                        ]
                    }
                ]
            }
        }
    ]
}'
```

#### Create a payment link with variant-level pricing

Create a payment link for a T-shirt with variant-specific pricing. The `Color` dimension is marked as primary and includes two options: `White` priced at \$19.00 USD, and `Black` priced at \$20.00 USD. The `Size` dimension is secondary and includes `11oz` and `15oz` options, with no price difference. No base `unit_amount` shows up in the payload because each color variant specifies its own price.

```bash [expandable] theme={null}
curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v1/checkout/payment-resources' \
 -H 'Authorization: Bearer ACCESS-TOKEN' \
 -H 'Accept: application/json' \
 -H 'Content-Type: application/json' \
 -d '{
    "integration_mode": "LINK",
    "type": "BUY_NOW",
    "reusable": "MULTIPLE",
    "line_items": [
        {
            "name": "T-Shirt",
            "variants": {
                "dimensions": [
                    {
                        "name": "Color",
                        "primary": true,
                        "options": [
                            {
                                "label": "White",
                                "unit_amount": {
                                    "currency_code": "USD",
                                    "value": "19.00"
                                }
                            },
                            {
                                "label": "Black",
                                "unit_amount": {
                                    "currency_code": "USD",
                                    "value": "20.00"
                                }
                            }
                        ]
                    },
                    {
                        "name": "Size",
                        "primary": false,
                        "options": [
                            {
                                "label": "11oz"
                            },
                            {
                                "label": "15oz"
                            }
                        ]
                    }
                ]
            }
        }
    ]
}'
```

#### Create a payment link with taxes and shipping

Create a payment link for a coffee mug priced at \$12.00 USD with tax and shipping calculations. The `taxes` and `shipping` arrays specify `type: PREFERENCE` and `value: PROFILE` to apply the merchant's preconfigured tax and shipping settings from their PayPal account. Merchants must configure these tax and shipping settings in their PayPal account for this feature to work.

```bash [expandable] theme={null}
curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v1/checkout/payment-resources' \
 -H 'Authorization: Bearer ACCESS-TOKEN' \
 -H 'Accept: application/json' \
 -H 'Content-Type: application/json' \
 -d '{
    "integration_mode": "LINK",
    "type": "BUY_NOW",
    "reusable": "MULTIPLE",
    "return_url": "https://merchant.example.com/thank-you",
    "line_items": [
        {
            "name": "Coffee Mug",
            "unit_amount": {
                "currency_code": "USD",
                "value": "12.00"
            },
            "taxes": [
                {
                    "name": "Sales Tax",
                    "type": "PREFERENCE",
                    "value": "PROFILE"
                }
            ],
            "shipping": [
                {
                    "type": "PREFERENCE",
                    "value": "PROFILE"
                }
            ]
        }
    ]
}'
```

#### Create a payment link with a discount

Create a payment link for a jacket priced at \$89.99 USD with a 10% discount. The `discounts` array specifies a `type: PERCENTAGE` discount with a value of `10`, which reduces the price displayed to buyers at checkout.

```bash theme={null}
curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v1/checkout/payment-resources' \
 -H 'Authorization: Bearer ACCESS-TOKEN' \
 -H 'Accept: application/json' \
 -H 'Content-Type: application/json' \
 -d '{
    "integration_mode": "LINK",
    "type": "BUY_NOW",
    "reusable": "MULTIPLE",
    "return_url": "https://merchant.example.com/thank-you",
    "line_items": [
        {
            "name": "Jacket",
            "unit_amount": {
                "currency_code": "USD",
                "value": "89.99"
            },
            "discounts": [
                {
                    "type": "PERCENTAGE",
                    "value": "10"
                }
            ]
        }
    ]
}'
```

#### Create a payment link with a handling fee

Create a payment link for a fragile item that requires special packaging. The `handling` array adds a flat \$4.00 USD handling fee and displays it separately from the item price at checkout. The `handling` array applies the fee once per line item, regardless of the quantity ordered.

```bash theme={null}
curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v1/checkout/payment-resources' \
 -H 'Authorization: Bearer ACCESS-TOKEN' \
 -H 'Accept: application/json' \
 -H 'Content-Type: application/json' \
 -d '{
    "integration_mode": "LINK",
    "type": "BUY_NOW",
    "reusable": "MULTIPLE",
    "return_url": "https://merchant.example.com/thank-you",
    "line_items": [
        {
            "name": "Ceramic Vase",
            "unit_amount": {
                "currency_code": "USD",
                "value": "45.00"
            },
            "handling": [
                {
                    "type": "FLAT",
                    "value": "4.00"
                }
            ]
        }
    ]
}'
```

#### Create a payment link with free shipping

Create a payment link for a book priced at \$19.99 USD with free shipping. Set `type` to `PREFERENCE` and `value` to `FREE_SHIPPING` to display no shipping charge to buyers at checkout. This setting overrides any shipping rates configured in your PayPal account.

```bash theme={null}
curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v1/checkout/payment-resources' \
 -H 'Authorization: Bearer ACCESS-TOKEN' \
 -H 'Accept: application/json' \
 -H 'Content-Type: application/json' \
 -d '{
    "integration_mode": "LINK",
    "type": "BUY_NOW",
    "reusable": "MULTIPLE",
    "return_url": "https://merchant.example.com/thank-you",
    "line_items": [
        {
            "name": "Book",
            "unit_amount": {
                "currency_code": "USD",
                "value": "19.99"
            },
            "shipping": [
                {
                    "type": "PREFERENCE",
                    "value": "FREE_SHIPPING"
                }
            ],
            "collect_shipping_address": true
        }
    ]
}'
```

#### Create a payment link with two customer input fields

Create a payment link that collects two custom inputs from buyers at checkout. The `customer_notes` field supports up to two entries, each with a `label` and a `required` flag to specify whether the field is mandatory or optional.

```bash theme={null}
curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v1/checkout/payment-resources' \
 -H 'Authorization: Bearer ACCESS-TOKEN' \
 -H 'Accept: application/json' \
 -H 'Content-Type: application/json' \
 -d '{
    "integration_mode": "LINK",
    "type": "BUY_NOW",
    "reusable": "MULTIPLE",
    "return_url": "https://merchant.example.com/thank-you",
    "line_items": [
        {
            "name": "Personalized Mug",
            "unit_amount": {
                "currency_code": "USD",
                "value": "24.99"
            },
            "customer_notes": [
                {
                    "label": "Engraving Text",
                    "required": true
                },
                {
                    "label": "Gift Message (Optional)",
                    "required": false
                }
            ]
        }
    ]
}'
```

## List payment links (`GET`)

Retrieve a paginated list of all payment links created by the merchant. This endpoint supports filtering and pagination through query parameters, including filtering by link status and tags.

Endpoint: `GET /v1/checkout/payment-resources`

### Request

The following sample request includes these key details:

* Sends a `GET` request to list payment links you created.
* Uses the `page_size` parameter to limit results. For example, setting `page_size=2` returns two payment links per page.
* Includes an OAuth 2.0 Bearer token for authentication.
* Headers set to `Accept: application/json` and `Content-Type: application/json`.
* Uses a `page_token` from the response to retrieve additional pages.

```bash theme={null}
curl -v -k -X GET 'https://api-m.sandbox.paypal.com/v1/checkout/payment-resources' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json'
```

### Response

The following sample response includes these key details:

* Returns a resources array with two payment links.
* The first payment link is for a `Wireless Mouse`, priced at \$29.99 USD. This link is active, set to `BUY_NOW`, and is reusable.
* The second payment link is for a Wireless Keyboard, priced at \$99.99 USD. It has the same status, type, and reusability settings as the first link.
* Each resource includes a shareable `payment_link` URL, metadata such as ID, product name, price, status, type, and creation timestamp, and a links array with HATEOAS actions to retrieve, update, edit, delete, or access the payment link.
* The response also includes a top-level links array for navigation, with a self link referencing the current request and a next link with a `page_token` for retrieving additional results.

```json [expandable] theme={null}
{
  "resources": [
    {
      "id": "PLB-X7MNK9P2QR8T",
      "integration_mode": "LINK",
      "create_time": "2025-11-29T13:13:25.832592Z",
      "status": "ACTIVE",
      "payment_link": "https://www.paypal.com/ncp/payment/PLB-X7MNK9P2QR8T",
      "type": "BUY_NOW",
      "reusable": "MULTIPLE",
      "line_items": [
        {
          "name": "Wireless Mouse",
          "unit_amount": {
            "currency_code": "USD",
            "value": "29.99"
          }
        }
      ],
      "links": [
        {
          "href": "https://api.paypal.com/v1/checkout/payment-resources/PLB-X7MNK9P2QR8T",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://api.paypal.com/v1/checkout/payment-resources/PLB-X7MNK9P2QR8T",
          "rel": "replace",
          "method": "PUT"
        },
        {
          "href": "https://api.paypal.com/v1/checkout/payment-resources/PLB-X7MNK9P2QR8T",
          "rel": "delete",
          "method": "DELETE"
        },
        {
          "href": "https://www.paypal.com/ncp/payment/PLB-X7MNK9P2QR8T",
          "rel": "payment_link",
          "method": "GET"
        }
      ]
    },
    {
      "id": "PLB-P2QR8TX7MNK9",
      "integration_mode": "LINK",
      "create_time": "2025-11-29T13:13:25.832592Z",
      "status": "ACTIVE",
      "payment_link": "https://www.paypal.com/ncp/payment/PLB-P2QR8TX7MNK9",
      "type": "BUY_NOW",
      "reusable": "MULTIPLE",
      "line_items": [
        {
          "name": "Wireless Keyboard",
          "unit_amount": {
            "currency_code": "USD",
            "value": "99.99"
          }
        }
      ],
      "links": [
        {
          "href": "https://api.paypal.com/v1/checkout/payment-resources/PLB-P2QR8TX7MNK9",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://api.paypal.com/v1/checkout/payment-resources/PLB-P2QR8TX7MNK9",
          "rel": "replace",
          "method": "PUT"
        },
        {
          "href": "https://api.paypal.com/v1/checkout/payment-resources/PLB-P2QR8TX7MNK9",
          "rel": "delete",
          "method": "DELETE"
        },
        {
          "href": "https://www.paypal.com/ncp/payment/PLB-P2QR8TX7MNK9",
          "rel": "payment_link",
          "method": "GET"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "https://api.paypal.com/v1/checkout/payment-resources?page_size=2",
      "rel": "self"
    },
    {
      "href": "https://api.paypal.com/v1/checkout/payment-resources?page_token=eyJleGNsdXNpdmVfc3RhcnRfa2V5Ijp7ImlkIjoiUExCLVAyUVI4VFg3TU5LOSJ9LCJwYWdlX3NpemUiOjJ9",
      "rel": "next"
    }
  ]
}
```

## Get payment link details (`GET`)

Get the details of a specific payment link by its unique ID. This endpoint returns all available metadata, including payment status, links, reusable type, and line item details for the requested payment link.

Endpoint: `GET /v1/checkout/payment-resources/{id}`

### Request

The following sample request includes these key details:

* Includes the complete details for a specific payment link identified by the resource ID `PLB-X7MNK9P2QR8T` using a `GET` request.
* Uses an OAuth 2.0 Bearer token in the Authorization header to authenticate the request.
* Sets the `Accept` and `Content-Type` headers to `application/json` for proper formatting.

```bash theme={null}
curl -v -k -X GET 'https://api-m.sandbox.paypal.com/v1/checkout/payment-resources/PLB-X7MNK9P2QR8T' \
 -H 'Authorization: Bearer ACCESS-TOKEN' \
 -H 'Accept: application/json' \
 -H 'Content-Type: application/json'
```

### Response

The following response contains the complete details for a single fixed-price payment link. The API returns status code `200 OK` and content type `application/json`.

The following sample response includes these key details:

* Returns the full details of payment link `PLB-X7MNK9P2QR8T`.
* The payment link is active, set to `BUY_NOW`, and configured for multiple uses.
* Shows a product called Wireless Mouse, priced at \$29.99 USD
* The link was created on `2025-11-29T13:13:25.832592Z` with integration mode `LINK`.
* After payment, customers are redirected to `https://merchant.example.com/thank-you` that is specified by `return_url`.
* Includes a shareable payment link URL at `https://www.paypal.com/ncp/payment/PLB-X7MNK9P2QR8T`.
* Provides a links array with HATEOAS actions: retrieve the link details (`self`), update the link (`replace`), delete the link (`delete`), and access the customer-facing payment page (`payment_link`).

```json [expandable] theme={null}
{
  "id": "PLB-X7MNK9P2QR8T",
  "integration_mode": "LINK",
  "create_time": "2025-11-29T13:13:25.832592Z",
  "status": "ACTIVE",
  "payment_link": "https://www.paypal.com/ncp/payment/PLB-X7MNK9P2QR8T",
  "type": "BUY_NOW",
  "reusable": "MULTIPLE",
  "return_url": "https://merchant.example.com/thank-you",
  "line_items": [
    {
      "name": "Wireless Mouse",
      "unit_amount": {
        "currency_code": "USD",
        "value": "29.99"
      }
    }
  ],
  "links": [
    {
      "href": "https://api.paypal.com/v1/checkout/payment-resources/PLB-X7MNK9P2QR8T",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.paypal.com/v1/checkout/payment-resources/PLB-X7MNK9P2QR8T",
      "rel": "replace",
      "method": "PUT"
    },
    {
      "href": "https://api.paypal.com/v1/checkout/payment-resources/PLB-X7MNK9P2QR8T",
      "rel": "delete",
      "method": "DELETE"
    },
    {
      "href": "https://www.paypal.com/ncp/payment/PLB-X7MNK9P2QR8T",
      "rel": "payment_link",
      "method": "GET"
    }
  ]
}
```

## Update payment link (`PUT`)

Update a specific payment link by its unique identifier. This endpoint helps you replace the product and checkout details for a fixed price payment link with new configuration data.

Endpoint: `PUT /v1/checkout/payment-resources/{id}`

### Request

The following sample request includes these key details:

* Sends a `PUT` request to update the payment link with ID `PLB-X7MNK9P2QR8T`.
* Uses an OAuth 2.0 Bearer token in the Authorization header for authentication.
* Includes the `Accept` and `Content-Type` headers set to `application/json`.
* Sends the updated link configuration in the request body, replacing the existing product information entirely.
* Maintains the same payment link ID and URL while applying the new settings.

> **Note:** The API currently only uses `PUT` calls instead of `PATCH` calls.

```bash [expandable] theme={null}
curl -v -k -X PUT 'https://api-m.sandbox.paypal.com/v1/checkout/payment-resources/PLB-X7MNK9P2QR8T' \
 -H 'Authorization: Bearer ACCESS-TOKEN' \
 -H 'Accept: application/json' \
 -H 'Content-Type: application/json' \
 -d '{
    "type": "BUY_NOW",
    "integration_mode": "LINK",
    "reusable": "MULTIPLE",
    "return_url": "https://merchant.example.com/thank-you",
    "line_items": [
        {
            "name": "Wireless Mouse",
            "unit_amount": {
                "currency_code": "USD",
                "value": "29.99"
            }
        }
    ]
}'
```

### Response

The following response contains the confirmation details of an updated payment link.

The API returns HTTP status `204 No Content` or, in some cases, a confirmation response body with the content type `application/json`.

The following sample response includes these key details:

* Confirms that the updated payment link `PLB-X7MNK9P2QR8T` has been successfully applied.
* Returns the payment link with `ACTIVE` status, maintaining the same ID and payment link URL.
* Preserves the original creation time.

```json [expandable] theme={null}
{
  "id": "PLB-X7MNK9P2QR8T",
  "integration_mode": "LINK",
  "create_time": "2025-11-29T13:13:25.832592Z",
  "status": "ACTIVE",
  "payment_link": "https://www.paypal.com/ncp/payment/PLB-X7MNK9P2QR8T",
  "type": "BUY_NOW",
  "reusable": "MULTIPLE",
  "return_url": "https://merchant.example.com/thank-you",
  "line_items": [
    {
      "name": "Wireless Mouse",
      "unit_amount": {
        "currency_code": "USD",
        "value": "29.99"
      }
    }
  ],
  "links": [
    {
      "href": "https://api.paypal.com/v1/checkout/payment-resources/PLB-X7MNK9P2QR8T",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.paypal.com/v1/checkout/payment-resources/PLB-X7MNK9P2QR8T",
      "rel": "replace",
      "method": "PUT"
    },
    {
      "href": "https://api.paypal.com/v1/checkout/payment-resources/PLB-X7MNK9P2QR8T",
      "rel": "delete",
      "method": "DELETE"
    },
    {
      "href": "https://www.paypal.com/ncp/payment/PLB-X7MNK9P2QR8T",
      "rel": "payment_link",
      "method": "GET"
    }
  ]
}
```

## Delete payment link (`DELETE`)

Delete a specific payment link by its unique identifier. This endpoint permanently removes a payment link associated with the specified ID.

Endpoint: `DELETE /v1/checkout/payment-resources/{id}`

### Request

The following sample request includes these key details:

* Sends a `DELETE` request to permanently remove the payment link with ID `PLB-X7MNK9P2QR8T`.
* Uses an OAuth 2.0 Bearer token in the Authorization header for authentication.
* Includes the `Accept` and `Content-Type` headers set to `application/json`.

```bash theme={null}
curl -v -k -X DELETE 'https://api-m.sandbox.paypal.com/v1/checkout/payment-resources/PLB-X7MNK9P2QR8T' \
 -H 'Authorization: Bearer ACCESS-TOKEN' \
 -H 'Accept: application/json' \
 -H 'Content-Type: application/json'
```

### Response

The API returns HTTP status `204 No Content` with the content type `application/json`, indicating that the payment link was deleted. No response body is returned.

## Test

* Create a sandbox account through the PayPal Developer Portal.
* Use your sandbox environment for all development and testing. All endpoints are duplicated for the sandbox (`api-m.sandbox.paypal.com`) and live environments. See [Card testing](https://developer.paypal.com/tools/sandbox/card-testing/) to simulate transactions in the sandbox.
* To test live behavior, create a low-value payment link, complete a test purchase, and verify the transaction in the **Activity** section of your PayPal account. Refund the test transaction after verification.

## Common errors

For error handling and troubleshooting, see [Common errors](https://docs.paypal.ai/developer/how-to/api/troubleshooting/common-errors/overview).


# Capture authorized payment
Source: https://docs.paypal.ai/reference/api/rest/authorizations/capture-authorized-payment

/api-reference/payments_payment_v2.json post /v2/payments/authorizations/{authorization_id}/capture
Captures an authorized payment, by ID.



# Reauthorize authorized payment
Source: https://docs.paypal.ai/reference/api/rest/authorizations/reauthorize-authorized-payment

/api-reference/payments_payment_v2.json post /v2/payments/authorizations/{authorization_id}/reauthorize
Reauthorizes an authorized PayPal account payment, by ID. To ensure that funds are still available, reauthorize a payment after its initial three-day honor period expires. Within the 29-day authorization period, you can issue multiple re-authorizations after the honor period expires.<br/><br/>If 30 days have transpired since the date of the original authorization, you must create an authorized payment instead of reauthorizing the original authorized payment.<br/><br/>A reauthorized payment itself has a new honor period of three days.<br/><br/>You can reauthorize an authorized payment from 4 to 29 days after the 3-day honor period. The allowed amount depends on context and geography, for example in US it is up to 115% of the original authorized amount, not to exceed an increase of $75 USD.<br/><br/>Supports only the `amount` request parameter.



# Show details for authorized payment
Source: https://docs.paypal.ai/reference/api/rest/authorizations/show-details-for-authorized-payment

/api-reference/payments_payment_v2.json get /v2/payments/authorizations/{authorization_id}
Shows details for an authorized payment, by ID.



# Void authorized payment
Source: https://docs.paypal.ai/reference/api/rest/authorizations/void-authorized-payment

/api-reference/payments_payment_v2.json post /v2/payments/authorizations/{authorization_id}/void
Voids, or cancels, an authorized payment, by ID. You cannot void an authorized payment that has been fully captured.



# List all balances
Source: https://docs.paypal.ai/reference/api/rest/balances/list-all-balances

/api-reference/reporting_transactions_v1.json get /v1/reporting/balances
List all balances. Specify date time to list balances for that time that appear in the response.<blockquote><strong>Notes:</strong> <ul><li>It takes a maximum of three hours for balances to appear in the list balances call.</li><li>This call lists balances upto the previous three years.</li></ul></blockquote>



# Refund captured payment
Source: https://docs.paypal.ai/reference/api/rest/captures/refund-captured-payment

/api-reference/payments_payment_v2.json post /v2/payments/captures/{capture_id}/refund
Refunds a captured payment, by ID. For a full refund, include an empty payload in the JSON request body. For a partial refund, include an <code>amount</code> object in the JSON request body.



# Show captured payment details
Source: https://docs.paypal.ai/reference/api/rest/captures/show-captured-payment-details

/api-reference/payments_payment_v2.json get /v2/payments/captures/{capture_id}
Shows details for a captured payment, by ID.



# Create cart
Source: https://docs.paypal.ai/reference/api/rest/cart-operations/create-cart

/api-reference/paypal-cart-agentic-commerce-v1.yaml post /merchant-cart
Creates a new cart with the provided PayPalCart object. This is called by PayPal Shopping Cart
when an AI agent or customer initiates a checkout process.

**Returns:**
- `201 Created`: Cart created successfully with payment token in payment_method
- `200 OK` + `validation_issues`: Business logic issues that need resolution
- `400 Bad Request`: Invalid request format
- `401 Authentication Failed`: Authentication failed with a list of possible issues
- `422 Unprocessable Entity`: Validation errors in cart data
- `500 Internal Server Error`: System errors




# Get cart details
Source: https://docs.paypal.ai/reference/api/rest/cart-operations/get-cart-details

/api-reference/paypal-cart-agentic-commerce-v1.yaml get /merchant-cart/{cartId}
Retrieves the current state of a cart. Used by PayPal Shopping Cart to check
cart status, validation issues, and current totals.

**Error Handling:**
- **400 Bad Request**: Cart ID format is invalid (e.g., doesn't match expected pattern)
- **401 Authentication Failed**: Authentication failed with a list of possible issues
- **404 Not Found**: Cart ID is well-formed but doesn't exist in merchant's system  
- **500 Internal Server Error**: System error during cart retrieval




# Update cart
Source: https://docs.paypal.ai/reference/api/rest/cart-operations/update-cart

/api-reference/paypal-cart-agentic-commerce-v1.yaml put /merchant-cart/{cartId}
Updates a cart by completely replacing its contents with the provided PayPalCart object.
This is used when customers make changes like adding or removing items, updating quantities, updating shipping address,
applying discount codes, changing shipping options, or completing checkout fields.

**⚠️ CRITICAL: Complete Replacement Operation**
- PUT replaces the ENTIRE cart with the provided PayPalCart object
- Any fields not included in the request will be removed/reset
- Missing fields will be lost (e.g., omitting customer info will remove it)




# Complete checkout
Source: https://docs.paypal.ai/reference/api/rest/checkout/complete-checkout

/api-reference/paypal-cart-agentic-commerce-v1.yaml post /merchant-cart/{cartId}/checkout
Completes the checkout process after customer has approved payment via PayPal.
This endpoint receives the payment method with payer_id and finalizes the order.

**Called when:** Customer completes PayPal payment approval
**Required:** payment_method with valid token and payer_id




# List Connections.
Source: https://docs.paypal.ai/reference/api/rest/connections/list-connections

/api-reference/invoicing_v2.json get /v2/invoicing/accounting-sync/merchant/connections
Lists connections to accounting platforms per merchant.



# Accept claim
Source: https://docs.paypal.ai/reference/api/rest/disputes-actions/accept-claim

/api-reference/customer_disputes_v1.json post /v1/customer/disputes/{id}/accept-claim
Accepts liability for a claim, by ID. When you accept liability for a claim, the dispute closes in the customer’s favor and PayPal automatically refunds money to the customer from the merchant's account. Allowed accept_claim_type values for the request is available in dispute details <a href="/docs/api/customer-disputes/v1/#definition-allowed_response_options">allowed response options</a> object.



# Accept offer to resolve dispute
Source: https://docs.paypal.ai/reference/api/rest/disputes-actions/accept-offer-to-resolve-dispute

/api-reference/customer_disputes_v1.json post /v1/customer/disputes/{id}/accept-offer
The customer accepts the offer from merchant to resolve a dispute, by ID. PayPal automatically refunds the amount proposed by merchant to the customer.



# Acknowledge returned item
Source: https://docs.paypal.ai/reference/api/rest/disputes-actions/acknowledge-returned-item

/api-reference/customer_disputes_v1.json post /v1/customer/disputes/{id}/acknowledge-return-item
Acknowledges that the customer returned an item for a dispute, by ID. A merchant can make this request for disputes with the `MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED` reason. Allowed acknowledgement_type values for the request is available in dispute details <a href="/docs/api/customer-disputes/v1/#definition-allowed_response_options">allowed response options</a> object. For constraints and rules regarding documents, see <a href="/docs/integration/direct/customer-disputes/integration-guide/#documents">documents</a>.



# Appeal dispute
Source: https://docs.paypal.ai/reference/api/rest/disputes-actions/appeal-dispute

/api-reference/customer_disputes_v1.json post /v1/customer/disputes/{id}/appeal
Appeals a dispute, by ID. To appeal a dispute, use the <code>appeal</code> link in the <a href="/docs/api/reference/api-responses/#hateoas-links/">HATEOAS links</a> from the show dispute details response. If this link does not appear, you cannot appeal the dispute. Submit new evidence as a document or notes in the JSON request body. For constraints and rules regarding documents, see <a href="/docs/integration/direct/customer-disputes/integration-guide/#documents">documents</a>.<br/>To make this request, specify the dispute ID in the URI and specify the evidence in the JSON request body. For information about dispute reasons, see <a href="/docs/integration/direct/customer-disputes/integration-guide/#dispute-reasons">dispute reasons</a>.



# Deny offer to resolve dispute
Source: https://docs.paypal.ai/reference/api/rest/disputes-actions/deny-offer-to-resolve-dispute

/api-reference/customer_disputes_v1.json post /v1/customer/disputes/{id}/deny-offer
Denies an offer that the merchant proposes for a dispute, by ID.



# Escalate dispute to claim
Source: https://docs.paypal.ai/reference/api/rest/disputes-actions/escalate-dispute-to-claim

/api-reference/customer_disputes_v1.json post /v1/customer/disputes/{id}/escalate
Escalates the dispute, by ID, to a PayPal claim. To make this call, the stage in the dispute lifecycle must be `INQUIRY`.



# Make offer to resolve dispute
Source: https://docs.paypal.ai/reference/api/rest/disputes-actions/make-offer-to-resolve-dispute

/api-reference/customer_disputes_v1.json post /v1/customer/disputes/{id}/make-offer
Makes an offer to the other party to resolve a dispute, by ID. To make this call, the stage in the dispute lifecycle must be `INQUIRY`. If the customer accepts the offer, PayPal automatically makes a refund. Allowed offer_type values for the request is available in dispute details <a href="/docs/api/customer-disputes/v1/#definition-allowed_response_options">allowed response options</a> object.



# Provide evidence
Source: https://docs.paypal.ai/reference/api/rest/disputes-actions/provide-evidence

/api-reference/customer_disputes_v1.json post /v1/customer/disputes/{id}/provide-evidence
Provides evidence for a dispute, by ID. A merchant can provide evidence for disputes with the <code>WAITING_FOR_SELLER_RESPONSE</code> status while customers can provide evidence for disputes with the <code>WAITING_FOR_BUYER_RESPONSE</code> status. Evidence can be a proof of delivery or proof of refund document or notes, which can include logs. A proof of delivery document includes a tracking number while a proof of refund document includes a refund ID. For other evidence type, notes and documents can be given. Evidences requested from you can be found by checking the type of evidence for the corresponding source under the evidence section of the <a href="/docs/api/customer-disputes/v1/#disputes_get">show dispute details</a> response. The source will be <code>REQUESTED_FROM_SELLER</code> for evidences requested from the merchant while it will be <code>REQUESTED_FROM_BUYER</code> for evidences requested from the customer. For constraints and rules regarding documents, see <a href="/docs/integration/direct/customer-disputes/integration-guide/#documents">documents</a>.<br/>To make this request, specify the evidence in the JSON request body and use the <code>provide-evidence</code> link in the <a href="/docs/api/reference/api-responses/#hateoas-links/">HATEOAS links</a> of the <a href="/docs/api/customer-disputes/v1/#disputes_get">show dispute details</a> response. In case the link is not present in the response, you can't provide evidence for the dispute. For information about dispute reasons, see <a href="/docs/integration/direct/customer-disputes/integration-guide/#dispute-reasons">dispute reasons</a>.



# Provide supporting information for dispute
Source: https://docs.paypal.ai/reference/api/rest/disputes-actions/provide-supporting-information-for-dispute

/api-reference/customer_disputes_v1.json post /v1/customer/disputes/{id}/provide-supporting-info
Provides supporting information for a dispute, by ID. A merchant or buyer can make this request for disputes if they find the `provide-supporting-info` link in the HATEOAS links in the list disputes response. The party can provide the supporting information to PayPal to defend themselves only when the `dispute_life_cycle_stage` is `CHARGEBACK`, `PRE_ARBITRATION`, or `ARBITRATION`. They can provide a note that describes their part with details or upload any supporting documents to support their side. For constraints and rules regarding documents, see <a href="/docs/integration/direct/customer-disputes/integration-guide/#documents">documents</a>.<br/>To make this request, specify the dispute ID in the URI and specify the notes in the JSON request body. This method differs from the provide evidence method which supports only multipart request, where PayPal asks the concerned party for evidence.



# Send message about dispute to other party
Source: https://docs.paypal.ai/reference/api/rest/disputes-actions/send-message-about-dispute-to-other-party

/api-reference/customer_disputes_v1.json post /v1/customer/disputes/{id}/send-message
Sends a message about a dispute, by ID, to the other party in the dispute. Merchants and customers can only send messages if the `dispute_life_cycle_stage` value is `INQUIRY`. For constraints and rules regarding documents that can be attached as part of the message, see <a href="/docs/integration/direct/customer-disputes/integration-guide/#documents">documents</a>. To send a message, use the <code>send-message</code> link in the <a href="/docs/api/reference/api-responses/#hateoas-links/">HATEOAS links</a> of the <a href="/docs/api/customer-disputes/v1/#disputes_get">show dispute details</a> response and specify the message in the JSON request body. In case the link is not present in the response you can't send a message on the dispute.



# Settle dispute
Source: https://docs.paypal.ai/reference/api/rest/disputes-actions/settle-dispute

/api-reference/customer_disputes_v1.json post /v1/customer/disputes/{id}/adjudicate
<blockquote><strong>Important:</strong> This method is for sandbox use only.</blockquote> Settles a dispute in either the customer's or merchant's favor. Merchants can make this call in the sandbox to complete end-to-end dispute resolution testing, which mimics the dispute resolution that PayPal agents normally complete. To make this call, the dispute <code>status</code> must be <code>UNDER_REVIEW</code> and <code>adjudicate</code> link  should be available in the <a href="/docs/api/customer-disputes/v1/#disputes_get!c=200&path=links&t=response/">HATEOAS links</a> of the <a href="/docs/api/customer-disputes/v1/#disputes_get">show dispute details</a> response.



# Update dispute status
Source: https://docs.paypal.ai/reference/api/rest/disputes-actions/update-dispute-status

/api-reference/customer_disputes_v1.json post /v1/customer/disputes/{id}/require-evidence
<blockquote><strong>Important:</strong> This method is for sandbox use only.</blockquote> Updates the status of a dispute, by ID, from <code>UNDER_REVIEW</code> to either:<ul><li><code>WAITING_FOR_BUYER_RESPONSE</code></li><li><code>WAITING_FOR_SELLER_RESPONSE</code></li></ul>This status change enables either the customer or merchant to submit evidence for the dispute. To make this call, the dispute <code>status</code> must be <code>UNDER_REVIEW</code> and <code>require-evidence</code> link  should be available in the <a href="/docs/api/customer-disputes/v1/#disputes_get!c=200&path=links&t=response/">HATEOAS links</a> of the <a href="/docs/api/customer-disputes/v1/#disputes_get">show dispute details</a> response. Specify an <code>action</code> value in the JSON request body to indicate whether the status change enables the customer or merchant to submit evidence:<table><thead><tr align="left"><th>If <code>action</code> is</th><th>The <code>status</code> updates to</th></tr></thead><tbody><tr><td><code>BUYER_EVIDENCE</code></td><td> <code>WAITING_FOR_BUYER_RESPONSE</code></td></tr><tr><td><code>SELLER_EVIDENCE</code></td><td> <code>WAITING_FOR_SELLER_RESPONSE</code></td></tr></tbody></table>.



# List disputes
Source: https://docs.paypal.ai/reference/api/rest/disputes/list-disputes

/api-reference/customer_disputes_v1.json get /v1/customer/disputes
Lists disputes with a summary set of details, which shows the <code>dispute_id</code>, <code>reason</code>, <code>status</code>, <code>dispute_state</code>, <code>dispute_life_cycle_stage</code>, <code>dispute_channel</code>, <code>dispute_amount</code>, <code>create_time</code> and <code>update_time</code> fields.<br/><br/>To filter the disputes in the response, specify one or more optional query parameters. To limit the number of disputes in the response, specify the <code>page_size</code> query parameter.<br/><br/>To list multiple disputes, set these query parameters in the request:<ul><li><code>page_size=2</code></li><li><code>start_time</code> instead of <code>disputed_transaction_id</code></li></ul><br/>If the response contains more than two disputes, it lists two disputes and includes a HATEOAS link to the next page of results.



# Partially update dispute
Source: https://docs.paypal.ai/reference/api/rest/disputes/partially-update-dispute

/api-reference/customer_disputes_v1.json patch /v1/customer/disputes/{id}
Partially updates a dispute, by ID. Seller can update the `communication_detail` value or The partner can add the `partner action` information.



# Show dispute details
Source: https://docs.paypal.ai/reference/api/rest/disputes/show-dispute-details

/api-reference/customer_disputes_v1.json get /v1/customer/disputes/{id}
Shows details for a dispute, by ID.<blockquote><strong>Note:</strong> The fields that appear in the response depend on the access. For example, if the merchant requests shows dispute details, the customer's email ID does not appear.</blockquote>



# Receive updated order information via callback URL
Source: https://docs.paypal.ai/reference/api/rest/externalcallback/receive-updated-order-information-via-callback-url

/api-reference/openapi-orders.json post /v2/checkout/orders/order-update-callback
The documentation for this 'endpoint' is different from the other endpoints under v2 Orders. For this endpoint the role of client and server is reversed. The client sending the request is PayPal, and the server sending the response is the merchant. In the request, PayPal will send the buyer's redacted shipping address and selected shipping option to the callback URL defined the create order request. The response from the merchant will update the Orders resource.



# Find a list of eligible payment methods.
Source: https://docs.paypal.ai/reference/api/rest/find-eligible-methods/find-a-list-of-eligible-payment-methods

/api-reference/payments_payment_v2.json post /v2/payments/find-eligible-methods
Get a list of eligible payment methods based on the input parameters provided.



# List Connection Status for an Invoice.
Source: https://docs.paypal.ai/reference/api/rest/invoice-connection-details/list-connection-status-for-an-invoice

/api-reference/invoicing_v2.json get /v2/invoicing/accounting-sync/invoices/{id}/connections
Lists connections to accounting platforms per invoice.



# Cancel sent invoice
Source: https://docs.paypal.ai/reference/api/rest/invoices/cancel-sent-invoice

/api-reference/invoicing_v2.json post /v2/invoicing/invoices/{invoice_id}/cancel
Cancels a sent invoice, by ID, and, optionally, sends a notification about the cancellation to the payer, merchant, and CC: emails.



# Create draft invoice
Source: https://docs.paypal.ai/reference/api/rest/invoices/create-draft-invoice

/api-reference/invoicing_v2.json post /v2/invoicing/invoices
Creates a draft invoice. To move the invoice from a draft to payable state, you must <a href="#invoices_send">send the invoice</a>.<br/><br/>In the JSON request body, include invoice details including merchant information. The <code>invoice</code> object must include an <code>items</code> array.<blockquote><strong>Note:</strong> The merchant that you specify in an invoice must have a PayPal account in good standing.</blockquote>.



# Delete external payment
Source: https://docs.paypal.ai/reference/api/rest/invoices/delete-external-payment

/api-reference/invoicing_v2.json delete /v2/invoicing/invoices/{invoice_id}/payments/{transaction_id}
Deletes an external payment, by invoice ID and transaction ID.



# Delete external refund
Source: https://docs.paypal.ai/reference/api/rest/invoices/delete-external-refund

/api-reference/invoicing_v2.json delete /v2/invoicing/invoices/{invoice_id}/refunds/{transaction_id}
Deletes an external refund, by invoice ID and transaction ID.



# Delete invoice
Source: https://docs.paypal.ai/reference/api/rest/invoices/delete-invoice

/api-reference/invoicing_v2.json delete /v2/invoicing/invoices/{invoice_id}
Deletes a draft or scheduled invoice, by ID. Deletes invoices in the draft or scheduled state only. For invoices that have already been sent, you can <a href="/docs/api/invoicing/v2/#invoices_cancel">cancel the invoice</a>. After you delete a draft or scheduled invoice, you can no longer use it or show its details. However, you can reuse its invoice number.



# Fully update invoice
Source: https://docs.paypal.ai/reference/api/rest/invoices/fully-update-invoice

/api-reference/invoicing_v2.json put /v2/invoicing/invoices/{invoice_id}
Fully updates an invoice, by ID. In the JSON request body, include a complete `invoice` object. This call does not support partial updates. <blockquote><strong>Notes:</strong><ul><li>API caller can change/modify recipient only 2 times in 72 hours.</li></ul></blockquote>.



# Generate invoice number
Source: https://docs.paypal.ai/reference/api/rest/invoices/generate-invoice-number

/api-reference/invoicing_v2.json post /v2/invoicing/generate-next-invoice-number
Generates the next invoice number that is available to the merchant. The next invoice number uses the prefix and suffix from the last invoice number and increments the number by one. For example, the next invoice number after `INVOICE-1234` is `INVOICE-1235`.



# Generate QR code
Source: https://docs.paypal.ai/reference/api/rest/invoices/generate-qr-code

/api-reference/invoicing_v2.json post /v2/invoicing/invoices/{invoice_id}/generate-qr-code
Generates a QR code for an invoice, by ID. The QR code is a PNG image in <a href="https://www.base64encode.org/">Base64-encoded</a> format that corresponds to the invoice ID. You can generate a QR code for an invoice and add it to a paper or PDF invoice. When customers use their mobile devices to scan the QR code, they are redirected to the PayPal mobile payment flow where they can view the invoice and pay online with PayPal or a credit card. Before you get a QR code, you must <a href="#invoices_create">create an invoice</a> and <a href="#invoices_send">send an invoice</a> to move the invoice from a draft to payable state. Do not include an email address if you do not want the invoice emailed.



# List invoices
Source: https://docs.paypal.ai/reference/api/rest/invoices/list-invoices

/api-reference/invoicing_v2.json get /v2/invoicing/invoices
Lists invoices. To filter the invoices that appear in the response, you can specify one or more optional query parameters.



# Record payment for invoice
Source: https://docs.paypal.ai/reference/api/rest/invoices/record-payment-for-invoice

/api-reference/invoicing_v2.json post /v2/invoicing/invoices/{invoice_id}/payments
Records a payment for the invoice. If no payment is due, the invoice is marked as `PAID`. Otherwise, the invoice is marked as `PARTIALLY PAID`.



# Record refund for invoice
Source: https://docs.paypal.ai/reference/api/rest/invoices/record-refund-for-invoice

/api-reference/invoicing_v2.json post /v2/invoicing/invoices/{invoice_id}/refunds
Records a refund for the invoice. If all payments are refunded, the invoice is marked as `REFUNDED`. Otherwise, the invoice is marked as `PARTIALLY REFUNDED`.



# Send invoice
Source: https://docs.paypal.ai/reference/api/rest/invoices/send-invoice

/api-reference/invoicing_v2.json post /v2/invoicing/invoices/{invoice_id}/send
Sends or schedules an invoice, by ID, to be sent to a customer. The action depends on the invoice issue date:<ul><li>If the invoice issue date is current or in the past, sends the invoice immediately.</li><li>If the invoice issue date is in the future, schedules the invoice to be sent on that date.</li></ul>To suppress the merchant's email notification, set the `send_to_invoicer` body parameter to `false`. To send the invoice through a share link and not through PayPal, set the <code>send_to_recipient</code> parameter to <code>false</code> in the <code>notification</code> object. The <code>send_to_recipient</code> parameter does not apply to a future issue date because the invoice is scheduled to be sent through PayPal on that date.<blockquote><strong>Notes:</strong><ul><li>After you send an invoice, resending it has no effect.</li><li>To send a notification for updates, <a href="#invoices_update">update the invoice</a> and set the <code>send_to_recipient</code> body parameter to <code>true</code>.</li></ul></blockquote>



# Send invoice reminder
Source: https://docs.paypal.ai/reference/api/rest/invoices/send-invoice-reminder

/api-reference/invoicing_v2.json post /v2/invoicing/invoices/{invoice_id}/remind
Sends a reminder to the payer about an invoice, by ID. In the JSON request body, include a `notification` object that defines the subject of the reminder and other details. <blockquote><strong>Notes:</strong><ul><li>API caller can send only 2 reminders in a day.</li></ul></blockquote>.



# Show invoice details
Source: https://docs.paypal.ai/reference/api/rest/invoices/show-invoice-details

/api-reference/invoicing_v2.json get /v2/invoicing/invoices/{invoice_id}
Shows details for an invoice, by ID.



# Add tracking information for an Order.
Source: https://docs.paypal.ai/reference/api/rest/orders/add-tracking-information-for-an-order

/api-reference/openapi-orders.json post /v2/checkout/orders/{id}/track
Adds tracking information for an Order.



# Authorize payment for order
Source: https://docs.paypal.ai/reference/api/rest/orders/authorize-payment-for-order

/api-reference/openapi-orders.json post /v2/checkout/orders/{id}/authorize
Authorizes payment for an order. To successfully authorize payment for an order, the buyer must first approve the order or a valid payment_source must be provided in the request. A buyer can approve the order upon being redirected to the rel:approve URL that was returned in the HATEOAS links in the create order response.<blockquote><strong>Note:</strong> For error handling and troubleshooting, see <a href="https://developer.paypal.com/api/rest/reference/orders/v2/errors/#authorize-order">Orders v2 errors</a>.</blockquote>



# Capture payment for order
Source: https://docs.paypal.ai/reference/api/rest/orders/capture-payment-for-order

/api-reference/openapi-orders.json post /v2/checkout/orders/{id}/capture
Captures payment for an order. To successfully capture payment for an order, the buyer must first approve the order or a valid payment_source must be provided in the request. A buyer can approve the order upon being redirected to the rel:approve URL that was returned in the HATEOAS links in the create order response.<blockquote><strong>Note:</strong> For error handling and troubleshooting, see <a href="https://developer.paypal.com/api/rest/reference/orders/v2/errors/#capture-order">Orders v2 errors</a>.</blockquote>



# Confirm the Order
Source: https://docs.paypal.ai/reference/api/rest/orders/confirm-the-order

/api-reference/openapi-orders.json post /v2/checkout/orders/{id}/confirm-payment-source
Payer confirms their intent to pay for the the Order with the given payment source.



# Create order
Source: https://docs.paypal.ai/reference/api/rest/orders/create-order

/api-reference/openapi-orders.json post /v2/checkout/orders
Creates an order. Merchants and partners can add Level 2 and 3 data to payments to reduce risk and payment processing costs. For more information about processing payments, see <a href="https://developer.paypal.com/docs/checkout/advanced/processing/">checkout</a> or <a href="https://developer.paypal.com/docs/multiparty/checkout/advanced/processing/">multiparty checkout</a>.<blockquote><strong>Note:</strong> For error handling and troubleshooting, see <a href="https://developer.paypal.com/api/rest/reference/orders/v2/errors/#create-order">Orders v2 errors</a>.</blockquote>



# Show order details
Source: https://docs.paypal.ai/reference/api/rest/orders/show-order-details

/api-reference/openapi-orders.json get /v2/checkout/orders/{id}
Shows details for an order, by ID.<blockquote><strong>Note:</strong> For error handling and troubleshooting, see <a href="https://developer.paypal.com/api/rest/reference/orders/v2/errors/#get-order">Orders v2 errors</a>.</blockquote>



# Update order
Source: https://docs.paypal.ai/reference/api/rest/orders/update-order

/api-reference/openapi-orders.json patch /v2/checkout/orders/{id}
Updates an order with a `CREATED` or `APPROVED` status. You cannot update an order with the `COMPLETED` status.<br/><br/>To make an update, you must provide a `reference_id`. If you omit this value with an order that contains only one purchase unit, PayPal sets the value to `default` which enables you to use the path: <code>\"/purchase_units/@reference_id=='default'/{attribute-or-object}\"</code>. Merchants and partners can add Level 2 and 3 data to payments to reduce risk and payment processing costs. For more information about processing payments, see <a href="https://developer.paypal.com/docs/checkout/advanced/processing/">checkout</a> or <a href="https://developer.paypal.com/docs/multiparty/checkout/advanced/processing/">multiparty checkout</a>.<blockquote><strong>Note:</strong> For error handling and troubleshooting, see <a href="https://developer.paypal.com/api/rest/reference/orders/v2/errors/#patch-order">Orders v2 errors</a>.</blockquote>Patchable attributes or objects:<br/><br/><table><thead><th>Attribute</th><th>Op</th><th>Notes</th></thead><tbody><tr><td><code>intent</code></td><td>replace</td><td></td></tr><tr><td><code>payer</code></td><td>replace, add</td><td>Using replace op for <code>payer</code> will replace the whole <code>payer</code> object with the value sent in request.</td></tr><tr><td><code>purchase_units</code></td><td>replace, add</td><td></td></tr><tr><td><code>purchase_units[].custom_id</code></td><td>replace, add, remove</td><td></td></tr><tr><td><code>purchase_units[].description</code></td><td>replace, add, remove</td><td></td></tr><tr><td><code>purchase_units[].payee.email</code></td><td>replace</td><td></td></tr><tr><td><code>purchase_units[].shipping.name</code></td><td>replace, add</td><td></td></tr><tr><td><code>purchase_units[].shipping.email_address</code></td><td>replace, add</td><td></td></tr><tr><td><code>purchase_units[].shipping.phone_number</code></td><td>replace, add</td><td></td></tr><tr><td><code>purchase_units[].shipping.options</code></td><td>replace, add</td><td></td></tr><tr><td><code>purchase_units[].shipping.address</code></td><td>replace, add</td><td></td></tr><tr><td><code>purchase_units[].shipping.type</code></td><td>replace, add</td><td></td></tr><tr><td><code>purchase_units[].soft_descriptor</code></td><td>replace, remove</td><td></td></tr><tr><td><code>purchase_units[].amount</code></td><td>replace</td><td></td></tr><tr><td><code>purchase_units[].items</code></td><td>replace, add, remove</td><td></td></tr><tr><td><code>purchase_units[].invoice_id</code></td><td>replace, add, remove</td><td></td></tr><tr><td><code>purchase_units[].payment_instruction</code></td><td>replace</td><td></td></tr><tr><td><code>purchase_units[].payment_instruction.disbursement_mode</code></td><td>replace</td><td>By default, <code>disbursement_mode</code> is <code>INSTANT</code>.</td></tr><tr><td><code>purchase_units[].payment_instruction.payee_receivable_fx_rate_id</code></td><td>replace, add, remove</td><td></td></tr><tr><td><code>purchase_units[].payment_instruction.platform_fees</code></td><td>replace, add, remove</td><td></td></tr><tr><td><code>purchase_units[].supplementary_data.airline</code></td><td>replace, add, remove</td><td></td></tr><tr><td><code>purchase_units[].supplementary_data.card</code></td><td>replace, add, remove</td><td></td></tr><tr><td><code>application_context.client_configuration</code></td><td>replace, add</td><td></td></tr></tbody></table>



# Creates a payment resource for a single-item purchase
Source: https://docs.paypal.ai/reference/api/rest/payment-resources/creates-a-payment-resource-for-a-single-item-purchase

/api-reference/payment_links_and_buttons_v1.json post /v1/checkout/payment-resources
Creates a new PayPal payment resource for a single-item Buy Now checkout. Returns the full resource details including ID, payment link url, and status.



# Delete a payment resource
Source: https://docs.paypal.ai/reference/api/rest/payment-resources/delete-a-payment-resource

/api-reference/payment_links_and_buttons_v1.json delete /v1/checkout/payment-resources/{id}
Permanently deletes the specified payment resource. Operation is irreversible and returns HTTP 204 No Content.



# List payment resources
Source: https://docs.paypal.ai/reference/api/rest/payment-resources/list-payment-resources

/api-reference/payment_links_and_buttons_v1.json get /v1/checkout/payment-resources
Returns a paginated list of payment resources created by the authenticated merchant. Supports filtering by status and pagination parameters.



# Replace a payment resource
Source: https://docs.paypal.ai/reference/api/rest/payment-resources/replace-a-payment-resource

/api-reference/payment_links_and_buttons_v1.json put /v1/checkout/payment-resources/{id}
Replaces all editable fields of an existing payment resource. Use this for full updates.



# Retrieve a payment resource
Source: https://docs.paypal.ai/reference/api/rest/payment-resources/retrieve-a-payment-resource

/api-reference/payment_links_and_buttons_v1.json get /v1/checkout/payment-resources/{id}
Retrieves details for a specific payment resource, including current status, integration configuration, and related HATEOAS links.



# Create payment token for a given payment source
Source: https://docs.paypal.ai/reference/api/rest/payment-tokens/create-payment-token-for-a-given-payment-source

/api-reference/vault_payment_tokens_v3.json post /v3/vault/payment-tokens
Creates a Payment Token from the given payment source and adds it to the Vault of the associated customer.



# Delete payment token
Source: https://docs.paypal.ai/reference/api/rest/payment-tokens/delete-payment-token

/api-reference/vault_payment_tokens_v3.json delete /v3/vault/payment-tokens/{id}
Delete the payment token associated with the payment token id.



# List all payment tokens
Source: https://docs.paypal.ai/reference/api/rest/payment-tokens/list-all-payment-tokens

/api-reference/vault_payment_tokens_v3.json get /v3/vault/payment-tokens
Returns all payment tokens for a customer.



# Retrieve a payment token
Source: https://docs.paypal.ai/reference/api/rest/payment-tokens/retrieve-a-payment-token

/api-reference/vault_payment_tokens_v3.json get /v3/vault/payment-tokens/{id}
Returns a readable representation of vaulted payment source associated with the payment token id.



# Cancel unclaimed payout item
Source: https://docs.paypal.ai/reference/api/rest/payouts-item/cancel-unclaimed-payout-item

/api-reference/payments_payouts_batch_v1.json post /v1/payments/payouts-item/{payout_item_id}/cancel
Cancels an unclaimed payout item, by ID. If no one claims the unclaimed item within 30 days, the API automatically returns the funds to the sender. Use this call to cancel the unclaimed item before the automatic 30-day refund. You can cancel payout items with a <code>transaction_status</code> of <code>UNCLAIMED</code>.



# Show payout item details
Source: https://docs.paypal.ai/reference/api/rest/payouts-item/show-payout-item-details

/api-reference/payments_payouts_batch_v1.json get /v1/payments/payouts-item/{payout_item_id}
Shows details for a payout item, by ID. A <code>payout_item_id</code> helps you identify denied payments. If a payment is denied, you can use the <code>payout_item_id</code> to identify the payment even if it lacks a <code>transaction_id</code>.



# Create batch payout
Source: https://docs.paypal.ai/reference/api/rest/payouts/create-batch-payout

/api-reference/payments_payouts_batch_v1.json post /v1/payments/payouts
Creates a batch payout. In the JSON request body, pass a `sender_batch_header` and an `items` array. The `sender_batch_header` defines how to handle the payout. The `items` array defines the payout items.<br/>You can make payouts to one or more recipients.<blockquote><strong>Notes:</strong> <ul><li><p>PayPal does not process duplicate payouts. If you specify a <code>sender_batch_id</code> that was used in the last 30 days, the API rejects the request with an error message that shows the duplicate <code>sender_batch_id</code> and includes a HATEOAS link to the original payout with the same <code>sender_batch_id</code>.</p><p>If you receive an HTTP <code>5<i>nn</i></code> status code, you can safely retry the request with the same <code>sender_batch_id</code>.</p></li><li><p>The Payouts API does not support build notation (BN) codes. In a future Payouts release, you can optionally provide BN codes in the <code>PayPal-Partner-Attribution-Id</code> request header.</p><p>For information about the <code>PayPal-Partner-Attribution-Id</code> header, see <a href="/api/rest/requests/#http-request-headers">HTTP request headers</a>. To learn about or request a BN code, contact your partner manager or see <a href="https://www.paypal.com/us/webapps/mpp/partner-program">PayPal Partner Program</a>.</p></li></ul></blockquote>



# Show payout batch details
Source: https://docs.paypal.ai/reference/api/rest/payouts/show-payout-batch-details

/api-reference/payments_payouts_batch_v1.json get /v1/payments/payouts/{id}
Shows the latest status of a batch payout. Includes the transaction status and other data for individual payout items.



# Create Exchange Rate Quote
Source: https://docs.paypal.ai/reference/api/rest/quote-exchange-rates/create-exchange-rate-quote

/api-reference/currency_exchange_v2.json post /v2/pricing/quote-exchange-rates
<strong>Purpose:</strong><ul><p>The PayPal Exchange Rate Quote API enables businesses to dynamically display prices in multiple currencies by generating exchange rate quotes for currency pair.</p></ul><strong>Key Features:</strong><ul><p>FX Rate Guarantee: Guarantees exchange rates for a specified duration, ensuring stability and consistency in currency presentment scenarios.</p><p>Customizable Pricing: Provides flexible exchange rate options tailored to business needs, allowing customization through negotiated rates and dynamic pricing models to align with business requirements.</p><p>Provides functionality to source wholesale market rates with the addition of a percentage-based currency conversion fee. This enables the delivery of retail exchange rates without offering a rate guarantee.</p><p>FX Rate Revenue Markup: Offers merchants the flexibility to apply customized markups on exchange rates, allowing them to generate additional revenue from currency conversions. Enables businesses to define their own pricing strategies by setting adjustable markups based on transaction volume, customer segments, or market conditions, ensuring greater control over foreign exchange earnings while maintaining competitive pricing for end users.</p></ul><strong>Quote API Usage:</strong><ul><p>Need a Guaranteed Rate for a Certain Timeframe: Businesses want to lock in an exchange rate for a defined period to protect against market fluctuations and reduce the risk of FX volatility.</p><p>Offer Customers Stable, Upfront Pricing for a Limited Time: Displaying FX rates but ensuring the rate remains fixed for a short duration, allowing customers to complete their purchase without unexpected price changes.</p><p>Integrate with PayPal as Payment Processor for Real-Time Quoting Scenarios: Leveraging PayPal’s payment processing capabilities, ensuring seamless multi-currency support.</p></ul><strong>Sample Use cases:</strong> Multi-Currency Presentment, Real-Time Checkout Quotes, Subscription Pricing with Guaranteed Rate, Buy-Now-Price Guarantee for Cross-Border Seller.



# Show refund details
Source: https://docs.paypal.ai/reference/api/rest/refunds/show-refund-details

/api-reference/payments_payment_v2.json get /v2/payments/refunds/{refund_id}
Shows details for a refund, by ID.



# Search for invoices
Source: https://docs.paypal.ai/reference/api/rest/search-invoices/search-for-invoices

/api-reference/invoicing_v2.json post /v2/invoicing/search-invoices
Searches for and lists invoices that match search criteria. If you pass multiple criteria, the response lists invoices that match all criteria.



# Create a setup token
Source: https://docs.paypal.ai/reference/api/rest/setup-tokens/create-a-setup-token

/api-reference/vault_payment_tokens_v3.json post /v3/vault/setup-tokens
Creates a Setup Token from the given payment source and adds it to the Vault of the associated customer.



# Retrieve a setup token
Source: https://docs.paypal.ai/reference/api/rest/setup-tokens/retrieve-a-setup-token

/api-reference/vault_payment_tokens_v3.json get /v3/vault/setup-tokens/{id}
Returns a readable representation of temporarily vaulted payment source associated with the setup token id.



# Simulate webhook event
Source: https://docs.paypal.ai/reference/api/rest/simulate-event/simulate-webhook-event

/api-reference/notifications_webhooks_v1.json post /v1/notifications/simulate-event
Simulates a webhook event. In the JSON request body, specify a sample payload. <br/> You need to subscribe to the following webhook events for Pay upon Invoice:<br/><table><thead><tr><th>Event</th><th>Trigger</th></tr></thead><tbody><tr><td><code>PAYMENT.CAPTURE.COMPLETED</code></td><td>A payment capture completes.</td></tr><tr><td><code>PAYMENT.CAPTURE.DENIED</code></td><td>A payment capture is denied.</td></tr><tr><td><code>CHECKOUT.PAYMENT-APPROVAL.REVERSED</code></td><td>PayPal reverses a payment capture.</td></tr></tbody></table>



# Create template
Source: https://docs.paypal.ai/reference/api/rest/templates/create-template

/api-reference/invoicing_v2.json post /v2/invoicing/templates
Creates an invoice template. You can use details from this template to create an invoice. You can create up to 50 templates.<blockquote><strong>Note:</strong> Every merchant starts with three PayPal system templates that are optimized for the unit type billed. The template includes `Quantity`, `Hours`, and `Amount`.</blockquote>



# Delete template
Source: https://docs.paypal.ai/reference/api/rest/templates/delete-template

/api-reference/invoicing_v2.json delete /v2/invoicing/templates/{template_id}
Deletes a template, by ID.



# Fully update template
Source: https://docs.paypal.ai/reference/api/rest/templates/fully-update-template

/api-reference/invoicing_v2.json put /v2/invoicing/templates/{template_id}
Fully updates a template, by ID. In the JSON request body, include a complete `template` object. This call does not support partial updates.



# List templates
Source: https://docs.paypal.ai/reference/api/rest/templates/list-templates

/api-reference/invoicing_v2.json get /v2/invoicing/templates
Lists merchant-created templates with associated details. The associated details include the emails, addresses, and phone numbers from the user's PayPal profile.<br/>The user can select which values to show in the business information section of their template.



# Show template details
Source: https://docs.paypal.ai/reference/api/rest/templates/show-template-details

/api-reference/invoicing_v2.json get /v2/invoicing/templates/{template_id}
Shows details for a template, by ID.



# Update or cancel tracking information for an order
Source: https://docs.paypal.ai/reference/api/rest/trackers/update-or-cancel-tracking-information-for-an-order

/api-reference/openapi-orders.json patch /v2/checkout/orders/{id}/trackers/{tracker_id}
Updates or cancels the tracking information for a PayPal order, by ID. Updatable attributes or objects:<br/><br/><table><thead><th>Attribute</th><th>Op</th><th>Notes</th></thead><tbody></tr><tr><td><code>items</code></td><td>replace</td><td>Using replace op for <code>items</code> will replace the entire <code>items</code> object with the value sent in request.</td></tr><tr><td><code>notify_payer</code></td><td>replace, add</td><td></td></tr><tr><td><code>status</code></td><td>replace</td><td>Only patching status to CANCELLED is currently supported.</td></tr></tbody></table>



# List transactions
Source: https://docs.paypal.ai/reference/api/rest/transactions/list-transactions

/api-reference/reporting_transactions_v1.json get /v1/reporting/transactions
Lists transactions. Specify one or more query parameters to filter the transaction that appear in the response.<blockquote><strong>Notes:</strong> <ul><li>If you specify one or more optional query parameters, the <code>ending_balance</code> response field is empty.</li><li>It takes a maximum of three hours for executed transactions to appear in the list transactions call.</li><li>This call lists transaction for the previous three years.</li></ul></blockquote>



# Verify webhook signature
Source: https://docs.paypal.ai/reference/api/rest/verify-webhook-signature/verify-webhook-signature

/api-reference/notifications_webhooks_v1.json post /v1/notifications/verify-webhook-signature
Verifies a webhook signature.



# List available events
Source: https://docs.paypal.ai/reference/api/rest/webhooks-event-types/list-available-events

/api-reference/notifications_webhooks_v1.json get /v1/notifications/webhooks-event-types
Lists available events to which any webhook can subscribe. For a list of supported events, see [Webhook event names](/docs/api/notifications/webhooks/event-names/).



# List event notifications
Source: https://docs.paypal.ai/reference/api/rest/webhooks-events/list-event-notifications

/api-reference/notifications_webhooks_v1.json get /v1/notifications/webhooks-events
Lists webhooks event notifications. Use query parameters to filter the response.



# Resend event notification
Source: https://docs.paypal.ai/reference/api/rest/webhooks-events/resend-event-notification

/api-reference/notifications_webhooks_v1.json post /v1/notifications/webhooks-events/{event_id}/resend
Resends a webhook event notification, by ID. Any pending notifications are not resent.



# Show event notification details
Source: https://docs.paypal.ai/reference/api/rest/webhooks-events/show-event-notification-details

/api-reference/notifications_webhooks_v1.json get /v1/notifications/webhooks-events/{event_id}
Shows details for a webhooks event notification, by ID.



# Create webhook lookup
Source: https://docs.paypal.ai/reference/api/rest/webhooks-lookup/create-webhook-lookup

/api-reference/notifications_webhooks_v1.json post /v1/notifications/webhooks-lookup
Creates a webhook lookup. A webhook lookup ties the API caller's REST API app to the subject account (or, if no subject is specified, to the API caller's account). If a webhook event is generated for an event that is tied to the account but not to a particular REST API app (for example, payments initiated with the NVP/SOAP APIs or through the user interface on PayPal.com), those webhook events will treated as if they were intended for the REST API app registered in the webhook lookup instead. Webhook events will then be delivered to any webhooks registered to that REST API app.



# Delete webhook lookup
Source: https://docs.paypal.ai/reference/api/rest/webhooks-lookup/delete-webhook-lookup

/api-reference/notifications_webhooks_v1.json delete /v1/notifications/webhooks-lookup/{webhook_lookup_id}
Deletes a webhook lookup, by ID.



# List webhook lookups
Source: https://docs.paypal.ai/reference/api/rest/webhooks-lookup/list-webhook-lookups

/api-reference/notifications_webhooks_v1.json get /v1/notifications/webhooks-lookup
Lists webhook lookups.



# Show webhook lookup details
Source: https://docs.paypal.ai/reference/api/rest/webhooks-lookup/show-webhook-lookup-details

/api-reference/notifications_webhooks_v1.json get /v1/notifications/webhooks-lookup/{webhook_lookup_id}
Shows details for a webhook lookup, by ID.



# Create webhook
Source: https://docs.paypal.ai/reference/api/rest/webhooks/create-webhook

/api-reference/notifications_webhooks_v1.json post /v1/notifications/webhooks
Subscribes your webhook listener to events.



# Delete webhook
Source: https://docs.paypal.ai/reference/api/rest/webhooks/delete-webhook

/api-reference/notifications_webhooks_v1.json delete /v1/notifications/webhooks/{webhook_id}
Deletes a webhook, by ID.



# List event subscriptions for webhook
Source: https://docs.paypal.ai/reference/api/rest/webhooks/list-event-subscriptions-for-webhook

/api-reference/notifications_webhooks_v1.json get /v1/notifications/webhooks/{webhook_id}/event-types
Lists event subscriptions for a webhook, by ID.



# List webhooks
Source: https://docs.paypal.ai/reference/api/rest/webhooks/list-webhooks

/api-reference/notifications_webhooks_v1.json get /v1/notifications/webhooks
Lists webhooks for an app.



# Show webhook details
Source: https://docs.paypal.ai/reference/api/rest/webhooks/show-webhook-details

/api-reference/notifications_webhooks_v1.json get /v1/notifications/webhooks/{webhook_id}
Shows details for a webhook, by ID.



# Update webhook
Source: https://docs.paypal.ai/reference/api/rest/webhooks/update-webhook

/api-reference/notifications_webhooks_v1.json patch /v1/notifications/webhooks/{webhook_id}
Updates a webhook to replace webhook fields with new values. Supports only the `replace` operation. Pass a `json_patch` object with `replace` operation and `path`, which is `/url` for a URL or `/event_types` for events. The `value` is either the URL or a list of events.



# Country and region codes
Source: https://docs.paypal.ai/reference/codes/country-codes



PayPal's REST APIs support PayPal account payments across multiple countries when using a business account. For comprehensive information about country-specific offerings and limitations, see the [PayPal Offerings Worldwide](https://www.paypal.com/us/webapps/mpp/country-worldwide) page or your country-specific site.

PayPal's REST APIs support the following countries:

| Country or region        | Country or region code |
| ------------------------ | ---------------------- |
| ALBANIA                  | `AL`                   |
| ALGERIA                  | `DZ`                   |
| ANDORRA                  | `AD`                   |
| ANGOLA                   | `AO`                   |
| ANGUILLA                 | `AI`                   |
| ANTIGUA & BARBUDA        | `AG`                   |
| ARGENTINA                | `AR`                   |
| ARMENIA                  | `AM`                   |
| ARUBA                    | `AW`                   |
| AUSTRALIA                | `AU`                   |
| AUSTRIA                  | `AT`                   |
| AZERBAIJAN               | `AZ`                   |
| BAHAMAS                  | `BS`                   |
| BAHRAIN                  | `BH`                   |
| BARBADOS                 | `BB`                   |
| BELARUS                  | `BY`                   |
| BELGIUM                  | `BE`                   |
| BELIZE                   | `BZ`                   |
| BENIN                    | `BJ`                   |
| BERMUDA                  | `BM`                   |
| BHUTAN                   | `BT`                   |
| BOLIVIA                  | `BO`                   |
| BOSNIA & HERZEGOVINA     | `BA`                   |
| BOTSWANA                 | `BW`                   |
| BRAZIL                   | `BR`                   |
| BRITISH VIRGIN ISLANDS   | `VG`                   |
| BRUNEI                   | `BN`                   |
| BULGARIA                 | `BG`                   |
| BURKINA FASO             | `BF`                   |
| BURUNDI                  | `BI`                   |
| CAMBODIA                 | `KH`                   |
| CAMEROON                 | `CM`                   |
| CANADA                   | `CA`                   |
| CAPE VERDE               | `CV`                   |
| CAYMAN ISLANDS           | `KY`                   |
| CHAD                     | `TD`                   |
| CHILE                    | `CL`                   |
| CHINA                    | `C2`                   |
| COLOMBIA                 | `CO`                   |
| COMOROS                  | `KM`                   |
| CONGO - BRAZZAVILLE      | `CG`                   |
| CONGO - KINSHASA         | `CD`                   |
| COOK ISLANDS             | `CK`                   |
| COSTA RICA               | `CR`                   |
| CÔTE D’IVOIRE            | `CI`                   |
| CROATIA                  | `HR`                   |
| CYPRUS                   | `CY`                   |
| CZECH REPUBLIC           | `CZ`                   |
| DENMARK                  | `DK`                   |
| DJIBOUTI                 | `DJ`                   |
| DOMINICA                 | `DM`                   |
| DOMINICAN REPUBLIC       | `DO`                   |
| ECUADOR                  | `EC`                   |
| EGYPT                    | `EG`                   |
| EL SALVADOR              | `SV`                   |
| ERITREA                  | `ER`                   |
| ESTONIA                  | `EE`                   |
| ETHIOPIA                 | `ET`                   |
| FALKLAND ISLANDS         | `FK`                   |
| FAROE ISLANDS            | `FO`                   |
| FIJI                     | `FJ`                   |
| FINLAND                  | `FI`                   |
| FRANCE                   | `FR`                   |
| FRENCH GUIANA            | `GF`                   |
| FRENCH POLYNESIA         | `PF`                   |
| GABON                    | `GA`                   |
| GAMBIA                   | `GM`                   |
| GEORGIA                  | `GE`                   |
| GERMANY                  | `DE`                   |
| GIBRALTAR                | `GI`                   |
| GREECE                   | `GR`                   |
| GREENLAND                | `GL`                   |
| GRENADA                  | `GD`                   |
| GUADELOUPE               | `GP`                   |
| GUATEMALA                | `GT`                   |
| GUINEA                   | `GN`                   |
| GUINEA-BISSAU            | `GW`                   |
| GUYANA                   | `GY`                   |
| HONDURAS                 | `HN`                   |
| HONG KONG SAR CHINA      | `HK`                   |
| HUNGARY                  | `HU`                   |
| ICELAND                  | `IS`                   |
| INDIA                    | `IN`                   |
| INDONESIA                | `ID`                   |
| IRELAND                  | `IE`                   |
| ISRAEL                   | `IL`                   |
| ITALY                    | `IT`                   |
| JAMAICA                  | `JM`                   |
| JAPAN                    | `JP`                   |
| JORDAN                   | `JO`                   |
| KAZAKHSTAN               | `KZ`                   |
| KENYA                    | `KE`                   |
| KIRIBATI                 | `KI`                   |
| KUWAIT                   | `KW`                   |
| KYRGYZSTAN               | `KG`                   |
| LAOS                     | `LA`                   |
| LATVIA                   | `LV`                   |
| LESOTHO                  | `LS`                   |
| LIECHTENSTEIN            | `LI`                   |
| LITHUANIA                | `LT`                   |
| LUXEMBOURG               | `LU`                   |
| MACEDONIA                | `MK`                   |
| MADAGASCAR               | `MG`                   |
| MALAWI                   | `MW`                   |
| MALAYSIA                 | `MY`                   |
| MALDIVES                 | `MV`                   |
| MALI                     | `ML`                   |
| MALTA                    | `MT`                   |
| MARSHALL ISLANDS         | `MH`                   |
| MARTINIQUE               | `MQ`                   |
| MAURITANIA               | `MR`                   |
| MAURITIUS                | `MU`                   |
| MAYOTTE                  | `YT`                   |
| MEXICO                   | `MX`                   |
| MICRONESIA               | `FM`                   |
| MOLDOVA                  | `MD`                   |
| MONACO                   | `MC`                   |
| MONGOLIA                 | `MN`                   |
| MONTENEGRO               | `ME`                   |
| MONTSERRAT               | `MS`                   |
| MOROCCO                  | `MA`                   |
| MOZAMBIQUE               | `MZ`                   |
| NAMIBIA                  | `NA`                   |
| NAURU                    | `NR`                   |
| NEPAL                    | `NP`                   |
| NETHERLANDS              | `NL`                   |
| NEW CALEDONIA            | `NC`                   |
| NEW ZEALAND              | `NZ`                   |
| NICARAGUA                | `NI`                   |
| NIGER                    | `NE`                   |
| NIGERIA                  | `NG`                   |
| NIUE                     | `NU`                   |
| NORFOLK ISLAND           | `NF`                   |
| NORWAY                   | `NO`                   |
| OMAN                     | `OM`                   |
| PALAU                    | `PW`                   |
| PANAMA                   | `PA`                   |
| PAPUA NEW GUINEA         | `PG`                   |
| PARAGUAY                 | `PY`                   |
| PERU                     | `PE`                   |
| PHILIPPINES              | `PH`                   |
| PITCAIRN ISLANDS         | `PN`                   |
| POLAND                   | `PL`                   |
| PORTUGAL                 | `PT`                   |
| QATAR                    | `QA`                   |
| RÉUNION                  | `RE`                   |
| ROMANIA                  | `RO`                   |
| RUSSIA                   | `RU`                   |
| RWANDA                   | `RW`                   |
| SAMOA                    | `WS`                   |
| SAN MARINO               | `SM`                   |
| SÃO TOMÉ & PRÍNCIPE      | `ST`                   |
| SAUDI ARABIA             | `SA`                   |
| SENEGAL                  | `SN`                   |
| SERBIA                   | `RS`                   |
| SEYCHELLES               | `SC`                   |
| SIERRA LEONE             | `SL`                   |
| SINGAPORE                | `SG`                   |
| SLOVAKIA                 | `SK`                   |
| SLOVENIA                 | `SI`                   |
| SOLOMON ISLANDS          | `SB`                   |
| SOMALIA                  | `SO`                   |
| SOUTH AFRICA             | `ZA`                   |
| SOUTH KOREA              | `KR`                   |
| SPAIN                    | `ES`                   |
| SRI LANKA                | `LK`                   |
| ST. HELENA               | `SH`                   |
| ST. KITTS & NEVIS        | `KN`                   |
| ST. LUCIA                | `LC`                   |
| ST. PIERRE & MIQUELON    | `PM`                   |
| ST. VINCENT & GRENADINES | `VC`                   |
| SURINAME                 | `SR`                   |
| SVALBARD & JAN MAYEN     | `SJ`                   |
| SWAZILAND                | `SZ`                   |
| SWEDEN                   | `SE`                   |
| SWITZERLAND              | `CH`                   |
| TAIWAN                   | `TW`                   |
| TAJIKISTAN               | `TJ`                   |
| TANZANIA                 | `TZ`                   |
| THAILAND                 | `TH`                   |
| TOGO                     | `TG`                   |
| TONGA                    | `TO`                   |
| TRINIDAD & TOBAGO        | `TT`                   |
| TUNISIA                  | `TN`                   |
| TURKMENISTAN             | `TM`                   |
| TURKS & CAICOS ISLANDS   | `TC`                   |
| TUVALU                   | `TV`                   |
| UGANDA                   | `UG`                   |
| UKRAINE                  | `UA`                   |
| UNITED ARAB EMIRATES     | `AE`                   |
| UNITED KINGDOM           | `GB`                   |
| UNITED STATES            | `US`                   |
| URUGUAY                  | `UY`                   |
| VANUATU                  | `VU`                   |
| VATICAN                  | `VA`                   |
| VENEZUELA                | `VE`                   |
| VIETNAM                  | `VN`                   |
| WALLIS & FUTUNA          | `WF`                   |
| YEMEN                    | `YE`                   |
| ZAMBIA                   | `ZM`                   |
| ZIMBABWE                 | `ZW`                   |


# Currency codes
Source: https://docs.paypal.ai/reference/codes/currency-codes



PayPal's REST APIs support merchants across multiple countries and various currencies, depending on the payment method: PayPal payments or direct credit card payments. For country-specific offerings and limitations,  see the [PayPal Offerings Worldwide](https://www.paypal.com/us/webapps/mpp/country-worldwide) page or your country-specific site.

<Note> **Note:** To receive payments in a currency that you do not hold in your PayPal account, you must [configure your Payment Receiving Preferences](#payment-receiving-preferences) within your account. Otherwise, the payment status remains pending until you manually approve the payment in your PayPal account.</Note>

To specify currencies in request URI and body parameters, use [three-character ISO-4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) codes.

| Currency                       | Code  |
| ------------------------------ | ----- |
| Australian dollar              | `AUD` |
| Brazilian real <sup>2</sup>    | `BRL` |
| Canadian dollar                | `CAD` |
| Chinese Renmenbi <sup>3</sup>  | `CNY` |
| Czech koruna                   | `CZK` |
| Danish krone                   | `DKK` |
| Euro                           | `EUR` |
| Hong Kong dollar               | `HKD` |
| Hungarian forint <sup>1</sup>  | `HUF` |
| Israeli new shekel             | `ILS` |
| Japanese yen <sup>1</sup>      | `JPY` |
| Malaysian ringgit <sup>3</sup> | `MYR` |
| Mexican peso                   | `MXN` |
| New Taiwan dollar <sup>1</sup> | `TWD` |
| New Zealand dollar             | `NZD` |
| Norwegian krone                | `NOK` |
| Philippine peso                | `PHP` |
| Polish złoty                   | `PLN` |
| Pound sterling                 | `GBP` |
| Russian ruble                  | `RUB` |
| Singapore dollar               | `SGD` |
| Swedish krona                  | `SEK` |
| Swiss franc                    | `CHF` |
| Thai baht                      | `THB` |
| United States dollar           | `USD` |

> <sup>1</sup> This currency does not support decimals. If you pass a decimal amount, an error occurs.<br />
> <sup>2</sup> This currency is supported as a payment currency and a currency balance for in-country PayPal accounts only. If the receiver of funds is not from Brazil, then PayPal converts funds into the primary holding currency of the account with the applicable currency conversion rate. The currency conversion rate includes PayPal's applicable spread or fee.<br />
> <sup>3</sup> This currency is supported as a payment currency and a currency balance for in-country PayPal accounts only.

### [](#link-paymentreceivingpreferences)Payment receiving preferences

If you have a PayPal Premier or Business account, configure your **Payment Receiving Preferences** to handle payments automatically. You can convert any payment into your primary currency or block certain types of payments.

You can set the following:

* Block or unblock payments from U.S. customers who don't have a confirmed address.
* Block or unblock payments sent to you in a currency you don't hold.
* Block or unblock payments for duplicate invoice IDs.
* Block or unblock payments from customers who have non-U.S. PayPal accounts.
* Block or unblock payments from Student Account holders.
* Log in to your PayPal business account at [www.paypal.com](https://www.paypal.com) .
* Click the settings icon at the top of your PayPal account page and then click **Account Settings** .
* From the left menu, click **Payment preferences** .
* Click the Update link for the **Block Payments** item. Update your settings and they save automatically.


# Locale codes
Source: https://docs.paypal.ai/reference/codes/locale-codes



You can use any PayPal-supported language and locale to localize PayPal checkout pages.

## Localize the checkout experience

Pass a locale code to PayPal to customize the locale of the buyer's checkout experience.

To determine the locale for the checkout page, PayPal uses the locale code and these other factors:

1. The shipping address country provided by the merchant in the request.
2. The country taken from the locale code parameter passed by the merchant.
3. The country of the currently logged-in user.
4. The merchant's country.

When this information is not available, PayPal uses these default locales in this order:

1. `en_US`
2. `fr_XC`
3. `es_XC`
4. `zh_XC`

## Supported locale codes

PayPal supports these locales:

| Region                   | Region code | Language support priority | Locale code | BCP-47 code for REST APIs |
| ------------------------ | ----------- | ------------------------- | ----------- | ------------------------- |
| ALBANIA                  | `AL`        | 0                         | `en_US`     | `en-AL`                   |
| ALGERIA                  | `DZ`        | 0                         | `ar_EG`     | `ar-DZ`                   |
| ALGERIA                  | `DZ`        | 1                         | `en_US`     | `en-DZ`                   |
| ALGERIA                  | `DZ`        | 2                         | `fr_XC`     | `fr-DZ`                   |
| ALGERIA                  | `DZ`        | 3                         | `es_XC`     | `es-DZ`                   |
| ALGERIA                  | `DZ`        | 4                         | `zh_XC`     | `zh-DZ`                   |
| ANDORRA                  | `AD`        | 0                         | `en_US`     | `en-AD`                   |
| ANDORRA                  | `AD`        | 1                         | `fr_XC`     | `fr-AD`                   |
| ANDORRA                  | `AD`        | 2                         | `es_XC`     | `es-AD`                   |
| ANDORRA                  | `AD`        | 3                         | `zh_XC`     | `zh-AD`                   |
| ANGOLA                   | `AO`        | 0                         | `en_US`     | `en-AO`                   |
| ANGOLA                   | `AO`        | 1                         | `fr_XC`     | `fr-AO`                   |
| ANGOLA                   | `AO`        | 2                         | `es_XC`     | `es-AO`                   |
| ANGOLA                   | `AO`        | 3                         | `zh_XC`     | `zh-AO`                   |
| ANGUILLA                 | `AI`        | 0                         | `en_US`     | `en-AI`                   |
| ANGUILLA                 | `AI`        | 1                         | `fr_XC`     | `fr-AI`                   |
| ANGUILLA                 | `AI`        | 2                         | `es_XC`     | `es-AI`                   |
| ANGUILLA                 | `AI`        | 3                         | `zh_XC`     | `zh-AI`                   |
| ANTIGUA & BARBUDA        | `AG`        | 0                         | `en_US`     | `en-AG`                   |
| ANTIGUA & BARBUDA        | `AG`        | 1                         | `fr_XC`     | `fr-AG`                   |
| ANTIGUA & BARBUDA        | `AG`        | 2                         | `es_XC`     | `es-AG`                   |
| ANTIGUA & BARBUDA        | `AG`        | 3                         | `zh_XC`     | `zh-AG`                   |
| ARGENTINA                | `AR`        | 0                         | `es_XC`     | `es-AR`                   |
| ARGENTINA                | `AR`        | 1                         | `en_US`     | `en-AR`                   |
| ARMENIA                  | `AM`        | 0                         | `en_US`     | `en-AM`                   |
| ARMENIA                  | `AM`        | 1                         | `fr_XC`     | `fr-AM`                   |
| ARMENIA                  | `AM`        | 2                         | `es_XC`     | `es-AM`                   |
| ARMENIA                  | `AM`        | 3                         | `zh_XC`     | `zh-AM`                   |
| ARUBA                    | `AW`        | 0                         | `en_US`     | `en-AW`                   |
| ARUBA                    | `AW`        | 1                         | `fr_XC`     | `fr-AW`                   |
| ARUBA                    | `AW`        | 2                         | `es_XC`     | `es-AW`                   |
| ARUBA                    | `AW`        | 3                         | `zh_XC`     | `zh-AW`                   |
| AUSTRALIA                | `AU`        | 0                         | `en_AU`     | `en-AU`                   |
| AUSTRIA                  | `AT`        | 0                         | `de_DE`     | `de-AT`                   |
| AUSTRIA                  | `AT`        | 1                         | `en_US`     | `en-AT`                   |
| AZERBAIJAN               | `AZ`        | 0                         | `en_US`     | `en-AZ`                   |
| AZERBAIJAN               | `AZ`        | 1                         | `fr_XC`     | `fr-AZ`                   |
| AZERBAIJAN               | `AZ`        | 2                         | `es_XC`     | `es-AZ`                   |
| AZERBAIJAN               | `AZ`        | 3                         | `zh_XC`     | `zh-AZ`                   |
| BAHAMAS                  | `BS`        | 0                         | `en_US`     | `en-BS`                   |
| BAHAMAS                  | `BS`        | 1                         | `fr_XC`     | `fr-BS`                   |
| BAHAMAS                  | `BS`        | 2                         | `es_XC`     | `es-BS`                   |
| BAHAMAS                  | `BS`        | 3                         | `zh_XC`     | `zh-BS`                   |
| BAHRAIN                  | `BH`        | 0                         | `ar_EG`     | `ar-BH`                   |
| BAHRAIN                  | `BH`        | 1                         | `en_US`     | `en-BH`                   |
| BAHRAIN                  | `BH`        | 2                         | `fr_XC`     | `fr-BH`                   |
| BAHRAIN                  | `BH`        | 3                         | `es_XC`     | `es-BH`                   |
| BAHRAIN                  | `BH`        | 4                         | `zh_XC`     | `zh-BH`                   |
| BARBADOS                 | `BB`        | 0                         | `en_US`     | `en-BB`                   |
| BARBADOS                 | `BB`        | 1                         | `fr_XC`     | `fr-BB`                   |
| BARBADOS                 | `BB`        | 2                         | `es_XC`     | `es-BB`                   |
| BARBADOS                 | `BB`        | 3                         | `zh_XC`     | `zh-BB`                   |
| BELARUS                  | `BY`        | 0                         | `en_US`     | `en-BY`                   |
| BELGIUM                  | `BE`        | 0                         | `en_US`     | `en-BE`                   |
| BELGIUM                  | `BE`        | 1                         | `nl_NL`     | `nl-BE`                   |
| BELGIUM                  | `BE`        | 2                         | `fr_FR`     | `fr-BE`                   |
| BELIZE                   | `BZ`        | 0                         | `es_XC`     | `es-BZ`                   |
| BELIZE                   | `BZ`        | 1                         | `en_US`     | `en-BZ`                   |
| BELIZE                   | `BZ`        | 2                         | `fr_XC`     | `fr-BZ`                   |
| BELIZE                   | `BZ`        | 3                         | `zh_XC`     | `zh-BZ`                   |
| BENIN                    | `BJ`        | 0                         | `fr_XC`     | `fr-BJ`                   |
| BENIN                    | `BJ`        | 1                         | `en_US`     | `en-BJ`                   |
| BENIN                    | `BJ`        | 2                         | `es_XC`     | `es-BJ`                   |
| BENIN                    | `BJ`        | 3                         | `zh_XC`     | `zh-BJ`                   |
| BERMUDA                  | `BM`        | 0                         | `en_US`     | `en-BM`                   |
| BERMUDA                  | `BM`        | 1                         | `fr_XC`     | `fr-BM`                   |
| BERMUDA                  | `BM`        | 2                         | `es_XC`     | `es-BM`                   |
| BERMUDA                  | `BM`        | 3                         | `zh_XC`     | `zh-BM`                   |
| BHUTAN                   | `BT`        | 0                         | `en_US`     | `en-BT`                   |
| BOLIVIA                  | `BO`        | 0                         | `es_XC`     | `es-BO`                   |
| BOLIVIA                  | `BO`        | 1                         | `en_US`     | `en-BO`                   |
| BOLIVIA                  | `BO`        | 2                         | `fr_XC`     | `fr-BO`                   |
| BOLIVIA                  | `BO`        | 3                         | `zh_XC`     | `zh-BO`                   |
| BOSNIA & HERZEGOVINA     | `BA`        | 0                         | `en_US`     | `en-BA`                   |
| BOTSWANA                 | `BW`        | 0                         | `en_US`     | `en-BW`                   |
| BOTSWANA                 | `BW`        | 1                         | `fr_XC`     | `fr-BW`                   |
| BOTSWANA                 | `BW`        | 2                         | `es_XC`     | `es-BW`                   |
| BOTSWANA                 | `BW`        | 3                         | `zh_XC`     | `zh-BW`                   |
| BRAZIL                   | `BR`        | 0                         | `pt_BR`     | `pt-BR`                   |
| BRAZIL                   | `BR`        | 1                         | `en_US`     | `en-BR`                   |
| BRITISH VIRGIN ISLANDS   | `VG`        | 0                         | `en_US`     | `en-VG`                   |
| BRITISH VIRGIN ISLANDS   | `VG`        | 1                         | `fr_XC`     | `fr-VG`                   |
| BRITISH VIRGIN ISLANDS   | `VG`        | 2                         | `es_XC`     | `es-VG`                   |
| BRITISH VIRGIN ISLANDS   | `VG`        | 3                         | `zh_XC`     | `zh-VG`                   |
| BRUNEI                   | `BN`        | 0                         | `en_US`     | `en-BN`                   |
| BULGARIA                 | `BG`        | 0                         | `en_US`     | `en-BG`                   |
| BURKINA FASO             | `BF`        | 0                         | `fr_XC`     | `fr-BF`                   |
| BURKINA FASO             | `BF`        | 1                         | `en_US`     | `en-BF`                   |
| BURKINA FASO             | `BF`        | 2                         | `es_XC`     | `es-BF`                   |
| BURKINA FASO             | `BF`        | 3                         | `zh_XC`     | `zh-BF`                   |
| BURUNDI                  | `BI`        | 0                         | `fr_XC`     | `fr-BI`                   |
| BURUNDI                  | `BI`        | 1                         | `en_US`     | `en-BI`                   |
| BURUNDI                  | `BI`        | 2                         | `es_XC`     | `es-BI`                   |
| BURUNDI                  | `BI`        | 3                         | `zh_XC`     | `zh-BI`                   |
| CAMBODIA                 | `KH`        | 0                         | `en_US`     | `en-KH`                   |
| CAMEROON                 | `CM`        | 0                         | `fr_XC`     | `fr-CM`                   |
| CAMEROON                 | `CM`        | 1                         | `en_US`     | `en-CM`                   |
| CANADA                   | `CA`        | 0                         | `en_US`     | `en-CA`                   |
| CANADA                   | `CA`        | 1                         | `fr_CA`     | `fr-CA`                   |
| CAPE VERDE               | `CV`        | 0                         | `en_US`     | `en-CV`                   |
| CAPE VERDE               | `CV`        | 1                         | `fr_XC`     | `fr-CV`                   |
| CAPE VERDE               | `CV`        | 2                         | `es_XC`     | `es-CV`                   |
| CAPE VERDE               | `CV`        | 3                         | `zh_XC`     | `zh-CV`                   |
| CAYMAN ISLANDS           | `KY`        | 0                         | `en_US`     | `en-KY`                   |
| CAYMAN ISLANDS           | `KY`        | 1                         | `fr_XC`     | `fr-KY`                   |
| CAYMAN ISLANDS           | `KY`        | 2                         | `es_XC`     | `es-KY`                   |
| CAYMAN ISLANDS           | `KY`        | 3                         | `zh_XC`     | `zh-KY`                   |
| CHAD                     | `TD`        | 0                         | `fr_XC`     | `fr-TD`                   |
| CHAD                     | `TD`        | 1                         | `en_US`     | `en-TD`                   |
| CHAD                     | `TD`        | 2                         | `es_XC`     | `es-TD`                   |
| CHAD                     | `TD`        | 3                         | `zh_XC`     | `zh-TD`                   |
| CHILE                    | `CL`        | 0                         | `es_XC`     | `es-CL`                   |
| CHILE                    | `CL`        | 1                         | `en_US`     | `en-CL`                   |
| CHILE                    | `CL`        | 2                         | `fr_XC`     | `fr-CL`                   |
| CHILE                    | `CL`        | 3                         | `zh_XC`     | `zh-CL`                   |
| CHINA                    | `CN`        | 0                         | `zh_CN`     | `zh-CN`                   |
| CHINA WORLDWIDE          | `C2`        | 0                         | `zh_XC`     | `zh-CN`                   |
| CHINA WORLDWIDE          | `C2`        | 1                         | `en_US`     | `en-CN`                   |
| COLOMBIA                 | `CO`        | 0                         | `es_XC`     | `es-CO`                   |
| COLOMBIA                 | `CO`        | 1                         | `en_US`     | `en-CO`                   |
| COLOMBIA                 | `CO`        | 2                         | `fr_XC`     | `fr-CO`                   |
| COLOMBIA                 | `CO`        | 3                         | `zh_XC`     | `zh-CO`                   |
| COMOROS                  | `KM`        | 0                         | `fr_XC`     | `fr-KM`                   |
| COMOROS                  | `KM`        | 1                         | `en_US`     | `en-KM`                   |
| COMOROS                  | `KM`        | 2                         | `es_XC`     | `es-KM`                   |
| COMOROS                  | `KM`        | 3                         | `zh_XC`     | `zh-KM`                   |
| CONGO - BRAZZAVILLE      | `CG`        | 0                         | `en_US`     | `en-CG`                   |
| CONGO - BRAZZAVILLE      | `CG`        | 1                         | `fr_XC`     | `fr-CG`                   |
| CONGO - BRAZZAVILLE      | `CG`        | 2                         | `es_XC`     | `es-CG`                   |
| CONGO - BRAZZAVILLE      | `CG`        | 3                         | `zh_XC`     | `zh-CG`                   |
| CONGO - KINSHASA         | `CD`        | 0                         | `fr_XC`     | `fr-CD`                   |
| CONGO - KINSHASA         | `CD`        | 1                         | `en_US`     | `en-CD`                   |
| CONGO - KINSHASA         | `CD`        | 2                         | `es_XC`     | `es-CD`                   |
| CONGO - KINSHASA         | `CD`        | 3                         | `zh_XC`     | `zh-CD`                   |
| COOK ISLANDS             | `CK`        | 0                         | `en_US`     | `en-CK`                   |
| COOK ISLANDS             | `CK`        | 1                         | `fr_XC`     | `fr-CK`                   |
| COOK ISLANDS             | `CK`        | 2                         | `es_XC`     | `es-CK`                   |
| COOK ISLANDS             | `CK`        | 3                         | `zh_XC`     | `zh-CK`                   |
| COSTA RICA               | `CR`        | 0                         | `es_XC`     | `es-CR`                   |
| COSTA RICA               | `CR`        | 1                         | `en_US`     | `en-CR`                   |
| COSTA RICA               | `CR`        | 2                         | `fr_XC`     | `fr-CR`                   |
| COSTA RICA               | `CR`        | 3                         | `zh_XC`     | `zh-CR`                   |
| CÔTE D’IVOIRE            | `CI`        | 0                         | `fr_XC`     | `fr-CI`                   |
| CÔTE D’IVOIRE            | `CI`        | 1                         | `en_US`     | `en-CI`                   |
| CROATIA                  | `HR`        | 0                         | `en_US`     | `en-HR`                   |
| CYPRUS                   | `CY`        | 0                         | `en_US`     | `en-CY`                   |
| CZECH REPUBLIC           | `CZ`        | 0                         | `cs_CZ`     | `cs-CZ`                   |
| CZECH REPUBLIC           | `CZ`        | 1                         | `en_US`     | `en-CZ`                   |
| CZECH REPUBLIC           | `CZ`        | 2                         | `fr_XC`     | `fr-CZ`                   |
| CZECH REPUBLIC           | `CZ`        | 3                         | `es_XC`     | `es-CZ`                   |
| CZECH REPUBLIC           | `CZ`        | 4                         | `zh_XC`     | `zh-CZ`                   |
| DENMARK                  | `DK`        | 0                         | `da_DK`     | `da-DK`                   |
| DENMARK                  | `DK`        | 1                         | `en_US`     | `en-DK`                   |
| DJIBOUTI                 | `DJ`        | 0                         | `fr_XC`     | `fr-DJ`                   |
| DJIBOUTI                 | `DJ`        | 1                         | `en_US`     | `en-DJ`                   |
| DJIBOUTI                 | `DJ`        | 2                         | `es_XC`     | `es-DJ`                   |
| DJIBOUTI                 | `DJ`        | 3                         | `zh_XC`     | `zh-DJ`                   |
| DOMINICA                 | `DM`        | 0                         | `en_US`     | `en-DM`                   |
| DOMINICA                 | `DM`        | 1                         | `fr_XC`     | `fr-DM`                   |
| DOMINICA                 | `DM`        | 2                         | `es_XC`     | `es-DM`                   |
| DOMINICA                 | `DM`        | 3                         | `zh_XC`     | `zh-DM`                   |
| DOMINICAN REPUBLIC       | `DO`        | 0                         | `es_XC`     | `es-DO`                   |
| DOMINICAN REPUBLIC       | `DO`        | 1                         | `en_US`     | `en-DO`                   |
| DOMINICAN REPUBLIC       | `DO`        | 2                         | `fr_XC`     | `fr-DO`                   |
| DOMINICAN REPUBLIC       | `DO`        | 3                         | `zh_XC`     | `zh-DO`                   |
| ECUADOR                  | `EC`        | 0                         | `es_XC`     | `es-EC`                   |
| ECUADOR                  | `EC`        | 1                         | `en_US`     | `en-EC`                   |
| ECUADOR                  | `EC`        | 2                         | `fr_XC`     | `fr-EC`                   |
| ECUADOR                  | `EC`        | 3                         | `zh_XC`     | `zh-EC`                   |
| EGYPT                    | `EG`        | 0                         | `ar_EG`     | `ar-EG`                   |
| EGYPT                    | `EG`        | 1                         | `en_US`     | `en-EG`                   |
| EGYPT                    | `EG`        | 2                         | `fr_XC`     | `fr-EG`                   |
| EGYPT                    | `EG`        | 3                         | `es_XC`     | `es-EG`                   |
| EGYPT                    | `EG`        | 4                         | `zh_XC`     | `zh-EG`                   |
| EL SALVADOR              | `SV`        | 0                         | `es_XC`     | `es-SV`                   |
| EL SALVADOR              | `SV`        | 1                         | `en_US`     | `en-SV`                   |
| EL SALVADOR              | `SV`        | 2                         | `fr_XC`     | `fr-SV`                   |
| EL SALVADOR              | `SV`        | 3                         | `zh_XC`     | `zh-SV`                   |
| ERITREA                  | `ER`        | 0                         | `en_US`     | `en-ER`                   |
| ERITREA                  | `ER`        | 1                         | `fr_XC`     | `fr-ER`                   |
| ERITREA                  | `ER`        | 2                         | `es_XC`     | `es-ER`                   |
| ERITREA                  | `ER`        | 3                         | `zh_XC`     | `zh-ER`                   |
| ESTONIA                  | `EE`        | 0                         | `en_US`     | `en-EE`                   |
| ESTONIA                  | `EE`        | 1                         | `ru_RU`     | `ru-EE`                   |
| ESTONIA                  | `EE`        | 2                         | `fr_XC`     | `fr-EE`                   |
| ESTONIA                  | `EE`        | 3                         | `es_XC`     | `es-EE`                   |
| ESTONIA                  | `EE`        | 4                         | `zh_XC`     | `zh-EE`                   |
| ETHIOPIA                 | `ET`        | 0                         | `en_US`     | `en-ET`                   |
| ETHIOPIA                 | `ET`        | 1                         | `fr_XC`     | `fr-ET`                   |
| ETHIOPIA                 | `ET`        | 2                         | `es_XC`     | `es-ET`                   |
| ETHIOPIA                 | `ET`        | 3                         | `zh_XC`     | `zh-ET`                   |
| FALKLAND ISLANDS         | `FK`        | 0                         | `en_US`     | `en-FK`                   |
| FALKLAND ISLANDS         | `FK`        | 1                         | `fr_XC`     | `fr-FK`                   |
| FALKLAND ISLANDS         | `FK`        | 2                         | `es_XC`     | `es-FK`                   |
| FALKLAND ISLANDS         | `FK`        | 3                         | `zh_XC`     | `zh-FK`                   |
| FAROE ISLANDS            | `FO`        | 0                         | `da_DK`     | `da-FO`                   |
| FAROE ISLANDS            | `FO`        | 1                         | `en_US`     | `en-FO`                   |
| FAROE ISLANDS            | `FO`        | 2                         | `fr_XC`     | `fr-FO`                   |
| FAROE ISLANDS            | `FO`        | 3                         | `es_XC`     | `es-FO`                   |
| FAROE ISLANDS            | `FO`        | 4                         | `zh_XC`     | `zh-FO`                   |
| FIJI                     | `FJ`        | 0                         | `en_US`     | `en-FJ`                   |
| FIJI                     | `FJ`        | 1                         | `fr_XC`     | `fr-FJ`                   |
| FIJI                     | `FJ`        | 2                         | `es_XC`     | `es-FJ`                   |
| FIJI                     | `FJ`        | 3                         | `zh_XC`     | `zh-FJ`                   |
| FINLAND                  | `FI`        | 0                         | `fi_FI`     | `fi-FI`                   |
| FINLAND                  | `FI`        | 1                         | `en_US`     | `en-FI`                   |
| FINLAND                  | `FI`        | 2                         | `fr_XC`     | `fr-FI`                   |
| FINLAND                  | `FI`        | 3                         | `es_XC`     | `es-FI`                   |
| FINLAND                  | `FI`        | 4                         | `zh_XC`     | `zh-FI`                   |
| FRANCE                   | `FR`        | 0                         | `fr_FR`     | `fr-FR`                   |
| FRANCE                   | `FR`        | 1                         | `en_US`     | `en-FR`                   |
| FRENCH GUIANA            | `GF`        | 0                         | `en_US`     | `en-GF`                   |
| FRENCH GUIANA            | `GF`        | 1                         | `fr_XC`     | `fr-GF`                   |
| FRENCH GUIANA            | `GF`        | 2                         | `es_XC`     | `es-GF`                   |
| FRENCH GUIANA            | `GF`        | 3                         | `zh_XC`     | `zh-GF`                   |
| FRENCH POLYNESIA         | `PF`        | 0                         | `en_US`     | `en-PF`                   |
| FRENCH POLYNESIA         | `PF`        | 1                         | `fr_XC`     | `fr-PF`                   |
| FRENCH POLYNESIA         | `PF`        | 2                         | `es_XC`     | `es-PF`                   |
| FRENCH POLYNESIA         | `PF`        | 3                         | `zh_XC`     | `zh-PF`                   |
| GABON                    | `GA`        | 0                         | `fr_XC`     | `fr-GA`                   |
| GABON                    | `GA`        | 1                         | `en_US`     | `en-GA`                   |
| GABON                    | `GA`        | 2                         | `es_XC`     | `es-GA`                   |
| GABON                    | `GA`        | 3                         | `zh_XC`     | `zh-GA`                   |
| GAMBIA                   | `GM`        | 0                         | `en_US`     | `en-GM`                   |
| GAMBIA                   | `GM`        | 1                         | `fr_XC`     | `fr-GM`                   |
| GAMBIA                   | `GM`        | 2                         | `es_XC`     | `es-GM`                   |
| GAMBIA                   | `GM`        | 3                         | `zh_XC`     | `zh-GM`                   |
| GEORGIA                  | `GE`        | 0                         | `en_US`     | `en-GE`                   |
| GEORGIA                  | `GE`        | 1                         | `fr_XC`     | `fr-GE`                   |
| GEORGIA                  | `GE`        | 2                         | `es_XC`     | `es-GE`                   |
| GEORGIA                  | `GE`        | 3                         | `zh_XC`     | `zh-GE`                   |
| GERMANY                  | `DE`        | 0                         | `de_DE`     | `de-DE`                   |
| GERMANY                  | `DE`        | 1                         | `en_US`     | `en-DE`                   |
| GIBRALTAR                | `GI`        | 0                         | `en_US`     | `en-GI`                   |
| GIBRALTAR                | `GI`        | 1                         | `fr_XC`     | `fr-GI`                   |
| GIBRALTAR                | `GI`        | 2                         | `es_XC`     | `es-GI`                   |
| GIBRALTAR                | `GI`        | 3                         | `zh_XC`     | `zh-GI`                   |
| GREECE                   | `GR`        | 0                         | `el_GR`     | `el-GR`                   |
| GREECE                   | `GR`        | 1                         | `en_US`     | `en-GR`                   |
| GREECE                   | `GR`        | 2                         | `fr_XC`     | `fr-GR`                   |
| GREECE                   | `GR`        | 3                         | `es_XC`     | `es-GR`                   |
| GREECE                   | `GR`        | 4                         | `zh_XC`     | `zh-GR`                   |
| GREENLAND                | `GL`        | 0                         | `da_DK`     | `da-GL`                   |
| GREENLAND                | `GL`        | 1                         | `en_US`     | `en-GL`                   |
| GREENLAND                | `GL`        | 2                         | `fr_XC`     | `fr-GL`                   |
| GREENLAND                | `GL`        | 3                         | `es_XC`     | `es-GL`                   |
| GREENLAND                | `GL`        | 4                         | `zh_XC`     | `zh-GL`                   |
| GRENADA                  | `GD`        | 0                         | `en_US`     | `en-GD`                   |
| GRENADA                  | `GD`        | 1                         | `fr_XC`     | `fr-GD`                   |
| GRENADA                  | `GD`        | 2                         | `es_XC`     | `es-GD`                   |
| GRENADA                  | `GD`        | 3                         | `zh_XC`     | `zh-GD`                   |
| GUADELOUPE               | `GP`        | 0                         | `en_US`     | `en-GP`                   |
| GUADELOUPE               | `GP`        | 1                         | `fr_XC`     | `fr-GP`                   |
| GUADELOUPE               | `GP`        | 2                         | `es_XC`     | `es-GP`                   |
| GUADELOUPE               | `GP`        | 3                         | `zh_XC`     | `zh-GP`                   |
| GUATEMALA                | `GT`        | 0                         | `es_XC`     | `es-GT`                   |
| GUATEMALA                | `GT`        | 1                         | `en_US`     | `en-GT`                   |
| GUATEMALA                | `GT`        | 2                         | `fr_XC`     | `fr-GT`                   |
| GUATEMALA                | `GT`        | 3                         | `zh_XC`     | `zh-GT`                   |
| GUINEA                   | `GN`        | 0                         | `fr_XC`     | `fr-GN`                   |
| GUINEA                   | `GN`        | 1                         | `en_US`     | `en-GN`                   |
| GUINEA                   | `GN`        | 2                         | `es_XC`     | `es-GN`                   |
| GUINEA                   | `GN`        | 3                         | `zh_XC`     | `zh-GN`                   |
| GUINEA-BISSAU            | `GW`        | 0                         | `en_US`     | `en-GW`                   |
| GUINEA-BISSAU            | `GW`        | 1                         | `fr_XC`     | `fr-GW`                   |
| GUINEA-BISSAU            | `GW`        | 2                         | `es_XC`     | `es-GW`                   |
| GUINEA-BISSAU            | `GW`        | 3                         | `zh_XC`     | `zh-GW`                   |
| GUYANA                   | `GY`        | 0                         | `en_US`     | `en-GY`                   |
| GUYANA                   | `GY`        | 1                         | `fr_XC`     | `fr-GY`                   |
| GUYANA                   | `GY`        | 2                         | `es_XC`     | `es-GY`                   |
| GUYANA                   | `GY`        | 3                         | `zh_XC`     | `zh-GY`                   |
| HONDURAS                 | `HN`        | 0                         | `es_XC`     | `es-HN`                   |
| HONDURAS                 | `HN`        | 1                         | `en_US`     | `en-HN`                   |
| HONDURAS                 | `HN`        | 2                         | `fr_XC`     | `fr-HN`                   |
| HONDURAS                 | `HN`        | 3                         | `zh_XC`     | `zh-HN`                   |
| HONG KONG SAR CHINA      | `HK`        | 0                         | `en_GB`     | `en-HK`                   |
| HONG KONG SAR CHINA      | `HK`        | 1                         | `zh_HK`     | `zh-HK`                   |
| HUNGARY                  | `HU`        | 0                         | `hu_HU`     | `hu-HU`                   |
| HUNGARY                  | `HU`        | 1                         | `en_US`     | `en-HU`                   |
| HUNGARY                  | `HU`        | 2                         | `fr_XC`     | `fr-HU`                   |
| HUNGARY                  | `HU`        | 3                         | `es_XC`     | `es-HU`                   |
| HUNGARY                  | `HU`        | 4                         | `zh_XC`     | `zh-HU`                   |
| ICELAND                  | `IS`        | 0                         | `en_US`     | `en-IS`                   |
| INDIA                    | `IN`        | 0                         | `en_IN`     | `en-IN`                   |
| INDONESIA                | `ID`        | 0                         | `id_ID`     | `id-ID`                   |
| INDONESIA                | `ID`        | 1                         | `en_US`     | `en-ID`                   |
| IRELAND                  | `IE`        | 0                         | `en_US`     | `en-IE`                   |
| IRELAND                  | `IE`        | 1                         | `fr_XC`     | `fr-IE`                   |
| IRELAND                  | `IE`        | 2                         | `es_XC`     | `es-IE`                   |
| IRELAND                  | `IE`        | 3                         | `zh_XC`     | `zh-IE`                   |
| ISRAEL                   | `IL`        | 0                         | `he_IL`     | `he-IL`                   |
| ISRAEL                   | `IL`        | 1                         | `en_US`     | `en-IL`                   |
| ITALY                    | `IT`        | 0                         | `it_IT`     | `it-IT`                   |
| ITALY                    | `IT`        | 1                         | `en_US`     | `en-IT`                   |
| JAMAICA                  | `JM`        | 0                         | `es_XC`     | `es-JM`                   |
| JAMAICA                  | `JM`        | 1                         | `en_US`     | `en-JM`                   |
| JAMAICA                  | `JM`        | 2                         | `fr_XC`     | `fr-JM`                   |
| JAMAICA                  | `JM`        | 3                         | `zh_XC`     | `zh-JM`                   |
| JAPAN                    | `JP`        | 0                         | `ja_JP`     | `ja-JP`                   |
| JAPAN                    | `JP`        | 1                         | `en_US`     | `en-JP`                   |
| JORDAN                   | `JO`        | 0                         | `ar_EG`     | `ar-JO`                   |
| JORDAN                   | `JO`        | 1                         | `en_US`     | `en-JO`                   |
| JORDAN                   | `JO`        | 2                         | `fr_XC`     | `fr-JO`                   |
| JORDAN                   | `JO`        | 3                         | `es_XC`     | `es-JO`                   |
| JORDAN                   | `JO`        | 4                         | `zh_XC`     | `zh-JO`                   |
| KAZAKHSTAN               | `KZ`        | 0                         | `en_US`     | `en-KZ`                   |
| KAZAKHSTAN               | `KZ`        | 1                         | `fr_XC`     | `fr-KZ`                   |
| KAZAKHSTAN               | `KZ`        | 2                         | `es_XC`     | `es-KZ`                   |
| KAZAKHSTAN               | `KZ`        | 3                         | `zh_XC`     | `zh-KZ`                   |
| KENYA                    | `KE`        | 0                         | `en_US`     | `en-KE`                   |
| KENYA                    | `KE`        | 1                         | `fr_XC`     | `fr-KE`                   |
| KENYA                    | `KE`        | 2                         | `es_XC`     | `es-KE`                   |
| KENYA                    | `KE`        | 3                         | `zh_XC`     | `zh-KE`                   |
| KIRIBATI                 | `KI`        | 0                         | `en_US`     | `en-KI`                   |
| KIRIBATI                 | `KI`        | 1                         | `fr_XC`     | `fr-KI`                   |
| KIRIBATI                 | `KI`        | 2                         | `es_XC`     | `es-KI`                   |
| KIRIBATI                 | `KI`        | 3                         | `zh_XC`     | `zh-KI`                   |
| KUWAIT                   | `KW`        | 0                         | `ar_EG`     | `ar-KW`                   |
| KUWAIT                   | `KW`        | 1                         | `en_US`     | `en-KW`                   |
| KUWAIT                   | `KW`        | 2                         | `fr_XC`     | `fr-KW`                   |
| KUWAIT                   | `KW`        | 3                         | `es_XC`     | `es-KW`                   |
| KUWAIT                   | `KW`        | 4                         | `zh_XC`     | `zh-KW`                   |
| KYRGYZSTAN               | `KG`        | 0                         | `en_US`     | `en-KG`                   |
| KYRGYZSTAN               | `KG`        | 1                         | `fr_XC`     | `fr-KG`                   |
| KYRGYZSTAN               | `KG`        | 2                         | `es_XC`     | `es-KG`                   |
| KYRGYZSTAN               | `KG`        | 3                         | `zh_XC`     | `zh-KG`                   |
| LAOS                     | `LA`        | 0                         | `en_US`     | `en-LA`                   |
| LATVIA                   | `LV`        | 0                         | `en_US`     | `en-LV`                   |
| LATVIA                   | `LV`        | 1                         | `ru_RU`     | `ru-LV`                   |
| LATVIA                   | `LV`        | 2                         | `fr_XC`     | `fr-LV`                   |
| LATVIA                   | `LV`        | 3                         | `es_XC`     | `es-LV`                   |
| LATVIA                   | `LV`        | 4                         | `zh_XC`     | `zh-LV`                   |
| LESOTHO                  | `LS`        | 0                         | `en_US`     | `en-LS`                   |
| LESOTHO                  | `LS`        | 1                         | `fr_XC`     | `fr-LS`                   |
| LESOTHO                  | `LS`        | 2                         | `es_XC`     | `es-LS`                   |
| LESOTHO                  | `LS`        | 3                         | `zh_XC`     | `zh-LS`                   |
| LIECHTENSTEIN            | `LI`        | 0                         | `en_US`     | `en-LI`                   |
| LIECHTENSTEIN            | `LI`        | 1                         | `fr_XC`     | `fr-LI`                   |
| LIECHTENSTEIN            | `LI`        | 2                         | `es_XC`     | `es-LI`                   |
| LIECHTENSTEIN            | `LI`        | 3                         | `zh_XC`     | `zh-LI`                   |
| LITHUANIA                | `LT`        | 0                         | `en_US`     | `en-LT`                   |
| LITHUANIA                | `LT`        | 1                         | `ru_RU`     | `ru-LT`                   |
| LITHUANIA                | `LT`        | 2                         | `fr_XC`     | `fr-LT`                   |
| LITHUANIA                | `LT`        | 3                         | `es_XC`     | `es-LT`                   |
| LITHUANIA                | `LT`        | 4                         | `zh_XC`     | `zh-LT`                   |
| LUXEMBOURG               | `LU`        | 0                         | `en_US`     | `en-LU`                   |
| LUXEMBOURG               | `LU`        | 1                         | `de_DE`     | `de-LU`                   |
| LUXEMBOURG               | `LU`        | 2                         | `fr_XC`     | `fr-LU`                   |
| LUXEMBOURG               | `LU`        | 3                         | `es_XC`     | `es-LU`                   |
| LUXEMBOURG               | `LU`        | 4                         | `zh_XC`     | `zh-LU`                   |
| MACEDONIA                | `MK`        | 0                         | `en_US`     | `en-MK`                   |
| MADAGASCAR               | `MG`        | 0                         | `en_US`     | `en-MG`                   |
| MADAGASCAR               | `MG`        | 1                         | `fr_XC`     | `fr-MG`                   |
| MADAGASCAR               | `MG`        | 2                         | `es_XC`     | `es-MG`                   |
| MADAGASCAR               | `MG`        | 3                         | `zh_XC`     | `zh-MG`                   |
| MALAWI                   | `MW`        | 0                         | `en_US`     | `en-MW`                   |
| MALAWI                   | `MW`        | 1                         | `fr_XC`     | `fr-MW`                   |
| MALAWI                   | `MW`        | 2                         | `es_XC`     | `es-MW`                   |
| MALAWI                   | `MW`        | 3                         | `zh_XC`     | `zh-MW`                   |
| MALAYSIA                 | `MY`        | 0                         | `en_US`     | `en-MY`                   |
| MALDIVES                 | `MV`        | 0                         | `en_US`     | `en-MV`                   |
| MALI                     | `ML`        | 0                         | `fr_XC`     | `fr-ML`                   |
| MALI                     | `ML`        | 1                         | `en_US`     | `en-ML`                   |
| MALI                     | `ML`        | 2                         | `es_XC`     | `es-ML`                   |
| MALI                     | `ML`        | 3                         | `zh_XC`     | `zh-ML`                   |
| MALTA                    | `MT`        | 0                         | `en_US`     | `en-MT`                   |
| MARSHALL ISLANDS         | `MH`        | 0                         | `en_US`     | `en-MH`                   |
| MARSHALL ISLANDS         | `MH`        | 1                         | `fr_XC`     | `fr-MH`                   |
| MARSHALL ISLANDS         | `MH`        | 2                         | `es_XC`     | `es-MH`                   |
| MARSHALL ISLANDS         | `MH`        | 3                         | `zh_XC`     | `zh-MH`                   |
| MARTINIQUE               | `MQ`        | 0                         | `en_US`     | `en-MQ`                   |
| MARTINIQUE               | `MQ`        | 1                         | `fr_XC`     | `fr-MQ`                   |
| MARTINIQUE               | `MQ`        | 2                         | `es_XC`     | `es-MQ`                   |
| MARTINIQUE               | `MQ`        | 3                         | `zh_XC`     | `zh-MQ`                   |
| MAURITANIA               | `MR`        | 0                         | `en_US`     | `en-MR`                   |
| MAURITANIA               | `MR`        | 1                         | `fr_XC`     | `fr-MR`                   |
| MAURITANIA               | `MR`        | 2                         | `es_XC`     | `es-MR`                   |
| MAURITANIA               | `MR`        | 3                         | `zh_XC`     | `zh-MR`                   |
| MAURITIUS                | `MU`        | 0                         | `en_US`     | `en-MU`                   |
| MAURITIUS                | `MU`        | 1                         | `fr_XC`     | `fr-MU`                   |
| MAURITIUS                | `MU`        | 2                         | `es_XC`     | `es-MU`                   |
| MAURITIUS                | `MU`        | 3                         | `zh_XC`     | `zh-MU`                   |
| MAYOTTE                  | `YT`        | 0                         | `en_US`     | `en-YT`                   |
| MAYOTTE                  | `YT`        | 1                         | `fr_XC`     | `fr-YT`                   |
| MAYOTTE                  | `YT`        | 2                         | `es_XC`     | `es-YT`                   |
| MAYOTTE                  | `YT`        | 3                         | `zh_XC`     | `zh-YT`                   |
| MEXICO                   | `MX`        | 0                         | `es_XC`     | `es-MX`                   |
| MEXICO                   | `MX`        | 1                         | `en_US`     | `en-MX`                   |
| MICRONESIA               | `FM`        | 0                         | `en_US`     | `en-FM`                   |
| MOLDOVA                  | `MD`        | 0                         | `en_US`     | `en-MD`                   |
| MONACO                   | `MC`        | 0                         | `fr_XC`     | `fr-MC`                   |
| MONACO                   | `MC`        | 1                         | `en_US`     | `en-MC`                   |
| MONGOLIA                 | `MN`        | 0                         | `en_US`     | `en-MN`                   |
| MONTENEGRO               | `ME`        | 0                         | `en_US`     | `en-ME`                   |
| MONTSERRAT               | `MS`        | 0                         | `en_US`     | `en-MS`                   |
| MONTSERRAT               | `MS`        | 1                         | `fr_XC`     | `fr-MS`                   |
| MONTSERRAT               | `MS`        | 2                         | `es_XC`     | `es-MS`                   |
| MONTSERRAT               | `MS`        | 3                         | `zh_XC`     | `zh-MS`                   |
| MOROCCO                  | `MA`        | 0                         | `ar_EG`     | `ar-MA`                   |
| MOROCCO                  | `MA`        | 1                         | `en_US`     | `en-MA`                   |
| MOROCCO                  | `MA`        | 2                         | `fr_XC`     | `fr-MA`                   |
| MOROCCO                  | `MA`        | 3                         | `es_XC`     | `es-MA`                   |
| MOROCCO                  | `MA`        | 4                         | `zh_XC`     | `zh-MA`                   |
| MOZAMBIQUE               | `MZ`        | 0                         | `en_US`     | `en-MZ`                   |
| MOZAMBIQUE               | `MZ`        | 1                         | `fr_XC`     | `fr-MZ`                   |
| MOZAMBIQUE               | `MZ`        | 2                         | `es_XC`     | `es-MZ`                   |
| MOZAMBIQUE               | `MZ`        | 3                         | `zh_XC`     | `zh-MZ`                   |
| NAMIBIA                  | `NA`        | 0                         | `en_US`     | `en-NA`                   |
| NAMIBIA                  | `NA`        | 1                         | `fr_XC`     | `fr-NA`                   |
| NAMIBIA                  | `NA`        | 2                         | `es_XC`     | `es-NA`                   |
| NAMIBIA                  | `NA`        | 3                         | `zh_XC`     | `zh-NA`                   |
| NAURU                    | `NR`        | 0                         | `en_US`     | `en-NR`                   |
| NAURU                    | `NR`        | 1                         | `fr_XC`     | `fr-NR`                   |
| NAURU                    | `NR`        | 2                         | `es_XC`     | `es-NR`                   |
| NAURU                    | `NR`        | 3                         | `zh_XC`     | `zh-NR`                   |
| NEPAL                    | `NP`        | 0                         | `en_US`     | `en-NP`                   |
| NETHERLANDS              | `NL`        | 0                         | `nl_NL`     | `nl-NL`                   |
| NETHERLANDS              | `NL`        | 1                         | `en_US`     | `en-NL`                   |
| NEW CALEDONIA            | `NC`        | 0                         | `en_US`     | `en-NC`                   |
| NEW CALEDONIA            | `NC`        | 1                         | `fr_XC`     | `fr-NC`                   |
| NEW CALEDONIA            | `NC`        | 2                         | `es_XC`     | `es-NC`                   |
| NEW CALEDONIA            | `NC`        | 3                         | `zh_XC`     | `zh-NC`                   |
| NEW ZEALAND              | `NZ`        | 0                         | `en_US`     | `en-NZ`                   |
| NEW ZEALAND              | `NZ`        | 1                         | `fr_XC`     | `fr-NZ`                   |
| NEW ZEALAND              | `NZ`        | 2                         | `es_XC`     | `es-NZ`                   |
| NEW ZEALAND              | `NZ`        | 3                         | `zh_XC`     | `zh-NZ`                   |
| NICARAGUA                | `NI`        | 0                         | `es_XC`     | `es-NI`                   |
| NICARAGUA                | `NI`        | 1                         | `en_US`     | `en-NI`                   |
| NICARAGUA                | `NI`        | 2                         | `fr_XC`     | `fr-NI`                   |
| NICARAGUA                | `NI`        | 3                         | `zh_XC`     | `zh-NI`                   |
| NIGER                    | `NE`        | 0                         | `fr_XC`     | `fr-NE`                   |
| NIGER                    | `NE`        | 1                         | `en_US`     | `en-NE`                   |
| NIGER                    | `NE`        | 2                         | `es_XC`     | `es-NE`                   |
| NIGER                    | `NE`        | 3                         | `zh_XC`     | `zh-NE`                   |
| NIGERIA                  | `NG`        | 0                         | `en_US`     | `en-NG`                   |
| NIUE                     | `NU`        | 0                         | `en_US`     | `en-NU`                   |
| NIUE                     | `NU`        | 1                         | `fr_XC`     | `fr-NU`                   |
| NIUE                     | `NU`        | 2                         | `es_XC`     | `es-NU`                   |
| NIUE                     | `NU`        | 3                         | `zh_XC`     | `zh-NU`                   |
| NORFOLK ISLAND           | `NF`        | 0                         | `en_US`     | `en-NF`                   |
| NORFOLK ISLAND           | `NF`        | 1                         | `fr_XC`     | `fr-NF`                   |
| NORFOLK ISLAND           | `NF`        | 2                         | `es_XC`     | `es-NF`                   |
| NORFOLK ISLAND           | `NF`        | 3                         | `zh_XC`     | `zh-NF`                   |
| NORWAY                   | `NO`        | 0                         | `no_NO`     | `no-NO`                   |
| NORWAY                   | `NO`        | 1                         | `en_US`     | `en-NO`                   |
| OMAN                     | `OM`        | 0                         | `ar_EG`     | `ar-OM`                   |
| OMAN                     | `OM`        | 1                         | `en_US`     | `en-OM`                   |
| OMAN                     | `OM`        | 2                         | `fr_XC`     | `fr-OM`                   |
| OMAN                     | `OM`        | 3                         | `es_XC`     | `es-OM`                   |
| OMAN                     | `OM`        | 4                         | `zh_XC`     | `zh-OM`                   |
| PALAU                    | `PW`        | 0                         | `en_US`     | `en-PW`                   |
| PALAU                    | `PW`        | 1                         | `fr_XC`     | `fr-PW`                   |
| PALAU                    | `PW`        | 2                         | `es_XC`     | `es-PW`                   |
| PALAU                    | `PW`        | 3                         | `zh_XC`     | `zh-PW`                   |
| PANAMA                   | `PA`        | 0                         | `es_XC`     | `es-PA`                   |
| PANAMA                   | `PA`        | 1                         | `en_US`     | `en-PA`                   |
| PANAMA                   | `PA`        | 2                         | `fr_XC`     | `fr-PA`                   |
| PANAMA                   | `PA`        | 3                         | `zh_XC`     | `zh-PA`                   |
| PAPUA NEW GUINEA         | `PG`        | 0                         | `en_US`     | `en-PG`                   |
| PAPUA NEW GUINEA         | `PG`        | 1                         | `fr_XC`     | `fr-PG`                   |
| PAPUA NEW GUINEA         | `PG`        | 2                         | `es_XC`     | `es-PG`                   |
| PAPUA NEW GUINEA         | `PG`        | 3                         | `zh_XC`     | `zh-PG`                   |
| PARAGUAY                 | `PY`        | 0                         | `es_XC`     | `es-PY`                   |
| PARAGUAY                 | `PY`        | 1                         | `en_US`     | `en-PY`                   |
| PERU                     | `PE`        | 0                         | `es_XC`     | `es-PE`                   |
| PERU                     | `PE`        | 1                         | `en_US`     | `en-PE`                   |
| PERU                     | `PE`        | 2                         | `fr_XC`     | `fr-PE`                   |
| PERU                     | `PE`        | 3                         | `zh_XC`     | `zh-PE`                   |
| PHILIPPINES              | `PH`        | 0                         | `en_US`     | `en-PH`                   |
| PITCAIRN ISLANDS         | `PN`        | 0                         | `en_US`     | `en-PN`                   |
| PITCAIRN ISLANDS         | `PN`        | 1                         | `fr_XC`     | `fr-PN`                   |
| PITCAIRN ISLANDS         | `PN`        | 2                         | `es_XC`     | `es-PN`                   |
| PITCAIRN ISLANDS         | `PN`        | 3                         | `zh_XC`     | `zh-PN`                   |
| POLAND                   | `PL`        | 0                         | `pl_PL`     | `pl-PL`                   |
| POLAND                   | `PL`        | 1                         | `en_US`     | `en-PL`                   |
| PORTUGAL                 | `PT`        | 0                         | `pt_PT`     | `pt-PT`                   |
| PORTUGAL                 | `PT`        | 1                         | `en_US`     | `en-PT`                   |
| QATAR                    | `QA`        | 0                         | `en_US`     | `en-QA`                   |
| QATAR                    | `QA`        | 1                         | `fr_XC`     | `fr-QA`                   |
| QATAR                    | `QA`        | 2                         | `es_XC`     | `es-QA`                   |
| QATAR                    | `QA`        | 3                         | `zh_XC`     | `zh-QA`                   |
| QATAR                    | `QA`        | 4                         | `ar_EG`     | `ar-QA`                   |
| RÉUNION                  | `RE`        | 0                         | `en_US`     | `en-RE`                   |
| RÉUNION                  | `RE`        | 1                         | `fr_XC`     | `fr-RE`                   |
| RÉUNION                  | `RE`        | 2                         | `es_XC`     | `es-RE`                   |
| RÉUNION                  | `RE`        | 3                         | `zh_XC`     | `zh-RE`                   |
| ROMANIA                  | `RO`        | 0                         | `en_US`     | `en-RO`                   |
| ROMANIA                  | `RO`        | 1                         | `fr_XC`     | `fr-RO`                   |
| ROMANIA                  | `RO`        | 2                         | `es_XC`     | `es-RO`                   |
| ROMANIA                  | `RO`        | 3                         | `zh_XC`     | `zh-RO`                   |
| RUSSIA                   | `RU`        | 0                         | `ru_RU`     | `ru-RU`                   |
| RUSSIA                   | `RU`        | 1                         | `en_US`     | `en-RU`                   |
| RWANDA                   | `RW`        | 0                         | `fr_XC`     | `fr-RW`                   |
| RWANDA                   | `RW`        | 1                         | `en_US`     | `en-RW`                   |
| RWANDA                   | `RW`        | 2                         | `es_XC`     | `es-RW`                   |
| RWANDA                   | `RW`        | 3                         | `zh_XC`     | `zh-RW`                   |
| SAMOA                    | `WS`        | 0                         | `en_US`     | `en-WS`                   |
| SAN MARINO               | `SM`        | 0                         | `en_US`     | `en-SM`                   |
| SAN MARINO               | `SM`        | 1                         | `fr_XC`     | `fr-SM`                   |
| SAN MARINO               | `SM`        | 2                         | `es_XC`     | `es-SM`                   |
| SAN MARINO               | `SM`        | 3                         | `zh_XC`     | `zh-SM`                   |
| SÃO TOMÉ & PRÍNCIPE      | `ST`        | 0                         | `en_US`     | `en-ST`                   |
| SÃO TOMÉ & PRÍNCIPE      | `ST`        | 1                         | `fr_XC`     | `fr-ST`                   |
| SÃO TOMÉ & PRÍNCIPE      | `ST`        | 2                         | `es_XC`     | `es-ST`                   |
| SÃO TOMÉ & PRÍNCIPE      | `ST`        | 3                         | `zh_XC`     | `zh-ST`                   |
| SAUDI ARABIA             | `SA`        | 0                         | `ar_EG`     | `ar-SA`                   |
| SAUDI ARABIA             | `SA`        | 1                         | `en_US`     | `en-SA`                   |
| SAUDI ARABIA             | `SA`        | 2                         | `fr_XC`     | `fr-SA`                   |
| SAUDI ARABIA             | `SA`        | 3                         | `es_XC`     | `es-SA`                   |
| SAUDI ARABIA             | `SA`        | 4                         | `zh_XC`     | `zh-SA`                   |
| SENEGAL                  | `SN`        | 0                         | `fr_XC`     | `fr-SN`                   |
| SENEGAL                  | `SN`        | 1                         | `en_US`     | `en-SN`                   |
| SENEGAL                  | `SN`        | 2                         | `es_XC`     | `es-SN`                   |
| SENEGAL                  | `SN`        | 3                         | `zh_XC`     | `zh-SN`                   |
| SERBIA                   | `RS`        | 0                         | `en_US`     | `en-RS`                   |
| SERBIA                   | `RS`        | 1                         | `fr_XC`     | `fr-RS`                   |
| SERBIA                   | `RS`        | 2                         | `es_XC`     | `es-RS`                   |
| SERBIA                   | `RS`        | 3                         | `zh_XC`     | `zh-RS`                   |
| SEYCHELLES               | `SC`        | 0                         | `fr_XC`     | `fr-SC`                   |
| SEYCHELLES               | `SC`        | 1                         | `en_US`     | `en-SC`                   |
| SEYCHELLES               | `SC`        | 2                         | `es_XC`     | `es-SC`                   |
| SEYCHELLES               | `SC`        | 3                         | `zh_XC`     | `zh-SC`                   |
| SIERRA LEONE             | `SL`        | 0                         | `en_US`     | `en-SL`                   |
| SIERRA LEONE             | `SL`        | 1                         | `fr_XC`     | `fr-SL`                   |
| SIERRA LEONE             | `SL`        | 2                         | `es_XC`     | `es-SL`                   |
| SIERRA LEONE             | `SL`        | 3                         | `zh_XC`     | `zh-SL`                   |
| SINGAPORE                | `SG`        | 0                         | `en_GB`     | `en-SG`                   |
| SLOVAKIA                 | `SK`        | 0                         | `sk_SK`     | `sk-SK`                   |
| SLOVAKIA                 | `SK`        | 1                         | `en_US`     | `en-SK`                   |
| SLOVAKIA                 | `SK`        | 2                         | `fr_XC`     | `fr-SK`                   |
| SLOVAKIA                 | `SK`        | 3                         | `es_XC`     | `es-SK`                   |
| SLOVAKIA                 | `SK`        | 4                         | `zh_XC`     | `zh-SK`                   |
| SLOVENIA                 | `SI`        | 0                         | `en_US`     | `en-SI`                   |
| SLOVENIA                 | `SI`        | 1                         | `fr_XC`     | `fr-SI`                   |
| SLOVENIA                 | `SI`        | 2                         | `es_XC`     | `es-SI`                   |
| SLOVENIA                 | `SI`        | 3                         | `zh_XC`     | `zh-SI`                   |
| SOLOMON ISLANDS          | `SB`        | 0                         | `en_US`     | `en-SB`                   |
| SOLOMON ISLANDS          | `SB`        | 1                         | `fr_XC`     | `fr-SB`                   |
| SOLOMON ISLANDS          | `SB`        | 2                         | `es_XC`     | `es-SB`                   |
| SOLOMON ISLANDS          | `SB`        | 3                         | `zh_XC`     | `zh-SB`                   |
| SOMALIA                  | `SO`        | 0                         | `en_US`     | `en-SO`                   |
| SOMALIA                  | `SO`        | 1                         | `fr_XC`     | `fr-SO`                   |
| SOMALIA                  | `SO`        | 2                         | `es_XC`     | `es-SO`                   |
| SOMALIA                  | `SO`        | 3                         | `zh_XC`     | `zh-SO`                   |
| SOUTH AFRICA             | `ZA`        | 0                         | `en_US`     | `en-ZA`                   |
| SOUTH AFRICA             | `ZA`        | 1                         | `fr_XC`     | `fr-ZA`                   |
| SOUTH AFRICA             | `ZA`        | 2                         | `es_XC`     | `es-ZA`                   |
| SOUTH AFRICA             | `ZA`        | 3                         | `zh_XC`     | `zh-ZA`                   |
| SOUTH KOREA              | `KR`        | 0                         | `ko_KR`     | `ko-KR`                   |
| SOUTH KOREA              | `KR`        | 1                         | `en_US`     | `en-KR`                   |
| SPAIN                    | `ES`        | 0                         | `es_ES`     | `es-ES`                   |
| SPAIN                    | `ES`        | 1                         | `en_US`     | `en-ES`                   |
| SRI LANKA                | `LK`        | 0                         | `en_US`     | `en-LK`                   |
| ST. HELENA               | `SH`        | 0                         | `en_US`     | `en-SH`                   |
| ST. HELENA               | `SH`        | 1                         | `fr_XC`     | `fr-SH`                   |
| ST. HELENA               | `SH`        | 2                         | `es_XC`     | `es-SH`                   |
| ST. HELENA               | `SH`        | 3                         | `zh_XC`     | `zh-SH`                   |
| ST. KITTS & NEVIS        | `KN`        | 0                         | `en_US`     | `en-KN`                   |
| ST. KITTS & NEVIS        | `KN`        | 1                         | `fr_XC`     | `fr-KN`                   |
| ST. KITTS & NEVIS        | `KN`        | 2                         | `es_XC`     | `es-KN`                   |
| ST. KITTS & NEVIS        | `KN`        | 3                         | `zh_XC`     | `zh-KN`                   |
| ST. LUCIA                | `LC`        | 0                         | `en_US`     | `en-LC`                   |
| ST. LUCIA                | `LC`        | 1                         | `fr_XC`     | `fr-LC`                   |
| ST. LUCIA                | `LC`        | 2                         | `es_XC`     | `es-LC`                   |
| ST. LUCIA                | `LC`        | 3                         | `zh_XC`     | `zh-LC`                   |
| ST. PIERRE & MIQUELON    | `PM`        | 0                         | `en_US`     | `en-PM`                   |
| ST. PIERRE & MIQUELON    | `PM`        | 1                         | `fr_XC`     | `fr-PM`                   |
| ST. PIERRE & MIQUELON    | `PM`        | 2                         | `es_XC`     | `es-PM`                   |
| ST. PIERRE & MIQUELON    | `PM`        | 3                         | `zh_XC`     | `zh-PM`                   |
| ST. VINCENT & GRENADINES | `VC`        | 0                         | `en_US`     | `en-VC`                   |
| ST. VINCENT & GRENADINES | `VC`        | 1                         | `fr_XC`     | `fr-VC`                   |
| ST. VINCENT & GRENADINES | `VC`        | 2                         | `es_XC`     | `es-VC`                   |
| ST. VINCENT & GRENADINES | `VC`        | 3                         | `zh_XC`     | `zh-VC`                   |
| SURINAME                 | `SR`        | 0                         | `en_US`     | `en-SR`                   |
| SURINAME                 | `SR`        | 1                         | `fr_XC`     | `fr-SR`                   |
| SURINAME                 | `SR`        | 2                         | `es_XC`     | `es-SR`                   |
| SURINAME                 | `SR`        | 3                         | `zh_XC`     | `zh-SR`                   |
| SVALBARD & JAN MAYEN     | `SJ`        | 0                         | `en_US`     | `en-SJ`                   |
| SVALBARD & JAN MAYEN     | `SJ`        | 1                         | `fr_XC`     | `fr-SJ`                   |
| SVALBARD & JAN MAYEN     | `SJ`        | 2                         | `es_XC`     | `es-SJ`                   |
| SVALBARD & JAN MAYEN     | `SJ`        | 3                         | `zh_XC`     | `zh-SJ`                   |
| SWAZILAND                | `SZ`        | 0                         | `en_US`     | `en-SZ`                   |
| SWAZILAND                | `SZ`        | 1                         | `fr_XC`     | `fr-SZ`                   |
| SWAZILAND                | `SZ`        | 2                         | `es_XC`     | `es-SZ`                   |
| SWAZILAND                | `SZ`        | 3                         | `zh_XC`     | `zh-SZ`                   |
| SWEDEN                   | `SE`        | 0                         | `sv_SE`     | `sv-SE`                   |
| SWEDEN                   | `SE`        | 1                         | `en_US`     | `en-SE`                   |
| SWITZERLAND              | `CH`        | 0                         | `de_DE`     | `de-CH`                   |
| SWITZERLAND              | `CH`        | 1                         | `fr_FR`     | `fr-CH`                   |
| SWITZERLAND              | `CH`        | 2                         | `en_US`     | `en-CH`                   |
| TAIWAN                   | `TW`        | 0                         | `zh_TW`     | `zh-TW`                   |
| TAIWAN                   | `TW`        | 1                         | `en_US`     | `en-TW`                   |
| TAJIKISTAN               | `TJ`        | 0                         | `en_US`     | `en-TJ`                   |
| TAJIKISTAN               | `TJ`        | 1                         | `fr_XC`     | `fr-TJ`                   |
| TAJIKISTAN               | `TJ`        | 2                         | `es_XC`     | `es-TJ`                   |
| TAJIKISTAN               | `TJ`        | 3                         | `zh_XC`     | `zh-TJ`                   |
| TANZANIA                 | `TZ`        | 0                         | `en_US`     | `en-TZ`                   |
| TANZANIA                 | `TZ`        | 1                         | `fr_XC`     | `fr-TZ`                   |
| TANZANIA                 | `TZ`        | 2                         | `es_XC`     | `es-TZ`                   |
| TANZANIA                 | `TZ`        | 3                         | `zh_XC`     | `zh-TZ`                   |
| THAILAND                 | `TH`        | 0                         | `th_TH`     | `th-TH`                   |
| THAILAND                 | `TH`        | 1                         | `en_GB`     | `en-TH`                   |
| TOGO                     | `TG`        | 0                         | `fr_XC`     | `fr-TG`                   |
| TOGO                     | `TG`        | 1                         | `en_US`     | `en-TG`                   |
| TOGO                     | `TG`        | 2                         | `es_XC`     | `es-TG`                   |
| TOGO                     | `TG`        | 3                         | `zh_XC`     | `zh-TG`                   |
| TONGA                    | `TO`        | 0                         | `en_US`     | `en-TO`                   |
| TRINIDAD & TOBAGO        | `TT`        | 0                         | `en_US`     | `en-TT`                   |
| TRINIDAD & TOBAGO        | `TT`        | 1                         | `fr_XC`     | `fr-TT`                   |
| TRINIDAD & TOBAGO        | `TT`        | 2                         | `es_XC`     | `es-TT`                   |
| TRINIDAD & TOBAGO        | `TT`        | 3                         | `zh_XC`     | `zh-TT`                   |
| TUNISIA                  | `TN`        | 0                         | `ar_EG`     | `ar-TN`                   |
| TUNISIA                  | `TN`        | 1                         | `en_US`     | `en-TN`                   |
| TUNISIA                  | `TN`        | 2                         | `fr_XC`     | `fr-TN`                   |
| TUNISIA                  | `TN`        | 3                         | `es_XC`     | `es-TN`                   |
| TUNISIA                  | `TN`        | 4                         | `zh_XC`     | `zh-TN`                   |
| TURKMENISTAN             | `TM`        | 0                         | `en_US`     | `en-TM`                   |
| TURKMENISTAN             | `TM`        | 1                         | `fr_XC`     | `fr-TM`                   |
| TURKMENISTAN             | `TM`        | 2                         | `es_XC`     | `es-TM`                   |
| TURKMENISTAN             | `TM`        | 3                         | `zh_XC`     | `zh-TM`                   |
| TURKS & CAICOS ISLANDS   | `TC`        | 0                         | `en_US`     | `en-TC`                   |
| TURKS & CAICOS ISLANDS   | `TC`        | 1                         | `fr_XC`     | `fr-TC`                   |
| TURKS & CAICOS ISLANDS   | `TC`        | 2                         | `es_XC`     | `es-TC`                   |
| TURKS & CAICOS ISLANDS   | `TC`        | 3                         | `zh_XC`     | `zh-TC`                   |
| TUVALU                   | `TV`        | 0                         | `en_US`     | `en-TV`                   |
| TUVALU                   | `TV`        | 1                         | `fr_XC`     | `fr-TV`                   |
| TUVALU                   | `TV`        | 2                         | `es_XC`     | `es-TV`                   |
| TUVALU                   | `TV`        | 3                         | `zh_XC`     | `zh-TV`                   |
| UGANDA                   | `UG`        | 0                         | `en_US`     | `en-UG`                   |
| UGANDA                   | `UG`        | 1                         | `fr_XC`     | `fr-UG`                   |
| UGANDA                   | `UG`        | 2                         | `es_XC`     | `es-UG`                   |
| UGANDA                   | `UG`        | 3                         | `zh_XC`     | `zh-UG`                   |
| UKRAINE                  | `UA`        | 0                         | `en_US`     | `en-UA`                   |
| UKRAINE                  | `UA`        | 1                         | `ru_RU`     | `ru-UA`                   |
| UKRAINE                  | `UA`        | 2                         | `fr_XC`     | `fr-UA`                   |
| UKRAINE                  | `UA`        | 3                         | `es_XC`     | `es-UA`                   |
| UKRAINE                  | `UA`        | 4                         | `zh_XC`     | `zh-UA`                   |
| UNITED ARAB EMIRATES     | `AE`        | 0                         | `en_US`     | `en-AE`                   |
| UNITED ARAB EMIRATES     | `AE`        | 1                         | `fr_XC`     | `fr-AE`                   |
| UNITED ARAB EMIRATES     | `AE`        | 2                         | `es_XC`     | `es-AE`                   |
| UNITED ARAB EMIRATES     | `AE`        | 3                         | `zh_XC`     | `zh-AE`                   |
| UNITED ARAB EMIRATES     | `AE`        | 4                         | `ar_EG`     | `ar-AE`                   |
| UNITED KINGDOM           | `GB`        | 0                         | `en_GB`     | `en-GB`                   |
| UNITED STATES            | `US`        | 0                         | `en_US`     | `en-US`                   |
| UNITED STATES            | `US`        | 1                         | `fr_XC`     | `fr-US`                   |
| UNITED STATES            | `US`        | 2                         | `es_XC`     | `es-US`                   |
| UNITED STATES            | `US`        | 3                         | `zh_XC`     | `zh-US`                   |
| URUGUAY                  | `UY`        | 0                         | `es_XC`     | `es-UY`                   |
| URUGUAY                  | `UY`        | 1                         | `en_US`     | `en-UY`                   |
| URUGUAY                  | `UY`        | 2                         | `fr_XC`     | `fr-UY`                   |
| URUGUAY                  | `UY`        | 3                         | `zh_XC`     | `zh-UY`                   |
| VANUATU                  | `VU`        | 0                         | `en_US`     | `en-VU`                   |
| VANUATU                  | `VU`        | 1                         | `fr_XC`     | `fr-VU`                   |
| VANUATU                  | `VU`        | 2                         | `es_XC`     | `es-VU`                   |
| VANUATU                  | `VU`        | 3                         | `zh_XC`     | `zh-VU`                   |
| VATICAN CITY             | `VA`        | 0                         | `en_US`     | `en-VA`                   |
| VATICAN CITY             | `VA`        | 1                         | `fr_XC`     | `fr-VA`                   |
| VATICAN CITY             | `VA`        | 2                         | `es_XC`     | `es-VA`                   |
| VATICAN CITY             | `VA`        | 3                         | `zh_XC`     | `zh-VA`                   |
| VENEZUELA                | `VE`        | 0                         | `es_XC`     | `es-VE`                   |
| VENEZUELA                | `VE`        | 1                         | `en_US`     | `en-VE`                   |
| VENEZUELA                | `VE`        | 2                         | `fr_XC`     | `fr-VE`                   |
| VENEZUELA                | `VE`        | 3                         | `zh_XC`     | `zh-VE`                   |
| VIETNAM                  | `VN`        | 0                         | `en_US`     | `en-VN`                   |
| WALLIS & FUTUNA          | `WF`        | 0                         | `en_US`     | `en-WF`                   |
| WALLIS & FUTUNA          | `WF`        | 1                         | `fr_XC`     | `fr-WF`                   |
| WALLIS & FUTUNA          | `WF`        | 2                         | `es_XC`     | `es-WF`                   |
| WALLIS & FUTUNA          | `WF`        | 3                         | `zh_XC`     | `zh-WF`                   |
| YEMEN                    | `YE`        | 0                         | `ar_EG`     | `ar-YE`                   |
| YEMEN                    | `YE`        | 1                         | `en_US`     | `en-YE`                   |
| YEMEN                    | `YE`        | 2                         | `fr_XC`     | `fr-YE`                   |
| YEMEN                    | `YE`        | 3                         | `es_XC`     | `es-YE`                   |
| YEMEN                    | `YE`        | 4                         | `zh_XC`     | `zh-YE`                   |
| ZAMBIA                   | `ZM`        | 0                         | `en_US`     | `en-ZM`                   |
| ZAMBIA                   | `ZM`        | 1                         | `fr_XC`     | `fr-ZM`                   |
| ZAMBIA                   | `ZM`        | 2                         | `es_XC`     | `es-ZM`                   |
| ZAMBIA                   | `ZM`        | 3                         | `zh_XC`     | `zh-ZM`                   |
| ZIMBABWE                 | `ZW`        | 0                         | `en_US`     | `en-ZW`                   |


# State and province codes
Source: https://docs.paypal.ai/reference/codes/state-province-codes



PayPal's REST APIs accept the following state and province codes in the `state` parameter for an address.

<Note> **Note:** Some tables list only the state or province name and not a state or province code. For these countries, use the spelling of the state or province name exactly as the table presents it.</Note>

## Argentina

<Accordion icon="globe" title="Select this tab to see the list of supported provinces.">
  | Province name            | Province code                     |
  | ------------------------ | --------------------------------- |
  | Buenos Aires (Ciudad)    | `CIUDAD AUTÓNOMA DE BUENOS AIRES` |
  | Buenos Aires (Provincia) | `BUENOS AIRES`                    |
  | Catamarca                | `CATAMARCA`                       |
  | Chaco                    | `CHACO`                           |
  | Chubut                   | `CHUBUT`                          |
  | Corrientes               | `CORRIENTES`                      |
  | Córdoba                  | `CÓRDOBA`                         |
  | Entre Ríos               | `ENTRE RÍOS`                      |
  | Formosa                  | `FORMOSA`                         |
  | Jujuy                    | `JUJUY`                           |
  | La Pampa                 | `LA PAMPA`                        |
  | La Rioja                 | `LA RIOJA`                        |
  | Mendoza                  | `MENDOZA`                         |
  | Misiones                 | `MISIONES`                        |
  | Neuquén                  | `NEUQUÉN`                         |
  | Río Negro                | `RÍO NEGRO`                       |
  | Salta                    | `SALTA`                           |
  | San Juan                 | `SAN JUAN`                        |
  | San Luis                 | `SAN LUIS`                        |
  | Santa Cruz               | `SANTA CRUZ`                      |
  | Santa Fe                 | `SANTA FE`                        |
  | Santiago del Estero      | `SANTIAGO DEL ESTERO`             |
  | Tierra del Fuego         | `TIERRA DEL FUEGO`                |
  | Tucumán                  | `TUCUMÁN`                         |
</Accordion>

## Brazil

<Accordion icon="globe" title="Select this tab to see the list of supported provinces.">
  | State name          | State code |
  | ------------------- | ---------- |
  | Acre                | `AC`       |
  | Alagoas             | `AL`       |
  | Amapá               | `AP`       |
  | Amazonas            | `AM`       |
  | Bahia               | `BA`       |
  | Ceará               | `CE`       |
  | Distrito Federal    | `DF`       |
  | Espírito Santo      | `ES`       |
  | Goiás               | `GO`       |
  | Maranhão            | `MA`       |
  | Mato Grosso         | `MT`       |
  | Mato Grosso do Sul  | `MS`       |
  | Minas Gerais        | `MG`       |
  | Paraná              | `PR`       |
  | Paraíba             | `PB`       |
  | Pará                | `PA`       |
  | Pernambuco          | `PE`       |
  | Piauí               | `PI`       |
  | Rio Grande do Norte | `RN`       |
  | Rio Grande do Sul   | `RS`       |
  | Rio de Janeiro      | `RJ`       |
  | Rondônia            | `RO`       |
  | Roraima             | `RR`       |
  | Santa Catarina      | `SC`       |
  | Sergipe             | `SE`       |
  | São Paulo           | `SP`       |
  | Tocantins           | `TO`       |
</Accordion>

## Canada

<Accordion icon="globe" title="Select this tab to see the list of supported provinces.">
  | Province name             | Province code |
  | ------------------------- | ------------- |
  | Alberta                   | `AB`          |
  | British Columbia          | `BC`          |
  | Manitoba                  | `MB`          |
  | New Brunswick             | `NB`          |
  | Newfoundland and Labrador | `NL`          |
  | Northwest Territories     | `NT`          |
  | Nova Scotia               | `NS`          |
  | Nunavut                   | `NU`          |
  | Ontario                   | `ON`          |
  | Prince Edward Island      | `PE`          |
  | Quebec                    | `QC`          |
  | Saskatchewan              | `SK`          |
  | Yukon                     | `YT`          |
</Accordion>

## China

<Accordion icon="globe" title="Select this tab to see the list of supported provinces.">
  | Subdivision name                                                        | Subdivision name                     | Subdivision category          | Code    |
  | ----------------------------------------------------------------------- | ------------------------------------ | ----------------------------- | ------- |
  | Anhui Sheng                                                             | 安徽省 (Ānhuī Shěng)                    | Province                      | `CN-AH` |
  | Beijing Shi                                                             | 北京市 (Běijīng Shì)                    | Municipality                  | `CN-BJ` |
  | Chongqing Shi                                                           | 重庆市 (Chóngqìng Shì)                  | Municipality                  | `CN-CQ` |
  | Fujian Sheng                                                            | 福建省 (Fújiàn Shěng)                   | Province                      | `CN-FJ` |
  | Guangdong Sheng                                                         | 广东省 (Guǎngdōng Shěng)                | Province                      | `CN-GD` |
  | Gansu Sheng                                                             | 甘肃省 (Gānsù Shěng)                    | Province                      | `CN-GS` |
  | Guangxi Zhuangzu Zizhiqu                                                | 广西壮族自治区 (Guǎngxī Zhuàngzú Zìzhìqū)   | Autonomous region             | `CN-GX` |
  | Guizhou Sheng                                                           | 贵州省 (Guìzhōu Shěng)                  | Province                      | `CN-GZ` |
  | Henan Sheng                                                             | 河南省 (Hénán Shěng)                    | Province                      | `CN-HA` |
  | Hubei Sheng                                                             | 湖北省 (Húběi Shěng)                    | Province                      | `CN-HB` |
  | Hebei Sheng                                                             | 河北省 (Héběi Shěng)                    | Province                      | `CN-HE` |
  | Hainan Sheng                                                            | 海南省 (Hǎinán Shěng)                   | Province                      | `CN-HI` |
  | Hong Kong SAR (en)  <br />Xianggang Tebiexingzhengqu (zh)               | 香港特别行政区 (Xiānggǎng Tèbiéxíngzhèngqū) | Special administrative region | `CN-HK` |
  | Heilongjiang Sheng                                                      | 黑龙江省 (Hēilóngjiāng Shěng)            | Province                      | `CN-HL` |
  | Hunan Sheng                                                             | 湖南省 (Húnán Shěng)                    | Province                      | `CN-HN` |
  | Jilin Sheng                                                             | 吉林省 (Jílín Shěng)                    | Province                      | `CN-JL` |
  | Jiangsu Sheng                                                           | 江苏省 (Jiāngsū Shěng)                  | Province                      | `CN-JS` |
  | Jiangxi Sheng                                                           | 江西省 (Jiāngxī Shěng)                  | Province                      | `CN-JX` |
  | Liaoning Sheng                                                          | 辽宁省 (Liáoníng Shěng)                 | Province                      | `CN-LN` |
  | Macao SAR (en)  <br />Macau SAR (pt)  <br />Aomen Tebiexingzhengqu (zh) | 澳门特别行政区 (Àomén Tèbiéxíngzhèngqū)     | Special administrative region | `CN-MO` |
  | Nei Mongol Zizhiqu (mn)                                                 | 内蒙古自治区 (Nèi Ménggǔ Zìzhìqū)          | Autonomous region             | `CN-NM` |
  | Ningxia Huizu Zizhiqu                                                   | 宁夏回族自治区 (Níngxià Huízú Zìzhìqū)      | Autonomous region             | `CN-NX` |
  | Qinghai Sheng                                                           | 青海省 (Qīnghǎi Shěng)                  | Province                      | `CN-QH` |
  | Sichuan Sheng                                                           | 四川省 (Sìchuān Shěng)                  | Province                      | `CN-SC` |
  | Shandong Sheng                                                          | 山东省 (Shāndōng Shěng)                 | Province                      | `CN-SD` |
  | Shanghai Shi                                                            | 上海市 (Shànghǎi Shì)                   | Municipality                  | `CN-SH` |
  | Shaanxi Sheng                                                           | 陕西省 (Shǎnxī Shěng)                   | Province                      | `CN-SN` |
  | Shanxi Sheng                                                            | 山西省 (Shānxī Shěng)                   | Province                      | `CN-SX` |
  | Tianjin Shi                                                             | 天津市 (Tiānjīn Shì)                    | Municipality                  | `CN-TJ` |
  | Taiwan Sheng                                                            | 台湾省 (Táiwān Shěng)                   | Province                      | `CN-TW` |
  | Xinjiang Uygur Zizhiqu                                                  | 新疆维吾尔自治区 (Xīnjiāng Wéiwú'ěr Zìzhìqū) | Autonomous region             | `CN-XJ` |
  | Xizang Zizhiqu                                                          | 西藏自治区 (Xīzàng Zìzhìqū)               | Autonomous region             | `CN-XZ` |
  | Yunnan Sheng                                                            | 云南省 (Yúnnán Shěng)                   | Province                      | `CN-YN` |
  | Zhejiang Sheng                                                          | 浙江省 (Zhèjiāng Shěng)                 | Province                      | `CN-ZJ` |
</Accordion>

## India

<Accordion icon="globe" title="Select this tab to see the list of supported provinces.">
  | State name                  | State code                    |
  | --------------------------- | ----------------------------- |
  | Andaman and Nicobar Islands | `Andaman and Nicobar Islands` |
  | Andhra Pradesh              | `Andhra Pradesh`              |
  | Army Post Office            | `APO`                         |
  | Arunachal Pradesh           | `Arunachal Pradesh`           |
  | Assam                       | `Assam`                       |
  | Bihar                       | `Bihar`                       |
  | Chandigarh                  | `Chandigarh`                  |
  | Chhattisgarh                | `Chhattisgarh`                |
  | Dadra and Nagar Haveli      | `Dadra and Nagar Haveli`      |
  | Daman and Diu               | `Daman and Diu`               |
  | Delhi                       | `Delhi (NCT)`                 |
  | Goa                         | `Goa`                         |
  | Gujarat                     | `Gujarat`                     |
  | Haryana                     | `Haryana`                     |
  | Himachal Pradesh            | `Himachal Pradesh`            |
  | Jammu and Kashmir           | `Jammu and Kashmir`           |
  | Jharkhand                   | `Jharkhand`                   |
  | Karnataka                   | `Karnataka`                   |
  | Kerala                      | `Kerala`                      |
  | Lakshadweep                 | `Lakshadweep`                 |
  | Madhya Pradesh              | `Madhya Pradesh`              |
  | Maharashtra                 | `Maharashtra`                 |
  | Manipur                     | `Manipur`                     |
  | Meghalaya                   | `Meghalaya`                   |
  | Mizoram                     | `Mizoram`                     |
  | Nagaland                    | `Nagaland`                    |
  | Odisha                      | `Odisha`                      |
  | Puducherry                  | `Puducherry`                  |
  | Punjab                      | `Punjab`                      |
  | Rajasthan                   | `Rajasthan`                   |
  | Sikkim                      | `Sikkim`                      |
  | Tamil Nadu                  | `Tamil Nadu`                  |
  | Telangana                   | `Telangana`                   |
  | Tripura                     | `Tripura`                     |
  | Uttar Pradesh               | `Uttar Pradesh`               |
  | Uttarakhand                 | `Uttarakhand`                 |
  | West Bengal                 | `West Bengal`                 |
</Accordion>

## Indonesia

<Accordion icon="globe" title="Select this tab to see the list of supported provinces.">
  | Province name            | Province code |
  | ------------------------ | ------------- |
  | Bali                     | `ID-BA`       |
  | Bangka Belitung          | `ID-BB`       |
  | Banten                   | `ID-BT`       |
  | Bengkulu                 | `ID-BE`       |
  | DI Yogyakarta            | `ID-YO`       |
  | DKI Jakarta              | `ID-JK`       |
  | Gorontalo                | `ID-GO`       |
  | Jambi                    | `ID-JA`       |
  | Jawa Barat               | `ID-JB`       |
  | Jawa Tengah              | `ID-JT`       |
  | Jawa Timur               | `ID-JI`       |
  | Kalimantan Barat         | `ID-KB`       |
  | Kalimantan Selatan       | `ID-KS`       |
  | Kalimantan Tengah        | `ID-KT`       |
  | Kalimantan Timur         | `ID-KI`       |
  | Kalimantan Utara         | `ID-KU`       |
  | Kepulauan Riau           | `ID-KR`       |
  | Lampung                  | `ID-LA`       |
  | Maluku                   | `ID-MA`       |
  | Maluku Utara             | `ID-MU`       |
  | Nanggroe Aceh Darussalam | `ID-AC`       |
  | Nusa Tenggara Barat      | `ID-NB`       |
  | Nusa Tenggara Timur      | `ID-NT`       |
  | Papua                    | `ID-PA`       |
  | Papua Barat              | `ID-PB`       |
  | Riau                     | `ID-RI`       |
  | Sulawesi Barat           | `ID-SR`       |
  | Sulawesi Selatan         | `ID-SN`       |
  | Sulawesi Tengah          | `ID-ST`       |
  | Sulawesi Tenggara        | `ID-SG`       |
  | Sulawesi Utara           | `ID-SA`       |
  | Sumatera Barat           | `ID-SB`       |
  | Sumatera Selatan         | `ID-SS`       |
  | Sumatera Utara           | `ID-SU`       |
</Accordion>

## Italy

<Accordion icon="globe" title="Select this tab to see the list of supported provinces.">
  | Province name         | Province code |
  | --------------------- | ------------- |
  | Agrigento             | `AG`          |
  | Alessandria           | `AL`          |
  | Ancona                | `AN`          |
  | Aosta                 | `AO`          |
  | Arezzo                | `AR`          |
  | Ascoli Piceno         | `AP`          |
  | Asti                  | `AT`          |
  | Avellino              | `AV`          |
  | Bari                  | `BA`          |
  | Barletta-Andria-Trani | `BT`          |
  | Belluno               | `BL`          |
  | Benevento             | `BN`          |
  | Bergamo               | `BG`          |
  | Biella                | `BI`          |
  | Bologna               | `BO`          |
  | Bolzano               | `BZ`          |
  | Brescia               | `BS`          |
  | Brindisi              | `BR`          |
  | Cagliari              | `CA`          |
  | Caltanissetta         | `CL`          |
  | Campobasso            | `CB`          |
  | Carbonia-Iglesias     | `CI`          |
  | Caserta               | `CE`          |
  | Catania               | `CT`          |
  | Catanzaro             | `CZ`          |
  | Chieti                | `CH`          |
  | Como                  | `CO`          |
  | Cosenza               | `CS`          |
  | Cremona               | `CR`          |
  | Crotone               | `KR`          |
  | Cuneo                 | `CN`          |
  | Enna                  | `EN`          |
  | Fermo                 | `FM`          |
  | Ferrara               | `FE`          |
  | Firenze               | `FI`          |
  | Foggia                | `FG`          |
  | Forlì-Cesena          | `FC`          |
  | Frosinone             | `FR`          |
  | Genova                | `GE`          |
  | Gorizia               | `GO`          |
  | Grosseto              | `GR`          |
  | Imperia               | `IM`          |
  | Isernia               | `IS`          |
  | L'Aquila              | `AQ`          |
  | La Spezia             | `SP`          |
  | Latina                | `LT`          |
  | Lecce                 | `LE`          |
  | Lecco                 | `LC`          |
  | Livorno               | `LI`          |
  | Lodi                  | `LO`          |
  | Lucca                 | `LU`          |
  | Macerata              | `MC`          |
  | Mantova               | `MN`          |
  | Massa-Carrara         | `MS`          |
  | Matera                | `MT`          |
  | Medio Campidano       | `VS`          |
  | Messina               | `ME`          |
  | Milano                | `MI`          |
  | Modena                | `MO`          |
  | Monza e della Brianza | `MB`          |
  | Napoli                | `NA`          |
  | Novara                | `NO`          |
  | Nuoro                 | `NU`          |
  | Ogliastra             | `OG`          |
  | Olbia-Tempio          | `OT`          |
  | Oristano              | `OR`          |
  | Padova                | `PD`          |
  | Palermo               | `PA`          |
  | Parma                 | `PR`          |
  | Pavia                 | `PV`          |
  | Perugia               | `PG`          |
  | Pesaro e Urbino       | `PU`          |
  | Pescara               | `PE`          |
  | Piacenza              | `PC`          |
  | Pisa                  | `PI`          |
  | Pistoia               | `PT`          |
  | Pordenone             | `PN`          |
  | Potenza               | `PZ`          |
  | Prato                 | `PO`          |
  | Ragusa                | `RG`          |
  | Ravenna               | `RA`          |
  | Reggio Calabria       | `RC`          |
  | Reggio Emilia         | `RE`          |
  | Rieti                 | `RI`          |
  | Rimini                | `RN`          |
  | Roma                  | `RM`          |
  | Rovigo                | `RO`          |
  | Salerno               | `SA`          |
  | Sassari               | `SS`          |
  | Savona                | `SV`          |
  | Siena                 | `SI`          |
  | Siracusa              | `SR`          |
  | Sondrio               | `SO`          |
  | Taranto               | `TA`          |
  | Teramo                | `TE`          |
  | Terni                 | `TR`          |
  | Torino                | `TO`          |
  | Trapani               | `TP`          |
  | Trento                | `TN`          |
  | Treviso               | `TV`          |
  | Trieste               | `TS`          |
  | Udine                 | `UD`          |
  | Varese                | `VA`          |
  | Venezia               | `VE`          |
  | Verbano-Cusio-Ossola  | `VB`          |
  | Vercelli              | `VC`          |
  | Verona                | `VR`          |
  | Vibo Valentia         | `VV`          |
  | Vicenza               | `VI`          |
  | Viterbo               | `VT`          |
</Accordion>

## Japan

<Accordion icon="globe" title="Select this tab to see the list of supported provinces.">
  | Prefecture name | Prefecture code |
  | --------------- | --------------- |
  | Aichi           | `AICHI-KEN`     |
  | Akita           | `AKITA-KEN`     |
  | Aomori          | `AOMORI-KEN`    |
  | Chiba           | `CHIBA-KEN`     |
  | Ehime           | `EHIME-KEN`     |
  | Fukui           | `FUKUI-KEN`     |
  | Fukuoka         | `FUKUOKA-KEN`   |
  | Fukushima       | `FUKUSHIMA-KEN` |
  | Gifu            | `GIFU-KEN`      |
  | Gunma           | `GUNMA-KEN`     |
  | Hiroshima       | `HIROSHIMA-KEN` |
  | Hokkaido        | `HOKKAIDO`      |
  | Hyogo           | `HYOGO-KEN`     |
  | Ibaraki         | `IBARAKI-KEN`   |
  | Ishikawa        | `ISHIKAWA-KEN`  |
  | Iwate           | `IWATE-KEN`     |
  | Kagawa          | `KAGAWA-KEN`    |
  | Kagoshima       | `KAGOSHIMA-KEN` |
  | Kanagawa        | `KANAGAWA-KEN`  |
  | Kochi           | `KOCHI-KEN`     |
  | Kumamoto        | `KUMAMOTO-KEN`  |
  | Kyoto           | `KYOTO-FU`      |
  | Mie             | `MIE-KEN`       |
  | Miyagi          | `MIYAGI-KEN`    |
  | Miyazaki        | `MIYAZAKI-KEN`  |
  | Nagano          | `NAGANO-KEN`    |
  | Nagasaki        | `NAGASAKI-KEN`  |
  | Nara            | `NARA-KEN`      |
  | Niigata         | `NIIGATA-KEN`   |
  | Oita            | `OITA-KEN`      |
  | Okayama         | `OKAYAMA-KEN`   |
  | Okinawa         | `OKINAWA-KEN`   |
  | Osaka           | `OSAKA-FU`      |
  | Saga            | `SAGA-KEN`      |
  | Saitama         | `SAITAMA-KEN`   |
  | Shiga           | `SHIGA-KEN`     |
  | Shimane         | `SHIMANE-KEN`   |
  | Shizuoka        | `SHIZUOKA-KEN`  |
  | Tochigi         | `TOCHIGI-KEN`   |
  | Tokushima       | `TOKUSHIMA-KEN` |
  | Tokyo           | `TOKYO-TO`      |
  | Tottori         | `TOTTORI-KEN`   |
  | Toyama          | `TOYAMA-KEN`    |
  | Wakayama        | `WAKAYAMA-KEN`  |
  | Yamagata        | `YAMAGATA-KEN`  |
  | Yamaguchi       | `YAMAGUCHI-KEN` |
  | Yamanashi       | `YAMANASHI-KEN` |
</Accordion>

## Mexico

<Accordion icon="globe" title="Select this tab to see the list of supported provinces.">
  | State name          | State code |
  | ------------------- | ---------- |
  | Aguascalientes      | `AGS`      |
  | Baja California     | `BC`       |
  | Baja California Sur | `BCS`      |
  | Campeche            | `CAMP`     |
  | Chiapas             | `CHIS`     |
  | Chihuahua           | `CHIH`     |
  | Ciudad de México    | `CDMX`     |
  | Coahuila            | `COAH`     |
  | Colima              | `COL`      |
  | Distrito Federal    | `DF`       |
  | Durango             | `DGO`      |
  | Estado de México    | `MEX`      |
  | Guanajuato          | `GTO`      |
  | Guerrero            | `GRO`      |
  | Hidalgo             | `HGO`      |
  | Jalisco             | `JAL`      |
  | Michoacán           | `MICH`     |
  | Morelos             | `MOR`      |
  | Nayarit             | `NAY`      |
  | Nuevo León          | `NL`       |
  | Oaxaca              | `OAX`      |
  | Puebla              | `PUE`      |
  | Querétaro           | `QRO`      |
  | Quintana Roo        | `Q ROO`    |
  | San Luis Potosí     | `SLP`      |
  | Sinaloa             | `SIN`      |
  | Sonora              | `SON`      |
  | Tabasco             | `TAB`      |
  | Tamaulipas          | `TAMPS`    |
  | Tlaxcala            | `TLAX`     |
  | Veracruz            | `VER`      |
  | Yucatán             | `YUC`      |
  | Zacatecas           | `ZAC`      |
</Accordion>

## Thailand

<Accordion icon="globe" title="Select this tab to see the list of supported provinces.">
  | Province name            |
  | ------------------------ |
  | Amnat Charoen            |
  | Ang Thong                |
  | Bangkok                  |
  | Bueng Kan                |
  | Buri Ram                 |
  | Chachoengsao             |
  | Chai Nat                 |
  | Chaiyaphum               |
  | Chanthaburi              |
  | Chiang Mai               |
  | Chiang Rai               |
  | Chon Buri                |
  | Chumphon                 |
  | Kalasin                  |
  | Kamphaeng Phet           |
  | Kanchanaburi             |
  | Khon Kaen                |
  | Krabi                    |
  | Lampang                  |
  | Lamphun                  |
  | Loei                     |
  | Lop Buri                 |
  | Mae Hong Son             |
  | Maha Sarakham            |
  | Mukdahan                 |
  | Nakhon Nayok             |
  | Nakhon Pathom            |
  | Nakhon Phanom            |
  | Nakhon Ratchasima        |
  | Nakhon Sawan             |
  | Nakhon Si Thammarat      |
  | Nan                      |
  | Narathiwat               |
  | Nong Bua Lamphu          |
  | Nong Khai                |
  | Nonthaburi               |
  | Pathum Thani             |
  | Pattani                  |
  | Phang Nga                |
  | Phatthalung              |
  | Phatthaya                |
  | Phayao                   |
  | Phetchabun               |
  | Phetchaburi              |
  | Phichit                  |
  | Phitsanulok              |
  | Phra Nakhon Si Ayutthaya |
  | Phrae                    |
  | Phuket                   |
  | Prachin Buri             |
  | Prachuap Khiri Khan      |
  | Ranong                   |
  | Ratchaburi               |
  | Rayong                   |
  | Roi Et                   |
  | Sa Kaeo                  |
  | Sakon Nakhon             |
  | Samut Prakan             |
  | Samut Sakhon             |
  | Samut Songkhram          |
  | Saraburi                 |
  | Satun                    |
  | Si Sa Ket                |
  | Sing Buri                |
  | Songkhla                 |
  | Sukhothai                |
  | Suphan Buri              |
  | Surat Thani              |
  | Surin                    |
  | Tak                      |
  | Trang                    |
  | Trat                     |
  | Ubon Ratchathani         |
  | Udon Thani               |
  | Uthai Thani              |
  | Uttaradit                |
  | Yala                     |
  | Yasothon                 |
</Accordion>

## USA

<Accordion icon="globe" title="Select this tab to see the list of supported provinces.">
  | State name           | State code |
  | -------------------- | ---------- |
  | Alabama              | `AL`       |
  | Alaska               | `AK`       |
  | Arizona              | `AZ`       |
  | Arkansas             | `AR`       |
  | California           | `CA`       |
  | Colorado             | `CO`       |
  | Connecticut          | `CT`       |
  | Delaware             | `DE`       |
  | District of Columbia | `DC`       |
  | Florida              | `FL`       |
  | Georgia              | `GA`       |
  | Hawaii               | `HI`       |
  | Idaho                | `ID`       |
  | Illinois             | `IL`       |
  | Indiana              | `IN`       |
  | Iowa                 | `IA`       |
  | Kansas               | `KS`       |
  | Kentucky             | `KY`       |
  | Louisiana            | `LA`       |
  | Maine                | `ME`       |
  | Maryland             | `MD`       |
  | Massachusetts        | `MA`       |
  | Michigan             | `MI`       |
  | Minnesota            | `MN`       |
  | Mississippi          | `MS`       |
  | Missouri             | `MO`       |
  | Montana              | `MT`       |
  | Nebraska             | `NE`       |
  | Nevada               | `NV`       |
  | New Hampshire        | `NH`       |
  | New Jersey           | `NJ`       |
  | New Mexico           | `NM`       |
  | New York             | `NY`       |
  | North Carolina       | `NC`       |
  | North Dakota         | `ND`       |
  | Ohio                 | `OH`       |
  | Oklahoma             | `OK`       |
  | Oregon               | `OR`       |
  | Pennsylvania         | `PA`       |
  | Puerto Rico          | `PR`       |
  | Rhode Island         | `RI`       |
  | South Carolina       | `SC`       |
  | South Dakota         | `SD`       |
  | Tennessee            | `TN`       |
  | Texas                | `TX`       |
  | Utah                 | `UT`       |
  | Vermont              | `VT`       |
  | Virginia             | `VA`       |
  | Washington           | `WA`       |
  | West Virginia        | `WV`       |
  | Wisconsin            | `WI`       |
  | Wyoming              | `WY`       |
</Accordion>

### Armed forces APO

| State name            | State code |
| --------------------- | ---------- |
| Armed Forces Americas | `AA`       |
| Armed Forces Europe   | `AE`       |
| Armed Forces Pacific  | `AP`       |

### Outlying areas

| State name                     | State code |
| ------------------------------ | ---------- |
| American Samoa                 | `AS`       |
| Federated States of Micronesia | `FM`       |
| Guam                           | `GU`       |
| Marshall Islands               | `MH`       |
| Northern Mariana Islands       | `MP`       |
| Palau                          | `PW`       |
| Virgin Islands                 | `VI`       |


# JavaScript SDK v6 Reference
Source: https://docs.paypal.ai/reference/sdk/js/v6/reference



Use the PayPal v6 JavaScript SDK to integrate PayPal, Venmo, Pay Later, and other payment methods into web applications. This reference covers payment eligibility checking, session management, callback handling, and web components.

<Tip>
  * For the React JavaScript SDK v6 reference, see [React SDK v6 Reference](/reference/sdk/react).
  * For setup and initialization, see [Set up JavaScript SDK v6](/developer/how-to/sdk/js/v6/configuration).
</Tip>

## Check payment eligibility

Before displaying payment buttons to your buyers, check which payment methods are available for the current transaction. Eligibility depends on various factors including the buyer's location, currency, merchant configuration, and transaction amount.

### `sdkInstance.findEligibleMethods(options?)`

Use `findEligibleMethods` to determine which payment methods are available for the current context. This method queries PayPal's eligibility service and returns an object with methods to check specific payment options.

#### Parameters

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Required</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>currencyCode</code></td>
      <td>no</td>

      <td>
        <p><strong>string.</strong> The three-letter ISO 4217 currency code for the transaction, for example, `"USD"`, `"EUR"`, or `"GBP"`. This affects payment method availability, especially for Pay Later options which have currency restrictions. Default: <code>"USD"</code></p>
      </td>
    </tr>

    <tr>
      <td><code>countryCode</code></td>
      <td>no</td>

      <td>
        <p><strong>string.</strong> The two-letter ISO 3166-1 alpha-2 country code representing the buyer's country. This determines regional payment method availability. For example, Venmo is only available in the US. If not specified, the SDK attempts to detect the buyer's country.</p>
      </td>
    </tr>

    <tr>
      <td><code>amount</code></td>
      <td>no</td>

      <td>
        <p><strong>string.</strong> The transaction amount as a string, for example, `"99.99"`. The amount affects Pay Later eligibility, as different financing options have minimum and maximum amount thresholds.</p>
      </td>
    </tr>
  </tbody>
</table>

#### Returns

Returns a promise that resolves to an EligiblePaymentMethods object with methods to check and retrieve payment method information.

The returned object provides these methods:

* `isEligible(method)` - Check if a specific payment method is available
* `getDetails(method)` - Get additional information about a payment method

#### Example

```javascript lines expandable theme={null}
// Check with default settings
const paymentMethods = await sdkInstance.findEligibleMethods();

// Check with specific currency and amount
const paymentMethods = await sdkInstance.findEligibleMethods({
  currencyCode: "USD",
  countryCode: "US",
  amount: "125.00",
});

// Use the eligibility results
if (paymentMethods.isEligible("paypal")) {
  // Show PayPal button
}

if (paymentMethods.isEligible("paylater")) {
  const details = paymentMethods.getDetails("paylater");
  // Show Pay Later button with product-specific messaging
}
```

### `paymentMethods.isEligible(method)`

Check whether a specific payment method is available for the current transaction.

#### Parameters

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Required</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>method</code></td>
      <td>yes</td>

      <td>
        <p><strong>string.</strong> The payment method identifier to check.</p>
        <p>Supported values:</p>

        <ul>
          <li><code>paypal</code> — PayPal Checkout</li>
          <li><code>venmo</code> — Venmo (US only)</li>
          <li><code>paylater</code> — Pay Later / Pay in 4</li>
          <li><code>credit</code> — PayPal Credit</li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

#### Returns

Returns `true` if the payment method is available, `false` otherwise.

#### Example

```javascript lines  theme={null}
// Check individual payment methods
const canUsePayPal = paymentMethods.isEligible("paypal");
const canUseVenmo = paymentMethods.isEligible("venmo");

// Conditionally show buttons
if (paymentMethods.isEligible("venmo")) {
  document.getElementById("venmo-button").style.display = "block";
}
```

### `paymentMethods.getDetails(method)`

Retrieve additional configuration details for a specific payment method. This is particularly useful for Pay Later and PayPal Credit, which require additional attributes for proper button rendering.

#### Parameters

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Required</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>method</code></td>
      <td>yes</td>

      <td>
        <p><strong>string.</strong> The payment method to get details for.</p>
        <p>Currently returns details for:</p>

        <ul>
          <li><code>paylater</code> — Returns product code and country</li>
          <li><code>credit</code> — Returns country configuration</li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

#### Returns

Returns an object with payment method-specific details. The structure varies by payment method.

For Pay Later:

```javascript theme={null}
{
  productCode: string; // Example: "PAY_IN_4"
  countryCode: string; // Example: "US"
}
```

For PayPal Credit:

```javascript theme={null}
{
  countryCode: string; // Example: "US"
}
```

#### Example

```javascript lines theme={null}
// Get Pay Later configuration
const payLaterDetails = paymentMethods.getDetails("paylater");
const button = document.querySelector("paylater-button");
button.productCode = payLaterDetails.productCode;
button.countryCode = payLaterDetails.countryCode;

// Get PayPal Credit configuration
const creditDetails = paymentMethods.getDetails("credit");
```

## Creating payment sessions

Payment sessions manage the complete payment flow from initiation through completion. Each payment method has its own session creation method that returns a session object with methods to start and control the payment process.

### `sdkInstance.createPayPalOneTimePaymentSession(options)`

Create a payment session for one-time PayPal payments. This session handles the complete PayPal Checkout flow, including payment approval, shipping address changes, and order updates.

#### Parameters

The options object configures callbacks that handle different stages of the payment flow. These callbacks allow you to respond to buyer actions and update your order accordingly.

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Required</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>onApprove</code></td>
      <td>yes</td>

      <td>
        <p><strong>function(data).</strong> Called when the buyer approves the payment in the PayPal flow. This is where you should capture or authorize the payment on your server.</p>
        <p>The function receives a data object containing:</p>

        <ul>
          <li><code>orderId</code> — The PayPal order ID to capture</li>
          <li><code>payerId</code> — The buyer's PayPal payer ID</li>
        </ul>

        <p>This function can return a promise if you need to perform async operations like capturing the payment.</p>
      </td>
    </tr>

    <tr>
      <td><code>onCancel</code></td>
      <td>no</td>

      <td>
        <p><strong>function(data).</strong> Called when the buyer cancels the payment flow by closing the PayPal window or selecting cancel.</p>
        <p>The data object contains:</p>

        <ul>
          <li><code>orderId</code> — The order ID (if one was created)</li>
        </ul>

        <p>Use this callback to:</p>

        <ul>
          <li>Track abandoned checkouts</li>
          <li>Re-enable your checkout button</li>
          <li>Show a message to the buyer</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td><code>onError</code></td>
      <td>no</td>

      <td>
        <p><strong>function(error).</strong> Called when an error occurs during the payment flow. This includes network errors, validation errors, or payment failures.</p>
        <p>The error object contains:</p>

        <ul>
          <li><code>code</code> — Error code for identifying the issue</li>
          <li><code>message</code> — Human-readable error description</li>
        </ul>

        <p>Use this to display user-friendly error messages and log errors for debugging.</p>
      </td>
    </tr>

    <tr>
      <td><code>onShippingAddressChange</code></td>
      <td>no</td>

      <td>
        <p><strong>function(data).</strong> Called when the buyer changes their shipping address within the PayPal flow. This allows you to update shipping costs or restrict certain addresses.</p>
        <p>The data object contains:</p>

        <ul>
          <li><code>errors</code> — Errors to show to the user</li>
          <li><code>orderId</code> — The current order ID</li>
          <li><code>shippingAddress</code> — The new address object</li>
        </ul>

        <p>Return a promise to update the order with new shipping costs. If you reject the promise, the address change will be rejected.</p>
      </td>
    </tr>

    <tr>
      <td><code>onShippingOptionsChange</code></td>
      <td>no</td>

      <td>
        <p><strong>function(data).</strong> Called when the buyer selects a different shipping option, for example, standard or express shipping.</p>
        <p>The data object contains:</p>

        <ul>
          <li><code>errors</code> — Errors to show to the user</li>
          <li><code>orderId</code> — The current order ID</li>
          <li><code>selectedShippingOption</code> — The selected option details</li>
        </ul>

        <p>Return a promise to update the order total with the new shipping cost.</p>
      </td>
    </tr>

    <tr>
      <td><code>orderId</code></td>
      <td>no</td>

      <td>
        <p><strong>string.</strong> An existing PayPal order ID to use for this session. This allows you to create the order on your server before starting the payment flow (eager order creation).</p>
        <p>If not provided, you'll pass an order creation function to the <code>start()</code> method.</p>
      </td>
    </tr>

    <tr>
      <td><code>commit</code></td>
      <td>no</td>

      <td>
        <p><strong>boolean.</strong> Controls the final button text in the PayPal flow:</p>

        <ul>
          <li><code>true</code> — Shows "Pay Now" (payment happens immediately)</li>
          <li><code>false</code> — Shows "Continue" (additional confirmation step)</li>
        </ul>

        <p>Default: <code>true</code></p>
      </td>
    </tr>

    <tr>
      <td><code>savePayment</code></td>
      <td>no</td>

      <td>
        <p><strong>boolean.</strong> Saves the customer's payment method during purchase. Set to <code>true</code> if your [Orders API request saves the payment method](https://developer.paypal.com/docs/checkout/save-payment-methods/during-purchase/orders-api/cards/).</p>
      </td>
    </tr>
  </tbody>
</table>

#### Returns

Returns a `PaymentSession` object with methods to control the payment flow.

```javascript lines theme={null}
interface PaymentSession {
  start(options?: StartOptions, orderPromise: Promise): Promise<void>;
  hasReturned(): boolean;
  resume(): Promise<void>;
}
```

#### Example

```javascript lines expandable theme={null}
const paypalSession = sdkInstance.createPayPalOneTimePaymentSession({
  onApprove: async (data) => {
    // Capture the payment on your server
    const response = await fetch(`/api/orders/${data.orderId}/capture`, {
      method: "POST",
    });

    if (response.ok) {
      // Payment successful
      window.location.href = "/order/complete";
    } else {
      throw new Error("Capture failed");
    }
  },

  onShippingAddressChange: async (data) => {
    // Calculate new shipping cost based on address
    const shippingCost = await calculateShipping(data.shippingAddress);

    // Update the order with new shipping
    return fetch(`/api/orders/${data.orderId}/update-shipping`, {
      method: "PATCH",
      body: JSON.stringify({ shippingCost }),
    });
  },

  onCancel: (data) => {
    console.log("Payment cancelled", data);
    // Re-enable checkout button
    document.getElementById("checkout-btn").disabled = false;
  },

  onError: (error) => {
    console.error("Payment error:", error);
    // Show error message to buyer
    showErrorMessage("Payment failed. Please try again.");
  },
});
```

### `sdkInstance.createPayPalSavePaymentSession(options)`

Create a session for saving PayPal as a payment method for future use (vaulting). This allows buyers to save their PayPal account for faster checkout in future purchases.

The parameters and usage are identical to `createPayPalOneTimePaymentSession`, except the `onApprove` callback receives a `billingToken` instead of requiring immediate payment capture.

#### Example

```javascript lines expandable theme={null}
const saveSession = sdkInstance.createPayPalSavePaymentSession({
  onApprove: async (data) => {
    // Save the billing token to your customer's profile
    await savePaymentMethod({
      customerId: currentUser.id,
      billingToken: data.billingToken,
      type: "paypal",
    });

    showSuccess("PayPal saved for future purchases");
  },
});
```

### `sdkInstance.createVenmoOneTimePaymentSession(options)`

Create a payment session for Venmo payments (US only). Venmo provides a mobile-optimized payment experience for US buyers using their Venmo balance or linked payment methods.

The parameters are identical to `createPayPalOneTimePaymentSession`. Venmo sessions support the same callbacks and flow options.

#### Example

```javascript lines theme={null}
const venmoSession = sdkInstance.createVenmoOneTimePaymentSession({
  onApprove: async (data) => {
    // Capture the Venmo payment
    await captureOrder(data.orderId);
  },
});
```

### `sdkInstance.createPayLaterOneTimePaymentSession(options)`

Create a session for Pay Later financing options. Pay Later allows buyers to pay in installments (like Pay in 4) or over time with longer-term financing.

The parameters are identical to `createPayPalOneTimePaymentSession`. Pay Later availability depends on transaction amount and buyer eligibility.

#### Example

```javascript lines expandable theme={null}
const payLaterSession = sdkInstance.createPayLaterOneTimePaymentSession({
  onApprove: async (data) => {
    await captureOrder(data.orderId);
    // Buyer has been approved for Pay Later financing
  },
});

// Configure the Pay Later button with product details
const details = paymentMethods.getDetails("paylater");
const button = document.querySelector("paylater-button");
button.productCode = details.productCode;
button.countryCode = details.countryCode;
```

### `sdkInstance.createPayPalCreditOneTimePaymentSession(options)`

Create a session for PayPal Credit payments (US only). PayPal Credit offers buyers a reusable line of credit for purchases.

### `sdkInstance.createPayPalSubscriptionSession(options)`

Create a payment session for PayPal subscription payments. Use subscriptions when buyers need recurring billing — for example, membership fees, software licenses, or regular service plans.

<Note>
  Before creating a subscription session, create a subscription plan using the [PayPal Subscriptions API](https://developer.paypal.com/docs/subscriptions/). You'll create a subscription ID for the buyer using this Plan ID when the buyer initiates checkout.
</Note>

#### Parameters

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Required</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>onApprove</code></td>
      <td>yes</td>

      <td>
        <p><strong>function(data)</strong> — Called when the buyer approves the subscription. The data object includes:</p>

        <ul>
          <li><code>subscriptionId</code> — The approved PayPal subscription ID. Use this to activate or retrieve subscription details on your server.</li>
          <li><code>payerId</code> — The buyer's PayPal payer ID.</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td><code>onCancel</code></td>
      <td>no</td>

      <td>
        <p><strong>function(data)</strong> — Called when the buyer cancels the subscription flow. The data object contains <code>subscriptionId</code> if a subscription was created.</p>
      </td>
    </tr>

    <tr>
      <td><code>onError</code></td>
      <td>no</td>

      <td>
        <p><strong>function(error)</strong> — Called when an error occurs during the subscription flow. The error object contains <code>code</code> and <code>message</code>.</p>
      </td>
    </tr>
  </tbody>
</table>

#### Returns

Returns a subscription session object with a `start(options?, subscriptionPromise)` method. `subscriptionPromise` must resolve to `{ subscriptionId: string }` containing your PayPal subscription ID.

#### Example

```javascript lines expandable theme={null}
const subscriptionSession = sdkInstance.createPayPalSubscriptionSession({
  onApprove: async (data) => {
    console.log("Subscription approved:", data.subscriptionId);

    // Record the subscription on your server
    await fetch("/api/subscriptions/activate", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ subscriptionId: data.subscriptionId }),
    });

    window.location.href = "/subscription/success";
  },

  onCancel: (data) => {
    console.log("Subscription cancelled");
    document.getElementById("subscribe-button").disabled = false;
  },

  onError: (error) => {
    console.error("Subscription error:", error.code, error.message);
  },
});

document.getElementById("subscribe-button").addEventListener("click", () => {
  subscriptionSession.start(
    { presentationMode: "auto" },
    Promise.resolve({ subscriptionId: "YOUR_SUBSCRIPTION_ID" })
  );
});
```

### `sdkInstance.createGooglePayOneTimePaymentSession()`

Create a session for Google Pay payments. The Google Pay session integrates with the [Google Pay API](https://developers.google.com/pay/api/web/guides/tutorial) and handles PayPal order confirmation.

<Note>
  Google Pay requires the `googlepay-payments` component and the [Google Pay JavaScript SDK](https://pay.google.com/gp/p/js/pay.js). Load both before calling this method. Enable Google Pay in your PayPal sandbox and production account settings before going live.
</Note>

#### Returns

Returns a `GooglePaySession` object (synchronously) with these methods:

#### `googlePaySession.formatConfigForPaymentRequest(config)`

Format the Google Pay configuration for the Google Pay API. Before calling this method, use `sdkInstance.findEligibleMethods()` to check eligibility and retrieve the raw configuration, then pass the `.config` property from `paymentMethods.getDetails("googlepay")`:

```javascript theme={null}
const paymentMethods = await sdkInstance.findEligibleMethods({ currencyCode: "USD" });
const googlePayPaymentMethodDetails = paymentMethods.getDetails("googlepay");
const googlePayConfig = googlePaySession.formatConfigForPaymentRequest(
  googlePayPaymentMethodDetails.config,
);
```

##### Parameters

| Parameter | Required | Description                                                                      |
| :-------- | :------- | :------------------------------------------------------------------------------- |
| `config`  | yes      | **object.** The `config` property from `paymentMethods.getDetails("googlepay")`. |

##### Returns

Returns a formatted configuration object:

| Property                | Type   | Description                                         |
| :---------------------- | :----- | :-------------------------------------------------- |
| `allowedPaymentMethods` | array  | Payment method configuration for the Google Pay API |
| `merchantInfo`          | object | PayPal merchant information for Google Pay          |
| `apiVersion`            | number | Google Pay API version                              |
| `apiVersionMinor`       | number | Google Pay API minor version                        |
| `countryCode`           | string | Two-letter ISO 3166-1 country code                  |

#### `googlePaySession.confirmOrder(options)`

Use the payment data from Google Pay to confirm the PayPal order. Call this inside the `onPaymentAuthorized` callback.

##### Parameters

| Parameter           | Required | Description                                                                                                       |
| :------------------ | :------- | :---------------------------------------------------------------------------------------------------------------- |
| `orderId`           | yes      | **string.** The PayPal order ID created on your server.                                                           |
| `paymentMethodData` | yes      | **object.** The payment method data from the Google Pay authorization response (`paymentData.paymentMethodData`). |

##### Returns

Returns a promise that resolves to `{ status }`:

| Status                  | Description                                       |
| :---------------------- | :------------------------------------------------ |
| `APPROVED`              | Order confirmed and ready to capture.             |
| `PAYER_ACTION_REQUIRED` | 3D Secure authentication required before capture. |

#### Example

```javascript lines expandable theme={null}
const sdkInstance = await window.paypal.createInstance({
  clientId: "YOUR_CLIENT_ID",
  components: ["googlepay-payments"],
  pageType: "checkout",
});

// Check eligibility before setting up Google Pay
const paymentMethods = await sdkInstance.findEligibleMethods({
  currencyCode: "USD",
});

if (paymentMethods.isEligible("googlepay")) {
  const googlePayPaymentMethodDetails = paymentMethods.getDetails("googlepay");

  // Create Google Pay session and format config
  const googlePaySession = sdkInstance.createGooglePayOneTimePaymentSession();
  const googlePayConfig = googlePaySession.formatConfigForPaymentRequest(
    googlePayPaymentMethodDetails.config,
  );

  // Initialize Google Pay client
  const paymentsClient = new google.payments.api.PaymentsClient({
    environment: "TEST", // Use "PRODUCTION" for live transactions
    paymentDataCallbacks: {
      onPaymentAuthorized: async (paymentData) => {
        try {
          const orderId = await createOrder();

          const { status } = await googlePaySession.confirmOrder({
            orderId,
            paymentMethodData: paymentData.paymentMethodData,
          });

          if (status !== "PAYER_ACTION_REQUIRED") {
            await captureOrder(orderId);
          }

          return { transactionState: "SUCCESS" };
        } catch (err) {
          return {
            transactionState: "ERROR",
            error: { message: err.message },
          };
        }
      },
    },
  });

  // Check readiness and render button
  const { result } = await paymentsClient.isReadyToPay({
    allowedPaymentMethods: googlePayConfig.allowedPaymentMethods,
    apiVersion: googlePayConfig.apiVersion,
    apiVersionMinor: googlePayConfig.apiVersionMinor,
  });

  if (result) {
    const button = paymentsClient.createButton({
      onClick: () => {
        paymentsClient.loadPaymentData({
          ...googlePayConfig,
          transactionInfo: {
            countryCode: googlePayConfig.countryCode,
            currencyCode: "USD",
            totalPriceStatus: "FINAL",
            totalPrice: "10.00",
          },
          callbackIntents: ["PAYMENT_AUTHORIZATION"],
        });
      },
    });
    document.getElementById("google-pay-container").appendChild(button);
  }
}
```

### `sdkInstance.createApplePayOneTimePaymentSession()`

Create a session for Apple Pay payments. The Apple Pay session integrates with the browser's native `ApplePaySession` API and handles merchant validation and order confirmation.

<Note>
  Apple Pay requires:

  * The `applepay-payments` component
  * The [Apple Pay JavaScript SDK](https://applepay.cdn-apple.com/jsapi/v1/apple-pay-sdk.js)
  * An HTTPS connection
  * A merchant domain registration with PayPal
    Apple Pay is available in Safari on Apple devices only.
</Note>

#### Returns

Returns a promise that resolves to an Apple Pay session object with these methods:

#### `applePaySession.config()`

Fetch the Apple Pay merchant configuration from PayPal.

##### Returns

Returns a promise that resolves to:

| Property               | Type      | Description                                                                             |
| :--------------------- | :-------- | :-------------------------------------------------------------------------------------- |
| `merchantCapabilities` | string\[] | Merchant capabilities for the Apple Pay payment request, for example, `["supports3DS"]` |
| `supportedNetworks`    | string\[] | Card networks the merchant accepts, for example, `["visa", "masterCard", "amex"]`       |

#### `applePaySession.validateMerchant(options)`

Complete Apple Pay merchant validation. Call this inside the `onvalidatemerchant` event handler of the browser's `ApplePaySession`.

##### Parameters

| Parameter       | Required | Description                                                                                 |
| :-------------- | :------- | :------------------------------------------------------------------------------------------ |
| `validationUrl` | yes      | **string.** The validation URL from the `onvalidatemerchant` event (`event.validationURL`). |

##### Returns

Returns a promise that resolves to `{ merchantSession }`. Pass `merchantSession` to `applePaySession.completeMerchantValidation()`.

#### `applePaySession.confirmOrder(options)`

Confirm the PayPal order using the payment token from Apple Pay. Call this inside the `onpaymentauthorized` event handler.

##### Parameters

| Parameter         | Required | Description                                                                    |
| :---------------- | :------- | :----------------------------------------------------------------------------- |
| `orderId`         | yes      | **string.** The PayPal order ID created on your server.                        |
| `token`           | yes      | **object.** The Apple Pay payment token from `event.payment.token`.            |
| `billingContact`  | no       | **object.** The buyer's billing contact from `event.payment.billingContact`.   |
| `shippingContact` | no       | **object.** The buyer's shipping contact from `event.payment.shippingContact`. |

#### Payment request structure

Build an `ApplePayPaymentRequest` to pass to the browser's `new ApplePaySession()`:

| Property                        | Description                                                                            |
| :------------------------------ | :------------------------------------------------------------------------------------- |
| `countryCode`                   | Merchant country code, for example, `"US"`                                             |
| `currencyCode`                  | Transaction currency code, for example, `"USD"`                                        |
| `merchantCapabilities`          | From `applePaySession.config()`                                                        |
| `supportedNetworks`             | From `applePaySession.config()`                                                        |
| `requiredBillingContactFields`  | Array of required billing fields: `"name"`, `"phone"`, `"email"`, `"postalAddress"`    |
| `requiredShippingContactFields` | Array of required shipping fields, or empty array if no shipping needed                |
| `total`                         | Object with `label` (string), `amount` (string), and `type` (`"final"` or `"pending"`) |

#### Example

```javascript lines expandable theme={null}
const sdkInstance = await window.paypal.createInstance({
  clientId: "YOUR_CLIENT_ID",
  components: ["applepay-payments"],
  pageType: "checkout",
});

// Create Apple Pay session
const paypalApplePaySession = sdkInstance.createApplePayOneTimePaymentSession();

// Get merchant configuration
    const paymentMethods = await sdkInstance.findEligibleMethods({
      currencyCode: "USD",
    });

    if (paymentMethods.isEligible("applepay")) {
      const applePayPaymentMethodDetails =
        paymentMethods.getDetails("applepay");
      setupApplePayButton(sdkInstance, applePayPaymentMethodDetails);

// Display Apple Pay button
document.getElementById("apple-pay-container").innerHTML =
  '<apple-pay-button buttonstyle="black" type="buy" locale="en"></apple-pay-button>';

document.querySelector("apple-pay-button").addEventListener("click", async () => {
  const paymentRequest = {
    countryCode: "US",
    currencyCode: "USD",
    merchantCapabilities,
    supportedNetworks,
    requiredBillingContactFields: ["name", "postalAddress"],
    requiredShippingContactFields: [],
    total: {
      label: "Your Store",
      amount: "25.00",
      type: "final",
    },
  };

  const applePaySession = new ApplePaySession(4, paymentRequest);

  applePaySession.onvalidatemerchant = async (event) => {
    try {
      const { merchantSession } = await paypalApplePaySession.validateMerchant({
        validationUrl: event.validationURL,
      });
      applePaySession.completeMerchantValidation(merchantSession);
    } catch (err) {
      console.error("Merchant validation failed:", err);
      applePaySession.abort();
    }
  };

  applePaySession.onpaymentauthorized = async (event) => {
    try {
      const orderId = await createOrder();

      await paypalApplePaySession.confirmOrder({
        orderId,
        token: event.payment.token,
        billingContact: event.payment.billingContact,
        shippingContact: event.payment.shippingContact,
      });

      await captureOrder(orderId);

      applePaySession.completePayment({
        status: ApplePaySession.STATUS_SUCCESS,
      });
    } catch (err) {
      console.error("Payment failed:", err);
      applePaySession.completePayment({
        status: ApplePaySession.STATUS_FAILURE,
      });
    }
  };

  applePaySession.oncancel = () => {
    console.log("Apple Pay cancelled");
  };

  applePaySession.begin();
});
```

### `sdkInstance.createFastlane()`

Create a Fastlane instance for accelerated guest checkout. Fastlane enables one-click checkout for recognized guests.

#### Returns

Returns a promise that resolves to a Fastlane instance.

#### Example

```javascript theme={null}
const fastlane = await sdkInstance.createFastlane();
// Use fastlane instance for guest checkout acceleration
```

### `sdkInstance.createPayPalMessages(options?)`

Display PayPal Messages to show financing options and promotional messaging to buyers. These messages dynamically update based on the transaction amount and buyer eligibility.

#### Parameters

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Required</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>amount</code></td>
      <td>no</td>

      <td>
        <p><strong>number.</strong> The product or cart amount to display messaging for. Messages update dynamically based on this amount.</p>
      </td>
    </tr>

    <tr>
      <td><code>placement</code></td>
      <td>no</td>

      <td>
        <p><strong>string.</strong> The page placement context for the messages. This affects message format and content.</p>
        <p>Values: <code>product</code>, <code>cart</code>, <code>checkout</code></p>
      </td>
    </tr>

    <tr>
      <td><code>style</code></td>
      <td>no</td>

      <td>
        <p><strong>object.</strong> Visual styling options for the messages, including layout and logo configuration.</p>
      </td>
    </tr>
  </tbody>
</table>

#### Returns

Returns a `PayPalMessagesInstance` object with `fetchContent(options?)` and `createLearnMore(options?)` methods.

#### `messagesInstance.fetchContent(options?)`

Fetch message content from PayPal and render it in all `<paypal-messages>` components on the page.

| Option            | Required | Description                                                                                                                                                                     |
| :---------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `amount`          | no       | **string.** Transaction amount with up to 2 decimal places, for example, `"125.00"`. Affects which financing offers are displayed.                                              |
| `currencyCode`    | no       | **string.** Three-letter ISO 4217 currency code, for example, `"USD"`.                                                                                                          |
| `logoPosition`    | no       | **string.** Where to place the PayPal logo. Values: `LEFT` (default), `RIGHT`, `TOP`, `INLINE`. Note: `MONOGRAM` logo type requires `LEFT`; `TEXT` logo type requires `INLINE`. |
| `logoType`        | no       | **string.** PayPal branding style. Values: `WORDMARK` (default), `MONOGRAM`, `TEXT`.                                                                                            |
| `textColor`       | no       | **string.** Message text color. Values: `BLACK` (default), `WHITE`, `MONOCHROME`.                                                                                               |
| `onContentReady`  | no       | **function.** Called when content arrives from the server. Takes precedence over `onReady`.                                                                                     |
| `onTemplateReady` | no       | **function.** Called when content is served from local cache. Takes precedence over `onReady`.                                                                                  |
| `onReady`         | no       | **function.** Called when content is ready from either cache or server. Used when neither `onContentReady` nor `onTemplateReady` is specified.                                  |

#### `messagesInstance.createLearnMore(options?)`

Initialize a Learn more presentation that provides additional financing details when buyers select the Learn more link in a message.

| Option             | Required | Description                                                                                              |
| :----------------- | :------- | :------------------------------------------------------------------------------------------------------- |
| `amount`           | no       | **string.** The transaction amount to display in the Learn more presentation.                            |
| `presentationMode` | no       | **string.** How the Learn more content is shown. Values: `AUTO` (default), `MODAL`, `POPUP`, `REDIRECT`. |
| `onApply`          | no       | **function.** Called when the buyer selects Apply in the Learn more presentation.                        |
| `onCalculate`      | no       | **function.** Called when the buyer enters a value in the amount input field.                            |
| `onShow`           | no       | **function.** Called when the Learn more presentation opens.                                             |
| `onClose`          | no       | **function.** Called when the Learn more presentation closes.                                            |

#### CSS custom properties

Customize message appearance using these CSS properties on the `<paypal-messages>` element:

| Property                      | Description                                        | Default |
| :---------------------------- | :------------------------------------------------- | :------ |
| `--paypal-message-font-size`  | Font size in `px`, clamped to `10px`–`16px`.       | `14px`  |
| `--paypal-message-text-align` | Text alignment. Values: `left`, `right`, `center`. | `left`  |

#### Example

```javascript lines expandable theme={null}
const sdkInstance = await window.paypal.createInstance({
  clientId: "YOUR_CLIENT_ID",
  components: ["paypal-messages"],
});

const messagesInstance = sdkInstance.createPayPalMessages();

// Render message with style options
messagesInstance.fetchContent({
  amount: "199.99",
  currencyCode: "USD",
  logoPosition: "LEFT",
  logoType: "WORDMARK",
  textColor: "BLACK",
  onContentReady: () => {
    document.getElementById("paypal-message-container").style.display = "block";
  },
});

// Optional: create a Learn More presentation
const learnMore = messagesInstance.createLearnMore({
  amount: "199.99",
  presentationMode: "MODAL",
  onShow: () => console.log("Learn more opened"),
  onClose: () => console.log("Learn more closed"),
});
```

```html lines theme={null}
<!-- PayPal Messages web component with CSS custom properties -->
<paypal-messages
  style="--paypal-message-font-size: 14px; --paypal-message-text-align: left;"
></paypal-messages>
```

### `paymentSession.start(options?, orderPromise)`

Start the payment user experience. This method opens the payment interface using the specified presentation mode and begins the checkout flow.

#### Parameters

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Required</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>options</code></td>
      <td>no</td>

      <td>
        <p><strong>object.</strong> Configuration for how the payment UI is presented.</p>
      </td>
    </tr>

    <tr>
      <td><code>options.presentationMode</code></td>
      <td>no</td>

      <td>
        <p><strong>string.</strong> Controls how the payment interface is displayed to the buyer.</p>
        <p>Available modes:</p>

        <ul>
          <li><code>auto</code> — Recommended. SDK automatically selects the best experience. Tries popup first and falls back to modal if popups are blocked.</li>
          <li><code>popup</code> — Opens PayPal in a popup window. May be blocked by popup blockers.</li>
          <li><code>modal</code> — Creates an iframe overlay on the current page. Recommended only for WebView scenarios. Do not use in desktop web scenarios as this integration has limitations on cookies, which can affect user authentication.</li>
          <li><code>redirect</code> — Full page redirect to PayPal. Recommended for mobile devices. Requires a return/cancel URL.</li>
          <li><code>payment-handler</code> — Experimental. Uses the browser's Payment Handler API. Provides a native payment experience. Modern browsers only. </li>
        </ul>

        <p>Default: <code>auto</code></p>
        <p>The SDK will automatically fall back to alternative modes if the requested mode is unavailable.</p>
      </td>
    </tr>

    <tr>
      <td><code>options.autoRedirect</code></td>
      <td>no</td>

      <td>
        <p><strong>object.</strong> Configuration for redirect mode behavior.</p>

        <ul>
          <li><code>enabled</code> (boolean) — Whether to automatically redirect or return the URL</li>
        </ul>

        <p>Only applies when using <code>presentationMode: "redirect"</code>.</p>
      </td>
    </tr>

    <tr>
      <td><code>options.fullPageOverlay</code></td>
      <td>no</td>

      <td>
        <p><strong>object.</strong> Controls the background overlay when using popup mode.</p>

        <ul>
          <li><code>enabled</code> (boolean) — Show/hide the page overlay</li>
        </ul>

        <p>Default: <code>enabled: true</code></p>
      </td>
    </tr>

    <tr>
      <td><code>options.loadingScreen</code></td>
      <td>no</td>

      <td>
        <p><strong>object.</strong> Customize the loading screen text.</p>

        <ul>
          <li><code>label</code> (string) — Currently only supports "connecting"</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td><code>orderPromise</code></td>
      <td>yes</td>

      <td>
        <p><strong>promise.</strong> A promise that creates or retrieves the PayPal order. This promise should resolve to an object containing the <code>orderId</code>.</p>
        <p>The order creation can happen asynchronously while the payment UI is loading, improving perceived performance.</p>
      </td>
    </tr>
  </tbody>
</table>

#### Returns

For most presentation modes, returns a promise that resolves when the payment flow completes or is cancelled.

For redirect mode with `autoRedirect.enabled: false`, returns the redirect URL:

```javascript theme={null}
Promise<{ redirectURL: string }>
```

#### Example

```javascript lines expandable theme={null}
// Basic usage with auto mode
await paymentSession.start(
  { presentationMode: "auto" },
  createOrder() // Returns Promise<{orderId: string}>
);

// Redirect mode with manual handling
const { redirectURL } = await paymentSession.start(
  {
    presentationMode: "redirect",
    autoRedirect: { enabled: false },
  },
  createOrder()
);

if (redirectURL) {
  // Manually redirect the buyer to a new tab
  // Only recommended for use cases where the v6 SDK is being wrapped in an iframe
  // Or usage with redirect flow for webview use cases
  window.location.href = redirectURL;
}

// Fallback pattern for incompatible browsers
const modes = [
  { mode: "popup", errorCode: "ERR_DEV_UNABLE_TO_OPEN_POPUP" },
  { mode: "modal", errorCode: null },
];

for (const { mode, errorCode } of modes) {
  try {
    await paymentSession.start({ presentationMode: mode }, createOrder());
    break; // Success
  } catch (error) {
    if (errorCode && error.code === errorCode) {
      continue; // Try next mode
    }
    throw error; // Unexpected error
  }
}
```

### `paymentSession.hasReturned()`

Check if the current page load is a return from a redirect payment flow. Use this method on page load to detect and resume interrupted payment sessions.

#### Returns

Returns `true` if the buyer is returning from a PayPal redirect, `false` otherwise.

#### Example

```javascript lines expandable theme={null}
// Runs on page load when SDK has finished downloading
async function onPayPalWebSdkLoaded() {
  try {
    const sdkInstance = await window.paypal.createInstance({
      clientId: "YOUR_CLIENT_ID",
      components: ["paypal-payments"],
      pageType: "checkout",
    });
    const paypalPaymentSession = sdkInstance.createPayPalOneTimePaymentSession(
      paymentSessionOptions
    );
    // Check to see if Buyer is returning from PayPal
    if (paypalPaymentSession.hasReturned()) {
      // Original callbacks will be triggered
      await paypalPaymentSession.resume();
    } else {
      configurePayPalButton(paypalPaymentSession);
    }
  } catch (error) {
    console.error(error);
  }
}
```

### `paymentSession.resume()`

Resume a payment session after returning from a redirect flow. This method continues the payment process and triggers the appropriate callbacks based on the payment outcome.

#### Returns

Returns a promise that resolves when the session is successfully resumed.

## Handling callbacks

Callbacks allow you to respond to events during the payment flow. Each callback receives specific data about the event and can optionally return a promise to perform asynchronous operations.

### `onApprove(data)`

Called when the buyer successfully approves the payment. This is where you should capture or authorize the payment on your server.

#### Parameters

The callback receives a data object with the following properties:

| Property       | Type                | Description                                                                            |
| :------------- | :------------------ | :------------------------------------------------------------------------------------- |
| `orderId`      | string              | The PayPal order ID that was approved. Use this to capture the payment on your server. |
| `payerId`      | string              | The buyer's PayPal payer ID. This identifies the PayPal account used for payment.      |
| `paymentId`    | string \| undefined | Legacy payment ID for backwards compatibility. Only present in certain flows.          |
| `billingToken` | string \| undefined | Token for saving payment method. Only present when using save payment sessions.        |

#### Return value

The callback can optionally return a promise. If a promise is returned, the SDK waits for it to resolve before completing the flow.

#### Example

```javascript lines expandable theme={null}
onApprove: async (data) => {
  console.log("Payment approved for order:", data.orderId);

  // Capture the payment on your server
  const response = await fetch(`/api/orders/${data.orderId}/capture`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
  });

  const captureData = await response.json();

  if (captureData.status === "COMPLETED") {
    // Redirect to success page
    window.location.href = `/order/success?id=${data.orderId}`;
  } else {
    throw new Error("Payment capture failed");
  }
};
```

### `onCancel(data)`

Called when the buyer cancels the payment without completing it. This typically happens when they close the PayPal window or select a cancel button.

#### Parameters

| Property  | Type                | Description                                                                                               |
| :-------- | :------------------ | :-------------------------------------------------------------------------------------------------------- |
| `orderId` | string \| undefined | The order ID if one was created before cancellation. May be undefined if cancelled before order creation. |

#### Example

```javascript lines expandable theme={null}
onCancel: (data) => {
  console.log("Payment cancelled", data);

  // Use your own analytics to track cancellation
  // Always ensure this is a non-blocking call
  analytics.track("checkout_abandoned", {
    orderId: data.orderId,
    timestamp: Date.now(),
  });

  // Show a message to the buyer
  showMessage("Your payment was cancelled. Your cart items are still saved.");

  // Re-enable the checkout button
  document.getElementById("checkout-button").disabled = false;
};
```

### `onError(error)`

Called when an error occurs during the payment flow. This includes network errors, validation failures, and payment processing errors.

#### Parameters

The callback receives an error object with these properties:

| Property  | Type   | Description                                                                                     |
| --------- | ------ | ----------------------------------------------------------------------------------------------- |
| `code`    | string | A specific error code identifying the type of error. Use this for programmatic error handling.  |
| `message` | string | A human-readable error description. This may contain technical details not suitable for buyers. |

#### Common error codes

| Code                                            | Description                        | Recommended action                    |
| :---------------------------------------------- | :--------------------------------- | :------------------------------------ |
| `ERR_INVALID_CLIENT_TOKEN`                      | Client token is invalid or expired | Generate a new token and reinitialize |
| `ERR_DOMAIN_MISMATCH`                           | Current domain doesn't match token | Verify domain configuration           |
| `ERR_DEV_UNABLE_TO_OPEN_POPUP`                  | Popup was blocked by browser       | Fall back to modal or redirect mode   |
| `ERR_FLOW_PAYMENT_HANDLER_BROWSER_INCOMPATIBLE` | Payment handler not supported      | Use traditional checkout flow         |
| `INSTRUMENT_DECLINED`                           | Payment method was declined        | Suggest alternative payment method    |
| `NETWORK_ERROR`                                 | Network request failed             | Retry or check connection             |

#### Example

```javascript lines expandable theme={null}
onError: (error) => {
  console.error("Payment error:", error);

  // Log to error tracking service
  errorReporter.log(error);

  // Show user-friendly message based on error code
  let message;
  switch (error.code) {
    case "ERR_INVALID_CLIENT_TOKEN":
      message = "Your session has expired. Please refresh and try again.";
      setTimeout(() => location.reload(), 3000);
      break;
    case "INSTRUMENT_DECLINED":
      message =
        "Your payment was declined. Please try a different payment method.";
      break;
    case "NETWORK_ERROR":
      message = "Connection lost. Please check your internet and try again.";
      break;
    default:
      message = "Something went wrong. Please try again.";
  }

  showErrorMessage(message);
};
```

### `onShippingAddressChange(data)`

Called when the buyer selects or changes their shipping address within the PayPal flow. Use this callback to update shipping costs, validate addresses, or apply location-based restrictions.

#### Data properties

| Property                      | Type   | Description                                                   |
| :---------------------------- | :----- | :------------------------------------------------------------ |
| `errors`                      | object | Error messages you can display to the user in the Checkout UI |
| `errors.ADDRESS_ERROR`        | string | "Your order can't be shipped to this address."                |
| `errors.COUNTRY_ERROR`        | string | "Your order can't be shipped to this country."                |
| `errors.STATE_ERROR`          | string | "Your order can't be shipped to this state."                  |
| `errors.ZIP_ERROR`            | string | "Your order can't be shipped to this zip."                    |
| `orderId`                     | string | The current order ID                                          |
| `shippingAddress`             | object | The newly selected shipping address                           |
| `shippingAddress.city`        | string | City name                                                     |
| `shippingAddress.state`       | string | State or province code                                        |
| `shippingAddress.countryCode` | string | ISO 3166-1 alpha-2 country code                               |
| `shippingAddress.postalCode`  | string | Postal or ZIP code                                            |

#### Return value

Return a promise to update the order asynchronously. If the promise rejects, the address change will be rejected and the buyer must select a different address.

#### Example

```javascript lines expandable theme={null}
onShippingAddressChange: async (data) => {
  const { errors, shippingAddress } = data;

  // Check if we ship to this address
  if (!isShippableLocation(shippingAddress)) {
    // Reject the address change
    throw new Error(errors.ADDRESS_ERROR);
  }

  // Calculate new shipping cost
  const shippingCost = calculateShipping({
    address: shippingAddress,
    items: cartItems,
  });

  // Update the order with new shipping
  const response = await fetch(`/api/orders/${data.orderId}/shipping`, {
    method: "PATCH",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      shippingAddress,
      shippingCost,
    }),
  });

  if (!response.ok) {
    throw new Error("Failed to update shipping");
  }
};
```

### `onShippingOptionsChange(data)`

Called when the buyer selects a different shipping option, for example, standard or express delivery. Use this to update the order total with the selected shipping cost.

#### Data properties

| Property                    | Type   | Description                                                                                        |
| :-------------------------- | :----- | :------------------------------------------------------------------------------------------------- |
| `errors`                    | object | Error messages you can display to the user in the Checkout UI                                      |
| `errors.METHOD_UNAVAILABLE` | string | "The shipping method you chose is unavailable. To continue, choose another way to get your order." |
| `errors.STORE_UNAVAILABLE`  | string | "Part of your order isn't available at this store."                                                |
| `orderId`                   | string | The current order ID                                                                               |
| `selectedShippingOption`    | object | Details of the selected shipping option                                                            |

#### Example

```javascript lines expandable theme={null}
onShippingOptionsChange: async (data) => {
  const { errors, selectedShippingOption } = data;

  // disable store pickup
  if (selectedShippingOption.type === 'PICKUP') {
    throw new Error(errors.STORE_UNAVAILABLE);
  }

  // Update order with new shipping option
  await updateOrderShipping({
    orderId: data.orderId,
    shippingId: selectedShippingOption.id,
    shippingCost: selectedShippingOption.amount.value,
  });
};
```

## Web components

PayPal.js provides native web components for rendering payment buttons. These components automatically handle styling and accessibility while allowing customization through CSS variables.

### `paypal-button`

The PayPal button web component renders a PayPal-branded button that buyers select to start the payment flow.

#### Attributes

<table>
  <thead>
    <tr>
      <th>Attribute</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>type</code></td>
      <td>string</td>

      <td>
        <p>Controls the button label text. Different types are optimized for different contexts in your checkout flow.</p>
        <p>Values:</p>

        <ul>
          <li><code>pay</code> — "Pay with PayPal"</li>
          <li><code>checkout</code> — "PayPal Checkout"</li>
          <li><code>buynow</code> — "PayPal Buy Now"</li>
          <li><code>subscribe</code> — "PayPal Subscribe"</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td><code>class</code></td>
      <td>string</td>

      <td>
        <p>Applies a predefined color scheme to the button.</p>
        <p>Values:</p>

        <ul>
          <li><code>paypal-gold</code> — Gold background (recommended)</li>
          <li><code>paypal-blue</code> — Blue background</li>
          <li><code>paypal-white</code> — White with border</li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

#### CSS variables

Customize the button appearance using CSS custom properties:

| Variable                        | Description                            | Example values  |
| :------------------------------ | :------------------------------------- | :-------------- |
| `--paypal-button-border-radius` | Border radius for the button           | 4px, 20px, 50px |
| `--paypal-mark-border-radius`   | Border radius for the PayPal mark/logo | 4px, 8px        |

#### Example

```html lines expandable theme={null}
<!-- Basic button -->
<paypal-button type="pay" class="paypal-gold"></paypal-button>

<!-- Initially hidden button -->
<paypal-button type="checkout" class="paypal-blue" hidden> </paypal-button>

<!-- Custom styled button -->
<style>
  paypal-button {
    --paypal-button-border-radius: 10px;
    width: 100%;
    max-width: 350px;
  }

  paypal-button.custom-style {
    --paypal-button-border-radius: 25px;
  }
</style>

<paypal-button type="pay" class="paypal-gold custom-style"></paypal-button>

<script>
  // Attach click handler
  const onClick = async () => {
    try {
      await paypalSession.start({ presentationMode: "auto" }, createOrder());
    } catch (error) {
      console.log(error);
    }
  };

  document.querySelector("paypal-button").addEventListener("click", onClick);
</script>
```

### `venmo-button`

The Venmo button web component renders a Venmo-branded button for US buyers. The attributes and styling options are identical to `<paypal-button>`.

### Example

```html theme={null}
<venmo-button type="pay" class="venmo-blue"></venmo-button>
```

### `paylater-button`

The Pay Later button component displays financing options to buyers. This button requires additional configuration based on the available Pay Later products.

#### Attributes

| Attribute     | Type   | Description                                                                                                                  |
| :------------ | :----- | :--------------------------------------------------------------------------------------------------------------------------- |
| `productCode` | string | The specific Pay Later product to display, for example, `"PAY_IN_4"`. Get this from `paymentMethods.getDetails('paylater')`. |
| `countryCode` | string | The country code for the Pay Later offer. Required for proper messaging display.                                             |

#### Example

```javascript lines theme={null}
// Configure Pay Later button
const payLaterDetails = paymentMethods.getDetails("paylater");

const button = document.querySelector("paylater-button");
button.productCode = payLaterDetails.productCode;
button.countryCode = payLaterDetails.countryCode;
button.removeAttribute("hidden");
```

### `paypal-credit-button`

The PayPal Credit button component displays PayPal's credit offering for eligible buyers (US only).

#### Attributes

| Attribute     | Type   | Description                                                                   |
| :------------ | :----- | :---------------------------------------------------------------------------- |
| `countryCode` | string | The country code for PayPal Credit availability. Required for proper display. |

#### Example

```javascript lines theme={null}
const creditDetails = paymentMethods.getDetails("credit");

const button = document.querySelector("paypal-credit-button");
button.countryCode = creditDetails.countryCode;
```

### Browser compatibility

The JavaScript SDK v6 supports modern browsers. Check browser compatibility before initializing the SDK to ensure optimal user experience.

#### Minimum supported versions

| Browser (web/mobile web) | Minimum Supported Version |
| :----------------------- | :------------------------ |
| Chrome                   | 69                        |
| Safari                   | 12                        |
| Firefox                  | 63                        |
| Samsung Internet         | 10                        |
| Edge                     | 79                        |

#### Browser support check

Use the `window.isBrowserSupportedByPayPal()` function to verify browser compatibility before initializing the SDK:

```javascript lines theme={null}
// Check browser compatibility
if (window.isBrowserSupportedByPayPal()) {
  // Initialize PayPal SDK
  const sdkInstance = await window.paypal.createInstance({
    clientId: "YOUR_CLIENT_ID",
  });
} else {
  // Show fallback payment options or browser upgrade message
  showBrowserNotSupportedMessage();
}
```

## Card fields

Card fields let you embed inline card input components on your page for credit and debit card payments. Card fields keep buyers on your page for the entire payment experience. Card data flows through PayPal-hosted iframes, so your site never handles raw card numbers.

<Note>
  Card fields require the `card-fields` component. Check eligibility using `paymentMethods.isEligible("advanced_cards")` before rendering the fields. For PCI compliance requirements, see [PCI DSS SAQ A-EP](https://www.pcisecuritystandards.org/).
</Note>

### `sdkInstance.createCardFieldsOneTimePaymentSession()`

Create a card fields session for a one-time payment. The session provides methods to create individual card input components and submit the payment.

#### Returns

Returns a `CardFieldsOneTimePaymentSession` object with `createCardFieldsComponent(options)` and `submit(orderId, options?)` methods.

### `sdkInstance.createCardFieldsSavePaymentSession()`

Create a card fields session for saving a card payment method (vaulting) for future use. The session behaves the same as the one-time session.

### `cardSession.createCardFieldsComponent(options)`

Create an individual card field input component. The method returns an `HTMLElement` that you append directly to a DOM container.

#### Parameters

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Required</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>type</code></td>
      <td>yes</td>

      <td>
        <p><strong>string.</strong> The card field to render.</p>
        <p>Values:</p>

        <ul>
          <li><code>number</code> — Card number field</li>
          <li><code>expiry</code> — Expiration date field</li>
          <li><code>cvv</code> — Security code field</li>
          <li><code>name</code> — Cardholder name field</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td><code>placeholder</code></td>
      <td>no</td>

      <td>
        <p><strong>string.</strong> Placeholder text shown inside the field when empty, for example, <code>"Card number"</code> or <code>"MM/YY"</code>.</p>
      </td>
    </tr>

    <tr>
      <td><code>style</code></td>
      <td>no</td>

      <td>
        <p><strong>object.</strong> CSS styles applied within the PayPal-hosted iframe. See <a href="#card-field-styling">Card field styling</a>.</p>
      </td>
    </tr>
  </tbody>
</table>

#### Returns

Returns an `HTMLElement`. Mount it to a container using `appendChild()` or equivalent.

```javascript lines theme={null}
const numberField = cardSession.createCardFieldsComponent({
  type: "number",
  placeholder: "Card number",
});

document.getElementById("card-number-container").appendChild(numberField);
```

### `cardSession.submit(orderId, options?)`

Submit the card payment. This validates the card data, runs 3D Secure (3DS) authentication if required, and returns the payment outcome.

#### Parameters

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Required</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>orderId</code></td>
      <td>yes</td>

      <td>
        <p><strong>string.</strong> The PayPal order ID created on your server. Pass the string directly — do not pass an object such as .</p>
      </td>
    </tr>

    <tr>
      <td><code>options.billingAddress</code></td>
      <td>no</td>

      <td>
        <p><strong>object.</strong> Billing address fields to include with the payment for risk and SCA purposes. Include at minimum the fields your risk strategy requires.</p>
        <p>Available fields: <code>postalCode</code>, <code>streetAddress</code>, <code>city</code>, <code>state</code>, <code>countryCode</code>.</p>
      </td>
    </tr>
  </tbody>
</table>

#### Returns

Returns a promise that resolves to `{ data, state }`:

| State       | Description                                                                                                |
| :---------- | :--------------------------------------------------------------------------------------------------------- |
| `succeeded` | Payment succeeded. `data.orderId` is the order ID to capture. `data.liabilityShift` indicates 3DS outcome. |
| `canceled`  | Buyer dismissed the 3D Secure modal. Display a non-blocking message and allow the buyer to retry.          |
| `failed`    | Validation or processing failure. `data.message` may contain details. Show an error and allow retry.       |

### Card field styling

Pass a `style` object to `createCardFieldsComponent()` to customize card field appearance. Styles are applied within the PayPal-hosted iframe.

#### Supported CSS selectors

| Selector   | When it applies                               |
| :--------- | :-------------------------------------------- |
| `input`    | The card input element                        |
| `.invalid` | Applied when the field value fails validation |
| `:focus`   | Applied when the field has keyboard focus     |

#### Supported CSS properties

* `appearance`
* `background`
* `border`
* `borderRadius`
* `boxShadow`
* `color`
* `direction`
* `font`
* `fontFamily`
* `fontSize`
* `fontSizeAdjust`
* `fontStretch`
* `fontStyle`
* `fontVariant`
* `fontVariantAlternates`
* `fontVariantCaps`
* `fontVariantEastAsian`
* `fontVariantLigatures`
* `fontVariantNumeric`
* `fontWeight`
* `height`
* `letterSpacing`
* `lineHeight`
* `opacity`
* `outline`
* `padding`
* `paddingBottom`
* `paddingLeft`
* `paddingRight`
* `paddingTop`
* `textShadow`
* `transition`

#### Example

```javascript lines theme={null}
const numberField = cardSession.createCardFieldsComponent({
  type: "number",
  placeholder: "Card number",
  style: {
    input: {
      fontSize: "16px",
      lineHeight: "24px",
      color: "#333333",
    },
    ".invalid": {
      color: "#e53e3e",
    },
  },
});
```

### Full card fields example

```javascript lines expandable theme={null}
async function onPayPalWebSdkLoaded() {
  try {
    const sdk = await window.paypal.createInstance({
      clientId: "YOUR_CLIENT_ID",
      components: ["card-fields"],
      pageType: "checkout",
    });

    // Check eligibility before rendering
    const paymentMethods = await sdk.findEligibleMethods({ currencyCode: "USD" });
    if (!paymentMethods.isEligible("advanced_cards")) {
      return; // Fall back to other payment methods
    }

    // Create card fields session
    const cardSession = sdk.createCardFieldsOneTimePaymentSession();

    // Create and mount field components
    const numberField = cardSession.createCardFieldsComponent({
      type: "number",
      placeholder: "Card number",
      style: { input: { fontSize: "16px" } },
    });
    const expiryField = cardSession.createCardFieldsComponent({
      type: "expiry",
      placeholder: "MM/YY",
    });
    const cvvField = cardSession.createCardFieldsComponent({
      type: "cvv",
      placeholder: "CVV",
    });

    document.getElementById("card-number").appendChild(numberField);
    document.getElementById("card-expiry").appendChild(expiryField);
    document.getElementById("card-cvv").appendChild(cvvField);

    // Handle submission
    document.getElementById("pay-button").addEventListener("click", async () => {
      try {
        const orderId = await createOrder();

        const { data, state } = await cardSession.submit(orderId, {
          billingAddress: { postalCode: "10001" },
        });

        switch (state) {
          case "succeeded":
            // 3DS may or may not have run; check liabilityShift
            await captureOrder(data.orderId);
            window.location.href = "/order/success";
            break;
          case "canceled":
            // Buyer dismissed 3DS — allow retry without a new session
            showMessage("Authentication cancelled. Please try again.");
            break;
          case "failed":
            showMessage(data?.message || "Payment failed. Check your card details.");
            break;
        }
      } catch (err) {
        console.error("Card payment error:", err);
        showMessage("An unexpected error occurred. Please try again.");
      }
    });
  } catch (err) {
    console.error("SDK initialization failed:", err);
  }
}
```

## Guest payments

Guest payments render a PayPal-hosted card form without requiring the buyer to create or log in to a PayPal account. The card form appears as an overlay on your page, handling card input and validation inside a PayPal-hosted environment.

<Note>
  Guest payments require the `paypal-guest-payments` component. Use the `<paypal-basic-card-button>` web component to trigger the payment flow.
</Note>

### `sdkInstance.createPayPalGuestOneTimePaymentSession(options)`

Create a guest payment session for one-time card payments. This session manages the full card collection and payment authorization flow.

#### Parameters

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Required</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>onApprove</code></td>
      <td>yes</td>

      <td>
        <p><strong>function(data).</strong> Called when the payment is approved. Capture the order using <code>data.orderId</code>.</p>
      </td>
    </tr>

    <tr>
      <td><code>onComplete</code></td>
      <td>yes</td>

      <td>
        <p><strong>function(data).</strong> Called after <code>onApprove</code> when the payment flow finishes. Use this to navigate to a confirmation page or update UI state.</p>
      </td>
    </tr>

    <tr>
      <td><code>onCancel</code></td>
      <td>no</td>

      <td>
        <p><strong>function(data).</strong> Called when the buyer closes the card form without completing payment.</p>
      </td>
    </tr>

    <tr>
      <td><code>onError</code></td>
      <td>no</td>

      <td>
        <p><strong>function(error).</strong> Called when an unrecoverable error occurs. The error object contains <code>code</code> and <code>message</code>.</p>
      </td>
    </tr>

    <tr>
      <td><code>onWarn</code></td>
      <td>no</td>

      <td>
        <p><strong>function(data).</strong> Called when the buyer encounters a recoverable error after submitting the card form — for example, a card decline, name formatting error, or invalid address. The overlay stays open so the buyer can correct and retry.</p>
        <p>The data object contains:</p>

        <ul>
          <li><code>message</code> — Human-readable description</li>
          <li><code>name</code> — Warning type, for example, <code>PaymentFlowWarning</code></li>
          <li><code>code</code> — Warning code, for example, <code>WARN\_FLOW\_GUEST\_CHECKOUT\_SUBMIT\_ERROR</code></li>
        </ul>
      </td>
    </tr>

    <tr>
      <td><code>onShippingAddressChange</code></td>
      <td>no</td>

      <td>
        <p><strong>function(data).</strong> Called when the buyer changes their shipping address. See <a href="#onshippingaddresschangedata"><code>onShippingAddressChange</code></a> for the full data structure.</p>
      </td>
    </tr>

    <tr>
      <td><code>onShippingOptionsChange</code></td>
      <td>no</td>

      <td>
        <p><strong>function(data).</strong> Called when the buyer selects a different shipping option. See <a href="#onshippingoptionschangedata"><code>onShippingOptionsChange</code></a> for the full data structure.</p>
      </td>
    </tr>
  </tbody>
</table>

#### Returns

Returns a guest payment session object with a `start(options, orderPromise)` method.

#### `start(options, orderPromise)` parameters

| Parameter                  | Required | Description                                                                                                 |
| :------------------------- | :------- | :---------------------------------------------------------------------------------------------------------- |
| `options.presentationMode` | no       | **string.** How the card form overlay is displayed. Values: `auto` (default), `modal`, `popup`, `redirect`. |
| `options.targetElement`    | no       | **HTMLElement.** The element that triggered the session, used for overlay positioning.                      |
| `orderPromise`             | yes      | **Promise.** A promise that resolves to `{ orderId: string }`.                                              |

#### Web components

Use these web components to render the guest payment button:

```html lines theme={null}
<paypal-basic-card-container>
  <paypal-basic-card-button id="guest-card-button">
  </paypal-basic-card-button>
</paypal-basic-card-container>
```

#### Example

```javascript lines expandable theme={null}
const sdkInstance = await window.paypal.createInstance({
  clientId: "YOUR_CLIENT_ID",
  components: ["paypal-guest-payments"],
  pageType: "checkout",
});

const paymentMethods = await sdkInstance.findEligibleMethods({ currencyCode: "USD" });

if (paymentMethods.isEligible("card")) {

const guestPaymentSession = await sdkInstance.createPayPalGuestOneTimePaymentSession({
  onApprove: async (data) => {
    const orderData = await captureOrder({ orderId: data.orderId });
    console.log("Payment captured:", orderData);
  },
    window.location.href = "/order/success";
  },
  onCancel: () => {
    document.getElementById("guest-card-button").disabled = false;
  },
  onError: (error) => {
    console.error("Payment error:", error.code, error.message);
  },
  onWarn: (data) => {
    // Buyer encountered a recoverable error — overlay stays open for retry
    console.warn("Payment warning:", data.code, data.message);
  },
});

document.getElementById("guest-card-button").addEventListener("click", async () => {
  await guestPaymentSession.start(
    { presentationMode: "auto" },
    createOrder() // Returns Promise<{ orderId: string }>
  );
});

}
```


# React SDK v6 Reference
Source: https://docs.paypal.ai/reference/sdk/react



To integrate PayPal, Venmo, Pay Later, and other payment methods into React applications, use the PayPal React SDK v6 (`@paypal/react-paypal-js/sdk-v6`). This reference covers the provider component, hooks, payment session hooks, payment button components, card fields, server utilities, types, and common patterns.

<Tip>
  * For the vanilla JavaScript SDK v6 reference, see [JavaScript SDK v6 Reference](/reference/sdk/js/v6/reference).
  * For setup and initialization, see [Set up JavaScript SDK v6](/developer/how-to/sdk/js/v6/configuration).
  * Check out our [GitHub sample integration with client-side React.](https://github.com/paypal-examples/v6-web-sdk-sample-integration/tree/main/client/prebuiltPages/react).
</Tip>

## PayPalProvider

`PayPalProvider` is a context provider that initializes the PayPal SDK and provides payment functionality to child components.

### Props

<table>
  <thead>
    <tr>
      <th>Prop</th>
      <th>Type</th>
      <th>Required</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>clientId</code></td>
      <td><code>string | Promise\<string> | undefined</code></td>
      <td>yes</td>

      <td>
        <p>PayPal client ID for authenticating SDK requests. Use either <code>clientId</code> or <code>clientToken</code>, not both</p>
      </td>
    </tr>

    <tr>
      <td><code>clientToken</code></td>
      <td><code>string | Promise\<string> | undefined</code></td>
      <td>yes</td>

      <td>
        <p>PayPal client token for authenticating SDK requests. Use either <code>clientId</code> or <code>clientToken</code>, not both.</p>
      </td>
    </tr>

    <tr>
      <td><code>components</code></td>
      <td><code>string\[]</code></td>
      <td>yes</td>

      <td>
        <p>Array of components to load: <code>"paypal-payments"</code> (default), <code>"venmo-payments"</code>, <code>"paypal-subscriptions"</code>, <code>"paypal-guest-payments"</code>, and <code>"card-fields"</code></p>
      </td>
    </tr>

    <tr>
      <td><code>environment</code></td>
      <td><code>string</code></td>
      <td>yes</td>

      <td>
        <p>Target environment: <code>"sandbox"</code> or <code>"production"</code></p>
      </td>
    </tr>

    <tr>
      <td><code>pageType</code></td>
      <td><code>string</code></td>
      <td>no</td>

      <td>
        <p>Page context type, for example, <code>"checkout"</code></p>
      </td>
    </tr>

    <tr>
      <td><code>locale</code></td>
      <td><code>string</code></td>
      <td>no</td>

      <td>
        <p>Locale for the SDK, for example, <code>"en\_US"</code></p>
      </td>
    </tr>

    <tr>
      <td><code>clientMetadataId</code></td>
      <td><code>string</code></td>
      <td>no</td>

      <td>
        <p>Client metadata ID for tracking</p>
      </td>
    </tr>

    <tr>
      <td><code>partnerAttributionId</code></td>
      <td><code>string</code></td>
      <td>no</td>

      <td>
        <p>Partner attribution ID</p>
      </td>
    </tr>

    <tr>
      <td><code>shopperSessionId</code></td>
      <td><code>string</code></td>
      <td>no</td>

      <td>
        <p>Shopper session ID for personalization</p>
      </td>
    </tr>

    <tr>
      <td><code>testBuyerCountry</code></td>
      <td><code>string</code></td>
      <td>no</td>

      <td>
        <p>Test buyer country for sandbox testing</p>
      </td>
    </tr>

    <tr>
      <td><code>merchantId</code></td>
      <td><code>string | string\[]</code></td>
      <td>no</td>

      <td>
        <p>Merchant ID or array of merchant IDs</p>
      </td>
    </tr>

    <tr>
      <td><code>eligibleMethodsResponse</code></td>
      <td><code>object</code></td>
      <td>no</td>

      <td>
        <p>Pre-fetched eligible methods response from server-side <code>useFetchEligibleMethods</code></p>
      </td>
    </tr>

    <tr>
      <td><code>debug</code></td>
      <td><code>boolean</code></td>
      <td>no</td>

      <td>
        <p>Enable debug mode</p>
      </td>
    </tr>

    <tr>
      <td><code>dataNamespace</code></td>
      <td><code>string</code></td>
      <td>no</td>

      <td>
        <p>Custom namespace for the SDK data attribute</p>
      </td>
    </tr>
  </tbody>
</table>

<Warning>
  <code>PayPalProvider</code> requires a <code>clientId</code> or <code>clientToken</code> to authenticate your integration.
</Warning>

### Example

Replace `YOUR_PAYPAL_CLIENT_ID` with your app's PayPal client ID when initializing the provider.

<Tip>
  Place `PayPalProvider` at your app root so payment buttons render sooner.
</Tip>

<CodeGroup>
  ```tsx lines expandable Client ID example theme={null}
  import { PayPalProvider } from "@paypal/react-paypal-js/sdk-v6";

  function App() {
    return (
      <PayPalProvider
        clientId="YOUR_PAYPAL_CLIENT_ID"
        environment="sandbox"
        components={["paypal-payments", "venmo-payments", "paypal-subscriptions"]}
        pageType="checkout"
      >
        {/* Child components */}
      </PayPalProvider>
    );
  }
  ```

  ```tsx lines expandable Client token example theme={null}
  import { useMemo } from "react";
  import { PayPalProvider } from "@paypal/react-paypal-js/sdk-v6";

  function App() {
    // Memoize the promise to prevent re-fetching on every render
    const tokenPromise = useMemo(() => fetchClientToken(), []);

    return (
      <PayPalProvider
        clientToken={tokenPromise}
        environment="sandbox"
        components={["paypal-payments"]}
        pageType="checkout"
      >
        {/* Child components */}
      </PayPalProvider>
    );
  }
  ```
</CodeGroup>

## Hooks

Hooks provide access to SDK state and payment eligibility data inside your React components. Use them to check SDK internals or conditionally render UI based on which payment methods are available.

### `usePayPal()`

`usePayPal` provides access to the PayPal SDK state and payment eligibility information. Must be used within a `PayPalProvider`.

#### Returns

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>loadingStatus</code></td>
      <td><code>INSTANCE\_LOADING\_STATE</code></td>
      <td>Current SDK loading state: <code>INSTANCE\_LOADING\_STATE</code> <a href="#instance-loading-state">enum values</a></td>
    </tr>

    <tr>
      <td><code>eligiblePaymentMethods</code></td>
      <td><code>object | null</code></td>
      <td>Available payment methods for the current user</td>
    </tr>

    <tr>
      <td><code>sdkInstance</code></td>
      <td><code>object | null</code></td>
      <td>The underlying SDK instance</td>
    </tr>

    <tr>
      <td><code>error</code></td>
      <td><code>Error | null</code></td>
      <td>Any error that occurred during SDK initialization</td>
    </tr>

    <tr>
      <td><code>isHydrated</code></td>
      <td><code>boolean</code></td>
      <td>Whether the component has been hydrated on the client</td>
    </tr>
  </tbody>
</table>

#### Example

Use `usePayPal` to access the SDK state and payment eligibility in any component inside `PayPalProvider`.

```tsx lines expandable theme={null}
import { usePayPal, INSTANCE_LOADING_STATE } from "@paypal/react-paypal-js/sdk-v6";

function CheckoutForm() {
  const { loadingStatus, error } = usePayPal();

  if (loadingStatus === INSTANCE_LOADING_STATE.PENDING) {
    return <div>Loading...</div>;
  }

  if (loadingStatus === INSTANCE_LOADING_STATE.REJECTED) {
    return <div>Failed to load PayPal SDK: {error?.message}</div>;
  }

  return <PaymentButtons />;
}
```

### `useEligibleMethods(options)`

`useEligibleMethods` returns eligible payment methods from the PayPal SDK. It prevents duplicate API calls across components.

#### Parameters

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Required</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>payload.amount</code></td>
      <td>no</td>

      <td>
        <p><strong>string.</strong> Order amount, for example, <code>"95.00"</code></p>
      </td>
    </tr>

    <tr>
      <td><code>payload.currencyCode</code></td>
      <td>no</td>

      <td>
        <p><strong>string.</strong> Three-letter ISO 4217 currency code, for example, <code>"USD"</code></p>
      </td>
    </tr>

    <tr>
      <td><code>payload.paymentFlow</code></td>
      <td>no</td>

      <td>
        <p><strong>string.</strong> The payment flow type: <code>"ONE\_TIME\_PAYMENT"</code>, <code>"RECURRING\_PAYMENT"</code>, <code>"VAULT\_WITH\_PAYMENT"</code>, or <code>"VAULT\_WITHOUT\_PAYMENT"</code></p>
      </td>
    </tr>
  </tbody>
</table>

#### Returns

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>eligiblePaymentMethods</code></td>
      <td><code>object | null</code></td>
      <td>Available payment methods for the current user. <ul><li>To retrieve product-specific details, call <code>.getDetails("")</code>.</li><li>To check eligibility for a specific payment method, call <code>.isEligible("")</code>.</li></ul></td>
    </tr>

    <tr>
      <td><code>isLoading</code></td>
      <td><code>boolean</code></td>
      <td>Whether eligibility data is still being fetched</td>
    </tr>

    <tr>
      <td><code>error</code></td>
      <td><code>Error | null</code></td>
      <td>Any error that occurred during the fetch</td>
    </tr>
  </tbody>
</table>

#### Example

The following example fetches eligible payment methods for a one-time USD payment and conditionally renders a Pay Later button that is based on the result.

```tsx lines expandable theme={null}
import { useEligibleMethods, usePayLaterOneTimePaymentSession } from "@paypal/react-paypal-js/sdk-v6";

function PayLaterCheckout(props) {
  const { handleClick } = usePayLaterOneTimePaymentSession(props);
  const { eligiblePaymentMethods, isLoading, error } = useEligibleMethods({
    payload: { currencyCode: "USD" },
  });

  const payLaterDetails = eligiblePaymentMethods?.getDetails?.("paylater");
  const countryCode = payLaterDetails?.countryCode;
  const productCode = payLaterDetails?.productCode;

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <paypal-pay-later-button
      onClick={handleClick}
      countryCode={countryCode}
      productCode={productCode}
    />
  );
}
```

### `usePayPalMessages(options)`

`usePayPalMessages` creates a PayPal Messages session to fetch messaging content and create learn more modals.

#### Parameters

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Required</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>buyerCountry</code></td>
      <td>no</td>
      <td><p><strong>string.</strong> Buyer's country code</p></td>
    </tr>

    <tr>
      <td><code>currencyCode</code></td>
      <td>no</td>
      <td><p><strong>string.</strong> Currency code</p></td>
    </tr>

    <tr>
      <td><code>shopperSessionId</code></td>
      <td>no</td>
      <td><p><strong>string.</strong> Shopper session ID</p></td>
    </tr>
  </tbody>
</table>

#### Returns

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>error</code></td>
      <td><code>Error | null</code></td>
      <td>Any session error</td>
    </tr>

    <tr>
      <td><code>isReady</code></td>
      <td><code>boolean</code></td>
      <td>Whether the session is created</td>
    </tr>

    <tr>
      <td><code>handleFetchContent</code></td>
      <td><code>function</code></td>
      <td>Fetches message content</td>
    </tr>

    <tr>
      <td><code>handleCreateLearnMore</code></td>
      <td><code>function</code></td>
      <td>Creates a learn more modal</td>
    </tr>
  </tbody>
</table>

#### Example

The following example uses auto-bootstrap mode to display a PayPal message with a Learn more modal.

```tsx lines expandable theme={null}
import { usePayPalMessages } from "@paypal/react-paypal-js/sdk-v6";

function PayPalMessaging({ amount }: { amount: string }) {
  const { error } = usePayPalMessages({});

  if (error) return null;

  return (
    <paypal-message
      auto-bootstrap={true}
      amount={amount}
      currency-code="USD"
      buyer-country="US"
    />
  );
}
```

## Payment session hooks

Payment session hooks give you control over the payment flow for advanced integrations. Each button component has a session hook. All payment session hooks return a `BasePaymentSessionReturn` object.

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>error</code></td>
      <td><code>Error | null</code></td>
      <td>Any session error</td>
    </tr>

    <tr>
      <td><code>isPending</code></td>
      <td><code>boolean</code></td>
      <td>Whether the SDK instance is still loading</td>
    </tr>

    <tr>
      <td><code>handleClick</code></td>
      <td><code>() => Promise</code></td>
      <td>Starts the payment session</td>
    </tr>

    <tr>
      <td><code>handleCancel</code></td>
      <td><code>() => void</code></td>
      <td>Cancels the session</td>
    </tr>

    <tr>
      <td><code>handleDestroy</code></td>
      <td><code>() => void</code></td>
      <td>Cleans up the session</td>
    </tr>
  </tbody>
</table>

### `usePayPalOneTimePaymentSession`

The following example creates an order on your server and renders a custom PayPal button that starts the payment session when selected.

```tsx lines expandable theme={null}
import { usePayPalOneTimePaymentSession } from "@paypal/react-paypal-js/sdk-v6";

function CustomPayPalButton() {
  const { isPending, error, handleClick } = usePayPalOneTimePaymentSession({
    createOrder: async () => {
      const res = await fetch("/api/orders", { method: "POST" });
      const { id } = await res.json();
      return { orderId: id };
    },
    onApprove: async (data) => {
      console.log("Approved:", data.orderId);
    },
    presentationMode: "auto",
  });

  if (isPending) return null;
  if (error) return <div>Error: {error.message}</div>;

  return <paypal-button onClick={handleClick} type="pay" />;
}
```

### `useVenmoOneTimePaymentSession`

The following example creates an order and renders a custom Venmo button for one-time payments.

```tsx lines expandable theme={null}
import { useVenmoOneTimePaymentSession } from "@paypal/react-paypal-js/sdk-v6";

function CustomVenmoButton() {
  const { isPending, error, handleClick } = useVenmoOneTimePaymentSession({
    createOrder: async () => {
      const res = await fetch("/api/orders", { method: "POST" });
      const { id } = await res.json();
      return { orderId: id };
    },
    onApprove: async (data) => {
      console.log("Approved:", data.orderId);
    },
    presentationMode: "auto",
  });

  if (isPending) return null;
  if (error) return <div>Error: {error.message}</div>;

  return <venmo-button onClick={handleClick} type="pay" />;
}
```

### `usePayLaterOneTimePaymentSession`

The following example retrieves Pay Later eligibility details from `usePayPal` and passes `countryCode` and `productCode` to a custom Pay Later button.

```tsx lines expandable theme={null}
import { usePayLaterOneTimePaymentSession, usePayPal } from "@paypal/react-paypal-js/sdk-v6";

function CustomPayLaterButton() {
  const { eligiblePaymentMethods } = usePayPal();
  const { isPending, error, handleClick } = usePayLaterOneTimePaymentSession({
    createOrder: async () => {
      const res = await fetch("/api/orders", { method: "POST" });
      const { id } = await res.json();
      return { orderId: id };
    },
    onApprove: async (data) => {
      console.log("Approved:", data.orderId);
    },
    presentationMode: "auto",
  });

  const payLaterDetails = eligiblePaymentMethods?.getDetails("paylater");

  if (isPending) return null;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <paypal-pay-later-button
      onClick={handleClick}
      countryCode={payLaterDetails?.countryCode}
      productCode={payLaterDetails?.productCode}
    />
  );
}
```

### `usePayPalCreditOneTimePaymentSession`

The following example retrieves PayPal Credit eligibility details and renders a custom credit button with the buyer's `countryCode`.

```tsx lines expandable theme={null}
import { usePayPalCreditOneTimePaymentSession, usePayPal } from "@paypal/react-paypal-js/sdk-v6";

function CustomCreditButton() {
  const { eligiblePaymentMethods } = usePayPal();
  const { isPending, error, handleClick } = usePayPalCreditOneTimePaymentSession({
    createOrder: async () => {
      const res = await fetch("/api/orders", { method: "POST" });
      const { id } = await res.json();
      return { orderId: id };
    },
    onApprove: async (data) => {
      console.log("Approved:", data.orderId);
    },
    presentationMode: "auto",
  });

  const creditDetails = eligiblePaymentMethods?.getDetails?.("credit");

  if (isPending) return null;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <paypal-credit-button
      onClick={handleClick}
      countryCode={creditDetails?.countryCode}
    />
  );
}
```

### `usePayPalGuestPaymentSession`

`usePayPalGuestPaymentSession` returns an additional `buttonRef` to pass to the `<paypal-basic-card-button>` element. The following example renders a guest checkout button inside a `<paypal-basic-card-container>` wrapper.

```tsx lines expandable theme={null}
import { usePayPalGuestPaymentSession } from "@paypal/react-paypal-js/sdk-v6";

function CustomGuestButton() {
  const { buttonRef, isPending, error, handleClick } = usePayPalGuestPaymentSession({
    createOrder: async () => {
      const res = await fetch("/api/orders", { method: "POST" });
      const { id } = await res.json();
      return { orderId: id };
    },
    onApprove: async (data) => {
      console.log("Approved:", data.orderId);
    },
  });

  if (isPending) return null;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <paypal-basic-card-container>
      <paypal-basic-card-button ref={buttonRef} onClick={handleClick} />
    </paypal-basic-card-container>
  );
}
```

### `usePayPalSavePaymentSession`

The following example creates a vault setup token on your server and renders a button that saves the payment method when selected.

```tsx lines expandable theme={null}
import { usePayPalSavePaymentSession } from "@paypal/react-paypal-js/sdk-v6";

function CustomSaveButton() {
  const { isPending, error, handleClick } = usePayPalSavePaymentSession({
    createVaultToken: async () => {
      const res = await fetch("/api/vault-setup-token", { method: "POST" });
      const { id } = await res.json();
      return { vaultSetupToken: id };
    },
    onApprove: async (data) => {
      console.log("Saved:", data.vaultSetupToken);
    },
    presentationMode: "auto",
  });

  if (isPending) return null;
  if (error) return <div>Error: {error.message}</div>;

  return <paypal-button onClick={handleClick} type="pay" />;
}
```

### `usePayPalCreditSavePaymentSession`

The following example saves a PayPal Credit payment method to the vault and passes the buyer's `countryCode` from eligibility data to the credit button.

```tsx lines expandable theme={null}
import { usePayPalCreditSavePaymentSession, usePayPal } from "@paypal/react-paypal-js/sdk-v6";

function CustomCreditSaveButton() {
  const { eligiblePaymentMethods } = usePayPal();
  const { isPending, error, handleClick } = usePayPalCreditSavePaymentSession({
    createVaultToken: async () => {
      const res = await fetch("/api/vault-setup-token", { method: "POST" });
      const { id } = await res.json();
      return { vaultSetupToken: id };
    },
    onApprove: async (data) => {
      console.log("Saved:", data.vaultSetupToken);
    },
    presentationMode: "auto",
  });

  const creditDetails = eligiblePaymentMethods?.getDetails?.("credit");

  if (isPending) return null;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <paypal-credit-button
      onClick={handleClick}
      countryCode={creditDetails?.countryCode}
    />
  );
}
```

### `usePayPalSubscriptionPaymentSession`

The following example creates a subscription on your server and renders a custom subscribe button that starts the subscription flow when selected.

```tsx lines expandable theme={null}
import { usePayPalSubscriptionPaymentSession } from "@paypal/react-paypal-js/sdk-v6";

function CustomSubscriptionButton() {
  const { isPending, error, handleClick } = usePayPalSubscriptionPaymentSession({
    createSubscription: async () => {
      const res = await fetch("/api/subscriptions", { method: "POST" });
      const { id } = await res.json();
      return { subscriptionId: id };
    },
    onApprove: async (data) => {
      console.log("Subscription approved:", data.payerId);
    },
    presentationMode: "auto",
  });

  if (isPending) return null;
  if (error) return <div>Error: {error.message}</div>;

  return <paypal-button onClick={handleClick} type="subscribe" />;
}
```

### `useApplePayOneTimePaymentSession`

The following example configures an Apple Pay session with a payment request and renders a native Apple Pay button.

```tsx lines expandable theme={null}
import { useApplePayOneTimePaymentSession } from "@paypal/react-paypal-js/sdk-v6";

function CustomApplePayButton({ applePayConfig }) {
  const { isPending, error, handleClick } = useApplePayOneTimePaymentSession({
    applePayConfig,
    paymentRequest: {
      countryCode: "US",
      currencyCode: "USD",
      total: { label: "Demo Store", amount: "100.00", type: "final" },
    },
    applePaySessionVersion: 4,
    createOrder: async () => {
      const res = await fetch("/api/orders", { method: "POST" });
      const { id } = await res.json();
      return { orderId: id };
    },
    onApprove: (data) => console.log("Approved:", data),
    onError: (err) => console.error(err),
  });

  if (isPending) return null;
  if (error) return <div>Error: {error.message}</div>;

  return <apple-pay-button onClick={handleClick} buttonstyle="black" type="pay" />;
}
```

## Payment components

The following components render PayPal payment buttons in your React app. Each component wraps a specific payment flow and accepts callback props to handle the payment lifecycle.

### PayPalOneTimePaymentButton

`PayPalOneTimePaymentButton` renders a button for one-time PayPal payments. It uses `usePayPalOneTimePaymentSession` internally.

#### Props

<table>
  <thead>
    <tr>
      <th>Prop</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>createOrder</code></td>
      <td><code>() => Promise\<\{ orderId: string }></code></td>
      <td>Function that calls your server to create a PayPal order and returns the resulting <code>orderId</code>. The component calls this function when the buyer clicks the button. Use either <code>createOrder</code> or <code>orderId</code>, not both.</td>
    </tr>

    <tr>
      <td><code>orderId</code></td>
      <td><code>string</code></td>
      <td>Order ID for an order you already created on your server. Use this when your app creates the order before rendering the button. Use either <code>createOrder</code> or <code>orderId</code>, not both.</td>
    </tr>

    <tr>
      <td><code>onApprove</code></td>
      <td><code>(data: OnApproveDataOneTimePayments) => Promise\<void></code></td>
      <td>Callback when payment is approved</td>
    </tr>

    <tr>
      <td><code>onCancel</code></td>
      <td><code>(data: OnCancelDataOneTimePayments) => void</code></td>
      <td>Callback when user cancels</td>
    </tr>

    <tr>
      <td><code>onError</code></td>
      <td><code>(data: OnErrorData) => void</code></td>
      <td>Callback on payment error</td>
    </tr>

    <tr>
      <td><code>onComplete</code></td>
      <td><code>(data: OnCompleteData) => void</code></td>
      <td>Callback when payment session completes</td>
    </tr>

    <tr>
      <td><code>presentationMode</code></td>
      <td><code>string</code></td>

      <td>
        <p><strong>string.</strong> Controls how the payment interface is displayed to the buyer.</p>
        <p>Available modes:</p>

        <ul>
          <li><code>auto</code> — Recommended. SDK automatically selects the best experience. Tries popup first and falls back to modal if popups are blocked.</li>
          <li><code>popup</code> — Opens PayPal in a popup window. May be blocked by popup blockers.</li>
          <li><code>modal</code> — Creates an iframe overlay on the current page. Recommended only for WebView scenarios. Do not use in desktop web scenarios as this integration has limitations on cookies, which can affect user authentication.</li>
          <li><code>redirect</code> — Full page redirect to PayPal. Recommended for mobile devices. Requires a return/cancel URL.</li>
          <li><code>payment-handler</code> — Experimental. Uses the browser's Payment Handler API. Provides a native payment experience. Modern browsers only.</li>
        </ul>

        <p>Default: <code>auto</code></p>
        <p>The SDK will automatically fall back to alternative modes if the requested mode is unavailable.</p>
      </td>
    </tr>

    <tr>
      <td><code>fullPageOverlay</code></td>
      <td><code>\{ enabled: boolean }</code></td>
      <td>Whether to show a full-page overlay</td>
    </tr>

    <tr>
      <td><code>onShippingAddressChange</code></td>
      <td><code>(data: OnShippingAddressChangeData) => Promise\<void></code></td>
      <td>Callback when shipping address changes</td>
    </tr>

    <tr>
      <td><code>onShippingOptionsChange</code></td>
      <td><code>(data: OnShippingOptionsChangeData) => Promise\<void></code></td>
      <td>Callback when shipping options change</td>
    </tr>

    <tr>
      <td><code>type</code></td>
      <td><code>string</code></td>
      <td>Button type: <code>"pay"</code> (default), <code>"checkout"</code>, <code>"buynow"</code>, or <code>"donate"</code></td>
    </tr>

    <tr>
      <td><code>disabled</code></td>
      <td><code>boolean</code></td>
      <td>Whether the button is disabled</td>
    </tr>

    <tr>
      <td><code>savePayment</code></td>
      <td><code>boolean</code></td>
      <td>Whether to save the payment method during checkout</td>
    </tr>
  </tbody>
</table>

#### Example

The following example renders a PayPal button that creates an order on your server and handles approval when the buyer completes payment.

```tsx lines expandable theme={null}
import { PayPalOneTimePaymentButton, type OnApproveDataOneTimePayments } from "@paypal/react-paypal-js/sdk-v6";

function Checkout() {
  const handleCreateOrder = async () => {
    const response = await fetch("/api/orders", { method: "POST" });
    const { id } = await response.json();
    return { orderId: id };
  };

  return (
    <PayPalOneTimePaymentButton
      createOrder={handleCreateOrder}
      onApprove={async (data: OnApproveDataOneTimePayments) => {
        console.log("Order approved:", data.orderId);
      }}
      presentationMode="auto"
    />
  );
}
```

### VenmoOneTimePaymentButton

`VenmoOneTimePaymentButton` renders a button for one-time Venmo payments (US only). It uses `useVenmoOneTimePaymentSession` internally.

#### Props

`VenmoOneTimePaymentButton` accepts the same props as `PayPalOneTimePaymentButton`.

<table>
  <thead>
    <tr>
      <th>Prop</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>createOrder</code></td>
      <td><code>() => Promise\<\{ orderId: string }></code></td>
      <td>Function that calls your server to create a PayPal order and returns the resulting <code>orderId</code>. The component calls this function when the buyer clicks the button. Use either <code>createOrder</code> or <code>orderId</code>, not both.</td>
    </tr>

    <tr>
      <td><code>orderId</code></td>
      <td><code>string</code></td>
      <td>Order ID for an order you already created on your server. Use this when your app creates the order before rendering the button. Use either <code>createOrder</code> or <code>orderId</code>, not both.</td>
    </tr>

    <tr>
      <td><code>onApprove</code></td>
      <td><code>(data: OnApproveDataOneTimePayments) => Promise\<void></code></td>
      <td>Callback when payment is approved</td>
    </tr>

    <tr>
      <td><code>onCancel</code></td>
      <td><code>(data: OnCancelDataOneTimePayments) => void</code></td>
      <td>Callback when user cancels</td>
    </tr>

    <tr>
      <td><code>onError</code></td>
      <td><code>(data: OnErrorData) => void</code></td>
      <td>Callback on payment error</td>
    </tr>

    <tr>
      <td><code>onComplete</code></td>
      <td><code>(data: OnCompleteData) => void</code></td>
      <td>Callback when payment session completes</td>
    </tr>

    <tr>
      <td><code>presentationMode</code></td>
      <td><code>string</code></td>

      <td>
        <p><strong>string.</strong> Controls how the payment interface is displayed to the buyer.</p>
        <p>Available modes:</p>

        <ul>
          <li><code>auto</code> — Recommended. SDK automatically selects the best experience. Tries popup first and falls back to modal if popups are blocked.</li>
          <li><code>popup</code> — Opens PayPal in a popup window. May be blocked by popup blockers.</li>
          <li><code>modal</code> — Creates an iframe overlay on the current page. Recommended only for WebView scenarios. Do not use in desktop web scenarios as this integration has limitations on cookies, which can affect user authentication.</li>
          <li><code>redirect</code> — Full page redirect to PayPal. Recommended for mobile devices. Requires a return/cancel URL.</li>
          <li><code>payment-handler</code> — Experimental. Uses the browser's Payment Handler API. Provides a native payment experience. Modern browsers only.</li>
        </ul>

        <p>Default: <code>auto</code></p>
        <p>The SDK will automatically fall back to alternative modes if the requested mode is unavailable.</p>
      </td>
    </tr>

    <tr>
      <td><code>fullPageOverlay</code></td>
      <td><code>\{ enabled: boolean }</code></td>
      <td>Whether to show a full-page overlay</td>
    </tr>

    <tr>
      <td><code>onShippingAddressChange</code></td>
      <td><code>(data: OnShippingAddressChangeData) => Promise\<void></code></td>
      <td>Callback when shipping address changes</td>
    </tr>

    <tr>
      <td><code>onShippingOptionsChange</code></td>
      <td><code>(data: OnShippingOptionsChangeData) => Promise\<void></code></td>
      <td>Callback when shipping options change</td>
    </tr>

    <tr>
      <td><code>type</code></td>
      <td><code>string</code></td>
      <td>Button type: <code>"pay"</code> (default), <code>"checkout"</code>, <code>"buynow"</code>, or <code>"donate"</code></td>
    </tr>

    <tr>
      <td><code>disabled</code></td>
      <td><code>boolean</code></td>
      <td>Whether the button is disabled</td>
    </tr>

    <tr>
      <td><code>savePayment</code></td>
      <td><code>boolean</code></td>
      <td>Whether to save the payment method during checkout</td>
    </tr>
  </tbody>
</table>

#### Example

The following example renders a Venmo payment button with order creation and approval callbacks.

```tsx lines expandable theme={null}
import { VenmoOneTimePaymentButton } from "@paypal/react-paypal-js/sdk-v6";

<VenmoOneTimePaymentButton
  createOrder={handleCreateOrder}
  onApprove={handleApprove}
  presentationMode="auto"
/>
```

### PayLaterOneTimePaymentButton

`PayLaterOneTimePaymentButton` renders a button for the Pay Later payment option (Pay in 4, financing). It requires `useEligibleMethods` to fetch eligibility data, which provides the `countryCode` and `productCode` needed for the button.

#### Props

<table>
  <thead>
    <tr>
      <th>Prop</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>createOrder</code></td>
      <td><code>() => Promise\<\{ orderId: string }></code></td>
      <td>Function that calls your server to create a PayPal order and returns the resulting <code>orderId</code>. The component calls this function when the buyer clicks the button. Use either <code>createOrder</code> or <code>orderId</code>, not both.</td>
    </tr>

    <tr>
      <td><code>orderId</code></td>
      <td><code>string</code></td>
      <td>Order ID for an order you already created on your server. Use this when your app creates the order before rendering the button. Use either <code>createOrder</code> or <code>orderId</code>, not both.</td>
    </tr>

    <tr>
      <td><code>onApprove</code></td>
      <td><code>(data: OnApproveDataOneTimePayments) => Promise\<void></code></td>
      <td>Callback when payment is approved</td>
    </tr>

    <tr>
      <td><code>onCancel</code></td>
      <td><code>(data: OnCancelDataOneTimePayments) => void</code></td>
      <td>Callback when user cancels</td>
    </tr>

    <tr>
      <td><code>onError</code></td>
      <td><code>(data: OnErrorData) => void</code></td>
      <td>Callback on payment error</td>
    </tr>

    <tr>
      <td><code>onComplete</code></td>
      <td><code>(data: OnCompleteData) => void</code></td>
      <td>Callback when payment session completes</td>
    </tr>

    <tr>
      <td><code>presentationMode</code></td>
      <td><code>string</code></td>

      <td>
        <p><strong>string.</strong> Controls how the payment interface is displayed to the buyer.</p>
        <p>Available modes:</p>

        <ul>
          <li><code>auto</code> — Recommended. SDK automatically selects the best experience. Tries popup first and falls back to modal if popups are blocked.</li>
          <li><code>popup</code> — Opens PayPal in a popup window. May be blocked by popup blockers.</li>
          <li><code>modal</code> — Creates an iframe overlay on the current page. Recommended only for WebView scenarios. Do not use in desktop web scenarios as this integration has limitations on cookies, which can affect user authentication.</li>
          <li><code>redirect</code> — Full page redirect to PayPal. Recommended for mobile devices. Requires a return/cancel URL.</li>
          <li><code>payment-handler</code> — Experimental. Uses the browser's Payment Handler API. Provides a native payment experience. Modern browsers only.</li>
        </ul>

        <p>Default: <code>auto</code></p>
        <p>The SDK will automatically fall back to alternative modes if the requested mode is unavailable.</p>
      </td>
    </tr>

    <tr>
      <td><code>disabled</code></td>
      <td><code>boolean</code></td>
      <td>Whether the button is disabled</td>
    </tr>
  </tbody>
</table>

#### Example

The following example renders a Pay Later button that lets buyers choose financing options like Pay in 4.

```tsx lines expandable theme={null}
import { PayLaterOneTimePaymentButton, useEligibleMethods } from "@paypal/react-paypal-js/sdk-v6";

function PayLaterCheckout() {
  const { error, isLoading } = useEligibleMethods();

  return (
    !error &&
    !isLoading && (
      <PayLaterOneTimePaymentButton
        createOrder={handleCreateOrder}
        onApprove={handleApprove}
        presentationMode="auto"
      />
    )
  );
}
```

### PayPalCreditOneTimePaymentButton

`PayPalCreditOneTimePaymentButton` renders a button for PayPal Credit one-time payments. It requires `useEligibleMethods` to fetch eligibility data, which provides the `countryCode` needed for the button.

#### Props

<table>
  <thead>
    <tr>
      <th>Prop</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>createOrder</code></td>
      <td><code>() => Promise\<\{ orderId: string }></code></td>
      <td>Function that calls your server to create a PayPal order and returns the resulting <code>orderId</code>. The component calls this function when the buyer clicks the button. Use either <code>createOrder</code> or <code>orderId</code>, not both.</td>
    </tr>

    <tr>
      <td><code>orderId</code></td>
      <td><code>string</code></td>
      <td>Order ID for an order you already created on your server. Use this when your app creates the order before rendering the button. Use either <code>createOrder</code> or <code>orderId</code>, not both.</td>
    </tr>

    <tr>
      <td><code>onApprove</code></td>
      <td><code>(data: OnApproveDataOneTimePayments) => Promise\<void></code></td>
      <td>Callback when payment is approved</td>
    </tr>

    <tr>
      <td><code>onCancel</code></td>
      <td><code>(data: OnCancelDataOneTimePayments) => void</code></td>
      <td>Callback when user cancels</td>
    </tr>

    <tr>
      <td><code>onError</code></td>
      <td><code>(data: OnErrorData) => void</code></td>
      <td>Callback on payment error</td>
    </tr>

    <tr>
      <td><code>onComplete</code></td>
      <td><code>(data: OnCompleteData) => void</code></td>
      <td>Callback when payment session completes</td>
    </tr>

    <tr>
      <td><code>presentationMode</code></td>
      <td><code>string</code></td>

      <td>
        <p><strong>string.</strong> Controls how the payment interface is displayed to the buyer.</p>
        <p>Available modes:</p>

        <ul>
          <li><code>auto</code> — Recommended. SDK automatically selects the best experience. Tries popup first and falls back to modal if popups are blocked.</li>
          <li><code>popup</code> — Opens PayPal in a popup window. May be blocked by popup blockers.</li>
          <li><code>modal</code> — Creates an iframe overlay on the current page. Recommended only for WebView scenarios. Do not use in desktop web scenarios as this integration has limitations on cookies, which can affect user authentication.</li>
          <li><code>redirect</code> — Full page redirect to PayPal. Recommended for mobile devices. Requires a return/cancel URL.</li>
          <li><code>payment-handler</code> — Experimental. Uses the browser's Payment Handler API. Provides a native payment experience. Modern browsers only.</li>
        </ul>

        <p>Default: <code>auto</code></p>
        <p>The SDK will automatically fall back to alternative modes if the requested mode is unavailable.</p>
      </td>
    </tr>

    <tr>
      <td><code>disabled</code></td>
      <td><code>boolean</code></td>
      <td>Whether the button is disabled</td>
    </tr>
  </tbody>
</table>

#### Example

The following example checks eligibility before rendering a PayPal Credit button for one-time payments.

```tsx lines expandable theme={null}
import { PayPalCreditOneTimePaymentButton, useEligibleMethods } from "@paypal/react-paypal-js/sdk-v6";

function CreditCheckout() {
  const { error, isLoading } = useEligibleMethods();

  return (
    !error &&
    !isLoading && (
      <PayPalCreditOneTimePaymentButton
        createOrder={handleCreateOrder}
        onApprove={handleApprove}
        presentationMode="auto"
      />
    )
  );
}
```

### PayPalGuestPaymentButton

`PayPalGuestPaymentButton` renders a button for guest checkout that does not require a PayPal account. It automatically wraps the button with `<paypal-basic-card-container>`.

<Note>
  This component does not accept `presentationMode`. It renders a `<paypal-basic-card-button>` inside a `<paypal-basic-card-container>` automatically.
</Note>

#### Props

<table>
  <thead>
    <tr>
      <th>Prop</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>createOrder</code></td>
      <td><code>() => Promise\<\{ orderId: string }></code></td>
      <td>Function that calls your server to create a PayPal order and returns the resulting <code>orderId</code>. The component calls this function when the buyer clicks the button. Use either <code>createOrder</code> or <code>orderId</code>, not both</td>
    </tr>

    <tr>
      <td><code>orderId</code></td>
      <td><code>string</code></td>
      <td>Order ID for an order you already created on your server. Use this when your app creates the order before rendering the button. Use either <code>createOrder</code> or <code>orderId</code>, not both</td>
    </tr>

    <tr>
      <td><code>onApprove</code></td>
      <td><code>(data: OnApproveDataOneTimePayments) => Promise\<void></code></td>
      <td>Callback when payment is approved</td>
    </tr>

    <tr>
      <td><code>onCancel</code></td>
      <td><code>(data: OnCancelDataOneTimePayments) => void</code></td>
      <td>Callback when user cancels</td>
    </tr>

    <tr>
      <td><code>onError</code></td>
      <td><code>(data: OnErrorData) => void</code></td>
      <td>Callback on payment error</td>
    </tr>

    <tr>
      <td><code>onComplete</code></td>
      <td><code>(data: OnCompleteData) => void</code></td>
      <td>Callback when payment session completes</td>
    </tr>

    <tr>
      <td><code>fullPageOverlay</code></td>
      <td><code>\{ enabled: boolean }</code></td>
      <td>Whether to show a full-page overlay</td>
    </tr>

    <tr>
      <td><code>onShippingAddressChange</code></td>
      <td><code>(data: OnShippingAddressChangeData) => Promise\<void></code></td>
      <td>Callback when shipping address changes</td>
    </tr>

    <tr>
      <td><code>onShippingOptionsChange</code></td>
      <td><code>(data: OnShippingOptionsChangeData) => Promise\<void></code></td>
      <td>Callback when shipping options change</td>
    </tr>

    <tr>
      <td><code>disabled</code></td>
      <td><code>boolean</code></td>
      <td>Whether the button is disabled</td>
    </tr>
  </tbody>
</table>

#### Example

The following example renders a guest checkout button that allows buyers to pay without a PayPal account.

```tsx lines expandable theme={null}
import { PayPalGuestPaymentButton } from "@paypal/react-paypal-js/sdk-v6";

<PayPalGuestPaymentButton
  createOrder={handleCreateOrder}
  onApprove={handleApprove}
/>
```

### PayPalSavePaymentButton

`PayPalSavePaymentButton` renders a button that saves payment methods to a vault.

#### Props

<table>
  <thead>
    <tr>
      <th>Prop</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>createVaultToken</code></td>
      <td><code>() => Promise\<\{ vaultSetupToken: string }></code></td>
      <td>Function that creates a vault setup token and returns an object with its ID. Use either <code>createVaultToken</code> or <code>vaultSetupToken</code>, not both.</td>
    </tr>

    <tr>
      <td><code>vaultSetupToken</code></td>
      <td><code>string</code></td>
      <td>Pre-created vault setup token. Use either <code>createVaultToken</code> or <code>vaultSetupToken</code>, not both.</td>
    </tr>

    <tr>
      <td><code>onApprove</code></td>
      <td><code>(data: OnApproveDataSavePayments) => Promise\<void></code></td>
      <td>Callback when payment method is saved</td>
    </tr>

    <tr>
      <td><code>onCancel</code></td>
      <td><code>(data: OnCancelDataSavePayments) => void</code></td>
      <td>Callback when user cancels</td>
    </tr>

    <tr>
      <td><code>onError</code></td>
      <td><code>(data: OnErrorData) => void</code></td>
      <td>Callback on error</td>
    </tr>

    <tr>
      <td><code>onComplete</code></td>
      <td><code>(data: OnCompleteData) => void</code></td>
      <td>Callback when session completes</td>
    </tr>

    <tr>
      <td><code>presentationMode</code></td>
      <td><code>string</code></td>

      <td>
        <p>Controls how the payment interface is displayed to the buyer.</p>
        <p>Available modes:</p>

        <ul>
          <li><code>auto</code> (default) — Recommended. SDK automatically selects the best experience. Tries popup first and falls back to modal if popups are blocked.</li>
          <li><code>popup</code> — Opens PayPal in a popup window. May be blocked by popup blockers.</li>
          <li><code>modal</code> — Creates an iframe overlay on the current page. Recommended only for WebView scenarios. Do not use in desktop web scenarios as this integration has limitations on cookies, which can affect user authentication.</li>
          <li><code>redirect</code> — Full page redirect to PayPal. Recommended for mobile devices. Requires a return/cancel URL.</li>
          <li><code>payment-handler</code> — Experimental. Uses the browser's Payment Handler API. Provides a native payment experience. Modern browsers only.</li>
        </ul>

        <p>The SDK will automatically fall back to alternative modes if the requested mode is unavailable.</p>
      </td>
    </tr>

    <tr>
      <td><code>type</code></td>
      <td><code>string</code></td>
      <td>Button type. Defaults to <code>"pay"</code></td>
    </tr>

    <tr>
      <td><code>disabled</code></td>
      <td><code>boolean</code></td>
      <td>Whether the button is disabled</td>
    </tr>
  </tbody>
</table>

#### Example

The following example creates a vault setup token on your server and renders a button that saves the buyer's payment method.

```tsx lines expandable theme={null}
import { PayPalSavePaymentButton, type OnApproveDataSavePayments } from "@paypal/react-paypal-js/sdk-v6";

function SavePayment() {
  const handleCreateVaultToken = async () => {
    const response = await fetch("/api/vault-setup-token", { method: "POST" });
    const { id } = await response.json();
    return { vaultSetupToken: id };
  };

  return (
    <PayPalSavePaymentButton
      createVaultToken={handleCreateVaultToken}
      onApprove={(data: OnApproveDataSavePayments) => {
        console.log("Payment saved with token:", data.vaultSetupToken);
      }}
      presentationMode="auto"
    />
  );
}
```

### PayPalCreditSavePaymentButton

`PayPalCreditSavePaymentButton` renders a button that saves PayPal Credit payment methods. It requires `useEligibleMethods` to fetch eligibility data, which provides the `countryCode` needed for the button.

#### Props

<table>
  <thead>
    <tr>
      <th>Prop</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>createVaultToken</code></td>
      <td><code>() => Promise\<\{ vaultSetupToken: string }></code></td>
      <td>Function that creates a vault setup token and returns an object with its ID. Use either <code>createVaultToken</code> or <code>vaultSetupToken</code>, not both.</td>
    </tr>

    <tr>
      <td><code>vaultSetupToken</code></td>
      <td><code>string</code></td>
      <td>Pre-created vault setup token. Use either <code>createVaultToken</code> or <code>vaultSetupToken</code>, not both.</td>
    </tr>

    <tr>
      <td><code>onApprove</code></td>
      <td><code>(data: OnApproveDataSavePayments) => Promise\<void></code></td>
      <td>Callback when payment method is saved</td>
    </tr>

    <tr>
      <td><code>onCancel</code></td>
      <td><code>(data: OnCancelDataSavePayments) => void</code></td>
      <td>Callback when user cancels</td>
    </tr>

    <tr>
      <td><code>onError</code></td>
      <td><code>(data: OnErrorData) => void</code></td>
      <td>Callback on error</td>
    </tr>

    <tr>
      <td><code>onComplete</code></td>
      <td><code>(data: OnCompleteData) => void</code></td>
      <td>Callback when session completes</td>
    </tr>

    <tr>
      <td><code>presentationMode</code></td>
      <td><code>string</code></td>

      <td>
        <p>Controls how the payment interface is displayed to the buyer.</p>
        <p>Available modes:</p>

        <ul>
          <li><code>auto</code> (default) — Recommended. SDK automatically selects the best experience. Tries popup first and falls back to modal if popups are blocked.</li>
          <li><code>popup</code> — Opens PayPal in a popup window. May be blocked by popup blockers.</li>
          <li><code>modal</code> — Creates an iframe overlay on the current page. Recommended only for WebView scenarios. Do not use in desktop web scenarios as this integration has limitations on cookies, which can affect user authentication.</li>
          <li><code>redirect</code> — Full page redirect to PayPal. Recommended for mobile devices. Requires a return/cancel URL.</li>
          <li><code>payment-handler</code> — Experimental. Uses the browser's Payment Handler API. Provides a native payment experience. Modern browsers only.</li>
        </ul>

        <p>The SDK will automatically fall back to alternative modes if the requested mode is unavailable.</p>
      </td>
    </tr>

    <tr>
      <td><code>type</code></td>
      <td><code>string</code></td>
      <td>Button type. Defaults to <code>"pay"</code></td>
    </tr>

    <tr>
      <td><code>disabled</code></td>
      <td><code>boolean</code></td>
      <td>Whether the button is disabled</td>
    </tr>
  </tbody>
</table>

#### Example

The following example checks eligibility before rendering a button that saves a PayPal Credit payment method to the vault.

```tsx lines expandable theme={null}
import { PayPalCreditSavePaymentButton, useEligibleMethods } from "@paypal/react-paypal-js/sdk-v6";

function CreditSavePayment() {
  const { error, isLoading } = useEligibleMethods();

  return (
    !error &&
    !isLoading && (
      <PayPalCreditSavePaymentButton
        createVaultToken={handleCreateVaultToken}
        onApprove={handleApprove}
        presentationMode="auto"
      />
    )
  );
}
```

### PayPalSubscriptionButton

`PayPalSubscriptionButton` renders a button that creates subscriptions.

<Note>
  Subscriptions only support `"auto"`, `"popup"`, `"modal"`, or `"payment-handler"` presentation modes.
</Note>

#### Props

<table>
  <thead>
    <tr>
      <th>Prop</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>createSubscription</code></td>
      <td><code>() => Promise\<\{ subscriptionId: string }></code></td>
      <td>Function that creates a subscription and returns an object with <code>subscriptionId</code></td>
    </tr>

    <tr>
      <td><code>onApprove</code></td>
      <td><code>(data: OnApproveDataSubscriptions) => Promise\<void></code></td>
      <td>Callback when subscription is approved. Receives <code>subscriptionId</code> and <code>payerId</code></td>
    </tr>

    <tr>
      <td><code>onCancel</code></td>
      <td><code>(data: OnCancelDataOneTimePayments) => void</code></td>
      <td>Callback when user cancels</td>
    </tr>

    <tr>
      <td><code>onError</code></td>
      <td><code>(data: OnErrorData) => void</code></td>
      <td>Callback on error</td>
    </tr>

    <tr>
      <td><code>onComplete</code></td>
      <td><code>(data: OnCompleteData) => void</code></td>
      <td>Callback when session completes</td>
    </tr>

    <tr>
      <td><code>presentationMode</code></td>
      <td><code>string</code></td>

      <td>
        <p>Controls how the payment interface is displayed to the buyer.</p>
        <p>Available modes:</p>

        <ul>
          <li><code>auto</code> (default) — Recommended. SDK automatically selects the best experience. Tries popup first and falls back to modal if popups are blocked.</li>
          <li><code>popup</code> — Opens PayPal in a popup window. May be blocked by popup blockers.</li>
          <li><code>modal</code> — Creates an iframe overlay on the current page. Recommended only for WebView scenarios. Do not use in desktop web scenarios as this integration has limitations on cookies, which can affect user authentication.</li>
          <li><code>redirect</code> — Full page redirect to PayPal. Recommended for mobile devices. Requires a return/cancel URL.</li>
          <li><code>payment-handler</code> — Experimental. Uses the browser's Payment Handler API. Provides a native payment experience. Modern browsers only.</li>
        </ul>

        <p>The SDK will automatically fall back to alternative modes if the requested mode is unavailable.</p>
      </td>
    </tr>

    <tr>
      <td><code>type</code></td>
      <td><code>string</code></td>
      <td>Button type. Defaults to <code>"subscribe"</code></td>
    </tr>

    <tr>
      <td><code>disabled</code></td>
      <td><code>boolean</code></td>
      <td>Whether the button is disabled</td>
    </tr>
  </tbody>
</table>

#### Example

The following example creates a subscription on your server and renders a button that starts the subscription approval flow.

```tsx lines expandable theme={null}
import { PayPalSubscriptionButton, type OnApproveDataSubscriptions } from "@paypal/react-paypal-js/sdk-v6";

function Subscription() {
  const handleCreateSubscription = async () => {
    const response = await fetch("/api/subscriptions", { method: "POST" });
    const { id } = await response.json();
    return { subscriptionId: id };
  };

  return (
    <PayPalSubscriptionButton
      createSubscription={handleCreateSubscription}
      onApprove={(data: OnApproveDataSubscriptions) => {
        console.log("Subscription ID:", data.subscriptionId);
      }}
      presentationMode="auto"
    />
  );
}
```

### ApplePayOneTimePaymentButton

`ApplePayOneTimePaymentButton` renders a native `<apple-pay-button>` element for Apple Pay payments with Safari-compatible styling.

#### Props

<table>
  <thead>
    <tr>
      <th>Prop</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>applePayConfig</code></td>
      <td><code>ApplePayConfig</code></td>
      <td>Apple Pay configuration from <code>findEligibleMethods</code></td>
    </tr>

    <tr>
      <td><code>paymentRequest</code></td>
      <td><code>ApplePayPaymentRequest</code></td>
      <td>Payment request with country, currency, and total</td>
    </tr>

    <tr>
      <td><code>applePaySessionVersion</code></td>
      <td><code>number</code></td>
      <td>Apple Pay JS API version (4 or later)</td>
    </tr>

    <tr>
      <td><code>createOrder</code></td>
      <td><code>() => Promise\<\{ orderId: string }></code></td>
      <td>Function that creates an order</td>
    </tr>

    <tr>
      <td><code>onApprove</code></td>
      <td><code>(data: ConfirmOrderResponse) => void</code></td>
      <td>Callback when payment is approved</td>
    </tr>

    <tr>
      <td><code>onCancel</code></td>
      <td><code>() => void</code></td>
      <td>Callback when payment is cancelled</td>
    </tr>

    <tr>
      <td><code>onError</code></td>
      <td><code>(error: Error) => void</code></td>
      <td>Callback on error</td>
    </tr>

    <tr>
      <td><code>displayName</code></td>
      <td><code>string</code></td>
      <td>Merchant display name</td>
    </tr>

    <tr>
      <td><code>domainName</code></td>
      <td><code>string</code></td>
      <td>Merchant domain name</td>
    </tr>

    <tr>
      <td><code>buttonstyle</code></td>
      <td><code>string</code></td>
      <td>Button style, for example, <code>"black"</code> (default) or <code>"white"</code></td>
    </tr>

    <tr>
      <td><code>type</code></td>
      <td><code>string</code></td>
      <td>Button type, for example, <code>"pay"</code> (default)</td>
    </tr>

    <tr>
      <td><code>locale</code></td>
      <td><code>string</code></td>
      <td>Locale, such as <code>"en"</code> (default)</td>
    </tr>

    <tr>
      <td><code>disabled</code></td>
      <td><code>boolean</code></td>
      <td>Whether the button is disabled</td>
    </tr>
  </tbody>
</table>

#### Example

The following example renders an Apple Pay button configured with a payment request and order creation callback.

```tsx lines expandable theme={null}
import { ApplePayOneTimePaymentButton } from "@paypal/react-paypal-js/sdk-v6";

<ApplePayOneTimePaymentButton
  applePayConfig={applePayConfig}
  paymentRequest={{
    countryCode: "US",
    currencyCode: "USD",
    total: { label: "Demo Store", amount: "100.00", type: "final" },
  }}
  applePaySessionVersion={4}
  createOrder={async () => {
    const res = await fetch("/api/orders", { method: "POST" });
    const data = await res.json();
    return { orderId: data.id };
  }}
  onApprove={(data) => console.log("Approved:", data)}
  onError={(err) => console.error(err)}
/>
```

## Card fields components

Card fields let you render individual, PCI-compliant input fields for card number, expiration, and CVV within your checkout form.

### PayPalCardFieldsProvider

`PayPalCardFieldsProvider` creates a Card Fields session and provides it to child field components. Only the `children` prop is required. All other props are optional and can be used to configure the session and listen to field events.

#### Props

<table>
  <thead>
    <tr>
      <th>Prop</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>children </code>(required)</td>
      <td><code>ReactNode</code></td>
      <td>Child components</td>
    </tr>

    <tr>
      <td><code>amount</code> </td>
      <td><code>\{ value?: string, currencyCode?: string }</code></td>
      <td>Order amount, which you can update dynamically</td>
    </tr>

    <tr>
      <td><code>isCobrandedEligible</code></td>
      <td><code>boolean</code></td>
      <td>Whether co-branded card eligibility is enabled</td>
    </tr>

    <tr>
      <td><code>blur</code></td>
      <td><code>(event) => void</code></td>
      <td>Callback when a card field loses focus</td>
    </tr>

    <tr>
      <td><code>validitychange</code></td>
      <td><code>(event) => void</code></td>
      <td>Callback when field validity changes</td>
    </tr>

    <tr>
      <td><code>cardtypechange</code></td>
      <td><code>(event) => void</code></td>
      <td>Callback when card type changes or is detected</td>
    </tr>

    <tr>
      <td><code>focus</code></td>
      <td><code>(event) => void</code></td>
      <td>Callback when a card field gains focus</td>
    </tr>

    <tr>
      <td><code>change</code></td>
      <td><code>(event) => void</code></td>
      <td>Callback when card field value changes</td>
    </tr>

    <tr>
      <td><code>empty</code></td>
      <td><code>(event) => void</code></td>
      <td>Callback when a card field is empty</td>
    </tr>

    <tr>
      <td><code>inputsubmit</code></td>
      <td><code>(event) => void</code></td>
      <td>Callback when a card field is submitted</td>
    </tr>

    <tr>
      <td><code>notempty</code></td>
      <td><code>(event) => void</code></td>
      <td>Callback when a card field is not empty</td>
    </tr>
  </tbody>
</table>

#### Example

The following example renders card number, expiry, and CVV fields inside a provider that listens for validity and card type changes.

```tsx lines expandable theme={null}
import {
  PayPalCardFieldsProvider,
  PayPalCardNumberField,
  PayPalCardExpiryField,
  PayPalCardCvvField,
} from "@paypal/react-paypal-js/sdk-v6";

function CardFieldsCheckout() {
  return (
    <PayPalCardFieldsProvider
      amount={{ value: "10.00", currencyCode: "USD" }}
      validitychange={(event) => console.log("Validity change event:", event)}
      cardtypechange={(event) => console.log("Card type change event:", event)}
    >
      <PayPalCardNumberField placeholder="Card number" />
      <PayPalCardExpiryField placeholder="MM/YY" />
      <PayPalCardCvvField placeholder="CVV" />
      <SubmitButton />
    </PayPalCardFieldsProvider>
  );
}
```

### PayPalCardNumberField

`PayPalCardNumberField` renders a card number input field. Use within a `PayPalCardFieldsProvider`. All props are optional.

#### Props

<table>
  <thead>
    <tr>
      <th>Prop</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>placeholder</code></td>
      <td><code>string</code></td>
      <td>Input placeholder text</td>
    </tr>

    <tr>
      <td><code>label</code></td>
      <td><code>string</code></td>
      <td>Input label</td>
    </tr>

    <tr>
      <td><code>style</code></td>
      <td><code>object</code></td>
      <td>Custom styles</td>
    </tr>

    <tr>
      <td><code>ariaLabel</code></td>
      <td><code>string</code></td>
      <td>Accessibility label</td>
    </tr>

    <tr>
      <td><code>ariaDescription</code></td>
      <td><code>string</code></td>
      <td>Accessibility description</td>
    </tr>

    <tr>
      <td><code>ariaInvalidErrorMessage</code></td>
      <td><code>string</code></td>
      <td>Error message for screen readers</td>
    </tr>

    <tr>
      <td><code>containerStyles</code></td>
      <td><code>CSSProperties</code></td>
      <td>Styles for the container div</td>
    </tr>

    <tr>
      <td><code>containerClassName</code></td>
      <td><code>string</code></td>
      <td>Class name for the container div</td>
    </tr>
  </tbody>
</table>

### PayPalCardExpiryField

`PayPalCardExpiryField` renders a card expiry input field. Use within a `PayPalCardFieldsProvider`. All props are optional.

#### Props

<table>
  <thead>
    <tr>
      <th>Prop</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>placeholder</code></td>
      <td><code>string</code></td>
      <td>Input placeholder text</td>
    </tr>

    <tr>
      <td><code>label</code></td>
      <td><code>string</code></td>
      <td>Input label</td>
    </tr>

    <tr>
      <td><code>style</code></td>
      <td><code>object</code></td>
      <td>Custom styles</td>
    </tr>

    <tr>
      <td><code>ariaLabel</code></td>
      <td><code>string</code></td>
      <td>Accessibility label</td>
    </tr>

    <tr>
      <td><code>ariaDescription</code></td>
      <td><code>string</code></td>
      <td>Accessibility description</td>
    </tr>

    <tr>
      <td><code>ariaInvalidErrorMessage</code></td>
      <td><code>string</code></td>
      <td>Error message for screen readers</td>
    </tr>

    <tr>
      <td><code>containerStyles</code></td>
      <td><code>CSSProperties</code></td>
      <td>Styles for the container div</td>
    </tr>

    <tr>
      <td><code>containerClassName</code></td>
      <td><code>string</code></td>
      <td>Class name for the container div</td>
    </tr>
  </tbody>
</table>

### PayPalCardCvvField

`PayPalCardCvvField` renders a CVV input field. Use within a `PayPalCardFieldsProvider`. All props are optional.

#### Props

<table>
  <thead>
    <tr>
      <th>Prop</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>placeholder</code></td>
      <td><code>string</code></td>
      <td>Input placeholder text</td>
    </tr>

    <tr>
      <td><code>label</code></td>
      <td><code>string</code></td>
      <td>Input label</td>
    </tr>

    <tr>
      <td><code>style</code></td>
      <td><code>object</code></td>
      <td>Custom styles</td>
    </tr>

    <tr>
      <td><code>ariaLabel</code></td>
      <td><code>string</code></td>
      <td>Accessibility label</td>
    </tr>

    <tr>
      <td><code>ariaDescription</code></td>
      <td><code>string</code></td>
      <td>Accessibility description</td>
    </tr>

    <tr>
      <td><code>ariaInvalidErrorMessage</code></td>
      <td><code>string</code></td>
      <td>Error message for screen readers</td>
    </tr>

    <tr>
      <td><code>containerStyles</code></td>
      <td><code>CSSProperties</code></td>
      <td>Styles for the container div</td>
    </tr>

    <tr>
      <td><code>containerClassName</code></td>
      <td><code>string</code></td>
      <td>Class name for the container div</td>
    </tr>
  </tbody>
</table>

### `usePayPalCardFields()`

`usePayPalCardFields` returns the Card Fields state from the `PayPalCardFieldsProvider` context. Use within a `PayPalCardFieldsProvider`.

### `usePayPalCardFieldsOneTimePaymentSession()`

`usePayPalCardFieldsOneTimePaymentSession` submits card field data for one-time payments.

#### Returns

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>submit</code></td>
      <td><code>(orderId: string | Promise\<string>, options?) => Promise\<void></code></td>
      <td>Submit the card fields for payment</td>
    </tr>

    <tr>
      <td><code>submitResponse</code></td>
      <td><code>object | null</code></td>
      <td>The response from the submit operation</td>
    </tr>

    <tr>
      <td><code>error</code></td>
      <td><code>Error | null</code></td>
      <td>Any error that occurred</td>
    </tr>
  </tbody>
</table>

#### Example

The following example renders styled card fields, submits the card data for a one-time payment, and handles both success and failure responses.

```tsx lines expandable One-time payment theme={null}
import {
  PayPalCardCvvField,
  PayPalCardExpiryField,
  PayPalCardNumberField,
  usePayPalCardFields,
  usePayPalCardFieldsOneTimePaymentSession,
} from "@paypal/react-paypal-js/sdk-v6";
import { useEffect } from "react";
import { captureOrder } from "../../../utils";

const PayPalCardFieldsOneTimePayment = () => {
  const { error: cardFieldsError } = usePayPalCardFields();
  const {
    error: submitError,
    submit,
    submitResponse,
  } = usePayPalCardFieldsOneTimePaymentSession();

  useEffect(() => {
    if (!submitResponse) {
      return;
    }

    const { orderId, message } = submitResponse.data;

    switch (submitResponse.state) {
      case "succeeded":
        console.log(`One time payment succeeded: orderId: ${orderId}`);
        captureOrder({ orderId }).then((captureResult) => {
          console.log("Payment capture result:", captureResult);
        });
        break;
      case "failed":
        console.error(
          `One time payment failed: orderId: ${orderId}, message:  ${message}`,
        );
        break;
    }
  }, [submitResponse]);

  useEffect(() => {
    if (cardFieldsError) {
      console.error("Error loading PayPal Card Fields", cardFieldsError);
    }
    if (submitError) {
      console.error("Error submitting PayPal Card Fields payment", submitError);
    }
  }, [cardFieldsError, submitError]);

  const handleSubmit = async () => {
    const { orderId } = await handleCreateOrder();
    await submit(orderId);
  };

  return (
    <div>
      <div
        style={{
          display: "flex",
          flexDirection: "column",
          gap: "1rem",
        }}
      >
        <PayPalCardNumberField
          containerStyles={{
            height: "3rem",
          }}
          placeholder="Enter card number"
        />
        <PayPalCardExpiryField
          containerStyles={{
            height: "3rem",
          }}
          placeholder="MM/YY"
        />
        <PayPalCardCvvField
          containerStyles={{
            height: "3rem",
          }}
          placeholder="Enter CVV"
        />
      </div>
      {!cardFieldsError && (
        <button className="card-fields-pay-button" onClick={handleSubmit}>
          Pay
        </button>
      )}
    </div>
  );
};

export default PayPalCardFieldsOneTimePayment;
```

### `usePayPalCardFieldsSavePaymentSession()`

`usePayPalCardFieldsSavePaymentSession` submits card field data to save a payment method.

#### Returns

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>submit</code></td>
      <td><code>(vaultSetupToken: string | Promise\<string>, options?) => Promise\<void></code></td>
      <td>Submit the card fields for vaulting</td>
    </tr>

    <tr>
      <td><code>submitResponse</code></td>
      <td><code>object | null</code></td>
      <td>The response from the submit operation</td>
    </tr>

    <tr>
      <td><code>error</code></td>
      <td><code>Error | null</code></td>
      <td>Any error that occurred</td>
    </tr>
  </tbody>
</table>

#### Example

The following example renders card fields and submits the card data to save it as a vaulted payment method.

```tsx lines expandable Save payment method theme={null}
import {
  PayPalCardCvvField,
  PayPalCardExpiryField,
  PayPalCardNumberField,
  usePayPalCardFields,
  usePayPalCardFieldsSavePaymentSession,
} from "@paypal/react-paypal-js/sdk-v6";
import { useEffect } from "react";
import { createCardVaultToken } from "../../../utils";

const PayPalCardFieldsSavePayment = () => {
  const { error: cardFieldsError } = usePayPalCardFields();
  const {
    error: submitError,
    submit,
    submitResponse,
  } = usePayPalCardFieldsSavePaymentSession();

  useEffect(() => {
    if (!submitResponse) {
      return;
    }

    const { vaultSetupToken, message } = submitResponse.data;

    switch (submitResponse.state) {
      case "succeeded":
        console.log(
          `Save payment method succeeded: vaultSetupToken: ${vaultSetupToken}`,
        );
        break;
      case "failed":
        console.error(
          `Save payment method failed: vaultSetupToken: ${vaultSetupToken}, message: ${message}`,
        );
        break;
    }
  }, [submitResponse]);

  useEffect(() => {
    if (cardFieldsError) {
      console.error("Error loading PayPal Card Fields", cardFieldsError);
    }
    if (submitError) {
      console.error("Error submitting PayPal Card Fields payment", submitError);
    }
  }, [cardFieldsError, submitError]);

  const handleSubmit = async () => {
    const { vaultSetupToken } = await createCardVaultToken();
    await submit(vaultSetupToken);
  };

  return (
    <div>
      <div
        style={{
          display: "flex",
          flexDirection: "column",
          gap: "1rem",
        }}
      >
        <PayPalCardNumberField
          containerStyles={{
            height: "3rem",
          }}
          placeholder="Enter card number"
        />
        <PayPalCardExpiryField
          containerStyles={{
            height: "3rem",
          }}
          placeholder="MM/YY"
        />
        <PayPalCardCvvField
          containerStyles={{
            height: "3rem",
          }}
          placeholder="Enter CVV"
        />
      </div>
      {!cardFieldsError && (
        <button className="card-fields-pay-button" onClick={handleSubmit}>
          Save Payment Method
        </button>
      )}
    </div>
  );
};

export default PayPalCardFieldsSavePayment;
```

## Server utilities

### `useFetchEligibleMethods(options)`

`useFetchEligibleMethods` pre-fetches eligible payment methods on the server. Import from `@paypal/react-paypal-js/sdk-v6/server`.

#### Parameters

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Required</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>options.headers</code></td>
      <td>no</td>
      <td><p><strong>HeadersInit.</strong> HTTP headers including the <code>Authorization</code> bearer token</p></td>
    </tr>

    <tr>
      <td><code>options.environment</code></td>
      <td>yes</td>
      <td><p><strong>string.</strong> Target environment (<code>"sandbox"</code> or <code>"production"</code>)</p></td>
    </tr>

    <tr>
      <td><code>options.payload</code></td>
      <td>no</td>
      <td><p><strong>object.</strong> Optional request payload with customer and purchase details</p></td>
    </tr>

    <tr>
      <td><code>options.signal</code></td>
      <td>no</td>
      <td><p><strong>AbortSignal.</strong> Optional abort signal</p></td>
    </tr>
  </tbody>
</table>

#### Example

The following example pre-fetches eligible payment methods on the server and passes the result to `PayPalProvider`.

<CodeGroup>
  ```tsx Implementation lines expandable theme={null}
  import { useFetchEligibleMethods } from "@paypal/react-paypal-js/sdk-v6/server";

  // In a server component or loader
  const eligibleMethodsResponse = await useFetchEligibleMethods({
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${clientToken}`,
    },
    environment: "sandbox",
    payload: {
      purchase_units: [{ amount: { currency_code: "USD", value: "100.00" } }],
    },
  });

  // Pass to provider
  <PayPalProvider
    eligibleMethodsResponse={eligibleMethodsResponse}
    clientToken={token}
    pageType="checkout"
  >
    <Checkout />
  </PayPalProvider>
  ```

  ```tsx Types lines expandable theme={null}
  type FindEligiblePaymentMethodsRequestPayload = {
    customer?: {
      channel?: {
        browser_type?: string;
        client_os?: string;
        device_type?: string;
      };
      country_code?: string;
      id?: string;
      email?: string;
      phone?: PhoneNumber;
    };
    purchase_units?: ReadonlyArray<{
      amount: {
        currency_code: string;
        value?: string;
      };
      payee?: {
        client_id?: string;
        display_data?: {
          business_email?: string;
          business_phone?: PhoneNumber & {
            extension_number: string;
          };
          brand_name?: string;
        };
        email_address?: string;
        merchant_id?: string;
      };
    }>;
    preferences?: {
      // runs advanced customer eligibility checks when set to true
      include_account_details?: boolean;
      include_vault_tokens?: boolean;
      payment_flow?: PaymentFlow;
      payment_source_constraint?: {
        constraint_type: string;
        payment_sources: Uppercase<EligiblePaymentMethods>[];
      };
    };
    shopper_session_id?: string;
  };
  ```
</CodeGroup>

## Types

The following types define the data structures passed to and from SDK callbacks.

### OnApproveDataOneTimePayments

Data passed to `onApprove` for one-time payments

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>orderId</code></td>
      <td><code>string</code></td>
      <td>The PayPal order ID</td>
    </tr>

    <tr>
      <td><code>payerId</code></td>
      <td><code>string</code> (optional)</td>
      <td>The PayPal payer ID</td>
    </tr>

    <tr>
      <td><code>billingToken</code></td>
      <td><code>string</code> (optional)</td>
      <td>The billing token</td>
    </tr>
  </tbody>
</table>

### OnApproveDataSubscriptions

Data passed to `onApprove` for subscription payments

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>subscriptionId</code></td>
      <td><code>string</code></td>
      <td>The PayPal subscription ID</td>
    </tr>

    <tr>
      <td><code>payerId</code></td>
      <td><code>string</code> (optional)</td>
      <td>The PayPal payer ID</td>
    </tr>
  </tbody>
</table>

### OnApproveDataSavePayments

Data passed to `onApprove` for save payment operations

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>vaultSetupToken</code></td>
      <td><code>string</code></td>
      <td>Token representing the saved payment method</td>
    </tr>

    <tr>
      <td><code>payerId</code></td>
      <td><code>string</code> (optional)</td>
      <td>The PayPal payer ID</td>
    </tr>
  </tbody>
</table>

### OnCancelDataOneTimePayments

Data passed to `onCancel` for one-time payments

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>orderId</code></td>
      <td><code>string</code> (optional)</td>
      <td>The PayPal order ID</td>
    </tr>
  </tbody>
</table>

### OnCancelDataSavePayments

Data passed to `onCancel` for save payment operations

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>vaultSetupToken</code></td>
      <td><code>string</code> (optional)</td>
      <td>The vault setup token</td>
    </tr>
  </tbody>
</table>

### OnErrorData

Data passed to `onError` when an error occurs. Extends `Error`.

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>code</code></td>
      <td><code>string</code></td>
      <td>Error code</td>
    </tr>

    <tr>
      <td><code>name</code></td>
      <td><code>string</code></td>
      <td>Error name</td>
    </tr>

    <tr>
      <td><code>message</code></td>
      <td><code>string</code></td>
      <td>Error message</td>
    </tr>

    <tr>
      <td><code>isRecoverable</code></td>
      <td><code>boolean</code></td>
      <td>Whether the error is recoverable</td>
    </tr>
  </tbody>
</table>

### OnCompleteData

Data passed to `onComplete` when payment session completes

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>paymentSessionState</code></td>
      <td><code>string</code></td>
      <td>Session result: <code>"approved"</code>, <code>"canceled"</code>, or <code>"error"</code></td>
    </tr>
  </tbody>
</table>

### BasePaymentSessionReturn

Return type for all payment session hooks

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>error</code></td>
      <td><code>Error | null</code></td>
      <td>Any session error</td>
    </tr>

    <tr>
      <td><code>isPending</code></td>
      <td><code>boolean</code></td>
      <td>Whether the SDK instance is still loading</td>
    </tr>

    <tr>
      <td><code>handleClick</code></td>
      <td><code>() => Promise\<\{ redirectURL?: string } | void></code></td>
      <td>Starts the payment session</td>
    </tr>

    <tr>
      <td><code>handleCancel</code></td>
      <td><code>() => void</code></td>
      <td>Cancels the session</td>
    </tr>

    <tr>
      <td><code>handleDestroy</code></td>
      <td><code>() => void</code></td>
      <td>Cleans up the session</td>
    </tr>
  </tbody>
</table>

### EventPayload

Data passed to Card Fields event callbacks such as `blur`, `focus`, `change`, and `validitychange`

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>data</code></td>
      <td><code>EventState</code></td>
      <td>The state of the card fields when the event was triggered</td>
    </tr>

    <tr>
      <td><code>sender</code></td>
      <td><code>CardFieldTypes</code></td>
      <td>The card field that triggered the event: <code>"number"</code>, <code>"expiry"</code>, or <code>"cvv"</code></td>
    </tr>
  </tbody>
</table>

### EventState

The state of all card fields at the time an event is triggered

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>cards</code></td>
      <td><code>Card\[]</code></td>
      <td>Detected card types based on the current card number input</td>
    </tr>

    <tr>
      <td><code>emittedBy</code></td>
      <td><code>CardFieldTypes</code></td>
      <td>The card field that emitted the event: <code>"number"</code>, <code>"expiry"</code>, or <code>"cvv"</code></td>
    </tr>

    <tr>
      <td><code>number</code></td>
      <td><code>FieldState</code></td>
      <td>State of the card number field</td>
    </tr>

    <tr>
      <td><code>cvv</code></td>
      <td><code>FieldState</code></td>
      <td>State of the CVV field</td>
    </tr>

    <tr>
      <td><code>expiry</code></td>
      <td><code>FieldState</code></td>
      <td>State of the expiry field</td>
    </tr>
  </tbody>
</table>

### FieldState

The state of an individual card field

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>isFocused</code></td>
      <td><code>boolean</code></td>
      <td>Whether the field currently has focus</td>
    </tr>

    <tr>
      <td><code>isValid</code></td>
      <td><code>boolean</code></td>
      <td>Whether the field value is valid</td>
    </tr>

    <tr>
      <td><code>isEmpty</code></td>
      <td><code>boolean</code></td>
      <td>Whether the field is empty</td>
    </tr>

    <tr>
      <td><code>isPotentiallyValid</code></td>
      <td><code>boolean</code></td>
      <td>Whether the field value could become valid with additional input</td>
    </tr>
  </tbody>
</table>

### Card

Represents a detected card type based on the current card number input

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>niceType</code></td>
      <td><code>string</code></td>
      <td>Human-readable card name, for example, <code>"Visa"</code></td>
    </tr>

    <tr>
      <td><code>type</code></td>
      <td><code>string</code></td>
      <td>Machine-readable card type, for example, <code>"visa"</code></td>
    </tr>

    <tr>
      <td><code>code.name</code></td>
      <td><code>string</code></td>
      <td>Security code label for the card type, for example, <code>"CVV"</code> or <code>"CID"</code></td>
    </tr>

    <tr>
      <td><code>code.size</code></td>
      <td><code>number</code></td>
      <td>Expected length of the security code, for example, <code>3</code> or <code>4</code></td>
    </tr>
  </tbody>
</table>

## INSTANCE\_LOADING\_STATE

Enum for SDK loading states. Use with `usePayPal()` to check SDK readiness.

<table>
  <thead>
    <tr>
      <th>Value</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>INSTANCE\_LOADING\_STATE.PENDING</code></td>
      <td>SDK is loading</td>
    </tr>

    <tr>
      <td><code>INSTANCE\_LOADING\_STATE.RESOLVED</code></td>
      <td>SDK loaded successfully</td>
    </tr>

    <tr>
      <td><code>INSTANCE\_LOADING\_STATE.REJECTED</code></td>
      <td>SDK failed to load</td>
    </tr>
  </tbody>
</table>

#### Example

The following example checks the SDK loading state and renders different UI for each state.

```tsx lines expandable theme={null}
import { INSTANCE_LOADING_STATE, usePayPal } from "@paypal/react-paypal-js/sdk-v6";

function Component() {
  const { loadingStatus } = usePayPal();

  if (loadingStatus === INSTANCE_LOADING_STATE.PENDING) {
    return <div>Loading...</div>;
  }

  if (loadingStatus === INSTANCE_LOADING_STATE.REJECTED) {
    return <div>Failed to load PayPal SDK</div>;
  }

  return <div>Ready to process payments</div>;
}
```

## Common patterns

The following examples cover common integration patterns for error handling, eligibility checks, and conditional rendering.

### Error handling

The following example shows how to capture error details, log them, and conditionally prompt a retry if the error is recoverable.

```tsx lines expandable theme={null}
import { PayPalOneTimePaymentButton, type OnErrorData } from "@paypal/react-paypal-js/sdk-v6";

function Payment() {
  const handleError = (error: OnErrorData) => {
    console.error("Payment failed:", error.message);
    if (error.isRecoverable) {
      // Prompt user to retry
    }
  };

  return (
    <PayPalOneTimePaymentButton
      createOrder={createOrder}
      onApprove={handleApprove}
      onError={handleError}
      presentationMode="auto"
    />
  );
}
```

### Checking payment eligibility

The following example checks payment method availability for the current user and conditionally renders payment buttons based on eligibility.

```tsx lines expandable theme={null}
import { useEligibleMethods } from "@paypal/react-paypal-js/sdk-v6";

function CheckoutFlow() {
  const { eligiblePaymentMethods, isLoading } = useEligibleMethods();

  if (isLoading) return <div>Loading...</div>;

  return (
    <>
      <PayPalOneTimePaymentButton {...props} />
      {eligiblePaymentMethods?.isEligible("venmo") && (
        <VenmoOneTimePaymentButton {...props} />
      )}
      {eligiblePaymentMethods?.isEligible("paylater") && (
        <PayLaterOneTimePaymentButton {...props} />
      )}
    </>
  );
}
```

### Conditional rendering based on loading state

The following example renders loading indicators while the PayPal SDK initializes and displays payment components only when ready.

```tsx lines expandable theme={null}
function Checkout() {
  const { loadingStatus } = usePayPal();

  const isLoading = loadingStatus === INSTANCE_LOADING_STATE.PENDING;

  return isLoading ? (
    <div>Initializing payment methods...</div>
  ) : (
    <PaymentButtons />
  );
}
```

### Using orderId instead of createOrder

All one-time payment buttons support passing a pre-created `orderId` directly instead of a `createOrder` callback.

```tsx lines expandable theme={null}
<PayPalOneTimePaymentButton
  orderId="ORDER-123"
  onApprove={handleApprove}
  presentationMode="auto"
/>
```

### Using vaultSetupToken instead of createVaultToken

Save payment buttons support passing a pre-created `vaultSetupToken` directly.

```tsx lines expandable theme={null}
<PayPalSavePaymentButton
  vaultSetupToken="VAULT-TOKEN-123"
  onApprove={handleApprove}
  presentationMode="auto"
/>
```


# Disputes v1
Source: https://docs.paypal.ai/reference/webhook-events/disputes-v1



The following are the webhook events related to the [Disputes v1 API](/reference/api/rest/disputes/show-dispute-details).

| Event                       | Trigger                    | Related method                                                                       |
| --------------------------- | -------------------------- | ------------------------------------------------------------------------------------ |
| `CUSTOMER.DISPUTE.CREATED`  | A dispute is created.      | N/A                                                                                  |
| `CUSTOMER.DISPUTE.RESOLVED` | A dispute is resolved.     | [Settle dispute](/reference/api/rest/disputes-actions/settle-dispute)                |
| `CUSTOMER.DISPUTE.UPDATED`  | A dispute is updated.      | [Partially update dispute](/reference/api/rest/disputes/partially-update-dispute)    |
| `RISK.DISPUTE.CREATED`      | A risk dispute is created. | The `CUSTOMER.DISPUTE.CREATED` event type supersedes and deprecates this event type. |


# Invoicing v2
Source: https://docs.paypal.ai/reference/webhook-events/invoicing-v2



The following are the webhook events related to the [Invoicing v2 API](/reference/api/rest/invoices/show-invoice-details).

| Event                         | Trigger                                                                | Related method                                                                     |
| ----------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `INVOICING.INVOICE.CANCELLED` | A merchant or customer cancels an invoice.                             | [Cancel invoice](/reference/api/rest/invoices/cancel-sent-invoice)                 |
| `INVOICING.INVOICE.CREATED`   | An invoice is created.                                                 | [Create draft invoice](/reference/api/rest/invoices/create-draft-invoice)          |
| `INVOICING.INVOICE.PAID`      | An invoice is paid, partially paid, or payment is made and is pending. | [Mark invoice as paid](/reference/api/rest/invoices/record-payment-for-invoice)    |
| `INVOICING.INVOICE.REFUNDED`  | An invoice is refunded or partially refunded.                          | [Mark invoice as refunded](/reference/api/rest/invoices/record-refund-for-invoice) |
| `INVOICING.INVOICE.SCHEDULED` | An invoice is scheduled.                                               | [Schedule invoice](/reference/api/rest/invoices/show-invoice-details)              |
| `INVOICING.INVOICE.UPDATED`   | An invoice is updated.                                                 | [Update invoice](/reference/api/rest/invoices/fully-update-invoice)                |


# Orders V2
Source: https://docs.paypal.ai/reference/webhook-events/orders-v2



The following are the webhook events related to the [Orders v2 API](/reference/api/rest/orders/create-order).

| Event                                | Trigger                                                                                                                                                                                                                                                       | Related method                                              |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `CHECKOUT.ORDER.COMPLETED`           | A checkout order is processed. **Note:** For use by marketplaces and platforms only.                                                                                                                                                                          | [Orders API](/reference/api/rest/orders/show-order-details) |
| `CHECKOUT.ORDER.APPROVED`            | A buyer approved a checkout order                                                                                                                                                                                                                             | [Orders API](/reference/api/rest/orders/show-order-details) |
| `CHECKOUT.PAYMENT-APPROVAL.REVERSED` | A problem occurred after the buyer approved the order but before you captured the payment. Refer to [Handle uncaptured payments](https://developer.paypal.com/docs/checkout/apm/reference/handle-uncaptured-payments/) for what to do when this event occurs. | [Orders API](/reference/api/rest/orders/show-order-details) |


# Payment Method Tokens v3
Source: https://docs.paypal.ai/reference/webhook-events/payment-method-tokens-v3



The following are the webhook events related to the [Payment Method Tokens v3 API](/reference/api/rest/payment-tokens/retrieve-a-payment-token).

| Event                                    | Trigger                                                                                                                                             | Payment methods  |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| `VAULT.PAYMENT-TOKEN.CREATED`            | A payment token is created to save a payment method.                                                                                                | Cards and PayPal |
| `VAULT.PAYMENT-TOKEN.DELETED`            | A payment token is deleted. The payer's payment method is no longer saved to the PayPal vault.                                                      | Cards and PayPal |
| `VAULT.PAYMENT-TOKEN.DELETION-INITIATED` | A request to delete a payment token has been submitted to the [Payment Method Tokens API](/reference/api/rest/payment-tokens/delete-payment-token). | PayPal           |


# Payments v2
Source: https://docs.paypal.ai/reference/webhook-events/payments-v2



The following are the webhook events related to the [Payments v2 API](/reference/api/rest/authorizations/show-details-for-authorized-payment).

| Event                           | Trigger                                                                                                                                                                        | Related method                                                                                                                            |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `PAYMENT.AUTHORIZATION.CREATED` | A payment authorization is created, approved, executed, or a future payment authorization is created.                                                                          | [Capture authorized payment](/reference/api/rest/authorizations/show-details-for-authorized-payment)                                      |
| `PAYMENT.AUTHORIZATION.VOIDED`  | A payment authorization is voided either due to authorization reaching it's 30 day validity period or authorization was manually voided using the Void Authorized Payment API. | [Show details for authorized payment](/reference/api/rest/authorizations/void-authorized-payment) with response `status` of `voided`.     |
| `PAYMENT.CAPTURE.DECLINED`      | A payment capture is declined.                                                                                                                                                 | [Capture authorized payment](/reference/api/rest/authorizations/capture-authorized-payment) with `status` of `declined`.                  |
| `PAYMENT.CAPTURE.COMPLETED`     | A payment capture completes.                                                                                                                                                   | [Capture authorized payment](/reference/api/rest/authorizations/capture-authorized-payment) with response `status` of `completed`.        |
| `PAYMENT.CAPTURE.PENDING`       | The state of a payment capture changes to pending.                                                                                                                             | [Show details for authorized payment](/reference/api/rest/authorizations/capture-authorized-payment) with response `status` of `pending`. |
| `PAYMENT.CAPTURE.REFUNDED`      | A merchant refunds a payment capture.                                                                                                                                          | [Capture authorized payment](/reference/api/rest/captures/refund-captured-payment) with response `status` of `refunded`.                  |
| `PAYMENT.CAPTURE.REVERSED`      | PayPal reverses a payment capture.                                                                                                                                             | [Refund captured payment](/reference/api/rest/refunds/show-refund-details)                                                                |


# Payouts v1
Source: https://docs.paypal.ai/reference/webhook-events/payouts-v1



The following are the webhook events related to the [Payouts v1 API](/reference/api/rest/payouts/create-batch-payout)

<Note>The PAYOUTSBATCH webhooks do not contain item-related information.
To get item-related information, use the HATEOAS links from the webhooks response.</Note>

| Event                             | Trigger                                                    | Related method                                                                                |
| --------------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `PAYMENT.PAYOUTSBATCH.DENIED`     | A batch payout payment is denied.                          | [Show payout details](/reference/api/rest/payouts/show-payout-batch-details)                  |
| `PAYMENT.PAYOUTSBATCH.PROCESSING` | The state of a batch payout payment changes to processing. | [Show payout details](/reference/api/rest/payouts/show-payout-batch-details)                  |
| `PAYMENT.PAYOUTSBATCH.SUCCESS`    | A batch payout payment completes successfully.             | [Show payout details](/reference/api/rest/payouts/show-payout-batch-details)                  |
| `PAYMENT.PAYOUTS-ITEM.BLOCKED`    | A payouts item is blocked.                                 | [Show payout item details](/reference/api/rest/payouts-item/show-payout-item-details)         |
| `PAYMENT.PAYOUTS-ITEM.CANCELED`   | A payouts item is canceled.                                | [Cancel unclaimed payout item](/reference/api/rest/payouts-item/cancel-unclaimed-payout-item) |
| `PAYMENT.PAYOUTS-ITEM.DENIED`     | A payouts item is denied.                                  | [Show payout item details](/reference/api/rest/payouts-item/show-payout-item-details)         |
| `PAYMENT.PAYOUTS-ITEM.FAILED`     | A payouts item fails.                                      | [Show payout item details](/reference/api/rest/payouts-item/show-payout-item-details)         |
| `PAYMENT.PAYOUTS-ITEM.HELD`       | A payouts item is held.                                    | [Show payout item details](/reference/api/rest/payouts-item/show-payout-item-details)         |
| `PAYMENT.PAYOUTS-ITEM.REFUNDED`   | A payouts item is refunded.                                | [Show payout item details](/reference/api/rest/payouts-item/show-payout-item-details)         |
| `PAYMENT.PAYOUTS-ITEM.RETURNED`   | A payouts item is returned.                                | [Show payout item details](/reference/api/rest/payouts-item/show-payout-item-details)         |
| `PAYMENT.PAYOUTS-ITEM.SUCCEEDED`  | A payouts item succeeds.                                   | [Show payout item details](/reference/api/rest/payouts-item/show-payout-item-details)         |
| `PAYMENT.PAYOUTS-ITEM.UNCLAIMED`  | A payouts item is unclaimed.                               | [Show payout item details](/reference/api/rest/payouts-item/show-payout-item-details)         |


# Webhook message format
Source: https://docs.paypal.ai/reference/webhook-events/webhook-format



Webhook messages are structured in a JSON format, which includes several key properties that provide important information about the event. The `resource` property contains an object that matches the format of the response object for the corresponding API call.

Here is a breakdown of the main properties in a webhook message:

| Field           | Description                                                                                                                                     |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`            | A unique identifier for the webhook event.                                                                                                      |
| `create_time`   | The timestamp when the event was created.                                                                                                       |
| `resource_type` | The type of resource associated with the event (e.g., authorization, payment).                                                                  |
| `event_version` | The version of the event schema.                                                                                                                |
| `event_type`    | The specific type of event that occurred (e.g., PAYMENT.AUTHORIZATION.CREATED).                                                                 |
| `summary`       | A brief description of the event.                                                                                                               |
| `resource`      | An object containing details about the resource involved in the event. See the coresponding API documentation for the structure of this object. |

```json Webhook Event Example theme={null}
{
  "id": "8PT597110X687430LKGECATA",
  "create_time": "2013-06-25T21:41:28Z",
  "resource_type": "authorization",
  "event_version": "1.0",
  "event_type": "PAYMENT.AUTHORIZATION.CREATED",
  "summary": "A payment authorization was created",
  "resource": {
    "id": "2DC87612EK520411B",
    "create_time": "2013-06-25T21:39:15Z",
    "update_time": "2013-06-25T21:39:17Z",
    "state": "authorized",
    "amount": {
      "total": "7.47",
      "currency": "USD",
      "details": {
        "subtotal": "7.47"
      }
    },
    "parent_payment": "PAY-36246664YD343335CKHFA4AY",
    "valid_until": "2013-07-24T21:39:15Z",
    "links": [
      {
        "href": "https://api-m.paypal.com/v1/payments/authorization/2DC87612EK520411B",
        "rel": "self",
        "method": "GET"
      },
      {
        "href": "https://api-m.paypal.com/v1/payments/authorization/2DC87612EK520411B/capture",
        "rel": "capture",
        "method": "POST"
      },
      {
        "href": "https://api-m.paypal.com/v1/payments/authorization/2DC87612EK520411B/void",
        "rel": "void",
        "method": "POST"
      },
      {
        "href": "https://api-m.paypal.com/v1/payments/payment/PAY-36246664YD343335CKHFA4AY",
        "rel": "parent_payment",
        "method": "GET"
      }
    ]
  },
  "links": [
    {
      "href": "https://api-m.paypal.com/v1/notfications/webhooks-events/8PT597110X687430LKGECATA",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.paypal.com/v1/notfications/webhooks-events/8PT597110X687430LKGECATA/resend",
      "rel": "resend",
      "method": "POST"
    }
  ]
}
```