On this page
No Headings
Last updated: May 21, 2026
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:
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.
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) + \".\");
\}
\}For a full refund, include an empty payload in the JSON request body.
{
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: "BN-CODE" -d '{}For a partial refund, include an amount object in the JSON request body.
{
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: BN-CODE" -d '{
"amount": {
"value": "10.99",
"currency_code": "USD"
},
"invoice_id": "INVOICE-123",
"note_to_payer": "Defective product"
}'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"
}
]
}For more information about the refunds API, see the Payment API refund resource.