Related API operations

When you create the simplest Express Checkout integration, you specify Sale as the payment action, enabling you to receive the money right away. You can also set up a payment to be collected later, or refund a payment.

Sale payment action for Express Checkout

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:

PAYMENTREQUEST_<n>_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:

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 for Express Checkout

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:

PAYMENTREQUEST_<n>_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.

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.To issue multiple re-authorizations, you must use the Authorize and Capture API.

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.

This table shows API operations associated with Authorization payment action in Express Checkout:

Order payment action for Express Checkout

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:

PAYMENTREQUEST_<n>_PAYMENTACTION=Order

Creating a PayPal Order indicates that the buyer has consented to the purchase but does not place the funds on hold. After creating the Order, you can capture the order directly without any additional authorization, or you can create an authorization API call to place funds on hold until you are ready to capture. Since the order does not place funds on hold, it is advised that you follow the second approach and create an authorization instead of capturing an Order directly.

An Order enables you to create multiple authorizations over the 29 days. You can capture multiple payments for each authorization, up to 115% (not to exceed USD $75) more than the amount you specify in the DoExpressCheckoutPayment request.

As a merchant, you might use this technique to accept orders for multiple items, including some items that are not available for shipment when the buyer places the order. As the items become available, you make subsequent basic authorizations to ensure that the buyer still has the funds to purchase each item. You might use this technique for:

To issue multiple re-authorizations, use DoAuthorization NVP/SOAP and DoCapture NVP/SOAP API calls.

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.

This table shows API operations associated with Order payment action in Express Checkout:

Issue refunds

You can issue a full or partial refund for up to the full amount of the payment. You can make a refund for payments captured initially or as part of a later settlement.

The default refund period is 180 days from the transaction date.

If you refund a payment for goods or services, there are no fees to make the refund, but the fees you originally paid as the seller are not returned to you. The amount of the refunded payment will be deducted from your PayPal account.

If the transaction occurred after the default refund period of 180 days, you cannot use RefundTransaction to issue the refund. Instead, you can use one of these methods to manually issue a credit:

For more about refunds, see All about refunds at PayPal.

Use the RefundTransaction API to issue one or more refunds associated with a transaction. The transaction is identified by a transaction ID that PayPal assigns when the payment is captured. When you call the RefundTransaction API, PayPal responds with another transaction ID, which is associated with the refund (not the original transaction), and additional information about the refund. This information identifies:

To issue a refund:

API Idempotency

You can use the MsgSubID, or Message Submission ID, to track pending or failed requests.

These API requests and responses now include MsgSubID:

Idempotency enables you to correlate request payloads with response payloads, eliminate duplicate requests, and retry failed requests or requests with unclear responses.

For example, when you include a previously specified MsgSubID in a request, PayPal returns the latest status of the previous request that used that same MsgSubID. Conversely, when you omit the MsgSubID from a request, PayPal duplicates the request.

Scenarios in which idempotency come into play:

Example

The following DoAuthorization request includes a MsgSubID:

<transactionID>O-87H32160HB8486131</transactionID>
<transactionEntity>Order</transactionEntity>
<amount currencyID="USD">10</amount>
<msgSubID>81d4fae-7dec-11d0-a765-00a0c91e6bf6</msgSubID>

Usage notes