Funding and Fee Information
The Mastercard Gateway offers support for your service provider to provide funding and fee information. The responsibility for the correctness of this information lies with the service provider.
Funding and fee information refers to the actual movement of funds by the service provider into your bank account. Funding can be positive (funding for a Payment or Capture) or negative (funding for a Refund). Fees are always negative. That is, debited from your bank account.
Prerequisites
The funding and fee information is only available on orders and transactions for which your service provider has provided the information to the Mastercard Gateway.
How to retrieve funding and fee information
If funding and fee information is provided by your service provider, you can retrieve this information from the Mastercard Gateway via:
- An API
RETRIEVE_ORDERorRETRIEVE_TRANSACTIONrequest - A transaction report via the Reporting API
- The Order or Transaction export from Merchant Administration
You can also sign up for Webhook Notifications to find out about any updates.
Transaction funding
Information about funding for a transaction is recorded against the transaction, including the funding amount and currency in the following API fields:
transaction.funding.amounttransaction.funding.currency
Funding for a:
- Payment or Capture transaction is credited to your account, so the funding amount will be positive.
- Refund is credited from your account, so the funding amount will be negative.
Transaction funding status
Based on the funding information for a transaction the transaction funding status is updated as follows:
| API Field | Status | Description |
|---|---|---|
transaction.funding.status |
NOT_SUPPORTED |
The transaction was settled to an institution from which the Mastercard Gateway does not receive funding information. |
NON_FUNDED |
The transaction cannot result in the transfer of money to or from your account. This applies to VERIFICATION or AUTHORIZATION transactions. |
|
IN_PROGRESS |
The transaction could result in the transfer of money to or from your account, but has not yet done so. This is usually a transient state. | |
FUNDING_ASSURED |
The transaction is guaranteed to settle, but has not yet done so. | |
FUNDED |
The transaction has now settled money into your account. | |
FUNDING_ON_HOLD |
The transaction could result in the transfer of money to / from your account, however the financial provider is unable to complete the transfer of funds. This might be a transient state. | |
FUNDING_FAILED |
The transaction could result in the transfer of money to / from your account, however the service provider has not yet recieved funds from the payer. In case of a refund the service provider was not able to transfer funds to the payer. | |
FUNDING_ADJUSTED |
A previously funded amount for the order has been adjusted. The adjustment could be either a credit or a debit to your account. |
Funding date
The Mastercard Gateway will provide at least one of the following dates for when the funding happened or will happen:
| API Field | Description |
|---|---|
transaction.funding.date |
The date the funds arrive in your bank account. Only populated if certain. |
transaction.funding.initiatedDate |
The date the acquirer initiated the funds transfer into your bank account. Only populated if neither the initiated date nor the actual funding date are available. |
transaction.funding.estimatedDate |
The date the acquirer estimates the funds to arrive in your bank account. Only populated if date is known with certainty, but the date the funds will settle to your account (transaction.funding.date) is uncertain. |
Which of the dates are provided depends on the information provided by the acquirer. However:
- At least one of these dates will be available
- Typically not all of these dates are available.
transaction.acquirer.timeZone).When is the funding status of a transaction updated?
The Mastercard Gateway will update the funding status of an order when it receives the information from the acquirer that funding occurred for a transaction.
When is it safe to ship the goods?
A transaction funding status of FUNDING_ASSURED or FUNDED indicates that it is safe for you to ship the goods to the payer.
Failed funding
If funding for a Payment or Capture transaction failed, the acquirer may recall the funds. That is, debit them from your account. In this case, a transaction with transaction type FUNDING is created on the order for the transaction for which funding failed. This transaction will have a transaction amount of zero and the same currency as the currency in which you were funded (settlement currency). The funding amount will be negative.
If funding for a Refund transaction failed, the acquirer may return the funds to you. For example, if the funds could not be returned to the payer because of the payer's account being closed. In this case, a transaction with transaction type FUNDING is created on the order for the transaction for which funding failed. This transaction will have a transaction amount of zero and the same currency as the currency in which you were funded (settlement currency). The funding amount will be positive.
Order funding status
The funding status reflects the current status of the funding for the money that you can reasonably expect for this order. It reflects both money into and out of your bank account. That is, both sales and refunds.
The order funding status (order.fundingStatus) is derived from the transaction funding status (transaction.funding.status) of the transactions assigned to the order.
When considering funding status, the Mastercard Gateway only examines transactions that can move funds. For example, it ignores Authorizations and declined Captures. This is because the Order Funding Status reflects the movement of the money for the commercial transaction, it does not reflect the movement of money for fees associated with the transaction.
| API Field | Status | Description |
|---|---|---|
order.fundingStatus |
NOT_SUPPORTED |
All transactions on the order were settled to a payment provider from which the Mastercard Gateway does not receive funding information. |
NON_FUNDED |
There are no transactions on the order that could result in transfer of money to or from your account. | |
IN_PROGRESS |
There are transactions on the order that could result in the transfer of money to or from your account, but some have not yet have done so. This is usually a transient state. | |
FUNDING_ASSURED |
All transactions that could transfer money to or from your account, are guaranteed to settle, but have not yet done so. The exact amount of the funds to be transferred might not be known in this state. | |
FUNDED |
All transactions that could transfer money to or from your account are clearing and will settle. | |
FUNDING_FAILED |
There are transactions on the order that could result in the transfer of money to or from your account, however the service provider is unable to complete the transfer of funds because of some problem with your account. This might be a transient state. | |
FUNDING_ON_HOLD |
There are transactions on the order that could result in the transfer of money to or from your account, however the service provider has not yet received funds from the payer. In the case of an order with a refund, the service provider was not able to return funds to the payer. You might need to contact the payer to unblock this condition. |
Order funding amount
The order funding amount (order.funding.amount) reflects the total amount of money funded to or from your bank account for this order (as reported to the Mastercard Gateway by your acquirer). This includes sales (credits to your account) and refunds (debits).
Refer to the order funding status (order.funding.status) to determine the certainty of this value.
Order funding currency
The order funding currency (order.funding.currency) is set to the same value as the transaction funding currency (transaction.funding.currency) of the first funded transaction for an order.
Funding information not provided
For transactions processed via an acquirer for which funding information is not provided in the Mastercard Gateway, the transaction funding status is set to NOT_SUPPORTED.
Fees
There are three types of acquirer fees:
- Transaction fees. For example, interchange fee.
- Event-related fees. For example, fraud inquiry fee and wire transfer fee.
- Merchant fees. For example, merchant setup fee, merchant monthly fee, and merchant minimum monthly fee.
Transaction fees
Information about fees applicable for a transaction is provided against the transaction in the following API fields:
transaction.funding.fee[n].feeTypetransaction.funding.fee[n].acquirerFeeNametransaction.funding.fee[n].amounttransaction.funding.fee[n].rate
Fee amounts are debited from your account by the acquirer but are positive amounts in the API.
Merchant and event fees
Information about fees applicable for a merchant or event is provided against a standalone funding order.
A standalone funding order has the following order details:
| Order Field | Description |
|---|---|
order.id |
ID issued by the Mastercard Gateway. |
order.amount |
0 |
order.currency |
Set to the settlement currency of the merchant or event fee recorded. |
order.status |
Set to FUNDING_ONLY. |
order.fundingStatus |
Set to NON_FUNDED. |
sourceOfFunds.type |
Set to NONE. |
order.description |
Contains a string that explains that this order only contains fee information. |
A standalone funding order also has the following transaction details:
| Transaction Field | Description |
|---|---|
transaction.id |
ID issued by the Mastercard Gateway. |
transaction.amount |
0 |
transaction.type |
Set to FUNDING. |
transaction.funding.fee[n] parameter group |
Fee information. |
If merchant or event fees are provided by the acquirer for a given merchant with an acquirer ID that is associated with more than one merchant in the Mastercard Gateway, the information is only recorded once (against a single merchant profile).
transaction.acquirer.id).Transaction fee amount
The transaction fee amount (transaction.funding.feeAmount) is provided in the settlement currency (transaction.funding.feeCurrency) and reflects the total amount of fees debited from your bank account for this transaction (as reported to the Mastercard Gateway by your acquirer).
Fee amounts may be provided with up to 4 decimal places (independent of the exponent of the currency). Therefore the total fee amount for the transaction may not agree with the sum of all fee amounts due to rounding.