Issue a refund

Docs

Last updated: Aug 15th, 7:13am

Refund a captured payment by ID calling the /v2/payments/captures/CAPTURE-ID/refund endpoint.

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

In a live environment, 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 order

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

Sample request

1{
2curl -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: "BN-CODE" -d '{}

Partially refund order

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

Sample request

1{
2curl -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: BN-CODE" -d '{
3  "amount": {
4    "value": "10.99",
5    "currency_code": "USD"
6  },
7  "invoice_id": "INVOICE-123",
8  "note_to_payer": "Defective product"
9}'

Sample response

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

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

Reference

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