Issue a Refund

You can refund a captured payment by ID using /v1/payments/capture/{capture_id}/refund. 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.


Pass the standard Content-Type and Authorization request headers along with the PayPal-Request-Id.

In live, pass the PayPal-Auth-Assertion header.

For first-party calls, the value is:


Note: The previous example contains two period (.) characters, which are required. The payer_id is the seller's payer ID.

To generate the value for the PayPal-Auth-Assertion request header, use the following function:

import org.apache.commons.codec.binary.Base64;
public class Base64Encode {
  public static void main(String[] args)
    String header = "{\"alg\":\"none\"}";
    String payload = "{\"email\":\"\",\"iss\":\"Acuy17p2LcOf9RMv8SUVBb3wic3FPEP2NHFFqfSCBRFrNFdmbC1JQ0w8HIKRxW3RDy2R8QTL93eptFYl\"}";
    //iss is the client id of the actor and email is the email id of the subject
    byte[] encodedBytes = Base64.encodeBase64(header.getBytes());
    System.out.println("Header encoded " + new String(encodedBytes));
    byte[] encodedBytesPayload = Base64.encodeBase64(payload.getBytes());
    System.out.println("Payload encoded " + new String(encodedBytesPayload));
    System.out.println("Paypal-Auth-Assertion=" + new String(encodedBytes) + "." + new String(encodedBytesPayload) + ".");

Fully refund an order

Request sample

curl -v \
  -X POST \
  -H "Authorization: Bearer Access-Token" \
  -H "Content-Type: application/json"

Partially refund an order

Request Sample

curl -v -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <var>Access-Token</var>" \
-H "PayPal-Request-Id: 123e4567-e89b-12d3-a456-426655440020" \
-d '{
  "amount": {
    "value": "10.99",
    "currency_code": "USD"
  "invoice_id": "INVOICE-123",
  "note_to_payer": "Defective product"

Refund response

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

  "id": "1JU08902781691411",
  "status": "COMPLETED",
  "links": [
      "rel": "self",
      "method": "GET",
      "href": ""
      "rel": "up",
      "method": "GET",
      "href": ""

Additional information

For more information about the refunds API, see PayPal's Payment API's refund resource.