Partner billing

Learn about partner fees, residuals, and reconciliation.

During the onboarding process, you'll enter into a partner agreement with Moov. Your buy rate is configured as a fee plan and assigned to your partner account.

You can view your active partner pricing agreement using the GET partner pricing endpoint.

Fees and revenue

You can retrieve information about fees, including partner costs and merchant-generated revenue, using the GET fees endpoint. Use this endpoint for partner fees by passing in your partner accountID and for merchant fees passing in the merchant's accountID.

List all partner fees. Partner fees include all the fees charged to you, per your buy-rate. Use your partner accountID in the route. To find your partner account ID, navigate to Settings in the side navigation. Your partner account ID is located below your account name and logo.

1
2


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

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


[
  {
    "feeID": "9dae7250-d128-4dbb-bc2c-3c2e8a2fb42d",
    "accountID": "3dfff852-927d-47e8-822c-2fffc57ff6b9",
    "walletID": "0eb7d670-c252-422a-892d-002136c358e0",
    "createdOn": "2019-08-24T14:15:22Z",
    "feeName": "string",
    "amount": {
      "currency": "USD",
      "valueDecimal": "12.987654321"
    },
    "generatedBy": {
      "transferID": "e23de6dd-5168-4e1d-894d-807fa691dc80",
      "cardID": "f159b73e-e9c6-4dce-9609-2274bb1f8396",
      "disputeID": "5720fd8c-f7a6-4c10-a19a-d345b5f89bec",
      "accountID": "3dfff852-927d-47e8-822c-2fffc57ff6b9",
      "bankAccountID": "5b03c365-bcf1-4c70-aeec-29a06f15faf2"
    },
    "feeGroup": "string",
    "residualID": "8df0a983-e21b-44af-a8c4-c35403236f69"
  }
]

List all fees for a specific merchant account. Use a merchant's accountID in the route. To find a merchant's account ID, navigate to Accounts in the Dashboard and select or search for a merchant's account. Their merchant account ID is located below their name and logo. You can also find a merchant account ID using the accounts API.

1
2


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

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


[
  {
    "feeID": "9dae7250-d128-4dbb-bc2c-3c2e8a2fb42d",
    "accountID": "3dfff852-927d-47e8-822c-2fffc57ff6b9",
    "walletID": "0eb7d670-c252-422a-892d-002136c358e0",
    "createdOn": "2019-08-24T14:15:22Z",
    "feeName": "Card decline fee",
    "amount": {
      "currency": "USD",
      "valueDecimal": "15.987444321"
    },
    "generatedBy": {
      "transferID": "e23de6dd-5168-4e1d-894d-807fa691dc80",
      "cardID": "f159b73e-e9c6-4dce-9609-2274bb1f8396",
      "disputeID": "5720fd8c-f7a6-4c10-a19a-d345b5f89bec",
      "accountID": "3dfff852-927d-47e8-822c-2fffc57ff6b9",
      "bankAccountID": "5b03c365-bcf1-4c70-aeec-29a06f15faf2"
    },
    "feeGroup": "string",
    "residualID": "8df0a983-e21b-44af-a8c4-c35403236f69"
  }
]

Reconcile costs and revenue

Reconcile your costs and revenue without revenue share. Partner processing costs are debited from your wallet in real time as the billable events occur and fees are created. Merchant fees collected are credited to your wallet in real time.

To reconcile costs for a specific period, use the GET fees endpoint and query by the date range. The amount and feeGroup are included in the response. You can use these fields to filter fees.

1
2


curl -X GET "https://api.moov.io/accounts/{accountID}/fees?startDateTime=2025-12-24T14:15:22Z?endDateTime=2026-02-24T14:15:22Z" \
  -H "Authorization: Bearer {token}" \

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


[
  {
    "feeID": "9dae7250-d128-4dbb-bc2c-3c2e8a2fb42d",
    "accountID": "3dfff852-927d-47e8-822c-2fffc57ff6b9",
    "walletID": "0eb7d670-c252-422a-892d-002136c358e0",
    "createdOn": "2026-01-24T14:15:22Z",
    "feeName": "string",
    "amount": {
      "currency": "USD",
      "valueDecimal": "12.987654321"
    },
    "generatedBy": {
      "transferID": "e23de6dd-5168-4e1d-894d-807fa691dc80",
      "cardID": "f159b73e-e9c6-4dce-9609-2274bb1f8396",
      "accountID": "3dfff852-927d-47e8-822c-2fffc57ff6b9",
    },
    "feeGroup": "string",
    "residualID": "8df0a983-e21b-44af-a8c4-c35403236f69"
  }
]

While partner fees and merchant fee revenue are recorded throughout the period for reporting purposes, Moov generates a single residual settlement transaction one business day after the billing period closes with one of the following outcomes:

Positive residual: wallet is credited
Negative residual: wallet is debited

The wallet transaction's sourceID corresponds to the residualID, which you can use to reconcile the settlement.

Calculations

A residual represents your share of net income: netIncome = merchantFees − partnerCost

Fee revenue is the merchantFees on the residual. Fee revenue can also be retrieved using the GET fee revenue endpoint.

Your residualAmount = netIncome x revenueShare

Calculate

Retrieve the residual summary

Use the residualID to retrieve the residual record with the GET residuals endpoint.

1
2


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

The response provides the totals used in the calculation:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


{
  "residualID": "8df0a983-e21b-44af-a8c4-c35403236f69",
  "partnerAccountID": "c197cd40-7745-4413-8f3b-ec962d1b5225",
  "periodStart": "2019-08-24T14:15:22Z",
  "periodEnd": "2019-08-24T14:15:22Z",
  "merchantFees": {
    "currency": "USD",
    "valueDecimal": "12.987654321"
  },
  "partnerCost": {
    "currency": "USD",
    "valueDecimal": "12.987654321"
  },
  "netIncome": {
    "currency": "USD",
    "valueDecimal": "12.987654321"
  },
  "revenueShare": "2.25",
  "residualAmount": {
    "currency": "USD",
    "valueDecimal": "12.987654321"
  },
  "moovShare": {
    "currency": "USD",
    "valueDecimal": "12.987654321"
  },
  "createdOn": "2019-08-24T14:15:22Z"
}

Reconcile fee revenue

To view the merchant fee revenue entries included in the residual calculation, use your partner accountID with the GET fee revenues endpoint and query the residualID.

1
2


curl -X GET "https://api.moov.io/accounts/{accountID}/fee-revenue?residualID={residualID}" \
  -H "Authorization: Bearer {token}" \

This returns all fee revenue items applied to the residual. Optionally, you can group results by feeGroup to review the revenue breakdown. The total should match merchantFees from step one.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


[
  {
    "feeID": "9dae7250-d128-4dbb-bc2c-3c2e8a2fb42d",
    "accountID": "3dfff852-927d-47e8-822c-2fffc57ff6b9",
    "walletID": "0eb7d670-c252-422a-892d-002136c358e0",
    "createdOn": "2019-08-24T14:15:22Z",
    "feeName": "string",
    "amount": {
      "currency": "USD",
      "valueDecimal": "12.987654321"
    },
    "generatedBy": {
      "transferID": "e23de6dd-5168-4e1d-894d-807fa691dc80",
      "cardID": "f159b73e-e9c6-4dce-9609-2274bb1f8396",
      "accountID": "3dfff852-927d-47e8-822c-2fffc57ff6b9",
    },
    "feeGroup": "string",
    "residualID": "8df0a983-e21b-44af-a8c4-c35403236f69"
  }
]

Reconcile partner costs

To view the partner fees included in the residual calculation, use your partner accountID with the GET fees endpoint and query the residualID.

1
2


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

This returns all partner cost entries applied to the residual. You may optionally group results by feeGroup to review the cost breakdown. The total should match partnerCosts from step one.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


[
  {
    "feeID": "9dae7250-d128-4dbb-bc2c-3c2e8a2fb42d",
    "accountID": "3dfff852-927d-47e8-822c-2fffc57ff6b9",
    "walletID": "0eb7d670-c252-422a-892d-002136c358e0",
    "createdOn": "2019-08-24T14:15:22Z",
    "feeName": "string",
    "amount": {
      "currency": "USD",
      "valueDecimal": "12.987654321"
    },
    "generatedBy": {
      "transferID": "e23de6dd-5168-4e1d-894d-807fa691dc80",
      "cardID": "f159b73e-e9c6-4dce-9609-2274bb1f8396",
      "accountID": "3dfff852-927d-47e8-822c-2fffc57ff6b9",
    },
    "feeGroup": "string",
    "residualID": "8df0a983-e21b-44af-a8c4-c35403236f69"
  }
]

Confirm result match

Look at the residualAmount from step one and confirm the calculations and the residualAmount match.

Partner statements

Moov generates monthly statements for each partner account. Statements are made available on the first day of the following month for the previous month's activity. Partner statements will include a summary of the following:

Merchant fees collected for each fee category
Partner fees assessed for each fee category
Net income for each fee category
Residual payment (for revenue-share partners)
Monthly partner platform fees (if applicable)
Interchange report

Use the GET list statements endpoint to list all statements. You can filter by billingPeriodStartDate and billingPeriodEndDate to specify the time period.

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

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

Access statements

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"

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

Statement availability via email is coming soon.

Was this helpful?