Guides API reference Use cases Changelog

Merchant billing

Moov collects each account's fees from its Moov wallet according to the account's fee plan. Use this page to reconcile those fees and get monthly merchant statements.

Each merchant account needs a fee plan, assigned during onboarding. See fee plans. When a billable event happens, Moov debits the fee from the account's Moov wallet. Standard rounding applies to all fees except network fees, such as interchange and scheme fees, which pass through at exact cost.

Charges and reconciliation

Fees are assessed in real time and deducted from the account's wallet immediately after a transfer reaches its final state. For plans with monthly charges, fees are billed on the first of each month for the prior billing cycle.

You can list fees for a specific merchant account and list all assessed fee transactions in a merchant's wallet.

Use the list fees endpoint.

curl -X GET "https://api.moov.io/accounts/{accountID}/fees" \
  -H "Authorization: Bearer {token}" \
  -H "x-moov-version: v2026.07.00"

Reconciliation

Each wallet transaction includes key details to help you understand the charges:

  • transactionType: Always set to moov-fee
  • source: Indicates the origin of the fee: transfer, dispute, or fee
  • memo: A human-readable description of the charge (for example, Fee for card payment)

Moov aggregates all fees associated with the same source into a single wallet charge. For cost-plus pricing plans, this aggregated amount may include interchange, dues and assessments, and processing fees combined into one transaction.

When you retrieve or list transfers, each moov-fee transaction response contains a moovFees array that references the individual fees contributing to the total charge (query parameters allow you to filter by time range or transfer ID):

{
  "moovFees": [
    {
      "accountID": "7e4b26c2-b399-49ef-8390-50e1ea44d550",
      "feeIDs": [
        "9d957d33-1a9a-47aa-9460-fe1a90f003dd"
      ],
      "totalAmount": {
        "currency": "USD",
        "valueDecimal": "0.1"
      },
      "transferParty": "source"
    }
  ]
}

Also included in the response are the feeIDs. You can send feeIDs in the body of the POST list fees endpoint to retrieve a granular breakdown of each fee:

{
  "feeID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43",
  "accountID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43",
  "walletID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43",
  "createdOn": "2019-08-24T14:15:22Z",
  "feeName": "string",
  "amount": {
    "currency": "USD",
    "valueDecimal": "12.987654321"
  },
  "generatedBy": {
    "transferID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43"
  }
}

Merchant statements

Moov generates monthly statements for each merchant account. Statements are made available on the first day of the following month for the previous month's activity.

Merchant statements will include a summary of the following:

  • Fee names
  • Transaction processing fees for all rails
  • Count of instances of the fee assessed
  • Total fee amount assessed
  • Network passthrough fees - card network fees
  • Interchange report (cost-plus plans only)

For merchants on a cost-plus fee plan, you'll also receive a detailed interchange report that breaks down charges by interchange or discount program and rate.

Access statements

Partners are responsible for delivering billing statements to their merchants.

Use the list statements endpoint to list all statements. You can filter by billingPeriodStartDateTime and billingPeriodEndDateTime to specify the time period.

curl -X GET "https://api.moov.io/accounts/{accountID}/statements?billingPeriodStartDateTime=2025-06-10T23:00:00Z" \
  -H "Authorization: Bearer {token}" \
  -H "x-moov-version: v2026.07.00"

To download a specific statement in your preferred format (PDF or JSON), use the GET statements endpoint with an accept header.

curl -X GET "https://api.moov.io/accounts/{accountID}/statements/{statementID}" \
  -H "Authorization: Bearer {token}" \
  -H "x-moov-version: v2026.07.00" \
  -H "Accept: application/pdf"

Statements are available in the Dashboard and API. You can subscribe to the billingStatement.created webhook to receive real-time notifications on availability.

In the Dashboard, statements can be accessed by navigating Settings > Documents and clicking on the Statements tab.

Update fee plan

To move a merchant to a different fee plan, create a new agreement that replaces the prior one. See update fee plan.