Use cases

Explore key ways to apply the Payment Links and 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	`POST /v1/checkout/payment-resources`
List payment links	`GET /v1/checkout/payment-resources`
Get payment link details	`GET /v1/checkout/payment-resources/{id}`
Update payment link	`PUT /v1/checkout/payment-resources/{id}`
Delete payment link	`DELETE /v1/checkout/payment-resources/{id}`

Prerequisites

Set up a PayPal Business Account.
Navigate to the Apps and Credentials section on the PayPal Developer Dashboard 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, 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.

{
  "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"
        }
      ],
      "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.

{
  "id": "PLB-8H2K9J3N5P7Q",
  "integration_mode": "LINK",
  "type": "BUY_NOW",
  "reusable": "MULTIPLE",
  "return_url": "https://example.com/return",
  "line_items": [
    {
      "name": "Premium Wireless Headphones",
      "product_id": "HEADPHONE-001",
      "description": "High-quality noise-canceling wireless headphones",
      "unit_amount": { "currency_code": "USD", "value": "199.99" },
      "taxes": [
        { "name": "Sales Tax", "amount": { "currency_code": "USD", "value": "16.00" } }
      ],
      "shipping": [
        { "name": "Standard Shipping", "amount": { "currency_code": "USD", "value": "5.99" } }
      ],
      "collect_shipping_address": true,
      "customer_notes": [{ "label": "Gift message", "required": false }],
      "variants": {
        "options": [
          { "name": "Color", "values": ["Black", "Silver", "White"] }
        ]
      },
      "adjustable_quantity": { "enabled": true, "min_quantity": 1, "max_quantity": 10 }
    }
  ],
  "status": "ACTIVE",
  "create_time": "2025-10-10T12:30:45Z",
  "payment_link": "https://www.paypal.com/paymentpage/PLB-8H2K9J3N5P7Q"
}

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.

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.

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.

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.

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"
                }
            ]
        }
    ]
}'

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.

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.

{
  "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.

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

{
  "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.

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.

{
  "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.

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

Payment links and buttons

Payment methods

Save payment methods

Prerequisites

Create payment links and buttons (`POST`)

Request

Response

Additional use cases

Create a payment link with a return URL

Create a payment link with variants

Create a payment link with variant-level pricing

Create a payment link with taxes and shipping

List payment links (`GET`)

Request

Response

Get payment link details (`GET`)

Request

Response

Update payment link (`PUT`)

Request

Response

Delete payment link (`DELETE`)

Request

Response

Test

Common errors

Payment links and buttons

Payment methods

Save payment methods

​Prerequisites

​Create payment links and buttons (POST)

​Request

​Response

​Additional use cases

​Create a payment link with a return URL

​Create a payment link with variants

​Create a payment link with variant-level pricing

​Create a payment link with taxes and shipping

​List payment links (GET)

​Request

​Response

​Get payment link details (GET)

​Request

​Response

​Update payment link (PUT)

​Request

​Response

​Delete payment link (DELETE)

​Request

​Response

​Test

​Common errors

Prerequisites

Create payment links and buttons (`POST`)

Request

Response

Additional use cases

Create a payment link with a return URL

Create a payment link with variants

Create a payment link with variant-level pricing

Create a payment link with taxes and shipping

List payment links (`GET`)

Request

Response

Get payment link details (`GET`)

Request

Response

Update payment link (`PUT`)

Request

Response

Delete payment link (`DELETE`)

Request

Response

Test

Common errors