Reports Reference

Product version Nium 3.91
Last edited January 2023

/ta#About this guide

Overview

The Nium product comes with a set of reports. These reports are used to reconcile financial activities performed through the application. This reference guide will show you how to access, interpret and use standard Nium reports.

๐Ÿšง

IMPORTANT

This document is intended solely for the recipient and only for use for the purposes agreed by Nium with the recipient. It contains confidential and commercially sensitive information. Do not use, copy or disclose the information contained in this document. If you have received this document in error, or if you are not bound by a confidentiality agreement with Nium, please notify us and immediately on [email protected] and delete or destroy the document and all copies you may have.

๐Ÿ“˜

NOTE

You can access full transaction history of a card using the Nium API, but this type of access is generally not feasible. You can use reports instead.

Whatโ€™s new in this version?

15th February 20213.74Updated formatting to match brand guidelines
2nd June 20213.76Introduced tab in Scheduled Loads Report to list all pending loads
13th August 20213.79Added ECB rate definition to Card Activity daily and monthly reports
24th August 20213.79Revised Card Activity Custom Field definition
12th April 20223.79Product and documentation rebranding
29th November 20213.83Added disputes to the Balance Sheet Report.
Added dispute transaction types to the Card activity: Daily report.
19th of August 20223.91Redirect hosting URLs from Ixaris into Nium domain; enhancing supported encoding for csv file in Create Cards in Bulk
12th of January3.91Product documentation transition to web view

Available reports

Card activity: DailyThis report contains all the transactions made on a specific day on all cards
Card activity: MonthlyThis report contains all the transactions made in a specific month on all cards.
Funding account activity: DailyThis report contains all the transactions for each funding account for a specific day.
Funding account activity: MonthlyThis report contains all the transactions for each funding account for a specific month.
Non-zero card balancesThis report contains all the cards that have an actual balance that is greater than zero
Balance sheetThis report contains a breakdown of the sum of funds deposited and how the funds have been used
Scheduled loadsThis report contains current pending loads and the minimum amount required in a funding account (per currency) to cover all the pending loads.
Credit activityThis report contains a daily snapshot as at end of day, visualizing all the credit activity for all the credit funding accounts of a deployment.
Credit statementA credit statement issued per deployment outlining the final outstanding balance per funding account as at cycle end date.

Report naming conventions

Nium reports follow these naming conventions.

Daily report convention:

All daily report names follow the following naming convention:
reportName_frequency_reportGenerationDate_batchNumber

Monthly report convention:

All monthly report names follow the following naming convention:
reportName_frequency_reportGenerationDate_transactionMonth

This is how to interpret report elements:

ELEMENT
reportName
This element indicates the name of the report, for example:
Card_Acvitity, Funding_Account_Activity
frequency
This element indicates the report frequency and can have one of two values:
Daily _or _Monthly
FREQUENCYDESCRIPTION
DailyA daily report contains a list of transactions made on a specific day.
MonthlyA monthly report contains data for a specific calendar month from the first day of the calendar month to the last day of the calendar month.
reportGenerationDate
This element indicates the date and time of when the report was generated by the system. The date is presented in the following format:
yyyy-mm-dd-hh24-mi-ss

๐Ÿ“˜

NOTE

All time values are represented using the Coordinated Universal Time (UTC). UTC does not change with local time (not affected by daylight saving time).

batchNumber
This element is used only in daily reports. It is a unique batch number associated with each report. The batch number is generated within a specific deployment and/or community.
transactionMonth
This element is used only in monthly reports. It is the transaction month of the set of transactions listed in the report. The month is presented in the following format: yyyy-mm

The following are example report names with explanation of their structure:

Card_Activity_daily_2017-06-25-05-31-21_0000001

report_Name =Card_Activity
frequency =Daily
reportGenerationDate =2017-06-25-04-31-21
June 24, 2017 at 04:31:21 hrs
batchNumber =0000001
The first report file generated for this deployment or community

Funding_Account_Activity_monthly_2017-06-03-05-34-55_2017-05

