Handling Revoked Payment Methods

Alan Buttars
Jul 8, 2019 · 2 min read
Image for post
Image for post

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.

Braintree Product and Technology

Essays on design, engineering, and product development at…

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

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