Issue a Refund

Refund a captured payment, by ID using /v2/payments/captures/{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.

Pass the PayPal-Auth-Assertion header with the standard Content-Type, Authorization, and PayPal-Request-ID headers. The value of the PayPal-Auth-Assertion header can be generated as follows:

const clientId = "CLIENT-ID";
const sellerPayerId = "SELLER=PAYER=ID"
const jwt = getAuthAssertionValue(clientId, sellerPayerId);
console.log(jwt);
function getAuthAssertionValue(clientId, sellerPayerId) {
    const header = {
        "alg": "none"
    };
    const encodedHeader = base64url(header);
    const payload = {
        "iss": clientId,
        "payer_id": sellerPayerId
    };
    const encodedPayload = base64url(payload);
    return `${encodedHeader}.${encodedPayload}.`;
}
function base64url(json) {
    return btoa(JSON.stringify(json))
        .replace(/=+$/, '')
        .replace(/\+/g, '-')
        .replace(/\//g, '_');
}

Note: This example contains two period (.) characters, which are required.

Modify the code

• Use the client ID of the platform or marketplace from the PayPal Developer dashboard for clientID.
• The sellerPayerId is the payer ID of the reciving seller's PayPal account. You can also use email instead of payer_id and supply the email address of the seller's PayPal account.

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

Node.js

const clientID = "Acuy17p2LcOf9RMv8SUVBb3wic3FPEP2NHFFqfSCBRFrNFdmbC1JQ0w8HIKRxW3RDy2R8QTL93eptFYl";
const merchantIDOrEmail = "identity_seller@paypal.com";
const auth1 = Buffer.from('\{"alg":"none"\}').toString(\"base64\");
const auth2 = Buffer.from(
  \`\{\"iss\":$\{clientID\},\"payer_id\":$\{merchantIDOrEmail\}\}\`
).toString(\"base64\");
const authAssertionHeader = \`$\{auth1\}.$\{auth2\}.\`;

Java

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

curl -v -X POST https://api-m.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" \
-d '{}

Partially refund an order

curl -v -X POST https://api-m.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" \
-d '{
  "amount": {
    "value": "10.99",
    "currency_code": "USD"
  },
  "invoice_id": "INVOICE-123",
  "note_to_payer": "Defective product"
}'

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-m.paypal.com/v2/payments/refunds/1JU08902781691411"
    },
    {
      "rel": "up",
      "method": "GET",
      "href": "https://api-m.paypal.com/v2/payments/captures/2GG279541U471931P"
    }
  ]
}

Additional information

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