Handle Funding Failures

If your buyer's funding source fails, the Orders API returns an INSTRUMENT_DECLINED error. A funding source might fail for these reasons:

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

Note: This step is necessary if you are directly calling the Orders API from your server. If you are using actions.order.capture(), the PayPal script automatically restarts the Checkout flow and prompts the buyer to select a different funding source.

To handle this error, restart the payment in the onApprove function so the buyer can select a different payment option:

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(captureData) {
      if (captureData.error === 'INSTRUMENT_DECLINED'); // Your server response structure and key names are what you choose
        return actions.restart();
      }
    });
  }
}).render('#paypal-button-container');

Next Steps

• Full demo pattern to read a v2/checkout/orders response and handle errors
• Negative Testing for REST APIs to simulate errors during testing