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 = "[email protected]";
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\":\"[email protected]\",\"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.

Headers

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

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

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 = "[email protected]";
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\":\"[email protected]\",\"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.

Issue a Refund

Headers

Modify the code

Fully refund an order

Partially refund an order

Response

Additional information

On this page

On this page

On this page

Issue a Refund

Headers

Modify the code

Fully refund an order

Partially refund an order

Response

Additional information

On this page

On this page

Issue a Refund

On this page

On this page

On this page

We currently use cookies to improve and customize your experience on our site. If you accept, we’ll also use marketing cookies to show you personalized ads. Manage your cookies and learn more.

Issue a Refund

On this page

On this page