API & Drops quick start

Sign up for Moov

Before you get started with the API or Drops, you'll use the Moov Dashboard to create a Moov account. Once you're signed up, you can use test mode with no commitment.

If you want to move real money and onboard real business accounts, you'll need to go through verification, underwriting, and sign a contract with Moov before you'll be approved for production access. See the account requirements section for more information, or contact Moov to get the verification process started.

An individual with administrator or developer permissions is required to take the actions laid out in this guide.

Create API keys

To use Moov's API, you'll need to generate keys in the Dashboard. Navigate to Developers and click the New API key button. Test mode and production mode each require their own API keys. To create an API key:

1. Name the API key (we suggest giving it a name that relates to the purpose)
2. Make sure to copy the key and save it in a secure place
3. Add any domains you'll use for testing and production
4. Optional: Include a note to remind you where the key is stored

Read the API keys documentation for more information. If you're ready to jump into production mode, make sure to take any necessary precautions if you've previously been using test mode.

Explore test mode

In test mode, test data is automatically enabled in the Dashboard and the API, which allows you to explore how the platform works. Make sure you're in test mode by using the account switcher on the top left of the Dashboard view.

In the accounts API and payment links API, you can set "mode": "sandbox" to test in sandbox mode with test mode data.

Try out the following:

• Add a bank account
• Initiate verification
• Initiate a transfer
• Initiate a return

Switch to production mode

When you're ready to switch to production mode, use the account switcher to change modes. Before you start using production mode, make sure to:

• Have your production API key
• Switch out the account ID anywhere it's hard coded
• Set up new webhook URLs if you used any in test mode

Set brand colors

Select light and dark mode brand color settings with the POST create brand endpoint.

curl -X POST "https://api.moov.io/accounts/{accountID}/branding" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.07.00" \
  -d '{
  "colors": {
    "dark": {
      "accent": "#DB8774"
    },
    "light": {
      "accent": "#9E432B"
    }
  }
}'

Onboard with hosted onboarding

Moov's hosted onboarding allows you to select capabilities, scopes, pre-fill existing information, and select a fee plan before sending a merchant a link to a secure session to finish the sign up process. A merchant can be redirected to your app upon completion.

You'll pre-fill information and send a branded secure session link to the account owner. The business/merchant can start and pause the process, picking up where they leave off. During the process, the account owner will give you permission to perform actions on their behalf, as well as agree to the terms of service agreement and pricing disclosure.

Any account onboarded through Moov's hosted onboarding process will have access to their own merchant Dashboard. You can send a support guide to the account owner so they'll know what information and documents to gather ahead of time.

All personally identifiable information (PII) goes straight to Moov, so you won’t be responsible for storing or handling sensitive user data.

Select Capabilities

Capabilities indicate what an account is able to do. Before you begin the hosted onboarding process, decide what capabilities the account will need:

• Transfer: Authorize debit transfers
• Wallet: Store funds with Moov
• Send funds: Send funds to another account
• Collect funds: (business accounts only): Collect funds from another account
• Card issuing beta: (business accounts only): Provide a virtual card to a merchant

Send funds and collect funds have multiple capabilities that can be requested per use case. For faster verification, only request required capabilities. For example, if a merchant is only interested in processing RTP payouts, only request the send-funds.instant-bank capability.

Each capability has different data and verification requirements depending on whether the account represents a business or individual. You should familiarize yourself with capability requirements before moving on to the next step.

Available capabilities:

See our capabilities section for more information.

Select scopes

Scopes specify what actions an account can take on Moov's platform. When you choose to enable certain scopes for an account, you create connections between your account, the business/merchant account, and the account's customers. You have the option to choose a set of scopes for your partner account (scopes) and a set of scopes for the merchant account (grantScopes).

For general usage, Moov suggests to enable at least the following scopes:

• accounts.read
• bank-accounts.read
• bank-accounts.write
• capabilities.read
• capabilities.write
• profile.read
• profile.write
• payment-methods.read
• transfers.read
• transfers.write
• wallets.read

Moov maintains strict access controls when a partner account shares scopes with a merchant. While a partner gains visibility across every connected account, merchants can only access their own customers.

See the connected accounts guide for more information.

Select pricing fee plan

During the onboarding process, you'll also choose a fee plan for the account, which they will agree to as part of their terms of service platform agreement.

