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.

Authorization

AuthorizationBearer <token>

FlowClient CredentialsToken URLhttps://api-m.sandbox.paypal.com/v1/oauth2/tokenInheader

Scopes

Permission to initiate a refund on a capture transactionhttps://uri.paypal.com/services/payments/refund

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

amountobject<money>Optional

The currency and amount for a financial transaction, such as a balance or payment due.

custom_idstringOptional

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.

Match^.*$Length1 <= length <= 127

invoice_idstringOptional

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

Match^.*$Length1 <= length <= 127

note_to_payerstringOptional

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.

Match^.*$Length1 <= length <= 255

payment_instructionobject<payment_instruction-2>Optional

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.

payment_instruction-2 properties

1 property

platform_feesobject<platform_fee>[]Optional

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.

Items0 <= length <= 1

Response Body

`application/json`

Callbacks

curl -X POST "https://example.com/v2/payments/captures/2GG279541U471931P/refund" \  -H "PayPal-Request-Id: 17e81d06-77ab-11e8-adc0-fa71639ebebc" \  -H "Prefer: return=representation" \  -H "Authorization: Bearer A21AAGHr9qtiRRXH4oYcQokQgV99rGqEIfgrr8xHCclP0OzmD9KVgg5ppIIg1jzJgQkV4wd02svIvBJyg6cLFJjFow_SjBhxQ" \  -H "PayPal-Auth-Assertion: eyJhbGciOiJub25lIn0.eyJlbWFpbCI6Im15QGVtYWlsLmNvbSJ9" \  -H "Content-Type: application/json" \  -d '{    "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"    }  ]}

Header Parameters

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

amountobject<money>Optional

The currency and amount for a financial transaction, such as a balance or payment due.

custom_idstringOptional

Match^.*$Length1 <= length <= 127

invoice_idstringOptional

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

Match^.*$Length1 <= length <= 127

note_to_payerstringOptional

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.

Match^.*$Length1 <= length <= 255

payment_instructionobject<payment_instruction-2>Optional

payment_instruction-2 properties

1 property

platform_feesobject<platform_fee>[]Optional

Items0 <= length <= 1

curl -X POST "https://example.com/v2/payments/captures/2GG279541U471931P/refund" \ -H "PayPal-Request-Id: 17e81d06-77ab-11e8-adc0-fa71639ebebc" \ -H "Prefer: return=representation" \ -H "Authorization: Bearer A21AAGHr9qtiRRXH4oYcQokQgV99rGqEIfgrr8xHCclP0OzmD9KVgg5ppIIg1jzJgQkV4wd02svIvBJyg6cLFJjFow_SjBhxQ" \ -H "PayPal-Auth-Assertion: eyJhbGciOiJub25lIn0.eyJlbWFpbCI6Im15QGVtYWlsLmNvbSJ9" \ -H "Content-Type: application/json" \ -d '{ "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" } ]}

money properties

payment_instruction-2 properties

platform_fee properties

money properties

payee_base properties

200application/json

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

500application/json

defaultapplication/json

capture_refundedPOSTcaptures/{$request.path.capture_id}/refunds

On this page

On this page

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

Refund captured payment

money properties

payment_instruction-2 properties

platform_fee properties

money properties

payee_base properties

200application/json

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

500application/json

defaultapplication/json

capture_refundedPOSTcaptures/{$request.path.capture_id}/refunds

On this page

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`