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.

Python
result = gateway.transaction.submit_for_settlement("the_transaction_id")

if result.is_success:
  settled_transaction = result.transaction
else:
  print(result.errors)

If the transaction can't be found, it will throw a NotFoundError exception.

Arguments
transaction_id required, str

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

amount Decimal or str

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 us 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 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' Decimal or str

A 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.

'line_items'

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' str

Code used to classify items purchased and track the total amount spent across various categories of products and services. Different corporate purchasing organizations may use different standards, but the United Nations Standard Products and Services Code (UNSPSC) is frequently used. Maximum 12 characters. This Braintree line-item field is not used by PayPal.

'description' str

Item description. Maximum 127 characters.

'discount_amount' Decimal or str

Discount amount for the line item. Can include up to 2 decimal places. This value can't be negative. This Braintree line-item field is not used by PayPal.

'item_type' str

Optional type of the item, e.g. physical, digital, etc.

'kind' required, str

Indicates whether the line item is a debit (sale) or credit (refund) to the customer. Accepted values:

  • "debit"
  • "credit"
'name' required, str

Item name. Maximum 35 characters, or 127 characters for PayPal transactions.

'product_code' str

Product or UPC code for the item. Maximum 12 characters, or 127 characters for PayPal transactions.

'quantity' required, Decimal or str

Number of units of the item purchased. Can include up to 4 decimal places. This value can't be negative or zero.

'tax_amount' Decimal or str

Tax amount for the line item. Can include up to 2 decimal places. This value can't be negative.

'total_amount' required, Decimal or str

Quantity x unit amount. Can include up to 2 decimal places.

'unit_amount' required, Decimal or str

Per-unit price of the item. Maximum 4 decimal places, or 2 decimal places for PayPal transactions. This value can't be negative or zero.

'unit_of_measure' str

The unit of measure or the unit of measure code. Maximum 12 characters. This Braintree line-item field is not used by PayPal.

'unit_tax_amount' Decimal or str

Per-unit tax price of the item. Can include up to 2 decimal places. This value can't be negative or zero.

'url' str

The URL to product information.

'order_id' str

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.

'purchase_order_number' str

A 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.

'shipping'

Shipping address information associated with a specific customer ID.

'company' str

Company name. 255 character maximum.

'country_code_alpha2' str

The ISO 3166-1 alpha-2 country code specified in an address. The gateway only accepts specific alpha-2 values.

'country_code_alpha3' str

The ISO 3166-1 alpha-3 country code specified in an address. The gateway only accepts specific alpha-3 values.

'country_code_numeric' str

The ISO 3166-1 numeric country code specified in an address. The gateway only accepts specific numeric values.

'country_name' str

The country name specified in an address. We only accept specific country names.

'extended_address' str

The extended address information—such as apartment or suite number. 255 character maximum.

'first_name' str

The first name. The first name value must be less than or equal to 255 characters. Required if passing a PayPal shipping address.

'last_name' str

The last name. The last name value must be less than or equal to 255 characters. Required if passing a PayPal shipping address.

'locality' str

The locality/city. 255 character maximum. Required if passing a PayPal shipping address.

'postal_code' str

The postal code. Postal code must be a string of 4-9 alphanumeric characters, optionally separated by a dash or a space. Spaces and hyphens are ignored. Required if passing a PayPal shipping address.

'region' str

The state or province. For PayPal addresses, the region must meet PayPal's state restrictions; for all other payment methods, it must be less than or equal to 255 characters. Required if passing a PayPal shipping address.

'street_address' str

The street address. 255 character maximum. Required if passing a PayPal shipping address.

'shipping_address_id' str

A shipping address associated with a specific customer ID. The maximum number of addresses per customer is 50.

'shipping_amount' Decimal or str

A 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' str

A Level 3 field that specifies the postal code of the shipping location.

'tax_amount' Decimal or str

A 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' bool

A 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.

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.

Python
result = gateway.transaction.submit_for_settlement("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.

Python
result = gateway.transaction.submit_for_settlement("transaction_id", None, {
    "purchase_order_number": "12345",
    "tax_amount": "5.00",
    "shipping_amount": "5.00",
    "discount_amount": "1.00",
    "ships_from_postal_code": "60654",
    "line_items": [
        {
            "name": "Product",
            "kind": braintree.TransactionLineItem.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"
        }
    ]
})
q

if result.is_success:
  # See result.transaction for details
else:
  # Handle errors
note

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

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.postal_code and shipping.country_code_alpha3.

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 Python, you must also specify the amount to settle. If you want to settle the entire amount, pass None.

Python
result = gateway.transaction.submit_for_settlement("transaction_id", None, {
  "order_id": "order_id"
})

if result.is_success:
  # See result.transaction for details
else:
  # Handle errors