# Refund API Operation (/archive/adaptive-payments/api/refund)



> **Note:** **Important:** Adaptive Payments is not available for new     integrations. PayPal provides this documentation to support existing     integrations. If you're starting an integration,     [we recommend our latest solutions](https://www.paypal.com/us/business/accept-payments).

Refunds all or part of a payment.

You can specify the amount of the refund, and identify the accounts to receive   the refund, by the payment key or tracking ID, and optionally, by transaction   ID or the receivers of the original payment.

The default refund period is 180 days from the transaction date.

If you refund a payment for goods or services, there are no fees to make the   refund, but the fees you originally paid as the seller are not returned to   you. The amount of the refunded payment will be deducted from your PayPal   account.

To learn how to make a refund after 180 days from the original transaction,   see   [All about refunds at PayPal](https://www.paypal.com/us/smarthelp/article/all-about-refunds-at-paypal-faq3248#How%20can%20I%20issue%20a%20refund?).

## Refund API Overview [#refund-api-overview]

PayPal supports refunds made manually, via the PayPal account interface, or   with the RefundTransaction API.

The terms *sender* and *receiver* refer to sender and receivers   of the original payment using the Pay API   operation. When making a refund, the sender's account receives the refund and   the receivers' accounts are the source of the refund. Refunds are made from   one or more receivers to a sender.

To make a refund using the Refund API operation,   you must:

* Have made a `Pay` request for which payment you want to refund       the payment, or you must have received the part of the payment you want to       refund, and
* Have permission to make a refund on behalf of the receiver, unless you are       also the receiver; in other words, each receiver whose account is the       source of the refund must have granted you third-party access permission       to call the Refund API operation.

  > **Note:** **Note:** A receiver with a         **business or premier account** can grant you third-party         access (to make a refund) by logging in to PayPal, choosing         API Access on the Profile page, clicking         the link to         [Grant API permission](https://www.paypal.com/us/cgi-bin/webscr?cmd=_profile-api-list-auths), and selecting Refund after clicking         Configure a custom API authorization.

For each kind of refund, you must specify values for the following fields:

### Table 1 . Common fields for all refunds [#table-1--common-fields-for-all-refunds]

| Field<br />                           | Description<br />                                                                                                                                                               |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `currencyCode`<br />                  | The currency code. You must specify the currency code that matches the           currency code of the original payment unless you also specify the           payment key.<br /> |
| `requestEnvelope.errorLanguage`<br /> | The code for the language in which errors are returned, which must be           `en_US`<br />                                                                                   |

You can refund a payment from all receivers associated with a payment by   specifying the payment's payment key or tracking ID:

### Table 2 . Refunds that apply to all receivers [#table-2--refunds-that-apply-to-all-receivers]

| Field<br />        | Description<br />                                                         |
| ------------------ | ------------------------------------------------------------------------- |
| `payKey`<br />     | The key used to create the payment that you want to refund<br />          |
| `trackingId`<br /> | The tracking ID associated with the payment that you want to refund<br /> |

You can make a refund to the sender of a payment from specific receivers   associated with a payment key or tracking ID. In this case, you must specify:

* either the payment key or tracking ID that identifies the original payment
* for each receiver making a refund, the receiver's email address or account       ID
* for each receiver, the amount to refund to the sender from the receiver's       account.

> **Note:** **Note:** The receiver can't make a partial refund if the     original payment was a cash advance, personal payment, or unilateral     payment.

### Table 3 . Additional fields for refunds of specific amounts to specific receivers [#table-3--additional-fields-for-refunds-of-specific-amounts-to-specific-receivers]

| Field<br />                                | Description<br />                                                                                                                                                                                                                                                                                 |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `receiverList.receiver(n).email`<br />     | The identified receiver's email address, where n is between           0 and 5 for a maximum of 6 receivers<br />                                                                                                                                                                                  |
| `receiverList.receiver(n).accountId`<br /> | The account ID value (which is the same as the Payer ID value used in           the Express Checkout API) of the identified receiver. The account ID           value is an encrypted PayPal account ID. This account ID value can be           specified instead of a PayPal email address.<br /> |
| `receiverList.receiver(n).amount`<br />    | Amount to refund to the identified receiver<br />                                                                                                                                                                                                                                                 |

A payment can also be identified as a set of PayPal transactions between the   sender and each specific receiver. You can refund the amount of the   transaction by specifying the transaction ID:

### Table 4 . Refunds that apply to a PayPal transaction associated with the payment [#table-4--refunds-that-apply-to-a-paypal-transaction-associated-with-the-payment]

| Field<br />           | Description<br />                                                                                                                                                          |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transactionId`<br /> | A PayPal transaction ID associated with the receiver whose payment you           want to refund to the sender. Use field name characters exactly as           shown.<br /> |

### Refund Notifications [#refund-notifications]

Notifications are sent after the refund is complete:

* PayPal sends an email to all PayPal account holders affected by the       refund.
* PayPal sends an IPN message to the URL specified in the       `ipnNotificationUrl` field of the `Pay` request.

### Additional Notes About the Refund API Operation [#additional-notes-about-the-refund-api-operation]

1. Payments made using the Pay API operation cannot be refunded using the       RefundTransaction API operation. You must use       the Refund API operation or log in to PayPal       to issue the refund.
2. A personal account holder cannot grant API access to a third party. A       personal account holder must issue the refund by specifying the       transaction ID, or by logging in to paypal.com to make the refund.
3. A payment made using the Pay API operation       cannot be refunded by logging in to paypal.com if the fees cannot be       refunded. In these cases, you must use the       Refund API operation to issue the refund.
4. In the refund request, specify the payment using either the pay key,       transaction ID, or tracking ID; it is not recommended to specify more than       one of these arguments, unless they identify the same payment. If the       arguments do not belong to the same payment, the transaction ID is used;       next, it uses the payment key. If more than one way is specified, the ID       is never used.
5. With the Adaptive Payments Pay API operation, you can make payments to a       person who does not have a PayPal account. In essence, you send a payment       request that includes an email address for a receiver, and this email       address is not linked to a registered PayPal account. The receiver       receives an email notifying the receiver to create an account and claim       the payment. Supporting features include email notifications and IPNs to       the sender, receiver, and API caller, plus the ability to cancel unclaimed       payments.

   You can make such a payment in the same way that you make any other kind       of payment; however, PayPal holds a payment to a receiver whose email       address is not yet registered or confirmed until the receiver creates a       PayPal account and confirms the email address. If a refund specifies a       receiver whose email address is not yet registered or confirmed, the       payment to the receiver is canceled.
6. If the refund involves chained payments, PayPal first moves the money from       the secondary receiver to the primary, refunding the secondary's share       back to the primary. PayPal then attempts to refund the full amount from       primary to buyer.

   At this point, if the primary receiver's account still does not have       sufficient funds to cover the refund, PayPal initiates a draft from the       Primary's bank account to get enough money to complete the refund. The       bank draft is usually completed within a couple of days. At this time,       since the primary has enough funds in his account, PayPal completes the       refund to the buyer. If the bank draft fails, the refund request is       cancelled.

   > **Note:** **Note:** The Refund API operation does not support iACH.

## RefundRequest Message [#refundrequest-message]

The `refundRequest` message specifies information about the refund   and how it is to be allocated to PayPal account holders.

### RefundRequest Fields [#refundrequest-fields]

You must specify a value for only one of the following fields to identify the   part of the payment to refund: `payKey`,   `transactionId`, or `trackingId`.

| Field<br />             | Description<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `currencyCode`<br />    | *(Required)* The currency code. You must specify the currency           code used for the original payment. You do not need to specify this           field if you use a `payKey` to refund a complete           transaction.<br />          Allowable values are:<br />          Australian Dollar — `AUD`<br />Brazilian Real — `BRL`<br />              &#x2A;*Note:** This currency is supported as a payment               currency and a currency balance for in-country PayPal accounts               only. If the receiver of funds is not from Brazil, then PayPal               converts funds into the primary holding currency of the account               with the applicable currency conversion rate. The currency               conversion rate includes PayPal's applicable spread or fee.<br />Canadian Dollar — `CAD`<br />Czech Koruna — `CZK`<br />Danish Krone — `DKK`<br />Euro — `EUR`<br />Hong Kong Dollar — `HKD`<br />Hungarian Forint — `HUF`<br />Israeli New Shekel — `ILS`<br />Japanese Yen — `JPY`<br />Malaysian Ringgit — `MYR`<br />              &#x2A;*Note:** The Ringgit is supported as a payment               currency and currency balance only for Malaysian PayPal accounts.<br />Mexican Peso — `MXN`<br />Norwegian Krone — `NOK`<br />New Zealand Dollar` — NZD`<br />Philippine Peso — `PHP`<br />Polish Zloty — `PLN`<br />Pound Sterling` — GBP`<br />Singapore Dollar — `SGD`<br />Swedish Krona` — SEK`<br />Swiss Franc — `CHF`<br />Taiwan New Dollar — `TWD`<br />Thai Baht` — THB`<br />U.S. Dollar — `USD`<br /> |
| `payKey`<br />          | `xs:string`<br /&#x3E;          &#x2A;(Optional)* The key used to create the payment that you want           to refund.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `receiverList`<br />    | `ap:ReceiverList`<br /&#x3E;          &#x2A;(Optional)* Information about the receivers of the payment           that you want to refund; the payment is identified by payment key,           tracking ID, or transaction ID. Specify each receiver to whom you want           to issue a refund. You can specify the refund amount for specific           receivers. If you do not specify any receivers, all receivers will be           fully refunded if you specify the payment key or tracking ID;           otherwise, only the affected receiver will be fully refunded if you           specify the transaction ID.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `requestEnvelope`<br /> | `common:requestEnvelope`<br /&#x3E;          &#x2A;(Required)* Information common to each API operation, such as           the language in which an error message is returned.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `transactionId`<br />   | `xs:string`<br /&#x3E;          &#x2A;(Optional)* The PayPal transaction ID associated with the           payment that you want to refund.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `trackingId`<br />      | `xs:string`<br /&#x3E;          &#x2A;(Optional)* The tracking ID associated with the payment that           you want to refund.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

### ReceiverList Fields [#receiverlist-fields]

| Field<br />      | Description<br />                                                                                          |
| ---------------- | ---------------------------------------------------------------------------------------------------------- |
| `receiver`<br /> | `ap:Receiver`<br /&#x3E;          &#x2A;(Required)* Receiver is the party whose account is credited.<br /> |

### Receiver Fields [#receiver-fields]

| Field<br />            | Description<br />                                                                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `amount`<br />         | `xs:decimal`<br /&#x3E;          &#x2A;(Required)* Amount to be credited to the receiver's account.<br />                                                                                                                                                                                                                                                                                                                    |
| `email`<br />          | `xs:string`<br /&#x3E;          &#x2A;(Optional)* Receiver's email address.<br />          Maximum length: 127 characters<br />                                                                                                                                                                                                                                                                                              |
| `accountId`<br />      | `xs:string`<br /&#x3E;          &#x2A;(Optional)* Receiver's account ID value (which is the same as           the Payer ID value used in the Express Checkout API). The account ID           value is an encrypted PayPal account ID. This account ID value can be           specified instead of a PayPal email address.<br />          Maximum length: 13 single-byte alphanumeric characters<br />                        |
| `invoiceId`<br />      | `xs:string`<br /&#x3E;          &#x2A;(Optional)* This fields is not used.<br />          Maximum length: 127 characters<br />                                                                                                                                                                                                                                                                                               |
| `paymentType`<br />    | `xs:string`<br /&#x3E;          &#x2A;(Optional)* This field is not used.<br />                                                                                                                                                                                                                                                                                                                                              |
| `paymentSubType`<br /> | `xs:string`<br /&#x3E;          &#x2A;(Optional)* This field is not used.<br />                                                                                                                                                                                                                                                                                                                                              |
| `phone`<br />          | `common:PhoneNumberType`<br /&#x3E;          &#x2A;(Optional)* A type to specify the receiver's phone number. The           `PayRequest` must pass an email address, account ID, or a           phone number as the payment receiver.<br />                                                                                                                                                                                  |
| `primary`<br />        | `xs:boolean`<br /&#x3E;          &#x2A;(Optional)* Whether this receiver is the primary receiver,           which makes this a refund for a chained payment. You can specify at           most one primary receiver. Omit this field for refunds for simple and           parallel payments.<br />          Allowable values are:<br />          `true` — Primary receiver<br />`false` — Secondary receiver (default)<br /> |

### PhoneNumberType Fields [#phonenumbertype-fields]

| Field<br />         | Description<br />                                                               |
| ------------------- | ------------------------------------------------------------------------------- |
| `countryCode`<br /> | `xs:string`<br /&#x3E;          &#x2A;(Required)* Telephone country code.<br /> |
| `phoneNumber`<br /> | `xs:string`<br /&#x3E;          &#x2A;(Required)* Telephone number.<br />       |
| `extension`<br />   | `xs:string`<br /&#x3E;          &#x2A;(Optional)* Telephone extension.<br />    |

### RequestEnvelope Fields [#requestenvelope-fields]

| Field<br />           | Description<br />                                                                                                                                                                                                                                                 |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `detailLevel`<br />   | `common:DetailLevelCode`<br /&#x3E;          &#x2A;(Optional)* Level of detail required by the client application           for components. Value is:<br />          `ReturnAll` — This value provides the maximum level of               detail (default).<br /> |
| `errorLanguage`<br /> | `xs:string`<br /&#x3E;          &#x2A;(Required)* RFC 3066 language in which error messages are           returned; by default it is `en_US`, which is the only           language currently supported.<br />                                                     |

## Refund Response Message [#refund-response-message]

The `refundResponse` message contains status information about a   refund request.

### RefundResponse Fields [#refundresponse-fields]

| Field<br />              | Description<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `currencyCode`<br />     | The currency code represented by one of the following values:<br />          Australian Dollar — `AUD`<br />Brazilian Real — `BRL`<br />              &#x2A;*Note:** This currency is supported as a payment               currency and a currency balance for in-country PayPal accounts               only. If the receiver of funds is not from Brazil, then PayPal               converts funds into the primary holding currency of the account               with the applicable currency conversion rate. The currency               conversion rate includes PayPal's applicable spread or fee.<br />Canadian Dollar — `CAD`<br />Czech Koruna — `CZK`<br />Danish Krone — `DKK`<br />Euro — `EUR`<br />Hong Kong Dollar — `HKD`<br />Hungarian Forint — `HUF`<br />Israeli New Shekel — `ILS`<br />Japanese Yen — `JPY`<br />Malaysian Ringgit — `MYR`<br />              &#x2A;*Note:** The Ringgit is supported as a payment               currency and currency balance only for Malaysian PayPal accounts.<br />Mexican Peso — `MXN`<br />Norwegian Krone — `NOK`<br />New Zealand Dollar` — NZD`<br />Philippine Peso — `PHP`<br />Polish Zloty — `PLN`<br />Pound Sterling` — GBP`<br />Singapore Dollar — `SGD`<br />Swedish Krona` — SEK`<br />Swiss Franc — `CHF`<br />Taiwan New Dollar — `TWD`<br />Thai Baht` — THB`<br />U.S. Dollar — `USD`<br /> |
| `refundInfoList`<br />   | `ap:RefundInfoList`<br />          List of refunds associated with the payment.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `responseEnvelope`<br /> | `common:ResponseEnvelope`<br />          Common response information, including a timestamp and the response           acknowledgment status.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

### RefundInfoList Fields [#refundinfolist-fields]

| Field<br />        | Description<br />                                                                                                  |
| ------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `refundInfo`<br /> | `ap:RefundInfo`<br />          Represents the refund attempt made to a receiver of a           `PayRequest`.<br /> |

### RefundInfo Fields [#refundinfo-fields]

| Field<br />                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `encryptedRefundTransactionId`<br /> | `xs:string`<br />          The PayPal transaction ID for this refund.<br />          &#x2A;*Note:** This ID is different than the transaction ID           for the original payment.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `errorList`<br />                    | `ap:ErrorList`<br />          Information about why a refund failed.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `receiver`<br />                     | `ap:Receiver`<br />          Information about the receiver of the refund.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `refundFeeAmount`<br />              | `xs:decimal`<br />          Amount of fees that have been refunded.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `refundGrossAmount`<br />            | `xs:decimal`<br />          Gross amount of the refund, including the total amount from this           receiver and fees.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `refundHasBecomeFull`<br />          | `xs:boolean`<br />          Whether you have refunded the total amount of the payment.<br />          Value is:<br />          `true` — Entire amount of the payment has been refunded<br />`false` — Entire amount of the payment has not been               refunded<br />         &#x2A;*Note:** This field is only available when a partial           refund has been requested.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `refundNetAmount`<br />              | `xs:decimal`<br />          The total amount of the refund from this receiver.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `refundStatus`<br />                 | `xs:string`<br />          Status of the refund. Value is:<br />          `REFUNDED` — Refund successfully completed<br />`REFUNDED_PENDING` — Refund awaiting transfer of funds;               for example, a refund paid by eCheck.<br />`NOT_PAID` — Payment was never made; therefore, it               cannot be refunded.<br />`ALREADY_REVERSED_OR_REFUNDED` — Request rejected               because the refund was already made, or the payment was reversed               prior to this request.<br />`NO_API_ACCESS_TO_RECEIVER` — Request cannot be               completed because you do not have third-party access from the               receiver to make the refund.<br />`REFUND_NOT_ALLOWED` — Refund is not allowed.<br />`INSUFFICIENT_BALANCE` — Request rejected because the               receiver from which the refund is to be paid does not have               sufficient funds or the funding source cannot be used to make a               refund.<br />`AMOUNT_EXCEEDS_REFUNDABLE` — Request rejected because               you attempted to refund more than the remaining amount of the               payment; call the PaymentDetails API               operation to determine the amount already refunded.<br />`PREVIOUS_REFUND_PENDING` — Request rejected because a               refund is currently pending for this part of the payment<br />`NOT_PROCESSED` — Request rejected because it cannot be               processed at this time<br />`REFUND_ERROR` — Request rejected because of an               internal error<br />`PREVIOUS_REFUND_ERROR `— Request rejected because               another part of this refund caused an internal error.<br /> |
| `refundTransactionStatus`<br />      | `xs:string`<br />          The status of the refund transaction.<br />          Value is:<br />          `UNKNOWN` — The status of the refund process is               unknown.<br />`COMPLETED` — The refund process has been completed.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `totalOfAllRefunds`<br />            | `xs:decimal`<br />          The total of all refunds actually paid; does not include pending           amounts<br />          &#x2A;*Note:** This field is only available when a partial           refund has been requested.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

### ErrorData Fields [#errordata-fields]

| Field<br />         | Description<br />                                                                                                                                                                                                                                                                                          |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `category`<br />    | `common:ErrorCategory`<br />          The location where the error occurred.<br />          Value is:<br />          `System` — The system encountered errors; try again<br />`Application` — The application encountered errors; try               again<br />`Request` — The request was incorrect<br /> |
| `domain`<br />      | `xs:string`<br />          The domain to which this service belongs.<br />                                                                                                                                                                                                                                 |
| `errorId`<br />     | `xs:long`<br />          A 6-digit number that uniquely identifies a particular error.<br />                                                                                                                                                                                                               |
| `exceptionID`<br /> | This field is not used.<br />                                                                                                                                                                                                                                                                              |
| `message`<br />     | `xs:string`<br />          A description of the error.<br />                                                                                                                                                                                                                                               |
| `parameter`<br />   | `common:ErrorParameter`<br />          Represents contextual information about the error.<br />                                                                                                                                                                                                            |
| `severity`<br />    | `common:ErrorSeverity`<br />          The severity of the error encountered.<br />          Value is:<br />          `Error` — Processing of the request was interrupted<br />`Warning` — Processing of the request was completed<br />                                                                    |
| `subdomain`<br />   | This field is not used.<br />                                                                                                                                                                                                                                                                              |

### Receiver Fields [#receiver-fields-1]

| Field<br />            | Description<br />                                                                                                                                                                                                                                                                                                                                                                       |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `amount`<br />         | `xs:decimal`<br />          &#x2A;Amount to be refunded to the receiver.*<br />                                                                                                                                                                                                                                                                                                         |
| `email`<br />          | `xs:string`<br />          Receiver's email address.<br />          Maximum length: 127 characters<br />                                                                                                                                                                                                                                                                                |
| `accountId`<br />      | `xs:string`<br />          Receiver's account ID value (which is the same as the Payer ID value           used in the Express Checkout API). The account ID value is an           encrypted PayPal account ID. This account ID value can be specified           instead of a PayPal email address.<br />          Maximum length: 13 single-byte alphanumeric characters<br />          |
| `invoiceId`<br />      | `xs:string`<br />          This fields is not used.<br />          Maximum length: 127 characters<br />                                                                                                                                                                                                                                                                                 |
| `paymentType`<br />    | `xs:string`<br />          This field is not used.<br />                                                                                                                                                                                                                                                                                                                                |
| `paymentSubType`<br /> | `xs:string`<br />          This field is not used.<br />                                                                                                                                                                                                                                                                                                                                |
| `phone`<br />          | `common:PhoneNumberType`<br />          The receiver's phone number.<br />                                                                                                                                                                                                                                                                                                              |
| `primary`<br />        | `xs:boolean`<br />          Whether this receiver is the primary receiver, which makes this a           refund for a chained payment. If this field is set to false, this is a           refund for a simple or parallel payment.<br />          Value is:<br />          `true` — Primary receiver (chained payment)<br />`false` — Secondary receiver (simple/parallel payment)<br /> |

### PhoneNumberType Response Fields [#phonenumbertype-response-fields]

| Field<br />         | Description<br />                                        |
| ------------------- | -------------------------------------------------------- |
| `countryCode`<br /> | `xs:string`<br />          Telephone country code.<br /> |
| `phoneNumber`<br /> | `xs:string`<br />          Telephone number.<br />       |
| `extension`<br />   | `xs:string`<br />          Telephone extension.<br />    |

### ResponseEnvelope Fields [#responseenvelope-fields]

| Field<br />           | Description<br />                                                                                                                                                                                                                                                                                                                                                                                              |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ack`<br />           | `common:AckCode`<br />          Acknowledgment code. Value is:<br />          `Success` — The operation completed successfully.<br />`Failure` — The operation failed.<br />`SuccessWithWarning` — The operation completed               successfully; however, there is a warning message.<br />`FailureWithWarning `— The operation failed with a               warning message.<br />                       |
| `build`<br />         | `xs:string`<br />          Build number. It is used only by PayPal Merchant Technical Support.<br />                                                                                                                                                                                                                                                                                                           |
| `correlationId`<br /> | `xs:string`<br />          Correlation identifier. It is a 13-character, alphanumeric string (for           example, `db87c705a910e`) that is used only by PayPal           Merchant Technical Support.<br />          &#x2A;*Note:** You must log and store this data for every           response you receive. PayPal Technical Support uses the information to           assist with reported issues.<br /> |
| `timestamp`<br />     | `xs:datetime`<br />          Date on which the response was sent, for example:<br />          `2012-04-02T22:33:35.774-07:00`<br />          &#x2A;*Note:** You must log and store this data for every           response you receive. PayPal Technical Support uses the information to           assist with reported issues.<br />                                                                           |

## PPFault Message [#ppfault-message]

The `PPFaultMessage` returns `ErrorData` and the   `ResponseEnvelope` information to your application if an error   occurs.

### FaultMessage Fields [#faultmessage-fields]

| Field<br />              | Description<br />                                                                                                                                   |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `error`<br />            | `common:ErrorData`<br />          Detailed error information.<br />                                                                                 |
| `responseEnvelope`<br /> | `common:ResponseEnvelope`<br />          Common response information, including a timestamp and the response           acknowledgment status.<br /> |

### ErrorData Fields [#errordata-fields-1]

| Field<br />         | Description<br />                                                                                                                                                                                                                                                                                          |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `category`<br />    | `common:ErrorCategory`<br />          The location where the error occurred.<br />          Value is:<br />          `System` — The system encountered errors; try again<br />`Application` — The application encountered errors; try               again<br />`Request` — The request was incorrect<br /> |
| `domain`<br />      | `xs:string`<br />          The domain to which this service belongs.<br />                                                                                                                                                                                                                                 |
| `errorId`<br />     | `xs:long`<br />          A 6-digit number that uniquely identifies a particular error.<br />                                                                                                                                                                                                               |
| `exceptionID`<br /> | This field is not used.<br />                                                                                                                                                                                                                                                                              |
| `message`<br />     | `xs:string`<br />          A description of the error.<br />                                                                                                                                                                                                                                               |
| `parameter`<br />   | `common:ErrorParameter`<br />          Represents contextual information about the error.<br />                                                                                                                                                                                                            |
| `severity`<br />    | `common:ErrorSeverity`<br />          The severity of the error encountered.<br />          Value is:<br />          `Error` — Processing of the request was interrupted<br />`Warning` — Processing of the request was completed<br />                                                                    |
| `subdomain`<br />   | This field is not used.<br />                                                                                                                                                                                                                                                                              |

### ResponseEnvelope Fields [#responseenvelope-fields-1]

| Field<br />           | Description<br />                                                                                                                                                                                                                                                                                                                                                                                              |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ack`<br />           | `common:AckCode`<br />          Acknowledgment code. Value is:<br />          `Success` — The operation completed successfully.<br />`Failure` — The operation failed.<br />`SuccessWithWarning` — The operation completed               successfully; however, there is a warning message.<br />`FailureWithWarning `— The operation failed with a               warning message.<br />                       |
| `build`<br />         | `xs:string`<br />          Build number. It is used only by PayPal Merchant Technical Support.<br />                                                                                                                                                                                                                                                                                                           |
| `correlationId`<br /> | `xs:string`<br />          Correlation identifier. It is a 13-character, alphanumeric string (for           example, `db87c705a910e`) that is used only by PayPal           Merchant Technical Support.<br />          &#x2A;*Note:** You must log and store this data for every           response you receive. PayPal Technical Support uses the information to           assist with reported issues.<br /> |
| `timestamp`<br />     | `xs:datetime`<br />          Date on which the response was sent, for example:<br />          `2012-04-02T22:33:35.774-07:00`<br />          &#x2A;*Note:** You must log and store this data for every           response you receive. PayPal Technical Support uses the information to           assist with reported issues.<br />                                                                           |

## Refund Examples Using NVP and CURL [#refund-examples-using-nvp-and-curl]

These examples all use NVP for the data binding and CURL to deliver the HTTP   request to the PayPal sandbox endpoint. Line breaks are provided for ease of   reading; each CURL command is a single line and each request and response is a   string without line breaks or extra whitespace.

### Using the payment key to refund an entire payment [#using-the-payment-key-to-refund-an-entire-payment]

In this example, the caller of the Refund API   operation specifies a payment key. The total amount from each receiver is   refunded to the sender.

> **Note:** **Note:** The sample code below uses the     `insecure` setting to work around the certificate for testing in     a sandbox environment. For actual implementations, you must specify the     location of the certificate.

**Request:**

<div className="pl-[1.625rem]" />

```text lineNumbers
curl https://svcs.sandbox.paypal.com/AdaptivePayments/Refund \ -s \ --insecure \ -H "X-PAYPAL-SECURITY-USERID: " \ -H "X-PAYPAL-SECURITY-PASSWORD: " \ -H "X-PAYPAL-SECURITY-SIGNATURE: " \ -H "X-PAYPAL-REQUEST-DATA-FORMAT: NV" \ -H "X-PAYPAL-RESPONSE-DATA-FORMAT: NV" \ -H "X-PAYPAL-APPLICATION-ID:  "   \ -d requestEnvelope.errorLanguage=en_US \ -d payKey=AP-95V43510SV018561T
```

**Response:**

<div className="pl-[1.625rem]" />

```text lineNumbers
responseEnvelope.timestamp=2009-08-14T09%3A00%3A37.748-07%3A00 &responseEnvelope.ack=Success &responseEnvelope.correlationId=7967b2d03745a &responseEnvelope.build=DEV ¤cyCode=USD &refundInfoList.refundInfo(0).receiver.amount=3.15 &refundInfoList.refundInfo(0).receiver.email=&refundInfoList.refundInfo(0).refundStatus=REFUNDED &refundInfoList.refundInfo(0).refundNetAmount=2.81 &refundInfoList.refundInfo(0).refundFeeAmount=0.34 &refundInfoList.refundInfo(0).refundGrossAmount=3.15 &refundInfoList.refundInfo(0).totalOfAllRefunds=3.15 &refundInfoList.refundInfo(0).refundHasBecomeFull=true &refundInfoList.refundInfo(0).encryptedRefundTransactionId=48K11199GC160... &refundInfoList.refundInfo(0).refundTransactionStatus=COMPLETED &refundInfoList.refundInfo(1).receiver.amount=1.78 &refundInfoList.refundInfo(1).receiver.email=&refundInfoList.refundInfo(1).refundStatus=REFUNDED &refundInfoList.refundInfo(1).refundNetAmount=1.43 &refundInfoList.refundInfo(1).refundFeeAmount=0.35 &refundInfoList.refundInfo(1).refundGrossAmount=1.78 &refundInfoList.refundInfo(1).totalOfAllRefunds=1.78 &refundInfoList.refundInfo(1).refundHasBecomeFull=true &refundInfoList.refundInfo(1).encryptedRefundTransactionId=40Y76985BU687... &refundInfoList.refundInfo(1).refundTransactionStatus=COMPLETED
```

## Refund errors [#refund-errors]

| Message ID           | Short and long messages                                                                                                                          |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| 500000               | There is a system error                                                                                                                          |
| 520002               | Internal error                                                                                                                                   |
| 520003               | User name/password is incorrect                                                                                                                  |
| 520006               | This call is not defined in the database                                                                                                         |
| 520008               | You do not have a verified ACH                                                                                                                   |
| 520009               | Account is restricted                                                                                                                            |
| 520010               | The account for the counter party is locked or inactive                                                                                          |
| 560011               | Because a complaint case exists on this transaction, only a refund of         the full or full remaining amount of the transaction can be issued |
| 560016               | You cannot do a partial refund on this transaction                                                                                               |
| 560018               | You cannot refund this type of transaction                                                                                                       |
| 570012               | Cannot do a full refund after a partial refund                                                                                                   |
| 570013               | The partial refund amount must be less than or equal to the original         transaction amount                                                  |
| 570014               | The partial refund amount must be less than or equal to the remaining         amount                                                             |
| 570015               | This transaction has already been fully refunded                                                                                                 |
| 570017               | You are over the time limit to perform a refund on this transaction                                                                              |
| 579051               | The tracking ID is invalid                                                                                                                       |
| 580001               | Invalid request                                                                                                                                  |
| 580022               | Invalid request parameter: payKey with value \<value>                                                                                            |
| 580027               | The argument is unsupported                                                                                                                      |
| 589018               | The pay key is valid                                                                                                                             |
| 589023               | If a fractional amount is rounded due to currency conversion, funds         could be lost                                                        |
| 580029 (since 1.6.0) | A pay key, transaction ID, or tracking ID is missing                                                                                             |
| 580030 (since 1.3.0) | This transaction cannot be processed at this time. Please try again         later.                                                               |
| 589036               | The currency code is missing or does not match the code in the payment         request                                                           |
| 589037               | The refund's receiver was not part of the payment request                                                                                        |
| 589038               | The refund has to be both less than or equal to the original payment         request and greater than zero                                       |
| 589041               | All receivers must give full refunds for this type of chained payment                                                                            |
| 589052               | The transaction ID is invalid                                                                                                                    |
| 589061 (since 1.6.0) | The receiver \<value> is invalid for this refund                                                                                                 |