Related API Operations

Important: This integration method is deprecated as of January 1, 2017. PayPal continues to support existing merchants using this method, but please be advised new features and enhancements will not be applied to these integrations. For new integrations, see the PayPal Checkout Integration Guide.

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.

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:

API Operation Description
DoCapture Capture an authorized payment.
DoReauthorization Reauthorize a payment.
DoVoid 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 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 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:

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

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

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

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

    REFUNDTYPE=Full
    

    or

    REFUNDTYPE=Partial
    
  3. For a partial refund, specify the refund amount, including the currency.

    AMT amount
    CURRENCYCODE currencyID
    
  4. For a partial refund, specify the memo description.

    NOTE description
    
  5. Execute the RefundTransaction operation.

  6. Check the acknowledgment status in the RefundTransaction response to ensure that the operation was successful.

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:

  • If an API request that includes a MsgSubID times out, a client application can retry the original request with the same MsgSubID. If the request has finished processing, PayPal then provides the latest status of the request and might return a 11607 Duplicate request for specified Message Submission ID warning code and message.
  • When you send two simultaneous API requests with same MsgSubID, PayPal processes the first request and might fail the second request with the 11604 Request for Message Submission ID already in progress error code and message.

Note:

  • Idempotency is available with API version 74.0 and later.
  • For DoExpressCheckoutPayment, you can use the token in place of the MsgSubID. For multiple payments, use a combination of the token and the Express Checkout PaymentRequestID field in place of the MsgSubID.

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

  • 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 succeeds. If the original request fails, 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. For example, the original request makes a payment and status is Complete. Later, the caller refunds the payment. If the caller resubmits the original request with the original MsgSubId value, the response shows a payment status of Refunded.
  • The result in subsequent responses is different from the original transaction response and returns SuccessWithWarning rather than Success.
Feedback