partners

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.

Headers

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:

base64-encoding-of-({"alg":"none"}).base64-encoding-of-({"iss":"<client_id","payer_id":"payer_id"})>.

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\":\"identity_seller@paypal.com\",\"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 https://api.sandbox.paypal.com/v1/payments/capture/3CB62566PT644045J/refund \
  -X POST \
  -H "Authorization: Bearer Access-Token" \
  -H "Content-Type: application/json"

Partially refund an order

Request Sample

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/captures/2GG279541U471931P/refund \
-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": "https://api.paypal.com/v1/payments/refunds/1JU08902781691411"
    },
    {
      "rel": "up",
      "method": "GET",
      "href": "https://api.paypal.com/v1/payments/captures/2GG279541U471931P"
    }
  ]
}

Additional information

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

Feedback