RefundTransaction API Operation (NVP)

Issues a refund to the PayPal account holder associated with a transaction. This API operation can be used to issue a full or partial refund for any transaction within a default period of 180 days from when the payment is received.

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.

RefundTransaction Request Message

RefundTransaction Request Fields

Field Description

METHOD

(Required) Must be RefundTransaction.

TRANSACTIONID

(Required) Unique identifier of the transaction to be refunded.

Character length and limitations: 17 characters except for transactions of the type Order have a character length of 19.

PAYERID

(Optional) Encrypted PayPal customer account identification number. Supported only for Point of Sale transactions.

Character length and limitations: 13 single-byte alphanumeric characters

INVOICEID

(Optional) Your own invoice or tracking ID number.

Character length and limitations: 127 single-byte alphanumeric characters

REFUNDTYPE

Type of refund you are making. Value is:

  • Full — Full refund (default).

  • Partial — Partial refund.

AMT

(Optional) Refund amount. Required if the value of RefundType is Partial.

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.

Character length and limitations:

Value is typically a positive number that cannot exceed 10,000.00 USD 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.

CURRENCYCODE

(Optional) Currency code of the refund transaction. If this field is not passed, the currency code of the original transaction is used. It is an ISO 4217 3-letter currency code, for example, USD for US Dollars.

Character length and limitations: 3 single-byte characters

NOTE

(Optional) Custom memo about the refund.

Character length and limitations: 255 single-byte alphanumeric characters

REFUNDSOURCE

(Optional)Type of PayPal funding source (balance or eCheck) that can be used for auto refund. Value is:

  • any — The merchant does not have a preference. Use any available funding source.

  • instant — Use the merchant's balance as the funding source.

  • eCheck — The merchant prefers using the eCheck funding source. If the merchant's PayPal balance can cover the refund amount, use the PayPal balance.

Note: This field does not apply to point-of-sale transactions.

This field is available since version 82.0.

REFUNDADVICE

(Optional) 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:

  • true — The buyer was already given store credit for a given transaction.

  • false — The buyer was not given store credit for a given transaction.

This field is available since version 85.0.

SHIPPINGAMT

(Optional) The amount of shipping paid.

TAXAMT

(Optional) The amount of tax paid.

MSGSUBID

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

Merchant Store Details Fields

Note: These fields are only supported for Point of Sale transactions.

Field Description

STOREID

Identifier 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

(Optional) ID of the terminal.

Character length and limitations: 50 single-byte characters

This field is available since version 82.0.

InvoiceItemType Fields

Describes the details of each individual item in the refund transaction.

Field Description

L_INVOICEITEMNAMEn

(Optional) A human readable item name.

Character length and limitations: 127 single-byte characters.

You can specify multiple items in each request. The character n, in the field name, should be replaced with an integer between 0 and 15, inclusive. For example, if you are passing only one item in the request, then replace n with the digit 0 in all field names containing an n. When passing information about multiple items, the items must be ordered sequentially.

L_DESCRIPTIONn

(Optional) A human readable item description.

Character length and limitations: 127 single-byte characters.

You can specify multiple items in each request. The character n, in the field name, should be replaced with an integer between 0 and 15, inclusive. For example, if you are passing only one item in the request, then replace n with the digit 0 in all field names containing an n. When passing information about multiple items, the items must be ordered sequentially.

L_EANn

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

You can specify multiple items in each request. The character n, in the field name, should be replaced with an integer between 0 and 15, inclusive. For example, if you are passing only one item in the request, then replace n with the digit 0 in all field names containing an n. When passing information about multiple items, the items must be ordered sequentially.

L_SKUn

(Optional) The Stock-Keeping Unit or other identification code assigned to the item.

Character length and limitations: 64 single-byte characters.

You can specify multiple items in each request. The character n, in the field name, should be replaced with an integer between 0 and 15, inclusive. For example, if you are passing only one item in the request, then replace n with the digit 0 in all field names containing an n. When passing information about multiple items, the items must be ordered sequentially.

L_PRICEn

(Optional) The total price of this item.

Character length and limitations:

Value is typically a positive number that cannot exceed 10,000.00 USD 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.