reportName =Funding_Account_Activity
frequency =Monthly
ReportGenerationDate =2017-06-03-05-34-55
June 4, 2017 at 05:34:55 hrs
transactionMonth =2015-05
Contains data for transactions from 1 to 31 May 2017

Report creation process

Nium reports are created daily and stored in the file repository.

The Nium report generation engine performs the following process every day:

  1. Collects data from suppliers for the previous day.
  2. Stores collected data in a data repository.
  3. Validates stored data to check if it is correct and complete.
  4. Inserts transactions or files that failed validation into an audit table.
  5. Generates reports only for correct and complete data.
  6. Stores generated reports in files in the file repository.

๐Ÿ“˜

NOTE

If there is no activity on the reporting account for more than two months, the engine stops generating reports.

If there are any transactions or files that failed validation, the business intelligence team performs the following manual process:

  • Analyses the audit table.
  • Eliminates issues with data in the audit table.
  • Manually generates a report.
  • Stores the report in a file in the file repository with the next batch number

๐Ÿ“˜

NOTE

Monthly reports do not need to be corrected because they are based on complete daily reports.

File repository

The file repository contains report files. Each deployment has a dedicated folder in the repository.

๐Ÿšง

IMPORTANT

To access the file repository, use the link that you received by email. If you have not received the link by email, contact your IT team for help.

This is the general structure of the file repository:

Deployment folder

You have access to your dedicated deployment folder. This folder contains subfolders for each type of report. Your deployment folder is structured like this:

A report can have different frequencies (daily or monthly). The available frequencies are represented as subfolders for that report. The Daily subfolder contains reports scheduled for daily generation, and likewise the Monthly subfolder contains reports generated monthly (transactions from the previous month). Your report folder is structured like this:

Reporting on suspended transactions

Sometimes, a transaction is reported as in a suspended state. In these cases, Nium does not have access to any information about the status of the operation upon request from an external provider (e.g. a card processor).
As an example, consider a request for ยฃ50 to be transferred from a funding account to a virtual card. This will include the following steps:

  1. Take ยฃ50 from funding account A
  2. Put ยฃ50 on virtual card B

For funds to be placed on the virtual card (step 2), a card processor must perform an operation that is external to Nium. In this example, an exception may occur if Nium has no access to the status of the request sent to the card processor (perhaps due to a communication problem). If so, Nium has no information about whether the funds have been loaded on the card or not. In this example, Nium will mark the transaction as suspended until a Nium officer investigates the outcome of the operation. If the operation is found to be successful, the fund movement is marked as completed. If the operation is found to be failed, withdrawal of funds from the funding account (step 1) is reversed.
A partial transaction report is created for such transactions (fund movement that has already occurred is reported). In the above example, the Funding Account Activity report would show the movement of funds from the funding account. The transaction status will be INITIALISED, which indicates that this transaction is suspended and not yet completed.
In case of failure, funds will be reversed and the transaction status will be INITIALISED_FAILED. In case of successful completion, the transaction will be continued and marked as INITIALISED_COMPLETED.
A transactionId is a unique reference for each transaction. It can be used to reconcile the entries in Funding Account Activity and Card Activity reports for a particular transaction. For every INITIALISED transaction there must be a corresponding entry with the same transactionId and with an INITIALISED_FAILED or an INITIALISED_COMPLETED status. If not, the underlying issue probably still applies or an error has occurred.

Please report any transactions (INITIALISED) that do not have a corresponding completion state (INITIALISED_FAILED or INITIALISED_COMPLETED) to the Nium support team on [email protected] .

Nium Reports

All activities you perform in Nium can be tracked using reports. In this section, we provide the full specification for the following reports:

  • Card activity: Daily
  • Card activity: Monthly
  • Funding account activity: Daily
  • Funding account activity: Monthly
  • Non-zero card balances
  • Balance sheet
  • Scheduled loads
  • Credit activity: Daily
  • Credit statement: Daily

Card activity daily report

This report contains a detailed list of all card activity on all cards, on a specific day.
The purpose of this report is to track all activity that impacts the actual balance on every card. It is generated daily and covers all transactions carried out on the previous day.

Latest version: 3.13.0
File repository path: Card Activity/Daily
File name pattern: Card_Activity_daily

