Refund API Operation

API

Last updated: Aug 15th, 7:15am

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.

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.

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

Field	Description
`currencyCode`	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.
`requestEnvelope.errorLanguage`	The code for the language in which errors are returned, which must be `en_US`

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

Field	Description
`payKey`	The key used to create the payment that you want to refund
`trackingId`	The tracking ID associated with the payment that you want to refund

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: 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

Field	Description
`receiverList.receiver(n).email`	The identified receiver's email address, where `n` is between 0 and 5 for a maximum of 6 receivers
`receiverList.receiver(n).accountId`	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.
`receiverList.receiver(n).amount`	Amount to refund to the identified receiver

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

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

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

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.

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.

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.

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.

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.

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: The Refund API operation does not support iACH.

RefundRequest Message

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

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	Description
`currencyCode`	(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. Allowable values are: Australian Dollar — `AUD` Brazilian Real — `BRL` 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. Canadian Dollar — `CAD` Czech Koruna — `CZK` Danish Krone — `DKK` Euro — `EUR` Hong Kong Dollar — `HKD` Hungarian Forint — `HUF` Israeli New Shekel — `ILS` Japanese Yen — `JPY` Malaysian Ringgit — `MYR` Note: The Ringgit is supported as a payment currency and currency balance only for Malaysian PayPal accounts. Mexican Peso — `MXN` Norwegian Krone — `NOK` New Zealand Dollar `— NZD` Philippine Peso — `PHP` Polish Zloty — `PLN` Pound Sterling `— GBP` Singapore Dollar — `SGD` Swedish Krona `— SEK` Swiss Franc — `CHF` Taiwan New Dollar — `TWD` Thai Baht `— THB` U.S. Dollar — `USD`
`payKey`	`xs:string` (Optional) The key used to create the payment that you want to refund.
`receiverList`	`ap:ReceiverList` (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.
`requestEnvelope`	`common:requestEnvelope` (Required) Information common to each API operation, such as the language in which an error message is returned.
`transactionId`	`xs:string` (Optional) The PayPal transaction ID associated with the payment that you want to refund.
`trackingId`	`xs:string` (Optional) The tracking ID associated with the payment that you want to refund.

ReceiverList Fields

Field	Description
`receiver`	`ap:Receiver` (Required) Receiver is the party whose account is credited.

Field

Description

receiver

ap:Receiver

(Required) Receiver is the party whose account is credited.

Receiver Fields

Field	Description
`amount`	`xs:decimal` (Required) Amount to be credited to the receiver's account.
`email`	`xs:string` (Optional) Receiver's email address. Maximum length: 127 characters
`accountId`	`xs:string` (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. Maximum length: 13 single-byte alphanumeric characters
`invoiceId`	`xs:string` (Optional) This fields is not used. Maximum length: 127 characters
`paymentType`	`xs:string` (Optional) This field is not used.
`paymentSubType`	`xs:string` (Optional) This field is not used.
`phone`	`common:PhoneNumberType` (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.
`primary`	`xs:boolean` (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. Allowable values are: `true` — Primary receiver `false` — Secondary receiver (default)

PhoneNumberType Fields

Field	Description
`countryCode`	`xs:string` (Required) Telephone country code.
`phoneNumber`	`xs:string` (Required) Telephone number.
`extension`	`xs:string` (Optional) Telephone extension.

Field

Description

countryCode

xs:string

(Required) Telephone country code.

phoneNumber

xs:string

(Required) Telephone number.

extension

xs:string

(Optional) Telephone extension.

RequestEnvelope Fields

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

Field

Description

detailLevel

common:DetailLevelCode

(Optional) Level of detail required by the client application for components. Value is:

ReturnAll — This value provides the maximum level of detail (default).

errorLanguage

xs:string

(Required) RFC 3066 language in which error messages are returned; by default it is en_US, which is the only language currently supported.

Refund Response Message

The refundResponse message contains status information about a refund request.

RefundResponse Fields

Field	Description
`currencyCode`	The currency code represented by one of the following values: Australian Dollar — `AUD` Brazilian Real — `BRL` 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. Canadian Dollar — `CAD` Czech Koruna — `CZK` Danish Krone — `DKK` Euro — `EUR` Hong Kong Dollar — `HKD` Hungarian Forint — `HUF` Israeli New Shekel — `ILS` Japanese Yen — `JPY` Malaysian Ringgit — `MYR` Note: The Ringgit is supported as a payment currency and currency balance only for Malaysian PayPal accounts. Mexican Peso — `MXN` Norwegian Krone — `NOK` New Zealand Dollar `— NZD` Philippine Peso — `PHP` Polish Zloty — `PLN` Pound Sterling `— GBP` Singapore Dollar — `SGD` Swedish Krona `— SEK` Swiss Franc — `CHF` Taiwan New Dollar — `TWD` Thai Baht `— THB` U.S. Dollar — `USD`
`refundInfoList`	`ap:RefundInfoList` List of refunds associated with the payment.
`responseEnvelope`	`common:ResponseEnvelope` Common response information, including a timestamp and the response acknowledgment status.

Field

Description

currencyCode

The currency code represented by one of the following values:

Australian Dollar — AUD

Brazilian Real — BRL

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.

Canadian Dollar — CAD

Czech Koruna — CZK

Danish Krone — DKK

Euro — EUR

Hong Kong Dollar — HKD

Hungarian Forint — HUF

Israeli New Shekel — ILS

Japanese Yen — JPY

Malaysian Ringgit — MYR

Note: The Ringgit is supported as a payment currency and currency balance only for Malaysian PayPal accounts.

Mexican Peso — MXN

Norwegian Krone — NOK

New Zealand Dollar — NZD

Philippine Peso — PHP

Polish Zloty — PLN

Pound Sterling — GBP

Singapore Dollar — SGD

Swedish Krona — SEK

Swiss Franc — CHF

Taiwan New Dollar — TWD

Thai Baht — THB

U.S. Dollar — USD

refundInfoList

ap:RefundInfoList

List of refunds associated with the payment.

responseEnvelope

common:ResponseEnvelope

Common response information, including a timestamp and the response acknowledgment status.

RefundInfoList Fields

Field	Description
`refundInfo`	`ap:RefundInfo` Represents the refund attempt made to a receiver of a `PayRequest`.

Field

Description

refundInfo

ap:RefundInfo

Represents the refund attempt made to a receiver of a PayRequest.

RefundInfo Fields

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

ErrorData Fields

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

Receiver Fields

Field	Description
`amount`	`xs:decimal` Amount to be refunded to the receiver.
`email`	`xs:string` Receiver's email address. Maximum length: 127 characters
`accountId`	`xs:string` 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. Maximum length: 13 single-byte alphanumeric characters
`invoiceId`	`xs:string` This fields is not used. Maximum length: 127 characters
`paymentType`	`xs:string` This field is not used.
`paymentSubType`	`xs:string` This field is not used.
`phone`	`common:PhoneNumberType` The receiver's phone number.
`primary`	`xs:boolean` 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. Value is: `true` — Primary receiver (chained payment) `false` — Secondary receiver (simple/parallel payment)

PhoneNumberType Response Fields

Field	Description
`countryCode`	`xs:string` Telephone country code.
`phoneNumber`	`xs:string` Telephone number.
`extension`	`xs:string` Telephone extension.

Field

Description

countryCode

xs:string

Telephone country code.

phoneNumber

xs:string

Telephone number.

extension

xs:string

Telephone extension.

ResponseEnvelope Fields

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

PPFault Message

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

FaultMessage Fields

Field	Description
`error`	`common:ErrorData` Detailed error information.
`responseEnvelope`	`common:ResponseEnvelope` Common response information, including a timestamp and the response acknowledgment status.

Field

Description

error

common:ErrorData

Detailed error information.

responseEnvelope

common:ResponseEnvelope

Common response information, including a timestamp and the response acknowledgment status.

ErrorData Fields

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

ResponseEnvelope Fields

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

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

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: 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:

1curl 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:

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

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