Funding

Operation to create or update Orders and Transactions with Funding Information

PUT https://eu-gateway.mastercard.com/api/rest/version/52 / mso / {msoId}

Authentication

This operation requires authentication via one of the following methods:


  • Certificate authentication.
  • Basic HTTP authentication as described at w3.org. Provide 'MSO.<your gateway MSO ID>' in the userid portion and your API password in the password portion.

Request

URL Parameters

{msoId} Alphanumeric + additional characters REQUIRED

The identifier that uniquely identifies you or an MSO that has authorized you to use this operation on their behalf.


Data may consist of the characters 0-9, a-z, A-Z, '-', '_', ' ', '&', '+', '!', '$', '%', '.'

Min length: 1 Max length: 16

Fields

apiOperation String = RECORD_FUNDING FIXED

Any sequence of zero or more unicode characters.

correlationId String OPTIONAL

A transient identifier for the request, that can be used to match the response to the request.

The value provided is not validated, does not persist in the gateway, and is returned as provided in the response to the request.

Data can consist of any characters

Min length: 1 Max length: 100
order.owningEntity String OPTIONAL

Your identifier for the part of your organization that is responsible for the order.

You might provide this data when you want to track the accountability for the order. For example, store number, sales region, branch, or profit center

Data can consist of any characters

Min length: 1 Max length: 40
transaction REQUIRED

Information about this transaction.

transaction.acquirer REQUIRED
transaction.acquirer.additionalResponseData JSON Text OPTIONAL

Provides additional data provided by the acquirer in the transaction response that could be of interest to you.

It might provide additional information that may help you understand unexpected results or provide acquirer-specific response data.
For example, it could provide information about the results of validation of data by the issuer or card scheme of data you provided for card present transactions.
The data is provided as a series of name-value pairs where the name is the acquirer field and the value is exactly as provided by the acquirer.
For example, {"48.74.1":3, "48.74.2:5":48, "48.80":67}

Data is valid Json Format

Min length: 1 Max length: 4000
transaction.acquirer.customData String OPTIONAL

Additional information requested by the acquirer which cannot be passed using other available data fields.

This field must not contain sensitive data.

Data can consist of any characters, but sensitive data will be rejected

Min length: 1 Max length: 2048
transaction.acquirer.id String REQUIRED

The ID for the acquirer used to process the transaction.

Data can consist of any characters

Min length: 1 Max length: 40
transaction.acquirer.merchantId String REQUIRED

An identifier allocated by an acquirer to the merchant.

This may also be referred to as the Card Acceptor Identification Code (CAIC), Card Acceptor ID (CAID), or Service Establishment Number (SE Number).

Data can consist of any characters

Min length: 1 Max length: 127
transaction.acquirer.transactionId String OPTIONAL

Identifier used by the acquirer to identify the transaction.

This identifier may be used by the acquirer in settlement reports.

Data can consist of any characters

Min length: 1 Max length: 100
transaction.amount Decimal OPTIONAL

The total amount for the transaction.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
transaction.currency Upper case alphabetic text OPTIONAL

The currency of the transaction expressed as an ISO 4217 alpha code, e.g. USD.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
transaction.dispute OPTIONAL

Information about the disputed transaction.

Note: If you are using the RECORD_FUNDING operation then only provide this data if you receive information about a chargeback along with its funding information. In this case, the gateway will create a chargeback transaction, and record the funding information for it.

transaction.dispute.eventDate Date OPTIONAL

The date of the event in the dispute management process described by transaction.dispute.event.

Data must comply with ISO 8601 extended date format, yyyy-mm-dd

transaction.dispute.eventInformation String OPTIONAL

Additional information about the dispute event (see transaction.dispute.event).

The terms used here will reflect the terms used by your bank.

Data can consist of any characters

Min length: 1 Max length: 100
transaction.dispute.reason ASCII Text OPTIONAL

A description of why the transaction is disputed.

Data consists of ASCII characters

Min length: 1 Max length: 100
transaction.dispute.reasonCode ASCII Text OPTIONAL

A code provided by the acquirer to indicate the reason for the chargeback.

Data consists of ASCII characters

Min length: 1 Max length: 10
transaction.funding OPTIONAL

Details of the amount settled to your account for this transaction.

This group is present for transactions that could be funded, including successful CAPTURE, REFUND and PAY transactions as well as FUNDING transactions that provide funding and/or fee details only.

transaction.funding.acquirerEventDescription String OPTIONAL

The service provider's description for the funding type.

Data can consist of any characters