With a cost plus plan, card networks’ interchange fees and Moov’s processing markup are passed along to the merchant. With a flat rate plan, you can lump all the processing fees together with a flat rate customized for each merchant.

When you create a fee plan, you can use it once, or reuse it and assign it to many merchants. A merchant must accept the fee plan and enter into a fee agreement before it can go into effect.

To see what fee plans are available for an account, send the merchant's accountID to the GET list fee plans endpoint.

You'll use the planID provided in the response when creating an onboarding link.

curl -X GET "https://api.moov.io/accounts/{accountID}/fee-plans" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.07.00"

[
  {
    "planID": "b6134307-8922-4a72-bf3c-d0297bbe8a35",
    "name": "Fixed Rate Merchant Plan",
    "description": "string",
    "cardAcquiringModel": "cost-plus",
    "billableFees": [
      {
        "billableFeeID": "9d957d33-1a9a-47aa-9460-fe1a90f003dd",
        "billableEvent": "card-auth-volume",
        "feeName": "Card decline fee",
        "feeModel": "fixed",
        "feeCategory": "card-acquiring",
        "feeProperties": {
          "fixedAmount": {
            "currency": "USD",
            "valueDecimal": "0.0195"
          },
          "variableRate": "0.15",
          "minPerTransaction": {
            "currency": "USD",
            "valueDecimal": "0.0195"
          },
          "maxPerTransaction": {
            "currency": "USD",
            "valueDecimal": "0.035"
          },
          "volumeRanges": [
            {
              "fromValue": 1,
              "toValue": 2,
              "flatAmount": {
                "currency": "USD",
                "valueDecimal": "1.23"
              },
              "perUnitAmount": {
                "currency": "USD",
                "valueDecimal": "1.23"
              }
            }
          ]
        },
        "feeConditions": {
          "transactionType": [
            "decline"
          ]
        }
      }
    ],
    "minimumCommitment": {
      "currency": "USD",
      "valueDecimal": "12.987654321"
    },
    "monthlyPlatformFee": {
      "currency": "USD",
      "valueDecimal": "12.987654321"
    },
    "createdAt": "2026-01-24T14:15:22Z"
  }
]

See our pricing guide for more information and details on billable events.

Create & send onboarding link

Create the link by filling in all required and any optional, or pre-fill data fields you want. The response will include a link you can send to a business/merchant via email or SMS.

The merchant must accept the pricing fee plan and agree to the terms of service and pricing disclosure before the plan can go into effect. You are responsible to your merchants for communication regarding pricing models.

