Refund API Operation

Use the Refund API operation to refund 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.

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 can grant you third-party access to make a refund by logging in to PayPal, choosing API Access on the Profile page, then clicking the link to Grant API permission and selecting Refund after clicking Configure a custom API authorization.

    Note: The Adaptive Payments Refund API call does not support pay keys generated by the Mobile Payment Library (MPL).

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

  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: 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: The Real is supported as a payment currency and currency balance only for Brazilian PayPal accounts.

  • Canadian Dollar – CAD

  • Czech Koruna – CZK

  • Danish Krone – DKK

  • Euro – EUR

  • Hong Kong Dollar – HKD

  • Hungarian Forint – HUF

  • Israeli New Sheqel – 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

  • Turkish Lira – TRY

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

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

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.

RequestEnvelope Fields

Field

Description

detailLevel

common:DetailLevelCode

(Optional) Level of detail required by the client application for components. It is one of the following values:

  • 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: The Real is supported as a payment currency and currency balance only for Brazilian PayPal accounts.

  • Canadian Dollar – CAD

  • Czech Koruna – CZK

  • Danish Krone – DKK

  • Euro – EUR

  • Hong Kong Dollar – HKD

  • Hungarian Forint – HUF

  • Israeli New Sheqel – 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

  • Turkish Lira – TRY

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

  • 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 acknowledgement status.

RefundInfoList Fields

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.

Possible values are:

  • 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. It is one of the following values:

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

Possible values are:

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

Possible values are:

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

Possible values are:

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

Possible values are:

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

ResponseEnvelope Fields

Field

Description

ack

common:AckCode

Acknowledgement code. It is one of the following values:

  • 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 acknowledgement status.

ErrorData Fields

Field

Description

category

common:ErrorCategory

The location where the error occurred.

Possible values are:

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

Possible values are:

  • 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

Acknowledgement code. It is one of the following values:

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

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

Response:

responseEnvelope.timestamp=2009-08-14T09%3A00%3A37.748-07%3A00 
&responseEnvelope.ack=Success
&responseEnvelope.correlationId=7967b2d03745a
&responseEnvelope.build=DEV
&currencyCode=USD
&refundInfoList.refundInfo(0).receiver.amount=3.15
&refundInfoList.refundInfo(0).receiver.email=receiver1@domain
&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=receiver2@domain
&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

Code

Message

Additional Information

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 A pay key, transaction ID, or tracking ID is missing Since 1.6.0

580030

This transaction cannot be processed at this time. Please try again later. Since 1.3.0
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

The receiver <value> is invalid for this refund

Since 1.6.0