Min length: 1 Max length: 100
transaction.funding.amount Decimal OPTIONAL

The amount of money in your bank account, as reported to the gateway for this transaction.

This may be a credit (positive value) or debit (negative value).
This value is provided if transaction.funding.status is FUNDED. It might be provided if transaction.funding.status is FUNDING_ASSURED or FUNDING_ON_HOLD.

Data is a string that consists of the characters 0-9, '.' and '-' and represents a valid decimal number.

Min length: 1 Max length: 14
transaction.funding.currency Upper case alphabetic text OPTIONAL

The currency of transaction.funding.amount expressed as an ISO 4217 alpha code, e.g. USD.

This value is provided if transaction.funding.status is FUNDED. It might be provided if transaction.funding.status is FUNDING_ASSURED or FUNDING_ON_HOLD.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
transaction.funding.date Date OPTIONAL

The date the funds arrive in your bank account.

The date is defined in the acquirer's time zone (see transaction.acquirer.timeZone).
This value is only populated if the date is known with certainty.

Data must comply with ISO 8601 extended date format, yyyy-mm-dd

transaction.funding.estimatedDate Date OPTIONAL

The date the acquirer estimates the funds to arrive in your bank account.

This value is only populated if neither the initiated date nor the actual funding date are available.
The date is defined in the acquirer's time zone (see transaction.acquirer.timeZone).

Data must comply with ISO 8601 extended date format, yyyy-mm-dd

transaction.funding.event Enumeration REQUIRED

The event that triggered the movement of funds to/ from your account.

Value must be a member of the following list. The values are case sensitive.

CHARGEBACK_FUNDING

Funds for a chargeback have been debited from your account.

CHARGEBACK_REVERSAL_FUNDING

Funds for a chargeback that had been debited to your account have been successfully credited back to your account.

FAILED_FUNDING

Funds have been debited from or credited to your account when the funds transfer for a transaction was not able to be completed. For example, funds are credited for a refund because the payer's account was closed or a service provider has debited your account because they had not received the funds from the payer's bank after they had funded your account.

FEES_ONLY

Fees charged for the transaction before or after the transaction itself has been funded.

FUNDING_ADJUSTMENT

Funding for the transaction has been adjusted.

FUNDING_ASSURED

Funding for this transaction is guaranteed to happen but has not yet done so.

FUNDING_ON_HOLD

Funds for the transaction could not be credited/debited from your account because of some problem with your account. This might be a transient state.

SUCCESSFUL_FUNDING

Funds for the transaction have successfully been credited to/debited from your account.

transaction.funding.fee[n] OPTIONAL

Breakdown of the fees deducted by your acquirer for this transaction.

transaction.funding.fee[n].acquirerFeeName String OPTIONAL

The name of the fee as provided by your acquirer.

Data can consist of any characters

Min length: 0 Max length: 127
transaction.funding.fee[n].amount Decimal OPTIONAL

The fee amount for the fee type defined in funding.fee[n].type for this transaction.

Data is a string that consists of the characters 0-9, '.' and '-' and represents a valid decimal number.

Min length: 1 Max length: 14 Max post-decimal digits: 4
transaction.funding.fee[n].date Date OPTIONAL

The date the fees are debited from your bank account.

This value is only populated if the date is known with certainty.
The date is defined in the acquirer's time zone (see transaction.acquirer.timeZone).

Data must comply with ISO 8601 extended date format, yyyy-mm-dd

transaction.funding.fee[n].estimatedDate Date OPTIONAL

The date the acquirer estimates that the fees are being debited from your bank account.

This value is only populated if neither the initiated date nor the actual date the funds are debited are available.
The date is defined in the acquirer's time zone (see transaction.acquirer.timeZone).

Data must comply with ISO 8601 extended date format, yyyy-mm-dd

transaction.funding.fee[n].initiatedDate Date OPTIONAL

The date the acquirer initiated the fees being debited from your bank account.

This value is only populated if the date of transfer is known with certainty, but the date the funds will settle to your account is uncertain.
The date is defined in the acquirer's time zone (see transaction.acquirer.timeZone).

Data must comply with ISO 8601 extended date format, yyyy-mm-dd

transaction.funding.fee[n].rate Decimal OPTIONAL

The rate (percentage) applied to the transaction amount to determine the fee amount for the fee type defined in funding.fee[n].type.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 6
transaction.funding.fee[n].type Enumeration OPTIONAL

The fee type for which the amount defined in funding.fee[n].amount has been charged.