REPORT CONTENT
startDate
The date when the transaction started.
transactionDate
The date when the balance movement was performed.
community
The name of the community to which a client belongs as set up in Nium.
client
The name of the client as set up in Nium.
country
Represents the country in which the client is based.
transactionId
Represents a unique transaction identifier.
adjustmentId
Represents a unique identifier for each balance movement.

๐Ÿ“˜

NOTE

A transaction can have multiple balance movements.

transactionType
Describes the type of activity carried out on the card. The following reported transaction types are available:
TRANSACTION TYPEDESCRIPTIONTRANSACTION INFO FIELD
TransferRepresents transfers to or from this card.If the transfer is initiated by the client, this field contains NULL.
If the transfer is initiated by Nium, this field contains comments entered by the Nium officer.
AuthorisationRepresents the receipt of an authorisation request for the card.Contains the authorisation reason.
Authorisation releaseRepresents the cancellation of a previous authorisation request by the merchant.Contains the authorisation reason.
PurchaseRepresents the receipt and processing of a settlement request for the card.NULL
Merchant refundRepresents the receipt of funds on a card from a merchant. Includes both merchant refunds as well as original credit transfers as processed through the Visa network.NULL
Manual creditRepresents a positive manual adjustment on a card.Contains comments entered by the Nium officer.
Manual debitRepresents a negative manual adjustment on a card.Contains comments entered by the Nium officer.
Card createdRepresents the creation of new cards (which could involve fund transfer).NULL
FreezeRepresents the change of card state to restricted.NULL
ThawRepresents the change of card state to active.NULL
Loss recoveryRepresents negative card balance recoveryNULL
Dispute openedRepresents the opening of a new dispute.NULL
Dispute reversedRepresents the reversal of an open dispute.NULL
Dispute wonRepresents a dispute which has been won.This field contains WON_PARTIAL in the case of a partial win, otherwise it will contain NULL.
Dispute lostRepresents a dispute which has been lost.NULL
Deduct feeRepresents any deducted fees.This field contains INVALID_DISPUTE_FEE in the case of invalid disputes.
transactionCurrency
The currency of the participant (card). For example, if the client requested 1000 GBP but the currency of the card is EUR, transactionCurrency is EUR.

๐Ÿ“˜

NOTE

In a cross-currency transfer, the transactionCurrency is that of the source instrument. For example, in case of a transfer from a EUR funding account to a USD card, transactionCurrency is EUR because that is the amount that would have been requested by the client

transactionAmount
The requested amount represented in transactionCurrency. This amount also includes Forex padding (for authorisations) and any fees set at processor level, if applicable. For example, if the client requested 1000 GBP, the transactionCurrency is EUR, the current GBP to EUR exchange rate is 1.1, and Forex padding is EUR 5, transactionAmount is 1105: EUR 1100 from currency exchange plus EUR 5 Forex padding.

๐Ÿ“˜

NOTE

This amount does not include fees in case of cross-currency transfers.

transactionAuthor
The author of the transaction (for example, username, API call).
sourceType
The source participant in the transaction.
sourceDetails
A friendly name of the source participant.
destinationType
The destination participant in the transaction
destinationDetails
A friendly name of the destination participant.
participantType
The type of transaction participant (can be a source or a destination participant).

๐Ÿ“˜

NOTE

For card reports, participantType is always Virtual Card.

PARTICIPANT TYPEDESCRIPTION
Funding AccountAn account maintained with Nium, used by the client to issue and load cards.
Virtual CardA virtual card issued through Nium.
Bank CardThe account holderโ€™s bank card, which is used to deposit funds to their Nium funding account.
Bank AccountManual accounts are tagged accounts used by Nium for manual adjustments. These include the following:

Manual accounts are tagged accounts used by Nium for manual adjustments. These include the following:
Manual Account

