Reporting Guides Appendices
Appendix A: Definitions
The authorization and settlement process
When a card is used for a purchase at a merchant, the purchase is processed as described here.
- At the point of purchase, the merchant submits an authorization request to their payment gateway and the acquiring bank.
- Nium receives the authorization request. If card details match and there is sufficient balance on the card, the balance is reduced, and the authorization request is authorized.
- The card processor submits a file to Nium containing a list of all authorization requests.
- Nium subsequently receives a settlement record that specifies the amount that Nium has to settle with its issuing bank for that transaction. There could be minor differences between the purchase amount submitted in the authorization request and the settlement request if the transaction is being carried out in a currency different than the card currency (the card scheme would have applied different Forex fees).
- It can take up to three days for a settlement record to be received by Nium after a purchase has been completed.
Single-use and Multispend cards
During the initial account configuration, Nium and the client defined the card type to be issued to the client. Nium supports two types of virtual cards:
- Single-use cards: these are cards to be loaded and used for a single transaction. Upon receiving the first authorization request from the card scheme, any remaining funds on the card become unavailable (the term used for this is frozen, preventing further authorization requests from being processed). The card is deleted upon receipt of the settlement record, and frozen funds are returned to the funding account.
- Multispend cards: These can be loaded and reloaded for multiple purchases. When a card reaches its expiry date, any outstanding balance on the card is returned automatically to the funding account.
Refunds
If the merchant cancels a transaction, Nium receives a refund record with the settlement records.
Typically a single-use card would have been deleted when a refund is received. In this case, funds for the refund are returned immediately and directly to the funding account.
Refunds on a multispend card are added to the existing card balance if the card is active or directly to the funding account in case multispend card is deleted.
Expired authorizations
Authorization requests can be automatically expired.
Sometimes, a merchant submits an initial authorization request (affecting the available balance on a card) but does not follow up with a settlement request. After a pre-set period, Nium automatically expires the authorization request.
- If the card is a single-use card, all funds (equal to the amount loaded on the card) are returned to the funding account.
- The authorized but unsettled funds are added to the card balance if the card is reloadable.
Manual adjustments
If issues occur, manual adjustments are possible. Theoretically, manual interventions would not be needed if there were no technical or manual issues in the system. All transaction entries recorded in the system would correspond to real-life transactions. In practice, however, there are situations when transactions are not processed correctly due to system issues or manual errors.
For instance, a purchase request could erroneously be processed twice because there are two transaction records when there should have only been one. In such a scenario, a manual adjustment is made to compensate for the action because executed and completed transactions cannot be reversed or cancelled. An administrator can only perform a compensating action to cancel the effect of the transaction.x
When a discrepancy is identified, the adjustment can be credited or debited in the same or subsequent months.
Authorisation reasons
The following authorization reasons are available.
NORMAL_TAKE | Represents an approved, successful debit authorization. |
NORMAL_TAKE_PRE_AUTH | Represents an approved, successful debit pre-authorization. |
NORMAL_PUT | Represents a reversal of an approved, successful debit authorization. See NORMAL_TAKE. |
REVERSE_PUT | Represents a merchant's approved, successful credit authorization (an authorization for a merchant refund). |
REVERSE_TAKE | Represents a reversal of an approved, successful credit authorization by a merchant. See REVERSE_PUT. |
EXPIRY_TAKE | Represents an approved, successful authorization release when a settlement is not received within the stipulated days. This could also be a partial authorization release because the authorization was more significant than the settled amount. |
EXPIRY_PUT | Represents a reversal of an approved, successful authorization release. See EXPIRY_TAKE. |
DECLINED_TAKE: provider reason | Represents a declined debit authorization. |
CLOSE_TAKE | Represents manual closure of an approved, successful debit authorization. |
CLOSE_PUT | Represents a reversal of a manually closed authorization. See CLOSE_TAKE. |
Appendix B: Cases
You can receive the following sample reports:
Card_Activity_daily_2014-06-25-04-31-21_0000001
Funding_Account_Activity_daily_2014-06-03-05-34-55_0000001
These reports depict how the following cases are presented
- Single cases
- Other scenarios cases
To receive sample reports, contact the Nium support team ([email protected]).
Note:
- Although named 2014-06-25, sample reports contain data with numerous dates from captured live data scenarios. These have been grouped in a sample file containing a majority of cases.
- Sample reports include two additional columns highlighting the cases. Real reports do not include these columns.
- Columns externalID and customField1 to customField20 have been left empty because these are usually populated by the client when creating a card in Nium.
Single cases
This section contains a list of single cases.
CASE | TRANSACTION TYPE | CASE DESCRIPTION |
---|---|---|
0100 | TRANSFER | Successful normal transfer. |
0101 | TRANSFER | Successful Forex transfer. |
0102 | TRANSFER | Successful transfer initiated by Nium (more information in the note entered by Nium operators). |
0103 | TRANSFER | Transfer of funds stuck in a suspended state. It was then resumed to successful completion. |
0200 | FEE REVERSAL | Fee reversal by the Nium finance team (refunding a transaction fee previously taken). Note: The Transaction info field column contains the original transactionId that this fee relates to (original transactionId is when the original fee was taken). |
0300 | BANK DEPOSIT | Successful bank deposit transfer. |
0400 | BANK DEPOSIT REVERSAL | The reversal of a successful bank deposit transfer was reversed as the bank service provider initially reversed it. |
0500 | CARD DEPOSIT | Successful card deposit transfer via a credit/debit card. |
0501 | CARD DEPOSIT | Failed attempt card deposit transfer via a credit/debit card. Note: No balance movements have happened on the participant balance. |
0600 | CARD RETURN | Successful card return of funds to a credit/debit card. |
0601 | CARD RETURN | Failed card return of funds to a credit/debit card. |
0700 | BANK RETURN | Successful bank transfer return to a bank account. |
0701 | BANK RETURN | The Bank return failed; however, an adjustment initially happened and reversed it immediately. |
0702 | BANK RETURN | Successful bank transfer returned to a bank account requested by the client and initiated manually by Nium officers. |
0800 | BANK RETURN REVERSAL | Bank transfer out reversed by the bank. Funds are returned to the funding account. |
0900 | REVENUE SHARE | Successful revenue share credit/debit. |
1000 | MANUAL CREDIT | Successful manual credit. |
1100 | MANUAL DEBIT | Successful manual debit. |
1200 | CARD CREATED | Successful card creation with funds transfer. |
1201 | CARD CREATED | Card creation with funds transfer stuck in a suspended state. It was then resumed to successful completion. |
1202 | CARD CREATED | Card creation with funds transfer stuck in a suspended state. It was then resumed to reversal/failed completion. Note: Since the card was not created, the card's first six and last four digits are not present. |
1203 | CARD CREATED | Card creation with funds transfer stuck in a suspended state. The transaction has not been resumed. These cases need to be monitored and reported |
1204 | CARD CREATED | Successful card creation with Forex funds transfer. |
1205 | CARD CREATED | Successful card creation with no funds transfer. |
1300 | CARD DELETED | The card was deleted successfully with a funds transfer. |
1301 | CARD DELETED | Card deletion failed; however, an adjustment happened and was reversed immediately. Note that the Non-Forex fee column shows the reversal of the fee. |
1302 | CARD DELETED | The card was deleted successfully with no funds transfer. |
1400 | AUTHORIZATION | Normal successful authorization. |
1401 | AUTHORIZATION | Regular successful Forex authorization. |
1500 | AUTHORIZATION RELEASE | The merchant cancelled the successful authorization, and an authorization release was received. In this case, the virtual card is thawed and is available for use (unless another spend transaction is settled on the card). The authorization release can be matched against the original authorization using the authorization code. |
1600 | PURCHASE | Normal successful purchase. |
1601 | PURCHASE | Standard successful Forex purchase. |
1602 | PURCHASE | Standard successful purchase with a fee. |
1700 | MERCHANT REFUND | A successful merchant refund transaction. Nothing comparable between the settlement (purchase) and refund apart from the merchant name. |
1701 | MERCHANT REFUND | A successful merchant Forex refund transaction. |
1800 | CARD DEPOSIT REVERSAL | A successful card deposit transfer via a credit/debit card gets reversed. Note that in the transaction info, the related original transactionId is available. |
1900 | FREEZE | The card state was successfully changed to Restricted. This happens when the first authorisation is processed on a single-spend card. |
2000 | THAW | The card state was successfully changed to active. This typically happens when an authorization has been released, and no settlements/purchases are on the card. |
2100 | LOSS RECOVERY | A successful loss recovery transaction is to recover any virtual card's negative balance. |
2200 | DISPUTE OPENED | A dispute was opened. This is the first step in a dispute process. No fund movements take place with this type of transaction |
2300 | DISPUTE REVERSED | A dispute was reversed. No fund movements take place with this type of transaction. |
2400 | DISPUTE WON | A dispute was won, and funds, less a fee, were transferred to the card. |
2401 | DISPUTE WON | A dispute was partially won, and funds, less a fee, were transferred to the card. The transactionInfo column contains WON_PARTIAL. |
2500 | DISPUTE LOST | A dispute was lost, and a fee was deducted. |
2600 | DEDUCT FEE | The dispute was invalid. A fee was deducted, and transactionInfo column contains INVALID_DISPUTE_FEE. |
Other scenario cases
This section contains a list of other scenario cases:
CASE | TRANSACTION TYPE | CASE DESCRIPTION |
---|---|---|
5000 | MANUAL DEBIT / MANUAL CREDIT | Manual adjustments for testing card transactions. |
5100 | TRANSFER / MANUAL DEBIT / MANUAL CREDIT | Manual adjustments for reversing a Forex transfer as it was executed in error. |
5200 | CARD CREATED / AUTHORIZATION / PURCHASE / CARD DELETED | Multiple purchases for a single authorization. The authorization code is the point of reference to match the purchases against the authorization. An initial card creation with a funds transfer is also shown. |
5300 | CARD CREATED / AUTHORIZATION / PURCHASE / MERCHANT REFUND / CARD DELETED | One purchase and one authorization, and a split merchant refund. The refunds cannot be matched against the original purchase; however, the system must be able to accept multiple refunds. |
5400 | CARD CREATED / TRANSFER / AUTHORIZATION / CARD DELETED / TRANSFER / PURCHASE | Insufficient funds to cover a Forex purchase. This card required an adjustment from the funding account to cover the Forex discrepancy. Also note Forex authorization and original currency, and Forex settlement details and original currency. |
5500 | CARD CREATED / AUTHORIZATION / PURCHASE / CARD DELETED | Multiple authorizations and purchases (all with different authorization codes) on a single-fund/single-spend virtual card. This is rare but may happen if the merchant splits the authorization into several more minor authorizations, and they were all processed instantly so that a freeze did not occur on time. However, the authorization limit works accordingly, and authorizations of this sort are only approved if sufficient funds are available for all authorizations |
5600 | AUTHORIZATION / FREEZE | On single-spend cards, the card state is changed to restricted when authorization is processed. |
5700 | AUTHORIZATION RELEASE / THAW | On single-use cards, when an authorization is released (or expired), and no settlements have been processed on the card, the card state is changed to active, and another authorization can be processed. |
5800 | CARD CREATED / AUTHORIZATION / PURCHASE / LOSS RECOVERY | A card that ended up with a negative balance after the purchase. Loss recovery is a transaction that is used to recover any negative balance that may be present on a virtual card. |
5900 | DISPUTE OPENED / DISPUTE REVERSED | A dispute was opened, then reversed. |
6000 | DISPUTE OPENED / DISPUTE WON | A dispute was opened and won. |
6100 | DISPUTE OPENED / DISPUTE WON | A dispute was opened and partially won. |
6200 | DISPUTE OPENED / DISPUTE LOST | A dispute was opened, but the dispute was lost. |
Updated about 1 year ago