Skip to main content
POST
/
v2
/
payments
/
captures
/
{capture_id}
/
refund
curl --request POST \
  --url https://api-m.paypal.com/v2/payments/captures/{capture_id}/refund \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": {
    "value": "1.00",
    "currency_code": "USD"
  },
  "invoice_id": "RefundInvoice-123",
  "custom_id": "RefundCustom-123"
}
'
{
  "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"
    }
  ]
}

Authorizations

​
Authorization
string
header
required

OAuth 2.0 authentication

Headers

​
PayPal-Request-Id
string

A unique ID identifying the request header for idempotency purposes.

Required string length: 1 - 10000
Pattern: ^.*$
​
Prefer
string
default:return=minimal

The preferred server response upon successful completion of the request. Value is:

  • return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.
  • return=representation. The server returns a complete resource representation, including the current state of the resource.

Maximum string length: 2147483647
Pattern: ^[\S\s]*$
​
Authorization
string

Holds authorization information for external API calls. 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.

Required string length: 1 - 16000
Pattern: ^.*$
​
PayPal-Auth-Assertion
string

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 string length: 1 - 10000
Pattern: ^.*$

Path Parameters

​
capture_id
string
required

The PayPal-generated ID for the captured payment to refund.

Maximum string length: 2147483647
Pattern: ^[\S\s]*$

Body

application/json

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.

​
amount
Money · object

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
string

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.

Required string length: 1 - 127
Pattern: ^.*$
​
invoice_id
string

The API caller-provided external invoice ID for this order. The pattern is defined by an external party and supports Unicode.

Required string length: 1 - 127
Pattern: ^.*$
​
note_to_payer
string

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.

Required string length: 1 - 255
Pattern: ^.*$
​
payment_instruction
payment_instruction · object

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.

Callbacks

POST
captures/{$request.path.capture_id}/refundscapture_refunded

Body

application/json

Webhook event notification for capture refunded.

​
id
string

The ID of the webhook event notification.

Required string length: 1 - 255
Pattern: ^.*$
​
event_version
string

The version of the event.

Required string length: 1 - 50
Pattern: ^.*$
​
create_time
string

The date and time when the webhook event notification was created.

Required string length: 20 - 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})$
​
resource_type
string

The name of the resource related to the webhook notification event.

Required string length: 1 - 100
Pattern: ^.*$
​
resource_version
string

The version of the resource.

Required string length: 1 - 50
Pattern: ^.*$
​
event_type
enum<string>

The event that triggered the webhook event notification.

Available options:
PAYMENT.CAPTURE.REFUNDED
​
summary
string

A summary description for the event notification.

Required string length: 1 - 500
Pattern: ^.*$
​
resource
refund · object

The refund information.

​
links
Link Description · object[]

An array of request-related HATEOAS links.

Required array length: 1 - 10 elements

Response

Your server implementation should return this HTTP status code if the data was received successfully.

Response

A successful request returns the HTTP 200 OK status code and a JSON response body that shows refund details.

The refund information.

​
status
enum<string>
read-only

The status of the refund.

Available options:
CANCELLED,
FAILED,
PENDING,
COMPLETED
​
status_details
refund_status_details · object

The details of the refund status.

​
id
string
read-only

The PayPal-generated ID for the refund.

Maximum string length: 2147483647
Pattern: ^[\S\s]*$
​
amount
Money · object

The amount that the payee refunded to the payer.

​
invoice_id
string
read-only

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.

Maximum string length: 2147483647
Pattern: ^[\S\s]*$
​
custom_id
string

The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports.

Required string length: 1 - 255
Pattern: ^[A-Za-z0-9-_.,]*$
​
acquirer_reference_number
string

Reference ID issued for the card transaction. This ID can be used to track the transaction across processors, card brands and issuing banks.

Required string length: 1 - 36
Pattern: ^[a-zA-Z0-9]+$
​
note_to_payer
string
read-only

The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives.

Maximum string length: 2147483647
Pattern: ^[\S\s]*$
​
seller_payable_breakdown
Seller Payable Breakdown · object
read-only

The breakdown of the refund.

​
payer
payee_base · object

The details associated with the merchant for this transaction.

​
buyer_context
Buyer Context · object

The buyer context for the refund transaction.

​
links
link_description · object[]
read-only

An array of related HATEOAS links.

Maximum array length: 32767
​
create_time
string

The date and time when the transaction occurred, in Internet date and time format.

Required string length: 20 - 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})$
​
update_time
string

The date and time when the transaction was last updated, in Internet date and time format.

Required string length: 20 - 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})$