TRANSACTION TYPEDESCRIPTION
RevshareThis account is used to show revenue share credits/debits.
Forex_FeeThis account is used to adjust forex credits/debits.
Misc_ClearingThis account is used to adjust one-off occasional adjustments (supported by a note).
TestingThis account is used to adjust testing credits/debits.
Settlement_LossThis account is used to collect losses on client settlement processing.
Settlement _ChargeThis account is used to collect fees associated with settlement charges (not collected by the system).
Dispute_FeeThis account is used to collect dispute fees on client requests.
Dispute_WonThis account is used to credit funds won related to disputes processed.
Card_FeeThis account is used to collect/refund card fee charges manually.
Transfer_FeeThis account is used to collect/refund fees generated on a transfer manually.
Bank_ChargeThis account is used to collect/refund fees associated with a bank transfer.
Tracing_ChargeThis account is used to collect/refund fees associated with a bank transfer trace.
Professional_FeeThis account is used to collect fees associated to a bespoke task that had previously communicated a charge.
Setup_FeeThis account is used to collect/refund setup fees.
participantDetails
Contains a friendly name of the participant. For example, bank account information (if the participant type is Bank Account), funding account name (if the participant type is Funding Account), and so on.
participantSink
Possible values: SOURCE or DESTINATION.
originalCurrency
The original currency as requested by the client. This is independent of the participant currency. For example, if the client requested 1000 GBP and participantCurrency is EUR, originalCurrency is GBP.
originalAmount
The amount requested by the client. This is independent of the participant currency. For example, if the client requested 1000 GBP and participantCurrency is EUR, originalAmount is 1000.
participantCurrency
The currency of the participant (card). For example, if the client requested 1000 GBP and the currency of the card is EUR, participantCurrency is EUR.
participantAmount
The requested amount represented in the currency of the participant (see: participantCurrency). For example, if the client requested 1000 GBP, participantCurrency is EUR, and the current GBP to EUR exchange rate is 1.1, participantAmount is 1100.

๐Ÿ“˜

NOTE

At authorisation level there is no money movement, so if transactionType is Authorisation, then participantAmount is 0. The total amount blocked by the authorisation is represented in originalAmount and transactionAmount in respective currencies.

exchangeRate
The exchange rate used between source currency and destination currency (if they are different).
nonForexFee
Contains non-Forex fees for the reported transaction, where applicable.
forexFee
Contains Forex fees for the reported transaction, where applicable
balanceBefore
The balance on the card before the transaction was processed.
balanceAdjustment
The adjustment amount on the card. This is the sum of the card transaction amount and the non-Forex fee and the Forex fee
balanceAfter
The balance on the card after the transaction was processed. This excludes the fee amount.
status
Used to keep track of transactions.
STATUS TYPEDESCRIPTION
CompletedTransaction has completed successfully.
FailedTransaction has failed and no fund moments have happened.
InitialisedTransaction is in a suspended state and funds have only been partially moved.
Initialised completedTransaction was previously in a suspended state but has been resumed to completion successfully and funds have also been fully moved.
Initialised failedTransaction that was previously in a suspended state has been resumed to a failed state. Fund movements that happened initially have been reversed and a new balance movement entry has been created.
forexFlag
Contains a Boolean flag indicating whether a transaction is Forex or now (possible values: Y/N).
direction
Contains a Boolean flag indicating whether a transaction is an advance or a reversal (possible values: A/R).
merchantName
The name of the merchant.
merchantCountry
The base country for the merchant as registered with the acquirer.
merchantCategoryCode
An identifier for the merchant category that a merchant belongs to.
acquirerReferenceNumber
A unique reference number that identifies the acquirer for each merchant.
authCode
The authorisation code used in authorisations and settlements. It can be used to match a settlement to its corresponding authorisation.
providerDate
The date on which the transaction is processed at the card processor level. Usually, reported only for the authorisations and settlements.
externalRef
A unique Nium reference of the card. For example, CMCLHJCDHECDCCB.
externalID
The external ID of the card as supplied by the client and stored in the Nium system.
cardNum
The first six and last four digits of a virtual card. For example, 406742**\*\***8806. This should not be used to match or map card numbers, as multiple cards share the same set of first six and last four digits. Card reference should be used to match or map card numbers.
cardScheme
The card scheme of the issued card. For example, Visa or Mastercard.
cardFactoryName
Indicates the card factory (card type) that a card is linked to.
customField1 to customField20
The client may choose to pass specific information relating to the transaction by attaching additional information in the custom fields. Custom information allows the client to reconcile card activity (payments and refunds). Custom field data is retrieved from the โ€œcardInfoโ€ parameter when creating a card using the IssueVirtualCard() API, or from the โ€œadditional detailsโ€ form when creating a card in the Nium Portal. This information is passed as name:value pairs. For example, custom fields may contain the following information:
Client Customer Identifier : John123
Client Customer Booking Identifier : Paris321
Client Travel Package Type Descriptor : LOWCOST
Client Travel Package Identifier : LC21
Client Company Subsidiary Descriptor : Spain

