Handling Revoked Payment Methods

Alan Buttars
Jul 8, 2019 · 2 min read

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 Braintree.

Alan Buttars

Written by

Braintree Product and Technology

Essays on design, engineering, and product development at Braintree.

More From Medium

More from Braintree Product and Technology

More from Braintree Product and Technology

More from Braintree Product and Technology

A Year (plus a little) on TC39

More from Braintree Product and Technology

More from Braintree Product and Technology

Pay It Forward

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade