Handling Revoked Payment Methods

At Braintree, we continually look for ways to improve the merchant experience of integrating with our services. We seek to strike a balance between simplicity — hiding annoying processor-specific intricacies in favor of an intuitive processor-agnostic solution — and providing actionable details — events and exceptions that occur outside of the normal transaction-processing model.

A vaulted payment method represents a customer’s approval for a merchant to repeatedly charge a funding instrument. When that underlying instrument is a PayPal account, that approval is literal: the payment method references the PayPal billing agreement that the customer has approved and maintains in their individual PayPal account.

A common case that merchants must support is detecting and responding when a payment method becomes unusable. For credit cards, this occurs when the card expires or the account closes; for PayPal, the customer may revoke the billing agreement. A recent effort to improve our transaction-processing metrics revealed that PayPal billing agreement revocation was a common cause of PayPal transaction declines.

This insight prompted us to reexamine the merchant experience for unusable payment methods. Since merchants are not notified regarding payment method revocation, they must optimistically assume that all payment methods are valid until proven otherwise. When a transaction is inevitably declined, the merchant must parse the processor response code to determine whether the underlying payment method has become unusable. If it has, the merchant must then redirect the user to add a new payment method and attempt the transaction again.

Recently, Braintree added revocation webhook support, offering merchants the opportunity to proactively address cases when a PayPal billing agreement is revoked by a customer. Rather than waiting for a transaction to fail, a merchant can subscribe to a Braintree webhook which will notify the merchant of a revoked payment method within moments. A simple Ruby handler might look like this:

When received, the merchant can immediately (1) delete the payment method, (2) specify a new default payment method for the customer, and/or (3) prompt the customer with a notification to add a new, valid payment method either proactively or the next time they are charged. No more transaction interruptions!

For an introduction to Braintree webhooks, see our guide. If you’re already familiar, you can dive into the documentation for the new payment_method_revoked_by_customer webhook.




Love podcasts or audiobooks? Learn on the go with our new app.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Alan Buttars

Alan Buttars

More from Medium


Tips To Secure Text Messages From Any Leaks Or Privacy Invasions

secure text messages

Cost to Develop an App like Coursera

How to Choose Right Tech Stack for Mobile App Development? — Blog