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:
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.
- In the call to Capture payment for order, include the
PayPal-Mock-Response
header with themock_application_codes
value set toINSTRUMENT_DECLINED
. Sample code:-H "PayPal-Mock-Response: {"mock_application_codes" : "INSTRUMENT_DECLINED"}"
- Complete a purchase in the sandbox by clicking the PayPal button on your checkout page and following the instructions on the screen.
- When the instrument is declined, PayPal prompts you to select another funding source.
- 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.