Issue a refund
Last updated: Oct 30th, 1:44pm
Refund a captured payment from a seller back to a buyer.
Know before you code
To use this integration you must:
- Contact us to be an approved partner.
- Onboard merchants before you begin this integration.
- Inform your merchants of PayPal's Seller Protection policy, so they are aware of use cases that invalidate that protection, such as shipping to an address other than the one in the transaction confirmation.
Generate PayPal Auth Assertion header
Pass the PayPal-Auth-Assertion and the PayPal-Partner-Attribution-Id headers with the standard Content-Type
, Authorization
, and PayPal-Request-ID
headers. In client-side JavaScript, the value of the PayPal-Auth-Assertion
header can be generated as follows:
1// client-side JavaScript234function encodeObjectToBase64(object) {5 const objectString = JSON.stringify(object);6 return window.btoa(objectString);7}8910const clientId = "CLIENT-ID";11const sellerPayerId = "SELLER-PAYER-ID"; // preferred12// const sellerEmail = "SELLER-ACCOUNT-EMAIL"; // use instead of payer-id if required131415const header = {16 alg: "none"17};18const encodedHeader = encodeObjectToBase64(header);192021const payload = {22 iss: clientId,23 payer_id: sellerPayerId24 // email: sellerEmail25};26const encodedPayload = encodeObjectToBase64(payload);272829const jwt = `${encodedHeader}.${encodedPayload}.`; // json web token30console.log(`Paypal-Auth-Assertion=${jwt}`);
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
. - In the given example, the
sellerPayerId
is the payer ID of the receiving seller's PayPal account. You can also useemail
instead ofpayer_id
and supply the email address of the seller's PayPal account.
Example functions to generate the PayPal-Auth-Assertion
header in other programming environments:
Node.js
1// Node.js234function encodeObjectToBase64(object) {5 const objectString = JSON.stringify(object);6 return Buffer7 .from(objectString)8 .toString("base64");9}101112const clientId = "CLIENT-ID";13const sellerPayerId = "SELLER-PAYER-ID"; // preferred14// const sellerEmail = "SELLER-ACCOUNT-EMAIL"; // use instead if payer-id unknown151617const header = {18 alg: "none"19};20const encodedHeader = encodeObjectToBase64(header);212223const payload = {24 iss: clientId,25 payer_id: sellerPayerId26 // email: sellerEmail27};28const encodedPayload = encodeObjectToBase64(payload);293031const jwt = `${encodedHeader}.${encodedPayload}.`; // json web token32console.log(`Paypal-Auth-Assertion=${jwt}`);
Java
1// Java234import org.apache.commons.codec.binary.Base64;567public class Base64Encode {8910 public static void main(String[] args) {11 String clientId = "CLIENT-ID";12 String sellerPayerId = "SELLER-PAYER-ID"; // preferred13 // String sellerEmail = "SELLER-ACCOUNT-EMAIL"; // use instead if payer-id unknown141516 String header = "{\"alg\":\"none\"}";17 String payload =18 "{\"iss\":\"" + clientId + "\",\"payer_id\":\"" + sellerPayerId + "\"}";19 // "{"iss":"" + clientId + "","email":"" + sellerEmail + ""}";202122 byte[] encodedHeader = Base64.encodeBase64(header.getBytes());23 byte[] encodedPayload = Base64.encodeBase64(payload.getBytes());242526 String jwt = new String(encodedHeader) +27 "." +28 new String(encodedPayload) +29 "."; // json web token30 System.out.println("Paypal-Auth-Assertion=" + jwt);31 }32}
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. - Replace
BN-CODE
with your PayPal attribution ID to receive revenue attribution.To find your BN code, see Code and Credential Reference.
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/refund2 -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 -H "PayPal-Partner-Attribution-Id: BN-CODE"7 -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/refund2-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-H "PayPal-Partner-Attribution-Id: BN-CODE"7-d '{8 "amount": {9 "value": "10.99",10 "currency_code": "USD"11 }12}'
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
For more information about the refunds API, see the Payment API.
Go through the integration checklist before you go live.