Transaction settlements
Learn how funds from an authorized card transaction are settled and reflected in a user's account. This guide explains the settlement process and how to interpret the corresponding status updates you receive.
Clearing
The MatchMove platform receives clearing files from various networks at stipulated timeframes. These files are validated and parsed individually for each respective network.
Please note that even though a cardholder might be associated with a single scheme, the transactions for the same card could be processed by different networks. This depends on transaction attributes like domestic vs cross-border transactions. Thus, customer transactions may be included in different network clearing files.
Reconciliation
After receiving the clearing files from the network, the MatchMove platform compares the clearing message against the authorized transactions in the system.
Possible Outcomes of the Reconciliation Process
- The clearing record matches an authorized transaction.
- The clearing record differs in amount from the authorized transaction amount.
- A clearing record is received, which is a credit issued by the merchant to the cardholder.
- A clearing record is received, which requires a debit to be issued to the cardholder.
- A clearing record requires a reversal of the original transaction to the cardholder.
- No clearing record is received for an authorized transaction by the network beyond the stipulated maximum timeframe imposed by the scheme for the merchant to raise a settlement for a transaction.
Some processes may be flagged into an exception queue requiring intervention by the MatchMove operations team. After evaluation, these records are processed again as a separate batch, each falling under one of the above scenarios.
Posting
Once the clearing records have been reconciled with authorized transactions, the MatchMove system automatically adjusts the cardholder account/wallet balances and program balances (when required) to accommodate the update of transaction values/records.
Depending on which bucket a clearing record is placed, as part of the reconciliation process, the MatchMove platform performs actions listed in the table below:
Settle | The original authorization record is marked as settled | The transaction record is reflected as settled |
No Auth | A new debit transaction record is created | - New transaction record created - If applicable, new fee record(s) will be created - Balance reduced by the amount of the transaction + fees (if applicable) |
Issue Voucher | A new transaction record is created | New credit transaction record created - If applicable, new fee record(s) with debit entry will be created - Balance will be increased by the amount of the transaction and fees (if applicable) |
Reverse | Original authorization record marked as reversed | - The original Transaction record is marked as reversed - Balance increased with the original transaction amount |
Adjust | Original authorization record marked as reversed and tagged as a mismatch reversal. New debit record created with type as Mismatch Debit, with the final amount | - The original transaction record was identified as a mismatch reversal and reversed - User Balance increased by the amount - New transaction record tagged as Mismatch Debit and balance reduced by the final amount to be charged (This may be higher or lower than the original amount) - User Balance decreases by the amount of mismatch debit transaction and associated fees |
Settlement Webhooks
MatchMove's platform facilitates seamless end-to-end operations for partners by triggering webhooks that notify them of the completion of a clearing batch after every batch execution. Partners can then take appropriate actions within their systems based on these webhook messages.
Below are the suggested actions recommended for partners depending on their program construct:
SETTLEMENT_BATCH_SUCCESS | The event is triggered when a batch of transactions is posted in the | No Action | No Action | Update the internal system to mark the transaction as completed |
AUTHRELEASE_BATCH_SUCCESS | Triggered when a batch of transactions is posted in the | - Inform user via SMS / Email / In-App notification | - Update internal system to mark transaction as reversed - Inform user via SMS / Email / In-App notification | - Update internal system to mark transaction as reversed and return associated funds/limits to the cardholder - Inform user via SMS / Email / In-App notification |
CREDITVOUCHER_BATCH_SUCCESS | Triggered when a batch of transactions is posted in the | - Inform user via SMS / Email / In-App notification | - Update the internal system to record new credit type transactions - Inform user via SMS / Email / In-App notification | - Update internal system to create a transaction of type credit and credit associated funds/limits to the cardholder - Inform user via SMS / Email / In-App notification |
NOAUTH_BATCH_SUCCESS | Triggered when a batch of transactions is posted in the | - Inform user via SMS / Email / In-App notification | - Update the internal system to record a new debit-type transaction - Inform user via SMS / Email / In-App notification | - Update internal system to create a transaction of type debit and debit associated funds/limits to the cardholder - Inform user via SMS / Email / In-App notification |
MISMATCH_BATCH_SUCCESS | Triggered when a batch of transactions is posted in the | - Inform user via SMS / Email / In-App notification | - Update the internal system to update the final value of the transaction by posting a debit/credit entry as per the final amount - Inform user via SMS / Email / In-App notification | - Update internal system to create a transaction of type debit/credit and debit/credit associated funds/limits to the cardholder - Inform user via SMS / Email / In-App notification |
Settlement Reports
To enable partners to programmatically process and ingest the outputs of the clearing and reconciliation process, each webhook triggered for a batch includes a linked file containing processed records.
The data embedded in these settlement reports follows the structure as illustrated in the table below:
process_batch_id | Unique reference for the batch Note: If the file contains a batch ID already processed, you can disregard the entire file | string | 150 |
user_hash_id | Unique ID for the user who initiated the transaction in the system | string | 100 |
wallet_hash_id | Unique ID for the wallet used to initiate the transaction in the system | string | 100 |
card_hash_id | Unique ID for the card used for the transaction in the system | string | 100 |
transaction_ref | Unique reference for the transaction in the MatchMove system | string | 100 |
retrieval_reference_number | An optional transaction identifier, if available from the network | string | 100 |
acquirer_ref_number | Option acquirer reference number, if available from the network | string | 100 |
transaction_type | Transaction type for the transaction | string | 100 |
authorization_transaction_amount | The transaction amount as charged during authorization | string | 100 |
authorization_transaction_currency | The currency in which the original transaction was authorized | string | 100 |
authorization_card_amount | The equivalent converted amount charged to the card as part of the authorization in the card's currency | string | 100 |
authorization_card_currency | Charge currency | string | 100 |
authorization_fee_amount | Total fee charged as part of the authorization stage, if applicable | string | 100 |
authorization_fee_currency | Charge currency | string | 100 |
authorization_total_transaction_amount | Total amount, including the fees charged to the cardholder as part of the authorization stage | string | 100 |
authorization_total_transaction_currency | Charge currency | string | 100 |
settled_transaction_amount | The transaction amount charged by the merchant as part of the settlement | string | 100 |
settled_transaction_currency | The currency in which the original transaction settlement was raised by the merchant | string | 100 |
settled_card_amount | The equivalent converted amount charged to the card as part of the settlement by the merchant in the card's currency | string | 100 |
settled_card_currency | Charge currency | string | 100 |
settled_fee_amount | Total fee charged as part of the settlement stage, if applicable | string | 100 |
settled_fee_currency | Charge currency | string | 100 |
settled_total_transaction_amount | Total amount, including the fees charged to the cardholder, is eventually as part of the settlement process | string | 100 |
settled_total_transaction_currency | Charge currency | string | 100 |
debit_credit_indicator | Debit / Credit Indicator for the original transaction | string | 100 |
merchant_name | Name of the merchant who initiated the transaction | string | 100 |
mcc | The merchant category code of the merchant who initiated the transaction | string | 100 |
mid | Merchant ID of the merchant who initiated the transaction | string | 100 |
tid | Terminal ID of the terminal on which the transaction was initiated | string | 100 |
transaction_status | Records successfully processed will be marked as success. Note: When successful transactions fail to be processed for any reason, they are retried and posted independently as part of a separate batch. Eventually, all records would be posted to the cardholder | string | 100 |
date_added | Timestamp of the original transaction authorization. Note: Since for actions no auth and issue voucher, there is no original transaction, this date would be the same as the date it was posted/updated to the cardholder as part of the settlement and reconciliation process | string | Format: yyyy-mm-dd H:i:s |
date_updated | Timestamp when the transaction was posted/updated to the cardholder as part of the settlement and reconciliation process | string | Format: yyyy-mm-dd H:i:s |
Settlement File Naming Convention
Every combination of reconciliation process, along with the outcome of reconciliation results, in a single file outpu,t which the partner can consume for fulfilling their downstream process.
The filename is a concatenation of the following values :
- Reconciliation_bucket (Possible values :
settle,reverse,no_auth,adjust,issue_voucher) - Product code
- File generation timestamp (Format :
YYYY-MM-DD HH:MM:SS) - Internal process batch ID (Format: Alphanumeric string 512 chars)
File Examples:
settle (Settlements) | settle_sgmmdemo_2024-06-10 06:00:41_XYASDSDASD324234432.csv settle_sgmmdemo_2024-06-10 00:39:08_AASD3SDASD324234432.csv |
reverse (Auth Release) | reverse_sgmmdemo_2024-06-10 00:20:29_AASD33243D324234432.csv reverse_sgmmdemo_posting_2024-06-10 00:20:29_AASD33243D324234432.csv |
no_auth (No Authorization) | no_auth_sgmmdemo_2024-06-10 00:19:52_ASDEREW42342342_432423.csv no_auth_sgmmdemo_posting_2024-06-10 00:19:52_ASDEREW42342342_432423.csv |
adjust (Mismatch Adjustment) | no_auth_sgmmdemo_2024-06-10 00:19:52_ASDEREW42342342_432423.csv no_auth_sgmmdemo_posting_2024-06-10 00:19:52_ASDEREW42342342_432423.csv |
issue_voucher (Credit Voucher) | issue_voucher_sgmmdemo_2024-06-10 00:21:38_PARFASD23432#MM-OPS_32434.csv issue_voucher_sgmmdemo_posting_2024-06-10 00:21:38__PARFASD23432#MM-OPS_32434.csv |
This naming convention ensures that each file is easily identifiable by its action type, program code, generation date, and associated batch ID. It is meant to facilitate the efficient location and utilization of the necessary reports by integrators.
Settlement Posting Report
When adjustments that require additional transactions are made as part of settlements, these are included in the Settlement Postings Report.
This report features only a subset of the fields found in the standard report. Its focus is on highlighting the additional transactions performed as necessary for the completion of the match-off process. It's important to note that retrieval and parsing of this report are optional and dependent on the program's specific needs.
process_batch_id | A batch identifier. Multiple transactions are included in a single batch to describe their contents at a glance. | String | 150 |
user_hash_id | The user’s MM identifier | String | 100 |
wallet_hash_id | The user’s wallet account identifier | String | 100 |
card_hash_id | The card’s unique identifier | String | 100 |
transaction_ref | The transaction’s unique identifier | String | 100 |
retrieval_reference_number | The unique transaction identifier created by the acquirer | String | 100 |
acquirer_ref_number | Unique transaction identifier of the fund exchange between the merchant and cardholder banks | String | 100 |
transaction_type | The subject transaction’s transaction type | String | 100 |
posted_transaction_currency | Currency of the total settled amount | String | 100 |
posted_total_transaction_amount | Total settled amount | String | 100 |
debit_credit_indicator | Indicates whether the transaction is a debit or a credit | String | 100 |
merchant_name | The merchant’s name can be found on billing statements | String | 100 |
transaction_status | The final result of the transaction’s settlement processing | String | 100 |
date_added | Date of authorization transaction | String | Format: yyyy-mm-dd H:i:s |
date_updated | Date of the settlement transaction | String | Format: yyyy-mm-dd H:i:s |
Related Links
On this page
- Transaction settlements