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!