You can specify multiple items in each request. The character n, in the field name, should be replaced with an integer between 0 and 15, inclusive. For example, if you are passing only one item in the request, then replace n with the digit 0 in all field names containing an n. When passing information about multiple items, the items must be ordered sequentially.

L_PRICECURRENCYCODEn

(Conditional) Required if L_PRICEn is passed. The currency code of L_PRICEn.

Character length and limitations:

You can specify multiple items in each request. The character n, in the field name, should be replaced with an integer between 0 and 15, inclusive. For example, if you are passing only one item in the request, then replace n with the digit 0 in all field names containing an n. When passing information about multiple items, the items must be ordered sequentially.

L_ITEMPRICEn

(Optional) The price for one item.

Character length and limitations:

Value is typically a positive number that cannot exceed 10,000.00 USD 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.

You can specify multiple items in each request. The character n, in the field name, should be replaced with an integer between 0 and 15, inclusive. For example, if you are passing only one item in the request, then replace n with the digit 0 in all field names containing an n. When passing information about multiple items, the items must be ordered sequentially.

L_ITEMPRICECURRENCYCODEn

(Conditional) Required if L_ITEMPRICEn is passed. The currency code of L_ITEMPRICEn.

Character length and limitations:

You can specify multiple items in each request. The character n, in the field name, should be replaced with an integer between 0 and 15, inclusive. For example, if you are passing only one item in the request, then replace n with the digit 0 in all field names containing an n. When passing information about multiple items, the items must be ordered sequentially.

L_ITEMCOUNTn

(Conditional) Required if L_ITEMCOUNTUNITn is passed. Quantity of the item. Must be positive.

Character length and limitations:

You can specify multiple items in each request. The character n, in the field name, should be replaced with an integer between 0 and 15, inclusive. For example, if you are passing only one item in the request, then replace n with the digit 0 in all field names containing an n. When passing information about multiple items, the items must be ordered sequentially.

L_ITEMCOUNTUNITn

(Conditional) Required if L_ITEMCOUNTn is passed. Unit of measure for the L_ITEMCOUNTn.

Character length and limitations:

You can specify multiple items in each request. The character n, in the field name, should be replaced with an integer between 0 and 15, inclusive. For example, if you are passing only one item in the request, then replace n with the digit 0 in all field names containing an n. When passing information about multiple items, the items must be ordered sequentially.

L_TAXRATEn

(Optional) The tax percentage applied to the item. This is only displayed in the receipt and is not used in pricing calculations.

Character length and limitations:

You can specify multiple items in each request. The character n, in the field name, should be replaced with an integer between 0 and 15, inclusive. For example, if you are passing only one item in the request, then replace n with the digit 0 in all field names containing an n. When passing information about multiple items, the items must be ordered sequentially.

L_ADDITIONALFEESnTYPEm

(Conditional) Required if L_ADDITIONALFEESnAMTm or L_ADDITIONALFEESnCURRENCYm is passed. The type of additional fees applied for this item.

Character length and limitations:

You can specify multiple items in each request. The character n, in the field name, should be replaced with an integer between 0 and 15, inclusive. For example, if you are passing only one item in the request, then replace n with the digit 0 in all field names containing an n. When passing information about multiple items, the items must be ordered sequentially.

This field also allows you to pass an array of information for each item. The character m, in the field name, is the nested array index and should be replaced with an integer. In other words, you can have multiple m values for each n value. Replace m with 0 for the first value you pass. If passing more than one value, make sure the integers used are sequential.

Allows up to 16 additional fees per item; m can range from 0 to 15.

L_ADDITIONALFEESnAMTm

(Conditional) Required if L_ADDITIONALFEESnTYPEm or L_ADDITIONALFEESnCURRENCYm is passed. The amount of additional fees applied for this item.

Character length and limitations:

Value is typically a positive number that cannot exceed 10,000.00 USD 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.

You can specify multiple items in each request. The character n, in the field name, should be replaced with an integer between 0 and 15, inclusive. For example, if you are passing only one item in the request, then replace n with the digit 0 in all field names containing an n. When passing information about multiple items, the items must be ordered sequentially.

This field also allows you to pass an array of information for each item. The character m, in the field name, is the nested array index and should be replaced with an integer. In other words, you can have multiple m values for each n value. Replace m with 0 for the first value you pass. If passing more than one value, make sure the integers used are sequential.

