See also the Transaction response object.

availability

Multiple partial settlements are only available for PayPal transactions.

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:

  1. Authorize the entire order amount using transaction.sale().
    • Do not pass the submitForSettlement option or make a submitForSettlement call.
  2. Make a separate submitForPartialSettlement call for each portion you want to settle separately.
Node.js
gateway.transaction.submitForPartialSettlement("theParentAuthTransactionId", "10.00", {
  "orderId": "orderId"
}, function(err, result) {
  if (result.success) {
    var settledTransaction = result.transaction;
  } else {
    console.log(result.errors);
  }
});
Arguments
authorizedTransaction required, String

The transaction ID of the parent authorization. You can only submit transactions that have a status of authorized or settlement_pending for partial settlement.

amount required, String

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

Additional Parameters
discountAmount String

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.

lineItems

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 String

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.

description String

Item description. Maximum 127 characters.

discountAmount String

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

kind required, String

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

  • "debit"
  • "credit"
name required, String

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

productCode String

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

quantity required, String

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

taxAmount String

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

totalAmount required, String

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

unitAmount required, String

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.

unitOfMeasure String

The unit of measure or the unit of measure code. Maximum 12 characters.

unitTaxAmount String

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

url String

The URL to product information.

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

purchaseOrderNumber String

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 String

Company name. 255 character maximum.

countryCodeAlpha2 String

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

countryCodeAlpha3 String

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

countryCodeNumeric String

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

countryName String

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

extendedAddress String

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

firstName String

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

lastName String

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

locality String

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

postalCode String

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 String

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.

streetAddress String

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

shippingAddressId String

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

shippingAmount String

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.

shipsFromPostalCode String

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

taxAmount String

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.

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

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 to settled when either 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.
  • 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.

See also