Issue a refund
Last updated: Sept 24th, 5:55am
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
header.PayPal-Auth-Assertion
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": sellerPayerId13 };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}
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 useemail
instead ofpayer_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 subject8 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.