Handle funding failures

DocsCurrent

Last updated: Feb 28th, 7:42pm

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

  • The billing address associated with the payment method is incorrect.
  • The transaction exceeds the card limit.
  • The card issuer denied the transaction.

To handle this error, restart the payment so the payer can select a different payment option.

Restart the payment

Restarting the payment is required if you directly call the Orders API from your server. If you use actions.order.capture(), the script automatically restarts the checkout flow and prompts the payer to select a different funding source.

Restart the payment in the onApprove function as follows:

1paypal.Buttons({
2  onApprove: function (data, actions) {
3    return fetch('/my-server/capture-paypal-transaction', {
4      headers: {
5        'content-type': 'application/json'
6      },
7      body: JSON.stringify({
8        orderID: data.orderID
9      })
10    }).then(function(res) {
11      return res.json();
12    }).then(function(captureData) {
13      if (captureData.error === 'INSTRUMENT_DECLINED'); // Your server response structure and key names are what you choose
14        return actions.restart();
15      }
16    });
17  }
18}).render('#paypal-button-container');

Know before you code

PayPal Checkout

Required

Complete the steps in Get started to get your sandbox account login information and access token from the Developer Dashboard.

This feature modifies an existing PayPal Checkout integration and uses the following:

JavaScript SDK:: Adds PayPal-supported payment methods.

Orders REST API: Create, update, retrieve, authorize, and capture orders.

PayPal Checkout

Get started

Explore PayPal APIs with Postman

Optional

You can use Postman to explore and test PayPal APIs. Learn more in our Postman guide.

Run in Postman