Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt

Use this file to discover all available pages before exploring further.

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 for a list of supported currencies.

​
Prerequisites

  • Set up a PayPal Business Account.
  • Navigate to the Apps and Credentials section on the PayPal Developer Dashboard 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. 
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. Send a POST request with the minimal required product details. 
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"
        }
      }
    ]
  }'
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. 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. 
{
    "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.

​
Endpoints

This section summarizes each endpoint. See the full API reference for the complete schema and additional examples.
Use caseEndpointRequestResponse
Create payment linksPOST /v1/checkout/payment-resourcesInclude product details in the request body, such as name, price, description, variants, taxes, shipping information, and the return URL.Returns 201 Created with the payment link ID, shareable link URL, status, and creation timestamp.
List all payment linksGET /v1/checkout/payment-resourcesThis 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 detailsGET /v1/checkout/payment-resources/{id}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 linkPUT /v1/checkout/payment-resources/{id}Use the payment link ID in the URL path. Include the complete, updated product information in the request body.Returns 200 OK with the updated payment link details.
Delete payment linkDELETE /v1/checkout/payment-resources/{id}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

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

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

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

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

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 typically returns HTTP status 204 No Content. In some cases, it may also return a confirmation body: 
{
  "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 resources (DELETE /v1/checkout/payment-resources/{id})

Permanently delete a payment resource by its unique ID.

​
Request

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 codeError nameError messageCommon cause
400INVALID_REQUESTRequest 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.
403NOT_AUTHORIZEDAuthorization failed due to insufficient permissions.The access token is expired or lacks the correct OAuth scopes, and the merchant account doesn’t have permission for payment buttons.
404RESOURCE_NOT_FOUNDThe 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.
422UNPROCESSABLE_ENTITYThe 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.
500INTERNAL_SERVER_ERRORAn 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.

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