Related API Operations
When you create the simplest Express Checkout integration,
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
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
- 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
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
An authorization enables you to capture multiple payments up
to 115% of, or USD $75 more than, the amount you specify in the
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
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
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
||Capture an authorized payment.|
||Reauthorize a payment.|
||Void an order or an authorization.|
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
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
This payment action provides the most flexibility and should be used when either a sale does not meet, 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
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
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 action in Express Checkout
||Authorize a payment.|
||Capture an authorized payment.|
||Void an order or an authorization.|
RefundTransaction PayPal API operation
to issue refunds.
RefundTransaction API to issue one or more
refunds associated with a transaction, such as a transaction created
by a capture of a payment. The transaction is identified by a transaction
ID that PayPal assigns when the payment is captured.
can refund amounts up to the total amount of the original transaction.
If you specify a full refund, the entire amount is refunded. If
you specify a partial refund, you must specify the amount to refund,
the currency, and a description of the refund, which is called a memo.
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:
- The gross amount of the refund, which is returned to the payer
- The amount of the refund associated with the original transaction fee, which is returned to you
- The net amount of the refund, which is deducted from your balance
To issue a refund:
RefundTransactionrequest, specify the transaction ID of the transaction whose payment you want to refund.
Specify the kind of refund, which is either
For a partial refund, specify the refund amount, including
For a partial refund, specify the memo description.
- Execute the
- Check the acknowledgement status in the
RefundTransactionresponse to ensure that the operation was successful.
Using API Idempotency
You can use the
MsgSubID (Message Submission ID) to help track pending or failed requests.
MsgSubID has been added to the request and response for following API calls:
Idempotency is useful in cases where a request has failed or if you are unsure about the results of an original request. It also helps to correlate request payloads with response payloads. Idempotency helps to eliminate duplicate requests, since a request sent with a previously accompanying
MsgSubID will return with the latest status of the previous request that used the same
MsgSubID. In contrast, a request with no accompanying
MsgSubID will instead duplicate the request.
Scenarios in which idempotency come into play:
In an API request sent with a
MsgSubIDtimes out, a client application can retry the original request using the accompanying
MsgSubID. If the request has finished processing, PayPal then provides the latest status of the request and might return a
11607warning code (
Duplicate request for specified Message Submission ID).
If a client application sends two API requests with same
MsgSubIDat the same time, PayPal processes the first request and the other may fail with
11604error code (
Request for Message Submission ID already in progress).
- Idempotency is available with API version
DoExpressCheckoutPayment, you can use the token in place of the
MsgSubID. For multiple payments, a combination of the token and the Express Checkout
PaymentRequestIDfield should be used in place of the
The following example shows
MsgSubID used as part of a
<transactionID>O-87H32160HB8486131</transactionID> <transactionEntity>Order</transactionEntity> <amount currencyID="USD">10</amount> <msgSubID>81d4fae-7dec-11d0-a765-00a0c91e6bf6</msgSubID>
MsgSubIDmust be unique for each request and, as a best practice, should be unique to an API call type (e.g.
PayPal recommends using the UUID standard for assigning a
MsgSubIDto your request, since it meets the 38 single-byte character limit for MsgSubID.
- Idempotency only applies when the original request was successful. If the original request results in an error, the original request is not saved.
PayPal reserves the right to expire a
MsgSubIDafter 13 days.
PayPal provides the status of a request at the current time and not the status of the initial request. Take for example, an initial request that makes a payment (status is
Complete). The payment is later refunded. If the original request with the original
MsgSubIdis resubmitted, the response will indicate that the payment status is
- The result in subsequent responses will be different from the original
transaction response and will return