Handling Payment Settlements

You can use PayPal API operations to:

Sale Payment Action

A sale payment action represents a single payment that completes a purchase for a specified amount.

A sale is the default Express Checkout payment action; however, you can also specify the following action in your SetExpressCheckout and DoExpressCheckoutPayment requests:

PAYMENTACTION=Sale

A sale is the most straightforward payment action. Choose this payment action if the transaction, including shipping of goods, can be completed immediately. To use this payment action:

  • The final amount of the payment must be known when you invoke the DoExpressCheckoutPayment API operation.
  • You should intend to fulfill the order immediately, such as would be the case for digital goods or for items you have in stock for immediate shipment.

After you execute the DoExpressCheckoutPayment API operation, the payment is complete and further action is unnecessary. You cannot capture a further payment or void any part of the payment when you use this payment action.

Authorization Payment Action

An authorization payment action represents an agreement to pay and places the buyer’s funds on hold for up to three days.

To set up an authorization, specify the following payment action in your SetExpressCheckout and DoExpressCheckoutPayment requests:

PAYMENTACTION=Authorization

An authorization places a hold on the funds and is valid for 29 days. After a successful authorization, PayPal recommends that you capture the funds within the three-day honor period. Success of the capture is subject to risk and availability of funds on the authorized funding instrument. Within the 29-day authorization period, you can issue multiple re-authorizations after the honor period expires. A re-authorization generates a new Authorization ID and restarts the honor period and any subsequent capture should be performed on the new Authorization ID. If you do a re-authorization on the 27th day of the authorization, you get only two days of honor period.

You can capture less than the original authorization, full authorization amount, or even more than the authorization amount (up to 115% of the original authorization or $75 USD more, whichever is less) in the DoExpressCheckoutPayment request.

You can void an authorization, in which case, the uncaptured part of the amount specified in the DoExpressCheckoutPayment request becomes void and can no longer be captured. If no part of the payment has been captured, the entire payment becomes void and nothing can be captured.

Table 1. API operations associated with authorization payment actions

API Operation Description
DoCapture

Capture an authorized payment

DoReauthorization Reauthorize a payment
DoVoid Void an order or an authorization

Order Payment Action

An order payment action represents an agreement to pay one or more authorized amounts up to the specified total over a maximum of 29 days.

To set up an order, specify the following payment action in your SetExpressCheckout and DoExpressCheckoutPayment requests:

PAYMENTACTION=Order

An order enables you to create multiple authorizations over the 29 days; each authorization you create places the buyer’s funds on hold for up to three days. You can capture multiple payments for each authorization, up to 115% of, or USD $75 more than, the amount you specify in the DoExpressCheckoutPayment request.

Note: The default number of child authorizations in your PayPal account is 1. To do multiple authorizations please contact PayPal to request an increase.

This payment action provides the most flexibility and should be used when either a sale or one authorization plus one reauthorization do not meet your needs. Situations in which orders are appropriate include the handling of

  • Back orders, in which available merchandise is sent immediately and the remaining merchandise is sent when available, which may include more than two shipments.
  • Split orders, in which merchandise is sent in more than one shipment, perhaps to different addresses, and you want to collect a payment for each shipment.
  • Drop shipments, which are shipments from other vendors for which you accept the payment.

You cannot reauthorize an authorization. You handle the need to reauthorize, for example when the hold period or valid period of an authorization expires, simply by creating another authorization.

You can void an order or an authorization created from the order. If you void an order, the uncaptured part of the amount specified in the DoExpressCheckoutPayment request becomes void and can no longer be captured. If no part of the payment has been captured, the entire payment becomes void and nothing can be captured.

If you void an authorization associated with the order, the uncaptured part of the amount specified in the authorization becomes void and can no longer be captured. If no part of the authorization has been captured, the entire authorized payment becomes void.

Table 2. API operations associated with order payment actions

API Operation Description
DoAuthorization Authorize a payment
DoCapture Capture an authorized payment
DoVoid Void an order or an authorization