Issue a Refund

Refund a captured payment from a seller back to a buyer.

Integration Steps

  1. Generate PayPal-Auth-Assertion header.
  2. Make a refund request.

1. Generate PayPal-Auth-Assertion header

In addition to the standard Content-Type, Authorization, and PayPal-Request-Id headers, you will need to pass the PayPal-Auth-Assertion header. The value of the PayPal-Auth-Assertion header can be generated according to the following pseudocode:

<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 client_id is your client ID. The payer_id is the payer_id of the seller's PayPal account on which you're performing a refund. In place of payer_id, you can also use email where the value is the email address of the seller's PayPal account on which you're performing a refund.

Example functions to generate the PayPal-Auth-Assertion header:

var auth_1 = btoa("{\"alg\":\"none\"}");
var auth_2 = btoa("{\"email\":identity_seller@paypal.com,\"iss\":Acuy17p2LcOf9RMv8SUVBb3wic3FPEP2NHFFqfSCBRFrNFdmbC1JQ0w8HIKRxW3RDy2R8QTL93eptFYl}");
var auth_assertion_header = auth_1 + "." + auth_2 + ".";
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) + ".");
  }
}

2. Make a refund request

To refund an order, use the /v2/payments/captures/{capture_id}/refund endpoint. capture_id can be read from the purchase_units/payments/captures/id field of the order you want to refund.

Fully refund an order

For a full refund, include an empty payload in the JSON request body.

curl -v -X POST https://api.sandbox.paypal.com/v2/payments/captures/2GG279541U471931P/refund \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-H "PayPal-Request-Id: 123e4567-e89b-12d3-a456-426655440020" \
-H "PayPal-Auth-Assertion: eyJhbGciOiJub25lIn0.eyJpc3MiOiJjbGllbnRfaWQiLCJlbWFpbCI6Im15LWVtYWlsQGV4YW1wbGUuY29tIn0." \
-d '{}

Partially refund an order

For a partial refund, include an amount object in the JSON request body.

curl -v -X POST https://api.sandbox.paypal.com/v2/payments/captures/2GG279541U471931P/refund \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-H "PayPal-Request-Id: 123e4567-e89b-12d3-a456-426655440020" \
-H "PayPal-Auth-Assertion: eyJhbGciOiJub25lIn0.eyJpc3MiOiJjbGllbnRfaWQiLCJlbWFpbCI6Im15LWVtYWlsQGV4YW1wbGUuY29tIn0." \
-d '{
  "amount": {
    "value": "10.99",
    "currency_code": "USD"
  }
}'

Response

A successful request returns the HTTP 201 Created status code.

Additional information

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

Feedback