Reporting
Quick Start: Gather Reporting Data!
Below is a detailed guide on how to pull Reporting data using the Newline platform. In this guide, we go through each step, the API and endpoints utilized, and any important fields for key payments operations.
However, for those familiar with payments and key reporting, and eager to find details fast, we've provided a list of steps.
- For Balance Reporting, utilize any of the GET requests against the Synthetic Accounts object.
- For Transaction Reporting, utilize any of the GET requests against the Transactions object.
Introduction: Reporting Details
Newline seeks to provide our clients with accurate and timely data about their accounts and transactions. This data helps clients to fulfill critical business functions from the mundane reconciliation tasks to time critical cash management decisions. Before we dive into the types of reporting data supported by Newline, let's cover the APIs involved.
| API | Usage |
|---|---|
| Synthetic Account | As one of our account constructs, Synthetic Accounts maintain balance information that can help clients and end-customers manage their liquidity. |
| Transactions | Transactions will store key information produced during origination. For instance, any ID produced by a network will be stored and returned. These IDs can be used for secondary confirmation that your transaction has been appropriately processed and executed. |
API or File? Choose your delivery method
Sometimes, API-based reporting isn't your exact need. Maybe your systems for reconciliation or accounting require file-based methods to optimally perform. If this rings true, then Newline can also provide you with a set of CSV (comma-separated values) files. The values provided, either through our API or file-based methods, are identical; however, there are processing considerations to review when choosing either method. Since the API-based is on demand, we'll focus on the file-based method below.
File-based delivery details
CSV Reports available
| Report | Purpose | Calculations | API Equivalent |
|---|---|---|---|
| Accounts | Provides balance information for all the accounts belonging to a Client's Customer Program. | Balance information in this report is based off of the Settled Transactions report. | List Synthetic Accounts |
| Client Pending Authorizations Report | Includes all transactions with an authorization status of client_approval_pending. | For programs with client authorization enables, CSV reports now include the following new columns: authorization_finalized_at, authorization_required_by, authorization_status, denied_memo, and denied_reason.These updates will be used in settled and updated transaction reports, as well as in new client pending authorizations and denied authorization reports. All payment rail information (i.e., ACH, Wire, or Instant Payment nest objects) are provided as JSON blobs, inserted into titular columns. This report also contains payment network information where appropriate. For instance, NOCs (see ACH guide) are included. | List Transactions with status filter applied. |
| Denied Authorizations Report | Includes all transactions with an authorization status of client_denied, client_unanswered_auto_denied, or auto_denied. | For programs with client authorization enables, CSV reports now include the following new columns: authorization_finalized_at, authorization_required_by, authorization_status, denied_memo, and denied_reason.These updates will be used in settled and updated transaction reports, as well as in new client pending authorizations and denied authorization reports. All payment rail information (i.e., ACH, Wire, or Instant Payment nest objects) are provided as JSON blobs, inserted into titular columns. This report also contains payment network information where appropriate. For instance, NOCs (see ACH guide) are included. | List Transactions with status filter applied. |
| Updated Transactions | Provides Transaction information for all transactions, in a terminal state, attributed to the accounts of a Client's Customer Program. The Transactions in this report include only the following states: failed, canceled, denied, expired. The only exception is a NOC for a settled ACH transaction. | All payment rail information (i.e., ACH, Wire, or Instant Payment nest objects) are provided as JSON blobs, inserted into titular columns. This report also contains payment network information where appropriate. For instance, NOCs (see ACH guide) are included. | List Transactions with status filter applied. |
| Settled Transactions | Provides Transaction information for all transactions, in the settled state, attributed to the accounts of a Client's Customer Program. | All transaction information is provided as JSON blobs, inserted into titular, payment rail columns. Reporting cadences determine what Transactions appear in this report (see below). | List Transactions with status filter applied. |
Processing and Cadence
File-based reporting can be produced in two particular flavors, each with their own preset cadences: Intra-day and Prior-day. Clients can subscribe to both flavors as needed.
- Intra-day: Produced in certain intervals, supplied by the client, that range from 15 minutes and 24 hours.
NoteIf you maintain a Cron schedule, you can provide that to your Newline Specialist, and they will include that in your program setup.
- Prior-day: Produced once a day (i.e., 24 duration).
Delivery
For both Sandbox and Production, Newline will configure and set up an SFTP (secure file transfer protocol) directory where these reports can either be sent to a Client's specified SFTP server or pulled from a Newline managed SFTP server. This will be discussed with your Newline Specialist during implementation so that any preferred delivery method is included in the program setup.
Error Handling
For intra-day reporting, when a file generation error occurs, Newline will include any Transactions that would have been included on that report and provide them on the next available report created.
For example -
- A Client specifies they'd like intra-day reporting provided every 30 minutes.
- A report at 9:30am fails and isn't re-generated and delivered until 9:37am.
- This new report contains all Transactions that occurred between 9:00-9:37am.
- The next expected report is at 10:00am, and it will include all Transactions that occurred between 9:38-10am.
Newline's error handling should prevent any missed Transactions or duplicate Transactions records from being reported.
For prior-day reporting, Newline will not perform this above Transaction catch-up logic, and simply provide the prior 24-hour period.
Types of Reporting
In Newline's initial release, we'll support both Balance and Transaction reporting, as they are part of established builds and utilized during core payments use cases.
Balance Reporting
As mentioned above, Balance reporting is included as part of the Synthetic Account. Within a Synthetic Account, there are three fields related to balances that can be utilized.
| Field | Context |
|---|---|
net_usd_balance | This field encompasses only settled transactions. Typically, transactions settle at the end of every business day, so this balance is most reflective of your account's balance at the start of each business day. |
net_usd_pending_balance | This field encompasses all settled and pending transactions, which means this balance is reflective of any pending credits or debits. |
net_usd_available_balance | This field encompasses all settled and pending debit transactions. This balance field can be utilized to identify an account's "remaining spend." Some payment rails like, Instant Payments, require pre-funding, so this field can be useful in preventing any insufficient funds (or NSF) error returned by the respective network. |
To retrieve this data, users can either request a single Synthetic Account, or pull a bulk request and list Synthetic Accounts attributed to a specific Customer.
Transaction Reporting
Transactions will contain important fields based on their type. Below is a table of key reporting fields that can be utilized when assessing or auditing the current state of your Transactions.
| Field | Context |
|---|---|
| Network Confirmation IDs | These IDs are provided by the respective payment network to allow originators assurance that their payment has been accepted and is being processed. For instance, wire payments will include either an imad or chips_ssn which are fields provided by the FedWire and CHIPS networks, respectively, confirming that the wire transfer in question has been successfully sent. An instant_payment will have the aptly named network_confirmation_id, and only one type of ID is noted as Newline currently only supports the RTP network. |
| Payment Volumes | Payment volumes can be pulled by utilizing the count and total_count fields when using the List Transactions endpoint. count refers to the amount of transactions returned based on your response while total_count lists the available Transactions to retrieve. It's important to utilize our API's available query parameters to segment your requested set. |
| Payment Totals | Payment totals are not readily provided by Newline, but they can be calculated by using the data returned when retrieving Transactions. As stated in the Payment Volumes row, it's important to utilize our API's available query parameters to segment your requested set. |
| Errors | Errors can be thrown by both Newline and the payment networks. When debugging a Transfer or Transaction related error, its important to understand the source as that will dictate where the additional information is available for review. Refer to the API Errors guide for more detail. |
To retrieve this data, users can either get a single Transaction, or pull a bulk request and list Transactions attributed to a specific Customer.
Newline and Alternate Channels
Reminder
As mentioned above, given that our Transactions API pulls back all transactions associated with a Synthetic Account, it’s very likely you’ll have visibility into transactions that were originated outside of the Newline platform.
These could be several different transaction types, like standard deposits, card transactions or book transfers. If a Client or Customer is particularly interested in Transfers initiated on Newline, we provide associated transfer_uid as a field returned in the Transaction.
Updated about 2 months ago