See also the Braintree_Transaction response object.

availability

Multiple partial settlements are only available for PayPal transactions.

This method allows you to settle multiple partial amounts against the same authorization, which is helpful if you send physical goods to customers in multiple shipments. You can create a parent authorization for the entire order amount, and when you’re ready to send each portion of the order, you can charge the customer for that portion in a separate child transaction.

To settle a transaction in multiple portions:

  1. Authorize the entire order amount using Braintree_Transaction::sale().
    • Do not pass the submitForSettlement option or make a submitForSettlement call.
  2. Make a separate submitForPartialSettlement call for each portion you want to settle separately.
PHP
Click to copy
Copied
$result = Braintree_Transaction::submitForPartialSettlement('theParentAuthTransactionId', '10.00');

if ($result->success) {
    $settledTransaction = $result->transaction;
} else {
    print_r($result->errors);
}
Arguments
authorizedTransaction required, string

The transaction ID of the parent authorization. You can only submit transactions that have a status of authorized for partial settlement.

amount required, String

An amount to submit for partial settlement against the parent authorization transaction. This amount to be partially settled must be greater than 0. You can make multiple partial settlement calls as long as the cumulative amount to be partially settled is less than or equal to the amount authorized by the parent transaction. You cannot settle more than the authorized amount unless your industry and processor support settlement adjustment (settling a certain percentage over the authorized amount); contact our Accounts team for details.

Additional Parameters
'orderId' string

Use this field to pass additional information about the transaction. On PayPal transactions, this field maps to the PayPal invoice number. PayPal invoice numbers must be unique in your PayPal business account.

Transaction settlement

  • Each partial settlement will create a new child transaction in the gateway with the same details as the original transaction, but with the amount specified in the submitForPartialSettlement call.
  • Once the child transaction is created, the parent will move to a settlement_pending status, whereas the child will move from authorized > submitted_for_settlement > settling > settled.
  • The parent transaction will move to settled when either of the following is true:
    • All child transactions are settled and the cumulative amount submitted for settlement across all child transactions is equal to the amount authorized on the parent transaction.
    • The original authorization is expired and there are one or more settled child transactions associated with the parent transaction.
  • Once the parent moves to the settled status, no further settlements can be created on that transaction.

Refunds

  • Once you've submitted a transaction for partial settlement, you can only issue a refund against the child transaction(s).
  • A refund on a child transaction can be up to the amount settled on the child.
  • A refund can be issued only when the corresponding transaction has fully settled and is in a settled state.

Control Panel visibility

  • The parent and child transactions will appear linked in the Control Panel as Authorized Transaction and Settled Transaction, respectively.
  • The parent transaction will show the child transaction(s) under the Settlement Information section on the transaction search in the Control Panel. Similarly, the child transactions will show the parent for authorization information.

See also

Still have questions?

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