Card Transactions

Run in Postman

A card transaction is a record of a debit or credit event that affects a wallet balance. This guide explains the transaction types recorded by Nium, provides examples for wallet and Delegated Model clients, and describes the authorization and settlement stages.

Transaction types

The following transaction types describe events that may be recorded during card processing. Availability and handling can vary by authorization model and program configuration.

Transaction type	Description
Auto_Sweep	Automatically moves funds between currencies within a wallet to support authorization when multicurrency auto-sweep is configured.
Balance_Inquiry	Records a balance inquiry that returns a cumulative balance for single- or multicurrency wallets in the base currency.
Chargeback_Credit	Records a credit associated with a chargeback.
Debit	Records a card debit transaction, such as a point-of-sale (POS), ATM, or e-commerce transaction.
Decline_Advice	Records a declined transaction reported by Visa or Mastercard, for example following a card verification failure or suspected fraud.
Incremental_Auth_Reversal	Records an online reversal of an incremental authorization.
Original_Credit	Records an incoming Original Credit Transfer (OCT) credited to the wallet linked to the cardholder's card.
Original_Credit_Reversal	Records an online reversal of an original credit transaction.
Partial_Reversal	Records an online reversal of part of an earlier card transaction amount.
Reversal	Records the reversal of a previously authorized transaction. See Reversal scenarios.
Reversal_Advice	Records a reversal advice, for example following a network timeout. For wallet clients, Nium applies the reversal advice and credits the customer's wallet. For Delegated Model clients, Nium reverses funds in the client's prefunding account and forwards the advice so the client can update its customer ledger.
Settlement_Credit	Credits the cardholder's wallet when the clearing or settlement amount is lower than the amount previously authorized.
Settlement_Debit	Debits the cardholder's wallet when the clearing or settlement amount is higher than the amount previously authorized.
Settlement_Direct_Debit	Records a debit based directly on a settlement file, such as a force-posted transaction.
Settlement_Direct_Reversal	Records a credit reversing a transaction debited directly from a settlement file.
Settlement_Reversal	Records a credit associated with the reversal of a previously debited transaction.

Transaction type values

The values shown above retain the naming convention used in this guide. Confirm the exact enum values, including capitalization and underscores, against the API specification before using them in application logic.

Reversal scenarios

A Reversal may arise in the following situations:

Scenario	Description
Online reversal	A merchant initiates a reversal of a previously approved authorization.
Manual reversal	If an online reversal does not occur because of a technical issue, the customer may raise the issue and Nium Card Operations may initiate a manual reversal through Nium One. Following a successful reversal, the transaction is marked as reversed.
Transaction aging	If a merchant does not submit clearing or settlement within the configured aging period, the authorization may be reversed automatically according to Nium One's transaction-aging rules. The existing guide specifies seven days; confirm the applicable period for your program.

Transaction examples

Wallet client

#	Scenario	Transaction record created by Nium
1	A cardholder makes a purchase at a merchant. The merchant's acquiring bank submits an authorization request in real time.	Nium creates a Debit record with the merchant, transaction amount, currency, and other relevant details.
2	A merchant submits a transaction directly through clearing, such as a force-posted transaction.	Nium creates a Settlement_Direct_Debit record with the merchant and transaction amount.
3	A cardholder returns a purchased item and the merchant processes a full refund associated with the original purchase.	Nium creates a new Settlement_Reversal record or credit entry. The original debit record remains unchanged.

Delegated Model client

#	Scenario	Transaction record created by Nium
1	A cardholder makes a purchase and the merchant's acquiring bank submits a real-time authorization request.	Nium forwards the authorization request to the client. If the client approves, Nium creates a Debit record with the merchant, transaction amount, currency, and other relevant details.
2	A merchant submits a transaction directly through clearing, such as a force-posted transaction.	Nium creates a Settlement_Direct_Debit record with the merchant and transaction amount.
3	A cardholder returns a purchased item and the merchant processes a full refund associated with the original purchase.	Nium creates a new Settlement_Reversal record or credit entry. The original debit record remains unchanged.

For more information about client-side authorization decisions, see the Delegated Model guide.

Card transaction lifecycle

A card transaction generally involves two processing stages:

1. Transaction authorization: The issuer evaluates a transaction request and approves or declines it according to the applicable checks and authorization model.
2. Transaction settlement: Nium processes scheme clearing and settlement information and applies any required financial adjustments.

note

An approved authorization does not necessarily mean the final settlement amount will be identical. Settlement processing may result in additional debits or credits, as described in the transaction types above.

Transaction authorization

When a cardholder makes a payment, an authorization request is routed through the payment network to Nium's card-processing systems.

Wallet client

Nium evaluates the applicable limits and restrictions at the client, customer, and card levels, as well as the available balance. If the required checks pass, the transaction is approved; otherwise, it is declined.

Delegated Model client

Nium performs the applicable card and program checks before forwarding the authorization request to the client for a decision. The client must respond within the configured authorization timeout. The existing guide states a default hard limit of two seconds; this should be confirmed against the current integration requirements. If the client does not respond within the applicable timeout, the authorization is declined.

Transaction settlement

Nium receives clearing and settlement information from the card schemes according to the applicable scheme processing cycle. Nium processes these files and applies any necessary adjustments based on the amounts presented for settlement.

Wallet client

Nium handles settlement with the scheme. Differences between authorized and settled amounts are reflected as credits or debits to the customer's wallet, as applicable.

Delegated Model client

Nium settles with the scheme and shares settlement information with the client. Because the client manages the customer ledger, the client is responsible for reflecting the relevant transactions and adjustments in that ledger. Nium applies any corresponding adjustments to the client's funding or prefunding arrangement as applicable.

Related guides

• Dynamic Authorization — Compare the available authorization models.
• Delegated Model — Understand client-side authorization decisions and ledger responsibilities.
• Manage Cards — Configure card-level limits and restrictions.