Merchant API v92.0 release notes

This release note addresses the API operations within the PayPal Merchant API WSDL and associated schemas:

The Merchant APIs include:

  • Express Checkout
  • Direct Payment
  • Recurring Payments
  • Mass Pay
  • Button Manager
  • PayPal Payments Standard
  • Website Payments Pro

Affected products

This release affects these products:

  • Express Checkout
  • PayPal Payments Pro — See Express Checkout section for related release notes

Express Checkout

For a current list of PayPal product and API issues, as well as upcoming maintenance events, go to PayPal Status.

Express Checkout - Changed calls

  1. DoAuthorization
  2. DoReferenceTransaction
  3. RefundTransaction
  4. DoCapture

Express Checkout - Schema changes

Name Part of schema Type of change
DoAuthorizationRequestType.MsgSubID Element New
DoAuthorizationResponseType.MsgSubID Element New
DoReferenceTransactionRequestDetailsType.MsgSubID Element New
DoReferenceTransactionResponseDetailsType.MsgSubID Element New
RefundTransactionRequestType.MsgSubID Element New
RefundTransactionResponseType.MsgSubID Element New
DoCaptureRequestType.MsgSubID Element New
DoCaptureResponseType.MsgSubID Element New

Express Checkout - New features

Idempotency through MsgSubID1

Idempotency has been added to the request and response for these API calls:

  1. DoAuthorization
  2. DoReferenceTransaction
  3. RefundTransaction
  4. 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 eliminate duplicate requests. A request sent with a previously accompanying MsgSubID (Message Submission ID) returns with latest status of 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. If the request is still or returns 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: For DoExpressCheckoutPayment, you can use the token in place of the MsgSubID. For multiple payments, a combination of the token and PaymentRequestID should be used in place of the MsgSubID.

Usage notes:

  • The MsgSubID must be unique for each request and API call type. For example, DoAuthorization, DoCapture, and so on.
  • PayPal recommends using the UUID standard for assigning MsgSubIDs to your requests.
  • 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 indicates that the payment status is Refunded.
  • The result in subsequent responses to an original transaction is different from the original response and returns SuccessWithWarning instead of Success.

Express Checkout - Additional documentation updates

Correction to TransactionSearch API reference documentation

The following TransactionSearch response field has been updated with additional values that were missing:

  • Type (SOAP), L_TYPEn (NVP)

Correction to DoExpressCheckout API reference documentation

The description for the following DoExpressCheckout response field has been updated with clarification on on the redirect URL:

  • SuccessPageRedirectRequested (SOAP, NVP)