Clearing and settlement payload

Card schemes perform settlement activities on a scheduled basis. Banking.Live processes the scheme's settlement files and sends settlement FAST messages to clients, allowing the final transfer of funds for associated transactions.

The settlement FAST message is a JSON array, which can contain multiple settlement JSON objects in a single message.

PaySchedular runs the job SendSettlementIso on a per client basis, which specifies the version, message type, and the number settlements (bulk size) to include in a single FAST request message. Banking.Live checks the HTTP response code from the client’s endpoint to verify that the FAST request message was received successfully.

Mada settlement messages

🗒️
Mada is a Single Messaging System (SMS), so no separate settlement messages are exchanged between Mada clients and Banking.Live. Instead, Mada sends a reconciliation file, also known as a TLF file. Banking.Live uses this to process the required reconciliation. There is nothing to clear, only to reconcile. All reconciled transaction data is then included in the Mada Presentment report, which is sent to clients on a daily basis.

Mastercard settlement messages

For Mastercard, we support three different versions for FAST settlement messages. The basic structure of these FAST payload versions is provided below.

🗒️
IMPORTANT
All new clients are required to integrate/consume FAST version 3.

FAST payload structure

FAST version 1

{
    "PacketType": "",
    "Header": {
        "source": "",
        "rid_set": "",
        "rid_auth": "",
        "tid": "",
        "cid": "",
        "file_date": "",
        "cycle_info": "",
        "de24": ""
    },
    "iso_msg": {}
}

Field Name	Description	Possible Values
`PacketType`	This field identifies the type of message	For Mastercard network , it will contain “1240” which indicates a presentment message.
`Header`	This field contains multiple other fields which provides the basic information for the message.	JSON Object
`source`	This field contains the network scheme.	“M” for Mastercard
`rid_set`	This field contains an unique id for the clearing message.	Text field with the unique id
`rid_auth`	This field contains the id of the authorization message which matches with the settlement record.	Text field with the id of authorization.
`tid`	This field contains the id of the transaction thread. This id will link all the transactions within a lifecycle i.e. auth, presentment , chargeback etc.	Text field with the id
`cid`	This field contains the client_id for which the message belongs	Text field with id.
`file_date`	The date of the file in which the message was received.	Text field with the date in the format YYMMDD.
`cycle_info`	Contains cycle information from Mastercard. The first two digit represents the clearing cycle, third position represents delivery cycle and the last two digit represents the sequence number.	Text field of length 5.
`de24`	Function code which indicates the specific purpose for the message.	Text Field of length 3.
`iso_msg`	The field contains a JSON object which further contains all of the data elements present in the clearing message.	JSON Object

FAST version 2

Version 2 is similar to Version 1, with the addition of a new field.

{
    "PacketType": "",
    "Header": {
        "source": "",
        "rid_set": "",
        "rid_auth": "",
        "tid": "",
        "cid": "",
        "file_date": "",
        "cycle_info": "",
        "de24": "",
        "total_bill_fee": ""
    },
    "iso_msg": {}
}

Field Name	Description	Possible Values
`PacketType`	This field identifies the type of message	For Mastercard network , it will contain “1240” which indicates a presentment message.
`Header`	This field contains multiple other fields which provides the basic information for the message.	JSON Object
`source`	This field contains the network scheme.	“M” for Mastercard
`rid_set`	This field contains an unique id for the clearing message.	Text field with the unique id
`rid_auth`	This field contains the id of the authorization message which matches with the settlement record.	Text field with the id of authorization.
`tid`	This field contains the id of the transaction thread. This id will link all the transactions within a lifecycle i.e. auth, presentment , chargeback etc.	Text field with the id
`cid`	This field contains the client_id for which the message belongs	Text field with id.
`file_date`	The date of the file in which the message was received.	Text field with the date in the format YYMMDD.
`cycle_info`	Contains cycle information from Mastercard. The first two digit represents the clearing cycle, third position represents delivery cycle and the last two digit represents the sequence number.	Text field of length 5.
`de24`	Function code which indicates the specific purpose for the message.	Text Field of length 3.
`total_bill_fee`	Contains the total fee charged on the transaction	Text value containing the fee amount
`iso_msg`	The field contains a JSON object which further contains all of the data elements present in the clearing message.	JSON Object