Value must be a member of the following list. The values are case sensitive.

CHARGEBACK_FEE

Fees associated with Chargeback transactions.

FUNDING_FEE

Fees associated with transferring money to your account.

MERCHANT_FEE

Fees associated with the merchant account. For example: Merchant monthly fee, Minimum monthly fee.

OTHER_FEE

Any other fees that have not been captured by the above types.

TRANSACTION_FEE

Fees associated with Authorization, Capture and Refund transactions.

transaction.funding.feeAmount Decimal OPTIONAL

The total fee amount as provided by your service provider.

If not provided by the acquirer this value will be the sum of fee amounts from transaction.funding.fee[n] parameter group.

Data is a string that consists of the characters 0-9, '.' and '-' and represents a valid decimal number.

Min length: 1 Max length: 14 Max post-decimal digits: 4
transaction.funding.feeCurrency Upper case alphabetic text OPTIONAL

The currency of transaction.funding.feeAmount expressed as an ISO 4217 alpha code, e.g. USD.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
transaction.funding.initiatedDate Date OPTIONAL

The date the acquirer initiated the funds transfer into your bank account.

This value is only populated if the date of transfer is known with certainty, but the date the funds will settle to your account is uncertain.
The date is defined in the acquirer's time zone (see transaction.acquirer.timeZone).

Data must comply with ISO 8601 extended date format, yyyy-mm-dd

transaction.funding.match.acquirerTransactionId String OPTIONAL

Identifier used by the acquirer to identify the original transaction.

Data can consist of any characters, but sensitive data will be rejected

Min length: 1 Max length: 100
transaction.funding.match.date Date OPTIONAL

The date of the original transaction.

Data must comply with ISO 8601 extended date format, yyyy-mm-dd

transaction.funding.match.rrn ASCII Text OPTIONAL

The Retrieval Reference Number of the original transaction.

Data consists of ASCII characters

Min length: 1 Max length: 100
transaction.funding.settlementIdentifier String OPTIONAL

Your bank's Identifier for the group of transactions settled to your account.

Data can consist of any characters

Min length: 1 Max length: 40
transaction.funding.matchAction Enumeration REQUIRED

Indicates how you want the gateway to record the funding information.

Value must be a member of the following list. The values are case sensitive.

MATCHED

Create the funding transaction only if it can be matched to the original transaction being funded.

STANDALONE

Do not match the funding transaction to the original transaction being funded; create a new order containing the chargeback transaction..

Response

Fields

correlationId String CONDITIONAL

A transient identifier for the request, that can be used to match the response to the request.

The value provided is not validated, does not persist in the gateway, and is returned as provided in the response to the request.

Data can consist of any characters

Min length: 1 Max length: 100
fundingTransaction[n] ALWAYS PROVIDED

A list containing the merchant, order and transaction identifiers for the transactions updated or created.

fundingTransaction[n].merchant Alphanumeric + additional characters ALWAYS PROVIDED

The unique identifier issued to you by your payment provider.

This identifier can be up to 12 characters in length.

Data may consist of the characters 0-9, a-z, A-Z, '-', '_'

Min length: 1 Max length: 40
fundingTransaction[n].order.id String ALWAYS PROVIDED

A unique identifier for this order to distinguish it from any other order you create.

Use this identifier when referring to this order in subsequent transactions and in retrieval operations.
This value must be unique for every order created by your merchant profile.

Data can consist of any characters

Min length: 1 Max length: 40
fundingTransaction[n].transaction.id String ALWAYS PROVIDED

Unique identifier for this transaction to distinguish it from any other transactions on the order.

Data can consist of any characters

Min length: 1 Max length: 40
response.gatewayCode Enumeration ALWAYS PROVIDED

Summary of the success or otherwise of the proposed operation.

Value must be a member of the following list. The values are case sensitive.

ABORTED

Transaction aborted by payer

ACQUIRER_SYSTEM_ERROR

Acquirer system error occurred processing the transaction

APPROVED

Transaction Approved

APPROVED_AUTO

The transaction was automatically approved by the gateway. it was not submitted to the acquirer.

APPROVED_PENDING_SETTLEMENT

Transaction Approved - pending batch settlement

AUTHENTICATION_FAILED

Payer authentication failed

AUTHENTICATION_IN_PROGRESS

The operation determined that payer authentication is possible for the given card, but this has not been completed, and requires further action by the merchant to proceed.

BALANCE_AVAILABLE

A balance amount is available for the card, and the payer can redeem points.

BALANCE_UNKNOWN

