Granular capabilities migration guide

This guide helps you understand what changes you need to make based on your current integration with Moov. Find your use case below and follow the steps to migrate to the new granular capabilities system.

Before you begin

Key changes

1. API Version — You'll need to use API version v2025.07.00 or later

2. No automatic mapping — Legacy capabilities do not auto-convert; you must explicitly request new granular capabilities

3. Business accounts only — Granular capabilities are only available for business accounts

4. New underwriting endpoint — Underwriting data is now submitted via a POST endpoint

Version header

Add the version header to all API requests:

curl -X POST "<https://api.moov.io/accounts/{accountID}/capabilities>" \\\\
  -H "Authorization: Bearer {token}" \\\\
  -H "x-moov-version: v2025.07.00" \\\\
  -H "Content-Type: application/json"

Full Capabilities reference

ACH/Bank Transfer Customers

If you're currently using the legacy send-funds or collect-funds capabilities for ACH bank transfers, here's what you need to know.

Capability mapping

Request new capabilities

curl -X POST "<https://api.moov.io/accounts/{accountID}/capabilities>" \\\\
  -H "Authorization: Bearer {token}" \\\\
  -H "x-moov-version: v2025.07.00" \\\\
  -H "Content-Type: application/json" \\\\
  -d '{
    "capabilities": [
      "collect-funds.ach",
      "send-funds.ach"
    ]
  }'

Underwriting requirements

Full Underwriting reference

Most ACH customers process more than $10,000/month, which triggers extended underwriting requirements.

Baseline requirements (all ACH capabilities)

Extended requirements (>$10k/month or not us-only)

Submit underwriting data

Use the POST endpoint to submit underwriting:

curl -X POST "<https://api.moov.io/accounts/{accountID}/underwriting>" \\\\
  -H "Authorization: Bearer {token}" \\\\
  -H "x-moov-version: v2025.07.00" \\\\
  -H "Content-Type: application/json" \\\\
  -d '{
    "geographicReach": "us-only",
    "businessPresence": "online-only",
    "volumeShareByCustomerType": {
      "business": 70,
      "consumer": 30,
      "p2p": 0
    },
    "pendingLitigation": "none",
    "collectFunds": {
      "ach": {
        "estimatedActivity": {
          "monthlyVolumeRange": "50k-100k",
          "averageTransactionAmount": 500,
          "maximumTransactionAmount": 5000
        }
      }
    },
    "sendFunds": {
      "ach": {
        "estimatedActivity": {
          "monthlyVolumeRange": "50k-100k",
          "averageTransactionAmount": 1000,
          "maximumTransactionAmount": 10000
        }
      }
    }
  }'

Card Payment Customers

If you're currently using the legacy collect-funds capability to accept card payments, here's what you need to know.

Capability mapping

Request new capabilities

curl -X POST "<https://api.moov.io/accounts/{accountID}/capabilities>" \\\\
  -H "Authorization: Bearer {token}" \\\\
  -H "x-moov-version: v2025.07.00" \\\\
  -H "Content-Type: application/json" \\\\
  -d '{
    "capabilities": [
      "collect-funds.card-payments"
    ]
  }'

Underwriting requirements

Card payment capabilities have additional requirements beyond the baseline and extended fields.

Baseline requirements (all ACH capabilities)

Extended requirements (>$10k/month or not us-only)

Card-specific requirements

For card-not-present merchants (online < 80% in-person)

If currently accepting cards

If currentlyAcceptsCards is true, you'll need to upload processing statements via the files API.

Submit underwriting data

curl -X POST "<https://api.moov.io/accounts/{accountID}/underwriting>" \\\\
  -H "Authorization: Bearer {token}" \\\\
  -H "x-moov-version: v2025.07.00" \\\\
  -H "Content-Type: application/json" \\\\
  -d '{
    "geographicReach": "us-only",
    "businessPresence": "online-only",
    "volumeShareByCustomerType": {
      "business": 20,
      "consumer": 80,
      "p2p": 0
    },
    "pendingLitigation": "none",
    "collectFunds": {
      "cardPayments": {
        "estimatedActivity": {
          "monthlyVolumeRange": "50k-100k",
          "averageTransactionAmount": 75,
          "maximumTransactionAmount": 500
        },
        "currentlyAcceptsCards": true,
        "cardAcceptanceMethods": {
          "inPersonPercentage": 0,
          "onlinePercentage": 100,
          "mailOrPhonePercentage": 0
        },
        "fulfillment": {
          "method": "digital-content",
          "timeframe": "immediate"
        },
        "refundPolicy": "full-refund-within-30-days"
      }
    }
  }'

New Capabilities Available

The granular capabilities system opens up easy access to new payment rails. If your business needs these, you can now request them for your existing accounts:

Instant payouts

Money transfer (specialized use cases)

Note: Money transfer capabilities are limited to approved use cases. Contact Moov to determine eligibility.

Migration checklist

Use this checklist to track your migration progress:

• Review this guide and identify your use case(s)

• Update API requests to include x-moov-version: v2025.07.00 header

• Identify which granular capabilities you need based on the mapping tables

• Update capability request code to use new granular capability names

• Prepare underwriting data for each capability

• Update underwriting submission to use POST endpoint with new schema

• Monitor for any capability requirement errors

Troubleshooting

If you encounter errors during migration, check the capabilities API response for requirement errors:

{
  "capability": "collect-funds.ach",
  "status": "pending",
  "requirements": {
    "currentlyDue": ["underwriting.geographicReach"],
    "errors": [
      {
        "requirement": "business.ein",
        "errorCode": "failed-automatic-verification"
      }
    ]
  }
}

For a complete list of errors, see the Troubleshooting Guide.

Getting help

• Documentation: docs.moov.io

• API Reference: docs.moov.io/api