Skip to main content

​
✨ New Features

​
Customers

  1. New Endpoint: GET /v2/customers List customers with the same filtering and pagination as V1. The V1 endpoint remains available.
  2. New Endpoint: GET /v2/customers/{customer_id} Retrieve customer details with new fields not available in V1. The response now includes rejection_reason (populated when customer_status is REJECTED or ACTION_REQUIRED) and request_for_information (populated when customer_status is ACTION_REQUIRED). These fields give developers structured visibility into why a customer was rejected or what action is needed, without requiring a separate API call or webhook.
  3. New Endpoint: POST /v2/customers/business Create a business customer with a significantly expanded KYB profile. Key additions over V1 include:
    • industry_codes — accepts NAICS 2022 6-digit codes instead of the V1 business_industry_id integer
    • tax_info[] array — replaces the single tax_id string, supporting multiple tax documents per country
    • holding_structure — captures corporate shareholders and foreign branch registrations
    • public_listings — stock exchange details for publicly traded companies
    • compliance — full AML/KYC program details including risk profile, regulated activity, and sanctions screening
    • source_of_fund_ids and source_of_wealth_ids — accept arrays instead of a single integer, ordered by contribution size
    • _en transliteration fields — for non-ASCII business names and addresses
    • Granular volume fields: expected_monthly_deposits_usd, expected_monthly_withdrawals_usd, expected_transaction_value_usd, and expected_monthly_transaction_count replace the single monthly_volume field
    The V1 POST /v1/customers/business endpoint remains available. Returns 201 on success (V1 returns 200).
  4. New Endpoint: POST /v2/customers/{customer_id}/business/attach Attach documents to a V2 business customer. Documents are organized into three categories: formation_documents, ownership_documents, and supporting_documents. This replaces the V1 structure of ownership_structure, company_details, and legal_presence. The customer_id is now a path parameter instead of a request body field.
  5. New Endpoint: POST /v2/customers/{customer_id}/associated-parties/individual/attach Attach identity and address documents for associated parties of a V2 business customer. Replaces proof_of_identity and proof_of_address with identifying_documents and address_documents arrays, allowing multiple identity documents per party. Also adds an optional supporting_documents array.
  6. New Endpoint: PATCH /v1/customers/{customer_id} Unified endpoint for responding to RFI requests across all customer types and API versions. Submit only the fields and documents specified in the customer.rfi webhook. Sending unrequested fields will trigger an error. The request body accepts the same field structures used by the customer creation and document attachment endpoints (both V1 and V2). This single endpoint replaces the need for separate PATCH calls per document category.

​
Beneficiaries

  1. New Endpoint: POST /v3/beneficiaries Create a beneficiary with a required counter_party field (FIRST_PARTY or THIRD_PARTY). The occupation_remarks field is no longer required in receiver_meta_data. The response returns beneficiary_id directly instead of id and status. The beneficiary is ready for transactions only when its status reaches ACTIVE (delivered via the beneficiary.status webhook).

​
Virtual Accounts

  1. New Endpoint: POST /v2/customers/virtual-account Create a virtual account with a restructured request body. Key changes from V1:
    • customer_id is no longer in the request body (inferred from auth context)
    • Uses destination.wallet, destination.currency, destination.rail instead of flat fields
    • Uses source.currency and source.rail instead of source_currency and source_rail
    • Accepts both developer_fee.percentage and developer_fee.fixed instead of only developer_fee_percentage
    • The account starts in PROCESSING status. deposit_instructions will be null until the account becomes ACTIVE.
  2. New Endpoint: GET /v2/customers/virtual-account List virtual accounts with the same filtering as V1. The response adds developer_fee_fixed, rfi, bank_country, account_type, and bank_code fields. The status enum is expanded to include PROCESSING, IN_COMPLIANCE, REQUEST_FOR_INFORMATION, ACTIVE, INACTIVE, and DECLINED.

​
Catalogue

  1. New Endpoint: GET /v1/source-of-wealth Retrieve a list of source of wealth options. Accepts type (INDIVIDUAL or BUSINESS) as a required query parameter. Used by POST /v2/customers/business via the source_of_wealth_ids field.

​
Webhooks

  1. New Webhook: customer.rfi Fires when the compliance team requests additional documents or data from a customer. Sets the customer status to ACTION_REQUIRED. The payload includes a structured request_for_information array describing exactly which sections, document types, and fields are MISSING, EXPIRED, or INVALID. Scoped to either the customer or a specific associated party. Can also fire after a customer is already APPROVED.
    Customer TypeSection Values
    Individualproof_of_identity, proof_of_address, tos_policies_value
    Business V1company_details, ownership_structure, legal_presence
    Business V2formation_documents, ownership_documents, supporting_documents
    Associated Party V1proof_of_identity, proof_of_address
    Associated Party V2identifying_documents, tax_info, address_documents
  2. New Webhook: virtual_account.created.v2 Fires when a V2 virtual account is created. The account starts in PROCESSING status with deposit_instructions set to null. Includes a developer_fee_fixed field and an rfi object (null initially).
  3. New Webhook: virtual_account.status.v2 Fires when a V2 virtual account status changes. Possible values: PROCESSING, IN_COMPLIANCE, REQUEST_FOR_INFORMATION, ACTIVE, INACTIVE, DECLINED. The payload includes deposit_instructions (populated once active), developer_fee_fixed, developer_fee_percent, and rfi.

​
🛠️ Improvements

​
Customers

  1. V2 Customer Status Names Three customer status values have been renamed in V2 endpoints and webhooks. V1 status names remain unchanged for V1 created customers.
    StatusV1 NameV2 Name
    Awaiting processingQUEUEDPROCESSING
    Paused for complianceON_HOLDIN_COMPLIANCE
    Action neededREINITIATEACTION_REQUIRED
    The status values you receive are determined by which version of the Get Customer Details endpoint you call, not which version was used to create the customer. A business customer created via POST /v1/customers/business will return V2 status names when retrieved via GET /v2/customers/{customer_id}, and vice versa.
  2. V1 entity_type enum: PRIVATE_LIMITED removed The PRIVATE_LIMITED value has been removed from the entity_type enum in POST /v2/customers/business. It remains available in V1.
  3. Identity document types expanded The ProofOfIdentity schema now includes RESIDENCE_PERMIT and PERMANENT_RESIDENCY_ID as accepted types. PERMANENT_RESIDENCY_ID is only supported for USA residents and will be rejected for non-USA residents.
  4. GET /v1/industries scoped to V1 only The List Industries catalogue endpoint now applies only to POST /v1/customers/business. The V2 business customer endpoint uses industry_codes (NAICS 6-digit codes) instead.

​
Beneficiaries

  1. counter_party field added to POST /v2/beneficiaries An optional counter_party field (FIRST_PARTY or THIRD_PARTY) has been added to the existing V2 Create Beneficiary endpoint.
  2. status and counter_party fields added to GET /v2/beneficiaries/details The Fetch Beneficiary Details V2 response now includes a status field with values PROCESSING, ACTIVE, INACTIVE, or REJECTED, and a counter_party field with values FIRST_PARTY or THIRD_PARTY.
  3. beneficiary.status webhook now includes status field The beneficiary.status webhook payload now includes a status field (PROCESSING, ACTIVE, INACTIVE, REJECTED) alongside the existing active boolean. The webhook now fires for all four status transitions.