Simulate Billing Statements

Overview

test with dummy data

Do not enter production data in the Highnote Test environment, which is for exploring features and training. Use only dummy or test data.

Billing statements reflect money movement, balances, and fees on an account holder's financial account. This guide provides steps for simulating the following actions for billing statements:

Shifting the billing statement end period
Rolling the billing statement over to the next billing cycle

Prerequisites

A Highnote account
An API key or API Explorer
A credit or charge card product
A financial account with a generated billing statement
Optional - Simulated transactions

Simulate shifting the statement end period

info

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 statement. When performing this simulation, refer to the following guidelines:

Set the new period at least 60 seconds in the future.
If no periodBoundary is provided, the system defaults the statement’s endPeriod to 60 seconds from now.

To simulate changing a statement's end period for a consumer revolving credit card, use the following mutation:

SimulateShiftCurrentStatementPeriod

Query

fragment statement on ConsumerRevolvingCardFinancialAccountStatement {
  id
  __typename
  periodStart
  periodEnd
  openedAt
  closedAt
  createdAt
  updatedAt
  paymentDueOn
  pastDueAmount {
    value
    currencyCode
  }
  periodInterestCharges {
    value
    currencyCode
  }
  periodPurchaseCreditPlan {
    balanceType
    balanceSubjectToInterestAmount {
      value
      currencyCode
    }
    interestChargedAmount {
      value
      currencyCode
    }
  }
  payOffWarning {
    paymentCycles {
      payOffType
      paymentDetails {
        estimatedPayOffDays
        estimatedTotal {
          value
          currencyCode
        }
        periodPayment {
          value
          currencyCode
        }
      }
    }
  }
  periodMinimumPaymentDue {
    value
    currencyCode
  }
  primaryLedger {
    id
    name
    normalBalance
    creditBalance {
      value
    }
    debitBalance {
      value
    }
  }
  startingPrimaryCreditBalance {
    value
  }
  startingPrimaryDebitBalance {
    value
  }
  endingPrimaryCreditBalance {
    value
  }
  endingPrimaryDebitBalance {
    value
  }
  secondaryLedger {
    id
    name
    normalBalance
    creditBalance {
      value
    }
    debitBalance {
      value
    }
  }
  startingSecondaryCreditBalance {
    value
  }
  startingSecondaryDebitBalance {
    value
  }
  endingSecondaryCreditBalance {
    value
  }
  endingSecondaryDebitBalance {
    value
  }
}

mutation SimulateShiftCurrentStatementPeriod(
  $input: SimulateShiftCurrentFinancialAccountStatementPeriodInput!
) {
  simulateShiftCurrentFinancialAccountStatementPeriod(input: $input) {
    __typename
    ... on FinancialAccount {
      id
      statementSnapshot {
        ... on ConsumerRevolvingCardFinancialAccountStatementSnapshot {
          __typename
          asOf
          currentOpenStatement {
            ...statement
          }
          latestClosedStatement {
            ...statement
          }
        }
      }
    }
    ... on UserError {
      errors {
        errorPath
        code
      }
    }
  }
}

Variables