A balance amount might be available for the card. Points redemption should be offered to the payer.

BLOCKED

Transaction blocked due to Risk or 3D Secure blocking rules

CANCELLED

Transaction cancelled by payer

DECLINED

The requested operation was not successful. For example, a payment was declined by issuer or payer authentication was not able to be successfully completed.

DECLINED_AVS

Transaction declined due to address verification

DECLINED_AVS_CSC

Transaction declined due to address verification and card security code

DECLINED_CSC

Transaction declined due to card security code

DECLINED_DO_NOT_CONTACT

Transaction declined - do not contact issuer

DECLINED_INVALID_PIN

Transaction declined due to invalid PIN

DECLINED_PAYMENT_PLAN

Transaction declined due to payment plan

DECLINED_PIN_REQUIRED

Transaction declined due to PIN required

DEFERRED_TRANSACTION_RECEIVED

Deferred transaction received and awaiting processing

DUPLICATE_BATCH

Transaction declined due to duplicate batch

EXCEEDED_RETRY_LIMIT

Transaction retry limit exceeded

EXPIRED_CARD

Transaction declined due to expired card

INSUFFICIENT_FUNDS

Transaction declined due to insufficient funds

INVALID_CSC

Invalid card security code

LOCK_FAILURE

Order locked - another transaction is in progress for this order

NOT_ENROLLED_3D_SECURE

Card holder is not enrolled in 3D Secure

NOT_SUPPORTED

Transaction type not supported

NO_BALANCE

A balance amount is not available for the card. The payer cannot redeem points.

PARTIALLY_APPROVED

The transaction was approved for a lesser amount than requested. The approved amount is returned in order.totalAuthorizedAmount.

PENDING

Transaction is pending

REFERRED

Transaction declined - refer to issuer

SUBMITTED

The transaction has successfully been created in the gateway. It is either awaiting submission to the acquirer or has been submitted to the acquirer but the gateway has not yet received a response about the success or otherwise of the payment.

SYSTEM_ERROR

Internal system error occurred processing the transaction

TIMED_OUT

The gateway has timed out the request to the acquirer because it did not receive a response. Points redemption should not be offered to the payer.

UNKNOWN

The transaction has been submitted to the acquirer but the gateway was not able to find out about the success or otherwise of the payment. If the gateway subsequently finds out about the success of the payment it will update the response code.

UNSPECIFIED_FAILURE

Transaction could not be processed

result Enumeration ALWAYS PROVIDED

A system-generated high level overall result of the operation.

Value must be a member of the following list. The values are case sensitive.

FAILURE

The operation was declined or rejected by the gateway, acquirer or issuer

PENDING

The operation is currently in progress or pending processing

SUCCESS

The operation was successfully processed

UNKNOWN

The result of the operation is unknown

Errors

error

Information on possible error conditions that may occur while processing an operation using the API.

error.cause Enumeration

Broadly categorizes the cause of the error.

For example, errors may occur due to invalid requests or internal system failures.

Value must be a member of the following list. The values are case sensitive.

INVALID_REQUEST

The request was rejected because it did not conform to the API protocol.

REQUEST_REJECTED

The request was rejected due to security reasons such as firewall rules, expired certificate, etc.

SERVER_BUSY

The server did not have enough resources to process the request at the moment.

SERVER_FAILED

There was an internal system failure.

error.explanation String

Textual description of the error based on the cause.

This field is returned only if the cause is INVALID_REQUEST or SERVER_BUSY.

Data can consist of any characters

Min length: 1 Max length: 1000
error.field String

Indicates the name of the field that failed validation.

This field is returned only if the cause is INVALID_REQUEST and a field level validation error was encountered.

Data can consist of any characters

Min length: 1 Max length: 100
error.supportCode String

Indicates the code that helps the support team to quickly identify the exact cause of the error.

This field is returned only if the cause is SERVER_FAILED or REQUEST_REJECTED.

Data can consist of any characters

Min length: 1 Max length: 100
error.validationType Enumeration

Indicates the type of field validation error.

This field is returned only if the cause is INVALID_REQUEST and a field level validation error was encountered.

Value must be a member of the following list. The values are case sensitive.

INVALID

The request contained a field with a value that did not pass validation.

MISSING

The request was missing a mandatory field.

UNSUPPORTED

The request contained a field that is unsupported.

result Enumeration

A system-generated high level overall result of the operation.

Value must be a member of the following list. The values are case sensitive.

ERROR

The operation resulted in an error and hence cannot be processed.

Resources

Glossary FAQs