Server-Side API Requests/
Transaction/
Refund

Transaction: Refund

You can refund transactions that have a status of settled or settling. If the transaction has not yet begun settlement, use Transaction: Void instead. If you do not specify an amount to refund, the entire transaction amount will be refunded.

Refer to the Transaction response object for more information.
  1. Java
Result<transaction> result = gateway.transaction().refund("the_transaction_id");
If the transaction can't be found, it will throw a NotFoundException.

If the refund fails, then the result will be unsuccessful and will include either validation errors indicating which parameters were invalid, or a processor settlement response code indicating the type of settlement failure.
  1. Java
result.isSuccess(); // false
for (ValidationError error : result.getErrors().getAllDeepValidationErrors()) {
    System.out.println(error.getMessage());
}
Arguments
transactionIdrequired, string
The unique transaction identifier.
Additional Parameters
.amount(…)BigDecimal
The amount to refund. This value must be greater than 0, and can't exceed the total amount of the transaction. If you do not specify an amount to refund, the entire transaction amount will be refunded. See partial refunds below for more details.
.lineItems(…)
The line items for this transaction. It can include up to 249 line items. Only available for Custom Actions transactions.
.commodityCode(…)string

Code used to classify items purchased and track the total amount spent across various categories of products and services. Different corporate purchasing organizations may use different standards, but the United Nations Standard Products and Services Code (UNSPSC) is frequently used. Maximum 12 characters. This Braintree line-item field is not used by PayPal. For Visa CEDP, required for Level 3 interchange.

.description(…)string
Item description. Maximum 127 characters.
.discountAmount(…)BigDecimal

Discount amount for the line item. Can include up to 2 decimal places. This value can't be negative. This Braintree line-item field is not used by PayPal. For Visa CEDP, must be provided if discount exists.

.kind(…)string

Indicates whether the line item is a debit (sale) or credit (refund) to the customer. Accepted values:

  • "debit"
  • "credit"
.name(…)string

Item name. Maximum 35 characters. Required for Level 3 interchange. For Visa CEDP, the item name should reflect the purchased item and must not be the same as the merchant name; it should not be generic, numeric, or non-descriptive.

.productCode(…)string

Product code for the item. Maximum 12 characters. For Visa CEDP, required for Level 3 interchange.

.quantity(…)BigDecimal
Number of units of the item purchased. Can include up to 4 decimal places. This value can't be negative or zero.
.taxAmount(…)BigDecimal

Tax amount for the line item. Can include up to 2 decimal places. This value can't be negative. For Visa CEDP, this field is not required; however, if tax amount was paid at the line-item level, the sum of all line-item taxes should be reflected in the transaction-level field. This summation rule is specific to Visa CEDP. For Mastercard, tax_amount can be sent in this field.

.totalAmount(…)BigDecimal

Quantity x unit amount. Can include up to 2 decimal places. For Visa CEDP, the line-item total is calculated as (quantity x unit amount) minus the discount per line item.

.unitAmount(…)BigDecimal
Per-unit price of the item. Maximum 4 decimal places. This value can't be negative or zero.
.unitOfMeasure(…)string

The unit of measure or the unit of measure code. Maximum 12 characters. It represents the measurement unit corresponding to the product sold. For example, item/box for a countable object, liter/gallon for a liquid, or kilogram/pound for weight. This Braintree line-item field is not used by PayPal. For Visa CEDP, required for Level 3 interchange.

.unitTaxAmount(…)BigDecimal
Per-unit tax price of the item. Can include up to 2 decimal places. This value can't be negative or zero.
.upcCode(…)string
UPC code for the item. Maximum 17 characters. If specified, you must also provide the UPC type.
.upcType(…)string

UPC type for the item. If specified, you must also provide the UPC code. Accepted values:

  • "UPC-A"
  • "UPC-B"
  • "UPC-C"
  • "UPC-D"
  • "UPC-E"
  • "UPC-2"
  • "UPC-5"
.url(…)string
The URL to product information.
.merchantAccountId(…)string

The merchant account ID used to create a transaction. Currency is also determined by merchant account ID. If no merchant account ID is specified, we will use your default merchant account.

.orderId(…)string

Use this parameter if you would like to pass an orderId different than that of the original transaction. Otherwise, the original transaction's getOrderId() value will be copied over to the refund. On PayPal transactions, this field maps to the PayPal invoice number. PayPal invoice numbers must be unique in your PayPal business account. Maximum 255 characters or 127 for PayPal transactions.

.surchargeAmount(…)BigDecimal
The surcharge amount to refund. For full refunds, Braintree automatically copies the surcharge amount from the original sale transaction. For partial refunds, the merchant must pass the appropriate surcharge amount. The original sale transaction must have been surcharged.

RequirementsAnchorIcon

  • Transaction status must be settled or settling.
  • Refund amount can't be greater than remaining non-refunded amount of the original transaction.
  • Transaction can't be refunded again after being completely refunded.
  • Transactions held in escrow can only be refunded in full. Attempts to partially refund an escrow transaction will throw a validation error.

ExamplesAnchorIcon

Partial refundsAnchorIcon

If you only want to refund a portion of the transaction, specify the amount to refund:
  1. Java
Result<transaction> result = gateway.transaction().refund(
    "a_transaction_id",
    new BigDecimal("50.00")
);
result.isSuccess(); // true
Transaction refund = result.getTarget();
refund.getType(); // Transaction.Type.CREDIT
refund.getAmount(); // 50.00

Result<transaction> result = gateway.transaction().refund(
    "a_transaction_id",
    new BigDecimal("10.00")
);
result.isSuccess(); // true
Transaction refund = result.getTarget();
refund.getType(); // Transaction.Type.CREDIT
refund.getAmount(); // 10.00
We support single and multiple partial refunds on a given transaction. You can continue to refund a transaction as many times as you like, as long as the sum of the refund amounts is less than the amount of the initial transaction.

If you have already partially refunded a transaction and you perform another refund without specifying the balance, we will refund the remaining non-refunded amount of the transaction.

Refund processor declinesAnchorIcon

If using the most current SDK, and the processor declines the refund, the response will have the processorResponseCode available. See the transaction statuses page for additional information on the Processor Declined response. If using an older SDK version, and the processor declines the refund, you may receive a validation error in lieu of a processor response code.
  1. Java
Transaction transaction = result.getTransaction();
transaction.getStatus(); // Transaction.Status.PROCESSOR_DECLINED
transaction.getProcessorResponseCode(); // e.g. "2005"
transaction.getProcessorResponseText(); // e.g. "Invalid Credit Card Number"

Settlement failuresAnchorIcon

If the processor declines the capture for the refund transaction, the transaction object will have the processorSettlementResponseCode available. See the transaction statuses page for additional information on the Settlement Declined response.
  1. Java
Transaction transaction = result.getTransaction();
transaction.getStatus(); // Transaction.Status.SETTLEMENT_DECLINED
transaction.getProcessorSettlementResponseCode(); // e.g. "4001"
transaction.getProcessorSettlementResponseText(); // e.g. "Settlement Declined"

Issuing a creditAnchorIcon

You can use credit transactions to give a customer money. However, you should refund to an existing payment method whenever possible.

The only required parameters to create a credit transaction are the amount and the payment method token.
  1. Java
TransactionRequest request = new TransactionRequest()
    .amount(new BigDecimal("100.00"))
    .paymentMethodToken("aToken")
    .done();

Result<transaction> result = gateway.transaction().credit(request);