> ## 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. # Refund captured payment > 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 amount object in the JSON request body. ## OpenAPI ````yaml /api-reference/payments_payment_v2.json post /v2/payments/captures/{capture_id}/refund openapi: 3.0.4 info: title: Payments description: >- Call the Payments API to authorize payments, capture authorized payments, refund payments that have already been captured, and show payment information. Use the Payments API in conjunction with the Orders API. For more information, see the PayPal Checkout Overview. version: '2.13' servers: - url: https://api-m.paypal.com description: Server for https scheme. security: [] tags: - name: assets description: Assets APIs for Checkout - name: authorizations description: >- Use the `/authorizations` resource to show details for, capture payment for, reauthorize, and void authorized payments. - name: cancel-payment description: >- Use the /cancel-payment resource to cancel an order capture or order authorization by PayPal-Request-Id. The merchant triggers the cancel action. - name: captures description: >- Use the `/captures` resource to show details for and refund a captured payment. - name: find-bin-details description: >- Use the `/find-bin-details` resource to determine PayPal supported networks and retrieve BIN details for given card and payee. - name: find-eligible-methods description: >- Use the `/find-eligible-methods` resource to show list of eligible payment methods for given customer/order context. - name: payment-resource-operations description: >- Use the `/payment-resource-operations` resource to show verifications details. - name: refunds description: Use the `/refunds` resource to show refund details. externalDocs: url: /docs/checkout/ paths: /v2/payments/captures/{capture_id}/refund: post: tags: - captures summary: Refund captured payment description: >- 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 amount object in the JSON request body. operationId: captures.refund parameters: - name: capture_id description: The PayPal-generated ID for the captured payment to refund. in: path required: true schema: type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ examples: captures_refund_200_idempotent_response: summary: Refund Captured Payment - 200 idempotent response description: >- Refunds a captured payment, by ID. For a full refund, include an empty payload in the request body. For a partial refund, include an `amount` object. value: 2GG279541U471931P captures_refund_empty_request: summary: Refund Captured Payment with an empty request description: >- Refunds a captured payment, by ID. For a full refund, include an empty payload in the request body. For a partial refund, include an `amount` object. value: 7TK53561YB803214S captures_refund_with_prefer_header: summary: Refund Captured Payment description: >- Refunds a captured payment, by ID. For a full refund, include an empty payload in the request body. For a partial refund, include an `amount` object. value: 2GG279541U471931P captures_refund_with_buyer_context: summary: Refund Captured Payment with Buyer Context (Personal Account) description: >- Refunds a captured payment by ID. The response includes buyer context with the buyer-side transaction details for a personal account buyer. value: 4ER00663XR761103C captures_refund_with_buyer_context_business: summary: Refund Captured Payment with Buyer Context (Business Account) description: >- Refunds a captured payment by ID. The response includes buyer context with the buyer-side transaction details for a business account buyer. value: 51Y24067WX474121X captures_refund_with_buyer_context_guest: summary: Refund Captured Payment with Buyer Context (Guest Checkout) description: >- Refunds a captured payment by ID where the buyer checked out as a guest without a PayPal account. The response includes buyer context without a transaction details URL. value: 53457045VC219825A - $ref: '#/components/parameters/paypal_request_id' - name: Prefer description: >- The preferred server response upon successful completion of the request. Value is: in: header required: false schema: type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ default: return=minimal examples: captures_refund_200_idempotent_response: summary: Refund Captured Payment - 200 idempotent response description: >- Refunds a captured payment, by ID. For a full refund, include an empty payload in the request body. For a partial refund, include an `amount` object. value: return=representation captures_refund_with_prefer_header: summary: Refund Captured Payment description: >- Refunds a captured payment, by ID. For a full refund, include an empty payload in the request body. For a partial refund, include an `amount` object. value: return=representation captures_refund_empty_request: summary: Refund Captured Payment with an empty request description: >- Refunds a captured payment, by ID. For a full refund, include an empty payload in the request body. For a partial refund, include an `amount` object. value: return=representation captures_refund_with_buyer_context: summary: Refund Captured Payment with Buyer Context (Personal Account) description: >- Refunds a captured payment by ID. The response includes buyer context with the buyer-side transaction details for a personal account buyer. value: return=representation captures_refund_with_buyer_context_business: summary: Refund Captured Payment with Buyer Context (Business Account) description: >- Refunds a captured payment by ID. The response includes buyer context with the buyer-side transaction details for a business account buyer. value: return=representation captures_refund_with_buyer_context_guest: summary: Refund Captured Payment with Buyer Context (Guest Checkout) description: >- Refunds a captured payment by ID where the buyer checked out as a guest without a PayPal account. The response includes buyer context without a transaction details URL. value: return=representation - $ref: '#/components/parameters/authorization' - $ref: '#/components/parameters/paypal_auth_assertion' requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/refund_request' examples: captures_refund_200_idempotent_response: summary: Refund Captured Payment - 200 idempotent response description: >- Refunds a captured payment, by ID. For a full refund, include an empty payload in the request body. For a partial refund, include an `amount` object. value: amount: value: '1.00' currency_code: USD invoice_id: RefundInvoice-123 custom_id: RefundCustom-123 captures_refund_empty_request: summary: Refund Captured Payment with an empty request description: >- Refunds a captured payment, by ID. For a full refund, include an empty payload in the request body. For a partial refund, include an `amount` object. value: {} captures_refund_with_prefer_header: summary: Refund Captured Payment description: >- Refunds a captured payment, by ID. For a full refund, include an empty payload in the request body. For a partial refund, include an `amount` object. value: amount: value: '10.99' currency_code: USD invoice_id: INVOICE-123 note: Defective product captures_refund_with_buyer_context: summary: Refund Captured Payment with Buyer Context (Personal Account) description: >- Refunds a captured payment by ID. The response includes buyer context with the buyer-side transaction details for a personal account buyer. value: amount: value: '1.00' currency_code: USD invoice_id: RefundInvoice-19_03_2026_6_41_17_pm custom_id: RefundCustom-19_03_2026_6_41_17_pm captures_refund_with_buyer_context_business: summary: Refund Captured Payment with Buyer Context (Business Account) description: >- Refunds a captured payment by ID. The response includes buyer context with the buyer-side transaction details for a business account buyer. value: amount: value: '1.00' currency_code: USD invoice_id: RefundInvoice-19_03_2026_6_42_08_pm custom_id: RefundCustom-19_03_2026_6_42_08_pm captures_refund_with_buyer_context_guest: summary: Refund Captured Payment with Buyer Context (Guest Checkout) description: >- Refunds a captured payment by ID where the buyer checked out as a guest without a PayPal account. The response includes buyer context without a transaction details URL. value: amount: value: '1.00' currency_code: USD invoice_id: RefundInvoice-19_03_2026_7_05_42_pm custom_id: RefundCustom-19_03_2026_7_05_42_pm responses: '200': description: >- A successful request returns the HTTP 200 OK status code and a JSON response body that shows refund details. content: application/json: schema: $ref: '#/components/schemas/refund' examples: captures_refund_200_idempotent_response: summary: Refund Captured Payment - 200 idempotent response description: >- Refunds a captured payment, by ID. For a full refund, include an empty payload in the request body. For a partial refund, include an `amount` object. value: id: 0K35355239430361V amount: currency_code: USD value: '1.00' seller_payable_breakdown: gross_amount: currency_code: USD value: '1.00' paypal_fee: currency_code: USD value: '0.00' net_amount: currency_code: USD value: '1.00' total_refunded_amount: currency_code: USD value: '11.00' invoice_id: RefundInvoice-14_10_2024_4_58_32_pm custom_id: RefundCustom-14_10_2024_4_58_32_pm status: COMPLETED create_time: '2024-10-14T14:58:34-07:00' update_time: '2024-10-14T14:58:34-07:00' links: - href: >- https://api.paypal.com/v2/payments/refunds/0K35355239430361V rel: self method: GET - href: >- https://api.paypal.com/v2/payments/captures/7TK53561YB803214S rel: up method: GET '201': description: >- A successful request returns the HTTP 201 Created status code and a JSON response body that shows refund details. content: application/json: schema: $ref: '#/components/schemas/refund' examples: captures_refund_empty_request: summary: Refund Captured Payment with an empty request description: >- Refunds a captured payment, by ID. For a full refund, include an empty payload in the request body. For a partial refund, include an `amount` object. value: id: 58K15806CS993444T amount: currency_code: USD value: '89.00' seller_payable_breakdown: gross_amount: currency_code: USD value: '89.00' paypal_fee: currency_code: USD value: '0.00' net_amount: currency_code: USD value: '89.00' total_refunded_amount: currency_code: USD value: '100.00' invoice_id: OrderInvoice-10_10_2024_12_58_20_pm status: COMPLETED create_time: '2024-10-14T15:03:29-07:00' update_time: '2024-10-14T15:03:29-07:00' links: - href: >- https://api.msmaster.qa.paypal.com/v2/payments/refunds/58K15806CS993444T rel: self method: GET - href: >- https://api.msmaster.qa.paypal.com/v2/payments/captures/7TK53561YB803214S rel: up method: GET captures_refund_with_prefer_header: summary: Refund Captured Payment description: >- Refunds a captured payment, by ID. For a full refund, include an empty payload in the request body. For a partial refund, include an `amount` object. value: id: 1JU08902781691411 amount: value: '10.99' currency_code: USD status: COMPLETED note: Defective product seller_payable_breakdown: gross_amount: value: '10.99' currency_code: USD paypal_fee: value: '0' currency_code: USD net_amount: value: '10.99' currency_code: USD total_refunded_amount: value: '10.99' currency_code: USD invoice_id: INVOICE-123 create_time: '2018-09-11T23:24:19Z' update_time: '2018-09-11T23:24:19Z' links: - rel: self method: GET href: >- https://api-m.paypal.com/v2/payments/refunds/1JU08902781691411 - rel: up method: GET href: >- https://api-m.paypal.com/v2/payments/captures/2GG279541U471931P captures_refund_with_buyer_context: summary: Refund Captured Payment with Buyer Context description: >- Refunds a captured payment by ID. The response includes buyer context with the buyer-side transaction details such as the buyer's transaction ID, status, and a link to the transaction details page. value: id: 8R659521N3692922R amount: currency_code: USD value: '1.00' seller_payable_breakdown: gross_amount: currency_code: USD value: '1.00' paypal_fee: currency_code: USD value: '0.00' net_amount: currency_code: USD value: '1.00' total_refunded_amount: currency_code: USD value: '2.00' invoice_id: RefundInvoice-19_03_2026_6_41_17_pm custom_id: RefundCustom-19_03_2026_6_41_17_pm status: COMPLETED create_time: '2026-03-19T18:41:26+05:30' update_time: '2026-03-19T18:41:26+05:30' buyer_context: transaction_id: 6T1484390E680692N transaction_details_url: >- https://www.paypal.com/myaccount/activities/details/6T1484390E680692N transaction_create_time: '2026-03-17T19:56:45+05:30' transaction_update_time: '2026-03-17T19:56:45+05:30' links: - href: >- https://api.paypal.com/v2/payments/refunds/8R659521N3692922R rel: self method: GET - href: >- https://api.paypal.com/v2/payments/captures/4ER00663XR761103C rel: up method: GET captures_refund_with_buyer_context_business: summary: >- Refund Captured Payment with Buyer Context (Business Account) description: >- Refunds a captured payment by ID. The response includes buyer context with the buyer-side transaction details for a business account buyer, with the transaction details URL pointing to the unified transactions page. value: id: 8VL67176625581325 amount: currency_code: USD value: '1.00' seller_payable_breakdown: gross_amount: currency_code: USD value: '1.00' paypal_fee: currency_code: USD value: '0.00' net_amount: currency_code: USD value: '1.00' total_refunded_amount: currency_code: USD value: '2.00' invoice_id: RefundInvoice-19_03_2026_6_42_08_pm custom_id: RefundCustom-19_03_2026_6_42_08_pm status: COMPLETED create_time: '2026-03-19T18:42:18+05:30' update_time: '2026-03-19T18:42:18+05:30' buyer_context: transaction_id: 55E00454BG761444L transaction_details_url: >- https://www.paypal.com/unifiedtransactions/details/payment/55E00454BG761444L transaction_create_time: '2026-03-17T20:10:16+05:30' transaction_update_time: '2026-03-17T20:10:16+05:30' links: - href: >- https://api.paypal.com/v2/payments/refunds/8VL67176625581325 rel: self method: GET - href: >- https://api.paypal.com/v2/payments/captures/51Y24067WX474121X rel: up method: GET captures_refund_with_buyer_context_guest: summary: Refund Captured Payment with Buyer Context (Guest Checkout) description: >- Refunds a captured payment by ID where the buyer checked out as a guest without a PayPal account. The response includes buyer context with the buyer-side transaction details but no transaction details URL. value: id: 0EN87552KK190061W amount: currency_code: USD value: '1.00' seller_payable_breakdown: gross_amount: currency_code: USD value: '1.00' paypal_fee: currency_code: USD value: '0.00' net_amount: currency_code: USD value: '1.00' total_refunded_amount: currency_code: USD value: '3.00' invoice_id: RefundInvoice-19_03_2026_7_05_42_pm custom_id: RefundCustom-19_03_2026_7_05_42_pm status: COMPLETED create_time: '2026-03-19T19:05:51+05:30' update_time: '2026-03-19T19:05:51+05:30' buyer_context: transaction_id: 0BF77575VK4138745 transaction_create_time: '2026-03-17T20:25:45+05:30' transaction_update_time: '2026-03-17T20:25:45+05:30' links: - href: >- https://api.paypal.com/v2/payments/refunds/0EN87552KK190061W rel: self method: GET - href: >- https://api.paypal.com/v2/payments/captures/53457045VC219825A rel: up method: GET '400': description: >- The request failed because it is not well-formed or is syntactically incorrect or violates schema. content: application/json: schema: $ref: '#/components/schemas/error' examples: capture_refund_400_invalid_request: summary: Refund Captured Payment - 400 Bad Request - Validation Error description: >- This code sample attempts to refund a captured payment, but the request fails because a validation error occurred. value: name: INVALID_REQUEST message: >- Request is not well-formed, syntactically incorrect, or violates schema debug_id: 78916e688cf7f details: - issue: INVALID_STRING_LENGTH field: /invoice_id value: >- Fm67fYiinqFm67fYiinqFm67fYiinqFm67fYiinqFm67fYiinqFm67fYiinqFm67fYiinqFm67fYiinqFm67fYiinqFm67fYiinqFm67fYiinqFm67fYiinqFm67fYiinqFm67fYiinq description: The value of a field is either too short or too long. location: body links: - href: >- https://developer.paypal.com/docs/api/payments/v2/#error-INVALID_STRING_LENGTH rel: information_link '401': $ref: '#/components/responses/401_error_response' '403': $ref: '#/components/responses/403_error_response' '404': $ref: '#/components/responses/404_error_response' '409': description: >- The request failed because a previous call for the given resource is in progress. content: application/json: schema: $ref: '#/components/schemas/error' examples: captures_refund_409_conflict: summary: >- Refund Captured Payment - 409 Conflict - Operation in Progress Error description: >- This code sample attempts to refund a captured payment but the request fails because a previous call for the given resource is in progress. value: name: RESOURCE_CONFLICT debug_id: b1d1f06c7246c message: >- The server has detected a conflict while processing this request. details: - issue: PREVIOUS_REQUEST_IN_PROGRESS description: >- A previous request on this resource is currently in progress. Please wait for some time and try again. It is best to space out the initial and the subsequent request(s) to avoid receiving this error. '422': description: >- The request failed because it either is semantically incorrect or failed business validation. content: application/json: schema: $ref: '#/components/schemas/error' examples: captures_refund_422_amount_exceeded: summary: >- Refund Captured Payment - 422 Unprocessable Entity - Refund Amount Exceeded Error description: >- This code sample attempts to refund a captured payment, but the request fails because the refund amount has exceeded the capture amount. value: name: UNPROCCESSABLE_ENTITY message: >- The requested action could not be completed, is semantically incorrect, or failed business validation. debug_id: 90bff07028f7f details: - issue: REFUND_AMOUNT_EXCEEDED description: >- The refund amount must be less than or equal to the capture amount that has not yet been refunded. captures_refund_422_transaction_disputed: summary: >- Refund Captured Payment - 422 Unprocessable Entity - Capture Disputed Partial Refund Error description: >- This code sample attempts to partially refund a captured payment, but the request fails because the captured payment is currently under dispute. value: name: UNPROCESSABLE_ENTITY message: >- The requested action could not be performed, semantically incorrect, or failed business validation. debug_id: 90bff07028f7f details: - issue: TRANSACTION_DISPUTED description: >- Partial refunds cannot be offered at this time because there is an open case on this transaction. Visit the PayPal Resolution Center to review this case. '500': $ref: '#/components/responses/500_error_response' default: $ref: '#/components/responses/default_response' callbacks: capture_refunded: captures/{$request.path.capture_id}/refunds: post: summary: Capture refunded notification description: Notification sent when a capture is refunded. operationId: captures.refunded.callback requestBody: required: true content: application/json: schema: type: object title: Capture Refunded Event description: Webhook event notification for capture refunded. properties: id: type: string description: The ID of the webhook event notification. minLength: 1 maxLength: 255 pattern: ^.*$ event_version: type: string description: The version of the event. minLength: 1 maxLength: 50 pattern: ^.*$ create_time: description: >- The date and time when the webhook event notification was created. allOf: - $ref: '#/components/schemas/date_time' resource_type: type: string description: >- The name of the resource related to the webhook notification event. minLength: 1 maxLength: 100 pattern: ^.*$ resource_version: type: string description: The version of the resource. minLength: 1 maxLength: 50 pattern: ^.*$ event_type: type: string description: >- The event that triggered the webhook event notification. enum: - PAYMENT.CAPTURE.REFUNDED x-enumDescriptions: PAYMENT.CAPTURE.REFUNDED: A payment capture was refunded. summary: type: string description: A summary description for the event notification. minLength: 1 maxLength: 500 pattern: ^.*$ resource: allOf: - $ref: '#/components/schemas/refund' links: type: array description: An array of request-related HATEOAS links. minItems: 1 maxItems: 10 items: $ref: '#/components/schemas/link_description-2' examples: capture_refunded: summary: Capture refunded event description: Webhook notification when a capture is refunded. value: id: WH-3UE850097C805102A-18305212AB1299210 event_version: '1.0' create_time: '2022-10-27T22:34:27.088Z' resource_type: refund resource_version: '2.0' event_type: PAYMENT.CAPTURE.REFUNDED summary: A $ 5.0 USD capture payment was refunded resource: seller_payable_breakdown: total_refunded_amount: value: '5.00' currency_code: USD paypal_fee: value: '0.00' currency_code: USD gross_amount: value: '5.00' currency_code: USD net_amount: value: '5.00' currency_code: USD amount: value: '5.00' currency_code: USD update_time: '2022-10-27T15:34:22-07:00' create_time: '2022-10-27T15:34:22-07:00' invoice_id: '1666910062' links: - method: GET rel: self href: >- https://api-m.paypal.com/v2/payments/refunds/3NG36268BJ600681V - method: GET rel: up href: >- https://api-m.paypal.com/v2/payments/captures/27C890397M291943E id: 3NG36268BJ600681V note_to_payer: Defective product status: COMPLETED links: - href: >- https://api-m.paypal.com/v1/notifications/webhooks-events/WH-3UE850097C805102A-18305212AB1299210 rel: self method: GET - href: >- https://api-m.paypal.com/v1/notifications/webhooks-events/WH-3UE850097C805102A-18305212AB1299210/resend rel: resend method: POST responses: '204': description: >- Your server implementation should return this HTTP status code if the data was received successfully. '400': description: >- Your server should return this HTTP status code if the request is malformed. content: application/json: schema: $ref: '#/components/schemas/error' examples: invalid_request: summary: Invalid webhook request. description: Request with malformed data. value: name: INVALID_REQUEST debug_id: b1d1f06c7246c message: >- Request is not well-formed, syntactically incorrect, or violates schema. details: - field: /event_type location: body issue: INVALID_PARAMETER_SYNTAX description: >- The value of a field does not conform to the expected format. '500': $ref: '#/components/responses/500_error_response' method: post type: path path: captures/{$request.path.capture_id}/refunds security: - Oauth2: - https://uri.paypal.com/services/payments/refund components: parameters: paypal_request_id: name: PayPal-Request-Id in: header description: A unique ID identifying the request header for idempotency purposes. required: false schema: description: A unique ID identifying the request header for idempotency purposes. type: string minLength: 1 maxLength: 10000 pattern: ^.*$ examples: request_id: summary: A request id. description: A paypal-request-id header with a randomized value. value: 17e81d06-77ab-11e8-adc0-fa71639ebebc authorization: name: Authorization in: header description: Holds authorization information for external API calls. required: false schema: $ref: '#/components/schemas/standard_header_schema' examples: bearer: summary: Bearer authorization. description: >- An authorization header with information for the Bearer authorization scheme. The authorization parameter value is randomized for this example. value: >- Bearer A21AAGHr9qtiRRXH4oYcQokQgV99rGqEIfgrr8xHCclP0OzmD9KVgg5ppIIg1jzJgQkV4wd02svIvBJyg6cLFJjFow_SjBhxQ paypal_auth_assertion: name: PayPal-Auth-Assertion in: header description: >- Header for an API client-provided JWT assertion that identifies the merchant. Establishing the consent to act-on-behalf of a merchant is a prerequisite for using this header. required: false schema: description: >- Header for an API client-provided JWT assertion that identifies the merchant. Establishing the consent to act-on-behalf of a merchant is a prerequisite for using this header. type: string minLength: 1 maxLength: 10000 pattern: ^.*$ examples: auth_assertion: summary: An auth assertion. description: A paypal-auth-assertion header with a randomized value. value: eyJhbGciOiJub25lIn0.eyJlbWFpbCI6Im15QGVtYWlsLmNvbSJ9 schemas: refund_request: title: Refund Request description: >- Refunds a captured payment, by ID. For a full refund, include an empty request body. For a partial refund, include an amount object in the request body. type: object properties: amount: allOf: - $ref: '#/components/schemas/money' - description: >- The amount to refund. To refund a portion of the captured amount, specify an amount. If amount is not specified, an amount equal to captured amount - previous refunds is refunded. The amount must be a positive number and in the same currency as the one in which the payment was captured. custom_id: description: >- The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports. The pattern is defined by an external party and supports Unicode. type: string minLength: 1 maxLength: 127 pattern: ^.*$ invoice_id: description: >- The API caller-provided external invoice ID for this order. The pattern is defined by an external party and supports Unicode. type: string minLength: 1 maxLength: 127 pattern: ^.*$ note_to_payer: description: >- The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives. The pattern is defined by an external party and supports Unicode. type: string minLength: 1 maxLength: 255 pattern: ^.*$ payment_instruction: allOf: - $ref: '#/components/schemas/payment_instruction-2' - description: >- Any additional refund instructions to be set during refund payment processing. This object is only applicable to merchants that have been enabled for PayPal Commerce Platform for Marketplaces and Platforms capability. Please speak to your account manager if you want to use this capability. refund: title: refund description: The refund information. type: object allOf: - allOf: - $ref: '#/components/schemas/refund_status' - title: Refund Properties description: >- The detailed properties of the refund transaction, including identifiers, amounts, breakdowns, and associated metadata. type: object properties: id: description: The PayPal-generated ID for the refund. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ readOnly: true amount: allOf: - $ref: '#/components/schemas/money' - description: The amount that the payee refunded to the payer. readOnly: true invoice_id: description: >- The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ readOnly: true custom_id: description: >- The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports. type: string minLength: 1 maxLength: 255 pattern: ^[A-Za-z0-9-_.,]*$ acquirer_reference_number: description: >- Reference ID issued for the card transaction. This ID can be used to track the transaction across processors, card brands and issuing banks. type: string minLength: 1 maxLength: 36 pattern: ^[a-zA-Z0-9]+$ note_to_payer: description: >- The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ readOnly: true seller_payable_breakdown: title: Seller Payable Breakdown description: The breakdown of the refund. type: object readOnly: true properties: gross_amount: allOf: - $ref: '#/components/schemas/money' - description: The amount that the payee refunded to the payer. readOnly: true paypal_fee: allOf: - $ref: '#/components/schemas/money' - description: >- The PayPal fee that was refunded to the payer in the currency of the transaction. This fee might not match the PayPal fee that the payee paid when the payment was captured. readOnly: true paypal_fee_in_receivable_currency: allOf: - $ref: '#/components/schemas/money' - description: >- The PayPal fee that was refunded to the payer in the receivable currency. Returned only in cases when the receivable currency is different from transaction currency. Example 'CNY'. readOnly: true net_amount: allOf: - $ref: '#/components/schemas/money' - description: >- The net amount that the payee's account is debited in the transaction currency. The net amount is calculated as gross_amount minus paypal_fee minus platform_fees. readOnly: true net_amount_in_receivable_currency: allOf: - $ref: '#/components/schemas/money' - description: >- The net amount that the payee's account is debited in the receivable currency. Returned only in cases when the receivable currency is different from transaction currency. Example 'CNY'. readOnly: true platform_fees: description: >- An array of platform or partner fees, commissions, or brokerage fees for the refund. type: array minItems: 0 maxItems: 1 items: allOf: - $ref: '#/components/schemas/platform_fee' - title: platform_fee net_amount_breakdown: description: >- An array of breakdown values for the net amount. Returned when the currency of the refund is different from the currency of the PayPal account where the payee holds their funds. type: array minItems: 0 maxItems: 32767 readOnly: true items: allOf: - $ref: '#/components/schemas/net_amount_breakdown_item' - title: net_amount_breakdown_item total_refunded_amount: allOf: - $ref: '#/components/schemas/money' - description: >- The total amount refunded from the original capture to date. For example, if a payer makes a $100 purchase and was refunded $20 a week ago and was refunded $30 in this refund, the `gross_amount` is $30 for this refund and the `total_refunded_amount` is $50. payer: allOf: - $ref: '#/components/schemas/payee_base' - description: >- The details associated with the merchant for this transaction. readOnly: true buyer_context: allOf: - $ref: '#/components/schemas/buyer_context' - description: The buyer context for the refund transaction. readOnly: true links: description: >- An array of related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). type: array minItems: 0 maxItems: 32767 readOnly: true items: allOf: - $ref: '#/components/schemas/link_description-2' - title: link_description - allOf: - $ref: '#/components/schemas/activity_timestamps' error: title: Error description: The error details. type: object required: - debug_id - message - name properties: name: description: The human-readable, unique name of the error. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ message: description: The message that describes the error. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ debug_id: description: The PayPal internal ID. Used for correlation purposes. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ details: description: An array of additional details about the error. type: array minItems: 0 maxItems: 32767 items: allOf: - $ref: '#/components/schemas/error_details' - title: error_details links: description: >- An array of request-related [HATEOAS links](/api/rest/responses/#hateoas-links). type: array minItems: 0 maxItems: 32767 readOnly: true items: allOf: - $ref: '#/components/schemas/link_description' - title: link_description readOnly: true date_time: 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.
type: string 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})$ link_description-2: title: Link Description description: >- The request-related [HATEOAS link](/api/rest/responses/#hateoas-links) information. type: object required: - href - rel properties: href: 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. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ rel: 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). type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ method: description: The HTTP method required to make the related call. type: string enum: - GET - POST - PUT - DELETE - HEAD - CONNECT - OPTIONS - PATCH x-enumDescriptions: GET: The HTTP GET method. POST: The HTTP POST method. PUT: The HTTP PUT method. DELETE: The HTTP DELETE method. HEAD: The HTTP HEAD method. CONNECT: The HTTP CONNECT method. OPTIONS: The HTTP OPTIONS method. PATCH: The HTTP PATCH method. title: description: The link title. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ mediaType: title: media_type description: >- The media type, as defined by [RFC 2046](https://www.ietf.org/rfc/rfc2046.txt). Describes the link target. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ encType: title: enc_type description: The media type in which to submit the request data. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ default: application/json schema: allOf: - $ref: '#/components/schemas/link_schema-2' - description: The schema that describes the request data. targetSchema: allOf: - $ref: '#/components/schemas/link_schema-2' - title: target_schema description: The schema that describes the link target. standard_header_schema: title: Schema Object for standard headers description: >- Standard headers are generally less restrictive in structure due to historical precedent across browsers, etc. This is a common schema for use in defining most standard headers. type: string minLength: 1 maxLength: 16000 pattern: ^.*$ money: title: Money description: >- The currency and amount for a financial transaction, such as a balance or payment due. type: object required: - currency_code - value properties: currency_code: $ref: '#/components/schemas/currency_code' value: 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/). type: string minLength: 0 maxLength: 32 pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$ payment_instruction-2: title: payment_instruction description: >- Any additional payments instructions during refund payment processing. This object is only applicable to merchants that have been enabled for PayPal Commerce Platform for Marketplaces and Platforms capability. Please speak to your account manager if you want to use this capability. type: object properties: platform_fees: description: >- Specifies the amount that the API caller will contribute to the refund being processed. The amount needs to be lower than platform_fees amount originally captured or the amount that is remaining if multiple refunds have been processed. This field is only applicable to merchants that have been enabled for PayPal Commerce Platform for Marketplaces and Platforms capability. Please speak to your account manager if you want to use this capability. type: array minItems: 0 maxItems: 1 items: allOf: - $ref: '#/components/schemas/platform_fee' - title: platform_fee not: required: - payee refund_status: title: refund_status description: The refund status with details. type: object properties: status: title: Refund Status With Details description: The status of the refund. type: string enum: - CANCELLED - FAILED - PENDING - COMPLETED x-enumDescriptions: CANCELLED: The refund was cancelled. FAILED: The refund could not be processed. PENDING: >- The refund is pending. For more information, see status_details.reason. COMPLETED: >- The funds for this transaction were debited to the customer's account. readOnly: true status_details: allOf: - $ref: '#/components/schemas/refund_status_details' - description: The details of the refund status. readOnly: true platform_fee: title: platform_fee description: >- The platform or partner fee, commission, or brokerage fee that is associated with the transaction. Not a separate or isolated transaction leg from the external perspective. The platform fee is limited in scope and is always associated with the original payment for the purchase unit. type: object required: - amount properties: amount: allOf: - $ref: '#/components/schemas/money' - title: amount description: The fee for this transaction. payee: allOf: - $ref: '#/components/schemas/payee_base' - title: payee description: The recipient of the fee for this transaction. net_amount_breakdown_item: title: net_amount_breakdown description: >- The net amount. Returned when the currency of the refund is different from the currency of the PayPal account where the merchant holds their funds. type: object properties: payable_amount: allOf: - $ref: '#/components/schemas/money' - description: The net amount debited from the merchant's PayPal account. readOnly: true converted_amount: allOf: - $ref: '#/components/schemas/money' - description: The converted payable amount. readOnly: true exchange_rate: allOf: - $ref: '#/components/schemas/exchange_rate' - description: >- The exchange rate that determines the amount that was debited from the merchant's PayPal account. readOnly: true payee_base: title: payee_base description: >- The details for the merchant who receives the funds and fulfills the order. The merchant is also known as the payee. type: object properties: email_address: allOf: - $ref: '#/components/schemas/email' - description: The email address of merchant. merchant_id: allOf: - $ref: '#/components/schemas/account_id-2' - description: The encrypted PayPal account ID of the merchant. buyer_context: title: Buyer Context description: The buyer context for the refund transaction. type: object properties: transaction_id: description: >- The PayPal generated transaction ID associated with the buyer's refund. type: string minLength: 1 maxLength: 255 pattern: ^[0-9a-zA-Z_-]+$ readOnly: true transaction_details_url: description: The URL for the buyer to view the transaction details. type: string minLength: 1 maxLength: 2048 format: uri readOnly: true transaction_create_time: allOf: - $ref: '#/components/schemas/date_time' - description: >- The date and time when the buyer's refund transaction was created, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true transaction_update_time: allOf: - $ref: '#/components/schemas/date_time' - description: >- The date and time when the buyer's refund transaction was last updated, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true activity_timestamps: title: activity_timestamps description: >- The date and time stamps that are common to authorized payment, captured payment, and refund transactions. type: object properties: create_time: allOf: - $ref: '#/components/schemas/date_time' - description: >- The date and time when the transaction occurred, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true update_time: allOf: - $ref: '#/components/schemas/date_time' - description: >- The date and time when the transaction was last updated, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true error_details: title: Error Details description: The error details. Required for client-side `4XX` errors. type: object required: - issue properties: field: 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. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ value: description: The value of the field that caused the error. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ location: description: >- The location of the field that caused the error. Value is `body`, `path`, or `query`. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ default: body issue: description: The unique, fine-grained application-level error code. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ links: 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. type: array minItems: 1 maxItems: 4 readOnly: true items: allOf: - $ref: '#/components/schemas/link_description' - title: link_description readOnly: true description: 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. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ link_description: title: Link Description description: >- The request-related [HATEOAS link](/api/rest/responses/#hateoas-links) information. type: object required: - href - rel properties: href: 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. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ rel: 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). type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ method: description: The HTTP method required to make the related call. type: string enum: - GET - POST - PUT - DELETE - HEAD - CONNECT - OPTIONS - PATCH x-enumDescriptions: GET: The HTTP GET method. POST: The HTTP POST method. PUT: The HTTP PUT method. DELETE: The HTTP DELETE method. HEAD: The HTTP HEAD method. CONNECT: The HTTP CONNECT method. OPTIONS: The HTTP OPTIONS method. PATCH: The HTTP PATCH method. title: description: The link title. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ mediaType: title: media_type description: >- The media type, as defined by [RFC 2046](https://www.ietf.org/rfc/rfc2046.txt). Describes the link target. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ encType: title: enc_type description: The media type in which to submit the request data. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ default: application/json schema: allOf: - $ref: '#/components/schemas/link_schema' - description: The schema that describes the request data. targetSchema: allOf: - $ref: '#/components/schemas/link_schema' - title: target_schema description: The schema that describes the link target. link_schema-2: title: Link Schema description: The request data or link target. type: object properties: additionalItems: title: additional_items description: Any additional items. type: object dependencies: title: Dependencies description: Any Dependencies. type: object items: title: Items description: An item. type: object definitions: title: Definitions description: Definitions. type: object patternProperties: title: pattern_properties description: The pattern properties. type: object properties: title: Properties description: Properties. type: object allOf: title: all_of description: >- An array of sub-schemas. The data must validate against all sub-schemas. type: array minItems: 0 maxItems: 32767 items: title: all_of_item description: A sub-schema against which the data must validate. type: object anyOf: title: any_of description: >- An array of sub-schemas. The data must validate against one or more sub-schemas. type: array minItems: 0 maxItems: 32767 items: title: any_of_item description: A sub-schema against which the data must validate. type: object oneOf: title: one_of description: >- An array of sub-schemas. The data must validate against one sub-schema. type: array minItems: 0 maxItems: 32767 items: title: one_of_item description: A sub-schema against which the data must validate. type: object not: title: Not description: Not. type: object links: description: An array of links. type: array minItems: 0 maxItems: 32767 readOnly: true items: title: link description: A link. type: object readOnly: true fragmentResolution: title: fragment_resolution description: The fragment resolution. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ media: title: Media description: The media type and context-encoding scheme. type: object properties: type: description: >- The media type. See [Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types](https://tools.ietf.org/html/rfc2046). type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ binaryEncoding: title: binary_encoding description: >- The content-encoding scheme. See [Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies](https://tools.ietf.org/html/rfc2045). type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ pathStart: title: path_start description: >- To apply this schema to the instances' URIs, start the URIs with this value. type: string minLength: 0 maxLength: 2147483647 format: uri currency_code: description: >- The [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency. type: string minLength: 3 maxLength: 3 pattern: ^[\S\s]*$ refund_status_details: title: refund_status_details description: The details of the refund status. type: object properties: reason: title: Refund Incomplete Reason description: The reason why the refund has the `PENDING` or `FAILED` status. type: string enum: - ECHECK x-enumDescriptions: ECHECK: >- The customer's account is funded through an eCheck, which has not yet cleared. exchange_rate: title: exchange_rate description: >- The exchange rate that determines the amount to convert from one currency to another currency. type: object readOnly: true properties: source_currency: allOf: - $ref: '#/components/schemas/currency_code' - description: The source currency from which to convert an amount. target_currency: allOf: - $ref: '#/components/schemas/currency_code' - description: The target currency to which to convert an amount. value: description: >- The target currency amount. Equivalent to one unit of the source currency. Formatted as integer or decimal value with one to 15 digits to the right of the decimal point. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ email: title: email description: >- The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.
type: string minLength: 3 maxLength: 254 pattern: >- ^.*(?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*|(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9])|[a-zA-Z0-9-]*[a-zA-Z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\]).*$ account_id-2: title: PayPal Account Identifier description: The account identifier for a PayPal account. type: string minLength: 13 maxLength: 13 pattern: ^[2-9A-HJ-NP-Z]{13}$ link_schema: title: Link Schema description: The request data or link target. type: object properties: additionalItems: title: additional_items description: Any additional items. type: object dependencies: title: Dependencies description: The dependencies. type: object items: title: Items description: An item. type: object definitions: title: Definitions description: Definitions. type: object patternProperties: title: pattern_properties description: The pattern properties. type: object properties: title: Properties description: The properties. type: object allOf: title: all_of description: >- An array of sub-schemas. The data must validate against all sub-schemas. type: array minItems: 0 maxItems: 32767 items: title: all_of_item description: A sub-schema against which the data must validate. type: object anyOf: title: any_of description: >- An array of sub-schemas. The data must validate against one or more sub-schemas. type: array minItems: 0 maxItems: 32767 items: title: any_of_item description: A sub-schema against which the data must validate. type: object oneOf: title: one_of description: >- An array of sub-schemas. The data must validate against one sub-schema. type: array minItems: 0 maxItems: 32767 items: title: one_of_item description: A sub-schema against which the data must validate. type: object not: title: Not description: Not. type: object links: description: An array of links. type: array minItems: 0 maxItems: 32767 readOnly: true items: title: link description: A link. type: object readOnly: true fragmentResolution: title: fragment_resolution description: The fragment resolution. type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ media: title: Media description: The media type and context-encoding scheme. type: object properties: type: description: >- The media type. See [Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types](https://tools.ietf.org/html/rfc2046). type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ binaryEncoding: title: binary_encoding description: >- The content-encoding scheme. See [Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies](https://tools.ietf.org/html/rfc2045). type: string minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ pathStart: title: path_start description: >- To apply this schema to the instances' URIs, start the URIs with this value. type: string minLength: 0 maxLength: 2147483647 format: uri responses: 401_error_response: description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/error' examples: generic: summary: Generic 'Unauthorized' error. description: Example response for unauthorized request. value: name: AUTHENTICATION_FAILURE debug_id: b1d1f06c7246c message: >- Authentication failed due to missing Authorization header, or invalid authentication credentials. 403_error_response: description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/error' examples: generic: summary: Generic 'Forbidden' error. description: Example response for a forbidden request. value: name: NOT_AUTHORIZED debug_id: b1d1f06c7246c message: Authorization failed due to insufficient permissions. 404_error_response: description: Not Found. content: application/json: schema: $ref: '#/components/schemas/error' examples: generic: summary: Generic 'Not Found' error. description: >- Example response for a request to a resource that does not exist. value: name: RESOURCE_NOT_FOUND debug_id: b1d1f06c7246c message: The specified resource does not exist. 500_error_response: description: Internal Server Error. content: application/json: schema: $ref: '#/components/schemas/error' examples: generic: summary: Generic internal server error. description: >- Example response for a request that fails for reasons internal to the server. value: name: INTERNAL_SERVER_ERROR debug_id: b1d1f06c7246c message: An internal server error has occurred. default_response: description: Default response. content: application/json: schema: $ref: '#/components/schemas/error' examples: generic: summary: Default response. description: >- Example catch all response, should not be encountered in practice. value: name: INTERNAL_SERVER_ERROR debug_id: b1d1f06c7246c message: An internal server error has occurred. 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/payments/payment/authcapture: >- Permission to do non-real time payments like capture on authorization https://uri.paypal.com/services/payments/refund: Permission to initiate a refund on a capture transaction https://uri.paypal.com/services/payments/non-referenced-credit: Permission to initiate non referenced credit https://uri.paypal.com/services/payments/realtimepayment: >- Permission to do any real time payment, with support for sale/authorize/order intents https://uri.paypal.com/services/payments/reversepayment: Permission to do any reverse payment https://uri.paypal.com/services/payments/payments-ready: Permission to get information about payment readiness. Braintree:PaymentsReady: Permission to call PaymentsReady via BrainTree SDK. https://uri.paypal.com/services/payments/client-payments-eligibility: >- Permission to get information about merchant's eligible payment methods. ````