PayPal Merchant API Release Notes - Version 109.0

Version 109 of the Merchant API includes the following PayPal releases:

Code release version Release date Description
110 02/04/2014 No changes to the API.
109 10/22/2013 Changes to the API are described below.

These release notes address the API operations within the PayPal Merchant API WSDL and associated schemas:

The document covers changes to the Merchant APIs, which include:

  • Express Checkout
  • Direct Payment
  • Authorization and Capture
  • Recurring Payments
  • Mass Pay
  • Button Manager

These products use this API:

  • PayPal Payments Standard
  • Website Payments Pro

Announcements

A new card verification feature is now available for Website Payments Pro merchants as well as to PayPal Payments Advanced and PayPal Payments Pro (Payflow) merchants. This feature is used to verify that a cardholder’s account is in good standing without processing a purchase transaction or applying a card authorization. Website Payments Pro merchants can refer to the feature details below. PayPal Payments Advanced and PayPal Payments Pro (Payflow) merchants should refer to the Payflow Gateway Developer Guide Revision History for integration details.

Affected products

These products are affected by this release:

  • Express Checkout
  • Website Payments Pro

Express Checkout and Website Payments Pro

For a current list of known issues, go to the PayPal Notifications page and enter the product or API of interest, such as Express Checkout, in the search box.

New API operations

There are no new API operations.

Changed API operations

There are no changed API operations.

Schema changes

Name PaymentDetailsType.PaymentCategoryType in:
SetExpressCheckoutRequestDetailsType
GetExpressCheckoutDetailsResponseDetailsType
DoExpressCheckoutPaymentRequestDetailsType
DoDirectPaymentRequestDetailsType
DoReferenceTransactionRequestDetailsType
Part of Schema Element
Type of Change New enumeration value
Description The enumeration value LocalDelivery was added to the SOAP field PaymentCategoryType of the PaymentDetailsType. The equivalent NVP field BucketCategoryType will take the int value 2 for local deliveries. These fields can be specified or returned in the following API operations: SetExpressCheckout (NVP | SOAP), GetExpressCheckoutDetails (NVP | SOAP), DoExpressCheckoutPayment (NVP | SOAP), DoDirectPayment (NVP | SOAP), DoReferenceTransaction (NVP | SOAP).

New features

Card verifications

Available to all US, UK, and Canadian merchants using Website Payments Pro.

PayPal now supports card verifications also referred to as authorizations without purchase or $0 auths. This feature is used to verify that a cardholder’s account is in good standing without processing a purchase transaction or applying a card authorization. It is available for the majority of currencies.

Cardholder experience and security

  • No authorization or hold is placed on the card holder’s account, so the transaction does not appear on the card holder’s statement. This feature is used for card verification purposes only.
  • The card issuer will decline invalid cards or those reported as lost or stolen.
  • AVS and CVV results are returned on card verifications where supported by the issuer.

Integration summary

  • The DoDirectPayment (NVP | SOAP) API operation has been changed to accept an authorization in the amount of $0.
  • A successful card verification returns Ack=SuccessWithWarning. The response message also includes the code 10574 with the short message Credit Card Verified, so merchants do not mistake this for a financial transaction. If the card is invalid, a typical error response is returned with Ack=Failure and an error message.
  • Capture, Re-authorizations and void attempts on card verifications are not permitted and will return error code 10575.
  • Currently, only Mastercard and Visa support this feature. If the card issuer does not support card verifications, error code 10525 is returned.
  • Merchants who offer free trial periods and recurring payments can use this feature to verify the card prior to extending the service. Other merchants who only need to charge the card holder one time after a successful card verification can process a reference transaction using the DoReferenceTransaction (NVP | SOAP) API operation.

See integration details.

Reporting, order processing, and notification

  • On the paypal.com transaction History page, the Completed status is displayed for a successful $0 Authorization transaction.
  • Merchants using the Instant Payment Notification service should also receive notifications for card verifications.
  • Similar to other transaction types, the GetTransactionDetails (NVP | SOAP) and TransactionSearch (NVP | SOAP) API operations can be used to lookup card verification transaction details.

Note: The card networks discourage the use of $1 authorizations as a method of verifying card status. The rule is that you should only authorize amounts greater than zero on transactions that you intend to capture.

Per transaction fees will apply for card verifications, and there is no percentage or discount rate fee associated with these transactions. For fee information:

  • Go to the PayPal Merchant Fees page.
  • In the Complete Payment Solutions section, expand View all discounts and fees.
  • Scroll to view the per transaction fee for Uncaptured Authorization.

Changed functionality

No existing functionality has changed in this release.

Additional documentation updates

Express checkout - Additional documentation updates

Updates to the Merchant API reference and Express Checkout documentation (Feb. 14, 2014)

Updates to the Merchant API reference and Express Checkout documentation (Feb. 06, 2014)

Updates to the Merchant API reference and Express Checkout documentation (Jan. 30, 2014)

R110 updates - published prior to the actual release date on Feb. 05

  • Important update for merchants using Recurring Payments for Website Payments Pro. PayPal will cancel recurring payment profiles if a recurring transaction is declined with specific PaymentAdviceCode values that indicate the merchant should not attempt to process the card again. In the event of a cancelled profile, PayPal will send an email notification to the merchant. For information on the PaymentAdviceCode response field, see the DoDirectPayment API operation (NVP | SOAP).

    Developers or partners using reference transactions to provide recurring payment or subscription support for PayPal Payments Pro merchants (outside of PayPal Recurring Payments) are responsible for stopping the subscription and should not try again with the same card if the Payment Advice codes 03 and 21 are returned.

    Added the error code 10577 (This transaction cannot be processed. The merchant must not attempt payment on this card again for this buyer) to the Recurring Payments errors section of the error codes page.

  • The Website Payments Pro DoDirectPayment (NVP | SOAP) API operation now supports addresses in Guatemala (GT), Laos (LA), and Papua New Guinea (PG). See the country codes page for a list of all countries supported by Website Payments Pro and those supported by Express Checkout.

  • Added the Mass Payments failed transaction IPN reason code 9302 (Transaction was declined) to the MassPay IPN variables and the API section of the MassPay integration guide.

Updates to the Merchant API reference and Express Checkout documentation (Jan. 22, 2014)

  • Added the DoExpressCheckoutPayment NVP field SKIPBACREATION or the SOAP field SkipBACreation. This field is used for reference transactions during billing agreement creation. Merchants who offer a store account can control whether PayPal must create a billing agreement or if billing agreement creation should be skipped.

Updates to the Merchant API reference and Express Checkout documentation (Jan. 15, 2014)

  • Updated the URL to the PayPal SDKs.
  • Added information about integrating with Bill Me Later, China Union Pay, ELV and other funding options in Express Checkout, using the SetExpressCheckout NVP field USERSELECTEDFUNDINGSOURCE or the SOAP field UserSelectedFundingSource.
  • Added a PayPal button image reference, which displays the redesigned PayPal buttons.

Updates to the Merchant API reference and Express Checkout documentation (Jan. 08, 2014)

  • Added to the currency codes page information about the Multi-currency feature, supported currencies and any default per transaction amount limits.

Updates to the Merchant API reference and Express Checkout documentation (Oct. 23, 2013)