Handling Payment Settlements

You can use PayPal API operations to handle the capture of payments authorized using Express Checkout and manage Express Checkout authorization and order payment actions.

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 enables you to capture multiple payments up to 115% of, or USD $75 more than, the amount you specify in the DoExpressCheckoutPayment request. Choose this payment action if you need to ship the goods before capturing the payment or if there is some reason not to accept the payment immediately.

The honor period, for which funds can be held, is three days. The valid period, for which the authorization is valid, is 29 days. You can reauthorize the 3-day honor period at most once within the 29-day valid period.

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