Transaction
Transaction: Submit For Partial Settlement
See also the Transaction response object.
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:
- Authorize the entire order amount using
Transaction: Sale
.- Do not pass the submitForSettlement option or make a submitForSettlement call.
- Make a separate submitForPartialSettlement call for each portion you want to settle separately.
- For each call, specify the authorized-transaction and the amount to settle.
- Callback
- Promise
gateway.transaction.submitForPartialSettlement("theParentAuthTransactionId", "10.00", {
"orderId": "orderId"
}, function(err, result) {
if (result.success) {
const settledTransaction = result.transaction;
} else {
console.log(result.errors);
}
});
Arguments
amount
required, StringAn 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 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.
authorizedTransaction
required, StringThe transaction ID of the parent authorization. You can only submit transactions that have a status of authorized or settlement_pending for partial settlement.
Additional Parameters
discountAmount
StringA 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.
finalCapture
boolUse this field to indicate a partial shipment as final for the given parent authorization. Braintree will attempt to reverse the uncaptured amount with the issuer. This is supported on limited processors; contact us for details.
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.
commodityCode
Stringdescription
StringdiscountAmount
Stringkind
StringIndicates whether the line item is a debit (sale) or credit (refund) to the customer. Accepted values:
"debit"
"credit"
name
StringproductCode
Stringquantity
StringtotalAmount
StringunitAmount
StringunitOfMeasure
StringunitTaxAmount
StringupcCode
StringupcType
StringUPC type for the item. If specified, you must also provide the UPC code. Accepted values:
"UPC-A"
"UPC-B"
"UPC-C"
"UPC-D"
"UPC-E"
"UPC-2"
"UPC-5"
url
StringorderId
StringpurchaseOrderNumber
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
StringcountryCodeAlpha2
StringThe ISO 3166-1 alpha-2 country code specified in an address. The gateway only accepts specific alpha-2 values.
countryCodeAlpha3
StringThe ISO 3166-1 alpha-3 country code specified in an address. The gateway only accepts specific alpha-3 values.
countryCodeNumeric
StringThe ISO 3166-1 numeric country code specified in an address. The gateway only accepts specific numeric values.
countryName
StringThe country name specified in an address. We only accept specific country names.
extendedAddress
StringfirstName
StringcountryCode
StringnationalNumber
StringlastName
Stringlocality
StringphoneNumber
StringDeprecated.
We recommend using international_phone
. This functionality still exists in the gateway but is no longer documented. This parameter will be removed in the future.
postalCode
Stringregion
StringstreetAddress
StringshippingAddressId
StringshippingAmount
StringA 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.
shippingTaxAmount
StringA Level 3 field that specifies the amount of tax that was charged on the . The value can't be negative, and in most cases, it must be greater than zero if the shipping amount is greater than zero. It does not add to the total transaction amount.
shipsFromPostalCode
StringA Level 3 field that specifies the postal code of the shipping location.
taxAmount
StringA 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.
taxExempt
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.
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 > SETTLED.
- The parent transaction will move from SETTLEMENT_PENDING to SETTLED when any 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.
- The parent transaction has remained in SETTLEMENT_PENDING for longer than 30 days, regardless of the child transactions' status.
- 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 Settlement Transaction ID, 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.