Handle funding failures

DocsCurrentLast updated: April 6th 2022, @ 4:06:12 pm


Handle your buyer's funding source failures to provide a unique experience.

Know before you code

  • These capabilities modify an existing checkout integration.
  • Complete the steps in Get started to get the following sandbox account information from the Developer Dashboard:
    • Your sandbox account login information
    • Your access token
  • These client-side and server-side integration capabilities use the following:
  • Use Postman to explore and test PayPal APIs.

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');