<< User Interface Requirements

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.

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

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 authorizations for an Order in your PayPal account is 1. To make multiple authorizations for an Order, please contact PayPal Customer Support to request an increase in the number of authorizations per Order.

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 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 action in Express Checkout

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

Issuing Refunds

You can use the RefundTransaction PayPal API operation to issue refunds.

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

Note You cannot make a refund if the transaction occurred after the refund period has passed; typically, the refund period is 60 days.

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

  • DoAuthorization
  • DoReferenceTransaction
  • RefundTransaction
  • DoCapture

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

<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 (e.g. 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.

Integrating with SDKs >>