See also the Braintree_Transaction response object.

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

PHP
Click to copy
Copied
$result = Braintree_Transaction::refund('the_transaction_id');

If the transaction cannot be found, you'll receive a Braintree_Exception_NotFound exception.

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.

PHP
Click to copy
Copied
$result->success
# false
Arguments
transactionId required, string

The unique transaction identifier.

Additional Parameters
'amount' String

The amount to refund. This value must be greater than 0, and cannot 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.

'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 orderId 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.

Requirements

  • Transaction status must be settled or settling.
  • Refund amount cannot be greater than remaining non-refunded amount of the original transaction.
  • Transaction cannot 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.

Examples

Partial refunds

If you only want to refund a portion of the transaction, specify the amount to refund:

PHP
Click to copy
Copied
$result = Braintree_Transaction::refund('a_transaction_id', '50.00');
$result->success
# true
$result->transaction->type
# 'credit'
$result->transaction->amount
# "50.00"

$result = Braintree_Transaction::refund('a_transaction_id', '10.00');
$result->success
# true
$result->transaction->type
# 'credit'
$result->transaction->amount
# "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.

note

It's best practice to allow each partial refund call to complete successfully before creating any more for the same transaction. If a single transaction has too many simultaneous refund requests, some are likely to fail, returning an error from the gateway.

Settlement failures

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.

PHP
Click to copy
Copied
$result->success
# false

$result->transaction->status
# "settlement_declined"

$result->transaction->processorSettlementResponseCode
# e.g. 4001

$result->transaction->processorSettlementResponseText
# e.g. "Settlement Declined"

Issuing a credit

important

Credit transactions are disabled by default. If an attacker gets your API keys, they could transfer money out of your merchant account and put it on any credit card. If you need credit transactions to be enabled, please contact support.

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.

PHP
Click to copy
Copied
$result = Braintree_CreditCard::credit(
  'the_token',
  ['amount' => '100.00']
);

Still have questions?

If you can’t find an answer, contact our Support team.