> ## Documentation Index > Fetch the complete documentation index at: https://paypal-sb-staging.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Show refund details > Shows details for a refund, by ID. ## OpenAPI ````yaml api-reference/payments_payment_v2.json get /v2/payments/refunds/{refund_id} openapi: 3.0.3 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.9' contact: {} servers: - url: https://api-m.sandbox.paypal.com description: PayPal Sandbox Environment - url: https://api-m.paypal.com description: PayPal Live Environment security: [] tags: - name: authorizations description: >- Use the `/authorizations` resource to show details for, capture payment for, reauthorize, and void authorized payments. - name: captures description: >- Use the `/captures` resource to show details for and refund a captured payment. - name: refunds description: Use the `/refunds` resource to show refund details. - name: assets description: Assets APIs for Checkout - 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: 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: find-bin-details description: >- Use the `/find-bin-details` resource to determine PayPal supported networks and retrieve BIN details for given card and payee. externalDocs: url: https://developer.paypal.com/docs/api/payments/v2/ paths: /v2/payments/refunds/{refund_id}: get: tags: - refunds summary: Show refund details description: Shows details for a refund, by ID. operationId: refunds.get parameters: - $ref: '#/components/parameters/refund_id' - $ref: '#/components/parameters/paypal_auth_assertion' 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' '401': description: >- Authentication failed due to missing authorization header, or invalid authentication credentials. content: application/json: schema: allOf: - $ref: '#/components/schemas/error_401' - $ref: '#/components/schemas/401' '403': description: The request failed because the caller has insufficient permissions. content: application/json: schema: allOf: - $ref: '#/components/schemas/error_403' - $ref: '#/components/schemas/403' '404': description: The request failed because the resource does not exist. content: application/json: schema: allOf: - $ref: '#/components/schemas/error_404' - $ref: '#/components/schemas/404' '500': description: The request failed because an internal server error occurred. default: $ref: '#/components/responses/default' security: - Oauth2: - https://uri.paypal.com/services/payments/refund components: parameters: refund_id: name: refund_id in: path description: The PayPal-generated ID for the refund for which to show details. required: true schema: type: string 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](/docs/api/reference/api-requests/#paypal-auth-assertion).
Note:For three party transactions in which a partner is managing the API calls on behalf of a merchant, the partner must identify the merchant using either a PayPal-Auth-Assertion header or an access token with target_subject.
required: false schema: type: string schemas: '401': properties: details: type: array items: anyOf: - title: INVALID_ACCOUNT_STATUS properties: issue: type: string enum: - INVALID_ACCOUNT_STATUS description: type: string enum: - Account validations failed for the user. '403': properties: details: type: array items: anyOf: - title: PERMISSION_DENIED properties: issue: type: string enum: - PERMISSION_DENIED description: type: string enum: - >- You do not have permission to access or perform operations on this resource. '404': properties: details: type: array items: anyOf: - title: INVALID_RESOURCE_ID properties: issue: type: string enum: - INVALID_RESOURCE_ID description: type: string enum: - >- Specified resource ID does not exist. Please check the resource ID and try again. refund: type: object title: Refund description: The refund information. allOf: - $ref: '#/components/schemas/refund_status' - properties: id: description: The PayPal-generated ID for the refund. type: string readOnly: true amount: $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 readOnly: true custom_id: type: string description: >- The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports. minLength: 1 maxLength: 255 pattern: ^[A-Za-z0-9-_.,]*$ acquirer_reference_number: type: string description: >- Reference ID issued for the card transaction. This ID can be used to track the transaction across processors, card brands and issuing banks. 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 readOnly: true seller_payable_breakdown: $ref: '#/components/schemas/seller_payable_breakdown' payer: $ref: '#/components/schemas/payee_base' description: The details associated with the merchant for this transaction. readOnly: true links: $ref: '#/components/schemas/link_description_list' - $ref: '#/components/schemas/activity_timestamps' error_401: type: object title: Unauthorized Error description: >- Authentication failed due to missing Authorization header, or invalid authentication credentials. properties: name: type: string enum: - AUTHENTICATION_FAILURE message: type: string enum: - >- Authentication failed due to missing authorization header, or invalid authentication credentials. details: type: array items: $ref: '#/components/schemas/error_details' debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. links: description: >- An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS). type: array minItems: 0 maxItems: 10000 items: $ref: '#/components/schemas/error_link_description' error_403: type: object title: Not Authorized Error description: >- The client is not authorized to access this resource, although it may have valid credentials. properties: name: type: string enum: - NOT_AUTHORIZED message: type: string enum: - Authorization failed due to insufficient permissions. details: type: array items: $ref: '#/components/schemas/error_details' debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. links: description: >- An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS). type: array minItems: 0 maxItems: 10000 items: $ref: '#/components/schemas/error_link_description' error_404: type: object title: Not found Error description: >- The server has not found anything matching the request URI. This either means that the URI is incorrect or the resource is not available. properties: name: type: string enum: - RESOURCE_NOT_FOUND message: type: string enum: - The specified resource does not exist. details: type: array items: $ref: '#/components/schemas/error_details' debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. links: description: >- An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS). type: array minItems: 0 maxItems: 10000 items: $ref: '#/components/schemas/error_link_description' refund_status: type: object description: The refund status with details. title: Refund Status With Details properties: status: title: Refund Status With Details description: The status of the refund. type: string x-enumDescriptions: - value: CANCELLED description: The refund was cancelled. - value: FAILED description: The refund could not be processed. - value: PENDING description: >- The refund is pending. For more information, see status_details.reason. - value: COMPLETED description: >- The funds for this transaction were debited to the customer's account. readOnly: true enum: - CANCELLED - FAILED - PENDING - COMPLETED status_details: $ref: '#/components/schemas/refund_status_details' description: The details of the refund status. readOnly: true 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 seller_payable_breakdown: description: The breakdown of the refund. type: object title: Seller Payable Breakdown properties: gross_amount: $ref: '#/components/schemas/money' description: The amount that the payee refunded to the payer. readOnly: true paypal_fee: $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: $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: $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: $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: $ref: '#/components/schemas/refund_definitions-platform_fee_list' net_amount_breakdown: $ref: '#/components/schemas/net_amount_breakdown_item_list' total_refunded_amount: $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. readOnly: true payee_base: type: object 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. properties: email_address: $ref: '#/components/schemas/email' description: The email address of merchant. merchant_id: $ref: '#/components/schemas/account_id' description: The encrypted PayPal account ID of the merchant. link_description_list: description: >- An array of related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). type: array readOnly: true items: $ref: '#/components/schemas/link_description' activity_timestamps: type: object description: >- The date and time stamps that are common to authorized payment, captured payment, and refund transactions. title: Transaction Date and Time Stamps properties: create_time: $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: $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 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: $ref: '#/components/schemas/error_location' issue: type: string description: The unique, fine-grained application-level error code. 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 error_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: 20000 pattern: ^.*$ 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: 100 pattern: ^.*$ method: description: The HTTP method required to make the related call. type: string minLength: 3 maxLength: 6 pattern: ^[A-Z]*$ enum: - GET - POST - PUT - DELETE - PATCH error_default: description: The default error response. oneOf: - $ref: '#/components/schemas/error_400' - $ref: '#/components/schemas/error_401' - $ref: '#/components/schemas/error_403' - $ref: '#/components/schemas/error_404' - $ref: '#/components/schemas/error_409' - $ref: '#/components/schemas/error_415' - $ref: '#/components/schemas/error_422' - $ref: '#/components/schemas/error_429' - $ref: '#/components/schemas/error_500' - $ref: '#/components/schemas/error_503' 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 x-enumDescriptions: - value: ECHECK description: >- The customer's account is funded through an eCheck, which has not yet cleared. enum: - ECHECK 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 x-security-classification: data_class: class4 data_category: INTRINSIC refund_definitions-platform_fee_list: type: array description: >- An array of platform or partner fees, commissions, or brokerage fees for the refund. minItems: 0 maxItems: 1 items: $ref: '#/components/schemas/platform_fee' net_amount_breakdown_item_list: type: array 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. items: $ref: '#/components/schemas/net_amount_breakdown_item' readOnly: true email: type: string 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.
format: merchant_common_email_address_v2 maxLength: 254 minLength: 3 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: type: string title: PayPal Account Identifier description: The account identifier for a PayPal account. format: ppaas_payer_id_v3 minLength: 13 maxLength: 13 pattern: ^[2-9A-HJ-NP-Z]{13}$ 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 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. 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})$ error_location: type: string description: >- The location of the field that caused the error. Value is `body`, `path`, or `query`. enum: - body - path - query default: body error_400: type: object title: Bad Request Error description: Request is not well-formed, syntactically incorrect, or violates schema. properties: name: type: string enum: - INVALID_REQUEST message: type: string enum: - >- Request is not well-formed, syntactically incorrect, or violates schema. details: type: array items: $ref: '#/components/schemas/error_details' debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. links: description: >- An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS). type: array minItems: 0 maxItems: 10000 items: $ref: '#/components/schemas/error_link_description' error_409: type: object title: Resource Conflict Error description: The server has detected a conflict while processing this request. properties: name: type: string enum: - RESOURCE_CONFLICT message: type: string enum: - The server has detected a conflict while processing this request. details: type: array items: $ref: '#/components/schemas/error_details' debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. links: description: >- An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS). type: array minItems: 0 maxItems: 10000 items: $ref: '#/components/schemas/error_link_description' error_415: type: object title: Unsupported Media Type Error description: The server does not support the request payload's media type. properties: name: type: string enum: - UNSUPPORTED_MEDIA_TYPE message: type: string enum: - The server does not support the request payload's media type. details: type: array items: $ref: '#/components/schemas/error_details' debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. links: description: >- An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS). type: array minItems: 0 maxItems: 10000 items: $ref: '#/components/schemas/error_link_description' error_422: type: object title: Unprocessable Entity Error description: >- The requested action cannot be performed and may require interaction with APIs or processes outside of the current request. This is distinct from a 500 response in that there are no systemic problems limiting the API from performing the request. properties: name: type: string enum: - UNPROCESSABLE_ENTITY message: type: string enum: - >- The requested action could not be performed, semantically incorrect, or failed business validation. details: type: array items: $ref: '#/components/schemas/error_details' debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. links: description: >- An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS). type: array minItems: 0 maxItems: 10000 items: $ref: '#/components/schemas/error_link_description' error_429: type: object title: Too many requests description: Too many requests. Blocked due to rate limiting. properties: name: type: string enum: - RATE_LIMIT_REACHED message: type: string enum: - Too many requests. Blocked due to rate limiting. debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. error_500: type: object title: Internal Server Error description: >- This is either a system or application error, and generally indicates that although the client appeared to provide a correct request, something unexpected has gone wrong on the server. properties: name: type: string enum: - INTERNAL_SERVER_ERROR message: type: string enum: - An internal server error occurred. debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. links: description: >- An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS). type: array minItems: 0 maxItems: 10000 items: $ref: '#/components/schemas/error_link_description' example: name: INTERNAL_SERVER_ERROR message: An internal server error occurred. debug_id: 90957fca61718 links: - href: >- https://developer.paypal.com/api/orders/v2/#error-INTERNAL_SERVER_ERROR rel: information_link error_503: type: object title: Service Unavailable Error description: >- The server is temporarily unable to handle the request, for example, because of planned maintenance or downtime. properties: name: type: string enum: - SERVICE_UNAVAILABLE message: type: string enum: - Service Unavailable. debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. links: description: >- An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS). type: array minItems: 0 maxItems: 10000 items: $ref: '#/components/schemas/error_link_description' example: name: SERVICE_UNAVAILABLE message: Service Unavailable. debug_id: 90957fca61718 information_link: >- https://developer.paypal.com/docs/api/orders/v2/#error-SERVICE_UNAVAILABLE platform_fee: type: object 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. properties: amount: $ref: '#/components/schemas/money' description: The fee for this transaction. payee: $ref: '#/components/schemas/payee_base' description: >- The recipient of the fee for this transaction. If you omit this value, the default is the API caller. required: - amount net_amount_breakdown_item: type: object title: Net Amount Breakdown Item 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. properties: payable_amount: $ref: '#/components/schemas/money' description: The net amount debited from the merchant's PayPal account. readOnly: true converted_amount: $ref: '#/components/schemas/money' description: The converted payable amount. readOnly: true exchange_rate: $ref: '#/components/schemas/exchange_rate' description: >- The exchange rate that determines the amount that was debited from the merchant's PayPal account. readOnly: true exchange_rate: description: >- The exchange rate that determines the amount to convert from one currency to another currency. type: object title: Exchange Rate properties: source_currency: $ref: '#/components/schemas/currency_code' description: The source currency from which to convert an amount. target_currency: $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 readOnly: true responses: default: description: The default response. content: application/json: schema: $ref: '#/components/schemas/error_default' securitySchemes: Oauth2: type: oauth2 description: OAuth 2.0 authentication flows: clientCredentials: tokenUrl: /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. ````