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:

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

Authorized funds are held during the three-day honor period.

The authorization is valid during the 29-day valid period.

After the honor period expires, you can re-authorize the payment, which restarts the three-day honor period. You can re-authorize a payment multiple times during the valid 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.

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.

Note: You can make up to 10 authorizations per Order. If you find your account limits the number of authorizations per Order, please contact PayPal Customer Support to request an increase in the number of authorizations (up to 99 authorizations per Order).

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:

Back orders – You send available merchandise immediately and the remaining merchandise when it becomes available. This may include more than two shipments.

Split orders – You send merchandise in more than one shipment, perhaps to different addresses, and you collect a payment for each shipment.

Drop shipments – You can drop shipments from other vendors. These are shipments for which you've accept payment.

To issue multiple re-authorizations, use DoAuthorizationNVP/SOAP and DoCaptureNVP/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.

Issuing Refunds

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.

Note: 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:

You 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. 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:

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:

In the RefundTransaction request, specify the transaction ID of the transaction whose payment you want to refund.

TRANSACTIONID=transaction_id

Specify the kind of refund, which is either Full or Partial.

REFUNDTYPE=Full

or

REFUNDTYPE=Partial

For a partial refund, specify the refund amount, including the currency.

AMT=amount
CURRENCYCODE=currencyID

For a partial refund, specify the memo description.

NOTE=description

Execute the RefundTransaction operation.

Check the acknowledgment status in the RefundTransaction response 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:

If an API request sent with a MsgSubID times 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 11607 warning code (Duplicate request for specified Message Submission ID).

If a client application sends two API requests with same MsgSubID at the same time, PayPal processes the first request and the other may fail with 11604 error code (Request for Message Submission ID already in progress).

Note:

Idempotency is available with API version 74.0 and higher.

For DoExpressCheckoutPayment, you can use the token in place of the MsgSubID. For multiple payments, a combination of the token and the Express Checkout PaymentRequestID field should be used in place of the MsgSubID.

Example

The following example shows MsgSubID used as part of a DoAuthorization request:

Usage Notes

The MsgSubID must be unique for each request and, as a best practice, should be unique to an API call type. For example, DoAuthorization, DoCapture.

PayPal recommends using the UUID standard for assigning a MsgSubID to 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 MsgSubID after 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 MsgSubId is resubmitted, the response will indicate that the payment status is Refunded.

The result in subsequent responses will be different from the original transaction response and will return SuccessWithWarning instead of Success.