Refund payments
Last updated: Aug 15th, 7:37am
A sale is a completed PayPal payment.
A captured payment is an authorized and captured PayPal payment.
You can refund sales and captured payments.
Integration steps
Important: You cannot run the following sample requests as-is. Replace all call-specific parameter values, such as tokens and IDs, with your own values.
| Step | Required | Description |
|---|---|---|
| 1. | Required | Set up your development environment. |
| 2. | Optional | Either fully refund a sale or partially refund a sale. |
| 3. | Optional | Fully or partially refund a captured payment. |
Set up your development environment
Before you can integrate Payments, you must set up your development environment. After you get a token that lets you access protected REST API resources, you create sandbox accounts to test your web and mobile apps. For details, see Get started.
Then, return to this page to integrate Payments.
Fully refund a sale
For a full refund, include the sale ID of the completed payment in the URI and include an empty JSON request body.
This example requests a full refund:
1curl -v https://api-m.sandbox.paypal.com/v1/payments/sale/67D22837NN7279935/refund \2 -H "Content-Type: application/json" \3 -H "Authorization: Bearer <Access-Token>" \4 -d '{}'
The response shows the refund details, indicates that the refund is complete, and includes request-related HATEOAS links:
1{2 "id": "1JU08902781691411",3 "status": "COMPLETED",4 "links": [5 {6 "rel": "self",7 "method": "GET",8 "href": "https://api-m.paypal.com/v1/payments/refunds/1JU08902781691411"9 },10 {11 "rel": "up",12 "method": "GET",13 "href": "https://api-m.paypal.com/v1/payments/captures/2GG279541U471931P"14 }15 ]16}
Partially refund a sale
For a partial refund, include an amount object in the JSON request body.
This example partially refunds a sale:
1curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/sale/2MU78835H4515710F/refund \2 -H "Content-Type: application/json" \3 -H "Authorization: Bearer <Access-Token>" \4 -d '{5 "amount": {6 "total": "10.99",7 "currency": "USD"8 },9 "invoice_number": "INVOICE-123",10 "description": "Defective product"11}'
The response shows the refund details:
1{2 "id": "2MU78835H4515710F",3 "status": "COMPLETED",4 "links": [5 {6 "rel": "self",7 "method": "GET",8 "href": "https://api-m.paypal.com/v1/payments/refunds/2MU78835H4515710F"9 },10 {11 "rel": "up",12 "method": "GET",13 "href": "https://api-m.paypal.com/v1/payments/captures/2GG279541U471931P"14 }15 ]16}
Refund a captured payment
To refund a captured payment, include the ID of the captured payment in the URI and an amount object in the JSON request body. You must include the amount object for both full and partial refunds:
1curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/capture/2MU78835H4515710F/refund \2 -H "Content-Type: application/json" \3 -H "Authorization: Bearer <Access-Token>" \4 -d '{5 "amount": {6 "currency": "USD",7 "total": "110.54"8 }9}'
The response shows the refund details:
1{2 "id": "0P209507D6694645N",3 "create_time": "2017-05-06T22:11:51Z",4 "update_time": "2017-05-06T22:11:51Z",5 "state": "completed",6 "amount": {7 "total": "110.54",8 "currency": "USD"9 },10 "capture_id": "8F148933LY9388354",11 "parent_payment": "PAY-8PT597110X687430LKGECATA",12 "invoice_number": "INV-1234567",13 "links": [{14 "href": "https://api-m.sandbox.paypal.com/v1/payments/refund/0P209507D6694645N",15 "rel": "self",16 "method": "GET"17 }, {18 "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-8PT597110X687430LKGECATA",19 "rel": "parent_payment",20 "method": "GET"21 }, {22 "href": "https://api-m.sandbox.paypal.com/v1/payments/capture/8F148933LY9388354",23 "rel": "capture",24 "method": "GET"25 }]26}
Next
You can show refund details.
Also, learn how to use the Payment Experience API to create web experience profiles to customize payment flow experiences.