Skip to main content
Deprecation Notice: The endpoints listed below will be deprecated on May 20, 2026. Please migrate to the new versions before this date to avoid service disruption.

​
API Migration Guide

This guide outlines the endpoints scheduled for deprecation, their replacements, and the key behavioral changes you need to be aware of when migrating. Each section includes direct links to the relevant API reference for both the deprecated and new endpoints.

​
Endpoint Migration Reference

​
Customers

ResourceDeprecated EndpointNew Endpoint
Create business customerPOST /v1/customers/business — referencePOST /v2/customers/business — reference
Attach business documentsPOST /v1/customers/business/attach — referencePOST /v2/customers/{customer_id}/business/attach — reference
Attach document to associated partyPOST /v1/customers/associated-parties/individual/attach — referencePOST /v2/customers/{customer_id}/associated-parties/individual/attach — reference
List customersGET /v1/customers — referenceGET /v2/customers — reference
Get business customer detailsGET /v1/customers/{customer_id} — referenceGET /v2/customers/{customer_id} — reference

​
Beneficiaries

ResourceDeprecated EndpointNew Endpoint
Create beneficiaryPOST /v2/beneficiaries — referencePOST /v3/beneficiaries — reference
Get beneficiary detailsGET /v1/beneficiaries/details — referenceGET /v2/beneficiaries/details — reference
The new beneficiary details endpoint adds visibility into the status and counter_party fields.

​
Virtual Accounts

ResourceDeprecated EndpointNew Endpoint
Create virtual accountPOST /v1/customers/virtual-account — referencePOST /v2/customers/virtual-account — reference
List virtual accountsGET /v1/customers/virtual-account — referenceGET /v2/customers/virtual-account — reference

​
What’s Changed

​
1. New Status Values for Business Customers (v2)

The v2 business customer API introduces clearer, more descriptive status values. If you have logic that branches on customer status, you’ll need to update it.
Legacy Status (v1)New Status (v2)
QUEUEDPROCESSING
ON_HOLDIN_COMPLIANCE
REINITIATEACTION_REQUIRED
Versioning rules:
  • Business customers — Use v2 for both creation and retrieval.
  • Individual customers — Continue using v1 for both creation and retrieval.

​
2. Request for Information (RFI) Management

A new request_for_information object has been introduced on the business customer resource to streamline RFI handling. To respond to or update an RFI, use: 
PATCH /v1/customers/{customer_id}
This is the canonical way to manage RFIs going forward — no separate workflow is required.

​
3. Capabilities Moved to a Dedicated Endpoint

The capabilities object has been removed from the v2 customer details response. To fetch a customer’s capabilities, use the new dedicated endpoint: 
GET /v2/customers/{customer_id}/capabilities
This keeps customer detail responses lighter and lets you fetch capability data only when you actually need it.

​
4. New Beneficiary Status Values

Beneficiaries now expose a more granular status lifecycle so you can clearly determine transaction eligibility:
StatusDescriptionEligible for Transactions?
PROCESSINGThe beneficiary is being prepared and is not yet ready.No
ACTIVEThe beneficiary is fully set up and ready to use.Yes
INACTIVEThe beneficiary is currently disabled.No
REJECTEDBeneficiary failed validation.No
Make sure your transaction-initiation logic checks for ACTIVE before attempting to send funds to a beneficiary.

​
Migration Checklist

Use this list to track your migration work before May 20, 2026:
  • Update all business customer create and fetch calls to v2.
  • Map legacy customer statuses (QUEUED, ON_HOLD, REINITIATE) to their new values in your codebase.
  • Implement the PATCH /v1/customers/{customer_id} flow for RFI handling.
  • Update document attachment calls to use the new {customer_id}-scoped paths.
  • Update customer list and detail integrations to v2.
  • Move any capabilities-dependent logic to GET /v2/customers/{customer_id}/capabilities.
  • Update beneficiary creation calls to v3 and fetch calls to v2.
  • Handle the new beneficiary statuses (PROCESSING, ACTIVE, INACTIVE, REJECTED) — gate transactions on ACTIVE.
  • Update virtual account create and list calls to v2.
  • Verify individual customer flows remain on v1 (no change required).
  • Complete migration before May 20, 2026.