๐Ÿ“˜

NOTE

In the Nium portal, custom fields are referred to as additional details.

transactionInfo
Additional information specific to each transaction type.
fundingAccountName
The name of the funding account from which the card was funded for the first time.
authTransactionDate
The date of the respective authorisation for a purchase.
schemeCode
The card product using the scheme provided code.
binOwner
The entity associated to the respective card product.
ecbRate
The latest European Central Bank (ECB) rate applicable for the day identified by field Central Processing Date.

Funding account activity daily report

This report contains a detailed list of all funding account activity on all funding accounts, on a specific day. The purpose of this report is to reconcile all funding account activity. It is generated daily and covers all transactions carried out on the previous day.

Latest version : 3.13.0
File repository path : Funding Account Activity/Daily
File name pattern : Funding_Account_Activity_daily

REPORT CONTENT
startDate
The date when the transaction started.
transactionDate
The date when the balance movement was performed.
community
The name of the community to which a client belongs as set up in Nium.
client
The name of the client, as set up in Nium.
country
The country the client is based in.
transactionId
A unique transaction identifier.
adjustmentId
A unique identifier for each balance movement.

๐Ÿ“˜

NOTE

A transaction can have multiple balance movements

transactionType
The type of activity carried out on a funding account. The following reported transaction types are available:
TRANSACTION TYPEDESCRIPTIONTRANSACTION INFO FIELD
TransferRepresents transfers to or from this funding account.If the transfer is initiated by the client, this field contains NULL.
If the transfer is initiated by Nium, this field contains comments entered by the Nium officer.
Fee reversalRepresents a reversal of a previous fee.Contains the original transactionID of the transaction for which the fee is being reversed.
Bank depositRepresents a deposit via a bank transfer.Contains the name of the provider used to make the bank deposit.
Bank deposit reversalRepresents the reversal of a deposit to the funding account via a bank transfer. Possible reasons could be: bank reverses the transaction, client does not supply Nium with bank documents, and so on.Contains the original transactionID of the transaction for which the bank deposit is being reversed.
Card returnRepresents the withdrawal of funds to a bank card.NULL
Bank returnRepresents the withdrawal of funds to a bank account.NULL
Bank return reversalRepresents the reversal of a fund transfer from the funding account to a bank account.
Possible reasons could be: incorrect bank details, cancelled by bank, cancelled by Nium due to unapproved bank details, and more.
Contains the original transactionID of the transaction for which the bank return is being reversed.
Revenue shareRepresents a revenue share deposit.Contains comments entered by the Nium officer
Manual creditRepresents a positive manual adjustment on a card.Contains comments entered by the Nium officer.
Manual debitRepresents a negative manual adjustment on a card.Contains comments entered by the Nium officer.
Card createdRepresents the creation of new cards (which could involve fund transfer).NULL
Card deletedRepresents the deletion of cards (which could involve fund transfer).NULL
Card deposit reversalRepresents the reversal of a deposit via a bank (credit/debit) card.Contains the original transactionID of the transaction for which the card deposit is being reversed.
Funding account createdRepresents the creation of a new funding account.NULL
Funding account deletedRepresents the deletion of a funding account.NULL
Loss recoveryRepresents negative card balance recovery.NULL
transactionCurrency
The requested currency. For example, if the client requested 1000 GBP and the currency of the funding account is EUR, transactionCurrency is GBP.
transactionAmount
The requested amount represented in transactionCurrency. For example, if the client requested 1000 GBP, transactionAmount is 1000.
transactionAuthor
The author of the transaction (for example, username, API call).
sourceType
The source participant in the transaction.
sourceDetails
A friendly name of the source participant.
destinationType
The destination participant in the transaction.
destinationDetails
A friendly name of the destination participant.
participantType
The type of transaction participant (it can be a source or a destination participant).

