Home / Guides/ Handle Transactions
Deliver Statements
Providing your Account Holders with billing statements is recommended whenever your product assesses fees and may be required for certain products, such as Credit. Highnote provides the data necessary to create a statement, which you can leverage to populate your own statement template. This guide will walk you through how to retrieve a Financial Accounts' billing data for your Account Holders.
You can get notified when new billing statements are available for Financial Accounts using the FINANCIAL_ACCOUNT_STATEMENT_READY notification event. This notification event allows you to generate statements for your account holders. See Notifications to learn more about subscribing to events.
Billing statement data is created on Financial Accounts and becomes available at the end of a billing cycle. The billing period end date for Credit Card products may vary across Financial Accounts on your portfolio. Statement data is typically available within 48 hours of a billing period's end date.
You can query the latest billing statement data for a Financial Account to generate the Account’s statement in the latestClosedStatement. Billing statements will only include posted transactions and the associated balances for a given billing period. Transactions for the Financial Account’s current billing period and the subsequent upcoming due date can be found in the currentOpenStatement.
When a balance is due on the Financial Account, the currentAmountDue will be updated based on credits to the Financial Account between the billing period end date and the due date. You’ll need to reference the type of CreditPayInFullCardFinancialAccountStatementSnapshot or SecuredDepositCommercialCreditCardFinancialAccountStatementSnapshot to retrieve the current amount due based on your Card Product. You can present this balance to your customer outside the statement so they know the remaining amount owed since their last statement was generated.
The billing statement period start date, end date, and due date occur at midnight Eastern Standard Time (EST) or Eastern Daylight Time (EDT) and are presented in Coordinated Universal Time (UTC). If you present the start date, end date, and due date fields to Account Holders, ensure you update the calendar day based on the applicable time zone. The following table provides an example of updating the calendar day for each of these fields:
| Field | Example |
|---|---|
paymentDueOn | To present the due date for the North American region, subtract by one calendar day. |
periodStart | To present the billing period start date for the North American region, do not change the calendar date. |
periodEnd | To present the billing period end date for the North American region, subtract by one calendar day. |
You can use the following query to generate the current billing statement for an Account Holder:
You can also search for the history of billing statements on a Financial Account based on a date range for your Account Holders to view. Up to 24 months of billing statement history can be provided. The results will be empty if statement data is unavailable for the Financial Account. You can query by periodStart or periodEnd.
You can use the following query to find billing statement history:
You can search for a billing statement’s details with a provided statement ID. In addition to retrieving the detailed transactions of the financialEvent in the statement's billing cycle period, you can retrieve the summary level balances for the statement's billing cycle. The following table provides elements of the summary statement balance that can be retrieved:
| SUMMARY STATEMENT BALANCE | FIELD | DESCRIPTION |
|---|---|---|
| Beginning Balance | startingPrimaryCreditBalance or startingPrimaryDebitBalance | The outstanding balance on the Financial Account as of the start of the statement’s billing cycle. |
| Total Purchases | periodPurchasesAmount | The total purchases posted to the Financial Account in the billing cycle period. |
| Total Payments & Refunds | periodRefundsAndPaymentsAmount | The total payments, returns, or refunds posted to the Financial Account in the billing cycle period. |
| Total Fees | periodFeeAmount | The total fees assessed on the Financial Account in the billing cycle period. |
| Ending Balance | endingPrimaryCreditBalance or endingPrimaryDebitBalance | The outstanding balance on the Financial Account at the end of the statement’s billing cycle. |
| Past Due Balance | pastDueAmount | The past due balance on the Financial Account as of the close of the statement’s billing cycle. This is only available for Commercial Charge Card Products. |
Use the following query to fetch a statement by ID:
Statement entries are paginated and can be filtered by their post date and whether they are credit or debit. Use the following query to filter statement entries:
This simulation feature is only compatible with Credit Card Products at this time.
In the Test Environment, you can end a Financial Account’s billing period early to simulate a billing period’s statement. The new period must be at least 60 seconds in the future, and if the periodBoundary is not supplied, the statement endPeriod will be set to 60 seconds in the future.
Use the following mutation to simulate shifting a statement's end period:
This simulation feature only works with Credit Card Products at this time.
In the Test Environment, you can roll over a Financial Account’s billing period to the next billing cycle so you can simulate ending and starting a new billing cycle for a Financial Account. You’ll need to reference the type of CreditPayInFullCardFinancialAccountStatementSnapshot or SecuredDepositCommercialCreditCardFinancialAccountStatementSnapshot to retrieve the simulated, current amount due, based on your Card Product.