{
  "input": {
    "financialAccountId": "FINANCIAL_ACCOUNT_ID",
    "periodBoundary": "2023-04-05T00:43:26.96"
  }
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "simulateShiftCurrentFinancialAccountStatementPeriod": {
      "__typename": "FinancialAccount",
      "id": "FINANCIAL_ACCOUNT_ID",
      "statementSnapshot": {
        "__typename": "ConsumerRevolvingCardFinancialAccountStatementSnapshot",
        "asOf": "2023-12-05T00:17:45.591Z",
        "currentOpenStatement": {
          "id": "STATEMENT_ID",
          "__typename": "ConsumerRevolvingCardFinancialAccountStatement",
          "periodStart": "2023-12-04T05:00:00.000Z",
          "periodEnd": "2023-12-05T00:43:26.960Z",
          "openedAt": "2023-12-05T00:17:45.529Z",
          "closedAt": null,
          "paymentDueOn": "2023-12-15T00:43:26.960Z",
          "pastDueAmount": null,
          "periodMinimumPaymentDue": null,
          "primaryLedger": {
            "id": "FINANCIAL_ACCOUNT_ID",
            "name": "OUTSTANDING_BALANCE_PAYABLE",
            "normalBalance": "CREDIT",
            "creditBalance": {
              "value": 3000,
              "currencyCode": "USD"
            },
            "debitBalance": {
              "value": 0,
              "currencyCode": "USD"
            }
          },
          "startingPrimaryCreditBalance": {
            "value": 0,
            "currencyCode": "USD"
          },
          "startingPrimaryDebitBalance": {
            "value": 0,
            "currencyCode": "USD"
          },
          "endingPrimaryCreditBalance": {
            "value": 0,
            "currencyCode": "USD"
          },
          "endingPrimaryDebitBalance": {
            "value": 0,
            "currencyCode": "USD"
          },
          "periodInterestCharges": null,
          "periodPurchaseCreditPlan": [],
          "payOffWarning": {
            "paymentCycles": []
          },
          "secondaryLedger": {
            "id": "FINANCIAL_ACCOUNT_ID",
            "name": "AVAILABLE_CREDIT",
            "normalBalance": "CREDIT",
            "creditBalance": {
              "value": 47000,
              "currencyCode": "USD"
            },
            "debitBalance": {
              "value": 0,
              "currencyCode": "USD"
            }
          },
          "startingSecondaryCreditBalance": {
            "value": 0,
            "currencyCode": "USD"
          },
          "startingSecondaryDebitBalance": {
            "value": 0,
            "currencyCode": "USD"
          },
          "endingSecondaryCreditBalance": {
            "value": 0,
            "currencyCode": "USD"
          },
          "endingSecondaryDebitBalance": {
            "value": 0,
            "currencyCode": "USD"
          }
        }
      }
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID",
    "rateLimit": {
      "cost": 37,
      "limit": 60060,
      "remaining": 60023
    }
  }
}

Simulate rolling over to the next billing cycle

info

This simulation feature only works with credit card products at this time.

In the Test environment, you can transition a financial account’s billing period to the next cycle, simulating the end of one billing cycle and the start of another. To retrieve the simulated current amount due, refer to the appropriate statement snapshot type:

Card product type	Statement snapshot
Commercial charge	`CreditPayInFullCardFinancialAccountStatementSnapshot`
Consumer charge	`ConsumerChargeCardFinancialAccountStatementSnapshot`
Consumer revolving credit	`ConsumerRevolvingCardFinancialAccountStatementSnapshot`

Use the following mutation to simulate rolling over the current statement period for a consumer revolving credit card:

SimulateRolloverCurrentStatementPeriod

Query

fragment statement on ConsumerRevolvingCardFinancialAccountStatement {
  id
  __typename
  periodStart
  periodEnd
  openedAt
  closedAt
  paymentDueOn
  pastDueAmount {
    value
    currencyCode
  }
  periodMinimumPaymentDue {
    value
    currencyCode
  }
  primaryLedger {
    id
    name
    normalBalance
    creditBalance {
      value
      currencyCode
    }
    debitBalance {
      value
      currencyCode
    }
  }
  startingPrimaryCreditBalance {
    value
    currencyCode
  }
  startingPrimaryDebitBalance {
    value
    currencyCode
  }
  endingPrimaryCreditBalance {
    value
    currencyCode
  }
  endingPrimaryDebitBalance {
    value
    currencyCode
  }
  periodInterestCharges {
    value
    currencyCode
  }
  periodPurchaseCreditPlan {
    balanceType
    balanceSubjectToInterestAmount {
      value
      currencyCode
    }
    interestChargedAmount {
      value
      currencyCode
    }
    apr
  }
  payOffWarning {
    paymentCycles {
      payOffType
      paymentDetails {
        periodPayment {
          value
          currencyCode
        }
        estimatedTotal {
          value
          currencyCode
        }
        estimatedPayOffDays
      }
    }
  }
  secondaryLedger {
    id
    name
    normalBalance
    creditBalance {
      value
      currencyCode
    }
    debitBalance {
      value
      currencyCode
    }
  }
  startingSecondaryCreditBalance {
    value
    currencyCode
  }
  startingSecondaryDebitBalance {
    value
    currencyCode
  }
  endingSecondaryCreditBalance {
    value
    currencyCode
  }
  endingSecondaryDebitBalance {
    value
    currencyCode
  }
}

mutation SimulateRolloverCurrentStatementPeriod(
  $input: SimulateRolloverCurrentFinancialAccountStatementPeriodInput!
) {
  simulateRolloverCurrentFinancialAccountStatementPeriod(input: $input) {
    __typename
    ... on FinancialAccount {
      id
      statementSnapshot {
        ... on ConsumerRevolvingCardFinancialAccountStatementSnapshot {
          __typename
          asOf
          currentAmountDue {
            value
          }
          latestClosedStatement {
            ...statement
          }
        }
      }
    }
    ... on UserError {
      errors {
        errorPath
        code
      }
    }
  }
}

