Transaction
Transaction: Submit For Settlement
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
result = gateway.transaction.submit_for_settlement("the_transaction_id")
if result.success?
settled_transaction = result.transaction
else
puts(result.message)
end
Arguments
amount
, BigDecimalAn 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 us for details.
If you settle an amount that is less than what was authorized, the transaction object will return the amount settled.
transaction_id
required, Stringauthorized
for settlement.Additional Parameters
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 us.
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.
:discount_amount
BigDecimalA Level 3 field that specifies the discount amount that was included in the total transaction amount. It can't be negative, and it does not add to the total transaction amount. This Braintree line-item field is not used by PayPal.
The line items for this transaction. It can include up to 249 line items. If your merchant account has been configured for Level 3 processing this field will be passed to the processor on your behalf.
:commodity_code
String:description
String:discount_amount
BigDecimal:kind
StringIndicates whether the line item is a debit (sale) or credit (refund) to the customer. Accepted values:
"debit"
"credit"
:name
String:product_code
String:quantity
BigDecimal:total_amount
BigDecimal:unit_amount
BigDecimal:unit_of_measure
String:unit_tax_amount
BigDecimal:url
String:order_id
String:purchase_order_number
StringA Level 2 field that can be used to pass a purchase order identification value of up to 12 ASCII characters for AIB and 17 ASCII characters for all other processors.
:company
String:country_code_alpha2
String:country_code_alpha3
String:country_code_numeric
String:country_name
String:extended_address
String:first_name
String:last_name
String:locality
String:postal_code
String:region
String:street_address
String:shipping_address_id
String:shipping_amount
BigDecimalA Level 3 field that specifies the shipping cost on the entire transaction. It can't be negative, and it does not add to the total transaction amount.
:ships_from_postal_code
StringA Level 3 field that specifies the postal code of the shipping location.
:tax_amount
BigDecimalA Level 2 field that specifies the amount of tax that was included in the total transaction amount. The value can't be negative, and in most cases, it must be greater than zero in order to qualify for lower interchange rates. It does not add to the total transaction amount.
:tax_exempt
boolA Level 2 field that indicates whether or not the transaction should be considered eligible for tax exemption. This does not affect the total transaction amount.
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.
Authorization adjustments
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.
- Ruby
result = gateway.transaction.submit_for_settlement("the_transaction_id", "35.00")
Specifying Level 2 and 3 data
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.
- Ruby
result = gateway.transaction.submit_for_settlement("transaction_id", nil, {
:purchase_order_number => "12345",
:tax_amount => "1.23",
:shipping_amount => "1.00",
:discount_amount => "0.00",
:ships_from_postal_code => "60654",
:line_items => [
{
:name => "Product Name",
:kind => "debit",
:quantity => "10.0000",
:unit_amount => "9.5000",
:unit_of_measure => "unit",
:total_amount => "95.00",
:tax_amount => "5.00",
:discount_amount => "0.00",
:product_code => "54321",
:commodity_code => "98765"
}
]
})
if result.success?
settled_transaction = result.transaction
else
puts(result.message)
end
Shipping address information
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.
Specifying order ID
You can pass additional information about a transaction by adding the order_id when submitting the transaction for settlement.
- Ruby
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