How To Recover from Funding Failure Error Code 10486 in Express Checkout

If the funding option selected by the buyer fails in a DoExpressCheckoutPayment or a DoAuthorization call, a funding failure recovery process is available to merchants. Error code 10486 is returned to merchants when a buyer's payment fails due to a bad funding method (typically an invalid or maxed out credit card). If the merchant receives this error code from PayPal, the Merchant can redirect the buyer back to the PayPal page to select an alternate payment source or to add a new funding instrument.

Possible reasons for payment failure include:

  • The billing address associated with the financial Instrument could not be confirmed.
  • The transaction exceeds the card limit.
  • The transaction was denied by the card issuer.

Contents

Requirements

In the case of a funding failure in Express Checkout implementations that use either the PaymentAction type Sale or Authorization, the DoExpressCheckoutPayment API operation returns the funding failure error code 10486. For Express Checkout integrations with an order ID, where the PaymentAction type is Order, the DoAuthorization API operation returns this error code.

This feature is not applicable to:

  • Reference Transactions
  • Recurring Payments

Error Code Details

The Express Checkout error response parameters for the NVP and SOAP API formats are:

API Format Parameter Returned Value
SOAP
NVP
ErrorCode
L_ERRORCODE0
10486
SOAP
NVP
ShortMessage
L_SHORTMESSAGE0
This transaction couldn't be completed.
SOAP
NVP
LongMessage
L_LONGMESSAGE0
This transaction couldn't be completed. Please redirect your customer to PayPal.

You may redirect the buyer back to PayPal multiple times as long as this error code is returned; after that, prompt the buyer to choose another payment method available on your site.

Integration details

Because the integration steps for transactions with a PaymentAction value of Sale or Authorization differ from transactions with a PaymentAction value of Order, this section is divided into two parts:

PaymentAction is a Sale or Authorization

Upon receiving this error code, redirect the buyer back to PayPal using the existing Express Checkout token. On the PayPal page, the buyer is presented with an error message explaining the reason for the decline. Additionally, the buyer is given the option to select an alternate funding source or add a new one. After the buyer changes the financial instrument, you can reattempt sending the payment and completing it successfully.

Fig. 1 - DoExpressCheckoutPayment PaymentAction of Sale or Authorization diagram

Note: This feature makes no changes to the current token expiry period.

Integration Steps

Modify your front-end error code handling to redirect the customer back to PayPal when PayPal returns error code 10486. You should redirect the buyer back to PayPal using the same redirect URL that was used to originally start the checkout flow.

Example of the redirect URL and token:
https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-ABCDE12345

Proceed to the testing your integration section.

PaymentAction is an Order

On receiving this error code during a DoAuthorization API call based on an order id, redirect the buyer back to PayPal. The redirect URL should include the order id. If DoAuthorization is not called immediately, or if for any other reason the buyer is not online when the authorization is created, notify the buyer to log in to your website. Then on your website's order review page, present the buyer with an update order button that uses the redirect URL containing the order id to redirect the buyer back to PayPal. PayPal gives the buyer the option to select an alternate funding source or add a new one. After the buyer successfully changes the financial instrument, you can reattempt sending the payment and completing it successfully.

Fig. 2 - DoAuthorization PaymentAction of Order diagram

Note: This feature is not supported for a guest or multi-seller payment.

Integration Steps

Modify your front-end error code handling to redirect the customer back to PayPal when PayPal returns error code 10486. Redirect the buyer back to PayPal using a redirect URL containing the order id. If you do not call DoAuthorization immediately, or if for another reason the buyer is not online when you are creating the authorization, notify the buyer to log in to your website. Then on your website's order review page, present the buyer with an update order button that uses the redirect URL containing the order id to redirect the buyer back to PayPal.

Example of the redirect URL with order id:
https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout&order_id=O-4PS66146G25310203

Modify your back-end code to call DoAuthorization again if the return URL from PayPal contains retry_authorization=true.

Testing your integration

The PayPal Sandbox is a self-contained, virtual testing environment that mimics the live PayPal production environment. It provides a shielded space where you can watch your application process calls to the PayPal APIs, without touching any live PayPal accounts. By substituting fictitious sandbox accounts and their associated authentication credentials in your PayPal API calls, you can test and debug your application without referencing any real PayPal users or their PayPal accounts. See the PayPal Sandbox Testing Guide to quickly setup your Sandbox testing environment.

To test your error-handling code, configure a fictitious Sandbox buyer's PayPal account to return error 10486 when it is used to execute an Express Checkout payment in the Sandbox environment.

Please refer to the testing steps that apply to your integration from the following:

Testing your PaymentAction=Sale or Authorization integration

  1. Log in to https://www.sandbox.paypal.com using your buyer's test PayPal account.
  2. Replace the contents of the street address Line-1 of the buyer's test credit card, with CCREJECT-REFUSED.
  3. Execute a typical Express Checkout payment flow against the sandbox environment using the same buyer account and with the same credit card that you just modified.
  4. When you execute DoExpressCheckoutPayment, error code 10486 will be returned. Your code should redirect the buyer back to PayPal using the same redirect URL used to start the checkout flow and the same Express Checkout token.

Testing your PaymentAction=Order integration

  1. Log in to https://www.sandbox.paypal.com using your buyer's test PayPal account.
  2. Replace the contents of the street address Line-1 of the buyer's test credit card, with CCREJECT-REFUSED.
  3. Execute a typical Express Checkout payment flow against the sandbox environment using the same buyer account and with the same credit card that you just modified.
  4. Execute DoExpressCheckoutPayment with the token and passing the PayerID.
  5. When you execute DoAuthorization on the order id, error code 10486 will be returned. Your code should redirect the buyer back to PayPal using a redirect URL containing the order id. For example, https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&order_id=O-4PS66146G25310203. If you do not call DoAuthorization immediately, or if for another reason the buyer is not online when you create the authorization, notify the buyer to log in to your website. Then on your website's order review page, present the buyer with an update order button that uses the redirect URL containing the order id to redirect the buyer back to PayPal.
  6. After the buyer successfully updates his / her funding options on PayPal, the buyer is returned to your website. The return URL will contain the order id and the field retry_authorization=true. For example, http://www.yourURL.com/return.html?order_id=O-9X380895SN0698611&retry_authorization=true. retry_authorization=true indicates that the buyer updated his / her funding source successfully. Your code should call DoAuthorization again for this order id.

The Buyer's Experience

When the buyer returns to PayPal, the buyer will be prompted with proper error messaging on the PayPal page. If the buyer's PayPal login session is still active, the customer does not need to log in again.

Example:

The buyer may see an error message similar to the following on the PayPal page:

We're sorry, but your transaction couldn't be completed using the selected card, Visa x-1234, because it has been denied by the card issuer. Another payment method has been chosen for you. Please continue with this payment method, or choose a different way to pay.

Option 1

If the buyer has other payment methods available, the buyer will be asked to choose another method as shown in the screen shot below.

Fig. 3 - Buyer with an additional funding source

Option 2

If the buyer has no alternative funding sources, the buyer will be prompted to add a new one as shown in the screen shot below.

Fig. 4 - Buyer without another funding source

Learn More