FAST version 3

{
    "MESSAGE_TYPE": {
        "Message_Type": "",
        "Message_Desc": ""
    },
    " SUMMARY ": {
        "TID": "",
        "RID": "",
        "ADD_REF_RID": "",
        "PID": "",
        "ClientID": "",
        "Network": "",
        "Transaction_Date_Time": "",
        "Spend_Type": "",
        "Spend_Location": "",
        "Transaction_Amount": "",
        "Transaction_Currency": "",
        "Billing_Amount": "",
        "Billing_Currency": "",
        "Total_Fee_Bill": "",
        "Card_Use_Type": "",
        "Customer_Validation": "",
        "Processor_Decision_Code": "",
        "Processor_Reason_Code": "",
        "Processor_Decision_Desc": "",
        "Merchant_Category": "",
        "Account_ID": "",
        "Customer_AC": "",
        "File_Date": "",
        "Cycle_Info": ""
    },
    "ISO_MSG": {}
}

[Table content for Mastercard Version 3 payload structure - temporarily removed due to formatting issues]

Sample FAST clearing and settlement messages for Mastercard clients

Sample FAST request and response messages for various typical settlement scenarios are located here.

Visa settlement messages

For Visa, we support three different versions for FAST settlement messages. The basic structure of these FAST payload versions is provided below.

🗒️
IMPORTANT
All new clients are required to integrate/consume FAST version 3.

FAST payload structure

FAST version 1

{
    "PacketType": "",
    "Header": {
        "DE2": "",
        "source": "",
        "rid_set": "",
        "rid_auth": "",
        "tid": "",
        "cid": "",
        "customer_account": ""
    },
    "iso_msg": {
        "tcr_0": {},
        "tcr_1": {},
        "tcr_5": {}
    }
}

[Table content for Visa Version 1 payload structure - temporarily removed due to formatting issues] ] } [Table content for Visa Version 2 payload structure - temporarily removed due to formatting issues] "2-1": "Contains the public token assigned by Paymentology to replace PAN.", "2-2": "Text field", "3-0": "source", "3-1": "Contains the network scheme", "3-2": "“V” for Visa", "4-0": "rid_set", "4-1": "This field contains an unique id for the clearing message", "4-2": "Text field with the unique id", "5-0": "rid_auth", "5-1": "This field contains the id of the authorization message which matches with the settlement record.", "5-2": "Text field with the id of authorization.", "6-0": "Tid", "6-1": "This field contains the id of the transaction thread. This id will link all the transactions within a lifecycle i.e. auth, presentment , chargeback etc.", "6-2": "Text field with the id", "7-0": "cid", "7-1": "This field contains the client_id for which the message belongs", "7-2": "Text field with the id", "8-0": "customer_account", "8-1": "The account external reference value passed by the client during account creation in paymentology", "8-2": "Text field with value", "9-0": "total_bill_fee", "9-1": "Contains the total fee charged on the transaction", "9-2": "Text field containing amount", "10-0": "iso_msg", "10-1": "Contains a JSON object with multiple TCR objects. TCR0 is always present which contains the basic fields present in the clearing message . Other TCRs can be present if provided in the message.", "10-2": "JSON object" }, "cols": 3, "rows": 11, "align": [ null, null, null ] } [/block]

FAST version 3

