Refund payments

A sale is a completed PayPal or credit card payment.

A captured payment is an authorized and captured PayPal or credit card payment.

You can refund sales and captured payments.

Integration steps

1. Required Meet the prerequisites.
2. Optional Either fully refund a sale or partially refund a sale.
3. Optional Fully or partially refund a captured payment.

Prerequisites

  1. Get an access token.

    To get an access token, you must create a PayPal app. When you create an app, PayPal generates a set of OAuth client_id and secret keys for your app for both the sandbox and live environments. Then, to get an access token, you pass the client_id:secret credentials in the Authorization header in a get access token request. The authorization server issues an access token in exchange for your client ID and secret credentials. You use the access token for authentication when you make REST API requests.

    For more information, see make your first call. If you are a non-US developer, see International Developer Questions. You can use your sandbox access token to try any of the code in the REST API reference.

    Each API response includes HATEOAS links that enable you to construct a payment flow.

  2. To receive payments in a currency that you do not hold, first configure your Payment Receiving Preferences in your PayPal account. Otherwise, your payment status might be pending until you manually approve the payment in your PayPal account.

  3. To receive guest checkout payments, which allow credit cards, enable the PayPal Account Optional option in your account settings. The path to this option for US accounts is:

    Profile > My selling tools > Website preferences > PayPal Account Optional

  4. To test payments, create test buyer and merchant accounts in the PayPal sandbox. To create a test buyer account, select the Personal account type. To create a test merchant account, select the Business account type. See create sandbox accounts.

Fully refund a sale

For a full refund, include the sale ID of the completed payment in the URI and include an empty JSON request body.

This example requests a full refund:

curl -v https://api.sandbox.paypal.com/v1/payments/sale/67D22837NN7279935/refund \
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer Access-Token" \
  -d '{}'

The response shows the refund details, indicates that the refund is complete, and includes request-related HATEOAS links:

{
  "id": "04700149C07500921",
  "create_time": "2013-03-01T18:39:18Z",
  "update_time": "2013-03-01T18:39:18Z",
  "state": "completed",
  "amount": {
    "total": "7.47",
    "currency": "USD"
  },
  "sale_id": "67D22837NN7279935",
  "parent_payment": "PAY-8DW08487GN7528733KEYPITA",
  "links": [{
    "href": "https://api.sandbox.paypal.com/v1/payments/refund/04700149C07500921",
    "rel": "self",
    "method": "GET"
  }, {
    "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-8DW08487GN7528733KEYPITA",
    "rel": "parent_payment",
    "method": "GET"
  }, {
    "href": "https://api.sandbox.paypal.com/v1/payments/sale/67D22837NN7279935",
    "rel": "sale",
    "method": "GET"
  }]
}

Partially refund a sale

For a partial refund, include an amount object in the JSON request body.

This example requests a partial refund of a sale:

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/sale/2MU78835H4515710F/refund \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "amount": {
  "total": "2.34",
  "currency": "USD"
  },
  "invoice_number": "INV-1234567"
}'

The response shows the refund details:

{
  "id": "4CF18861HF410323U",
  "create_time": "2017-01-31T04:13:34Z",
  "update_time": "2017-01-31T04:13:36Z",
  "state": "completed",
  "amount": {
    "total": "2.34",
    "currency": "USD"
  },
  "sale_id": "2MU78835H4515710F",
  "parent_payment": "PAY-46E69296BH2194803KEE662Y",
  "invoice_number": "INV-1234567",
  "links": [{
    "href": "https://api.sandbox.paypal.com/v1/payments/refund/4CF18861HF410323U",
    "rel": "self",
    "method": "GET"
  }, {
    "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-46E69296BH2194803KEE662Y",
    "rel": "parent_payment",
    "method": "GET"
  }, {
    "href": "https://api.sandbox.paypal.com/v1/payments/sale/2MU78835H4515710F",
    "rel": "sale",
    "method": "GET"
  }]
}

Refund a captured payment

To refund a captured payment, include the ID of the captured payment in the URI and an amount object in the JSON request body. You must include the amount object for both full and partial refunds:

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/capture/2MU78835H4515710F/refund \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "amount": {
    "currency": "USD",
    "total": "110.54"
  }
}'

The response shows the refund details:

{
  "id": "0P209507D6694645N",
  "create_time": "2017-05-06T22:11:51Z",
  "update_time": "2017-05-06T22:11:51Z",
  "state": "completed",
  "amount": {
    "total": "110.54",
    "currency": "USD"
  },
  "capture_id": "8F148933LY9388354",
  "parent_payment": "PAY-8PT597110X687430LKGECATA",
  "invoice_number": "INV-1234567",
  "links": [{
    "href": "https://api.sandbox.paypal.com/v1/payments/refund/0P209507D6694645N",
    "rel": "self",
    "method": "GET"
  }, {
    "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-8PT597110X687430LKGECATA",
    "rel": "parent_payment",
    "method": "GET"
  }, {
    "href": "https://api.sandbox.paypal.com/v1/payments/capture/8F148933LY9388354",
    "rel": "capture",
    "method": "GET"
  }]
}

Next

You can show refund details.

Also, learn how to use the Payment Experience API to create web experience profiles to customize payment flow experiences.

Additional information