Variables

{
  "input": {
    "financialAccountId": "FINANCIAL_ACCOUNT_ID"
  }
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "simulateRolloverCurrentFinancialAccountStatementPeriod": {
      "__typename": "FinancialAccount",
      "id": "FINANCIAL_ACCOUNT_ID",
      "statementSnapshot": {
        "__typename": "ConsumerRevolvingCardFinancialAccountStatementSnapshot",
        "asOf": "2023-12-05T00:48:34.468Z",
        "currentAmountDue": {
          "value": 0
        },
        "latestClosedStatement": {
          "id": "STATEMENT_ID",
          "periodStart": "2023-09-30T05:00:00.000Z",
          "periodEnd": "2023-10-28T05:00:00.000Z",
          "openedAt": "2023-11-30T07:51:25.643Z",
          "closedAt": "2023-11-30T07:54:45.333Z",
          "paymentDueOn": "2023-11-05T05:00:00.000Z",
          "pastDueAmount": {
            "value": 5878,
            "currencyCode": "USD"
          },
          "periodMinimumPaymentDue": {
            "value": 11862,
            "currencyCode": "USD"
          },
          "primaryLedger": {
            "id": "FINANCIAL_ACCOUNT_ID",
            "name": "OUTSTANDING_BALANCE_PAYABLE",
            "normalBalance": "CREDIT",
            "creditBalance": {
              "value": 114835
            },
            "debitBalance": {
              "value": 0
            }
          },
          "startingPrimaryCreditBalance": {
            "value": 2473,
            "currencyCode": "USD"
          },
          "startingPrimaryDebitBalance": {
            "value": 0,
            "currencyCode": "USD"
          },
          "endingPrimaryCreditBalance": {
            "value": 114835,
            "currencyCode": "USD"
          },
          "endingPrimaryDebitBalance": {
            "value": 0,
            "currencyCode": "USD"
          },
          "periodInterestCharges": {
            "value": 2484,
            "currencyCode": "USD"
          },
          "periodPurchaseCreditPlan": [
            {
              "balanceType": "PURCHASE",
              "balanceSubjectToInterestAmount": {
                "value": 129202,
                "currencyCode": "USD"
              },
              "interestChargedAmount": {
                "value": 2484,
                "currencyCode": "USD"
              },
              "apr": 23.99
            }
          ],
          "payOffWarning": {
            "paymentCycles": [
              {
                "payOffType": "MINIMUM_PAY_OFF",
                "paymentDetails": {
                  "periodPayment": {
                    "value": 11862,
                    "currencyCode": "USD"
                  },
                  "estimatedTotal": {
                    "value": 149572,
                    "currencyCode": "USD"
                  },
                  "estimatedPayOffDays": 990
                }
              },
              {
                "payOffType": "THREE_YEAR_PAY_OFF",
                "paymentDetails": {
                  "periodPayment": {
                    "value": 11862,
                    "currencyCode": "USD"
                  },
                  "estimatedTotal": {
                    "value": 153470,
                    "currencyCode": "USD"
                  },
                  "estimatedPayOffDays": 1095
                }
              }
            ]
          },
          "secondaryLedger": {
            "id": "FINANCIAL_ACCOUNT_ID",
            "name": "AVAILABLE_CREDIT",
            "normalBalance": "CREDIT",
            "creditBalance": {
              "value": 85165
            },
            "debitBalance": {
              "value": 0
            }
          },
          "startingSecondaryCreditBalance": {
            "value": 200000
          },
          "startingSecondaryDebitBalance": {
            "value": 0
          },
          "endingSecondaryCreditBalance": {
            "value": 87649
          },
          "endingSecondaryDebitBalance": {
            "value": 0
          }
        }
      }
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID",
    "rateLimit": {
      "cost": 38,
      "limit": 60060,
      "remaining": 60022
    }
  }
}

Automate your integration

To automate your integration, subscribe to the financial account statement notification event.

The details provided in the payloads from this event can be used for the following use cases:

Automate your application or website's transaction processing workflow
Create account holder notifications and alerts

Overview​

Prerequisites​

Simulate shifting the statement end period​

SimulateShiftCurrentStatementPeriod​

Simulate rolling over to the next billing cycle​

SimulateRolloverCurrentStatementPeriod​

Automate your integration​