1. Guides
2. Billing

Each merchant account must be configured with a custom fee plan during onboarding. When a billable event is triggered, the corresponding fee, calculated based on the account's fee plan, is debited from the Moov wallet. Moov provides you with monthly statements so you can reconcile your merchant processing costs. This guide will walk you through accessing and understanding merchant billing and statements.

To configure and assign fee plans, see the fee plan guide. In order to pass through exact costs, standard rounding is applied on all fees with the exception of network fees (interchange, scheme fees, etc.).

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.

1
2

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

1
2
3

curl -X GET "https://api.moov.io/accounts/{accountID}/wallets/{walletID}/transactions?transactionType=moov-fee" \
  -H "Authorization: Bearer {token}" \
  -H "x-moov-version: v2024.01.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):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "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 billingPeriodStartDate and billingPeriodEndDate to specify the time period.

1
2

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

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

1
2
3

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

Statements are available in the Dashboard and API. You can subscribe to the statement.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.