Reporting

Our reporting suite is designed for maximum transparency and ease of reconciliation. We provide detailed, granular data to give you complete visibility into every stage of the payment process.

Nopan provides four report types and flexible options for retrieving them depending on your operational needs:

• Secure file transfer (SFTP)
• Manual download through the merchant portal
• Programmatic access through REST APIs

---

Report Types

Nopan provides four report types, each serving a distinct reconciliation and auditing purpose:

Report Type

Purpose

Covers

Transaction Details

Full audit trail of all transactions with their last lifecycle status.

Per-transaction outcome, event type, and timestamps

Fee Details

Per-transaction and non-transaction fee breakdown.

Processing, settlement, chargeback, periodic, and one-time fees

Settlement

Financial impact of settled transactions grouped into payout batches.

Gross values, fees, net amounts, and bank reconciliation data

Bank Addenda

High-level aggregate view for matching physical fund transfers to your bank statement.

Payout-level totals, transaction counts, and bank references

---

Transaction Details

This report provides a full audit trail of all transactions, showing the last lifecycle status for each one. It outlines the final outcome of each payment:

• Successful payments appear as a single entry.
• Failed payments are represented by two entries - the last successful event that occurred and the final event indicating the failure.

For payments that failed, the successful event immediately preceding the failure is always included in the report.

Column

Purpose

Description

transaction_id

Allows to link the transaction event to incurred fees

Unique identifier for the transaction. Internally generated by Nopan

client_transaction_id

Identifies the transaction from the client side

Client format driven

processing_account_id

Identifies the specific processing account used for this transaction

Account that processed the payment. It can be defined as per the client, or internally generated

provider_id

Identifies the specific third-party payment provider that processed the transaction

Human readable identifier of the third-party payment provider

provider_transaction_id

Identifier assigned to the transaction by the payment provider

Payment provider format driven

amount

Gross value of the transaction

Expressed in non-decimal minor units

currency

Currency code in which the transaction was initiated and processed

Expressed as per ISO 4217 currency codes

status

Final determination of the payment's lifecycle stage outcome

Human readable, dependent on event_type. See Lifecycle concepts for possible values.

event_type

Specific lifecycle stage the payment reached

Human readable, dependent on payment method and integration path. See Lifecycle concepts for possible values.

event_time

Timestamp indicating when the recorded event_type occurred

Expressed as per ISO 8601 format in UTC timezone

info

For the full list of status and event_type values, see Lifecycle.

---

Fee Details

This report provides a detailed, per-transaction breakdown of every fee incurred. It itemizes all processing, settlement, and chargeback fees applied to a transaction, as well as non-transaction fees such as periodic or one-time charges.

• Transaction link: Ties each fee directly back to a transaction_id. For non-transaction-related fees, this value will not be present.
• Fee type and origin: Identifies the fee_type and the party to whom the fee was applied - either Nopan or our payment provider - along with the precise fee amount in the processing currency.

Column

Purpose

Description

transaction_id

Links the fee entry back to the original transaction

Present only for transaction-related fees, otherwise empty

fee_type

Identifies the category of the charge

Can be PROCESSING, SETTLEMENT, CHARGEBACK, PERIODIC, or ONE_TIME

applied_by

Determines which party levied the fee

Can be Nopan or a third-party provider

fee_amount

Value of the individual fee component

Expressed in non-decimal minor units

currency

Currency code in which the fee was applied

Expressed as per ISO 4217 currency codes

processing_account_id

Identifies the specific processing account

Account that processed the payment. It can be defined as per the client, or internally generated

payout_id

Links the fee to the payout batch

Ties the fee to the settlement group for bank reconciliation

---

Settlement

This report shows how transactions are grouped into payouts and provides the financial impact of settled transactions, refunds, and chargebacks within a specific payout batch.

• Payout grouping: The payout_id links all transactions settled in the same batch.
• Financial breakdown: Exposes the original gross_debit (or gross_credit for refunds), individual fees applied by Nopan and the provider, and the resulting net_debit or net_credit.
• Reconciliation link: The bank_reference and settlement_date ensure you can match net totals with the funds transferred to your bank.

info

Non-settled, failed, or incomplete transactions do not appear in the settlement report.

Column

Purpose

Description

processing_account_id

Identifies the specific processing account

Account that processed the payment

payout_id

Links the entry to the payout batch

Unique identifier for the settlement batch

transaction_id

Links the settlement entry back to the original transaction

Unique identifier for the transaction

provider_transaction_id

Identifier assigned by the payment provider

Payment provider format driven

client_transaction_id

Identifies the transaction from the client side

Client format driven

provider

Identifies the specific third-party payment provider

Human readable identifier of the third-party payment provider

settlement_date

Date the transaction was included in the payout batch

Expressed as per ISO 8601 format in UTC timezone

type

Type of event settled in this batch

Indicates if the entry is a PAYMENT_SETTLED, REFUND, or CHARGEBACK

processing_currency

Currency in which the transaction was initiated

Expressed as per ISO 4217 currency codes

gross_credit

Gross value of funds credited