๐Ÿ“˜

NOTE

For funding account reports, participantType is always Funding Account.

PARTICIPANT TYPEDESCRIPTION
Funding AccountAn account maintained with Nium, used by a lien to issue and load virtual cards.
Virtual CardA virtual card issued through Nium.
Bank CardThe account holderโ€™s bank card used to deposit funds to the funding account.
Bank AccountA bank account registered in Nium for bank transfers.

Manual accounts are tagged accounts used by Nium for manual adjustments. These include the following:

Manual Account

TYPEDESCRIPTION
RevshareThis account is used to show revenue share credits/debits.
Forex_feeThis account is used to adjust forex credits/debits.
Misc_ClearingMisc_Clearing This account is used to adjust one-off occasional adjustments (supported by a note).
TestingThis account is used to adjust testing credits/debits.
Settlement_LossThis account is used to collect losses on client settlement processing.
Settlement_ChargeThis account is used to collect fees associated with settlement charges (not collected by the system).
Dispute_FeeThis account is used to collect dispute fees on client requests.
Dispute_WonThis account is used to credit funds won related to disputes processed.
Card_FeeThis account is used to collect/refund card fee charges manually.
Transfer_FeeThis account is used to collect/refund fees generated on a transfer manually
Bank_ChargeThis account is used to collect/refund fees associated with a bank transfer.
Tracing_ChargeThis account is used to collect/refund fees associated with a bank transfer trace.
Professional_FeeThis account is used to collect fees associated to a bespoke task that had previously communicated a charge.
Setup_FeeThis account is used to collect/refund setup fees.
participantDetails
A friendly name of the participant. For example, bank account information (if the participant type is Bank Account), funding account name (if the participant is Funding Account), and so on.
participantSink
Possible values: SOURCE or DESTINATION.
originalCurrency
The original currency as requested by the client. This is independent of the participant currency. For example, if the client requeted 1000 GBP and participantCurrency is EUR, the originalCurrency is 1000.
originalAmount
The amount requested by the client. This is independent of the participant currency. For example, if the client requested 1000 GBP and participantCurrency is EUR, originalAmount is 1000.
participantCurrency
The currency of the participant (funding account). For example, if the client requested 1000 GBP and the currency or the funding account is EUR, participantCurrency is EUR.
participantAmount
The requested amount represented in the currency of the participant (see participantCurrency). For example, if the client requested 1000 GBP, participantCurrency is EUR and the current GBP to EUR exchange rate is 1.1, participantAmount is 1100.
exchangeRate
The exchange rate used between source currency and destination currency (if they are different).
nonForexFee
Non-Fore fees for the reported transaction, where applicable.
forexFee
Forex fees for the reported transaction, where applicable.
balanceBefore
The balance on the funding account before the transaction was processed.
balanceAdjustment
The adjustment amount on the funding account.
balanceAfter
The balance on the funding account after the transaction was processed.
status
Used to keep track of transactions.
STATUSDESCRIPTION
CompletedTransaction has completed successfully
FailedTransaction has failed and no fund movements have happened.
InitialisedTransaction is in a suspended state and funds have only been partially moved.
Initialised completedTransaction was previously in a suspended state but has been resumed to completion successfully and funds have also been fully moved.
Initialised failedTransaction that was previously in a suspended state has been resumed to a failed state. Therefore, fund movements that happened initially have been reversed and a new balance movement entry has been created.
forexFlag
Contains a Boolean flag indicating whether a transaction is Forex or not (possible values: Y/N).
direction
Contains a Boolean flag indicating whether a transaction is an advance or a reversal (possible values: A/R).
externalRef
A unique Nium reference of the funding account.
transactionInfo
Additional information specific to each transaction type.

Card activity monthly report