> ## 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. # Creates a payment resource for a single-item purchase > 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. ## OpenAPI ````yaml /api-reference/payment_links_and_buttons_v1.json post /v1/checkout/payment-resources openapi: 3.0.3 info: title: Payment Links and Buttons description: >- The Payment Links and Buttons API enables you to programmatically create and manage payment links and buttons. Use this API to generate shareable URLs, retrieve payment details, and update configurations without building custom checkout flows. version: '1.8' servers: - url: https://api.paypal.com/v1/checkout security: [] tags: - name: Payment-Links description: Use the /links/{id} resource to retrieve details about payment links. - name: Create-Context description: >- Use the `/links/{id}/create-context` resource to create context (order creation) associated with payment link. - name: Pay-Context description: >- Use the `/links/{id}/pay` resource to pay the context associated with payment link. - name: Context-Details description: >- Use the `/links/{id}/contexts/{context_id}` resource to retrieve the context details associated with payment link. - name: Acquire-Shipping-Options description: >- Use the `/links/{id}/shipping-options` resource to load the shipping options and updated amount of the context associated with payment link. - name: Cart description: >- Use the `/carts` resource to create or get cart and `/carts/{id}` resource to update or get cart. - name: Payment-Resources description: >- Use the `/payment-resources` resource to create or get payment resources and `/payment-resources/{id}` resource to update or get payment resource. paths: /v1/checkout/payment-resources: post: tags: - Payment-Resources summary: Creates a payment resource for a single-item purchase description: >- 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. operationId: payment-resources.post parameters: - $ref: '#/components/parameters/paypal_request_id' - $ref: '#/components/parameters/content_type' - $ref: '#/components/parameters/paypal_auth_assertion' requestBody: content: application/json: schema: $ref: '#/components/schemas/payment_resource_request' required: true responses: '200': description: Payment resource generated successfully. content: application/json: schema: $ref: '#/components/schemas/payment_resource_detailed_response' '201': description: Payment resource generated successfully. content: application/json: schema: $ref: '#/components/schemas/payment_resource_detailed_response' '400': description: >- Request is not well-formed, syntactically incorrect, or violates schema. content: application/json: schema: $ref: '#/components/schemas/error' '403': description: Authorization failed due to insufficient permissions. content: application/json: schema: $ref: '#/components/schemas/error' '409': description: >- The request failed because a previous call for the given resource is in progress. content: application/json: schema: $ref: '#/components/schemas/error' '422': description: >- The requested action could not be performed, semantically incorrect, or failed business validation. content: application/json: schema: $ref: '#/components/schemas/error' '500': description: An internal server error has occurred. content: application/json: schema: $ref: '#/components/schemas/error' default: description: The error response. content: application/json: schema: $ref: '#/components/schemas/error' security: - Oauth2: - https://uri.paypal.com/services/checkout/payment-resources - Oauth2: - >- https://uri.paypal.com/services/checkout/payment-resources/readwrite components: parameters: paypal_request_id: in: header name: PayPal-Request-Id description: The server stores keys for 6 hours. required: true schema: type: string minLength: 1 maxLength: 108 pattern: ^[0-9a-zA-Z_-]+$ content_type: name: Content-Type description: >- The media type. Required for operations with a request body. The value is `application/`, where `format` is `json`. in: header schema: type: string minLength: 1 maxLength: 255 pattern: ^[A-Za-z0-9/+-]+$ paypal_auth_assertion: name: PayPal-Auth-Assertion in: header description: >- An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see PayPal-Auth-Assertion. required: false schema: type: string schemas: payment_resource_request: type: object title: Create Payment Resource Request. description: Create payment resource details. allOf: - $ref: '#/components/schemas/payment_resource_entity' payment_resource_detailed_response: type: object title: Payment Resource Detailed Response description: >- Detailed response for Payment resource, which include code snippets for payment resources. allOf: - $ref: '#/components/schemas/payment_resource_base_response' - properties: code_snippets: $ref: '#/components/schemas/code_snippet' description: >- Code snippets holds the code needed to inject payment resources for merchant experience. error: type: object title: Error description: The error details. properties: name: type: string description: The human-readable, unique name of the error. message: type: string description: The message that describes the error. debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. details: $ref: '#/components/schemas/error_details_list' links: $ref: '#/components/schemas/definitions-link_description_list' required: - name - message - debug_id payment_resource_entity: type: object title: Payment Resource Entity description: Payment resource details. properties: integration_mode: $ref: '#/components/schemas/integration_mode' type: $ref: '#/components/schemas/payment_resource_type' reusable: $ref: '#/components/schemas/reusable' return_url: type: string description: >- URL to which the customer is redirected after completing the transaction. minLength: 1 maxLength: 1024 pattern: ^.*$ format: uri line_items: $ref: '#/components/schemas/line_item_list' required: - integration_mode - type payment_resource_base_response: type: object title: Payment Resource Response description: Payment resource response details. allOf: - properties: id: $ref: '#/components/schemas/payment_resource_id' payment_link: type: string description: >- The generated payment link URL for the transaction (present if integration_mode is link). minLength: 1 maxLength: 200 pattern: ^.*$ readOnly: true links: $ref: >- #/components/schemas/payment_resource_base_response_definitions-link_description_list create_time: $ref: '#/components/schemas/date_time' description: The date and time that this payment resource was created. readOnly: true update_time: $ref: '#/components/schemas/date_time' description: The date and time that the payment resource was updated. readOnly: true status: $ref: '#/components/schemas/status' - $ref: '#/components/schemas/payment_resource_entity' code_snippet: type: object title: Code snippets description: >- Code snippets holds the code needed to inject payment resources for merchant experience. Only applicable when integration_mode="BUTTON" & type="BUY_NOW". readOnly: true properties: single: $ref: '#/components/schemas/single' stacked: $ref: '#/components/schemas/code_snippet_stacked_list' error_details_list: type: array description: An array of additional details about the error. items: $ref: '#/components/schemas/error_details-2' definitions-link_description_list: type: array description: >- An array of request-related [HATEOAS links](/api/rest/responses/#hateoas-links). readOnly: true items: $ref: '#/components/schemas/link_description' integration_mode: title: Integration Mode description: >- Determines how the payment resource is presented to customers. Currently, only LINK is supported, which generates a PayPal-hosted payment page with a shareable URL. This value is immutable after creation. type: string pattern: ^[A-Z0-9_]+$ minLength: 1 maxLength: 20 x-enumDescriptions: - value: LINK description: >- Generates a hosted payment page accessible via URL. Currently the only supported mode. enum: - LINK payment_resource_type: title: Payment Resource Type description: >- The type of payment resource. Once a payment resource is created, this field cannot be changed. type: string pattern: ^[A-Z0-9_]+$ minLength: 1 maxLength: 20 x-enumDescriptions: - value: BUY_NOW description: >- Single-item purchase with immediate payment completion. Creates a payment resource for one product or service that processes payment in real-time during checkout. enum: - BUY_NOW reusable: title: Reusable description: >- Indicates if the payment resource can be used multiple times or only once. type: string pattern: ^[A-Z0-9_]+$ minLength: 1 maxLength: 20 default: MULTIPLE x-enumDescriptions: - value: MULTIPLE description: The payment resource can be used multiple times. enum: - MULTIPLE line_item_list: type: array minItems: 1 maxItems: 20 description: List of individual item in payment resource. items: $ref: '#/components/schemas/line_item' payment_resource_id: type: string description: Unique identifier for the payment resource (link or button). readOnly: true minLength: 1 maxLength: 127 pattern: ^[A-Z]{3}-[A-Z0-9]+$ payment_resource_base_response_definitions-link_description_list: type: array description: >- An array of related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). minItems: 1 maxItems: 20 readOnly: true items: $ref: '#/components/schemas/link_description' date_time: type: string description: >- The date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.
format: ppaas_date_time_v3 minLength: 20 maxLength: 64 pattern: >- ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$ status: title: Status description: Status of the payment resource. type: string pattern: ^[A-Z0-9_]+$ minLength: 1 maxLength: 20 default: ACTIVE readOnly: true x-enumDescriptions: - value: ACTIVE description: The payment resource is active. - value: INACTIVE description: The payment resource is inactive. enum: - ACTIVE - INACTIVE single: type: object title: Code snippets for single PayPal button. description: >- Code snippet to place the PayPal button on your site. Applicable only when integration_mode="BUTTON" & type="BUY_NOW". properties: body: description: >- Paste this code in your page's body tag, ideally near your product. You can repeat this for each payment resource you have on the page. type: string minLength: 1 maxLength: 9999 pattern: ^.*$ code_snippet_stacked_list: type: array minItems: 1 maxItems: 5 description: Code snippets to place the PayPal buttons on your site. items: $ref: '#/components/schemas/code_snippet_stacked' error_details-2: title: Error Details type: object description: The error details. Required for client-side `4XX` errors. properties: field: type: string description: >- The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors. value: type: string description: The value of the field that caused the error. location: type: string description: >- The location of the field that caused the error. Value is `body`, `path`, or `query`. default: body issue: type: string description: The unique, fine-grained application-level error code. links: $ref: '#/components/schemas/link_description_list' description: type: string description: >- The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value. required: - issue link_description: type: object title: Link Description description: >- The request-related [HATEOAS link](/api/rest/responses/#hateoas-links) information. required: - href - rel properties: href: type: string description: >- The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call. rel: type: string description: >- The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml). method: type: string description: The HTTP method required to make the related call. enum: - GET - POST - PUT - DELETE - HEAD - CONNECT - OPTIONS - PATCH line_item: type: object title: Line Item of Payment Resource description: List of individual item in payment resource. properties: name: type: string description: The product or service name displayed to customers during checkout. minLength: 1 maxLength: 127 pattern: ^.*$ product_id: type: string description: Your internal identifier for this product. minLength: 1 maxLength: 50 pattern: ^.*$ description: type: string description: >- Detailed information about the product or service shown to customers during checkout. Use this to provide additional context, specifications, or terms. minLength: 1 maxLength: 2048 pattern: ^.*$ unit_amount: $ref: '#/components/schemas/money' description: >- The price per unit of this item, including the numeric value and currency code. taxes: $ref: '#/components/schemas/tax_list' shipping: $ref: '#/components/schemas/shipping_list' collect_shipping_address: type: boolean description: >- Prompts customers for a shipping address during checkout for this item. Set to true for physical goods that require delivery, false for digital goods. customer_notes: $ref: '#/components/schemas/customer_note_list' variants: $ref: '#/components/schemas/variants' description: >- Product variants such as size, color, or material presented to customers during checkout. Each variant (e.g., "Size") can have up to 10 options (e.g., "S", "M", "L", "XL"). Supports up to 5 variants total. One variant can be designated as primary to enable different prices per option. adjustable_quantity: $ref: '#/components/schemas/adjustable_quantity' description: >- Allows customers to change the quantity of this item during checkout. code_snippet_stacked: type: object title: Code snippets for stacked button description: >- Code snippets to place the PayPal buttons on your site. It supports 2 flavours "REACT", "HTML". Applicable only when integration_mode="BUTTON" & type="BUY_NOW". readOnly: true properties: framework: type: string description: >- To identify the flavour of code snippets for stacked button (e.g. "HTML", "REACT"). pattern: ^[A-Z0-9_]+$ minLength: 1 maxLength: 32 x-enumDescriptions: - value: HTML description: Code snippets to add stacked buttons to your site with HTML - value: REACT description: Code snippets to add stacked buttons to your site with React enum: - HTML - REACT head: description: >- Paste this code in your website’s head (or at the top of your page’s body above the Part 2 code) only once per page. type: string minLength: 1 maxLength: 9999 pattern: ^.*$ body: description: Paste this code in your page's body. type: string minLength: 1 maxLength: 9999 pattern: ^.*$ button_placement: description: >- Paste this code in the page where you want the button to show up, near your product. type: string minLength: 1 maxLength: 9999 pattern: ^.*$ required: - framework link_description_list: type: array description: >- An array of request-related [HATEOAS links](/api/rest/responses/#hateoas-links) that are either relevant to the issue by providing additional information or offering potential resolutions. readOnly: true minItems: 1 maxItems: 4 items: $ref: '#/components/schemas/link_description' money: type: object title: Money description: >- The currency and amount for a financial transaction, such as a balance or payment due. properties: currency_code: $ref: '#/components/schemas/currency_code' value: type: string description: >- The value, which might be:For the required number of decimal places for a currency code, see [Currency Codes](/api/rest/reference/currency-codes/). maxLength: 32 pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$ required: - currency_code - value tax_list: type: array minItems: 1 maxItems: 1 description: >- Taxes applied to this item. Tax is displayed separately to customers during checkout. items: $ref: '#/components/schemas/tax' shipping_list: type: array minItems: 1 maxItems: 1 description: >- Shipping fee for this item. Shipping fee is displayed separately to customers during checkout. items: $ref: '#/components/schemas/shipping' customer_note_list: type: array minItems: 1 maxItems: 1 description: >- Label for a custom field to collect additional information from customers about this item (e.g., "Engraving text" or "Special instructions"). Can be set as mandatory. items: $ref: '#/components/schemas/customer_note' variants: type: object title: Variant of Payment Resource description: >- Product variants such as size, color, or material presented to customers during checkout. Each variant (e.g., "Size") can have up to 10 options (e.g., "S", "M", "L", "XL"). Supports up to 5 variants total. One variant can be designated as primary to enable different prices per option. properties: dimensions: $ref: '#/components/schemas/dimension_list' required: - dimensions adjustable_quantity: type: object title: Adjustable Quantity description: Allows customers to change the quantity of this item during checkout. properties: maximum: type: integer description: >- The maximum quantity customers can select. Must be between 1 and 100. Setting this value enables the quantity picker at checkout. minimum: 1 maximum: 100 required: - maximum currency_code: description: >- The [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency. type: string format: ppaas_common_currency_code_v2 minLength: 3 maxLength: 3 tax: type: object title: Tax description: >- Taxes applied to this item. Tax is displayed separately to customers during checkout. properties: name: type: string description: >- Internal label for this tax (e.g., "Sales Tax", "VAT"). Not visible to customer. minLength: 1 maxLength: 127 pattern: ^.*$ type: description: The method used to calculate this tax. type: string pattern: ^[A-Z0-9_]+$ minLength: 1 maxLength: 32 x-enumDescriptions: - value: PERCENTAGE description: >- Applies a flat percentage to the item amount (e.g., 10% sales tax). - value: PREFERENCE description: >- Calculates tax based on the merchant's PayPal account tax settings. Requires merchant to have tax rates configured in their PayPal account Settings. enum: - PERCENTAGE - PREFERENCE value: description: >- The tax amount or reference. For PERCENTAGE, enter the numeric percentage value (e.g., "10" for 10%). For PREFERENCE, must be set to "PROFILE". Maximum 20 characters. type: string minLength: 1 maxLength: 20 pattern: ^.*$ required: - type - value shipping: type: object title: Shipping description: >- Shipping fee for this item. Shipping fee is displayed separately to customers during checkout. properties: type: description: The method used to calculate shipping costs. type: string pattern: ^[A-Z0-9_]+$ minLength: 1 maxLength: 32 x-enumDescriptions: - value: FLAT description: >- Applies a fixed shipping fee regardless of quantity (e.g., $5.00 whether customer buys 1 or 10 units). - value: PERCENTAGE description: Percentage shipping type eg "10" for 10%. - value: PREFERENCE description: >- Calculates shipping based on the merchant's PayPal account shipping settings. Requires merchant to have shipping rates configured in their PayPal Business Settings. enum: - FLAT - PERCENTAGE - PREFERENCE value: description: >- The shipping value or reference. For FLAT, enter the fixed cost (e.g., "5" for $5.00). For PREFERENCE, must be set to "PROFILE". type: string minLength: 1 maxLength: 20 pattern: ^.*$ required: - type - value customer_note: type: object title: Customer Note description: >- Label for a custom field to collect additional information from customers about this item (e.g., "Engraving text" or "Special instructions"). Can be set as mandatory. properties: required: type: boolean description: >- Whether this custom field is required for checkout. Set to true to make the field mandatory. label: description: >- The label displayed to customers for this custom input field (e.g., "Enter engraving text" or "Delivery instructions"). type: string minLength: 1 maxLength: 127 pattern: ^.*$ dimension_list: type: array description: >- List of variant dimensions available for this product. Each dimension can have multiple options. minItems: 1 maxItems: 5 items: $ref: '#/components/schemas/dimension' dimension: type: object title: Variant of Payment Resource description: >- Variant dimension structure with multiple options. Each variant can have multiple options, and only one variant can be marked as primary. properties: name: type: string description: The name of the variant dimension (e.g., "Size", "Color"). minLength: 1 maxLength: 64 pattern: ^.*$ primary: type: boolean description: >- Only one dimension has primary set to true. Only options in the primary dimension can have unit_amount. options: $ref: '#/components/schemas/dimension_option_list' required: - name - primary - options dimension_option_list: type: array description: List of option available. minItems: 1 maxItems: 10 items: $ref: '#/components/schemas/dimension_option' dimension_option: type: object title: Option available for the item. description: Option available for the item. properties: label: type: string description: The display label for this option (e.g., "Large"). minLength: 1 maxLength: 200 pattern: ^.*$ unit_amount: $ref: '#/components/schemas/money' description: Unit Price of this option, including value and currency code. required: - label securitySchemes: Oauth2: type: oauth2 description: Oauth 2.0 authentication. flows: clientCredentials: tokenUrl: https://api-m.paypal.com/v1/oauth2/token scopes: https://uri.paypal.com/services/checkout/links: >- Allows merchants to create context and pay for nocode payment link. https://uri.paypal.com/services/checkout/payment-resources: Allow merchants to read and write payment resources. https://uri.paypal.com/services/checkout/payment-resources/read: Allows third-party apps to have read access to payment resources. https://uri.paypal.com/services/checkout/payment-resources/readwrite: >- Allows third-party apps to have read and write access to payment resources. ````