Multiparty Payments / Accept Payments / Issue Refund

Issue a refund

APICurrentLast updated: March 31st 2023, @ 9:55:03 am


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

Know before you code

Required

To use this integration you must:

Run in Postman

1. Generate 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

Copy the code and modify it as follows:

  • 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 = "CLIENT-ID";
2const merchantIDOrEmail = "identity_seller@paypal.com";
3const auth1 = Buffer.from('{"alg":"none"}').toString("base64");
4const auth2 = Buffer.from(`{"iss":${clientID},"payer_id":${merchantIDOrEmail}}`).toString("base64");
5const authAssertionHeader = `${auth1}.${auth2}.`;

Java

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

2. Make refund request

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

Modify the code

Copy the code and modify it as follows:

  • Replace ACCESS-TOKEN with your access token.
  • Replace YOUR-PAYPAL-REQUEST-ID with your PayPal request ID.
  • Replace PAYPAL-AUTH-ASSERTION with your PayPal auth assertion generated from Step 1.

Fully refund an order

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

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: YOUR-PAYPAL-REQUEST-ID" 
5  -H "PayPal-Auth-Assertion: PAYPAL-AUTH-ASSERTION" 
6  -d '{}'

Partially refund an order

For a partial refund, include an amount object in the JSON request body. You can also issue multiple partial refunds up to the total captured amount. If you are unsure how much captured amount is remaining to be refunded after one or more partial refunds, make the API call with the total captured amount or leave the amount field blank. The API will automatically calculate and issue the refund for the remaining value.

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: YOUR-PAYPAL-REQUEST-ID" 
5-H "PayPal-Auth-Assertion: PAYPAL-AUTH-ASSERTION" 
6-d '{
7  "amount": {
8    "value": "10.99",
9    "currency_code": "USD"
10  }
11}'

Step result

A successful request returns the HTTP 201 Created status code. If you didn't receive a response, making the same API call without changing the request should result in an HTTP 200 OK with a confirmation of the refund.

Next steps

Optional
Refund Resource

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

Recommended
Integration Checklist

Go through the integration checklist before you go live.

ReferencePayPal.comPrivacyCookiesSupportLegalContact