See also the Transaction response object.

If you do not use the options.submit_for_settlement option with Transaction.sale(), then you will have to explicitly submit the transaction for settlement.

Ruby
Copy
Copied
result = gateway.transaction.submit_for_settlement("the_transaction_id")

if result.success?
  settled_transaction = result.transaction
else
  puts(result.message)
end
This code snippet now uses gateway instance methods instead of class-level methods. Learn more.

If the transaction can't be found, it will raise a Braintree::NotFoundError.

Arguments
transaction_id required, String

The unique transaction identifier. You can only submit transactions that have a status of authorized for settlement.

amount BigDecimal or String

An amount to submit for settlement. Must be greater than 0. You can't 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.

If you settle an amount that is less than what was authorized, the transaction object will return the amount settled.

Additional Parameters
:descriptor

Dynamic descriptors are not enabled on all accounts by default. If you receive a validation error of 92203 or if your dynamic descriptors are not displaying as expected, please contact our Support team.

Dynamic descriptors are sent on a per-transaction basis and define what will appear on your customers' credit card statements for a specific purchase. The clearer the description of your product, the less likely customers will issue chargebacks due to confusion or non-recognition.

See the dynamic descriptor example for additional information.

:order_id 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. Maximum 255 characters or 127 for PayPal transactions.

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 our Support team for details.

Ruby
Copy
Copied
result = gateway.transaction.submit_for_settlement("the_transaction_id", "35.00")
This code snippet now uses gateway instance methods instead of class-level methods. Learn more.

Specifying order ID

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

note

When adding an order_id in Ruby, you must also specify the amount to settle. If you want to settle the entire amount, pass nil.

Ruby
Copy
Copied
result = gateway.transaction.submit_for_settlement("transaction_id", nil, {
  order_id: "order_id"
})

if result.success?
  settled_transaction = result.transaction
else
  puts(result.message)
end
This code snippet now uses gateway instance methods instead of class-level methods. Learn more.

Still have questions?

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