Issue a Refund

Docs

Last updated: Sept 24th, 3:58pm

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:

1const clientId = "CLIENT-ID";
2const sellerPayerId = "SELLER=PAYER=ID"
3const jwt = getAuthAssertionValue(clientId, sellerPayerId);
4console.log(jwt);
5function getAuthAssertionValue(clientId, sellerPayerId) {
6    const header = {
7        "alg": "none"
8    };
9    const encodedHeader = base64url(header);
10    const payload = {
11        "iss": clientId,
12        "payer_id": sellerPayerId
13    };
14    const encodedPayload = base64url(payload);
15    return `${encodedHeader}.${encodedPayload}.`;
16}
17function base64url(json) {
18    return btoa(JSON.stringify(json))
19        .replace(/=+$/, '')
20        .replace(/\+/g, '-')
21        .replace(/\//g, '_');
22}

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

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

Java

1import org.apache.commons.codec.binary.Base64;
2public class Base64Encode \{
3  public static void main(String[] args)
4  \{
5    String header = \"\{\"alg\":\"none\"}\";
6    String payload = "\{\"email\":\"identity_seller@paypal.com\",\"iss\":\"Acuy17p2LcOf9RMv8SUVBb3wic3FPEP2NHFFqfSCBRFrNFdmbC1JQ0w8HIKRxW3RDy2R8QTL93eptFYl\"\}";
7    //iss is the client id of the actor and email is the email id of the subject
8    byte[] encodedBytes = Base64.encodeBase64(header.getBytes());
9    System.out.println(\"Header encoded \" + new String(encodedBytes));
10    byte[] encodedBytesPayload = Base64.encodeBase64(payload.getBytes());
11    System.out.println(\"Payload encoded \" + new String(encodedBytesPayload));
12    System.out.println(\"Paypal-Auth-Assertion=\" + new String(encodedBytes) + \".\" + new String(encodedBytesPayload) + \".\");
13  \}
14\}

Fully refund an order

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

Partially refund an order

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/payments/captures/2GG279541U471931P/refund \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer Access-Token" \
4-H "PayPal-Request-Id: 123e4567-e89b-12d3-a456-426655440020" \
5-d '{
6  "amount": {
7    "value": "10.99",
8    "currency_code": "USD"
9  },
10  "invoice_id": "INVOICE-123",
11  "note_to_payer": "Defective product"
12}'

Response

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

1{
2  "id": "1JU08902781691411",
3  "status": "COMPLETED",
4  "links": [
5    {
6      "rel": "self",
7      "method": "GET",
8      "href": "https://api-m.paypal.com/v2/payments/refunds/1JU08902781691411"
9    },
10    {
11      "rel": "up",
12      "method": "GET",
13      "href": "https://api-m.paypal.com/v2/payments/captures/2GG279541U471931P"
14    }
15  ]
16}

Additional information

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