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 omit these fields from the response 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 (null until the date has been set).

​
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 absent, or where currency is USD and account_category is absent.
  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), mobile_money and rolla_transfer beneficiaries do not need account_owner_type — they are exempt from routing classification. NGN bank beneficiaries are exempt as well.

​
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 except NGN; account_category is required for USD beneficiaries. Enforced after a 60-day grace period during which incomplete requests receive a deprecation_warning.