Handle funding failures

A buyer's funding source can fail for several reasons, including:

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

If a funding source fails, the Orders API returns the INSTRUMENT_DECLINED error. Handle this error and provide the buyer an opportunity to select a different payment option by restarting the payment in the onApprove function.

Know before you code

• This procedure adds to the server-side Capture an order topic.
• If you're using actions.order.capture() in your client-side JavaScript code, don't complete this task. The script automatically restarts the Checkout flow and prompts the buyer to select a different funding source.

• This client and server-side integration uses the following:

  • Orders REST API
  • PayPal JavaScript SDK

1. Modify code

Add a then handler to check for the INSTRUMENT_DECLINED error and if it is returned, restart the onApprove function.

Sample JavaScript SDK code

paypal.Buttons({
  onApprove: function (data, actions) {
    return fetch('/my-server/capture-paypal-transaction', {
      headers: {
        'content-type': 'application/json'
      },
      body: JSON.stringify({
        orderID: data.orderID
      })
    }).then(function(res) {
      return res.json();
    }).then(function(details) { // check for INSTRUMENT_DECLINED and restart OnApprove if true
      if (details.error === 'INSTRUMENT_DECLINED') {
        return actions.restart();
      }
    });
  }
}).render('#paypal-button-container');

2. Test

Test a funding failure in the sandbox to confirm a buyer can recover and select another funding source.

1. In the call to Capture payment for order, include the PayPal-Mock-Response header with the mock_application_codes value set to INSTRUMENT_DECLINED. Sample code: -H "PayPal-Mock-Response: {"mock_application_codes" : "INSTRUMENT_DECLINED"}"
2. Complete a purchase in the sandbox by clicking the PayPal button on your checkout page and following the instructions on the screen.
3. When the instrument is declined, PayPal prompts you to select another funding source.
4. When the testing is completed, remove the PayPal-Mock-Response header from your code.

Next step

• Test and go live - Test your entire integration and take your code live.