curl --X POST "https://api.moov.io/onboarding-invites" \
  -H "Authorization: Bearer {token}" \
  -H "x-moov-version: v2024.07.00" \
  --data-raw '{
    "returnURL": "https://mycompany.com/account",
    "termsOfServiceURL": "https://mycompany.com/terms-of-service",
    "scopes": [
      "accounts.read",
      "bank-accounts.read",
      "bank-accounts.write",
      "capabilities.read",
      "capabilities.write",
      "profile.read",
      "profile.write",
      "payment-methods.read",
      "transfers.read",
      "transfers.write",
      "wallets.read"
    ],
    "grantScopes": [
      "accounts.read",
      "bank-accounts.read",
      "bank-accounts.write",
      "capabilities.read",
      "capabilities.write",
      "profile.read",
      "profile.write",
      "payment-methods.read",
      "transfers.read",
      "transfers.write",
      "wallets.read"
    ],
    "capabilities": [
      "transfers",
      "wallet.balance"
    ],
    "feePlanCodes": [
      "b6134307-8922-4a72-bf3c-d0297bbe8a35"
    ],
    "prefill": {
      "mode": "production",
      "accountType": "business",
      "profile": {
        "business": {
          "legalBusinessName": "Whole Body Fitness LLC",
          "doingBusinessAs": "Whole Body Fitness",
          "businessType": "llc",
          "address": {
            "addressLine1": "123 Main Street",
            "addressLine2": "Apt 302",
            "city": "Boulder",
            "stateOrProvince": "CO",
            "postalCode": "80301",
            "country": "US"
          },
          "phone": {
            "number": "8185551212",
            "countryCode": "1"
          },
          "email": "amanda@wbfgym.dev",
          "website": "www.wholebodyfitnessgym.com",
          "description": "Local fitness center paying out instructors",
          "taxID": {
            "ein": {
              "number": "123-45-6789"
            }
          },
          "industryCodes": {
            "naics": "713940",
            "sic": "7991",
            "mcc": "7997"
          },
          "primaryRegulator": "FDIC"
        }
      },
      "metadata": {
        "property1": "string",
        "property2": "string"
      },
      "termsOfService": {
        "token": "kgT1uxoMAk7QKuyJcmQE8nqW_HjpyuXBabiXPi6T83fUKRJkA3dsFID6fzitMpm2qrOh4"
      },
      "foreignID": "4528aba-b9a1-11eb-8529-0242ac13003",
      "customerSupport": {
        "phone": {
          "number": "8185551212",
          "countryCode": "1"
        },
        "email": "amanda@wbfgym.dev",
        "address": {
          "addressLine1": "123 Main Street",
          "addressLine2": "Apt 302",
          "city": "Boulder",
          "stateOrProvince": "CO",
          "postalCode": "80301",
          "country": "US"
        },
        "website": "www.wholebodyfitnessgym.com"
      },
      "settings": {
        "cardPayment": {
          "statementDescriptor": "Whole Body Fitness"
        },
        "achPayment": {
          "companyName": "Whole Body Fitness"
        }
      }
    }
  }'\

 1{
 2  "code": "N1IA5eWYNh",
 3  "link": "http://example.com",
 4  "returnURL": "string",
 5  "termsOfServiceURL": "string",
 6  "scopes": [
 7    "accounts.read"
 8  ],
 9  "grantScopes": [
10    "transfers.write"
11  ],
12  "capabilities": [
13    "transfers"
14  ],
15  "feePlanCodes": [
16    "merchant-direct"
17  ],
18  "redeemedAccountID": "string",
19  "prefill": {
20    "accountType": "business",
21    "profile": {
22      "business": {
23        "legalBusinessName": "Whole Body Fitness LLC"
24      }
25    }
26  },
27  "partner": {
28    "accountID": "string",
29    "accountMode": "production",
30    "displayName": "Bob's Widgets"
31  },
32  "createdOn": "2019-08-24T14:15:22Z",
33  "redeemedOn": "2019-08-24T14:15:22Z"
34}

Merchants will be asked to provide bank details to set up a funding source. Moov will send a small deposit with a verification code to verify the bank account instantly, if eligible. If the bank doesn't support instant verification, Moov will automatically use same-day ACH instead of RTP for verification. ACH verification may take 1-2 days.

You can track the status of a merchant's application a few ways. Sending the returned onboarding code in the GET onboarding link endpoint will show you if the code has been redeemed or not via the redeemedOn timestamp.

curl -X GET "https://api.moov.io/onboarding-invites/{code}" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.07.00"

 1{
 2  "code": "N1IA5eWYNh",
 3  "link": "http://example.com",
 4  "returnURL": "bobswidgets.dev",
 5  "termsOfServiceURL": "string",
 6  "partner": {
 7    "accountID": "string",
 8    "accountMode": "production",
 9    "displayName": "Bob's Widgets"
10  },
11  "createdOn": "2026-08-24T14:15:22Z",
12  "redeemedOn": "2026-08-25T09:00:00Z"
13}

Additionally, you can check on an account's capability status, which determines what actions an account has been approved for. If a capability status is enabled, they are approved to use that capability to facilitate money movement. Use the merchant's newly created accountID and send it with the request.

curl -X GET "https://api.moov.io/accounts/{accountID}/capabilities" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.07.00"

[
  {
    "capability": "transfers",
    "accountID": "string",
    "status": "enabled",
    "createdOn": "2016-08-26T15:30:34Z",
  },
    {
    "capability": "wallet.balance",
    "accountID": "string",
    "status": "enabled",
    "createdOn": "2016-08-26T15:30:34Z",
  }
]

Onboarding Drop (alternative)

An alternative way to onboard an account is Moov's onboarding Drop. Drops are pre-built, customizable UI components that take care of the entire account creation workflow within your application.

The Drop interacts directly with Moov’s API using JWTs to securely send data between your end users browser and Moov. Drops provide a secure flow, and PII goes straight to Moov, so you won’t be responsible for storing or handling sensitive user data. The onboarding Drop has the Moov terms of service agreement built in to the process.

Moov Drops are defined in the Moov.js package. After initializing Moov.js, you will have access to our full library of Drops.

The Drop is an HTML element with properties accessed through JavaScript using a reference to the moov-onboarding element.

Initialize the Drop with Moov.js:

<script type="text/javascript" src="https://js.moov.io/v1"></script>

And load the Drop:

<moov-onboarding></moov-onboarding>

See the onboarding Drop guide for more information. Moov also provides a standalone terms of service agreement Drop.

After an account is onboarded, use the payment methods Drop to allow the account owner to register new payment methods to their account.

Create a product

Products are optional, but allow you to create a catalog of items with the following:

• Name
• Description
• Base price
• Image
• Options group

Options allow you create additional properties on each item, such as a minimum or maximum selection, or identifiers like small or blue. Use the POST create new product endpoint to create a product.

curl -X POST "https://api.moov.io/accounts/{accountID}/products" \
  -H "Authorization: Bearer {token}" \
  --data '{
    "basePrice": {
      "currency": "USD",
      "valueDecimal": "14.95"
    },
    "title": "Monday lunch special 1",
    "description": "Sandwich, chips, latte",
    "images": [
      {
        "imageID": "bbdcb050-2e05-43cb-812a-e1296cd0c01a"
      }
    ],
    "optionGroups": [
      {
        "description": "Alternative milk options",
        "name": "Milk options",
        "options": [
          {
            "description": "Fancy brand oat milk",
            "images": [
              {
                "imageID": "bbdcb050-2e05-43cb-812a-e1296cd0c01a"
              }
            ],
            "name": "Oat milk",
            "priceModifier": {
              "currency": "USD",
              "valueDecimal": "1.00"
            }
          },
          {
            "description": "Fancy brand almond milk",
            "images": [
              {
                "imageID": "bbdcb050-2e05-43cb-812a-e1296cd0c01b"
              }
            ],
            "name": "Almond milk",
            "priceModifier": {
              "currency": "USD",
              "valueDecimal": "1.00"
            }
          }
        ]
      }
    ]
  }'\

See the product catalog guide for more information.

Move money with payment links

After successfully onboarding an account, you're ready to move money. First, you'll need to identify what payment methods can be used. Use the GET list payment methods endpoint with the account's accountID to retrieve a list of payment methods associated with the account.

curl -X GET "https://api.moov.io/accounts/{accountID}/payment-methods" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.07.00"

[
  {
    "paymentMethodID": "string",
    "paymentMethodType": "moov-wallet",
    "wallet": {
      "walletID": "string",
      "partnerAccountID": "string",
      "walletType": "default"
    }
  }
]

You'll be able to add a sales tax, a surcharge fee (for credit card transactions), and enable tipping.

Tip options

Tips are enabled per payment link and can include preset options or a free-form option. Preset options can be either a percentage of the total, or set dollar amounts.

Use the POST create transfer config endpoint to select presets for the account.

curl -X POST "https://api.moov.io/accounts/{accountID}/transfer-config" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.07.00" \
  -d '{
  "tipPresets": {
    "calculationBasis": "pre-tax",
    "percentageOptions": [
      15,
      20,
      25
    ]
  }
}'

Once presets are created, you'll set tippingEnabled: true when creating the payment link and they'll be displayed in the payment link. A free-form tip option will also be included with the presets. If you have not created presets, but set tippingEnabled: true, the payment link will only display a free-form tip option by default.

Tax & surcharge fee

Tax and a surcharge fee can be added to amountDetails when creating a payment link. Surcharge fees can only be added to credit card transactions. Accounts must go through a registration process before surcharging is enabled.

See the surcharges guide for more information.

Send link

When you're ready, create and send a payment link via your chosen form of communication, such as email or SMS.

curl -X POST "https://api.moov.io/accounts/{accountID}/payment-links" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.07.00" \
  -d '{
  "partnerAccountID": "string",
  "merchantPaymentMethodID": "string",
  "amount": {
    "currency": "USD",
    "value": 11125
  },
  "amountDetails": {
    "tax": {
      "currency": "USD",
      "valueDecimal": "8.25"
    },
    "surcharge": {
      "currency": "USD",
      "valueDecimal": "3.00"
    }
  },
  "display": {
    "title": "Mrs. Gees Food Emporium",
    "description": "Monday lunch special",
    "callToAction": "pay"
  },
  "customer": {
    "requirePhone": true,
    "tippingEnabled": true
  },
  "payment": {
    "allowedMethods": [
      "card-payment"
    ]
  }
}'

The payee will receive a branded payment link with the various payment and tip options that have been set.

View the payment links guide for more information.