# API & Drops quick start
This quick start guide brings you through the process of signing up for Moov, getting authorized for production, and creating user accounts with Moov's API and Moov.js Drops.
This guide focuses on the quickest and easiest way to get set up with a partner account and create your first merchant account with Moov's API and Drops. With the API you can send secure onboarding links to merchants and create payment links to facilitate payments and payouts.
After setting up your own account, you can add and connect additional business and individual accounts to your Moov account. See the linked guides below for more robust documentation:
[API](/api/)
[Moov.js](/moovjs/)
[Drops](/moovjs/drops/)
Additionally, check out the [glossary](/guides/get-started/glossary/) for a list of terms and concepts associated with Moov and the [integration](/guides/get-started/integration-options/) guide to see the complexity of various integration options.
## [Sign up for Moov](#sign-up-for-moov)
Before you get started with the API or Drops, you'll use the [Moov Dashboard](https://dashboard.moov.io/signup) 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](/guides/accounts/requirements/) section for more information, or [contact Moov](https://moov.io/contact/) 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](#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](/guides/get-started/api-keys/) documentation for more information. If you're ready to jump into production mode, make sure to take any [necessary precautions](#switch-to-production-mode) if you've previously been using test mode.
## [Explore test mode](#explore-test-mode)
In [test mode](/guides/get-started/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](/api/moov-accounts/accounts/) and [payment links API](/api/money-movement/payment-links/), you can set `"mode": "sandbox"` to test in sandbox mode with [test mode data](/guides/get-started/test-mode/#test-mode-data).
Try out the following:
- Add a bank account
- Initiate verification
- Initiate a transfer
- Initiate a return
### [Switch to production mode](#switch-to-production-mode)
When you're ready to switch to [production mode](/guides/get-started/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](#set-brand-colors)
Select light and dark mode brand color settings with the `POST` create brand [endpoint](/api/enrichment/branding/create/).
```zsh
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](#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](https://support.moov.io/articles/2845506014-merchant-onboarding) 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](#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](/guides/accounts/capabilities/reference/) 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:
| Capability | Description |
|---------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `transfers` | Participation in any Moov transfer. Auto-enabled on all qualifying accounts. |
| `wallet.balance` | Hold funds in a Moov wallet; participate in wallet-to-wallet transfers. Auto-enabled when any collect/send/money-transfer/card-issuing capability is enabled |
| `collect-funds.card-payments` | Accept card and digital wallet payments |
| `collect-funds.ach` | Accept ACH debit payments |
| `send-funds.ach` | ACH credits (standard and same-day) |
| `send-funds.instant-bank` | Real-time payouts via RTP (FedNow support coming soon) |
| `send-funds.push-to-card` | Instant card payouts (Visa Direct & Mastercard Send) |
| `money-transfer.pull-from-card` | Pull funds from cards (Visa Direct & Mastercard Send) |
| `money-transfer.push-to-card` | Push funds to cards (Visa Direct & Mastercard Send) |
| `card-issuing` | Create and manage virtual prepaid cards |
See our [capabilities](/guides/accounts/capabilities/) section for more information.
### [Select scopes](#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`).
Available scopes:
- `accounts.read`
- `accounts.write`
- `analytics.read`
- `apple-pay-merchant.read`
- `apple-pay-merchant.write`
- `apple-pay.read`
- `apple-pay.write`
- `bank-accounts.read`
- `bank-accounts.write`
- `capabilities.read`
- `capabilities.write`
- `cards.read`
- `cards.write`
- `documents.read`
- `documents.write`
- `fed.read`
- `files.read`
- `files.write`
- `issued-cards.read`
- `issued-cards.write`
- `issued-cards.read-secure`
- `payment-methods.read`
- `ping.read`
- `profile-enrichment.read`
- `profile.read`
- `profile.write`
- `profile.disconnect`
- `representatives.read`
- `representatives.write`
- `transfers.read`
- `transfers.write`
- `wallets.read`
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](/guides/accounts/connections/) guide for more information.
### [Select pricing fee plan](#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](/guides/accounts/requirements/platform-agreement/) 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](/api/moov-accounts/billing/list-plans/).
You'll use the `planID` provided in the response when creating an onboarding link.
[Request](#tab-853496712-1-0) [Response](#tab-853496712-1-1)
```zsh
curl -X GET "https://api.moov.io/accounts/{accountID}/fee-plans" \
-H "Authorization: Bearer {token}" \
-H "X-Moov-Version: v2026.07.00"
```
```json
[
{
"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](/guides/fee-plans/plan-options/) guide for more information and details on billable events.
### [Create & send onboarding link](#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.
[Request](#tab-647582139-2-0) [Response](#tab-647582139-2-1)
```zsh
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"
}
}
}
}'\
```
```json
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](/guides/sources/bank-accounts/verification/instant-micro-deposit/), 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](/api/moov-accounts/onboarding/get/) will show you if the code has been redeemed or not via the `redeemedOn` timestamp.
[Request](#tab-497632158-3-0) [Response](#tab-497632158-3-1)
```zsh
curl -X GET "https://api.moov.io/onboarding-invites/{code}" \
-H "Authorization: Bearer {token}" \
-H "X-Moov-Version: v2026.07.00"
```
```json
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.
[Request](#tab-347582196-4-0) [Response](#tab-347582196-4-1)
```zsh
curl -X GET "https://api.moov.io/accounts/{accountID}/capabilities" \
-H "Authorization: Bearer {token}" \
-H "X-Moov-Version: v2026.07.00"
```
```json
[
{
"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)](#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](/moovjs/) package. After [initializing](/moovjs/installation/) Moov.js, you will have access to our full library of Drops.
The Drop is an HTML element with [properties](/moovjs/drops/onboarding/#properties) accessed through JavaScript using a reference to the `moov-onboarding` element.
Initialize the Drop with Moov.js:
```html
```
And load the Drop:
```html
```
See the [onboarding Drop](/moovjs/drops/onboarding/) guide for more information. Moov also provides a standalone [terms of service agreement](/moovjs/drops/terms-of-service/) Drop.
After an account is onboarded, use the [payment methods Drop](/moovjs/drops/payment-methods/) to allow the account owner to register new payment methods to their account.
## [Create a product](#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](/api/tools/products/post/) to create a product.
```zsh
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](/guides/account-tools/product-catalog/) guide for more information.
## [Move money with payment links](#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](/api/sources/payment-methods/list/) with the account's `accountID` to retrieve a list of payment methods associated with the account.
[Request](#tab-643257189-0-0) [Response](#tab-643257189-0-1)
```zsh
curl -X GET "https://api.moov.io/accounts/{accountID}/payment-methods" \
-H "Authorization: Bearer {token}" \
-H "X-Moov-Version: v2026.07.00"
```
```json
[
{
"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](#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](/api/v2026.07.00/money-movement/transfers/create-transfer-config/) to select presets for the account.
```zsh
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--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](/guides/money-movement/accept-payments/card-acceptance/surcharges/) guide for more information.
If enabled, surcharge fees must follow card brand caps, as well as additional federal and state regulations.
### [Send link](#send-link)
When you're ready, create and send a payment link via your chosen form of communication, such as email or SMS.
```zsh
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](/guides/money-movement/payment-links/) guide for more information.
## [Resolution links](#resolution-links)
If an account doesn't finish onboarding, or the process results in errors, you can send a secure, temporary resolution link to resolve requirement errors surfaced during verification. Resolution links let end users self-serve by correcting or providing the additional information needed to resolve these errors and enable the capability.
Use the `POST` create resolution link [endpoint](/api/moov-accounts/resolution-links/create/) to send a request to the merchant.
```zsh
curl -X POST "https://api.moov.io/accounts/{accountID}/resolution-links" \
-H "Authorization: Bearer {token}" \
-H "X-Moov-Version: v2026.07.00" \
-d '{
"recipient": {
"email": "amanda@wbfgym.dev"
}
}'
```
## [Troubleshoot](#troubleshoot)
Troubleshoot some common issues when integrating with and using Moov:
### [Transfers or payment links not working](#transfers-or-payment-links-not-working)
Transfers and payment links will not work before [capabilities](/guides/accounts/capabilities/) are enabled. Ensure all involved accounts have the proper capabilities requested and enabled before attempting a transfer.
### [Missing terms of service agreement](#missing-terms-of-service-agreement)
All Moov accounts requiring wallet, send funds, or collect funds capabilities must agree to Moov's [platform terms of service agreement](/guides/accounts/requirements/platform-agreement/). If the agreement is missing on an account, the account will not be able to participate in any action on Moov's platform that requires a wallet, sending funds, or collecting funds.
## [Next steps](#next-steps)
You can manage wallet balances, send invoices, process refunds, and set up scheduled and recurring transfers all within the Dashboard. See our [Dashboard](https://docs.moov.io/guides/dashboard/) documentation for more information.
[Wallets](/guides/money-movement/wallets/)
[Invoices](/guides/money-movement/invoices/)
[Reversals & refunds](/guides/money-movement/accept-payments/card-acceptance/reversals/)
[Scheduled & recurring transfers](/guides/money-movement/scheduling/)
Explore other ways to integrate Moov:
- [Dashboard](/guides/dashboard/)
- SDKs: [Server-side](/sdks/#server-side-sdks) & [client-side](/sdks/#client-side-sdks)
- [Moov.js](/moovjs/)
- [More Drops](/moovjs/drops/)