Expressed in non-decimal minor units. Value based on processing_currency

gross_debit

Gross value of funds debited

Expressed in non-decimal minor units. Value based on processing_currency

exchange_rate

Rate applied to convert processing currency to settlement currency

Ratio between the processing_currency and the settlement_currency. Shown in major units, rounded to five decimal places at settlement time

settlement_currency

Currency in which the funds are settled

Expressed as per ISO 4217 currency codes

net_credit

Amount credited to client after deducting fees

Net amount credited after all Nopan and Provider fees are applied. Value based on settlement_currency

net_debit

Amount debited from client after deducting fees

Net amount debited after all Nopan and Provider fees are applied. Value based on settlement_currency

nopan_processing_fee

Processing fee applied by Nopan

Expressed in non-decimal minor units. Value based on settlement_currency

nopan_settl_fee

Settlement fee applied by Nopan

Expressed in non-decimal minor units. Value based on settlement_currency

nopan_chargeback_fee

Chargeback fee applied by Nopan

Expressed in non-decimal minor units. Value based on settlement_currency

provider_processing_fee

Processing fee applied by the third-party provider

Expressed in non-decimal minor units. Value based on settlement_currency

provider_settl_fee

Settlement fee applied by the third-party provider

Expressed in non-decimal minor units. Value based on settlement_currency

bank_reference

Ensures reconciliation of the bank transfer with the payout

Identifier for matching the payout batch to the bank statement

---

Bank Addenda

This report provides the high-level aggregate view necessary for matching the physical transfer of funds to your bank statement. It offers a concise, one-line summary for each bank transfer (payout batch).

• Payout summary: Shows the unique payout_id, the total transaction_count, the aggregate gross_total, the total fee_total deducted, and the final net_total transferred.
• Bank matching: The bank_reference is the identifier that will appear on your bank statement, ensuring immediate, reliable reconciliation of the incoming transfer.

Column

Purpose

Description

payout_id

Unique identifier for the settlement batch

Ties the entry to the payout batch

bank_reference

Ensures reconciliation of the bank transfer with the payout

Identifier for matching the payout batch to the bank statement

settlement_date

Date the funds were prepared for transfer

Expressed as per ISO 8601 format in UTC timezone

transaction_count

Total number of transactions included in the batch

A count of all transactions (payments, refunds, chargebacks) in the batch

gross_total

Aggregate gross value of all transactions in the batch

Sum of the gross values of all transactions in the payout. Expressed in processing_currency, using exchange_rate in settlement reports

fee_total

Aggregate value of all fees deducted from the batch

Sum of all Nopan and Provider fees applied to the transactions. Expressed in settlement_currency using exchange_rate in settlement reports

net_total

Final aggregate amount transferred to the bank

The final net amount of the funds transfer. Expressed in settlement_currency using exchange_rate in settlement reports

currency

Currency of the transfer

Expressed as per ISO 4217 currency codes

provider_id

Identifies the specific third-party payment provider

Human readable identifier of the third-party payment provider

processing_account_id

Identifies the specific processing account

Account that processed the payment

---

Retrieving Reports

We have three delivery channels available:

1. SFTP Delivery

Reports are automatically deposited on the Nopan SFTP server for your organization, in folders for each contractual entity, following a pattern as below:

outbound/{organization_id}/{entity_id}/{year}/{month}/{day}/

You can set up your access to Nopan SFTP server through portal for sandbox and production environments following these steps:

1. Generate your ssh key pair.

ssh-keygen -t ed25519

2. Upload your public key your-ssh-key-name.pub to the portal.

warning

Send only the public key file.

Never send your private key.

3. SFTP connection details will be displayed on portal, including your username.

• Access is scoped per directory - each client can only navigate their own organization folder.
• Authentication requires specific credentials (username and your private ssh key).
• SSH keys can be revoked from portal.

2. Merchant Portal

Log into the Nopan Merchant Portal for sandbox or production to view, filter, and download available reports. You can filter by name, type, date range, id, entity, and processing account directly from the UI.

This is useful for finance teams or ad-hoc reporting needs.

3. REST API

Reports can be retrieved programmatically through the Reports API, enabling full automation. Examples:

List reports:

GET /reports?from=2026-01-01T00:00:00Z&to=2026-12-31T23:59:59Z&processingAccountId=<some-account-id>
Authorization: Bearer <access-token>

Download a report:

GET /reports/download?reportId=<some-report-id>&organizationId=<some-organization-ie>
Authorization: Bearer <access-token>

tip

Check our API docs to see more details regarding available parameters.

info

Authentication is handled the same way as other Nopan APIs: with mTLS and access tokens.

Error Handling

When retrieving reports, you may encounter errors:

Scenario

HTTP Status / Error

Recommended Action

Report not found (wrong date, type, or ID)

404 Not Found

Verify that the report type and date combination exists.

Unauthorized API request

401 Unauthorized

Ensure a valid access token is provided.

SFTP connection refused

-

Check credentials and network access to our sftp server. You can check details on portal.

warning

Never process financial data or trigger business logic on unverified or corrupted reports.