New webhooks and powered-up PaymentMethod controls

Greetings, friends! Spring is upon us at last, and here at Routable, our spring cleaning project continues with new improvements to webhooks and PaymentMethods. Let's take a quick hop through the list!

New company.updated webhook

We've added, by popular request, a new webhook to the system: company.updated. A company.updated webhook event will be triggered when a Company 's legal name changes.

Powered-up PaymentMethods

Did we say one new webhook? We meant two.

A new payment_method.updated webhook event will fire when a PaymentMethod has its validation_status change, or when it is archived or unarchived.

📘

Created vs. Updated

Note that payment_method.updated is triggered when an existing PaymentMethod is updated. While colloquially, folks often refer to the act of adding a new bank account to a vendor as "updating their payment method", this actually results in the creation of a new PaymentMethod object, which would trigger payment_method.created webhook events instead.

Wait... PaymentMethods can be archived?!

Yes! Previously, if you wanted to archive a PaymentMethod you no longer wanted to use - perhaps because the bank account is no longer in use or a bank account validation check returned troubling information - you had to reach out to Routable's stellar success and support teams to facilitate it. No longer! Behold, the Archive a Payment Method endpoint! Now you can self-service this function programmatically, including as part of an automated strategy to address failed payments .

Of course, you might make a mistake, or just change your mind - so we've also provided a companion endpoint to restore an archived PaymentMethod .

📘

Whodunnit?!

A new boolean is_archived field has been added to PaymentMethods. When a PaymentMethod is archived, its new archived_by field will either have a value of system, meaning Routable's internal logic archived the PaymentMethod due to unrecoverable issues with it, or team_member if a member of your team requested the archival using the new endpoint. Only PaymentMethods that were archived_by a team_member can be unarchived.

Hold on a second! Archived and invalid PaymentMethods don't show in the API!

They do now! By default, they'll still be filtered out, so your existing code doesn't need to change, but you can pass archival_status=system or archival_status=team_member to the List Payment Methods endpoint to see them. These updates will also, for the first time, give you the option to see PaymentMethods that are not valid to be used for transactions.

Speaking of the concept of valid, we've slightly tweaked the logic behind the is_valid field on PaymentMethods to make it a bit more all-encompassing. Essentially, if you see is_valid: true on a PaymentMethod now, you can be confident that Routable knows of no issues that would prevent it from successfully executing transactions.

Visibility on the verification process

Finally on the PaymentMethod object, we've exposed a new verification_status field. Unlike its cousin bank account validation , which does a deep dive into the bank account to help catch fraud, verification refers to the existing practice when vendors add their bank accounts via the Invite a Company workflow. In order to verify the bank account is theirs, they either connect to their bank via Plaid, or confirm micro-deposit amounts. When this step has been successfully completed, the newly-exposed verification_status field will show verified. You'll see pending if micro-deposits were sent but the vendor has yet to confirm them, and failed if that confirmation process was unsuccessful.

📘

failed versus not_verified

When there is a failed verification (such as incorrect micro-deposit amounts entered during verification) you will see the failed value in verification_status. The not_verified value, however, does not mean that there is a problem with the PaymentMethod. It means that either the verification has not started (which generally would only take a few seconds for PaymentMethods added through the Invite a Company workflow) or the bank account did not require validation at all because it was added by your team via the Create a Payment Method endpoint or the Routable Dashboard.

The result of the verification (and the determination of whether it was needed in the first place) is part of what goes into the new is_valid logic. You never need to explicitly check verification_status if your goal is to determine that a PaymentMethod is safe to use; if is_valid = true, you can trust that any necessary validation has been successfully completed, the PaymentMethod is not archived, and other necessary criteria to enable payments to that PaymentMethod are also met.