Issue a refund

CurrentDocs

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

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 JavaScript
    2
    3
    4function encodeObjectToBase64(object) {
    5 const objectString = JSON.stringify(object);
    6 return window.btoa(objectString);
    7}
    8
    9
    10const clientId = "CLIENT-ID";
    11const sellerPayerId = "SELLER-PAYER-ID"; // preferred
    12// const sellerEmail = "SELLER-ACCOUNT-EMAIL"; // use instead of payer-id if required
    13
    14
    15const header = {
    16 alg: "none"
    17};
    18const encodedHeader = encodeObjectToBase64(header);
    19
    20
    21const payload = {
    22 iss: clientId,
    23 payer_id: sellerPayerId
    24 // email: sellerEmail
    25};
    26const encodedPayload = encodeObjectToBase64(payload);
    27
    28
    29const jwt = `${encodedHeader}.${encodedPayload}.`; // json web token
    30console.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 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 in other programming environments:

    Node.js

      1// Node.js
      2
      3
      4function encodeObjectToBase64(object) {
      5 const objectString = JSON.stringify(object);
      6 return Buffer
      7 .from(objectString)
      8 .toString("base64");
      9}
      10
      11
      12const clientId = "CLIENT-ID";
      13const sellerPayerId = "SELLER-PAYER-ID"; // preferred
      14// const sellerEmail = "SELLER-ACCOUNT-EMAIL"; // use instead if payer-id unknown
      15
      16
      17const header = {
      18 alg: "none"
      19};
      20const encodedHeader = encodeObjectToBase64(header);
      21
      22
      23const payload = {
      24 iss: clientId,
      25 payer_id: sellerPayerId
      26 // email: sellerEmail
      27};
      28const encodedPayload = encodeObjectToBase64(payload);
      29
      30
      31const jwt = `${encodedHeader}.${encodedPayload}.`; // json web token
      32console.log(`Paypal-Auth-Assertion=${jwt}`);

      Java

        1// Java
        2
        3
        4import org.apache.commons.codec.binary.Base64;
        5
        6
        7public class Base64Encode {
        8
        9
        10 public static void main(String[] args) {
        11 String clientId = "CLIENT-ID";
        12 String sellerPayerId = "SELLER-PAYER-ID"; // preferred
        13 // String sellerEmail = "SELLER-ACCOUNT-EMAIL"; // use instead if payer-id unknown
        14
        15
        16 String header = "{\"alg\":\"none\"}";
        17 String payload =
        18 "{\"iss\":\"" + clientId + "\",\"payer_id\":\"" + sellerPayerId + "\"}";
        19 // "{"iss":"" + clientId + "","email":"" + sellerEmail + ""}";
        20
        21
        22 byte[] encodedHeader = Base64.encodeBase64(header.getBytes());
        23 byte[] encodedPayload = Base64.encodeBase64(payload.getBytes());
        24
        25
        26 String jwt = new String(encodedHeader) +
        27 "." +
        28 new String(encodedPayload) +
        29 "."; // json web token
        30 System.out.println("Paypal-Auth-Assertion=" + jwt);
        31 }
        32}
        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.
        • 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/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 -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/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-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

            Refund Resource

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

            Integration Checklist

            Go through the integration checklist before you go live.

            We use cookies to improve your experience on our site. May we use marketing cookies to show you personalized ads? Manage all cookies