Refund Payments

APICURRENT

Last updated: Sept 19th, 3:28am

With Payments v2, you can refund a captured payment to the customer. You can:

Perform a full refund of captured payment.

Perform multiple partial refunds up to the total captured payment.

Include a note to the customer for reference.

Know before you code

The Payments API must be used with the Orders v2 API.

See the Orders v2 API reference documentation to learn more about Orders.

See the Payments v2 API reference documentation to learn more about Payments.

Complete the steps in Get Started to setup your developer environment.

Use Postman to explore and test PayPal APIs.

If you are a partner acting on behalf of merchants on your platform, you'll need to include the PayPal-Auth-Assertion header in your API request. You can generate the value according to the following pseudocode. See REST Requests for more information. You'll need to be an approved partner and complete seller onboarding.

1<base64-encoding <span class="hljs-keyword">of</span>-({<span class="hljs-string">"alg"</span>:<span class="hljs-string">"none"</span>})>.<base64-encoding-<span class="hljs-keyword">of</span>-({<span class="hljs-string">"iss"</span>:<span class="hljs-string">"<var>client_id</var>"</span>,<span class="hljs-string">"payer_id"</span>:<span class="hljs-string">"<var>payer_id</var>"</span>})>.

To issue a refund, the order has to be created, approved, authorized, and captured.

Refund a payment

To refund a payment, call the "Refund Captured Payment" API at /v2/payments/captures/{capture_id}/refund.

Sample API request

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/payments/captures/32G741949K374372X/refund -H "Content-Type: application/json" -H "Authorization: Bearer Access-Token" -H "PayPal-Request-Id: 123e4567-e89b-12d3-a456-426655440018" -d '{
2    "amount": {
3        "value": "200",
4        "currency_code": "USD"
5    },
6    "invoice_id": "1660844025",
7    "note_to_payer": "Defective product"
8}'

Modify the code

Set the Access Token to the one you used when you captured the order.

Change PayPal-Request-Id to a unique value, such as GUID, for each order to ensure idempotency.

Update capture_id to the id obtained from a successful capture call.

Update the value to the appropriate amount.

API response

You will get an HTTP 201 Created response. Note the refund id in the response body, which you may use to look up refund details. Refund status will be set to COMPLETED to indicate completion of the refund request.

Note: If you did not receive the response, making the same API call without changing anything will result in an HTTP 200 OK with confirmation of refund.

Sample API response

1{
2    "id": "80741007T74628258",
3    "amount": {
4        "currency_code": "USD",
5        "value": "200.00"
6    },
7    "note_to_payer": "Defective product",
8    "seller_payable_breakdown": {
9        "gross_amount": {
10            "currency_code": "USD",
11            "value": "200.00"
12        },
13        "paypal_fee": {
14            "currency_code": "USD",
15            "value": "0.00"
16        },
17        "net_amount": {
18            "currency_code": "USD",
19            "value": "200.00"
20        },
21        "total_refunded_amount": {
22            "currency_code": "USD",
23            "value": "200.00"
24        }
25    },
26    "invoice_id": "1660844025",
27    "status": "COMPLETED",
28    "create_time": "2022-08-18T11:46:32-07:00",
29    "update_time": "2022-08-18T11:46:32-07:00",
30    "links": [
31        {
32            "href": "https://api-m.sandbox.paypal.com/v2/payments/refunds/80741007T74628258",
33            "rel": "self",
34            "method": "GET"
35        },
36        {
37            "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/1UJ76552X4188552E",
38            "rel": "up",
39            "method": "GET"
40        }
41    ]
42}