Implementing a Funding API Integration
The Funding API allows you to record funding and fee information for orders and transactions processed via the gateway for the purpose of making this information available to merchants. Merchants can subsequently use the information for reconciliation purposes.
Funding and fee information associated with a transaction/order will be stored against the transaction/order. Merchant fees and event fees, i.e., fees not associated with a transaction/order are recorded against an order (standalone funding order) that is created in the gateway only for the purpose of tracking such fees.
Prerequisites
You must be enabled by Mastercard Gateway to use the Funding API. Once you are enabled, you will be able to configure your API credentials on the Admin > Web Services API Integration Settings page in Merchant Manager. See Generating API Credentials
Record Funding
The Record Funding request allows you to create or update orders and transactions with funding and fee information.
Record Funding Request
You need to provide the following key fields in the Record Funding request, which may be grouped as follows:
These mandatory fields must be provided on all Record Funding requests.
apiOperation=RECORD_FUNDINGtransaction.acquirer.idtransaction.acquirer.merchantIdtransaction.funding.eventtransaction.funding.matchAction
If the funding or fee information provided in the request must be associated with a transaction in the gateway, i.e., transaction.funding.matchAction=MATCHED, provide either of the following fields to allow the gateway to uniquely identify the transaction (or order).
transaction.funding.match.rrntransaction.funding.match.acquirerTransactionId
You can also provide the following optional parameters with either of these fields, if needed to uniquely identify the transaction.
transaction.funding.match.date(optional)transaction.funding.match.stan(optional)
Provide these fields to record successful funding or funding adjustments for a Payment, Capture, Refund, or Chargeback transaction, and failed funding for a Payment, Capture, or Refund transaction.
transaction.funding.eventtransaction.funding.datetransaction.funding.estimatedDatetransaction.funding.initiatedDatetransaction.funding.amounttransaction.funding.currency
Provide these fields to record fees for a Verification, Authorization, Payment, Capture, Refund, or Chargeback transaction.
transaction.funding.fee[n].datetransaction.funding.fee[n].estimatedDatetransaction.funding.fee[n].initiatedDatetransaction.funding.fee[n].amounttransaction.funding.fee[n].currencytransaction.funding.fee[n].typetransaction.funding.fee[n].acquirerFeeNametransaction.funding.fee[n].rate
You must provide additional fields when recording funding information for a Chargeback transaction (including both Chargebacks and Chargeback Reversals) where the Chargeback has not yet been recorded in the gateway. The gateway will use this information to create the Chargeback transaction before adding the funding and/or fee information.
transaction.amounttransaction.currencytransaction.dispute.eventDatetransction.dispute.eventInformationtransaction.dispute.reasonCodetransaction.dispute.reason
Record Funding API Reference[REST][NVP]
Examples
Here's a sample Record Funding Request in REST to associate the funding or fee information provided in the request to a transaction in the gateway.
| URL | https://eu-gateway.mastercard.com/api/rest/version/72/mso/{msoId} |
| HTTP Method | PUT |
{
"apiOperation" : "RECORD_FUNDING",
"correlationId" : "12345",
"order" : {
"owningEntity" : "store2"
},
"transaction" : {
"acquirer" : {
"customData" : "custom data",
"id" : "<your_acquirer_Id>",
"merchantId" : "<your_acquirer_merchant_Id>",
"transactionId" : "123"
},
"amount" : "100",
"currency" : "EUR",
"funding" : {
"amount" : "100",
"currency" : "EUR",
"event" : "SUCCESSFUL_FUNDING",
"fee" : [ {
"acquirerFeeName" : "Interchange",
"amount" : "1.5",
"initiatedDate" : "2018-11-14",
"rate" : "1.5",
"type" : "TRANSACTION_FEE"
}, {
"acquirerFeeName" : "Acquiring",
"amount" : "0.30",
"initiatedDate" : "2018-11-15",
"type" : "TRANSACTION_FEE"
} ],
"feeAmount" : "1.80",
"feeCurrency" : "EUR",
"initiatedDate" : "2018-11-15",
"match" : {
"acquirerTransactionId" : "d96acc38-9456-4a1a-b1fb-34afb82eb4d6"
},
"matchAction" : "MATCHED"
}
}
}
{
"correlationId" : "12345",
"fundingTransaction" : [ {
"merchant" : "<your_merchant_Id>",
"order" : {
"id" : "e6cc4df0-2463-42c0-8592-dac171d8cd7d"
},
"transaction" : {
"id" : "2"
}
} ],
"response" : {
"gatewayCode" : "APPROVED"
},
"result" : "SUCCESS"
}
Funding vs Fees
The gateway records funding for a transaction separately to any fees associated with a transaction. Therefore, when submitting the Record Funding request you must provide funding and fee information separately.
For example, for a payment transaction with a transaction amount USD $50 and an Interchange fee of USD $0.15 you must provide USD $50 as successful funding (transaction.funding.amount=50) and USD $0.15 as a fee associated with the payment transaction (transaction.funding.fee[n].amount=0.15).
Funding information can be provided for Capture, Purchase, Refund, Chargeback transactions whereas fee information can be provided for Verification, Authorization, Capture, Purchase, Refund, and Chargeback transactions.
Funding and Fee Date
When providing funding or fee information you must provide a date. If possible, you must provide the actual date that the funds arrived or have been debited from the merchant's bank account (transaction.funding.date for funding and transaction.funding.fee[n].date for fees).
If this information is not available, you can alternatively provide the date you initiated the funds transfer to/from the merchant's bank account (transaction.funding.initiatedDate for funding and transaction. funding.fee[n].initiatedDate for fees). Or, estimate the funds to arrive or be debited from the merchant's bank account (transaction.funding.estimatedDate for funding and transaction.funding.fee[n].estimatedDate for fees).
The date must be provided in the time zone configured for you in the gateway. Contact Mastercard if you are unsure which time zone you must use.
If you provide more than one of these dates the gateway will populate the date fields as follows:
- If the actual date is provided: Only populate the actual date (and ignore any other dates provided).
- If no actual date, but both the estimated and initiated dates are provided: Only the initiated date will be populated.
Order and Transaction Matching
The gateway will record funding information against the transaction for which the funding occurred for the following cases:
- successful funding (for a Payment, Capture, Refund transaction)
- failed funding (for a Payment, Capture, Refund transaction)
- funding adjustments (for a Payment, Capture, Refund, Chargeback, Chargeback Reversal transaction)
- chargeback funding (for a Chargeback transaction)
- chargeback reversal funding (for a Chargeback transaction)
Your Record Funding request must therefore contain transaction.funding.matchAction=MATCH as well as sufficient details for the gateway to uniquely identify the merchant and transaction (or order) for which the funding information is provided including:
transaction.acquirer.id: Provide the unique identifier allocated by the gateway to the acquirer used to process the transaction.transaction.acquirer.merchantId: Provide the unique identifier allocated to the merchant by the acquirer used to process the transaction. This may also be referred to as the Card Acceptor Identification Code (CAIC), Card Acceptor ID (CAID), or Service Establishment Number (SE Number).- One of two ways to identify the transaction:
- Retrieval Reference Number (RRN)
transaction.funding.match.rrn: (Mandatory) Provide the RRN for the transaction as issued by either the gateway or the acquirer.transaction.funding.match.date: (Optional) Provide the date the transaction was created in the gateway (timeofRecord in the Retrieve Transaction response).transaction.funding.match.stan: (Optional) Provide the STAN of the transaction as issued by the gateway (transaction.stan in the Retrieve Transaction response).
- Acquirer Transaction ID
transaction.funding.match.acquirerTransactionId: (Mandatory) Provide the unique identifier for the transaction used by the acquirer (and provided by the acquirer to the gateway in the transaction response).
If the information provided is not sufficient for the gateway to uniquely identify the transaction (or order), the Record Funding request is rejected.
If the gateway is able to uniquely identify the transaction, it will add the funding information to the transaction (or order) and the Record Funding response will contain the order ID and transaction ID of the transaction that has been updated.
Funding Status of Transactions and Orders
When a merchant creates a transaction the gateway automatically sets the transaction funding status (transaction.funding.status) as follows:
- If funding information is provided to the gateway by the acquirer the transaction funding status is set to:
- IN_PROGRESS if the transaction was successful. This indicates to the merchant that funding is expected for this transaction. Once you record funding against this transaction the funding status will be updated accordingly.
- NON_FUNDED if the transaction was not successful. This indicates to the merchant that funding is not expected for this transaction.
- If funding information is not provided to the gateway by the acquirer the transaction funding status is set to NOT_SUPPORTED. This indicates to the merchant that they cannot expect funding information for the transaction to be made available in the gateway.
The gateway also automatically updates the order funding status (transaction.orderStatus) based on the funding status of the transactions on the order.
Funding for Payment, Capture and Refund Transactions
Successful funding means that you have transferred (or initiated the funds transfer for) the funds for a transaction into the merchant's bank account.
Note that the successful funding amount must not include any fees, see Funding versus Fees for details.
If you want to provide details about successful funding for a Payment, Capture or Refund transaction you must submit the Record Funding request with the following details:
transaction.funding.matchAction=MATCH- Order and transaction matching criteria (see Order and Transaction Matching for details)
transaction.funding.event=SUCCESSFUL_FUNDINGtransaction.funding.amounttransaction.funding.currency
Note that for successful funding for a Payment or Capture the funding amount (transaction.funding.amount) must be positive, whereas for successful funding for a Refund the funding amount must be negative.
If the gateway is able to uniquely identify the transaction, it will add the funding information to the transaction and update the transaction funding status (transaction.funding.status), order funding amount (order.funding.amount) and order funding status (order.fundingStatus) accordingly.
The Record Funding response will provide the order ID and transaction ID of the transaction that has been updated.
Failed funding means that you have returned funds for a Payment or Capture to the payer, i.e., initiated for the funds to be debited from the merchant's bank account (e.g. if the payment provider did not end up providing the funds for the transaction but where you had already funded the merchant) or returned funds for a Refund to the merchant (e.g. if the payer's bank account used for a Refund is no longer valid).
Note that failed funding amount must not include any fees, see Funding versus Fees for details.
If you want to provide details about failed funding for a Payment, Capture or Refund transaction you must submit the Record Funding request with the following details:
transaction.funding.matchAction=MATCH- Order and transaction matching criteria (see Order and Transaction Matching for details)
transaction.funding.event=FAILED_FUNDINGtransaction.funding.amounttransaction.funding.currency
Note that for failed funding for a Payment or Capture the funding amount (transaction.funding.amount) must be negative, whereas for failed funding for a Refund the funding amount must be positive.
If the gateway is able to uniquely identify the transaction, it will create a new transaction on the order with the following details:
transaction.id: The transaction ID issued by the gateway.transaction.amount: The transaction amount will be set to zero.transaction.currency: The transaction currency will be set to the funding currency in the Record Funding request.transaction.type= FUNDINGtransaction.funding.status=FUNDING_FAILEDtransaction.funding.amount: The transaction funding amount as provided in the Record Funding request.transaction.funding.currency: The transaction funding currency as provided in the Record Funding request.transaction.acquirer.id: A unique identifier in the gateway for the acquirer used to process the transaction (based on the transaction.acquirer.merchantId provided in the Record Funding request.- Funding Date as as provided in the Record Funding request, see Funding Date for details.
The gateway will update the order funding amount (order.funding.amount) and order funding status (order.fundingStatus) accordingly.
The Record Funding response will provide the order ID of the order to which the transaction has been added and the transaction ID of the transaction that has been created.
See section Funding Adjustments for details.
Funding for Chargebacks and Chargeback Reversals
You can provide funding information for both Chargeback and Chargeback Reversals.
- A Chargeback is represented in the gateway as a transaction with transaction type CHARGEBACK and dispute event (transaction.dispute.event) CHARGEBACK_DEBITED.
- A Chargeback Reversal is represented in the gateway as a transaction with transaction type CHARGEBACK and dispute event (transaction.dispute.event) CHARGEBACK_REVERSED.
All other chargeback transactions are not expected to received funding, so when such a transactions is created in the gateway the transaction funding status is set to NON_FUNDED. This applies to chargeback transactions with dispute events ACTION_REQUIRED and INFORMATION_ONLY.
Note that funding amount must not include any fees, see Funding versus Fees for details.
Funding for a chargeback means that the amount is debited from the merchant's bank account.
To provide details for funding for a Chargeback you must submit the Record Funding request with the following details:
transaction.funding.matchAction=MATCH- Order and transaction matching criteria (see Order and Transaction Matching for details)
transaction.funding.event=CHARGEBACK_FUNDINGtransaction.funding.amounttransaction.funding.currencytransaction.disputeparameter group: This field is mandatory if the Chargeback transaction for which you provide the funding information does not yet exist in the gateway.
Note that for funding for a Chargeback the funding amount (transaction.funding.amount) must be negative.
If the gateway is able to uniquely identify the original transaction (and therefore order) and the order has a Chargeback transaction with dispute event CHARGEBACK_DEBITED, the gateway adds the funding information to the Chargeback transaction and updates the transaction funding status (transaction.funding.status), order funding amount (order.funding.amount) and order funding status (order.fundingStatus) accordingly.
If the gateway is able to uniquely identify the original transaction (and therefore order) but the order does not have a Chargeback transaction with dispute event CHARGEBACK_DEBITED the gateway creates a Chargeback transaction with the following details:
transaction.id: The transaction ID issued by the gateway.transaction.amount: The transaction amount as provided in the Record Funding request.transaction.currency: The transaction currency as provided in the Record Funding request.transaction.type= CHARGEBACKtransaction.funding.status=FUNDEDtransaction.dispute.event=CHARGEBACK_DEBITEDtransaction.funding.amount: The transaction funding amount as provided in the Record Funding request.transaction.funding.currency: The transaction funding currency as provided in the Record Funding request.- Funding Date as as provided in the Record Funding request, see Funding Date for details.
- Dispute details as provided in the transaction request in the transaction.dispute parameter group including:
transaction.dispute.eventDatetransction.dispute.eventInformationtransaction.dispute.reasonCodetransaction.dispute.reason
- Source of funds details (sourceOfFunds parameter group) from the original transaction
The gateway will update the order funding amount (order.funding.amount) and order funding status (order.fundingStatus) accordingly.
The Record Funding response will provide the order ID and transaction ID of the transaction that has been updated or created.
Funding for a Chargeback Reversal means that the amount is credited to the merchant's bank account.
To provide details for funding for a Chargeback Reversal you must submit the Record Funding request with the following details:
transaction.funding.matchAction=MATCH- Order and transaction matching criteria (see Order and Transaction Matching for details)
transaction.funding.event=CHARGEBACK_REVERSAL_FUNDINGtransaction.funding.amounttransaction.funding.currencytransaction.disputeparameter group: This field is mandatory if the Chargeback transaction for which you provide the funding information does not yet exist in the gateway.
Note that for funding for a Chargeback Reversal the funding amount (transaction.funding.amount) must be positive.
If the gateway is able to uniquely identify the original transaction (and therefore order) and the order has a Chargeback transaction with dispute event CHARGEBACK_REVERSED, the gateway adds the funding information to the Chargeback transaction and updates the transaction funding status (transaction.funding.status), order funding amount (order.funding.amount) and order funding status (order.fundingStatus) accordingly.
If the gateway is able to uniquely identify the original transaction (and therefore order) but the order does not have a Chargeback transaction with dispute event CHARGEBACK_REVERSED the gateway creates a Chargeback transaction with the following details:
transaction.id: The transaction ID issued by the gateway.transaction.amount: The transaction amount as provided in the Record Funding request.transaction.currency: The transaction currency as provided in the Record Funding request.transaction.type= CHARGEBACKtransaction.funding.status=FUNDEDtransaction.dispute.event=CHARGEBACK_REVERSEDtransaction.funding.amount: The transaction funding amount as provided in the Record Funding request.transaction.funding.currency: The transaction funding currency as provided in the Record Funding request.- Funding Date as as provided in the Record Funding request, see Funding Date for details.
- Dispute details as provided in the transaction request in the transaction.dispute parameter group including:
transaction.dispute.eventDatetransction.dispute.eventInformationtransaction.dispute.reasonCodetransaction.dispute.reason
- Source of funds details (sourceOfFunds parameter group) from the original transaction
The gateway will update the order funding amount (order.funding.amount) and order funding status (order.fundingStatus) accordingly.
The Record Funding response will provide the order ID and transaction ID of the transaction that has been updated or created.
See section Funding Adjustments for details.
Funding Adjustments
Funding adjustments cover all funds transfers that are not either successful or failed funding for a Payment, Capture, Refund or Chargeback transaction.
Note that funding amount for adjustments must not include any fees, see Funding versus Fees for details.
If you want to provide details about a funding adjustment for a Payment, Capture or Refund transaction you must submit the Record Funding request with the following details:
transaction.funding.matchAction=MATCH- Order and transaction matching criteria (see Order and Transaction Matching for details)
transaction.funding.event=FUNDING_ADJUSTMENTtransaction.funding.amounttransaction.funding.currency
The funding amount for an adjustment may be positive or negative.
If the gateway is able to uniquely identify the transaction, it will create a new transaction on the order with the following details:
transaction.id: The transaction ID issued by the gateway.transaction.amount: The transaction amount will be set to zero.transaction.currency: The transaction currency will be set to the transaction funding currency, as provided in the Record Funding request.transaction.type= FUNDINGtransaction.funding.amount: The transaction funding amount as provided in the Record Funding request.transaction.funding.currency: The transaction funding currency as provided in the Record Funding request.transaction.acquirer.id: A unique identifier in the gateway for the acquirer used to process the transaction (based on the transaction.acquirer.merchantId provided in the Record Funding request.- Funding Date as as provided in the Record Funding request, see Funding Date for details.
The gateway will update the order funding amount (order.funding.amount) accordingly.Note that funding adjustments do not affect the order funding status (order.fundingStatus).
The Record Funding response will provide the order ID of the order to which the transaction has been added and the transaction ID of the transaction that has been created.
Fees
Fees can be associated with any transaction, i.e., any transaction type, including for example Authorizations and Verification Only transactions.
Adding fees to a transaction does not update the transaction (and therefore order) funding status. Typically fee amounts are negative, as they are debited from the merchant's account.
If you want to provide details about fees that are associated with an individual transaction, like for instance discount or interchange fees you must submit the Record Funding request with the following details:
transaction.funding.matchAction=MATCH- Order and transaction matching criteria (see Order and Transaction Matching for details)
transaction.funding.event=FEES_ONLYtransaction.acquirer.merchantId: Provide the unique identifier for the merchant in the acquirer's system used to process the transaction. This may also be referred to as the Card Acceptor Identification Code (CAIC), Card Acceptor ID (CAID), or Service Establishment Number (SE Number).transaction.funding.currencytransaction.funding.fee[n]parameter group: For each fee, you can provide- fee date (mandatory)
- fee amount (mandatory)
- fee type (mandatory): This allows the merchant to categorize the fee, e.g. FUNDING_FEE or CHARGEBACK_FEE.
- fee rate: You may provide this for percentage fees.
- acquirer fee name: Provide the name for this type of fee that you use when communicating to the merchant.
When providing any fee details you must also provide the fee currency in field transaction.funding.feeCurrency (mandatory).
Instead of submitting a separate request for fees only, you can alternatively provide the fee details on a Record Funding request for successful funding, failed funding, a funding adjustment or funding for a chargeback or chargeback reversal. In this case, simply add the transaction.funding.fee[n] parameter group to the Record Funding request for this funding event.
The gateway will add the fee information provided to the transaction in the transaction.funding.fee[n] parameter group and compute the total fee amount for the order (transaction.funding.feeAmount).
The Record Funding response will provide the order ID and transaction ID of the transaction that has been updated.
If you want to provide details about merchant or event fees, i.e., fees that are not associated with an individual transaction, like merchant monthly fees, wire transfer fees or fraud investigation fees you must submit the Record Funding request with the following details:
transaction.funding.matchAction=STANDALONEtransaction.funding.event=FEES_ONLYtransaction.acquirer.merchantId: Provide the unique identifier for the merchant in the acquirer's system used to process the transaction. This may also be referred to as the Card Acceptor Identification Code (CAIC), Card Acceptor ID (CAID), or Service Establishment Number (SE Number).transaction.funding.fee[n]parameter group: For each fee, you can provide- fee date (mandatory)
- fee amount (mandatory)
- fee type (mandatory): This allows the merchant to categorize the fee, e.g., MERCHANT_FEE or OTHER_FEE.
- fee rate: You may provide this for percentage fees.
- acquirer fee name: Provide the name for this type of fee that you use when communicating to the merchant.
When providing any fee details you must also provide the fee currency in field transaction.funding.feeCurrency (mandatory).
This will result in the gateway creating a new order (standalone funding order) and recording the fee information against this order as follows:
order.id: Order ID issued by the gateway.order.amount: Order Amount set to zero.order.currency: Order Currency set to the currency of the fee.order.description: Order Description set to "Funding information provided by the Service Provider".order.status=FUNDING_ONLYorder.fundingStatus)=NON_FUNDEDtransaction.id: Transaction ID issued by the gateway for the transaction.transaction.amount: The transaction amount will be set to zero.transaction.type= FUNDINGtransaction.funding.status=NON_FUNDEDtransaction.funding.feeAmount: Computed by the gateway as the sum of the fee amounts for all fees on this transaction.transaction.funding.feeCurrency: Set to the fee currency of the fees on this transaction. Note that all fees on the transaction must have the same fee currency.- Fee information as provided in the Record Funding request in the transaction.funding.fee[n] parameter group.
Note that the neither the order nor transaction that have been created have any source of funds details, i.e., sourceOfFunds.type set to NONE and the sourceOfFunds parameter group is not present.
The Record Funding response will provide the order ID and transaction ID of the transaction that has been updated.
In case the gateway identified more than one gateway merchant profile with the same acquirer merchant ID (transaction.acquirer.merchantId), a single standalone funding order is created (on the first profile identified).
Here's a sample Record Funding Request in REST where the fees are not associated to a transaction in the gateway.
| URL | https://eu-gateway.mastercard.com/api/rest/version/72/mso/{msoId} |
| HTTP Method | PUT |
{
"apiOperation" : "RECORD_FUNDING",
"correlationId" : "12345",
"order" : {
"owningEntity" : "store2"
},
"transaction" : {
"acquirer" : {
"customData" : "custom data",
"id" : "<your_acquirer_Id>",
"merchantId" : "<your_acquirer_merchant_Id>",
"transactionId" : "123"
},
"funding" : {
"event" : "FEES_ONLY",
"fee" : [ {
"acquirerFeeName" : "Merchant Monthly Fee",
"amount" : "30",
"initiatedDate" : "2018-11-14",
"type" : "MERCHANT_FEE"
}, {
"acquirerFeeName" : "Merchant Min Monthly Fee",
"amount" : "15",
"initiatedDate" : "2018-11-15",
"type" : "MERCHANT_FEE"
} ],
"feeAmount" : "45",
"feeCurrency" : "EUR",
"matchAction" : "STANDALONE"
}
}
}
{
"correlationId": "12345",
"fundingTransaction": [
{
"merchant": "<your_merchant_Id>",
"order": {
"id": "4CXR-FE7P-CARD"
},
"transaction": {
"id": "2K363C"
}
}
],
"response": {
"gatewayCode": "APPROVED"
},
"result": "SUCCESS"
}
Funding Assured
If you have not yet initiated the funds transfer to the merchant's account for a Payment, Capture, Refund or Chargeback but you know that funding will occur, you may want to let the merchants know in advance to the actual funds transfer being initiated. This will for example allow the merchant to ship the goods knowing that funding for the payment is assured.
Note that telling the merchant that funding is assured does not include an actual funding amount (as this amount may not be known at this point in time). It simply updates the funding status of the transaction to FUNDING_ASSURED. Only once you provide details about the successful funding, will the funding status be updated to FUNDED.
If you want to provide details about assured funding for a Payment, Capture, Refund or Chargeback transaction you must submit the Record Funding request with the following details:
transaction.funding.matchAction=MATCH- Order and transaction matching criteria (see Order and Transaction Matching for details)
transaction.funding.event=FUNDING_ASSURED
If you provide a funding amount and/or currency, it will be ignored.
If the gateway is able to uniquely identify the transaction, it will update the Transaction Funding Status (transaction.funding.status) of the transaction to FUNDING_ASSURED and update the order funding status (order.fundingStatus) of the associated order accordingly.
The Record Funding response will provide the order ID and transaction ID of the transaction that has been updated.
Funding On Hold
If you were unable to complete the funds transfer for a Payment, Capture, Refund or Chargeback (e.g. if the merchant's account details provided were invalid or the account has been closed) you can let the merchant know by setting the funding status of a transaction to FUNDING_ON_HOLD.
Note that telling the merchant that funding is on hold does not include an actual funding amount. It simply updates the funding status of the transaction to FUNDING_ON_HOLD. Only once you provide details about the successful funding, will the funding status be updated to FUNDED.
If you want to provide details about a funding being on hold for a Payment, Capture, Refund or Chargeback transaction you must submit the Record Funding request with the following details:
transaction.funding.matchAction=MATCH- Order and transaction matching criteria (see Order and Transaction Matching for details)
transaction.funding.event=FUNDING_ON_HOLD
If you provide a funding amount and/or currency, it will be ignored.
If the gateway is able to uniquely identify the transaction, it will update the Transaction Funding Status (transaction.funding.status) of the transaction to FUNDING_ASSURED and update the order funding status (order.fundingStatus) of the associated order accordingly.
The Record Funding response will provide the order ID and transaction ID of the transaction that has been updated.
Order Funding Amount
After adding funding information to a transaction, the gateway automatically updates the total funding amount for the order (order.funding.amount).
Order and Transaction Funding Status
After adding funding information to a transaction, the gateway automatically updates the funding status for the transaction (transaction.funding.status) as well as the funding status for the order (order.fundingStatus).
Settlement Identifier
You can provide your identifier for the group of transactions settled into the merchant's bank account, that contained funding for a transaction on the Record Funding request for this transaction in the transaction.funding.settlementIdentifier field.
This will for example allow your merchants to quote this identifier when there are any issues with the funding for this transaction.
MSO On-Behalf-Of Support
The gateway allows you to submit the Record Funding request if you have been authorized to do so on behalf of another MSO. In the Record Funding request URL, specify the MSO ID of the MSO that has authorized you to submit this request. Provide your API credentials as configured in Merchant Manager to successfully authenticate to the gateway.
Testing Funding API
The Funding API does not support a specific testing framework; however, there are ways to test your integration on the gateway.
The first step is to configure your business application to use the gateway's Mastercard Testing Framework (MTF) environment. Contact Mastercard for access to the MTF environment.
Once the MTF environment is configured, you can start recording funding and fee information against transactions. To allow the funding or fee information provided in the request to be associated with a transaction in the gateway, create a test transaction for a production merchant profile, record the RRN and the date of the transaction. Provide the RRN and the date in transaction.funding.match.rrn and transaction.funding.match.date fields respectively, in the Record Funding request.
To check if the funding and fee information has been successfully recorded by the gateway, log on to Merchant Manager, Merchant Administration using the production merchant ID, or submit Retrieve Transaction/Retrieve Order operation and verify the data.
Once you are satisfied with the recorded funding and fee data, you can start recording funding and fee information on the production environment.