Transaction: Submit For Settlement

See also the Transaction response object.

If you do not use the options.submitForSettlement option with Transaction: Sale, then you will have to explicitly submit the transaction for settlement.

$result = $gateway->transaction()->submitForSettlement('the_transaction_id');

if ($result->success) {
    $settledTransaction = $result->transaction;
} else {
    print_r($result->errors);
}

If the transaction can't be found, you'll receive a Braintree\Exception\NotFound exception.

Arguments

Additional Parameters

Examples

Specifying settlement amount

If you want to settle for an amount that is different from the total authorization amount, you can specify the amount to settle. If you do not specify, the entire amount will be settled.

note

You can only submit for settlement for an amount that is less than the total authorization amount one time. To submit more than once, you will need to use multiple partial settlements; this method is available for all PayPal transactions and some credit card transactions for select merchants.

Authorization adjustments

availability

Authorization adjustments are available for select merchants and processors. See our support articles for details.

For eligible merchants, authorization adjustments occur automatically when you submit for settlement for an amount greater or less than the original authorized amount.

Each adjustment attempt is recorded as an adjustment detail, which is returned on the transaction response object. Adjustment details allow you to determine decline responses and track the overall success rate of auth adjustments.

You can account for real-time decline responses in the form of validation errors.

If you have questions regarding auth adjustment eligibility or functionality, please contact us for details.

$result = $gateway->transaction()->submitForSettlement('the_transaction_id', '35.00');

Specifying Level 2 and 3 data

availability

Level 2 and 3 processing via submit for settlement requires internal approval. Please contact us if you’re interested in this functionality. See our Level 2 and 3 processing overview for more details.

In some cases, transaction amounts, and by extension Level 2 and 3 parameters, are not finalized until the transaction is ready to be submitted for settlement. This functionality allows you to apply Level 2 and 3 parameters when submitting a transaction for settlement instead of specifying them in the transaction sale call.

note

Level 2 and 3 data provided via submit for settlement will override all Level 2 and 3 data previously provided in a sale request. If you wish to pass Level 2 and 3 data, we recommend utilizing either transaction.sale or transaction.submit_for_settlement, but not both at the same time.

$result = $gateway->transaction()->submitForSettlement('transactionId', null, [
    'purchaseOrderNumber' => '12345',
    'taxAmount' => '5.00',
    'shippingAmount' => '1.00',
    'discountAmount' => '0.00',
    'shipsFromPostalCode' => '60654',
    'lineItems' => [
        [
            'name' => 'Product',
            'kind' => Braintree\TransactionLineItem::DEBIT,
            'quantity' => '10.0000',
            'unitAmount' => '9.5000',
            'unitOfMeasure' => 'unit',
            'totalAmount' => '95.00',
            'taxAmount' => '5.00',
            'discountAmount' => '0.00',
            'productCode' => '54321',
            'commodityCode' => '98765'
        ]
    ]
]);

if ($result->success) {
  // See $result->transaction for details
} else {
  // Handle errors
}

note

When adding level 2 and 3 data in PHP, you must also specify the amount to settle. If you want to settle the entire amount, pass null.

Shipping address information

availability

Sending shipping address fields via submit for settlement requires internal approval. Please contact us if you’re interested in this functionality.

In some cases, the shipping address information cannot be determined until the transaction is ready to be submitted for settlement. This functionality allows you to apply shipping address fields when submitting a transaction for settlement instead of specifying them in the transaction sale call. If shipping address parameters are applied via submit for settlement, they will override any corresponding shipping address parameters applied on the sale. We recommend using either transaction.sale or transaction.submit_for_settlement to send shipping address parameters, but not both at the same time.

note

Shipping address includes the Level 3 fields shipping.postalCode and shipping.countryCodeAlpha3.

Specifying order ID

You can pass additional information about a transaction by adding the orderId when submitting the transaction for settlement.

note

When adding an orderId in PHP, you must also specify the amount to settle. If you want to settle the entire amount, pass null.

$result = $gateway->transaction()->submitForSettlement('transactionId', null, [
  'orderId' => 'orderId'
]);

if ($result->success) {
  // See $result->transaction for details
} else {
  // Handle errors
}