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:

  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) {
      if (details.error === 'INSTRUMENT_DECLINED') {
        return actions.restart();

To test the error handling flow, see Negative Testing for REST API.