Charge the Monthly Card Fee
Overview
The chargeAccountHolderFee mutation charges a fee to a financial account on request. It charges one fee type, MONTHLY_CARD_FEE. You can charge each financial account once for each billing month.
You calculate the amount, including any volume discount or proration, and send it. Highnote checks the amount against a limit and writes a fee transfer event. The ledger posts the charge shortly after.
Highnote configures the monthly card fee and its per-card maximum on your card product's fee schedule, or on an account-level fee schedule. If an account has no fee schedule with MONTHLY_CARD_FEE, the mutation returns FEE_NOT_CONFIGURED. For fee schedules, see Fees.
Any Subscriber can call the mutation with an API key that has access to fee transfers. A key without that access gets an AccessDeniedError.
Choose the billing month
A billing month is a UTC calendar month. The month must have ended before you charge it.
| What you send | Billing month |
|---|---|
No processingDate | The month before the month in which Highnote receives the request. |
A processingDate | The UTC month that contains the date. If that month has not ended, the request returns PERIOD_NOT_ENDED. Use this to charge a month you missed. |
Send the monthly charge after 00:00 UTC on the first day of the month. A request that Highnote receives before that time bills the month before the one you intend. This can happen when you send late in the day in a local time zone. To remove the doubt, send a processingDate that falls inside the month you want to bill.
Set the amount
The amount must meet these rules:
- It is greater than zero.
- It is in the currency of the financial account.
- It is in minor units. For USD,
500is USD 5.00.
Highnote charges the amount if it does not exceed the per-card maximum times the number of cards open during the billing month. Otherwise, the mutation returns FEE_AMOUNT_EXCEEDS_CARD_LIMIT. The error description gives the figures.
Highnote reads the per-card maximum when it receives your request. A request for a past month uses the maximum in force when Highnote receives the request, not the maximum in force during that month.
Send the charge
The following example charges the monthly card fee for the month before the request.
chargeAccountHolderFee
Query
mutation ChargeAccountHolderFee($input: ChargeAccountHolderFeeInput!) {
chargeAccountHolderFee(input: $input) {
__typename
... on FeeTransferEvent {
id
feeTransfer {
__typename
... on ChargedFeeTransfer {
feeActivityType
feeAmount {
value
currencyCode
}
feeTransferAmount {
value
currencyCode
}
originatingAccount {
id
}
transferDate
status {
__typename
... on NonFailureFeeTransferStatus {
status
}
... on FailureFeeTransferStatus {
status
reasonDetails {
type
reason
}
}
}
}
}
}
... on UserError {
errors {
code
description
errorPath
}
}
... on AccessDeniedError {
message
}
}
}
Variables
{ "input": { "fee": { "monthlyCardFee": { "financialAccountId": "<FINANCIAL_ACCOUNT_ID>", "amount": { "currencyCode": "USD", "value": 500 } } } } }
Result
{
"data": {
"chargeAccountHolderFee": {
"__typename": "FeeTransferEvent",
"id": "<FEE_TRANSFER_EVENT_ID>",
"feeTransfer": {
"__typename": "ChargedFeeTransfer",
"feeActivityType": "MONTHLY_CARD_FEE",
"feeAmount": {
"value": 500,
"currencyCode": "USD"
},
"feeTransferAmount": null,
"originatingAccount": null,
"transferDate": "2026-11-01T00:00:00.000Z",
"status": {
"__typename": "NonFailureFeeTransferStatus",
"status": "PENDING"
}
}
}
},
"extensions": {
"requestId": "REQUEST_ID"
}
}
To charge a specific month, add a processingDate that falls in that month. This example bills a different month than the first example, so you can run both against one financial account:
chargeAccountHolderFee - processingDate
Query
mutation ChargeAccountHolderFee($input: ChargeAccountHolderFeeInput!) {
chargeAccountHolderFee(input: $input) {
__typename
... on FeeTransferEvent {
id
feeTransfer {
__typename
... on ChargedFeeTransfer {
feeActivityType
feeAmount {
value
currencyCode
}
feeTransferAmount {
value
currencyCode
}
originatingAccount {
id
}
transferDate
status {
__typename
... on NonFailureFeeTransferStatus {
status
}
... on FailureFeeTransferStatus {
status
reasonDetails {
type
reason
}
}
}
}
}
}
... on UserError {
errors {
code
description
errorPath
}
}
... on AccessDeniedError {
message
}
}
}
Variables
{ "input": { "fee": { "monthlyCardFee": { "financialAccountId": "<FINANCIAL_ACCOUNT_ID>", "amount": { "currencyCode": "USD", "value": 500 }, "processingDate": "2026-09-15" } } } }
Result
{
"data": {
"chargeAccountHolderFee": {
"__typename": "FeeTransferEvent",
"id": "<FEE_TRANSFER_EVENT_ID>",
"feeTransfer": {
"__typename": "ChargedFeeTransfer",
"feeActivityType": "MONTHLY_CARD_FEE",
"feeAmount": {
"value": 500,
"currencyCode": "USD"
},
"feeTransferAmount": null,
"originatingAccount": null,
"transferDate": "2026-11-01T00:00:00.000Z",
"status": {
"__typename": "NonFailureFeeTransferStatus",
"status": "PENDING"
}
}
}
},
"extensions": {
"requestId": "REQUEST_ID"
}
}
Read the result
The mutation returns a FeeTransferEvent with the status PENDING. The charge is not complete yet. In the feeTransfer object, the originatingAccount, receivingAccount, and feeTransferAmount fields are null until the ledger posts the charge. The examples select originatingAccount and feeTransferAmount. The feeAmount field shows the amount you sent.
When the ledger posts the charge, the status moves to COMPLETE. If the ledger cannot post it, the status moves to FAIL, and reasonDetails gives the reason.
The transferDate field is the date and time Highnote charged the fee. It is not the billing month.
Store the id of the fee transfer event from the first response. Follow the charge until its status is COMPLETE or FAIL.
While the charge is PENDING, the fee transfer has no account fields, so you cannot match the event to a financial account. The feeTransferEvents query filters by card product, dates, and account IDs. It does not filter by fee activity type, so filter for MONTHLY_CARD_FEE in your own code. See Search for collected fees.
Retry a charge
A second charge for the same financial account and billing month returns FEE_ALREADY_CHARGED_FOR_PERIOD. Highnote already accepted a charge for that month. Do not send it again. Before you record the fee as collected, check the status of the first charge. A charge that is PENDING can still move to FAIL.
Send the same processingDate on every retry. A retry without one bills the month before the retry, which is a different month if the first request was sent near the end of a month.
The retry does not return the ID of the first charge. If you did not store it, query feeTransferEvents for the card product and the date range, and filter for MONTHLY_CARD_FEE in your own code. After the ledger posts the charge, you can match it by originatingAccount. See Read the result.
Highnote checks the limit first. A retry with an amount over the limit returns FEE_AMOUNT_EXCEEDS_CARD_LIMIT, not FEE_ALREADY_CHARGED_FOR_PERIOD.
chargeAccountHolderFee - already charged
Query
mutation ChargeAccountHolderFee($input: ChargeAccountHolderFeeInput!) {
chargeAccountHolderFee(input: $input) {
__typename
... on FeeTransferEvent {
id
feeTransfer {
__typename
... on ChargedFeeTransfer {
feeActivityType
feeAmount {
value
currencyCode
}
feeTransferAmount {
value
currencyCode
}
originatingAccount {
id
}
transferDate
status {
__typename
... on NonFailureFeeTransferStatus {
status
}
... on FailureFeeTransferStatus {
status
reasonDetails {
type
reason
}
}
}
}
}
}
... on UserError {
errors {
code
description
errorPath
}
}
... on AccessDeniedError {
message
}
}
}
Variables
{ "input": { "fee": { "monthlyCardFee": { "financialAccountId": "<FINANCIAL_ACCOUNT_ID>", "amount": { "currencyCode": "USD", "value": 500 } } } } }
Result
{
"data": {
"chargeAccountHolderFee": {
"__typename": "UserError",
"errors": [
{
"code": "FEE_ALREADY_CHARGED_FOR_PERIOD",
"description": "MONTHLY_CARD_FEE was already charged to account <FINANCIAL_ACCOUNT_ID> for 2026_10",
"errorPath": [
"input",
"fee",
"monthlyCardFee",
"processingDate"
]
}
]
}
},
"extensions": {
"requestId": "REQUEST_ID"
}
}
A month stays charged if the charge later fails in the ledger, or if you reverse it. A new request for that month returns FEE_ALREADY_CHARGED_FOR_PERIOD. To correct the month, contact your Highnote representative.
Handle failures
Request errors come back as a UserError. Check __typename, then read each error's code and description. The errorPath points to the input field at fault, under input.fee.monthlyCardFee.
| Code | Cause | What to do |
|---|---|---|
FEE_AMOUNT_NOT_POSITIVE | The amount is zero or less. | Send an amount greater than zero. |
FEE_AMOUNT_CURRENCY_MISMATCH | The amount is not in the currency of the financial account. | Send the amount in the account's currency. |
PERIOD_NOT_ENDED | The billing month has not ended. | Wait until after 00:00 UTC on the 1st, or send a processingDate in an earlier month. |
FINANCIAL_ACCOUNT_NOT_FOUND | Highnote found no financial account with that ID in your organization. | Check the financialAccountId. |
FEE_NOT_CONFIGURED | Highnote has not configured MONTHLY_CARD_FEE for the account, the fee rule has no flat amount, or the fee rule is in a different currency than the account. | Contact your Highnote representative. |
AMBIGUOUS_FEE_CONFIGURATION | More than one fee rule for MONTHLY_CARD_FEE applies to the account. | Contact your Highnote representative. Highnote does not charge until it fixes the setup. |
FEE_AMOUNT_EXCEEDS_CARD_LIMIT | The amount is above the per-card maximum times the cards open in the billing month. | Lower the amount. The error description gives the figures. |
FEE_ALREADY_CHARGED_FOR_PERIOD | Highnote already charged this account for the billing month. | Do not charge again. Check the first charge. See Retry a charge. |
Highnote checks for a closed financial account last. If the request passes the other checks, a closed account returns a UserError with an empty errors list. Highnote does not charge it. Do not retry. A closed account can also return FEE_AMOUNT_EXCEEDS_CARD_LIMIT or FEE_ALREADY_CHARGED_FOR_PERIOD, because those checks run first.
If the request fails with a GraphQL error and not a UserError, you cannot tell whether Highnote wrote the charge before the error. A failed card count and a timeout look the same. Retry with the same processingDate. If Highnote accepted the first request, the retry returns FEE_ALREADY_CHARGED_FOR_PERIOD. Read that code as "the first request was accepted". See Retry a charge.
Other error codes can occur. Read the description of each error.
Test the charge
In the Test environment, you can call this mutation. For the charge to succeed:
- The financial account needs a fee schedule with
MONTHLY_CARD_FEE. Without one, the mutation returnsFEE_NOT_CONFIGURED. - The account needs at least one card that was open in the billing month. Without one, the limit is zero and the mutation returns
FEE_AMOUNT_EXCEEDS_CARD_LIMIT. - The billing month must have ended. Send a
processingDatein an earlier month.
You cannot simulate a card created in an earlier month, so use a financial account that already has cards from the previous month.
Next steps
- Review fee schedules and fee activity types in Fees.
- Find a charge with Search for collected fees.
- Reverse a charge with Waive fees.
- Subscribe to fee notifications. See Fee transfer.