Issue a Refund

DOCS

Last updated: Sept 24th, 3:58pm

Refund a captured payment, by ID using /v2/payments/captures/{capture_id}/refund. For a full refund, include an empty payload in the JSON request body. For a partial refund, include an amount object in the JSON request body.

Headers

Pass the standard Content-Type and Authorization request headers along with the PayPal-Request-Id.

In live, 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:

    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}

    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 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 = "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 subject
        8 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 an order

          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: 123e4567-e89b-12d3-a456-426655440020" \
          5-d '{}

          Partially refund an order

            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: 123e4567-e89b-12d3-a456-426655440020" \
            5-d '{
            6 "amount": {
            7 "value": "10.99",
            8 "currency_code": "USD"
            9 },
            10 "invoice_id": "INVOICE-123",
            11 "note_to_payer": "Defective product"
            12}'

            Response

            A successful request returns the HTTP 201 Created status code and a JSON response body that shows refund details.

              1{
              2 "id": "1JU08902781691411",
              3 "status": "COMPLETED",
              4 "links": [
              5 {
              6 "rel": "self",
              7 "method": "GET",
              8 "href": "https://api-m.paypal.com/v2/payments/refunds/1JU08902781691411"
              9 },
              10 {
              11 "rel": "up",
              12 "method": "GET",
              13 "href": "https://api-m.paypal.com/v2/payments/captures/2GG279541U471931P"
              14 }
              15 ]
              16}

              Additional information

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