Allows up to 16 additional fees per item; m can range from 0 to 15.

L_ADDITIONALFEESnCURRENCYm

(Conditional) Required if L_ADDITIONALFEESnTYPEm or L_ADDITIONALFEESnAMTm is passed. The currency code of the additional fees applied for this item.

Character length and limitations:

You can specify multiple items in each request. The character n, in the field name, should be replaced with an integer between 0 and 15, inclusive. For example, if you are passing only one item in the request, then replace n with the digit 0 in all field names containing an n. When passing information about multiple items, the items must be ordered sequentially.

This field also allows you to pass an array of information for each item. The character m, in the field name, is the nested array index and should be replaced with an integer. In other words, you can have multiple m values for each n value. Replace m with 0 for the first value you pass. If passing more than one value, make sure the integers used are sequential.

Allows up to 16 additional fees per item; m can range from 0 to 15.

L_MPNn

(Optional) Manufacturer part number.

Character length and limitations:

You can specify multiple items in each request. The character n, in the field name, should be replaced with an integer between 0 and 15, inclusive. For example, if you are passing only one item in the request, then replace n with the digit 0 in all field names containing an n. When passing information about multiple items, the items must be ordered sequentially.

L_ISBNn

(Optional) International Standard Book Number. Reference International Standard Book Number.

Character length and limitations: 32 single-byte characters.

L_PLUn

(Optional) Price Look-Up code. Reference http://en.wikipedia.org/wiki/Price_Look-Up_code.

Character length and limitations: 5 single-byte characters.

L_MODELNUMBERn

(Optional) The item manufacturer's model number.

Character length and limitations: 32 single-byte characters.

You can specify multiple items in each request. The character n, in the field name, should be replaced with an integer between 0 and 15, inclusive. For example, if you are passing only one item in the request, then replace n with the digit 0 in all field names containing an n. When passing information about multiple items, the items must be ordered sequentially.

L_STYLENUMBERn

(Optional) The item manufacturer's style number.

Character length and limitations: 32 single-byte characters.

You can specify multiple items in each request. The character n, in the field name, should be replaced with an integer between 0 and 15, inclusive. For example, if you are passing only one item in the request, then replace n with the digit 0 in all field names containing an n. When passing information about multiple items, the items must be ordered sequentially.

RefundTransaction Response Message

RefundTransaction Response Fields

Field Description

REFUNDTRANSACTIONID

Unique transaction ID of the refund.

Character length and limitations: 17 characters except for transactions of the type Order have a character length of 19.

FEEREFUNDAMT

The 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 FEEREFUNDAMT 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 FEEREFUNDAMT is 1.45.

Character length and limitations:

Value is typically a positive number that cannot exceed 10,000.00 USD 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.

GROSSREFUNDAMT

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

Character length and limitations:

Value is typically a positive number that cannot exceed 10,000.00 USD 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.

NETREFUNDAMT

Amount deducted from your PayPal account to make this refund. This is the GrossRefundAmount minus the FEEREFUNDAMT.

Character length and limitations:

Value is typically a positive number that cannot exceed 10,000.00 USD 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.

TOTALREFUNDEDAMT

Total 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 TOTALREFUNDEDAMT is $50.00.

Character length and limitations:

Value is typically a positive number that cannot exceed 10,000.00 USD 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.

CURRENCYCODE

An ISO 4217 3-letter currency code, for example, USD for US Dollars.

Character length and limitations: 3 single-byte characters.

REFUNDINFO

Contains refund payment status information.

This field is available since version 84.0.

MSGSUBID

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

RefundInfoType Fields

Field Description

REFUNDSTATUS

ns:PaymentStatusCodeType

Status of the refund. Value is:

  • none — returned if the refund transaction fails (ACK=Failure).

  • instant

  • delayed

This field is available since version 84.0.

PENDINGREASON

Reason that the refund payment status is delayed. Value is:

  • none — The refund status is instant.

  • echeck — The refund status is delayed.

  • regulatoryreview - The payment is pending while we make sure it meets regulatory requirements. You will be contacted again in 24-72 hours with the outcome of the review.

This field is available since version 84.0.

Additional information