{
    "PACKET_TYPE": "",
    "SUMMARY": {
        "TID": "",
        "RID": "",
        "ADD_REF_RID": "",
        "PID": "",
        "ClientID": "",
        "Network": "",
        "Transaction_Date_Time": "",
        "Spend_Type": "",
        "Spend_Location": "",
        "Transaction_Amount": "",
        "Transaction_Currency": "",
        "Billing_Amount": "",
        "Billing_Currency": "",
        "Total_Fee_Bill": "",
        "Card_Use_Type": "",
        "Customer_Validation": "",
        "Processor_Decision_Code": "",
        "Processor_Reason_Code": "",
        "Processor_Decision_Desc": "",
        "Merchant_Category": "",
        "Account_ID": "",
        "Customer_AC": "",
        "File_Date": "",
        "Cycle_Info": ""
    },
    "iso_msg": {
        "tcr_0": {},
        "tcr_1": {},
        "tcr_5": {}
    }
}

Field Name	Field Description	Possible Values
`PACKET_TYPE`	This field identifies the type of message	It can contain following possible values: TC05, TC07, TC25, TC27,…
`SUMMARY`	This field contains multiple other fields which provides the basic information for the message.	JSON Object
`TID`	This field contains the id of the transaction thread. This id will link all the transactions within a lifecycle i.e. auth, presentment , chargeback etc.	Text field with the id
`RID`	Contains the unique id for the clearing message	Text field with id
`ADD_REF_RID`	Contains the id of the matched authorisation	Text field with id
`PID`	Product id	Text field with id
`ClientID`	This field contains the id of the client for which the message belongs	Text field with id
`Network`	Contains the network scheme identifier	Text field with identifier “M” for mastercard
`Transaction_Date_Time`	Local Date and time of the transaction	Text field with date and time in format YYYY-MM-DD HH:mm:ss
`Spend_Type`	Indicates the type of spend performed	Text field
`Spend_Location`	Location at which the spend was performed	Text Field
`Transaction_Amount`	Transaction amount received in the clearing message	Text field containing the amount
`Transaction_Currency`	Alphabetic currency code	Text Field . Length = 3
`Billing_Amount`	Billing amount received in the clearing message
`Billing_Currency`	Alphabetic currency code for billing amount	Text field. Length = 3
`Total_Fee_Bill`	Contains the total fee charged on the transaction	Text field containing amount
`Card_Use_Type`	Indicates the method used for PAN entry to initiate a transaction	Text Field
`Customer_Validation`	Validation method used	Text field . Value “PAN” for clearing message
`Processor_Decision_Code`	Decision code for transaction	“00” for clearing message
`Processor_Reason_Code`	Reason code for transaction	“000”
`Processor_Decision_Desc`	Decision description	“Approve”
`Merchant_Category`	Merchant category code involved in the transaction	Text field . Length = 3
`Account_ID`	Account id involved in the transaction	Text Field containing account number.
`Customer_AC`	The account external reference value passed by the client during account creation in paymentology	Text field with value.
`File_Date`	The date of the file in which the message was received.	Text field containing data in format YYMMDD
`Cycle_Info`	Contains cycle information from Mastercard. The first two digit represents the clearing cycle, third position represents delivery cycle and the last two digit represents the sequence number.	Text field . Length = 5
`ISO_MSG`	The field contains a JSON object with all the data elements present in the clearing message.	JSON Object containing all available data elements.

Package Type Usage

Package Type	Description	Usage
TC05	Sales Draft / Dispute Response Financial	Used for sales draft transactions and dispute response financial postings in the clearing process.
TC06	Credit Voucher / Dispute Response Financial	Represents a credit voucher (refund) or a dispute response financial transaction.
TC07	Cash Disbursement / Dispute Response Financial	Covers cash disbursement transactions (e.g., ATM or over-the-counter cash) and dispute response financials.
TC25	Sales Draft Reversal	Reverses a previously cleared sales draft transaction.
TC26	Credit Voucher Reversal	Reverses a credit voucher (refund) transaction that has already been cleared.
TC27	Cash Disbursement Reversal	Reverses a previously cleared cash disbursement transaction

Sample FAST clearing and settlement messages for Visa clients

Sample FAST request and response messages for various typical settlement scenarios are located here.