Skip to main content
To support compliant payout routing, every bank-account beneficiary now carries two classification fields. This guide covers the field definitions, when each is required, and how to migrate existing beneficiaries before enforcement begins.

​
What changed

Both fields are accepted on POST /beneficiaries and PATCH /beneficiaries/{beneficiaryId}, and are returned on every beneficiary read (list and get). Legacy records created before this change return null for these fields until you backfill them.
Invalid values are always rejected, even during the grace period. account_owner_type must be exactly individual or business; account_category must be exactly checking or savings.

​
Grace period and enforcement

The rollout runs in two phases so existing integrations do not break:
1

Grace period (60 days)

Requests that omit a required field still succeed. The response includes a deprecation_warning object listing the missing fields and the enforcement date. Use this window to add the fields to your integration and backfill saved beneficiaries.
2

Enforcement

After the enforcement date, a POST or PATCH that omits a required field is rejected with a 400 and no beneficiary is created or updated.
The exact enforcement date is communicated by email to all MSB and business API clients before the grace period begins. It is also surfaced in the enforcement_date field of every deprecation_warning response.

​
Deprecation warning response

During the grace period, an incomplete request returns a 2xx with a warning appended:
After enforcement, the same request instead returns:

​
Migrating existing beneficiaries

  1. List your beneficiaries and find records where account_owner_type is null, or where currency is USD and account_category is null.
  2. Backfill each one with a PATCH, sending the missing field(s) alongside the existing details:
  1. Send both fields on all new beneficiaries going forward so nothing regresses after enforcement.
Crypto (crypto_usdt, crypto_usdc) and rolla_transfer beneficiaries do not need either field — they are exempt from routing classification.

​
Changelog

​
Added account_owner_type (individual | business) and account_category (checking | savings) to the beneficiary create, update, get, and list endpoints. account_owner_type is required for all bank-account beneficiaries; account_category is required for USD beneficiaries. Enforced after a 60-day grace period during which incomplete requests receive a deprecation_warning.