On this page
No Headings
Last updated: June 18, 2026
Important: NVP/SOAP is a legacy integration method. We accept new integrations and support existing integrations, but there are newer solutions. If you're starting an integration, we recommend our latest solutions.
Issues a full or partial refund to the PayPal account holder associated with a transaction.
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.
After the refund period has passed, merchants can no longer use the RefundTransaction API operation to issue refunds. Instead, merchants can manually issue a credit to the buyer by logging into their PayPal account; for PayPal payments, a credit can be issued by clicking Send Money. Alternatively, merchants can use the MassPay API to credit PayPal accounts or utilize the DoNonReferencedCredit API operation to issue a credit to a card without referencing the original transaction.
For more about refunds, see All about refunds at PayPal.
| Field | Description |
|---|---|
TransactionID | xs:string(Required) Unique identifier of the transaction to be refunded. Character length and limitations: 17 characters. Orders transactions have 19 characters. |
PayerID | ebl:UserIDType(Optional) Encrypted PayPal customer account identification number. Supported only for Point of Sale transactions. Character length and limitations: 13 single-byte alphanumeric characters |
InvoiceID | xs:string(Optional) Your own invoice or tracking ID number. Character length and limitations: 127 single-byte alphanumeric characters |
RefundType | ebl:RefundPurposeTypeCodeTypeType of refund you are making. Value is:
|
Amount | ebl:BasicAmountType(Optional) Refund amount. Required if RefundType is Partial or for refunds greater than 100%. Note: If the value of RefundType is Full, do not set the amount unless you want to refund more than 100% of the original transaction amount. If you set the amount, you must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies. .), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page. |
Memo | xs:string(Optional) Custom memo about the refund. Character length and limitations: 255 single-byte alphanumeric characters |
RefundSource | ebl:RefundSourceCodeType*(Optional)*Type of PayPal funding source (balance or eCheck) that can be used for auto refund. Value is:
Note: This field does not apply to point-of-sale transactions. |
MerchantStoreDetails | ebl:MerchantStoreDetailsType(Optional) Information about the merchant store. Supported only for Point of Sale transactions. This field is available since version 82.0. |
RefundAdvice | xs:boolean(Deprecated) Flag indicates the buyer received store credit for a given transaction. Supported only for Point of Sale transactions and is one of the following values:
|
MsgSubId | xs:string(Optional) A message ID that uniquely identifies the request. This ID can later be used to request the latest results for a previous request without generating a new request. Examples of this include requests due to timeouts or errors during the original request. Character length and limitations: string of up to 38 single-byte characters. This field is available since version 92.0. |
Note: These fields are only supported for Point of Sale transactions.
Describe the merchant store details within the MerchantStoreDetails element.
| Field | Description |
|---|---|
StoreID | xs:stringIdentifier of the merchant store at which the refund is given. This field is required for point-of-sale transactions. Character length and limitations: 50 single-byte characters This field is available since version 82.0. |
TerminalID | xs:string(Optional) ID of the terminal. Character length and limitations: 50 single-byte characters This field is available since version 82.0. |
Describe additional fee information.
| Field | Description |
|---|---|
Type | xs:string(Required) The type of additional fee. |
Amount | cc:BasicAmountType(Required) The amount of the additional fee. Note: You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies. .), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page. |
| Field | Description |
|---|---|
RefundTransactionID | xs:stringUnique transaction ID of the refund. Character length and limitations: 17 characters. Orders transactions have 19 characters. |
FeeRefundAmount | ebl:BasicAmountTypeThe refunded amount of the PayPal transaction fees (all or part of the variable fee). PayPal's transaction fees for merchants typically consist of a variable fee and a fixed fee. For example, for a $100 payment amount, if the standard per transaction fee is the sum of a variable fee of 2.9% plus a fixed fee of $0.30, the fees would be $2.90 + $0.30. For a full refund of $100.00, the FeeRefundAmount is 2.90, or 100% of the variable fee.Note: PayPal does not refund the fixed per transaction fee, which is typically $0.30 in the U.S. or its equivalent for your country. See PayPal Merchant Fees for more information. For partial refunds, a percentage of the variable fee is refunded, equivalent to the percentage of the refund from the original payment amount. In this example, for a partial refund of $50.00, the FeeRefundAmount is 1.45. Note: You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies. .), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page. |
GrossRefundAmount | ebl:BasicAmountTypeAmount refunded to the buyer in this refund transaction. For example, a buyer originally made a $100.00 payment, the buyer was refunded $20.00 a week ago and is refunded $30.00 in this transaction. The gross refund amount is $30.00, only the amount refunded in this transaction. Note: You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies. .), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page. |
NetRefundAmount | ebl:BasicAmountTypeAmount deducted from your PayPal account to make this refund. This is the GrossRefundAmount minus the FeeRefundAmount. Note: You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies. .), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page. |
TotalRefundedAmount | ebl:BasicAmountTypeTotal amount refunded so far from the original payment. For example, a buyer originally made a $100.00 payment, the buyer was refunded $20.00 a week ago and is refunded $30.00 in this transaction. The TotalRefundedAmount is $50.00.Character length and limitations: Value is typically a positive number that cannot exceed nine (9) digits in SOAP request/response for USD, CLP, or JPY or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period ( .), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page.This field is available since version 67.0. |
RefundInfo | ebl:RefundInfoTypeContains refund payment status information. This field is available since version 84.0. |
MsgSubId | xs:string(Optional) A message ID used for idempotency to uniquely identify a message. This ID can later be used to request the latest results for a previous request without generating a new request. Examples of this include requests due to timeouts or errors during the original request. Character length and limitations: string of up to 38 single-byte characters. This field is available since version 92.0. |
| Field | Description |
|---|---|
RefundStatus | ns:PaymentStatusCodeTypeStatus of the refund. Value is:
|
PendingReason | xs:PendingStatusCodeTypeReason that the refund payment status is delayed. Value is:
|
The following fields are deprecated. Replacement fields are noted when available.
| Deprecated field | Replacement field | Since Version/Date |
|---|---|---|
RefundItemDetails | (No replacement)ebl:InvoiceItemType(Optional) Details about the individual items to be returned. | March 2019 |
ShippingAmount | (No replacement)cc:BasicAmountType(Optional) The amount of shipping paid. Note: You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies. | March 2019 |
TaxAmount | (No replacement)cc:BasicAmountType(Optional) The amount of tax paid. Note: You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies. | March 2019 |
| Deprecated field | Replacement field | Since Version/Date |
|---|---|---|
Name | (No replacement)xs:string(Optional) A human readable item name. Character length and limitations: 127 single-byte characters. | March 2019 |
Description | (No replacement)xs:string(Optional) A human readable item description. Character length and limitations: 127 single-byte characters. | March 2019 |
EAN | (No replacement)xs:string(Optional) The International Article Number or Universal Product Code (UPC) for the item. An empty string is allowed. Character length and limitations: 17 single-byte characters. | March 2019 |
SKU | (No replacement)xs:string(Optional) The Stock-Keeping Unit or other identification code assigned to the item. Character length and limitations: 64 single-byte characters. | March 2019 |
Price | (No replacement)cc:BasicAmountType(Optional) The total price of this item. Note: You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies. .), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page. | March 2019 |
ItemPrice | (No replacement)cc:BasicAmountType(Optional) The price for one item. Note: You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies. .), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page. | March 2019 |
ItemCount | (No replacement)xs:double(Conditional) Required if ItemCountUnit is passed. The quantity of the item. Must be positive. | March 2019 |
ItemCountUnit | (No replacement)ebl:UnitOfMeasure(Conditional) Required if ItemCount is passed. Unit of measure for the ItemCount.It is one of the following:
| March 2019 |
TaxRate | (No replacement)xs:double(Optional) The tax percentage applied to the item. This is only displayed in the receipt and is not used in pricing calculations. | March 2019 |
AdditionalFees | (No replacement)ebl:AdditionalFeeType(Optional) Additional fees applied for this item. | March 2019 |
MPN | (No replacement)xs:string(Optional) Manufacturer part number. | March 2019 |
ISBN | (No replacement)xs:string(Optional) International Standard Book Number. Reference International Standard Book Number. Character length and limitations: 32 single-byte characters. | March 2019 |
PLU | (No replacement)xs:string(Optional) Price Look-Up code. Reference https://en.wikipedia.org/wiki/Price_Look-Up_code. Character length and limitations: 5 single-byte characters. | March 2019 |
ModelNumber | (No replacement)xs:string(Optional) The item manufacturer's model number. Character length and limitations: 32 single-byte characters. | March 2019 |
StyleNumber | (No replacement)xs:string(Optional) The item manufacturer's style number. Character length and limitations: 32 single-byte characters. | March 2019 |