Transactions
Transactions are actions that are made on the order. They might be authenticating the payer or card, reserving payer funds, or moving money between you and the payer. You initiate a transaction in your system by sending an API request to the Mastercard Gateway, which in turn processes the request and sends it forward to a relevant payment method provider or acquirer.
PUT/merchant/{merchantId}/order/{orderid}/transaction/{transactionid}
Authorize
Request to obtain an authorization for a proposed funds transfer. An authorization is a response from a financial institution indicating that payment information is valid and funds are available in the payers account.
Request Parameters
Required Properties for a simple request.
- Name
apiOperation- Type
- string Required
- Description
- AUTHORIZE
- Name
order- Type
- object Required
- Description
- Information about the order associated with this transaction.
- Name
sourceOfFunds- Type
- object Required
- Description
- The details describing the source of the funds to be used.
Response Parameters
Required Properties for a simple request.
- Name
browserPayment- Type
- object
- Description
- Information used to manage interactions with the payment provider if you are offering your payment page on a website or are redirecting the payer's browser to the provider's website.
- Name
merchant- Type
- string
- Description
- The unique identifier issued to you by your payment provider.
- Name
order- Type
- object
- Description
- Information about the order associated with this transaction.
- Name
response- Type
- object
- Description
- Response
- Name
result- Type
- enum
- Description
- A system-generated high level overall result of the operation.Enum Options:FAILUREPENDINGSUCCESSUNKNOWN
- Name
transaction- Type
- object
- Description
- Information about this transaction.
PUT/merchant/{merchantId}/balanceInquiry
Balance Inquiry
Request to retrieve the balance available to spend on a card. You can use this operation to request: The balance available on a gift card, or The balance available to spend by redeeming rewards earned using a card enrolled in a rewards program. For gift cards, only the balance available is returned. For credit or debit cards, additional details such as the reward points available to redeem and the conversion rate used to determine the available balance are also returned.
Request Parameters
Required Properties for a simple request.
- Name
order- Type
- object Required
- Description
- Information about the order associated with this transaction.
- Name
sourceOfFunds- Type
- object Required
- Description
- Information about the order associated with this transaction.
Response Parameters
Required Properties for a simple request.
- Name
merchant- Type
- string
- Description
- The unique identifier issued to you by your payment provider.
- Name
order- Type
- object
- Description
- Information about the order associated with this transaction.
- Name
response- Type
- object
- Description
- Response
- Name
result- Type
- enum
- Description
- A system-generated high level overall result of the operation.Enum Options:FAILUREPENDINGSUCCESSUNKNOWN
- Name
sourceOfFunds- Type
- object
- Description
- The details describing the source of the funds to be used.
PUT/merchant/{merchantId}/order/{orderid}/transaction/{transactionid}
Capture
Request to capture funds previously reserved by an authorization. A Capture transaction triggers the movement of funds from the payer's account to the merchant's account. Typically, a Capture is linked to the authorization through the orderId - you provide the original orderId, a new transactionId, and the amount you wish to capture. You may provide other fields (such as shipping address) if you want to update their values; however, you must NOT provide sourceOfFunds.
Request Parameters
Required Properties for a simple request.
- Name
apiOperation- Type
- string Required
- Description
- CAPTURE
- Name
order- Type
- object Required
- Description
- Information about the order associated with this transaction.
- Name
sourceOfFunds- Type
- object Required
- Description
- The details describing the source of the funds to be used.
- Name
transaction- Type
- object Required
- Description
- Information about this transaction.
Response Parameters
Required Properties for a simple request.
- Name
browserPayment- Type
- object
- Description
- Information used to manage interactions with the payment provider if you are offering your payment page on a website or are redirecting the payer's browser to the provider's website.
- Name
merchant- Type
- string
- Description
- The unique identifier issued to you by your payment provider.
- Name
order- Type
- object
- Description
- Information about the order associated with this transaction.
- Name
response- Type
- object
- Description
- Response
- Name
result- Type
- enum
- Description
- A system-generated high level overall result of the operation.Enum Options:FAILUREPENDINGSUCCESSUNKNOWN
- Name
transaction- Type
- object
- Description
- Information about this transaction.
PUT/merchant/{merchantId}/order/{orderid}/transaction/{transactionid}
Disbursement
Use this operation to pay out funds to a payer, for example when you want to disburse gaming winnings or pay a payer's credit card bill.
Request Parameters
Required Properties for a simple request.
- Name
apiOperation- Type
- string Required
- Description
- DISBURSEMENT
- Name
disbursementType- Type
- enum Required
- Description
- The type of disbursement used for this transaction.Enum Options:CREDIT_CARD_BILL_PAYMENTGAMING_WINNINGS
- Name
order- Type
- object Required
- Description
- Information about the order associated with this transaction.
- Name
sourceOfFunds- Type
- object Required
- Description
- The details describing the source of the funds to be used.
Response Parameters
Required Properties for a simple request.
- Name
browserPayment- Type
- object
- Description
- Information used to manage interactions with the payment provider if you are offering your payment page on a website or are redirecting the payer's browser to the provider's website.
- Name
merchant- Type
- string
- Description
- The unique identifier issued to you by your payment provider.
- Name
order- Type
- object
- Description
- Information about the order associated with this transaction.
- Name
response- Type
- object
- Description
- Response
- Name
result- Type
- enum
- Description
- A system-generated high level overall result of the operation.Enum Options:FAILUREPENDINGSUCCESSUNKNOWN
- Name
transaction- Type
- object
- Description
- Information about this transaction.
PUT/merchant/{merchantId}/order/{orderid}/transaction/{transactionid}
Pay
A single transaction to authorise the payment and transfer funds from the payer's account to your account.
Request Parameters
Required Properties for a simple request.
- Name
apiOperation- Type
- string Required
- Description
- PAY
- Name
order- Type
- object Required
- Description
- Information about the order associated with this transaction.
- Name
sourceOfFunds- Type
- object Required
- Description
- The details describing the source of the funds to be used.
- Name
transaction- Type
- object Required
- Description
- Information about this transaction.
Response Parameters
Required Properties for a simple request.
- Name
browserPayment- Type
- object
- Description
- Information used to manage interactions with the payment provider if you are offering your payment page on a website or are redirecting the payer's browser to the provider's website.
- Name
merchant- Type
- string
- Description
- The unique identifier issued to you by your payment provider.
- Name
order- Type
- object
- Description
- Information about the order associated with this transaction.
- Name
response- Type
- object
- Description
- Response
- Name
result- Type
- enum
- Description
- A system-generated high level overall result of the operation.Enum Options:FAILUREPENDINGSUCCESSUNKNOWN
- Name
transaction- Type
- object
- Description
- Information about this transaction.
PUT/merchant/{merchantId}/order/{orderid}/transaction/{transactionid}
Referral
Request to resubmit a referred initial transaction (Authorization or Pay transaction that received a Refer_to_Issuer acquirer response) as a new Authorization or Pay transaction with an authorization code obtained from the issuer.
Request Parameters
Required Properties for a simple request.
- Name
apiOperation- Type
- string Required
- Description
- REFERRAL
- Name
transaction- Type
- object Required
- Description
- Information about this transaction.
Response Parameters
Required Properties for a simple request.
- Name
browserPayment- Type
- object
- Description
- Information used to manage interactions with the payment provider if you are offering your payment page on a website or are redirecting the payer's browser to the provider's website.
- Name
merchant- Type
- string
- Description
- The unique identifier issued to you by your payment provider.
- Name
order- Type
- object
- Description
- Information about the order associated with this transaction.
- Name
response- Type
- object
- Description
- Response
- Name
result- Type
- enum
- Description
- A system-generated high level overall result of the operation.Enum Options:FAILUREPENDINGSUCCESSUNKNOWN
- Name
transaction- Type
- object
- Description
- Information about this transaction.
PUT/merchant/{merchantId}/order/{orderid}/transaction/{transactionid}
Refund
Request to refund previously captured funds to the payer. Typically, a Refund is linked to the Capture or Pay through the orderId - you provide the original orderId, a new transactionId, and the amount you wish to refund. You may provide other fields if you want to update their values; however, you must NOT provide sourceOfFunds.
Request Parameters
Required Properties for a simple request.
- Name
apiOperation- Type
- string Required
- Description
- REFUND
- Name
order- Type
- object Required
- Description
- Information about the order associated with this transaction.
- Name
transaction- Type
- object Required
- Description
- Information about this transaction.
Response Parameters
Required Properties for a simple request.
- Name
browserPayment- Type
- object
- Description
- Information used to manage interactions with the payment provider if you are offering your payment page on a website or are redirecting the payer's browser to the provider's website.
- Name
merchant- Type
- string
- Description
- The unique identifier issued to you by your payment provider.
- Name
order- Type
- object
- Description
- Information about the order associated with this transaction.
- Name
response- Type
- object
- Description
- Response
- Name
result- Type
- enum
- Description
- A system-generated high level overall result of the operation.Enum Options:FAILUREPENDINGSUCCESSUNKNOWN
- Name
transaction- Type
- object
- Description
- Information about this transaction.
GET/merchant/{merchantId}/order/{orderid}
Retrieve Order
Request to retrieve the details of an order and all transactions associated with this order.
Request Parameters
All the properties that exist for this request.
- Name
correlationId- Type
- string
- Description
- A transient identifier for the request, that can be used to match the response to the request.
- Name
responseControls- Type
- object
- Description
- Container for fields that control the response returned for the request.
Response Parameters
Required Properties for a simple request.
- Name
amount- Type
- double
- Description
- The total amount for the order. This is the net amount plus any merchant charge amounts.If you provide any sub-total amounts, then the sum of these amounts (order.itemAmount, order.taxAmount, order.shippingAndHandlingAmount, order.cashbackAmount, order.gratuityAmount, order.merchantCharge.amount and order.dutyAmount), minus the order.discountAmount must equal the net amount.
- Name
creationTime- Type
- date
- Description
- Indicates the date and time the gateway considers the order to have been created.
- Name
currency- Type
- string
- Description
- The currency of the order expressed as an ISO 4217 alpha code, e.g. USD.
- Name
id- Type
- string
- Description
- A unique identifier for this order to distinguish it from any other order you create.
- Name
lastUpdatedTime- Type
- date
- Description
- Indicates the date and time the gateway considers the order to have last been updated.
- Name
merchant- Type
- string
- Description
- The unique identifier issued to you by your payment provider.
- Name
merchantAmount- Type
- double
- Description
- The total amount for the order in order.merchantCurrency units.
- Name
merchantCurrency- Type
- string
- Description
- The currency in which you priced your inventory for this order, expressed as an ISO 4217 alpha code, e.g. USD.
- Name
result- Type
- enum
- Description
- A system-generated high level overall result of the operation.Enum Options:FAILUREPENDINGSUCCESSUNKNOWN
- Name
totalAuthorizedAmount- Type
- double
- Description
- The amount that has been successfully authorized for this order.
- Name
totalCapturedAmount- Type
- double
- Description
- The amount that has been successfully captured for this order.
- Name
totalDisbursedAmount- Type
- double
- Description
- The amount that has been successfully disbursed for this order.
- Name
totalRefundedAmount- Type
- double
- Description
- The amount that has been successfully refunded for this order.
GET/merchant/{merchantId}/order/{orderid}/transaction/{transactionid}
Retrieve Transaction
Request to retrieve the details of a transaction. For example you can retrieve the details of an authorization that you previously executed.
Request Parameters
All the properties that exist for this request.
- Name
correlationId- Type
- string
- Description
- A transient identifier for the request, that can be used to match the response to the request.
- Name
responseControls- Type
- object
- Description
- Container for fields that control the response returned for the request.
Response Parameters
Required Properties for a simple request.
- Name
browserPayment- Type
- object
- Description
- Information used to manage interactions with the payment provider if you are offering your payment page on a website or are redirecting the payer's browser to the provider's website.
- Name
merchant- Type
- string
- Description
- The unique identifier issued to you by your payment provider.
- Name
order- Type
- object
- Description
- Information about the order associated with this transaction.
- Name
response- Type
- object
- Description
- Response
- Name
result- Type
- enum
- Description
- A system-generated high level overall result of the operation.Enum Options:FAILUREPENDINGSUCCESSUNKNOWN
- Name
transaction- Type
- object
- Description
- Information about this transaction.
PUT/merchant/{merchantId}/order/{orderid}/transaction/{transactionid}
Update Authorization
Request to update an existing authorization. If successful, this operation allows you to extend the authorization period and/or update the authorized amount for this order.
Request Parameters
Required Properties for a simple request.
- Name
apiOperation- Type
- string Required
- Description
- UPDATE_AUTHORIZATION
- Name
transaction- Type
- object Required
- Description
- Information about this transaction.
Response Parameters
Required Properties for a simple request.
- Name
browserPayment- Type
- object
- Description
- Information used to manage interactions with the payment provider if you are offering your payment page on a website or are redirecting the payer's browser to the provider's website.
- Name
merchant- Type
- string
- Description
- The unique identifier issued to you by your payment provider.
- Name
order- Type
- object
- Description
- Information about the order associated with this transaction.
- Name
response- Type
- object
- Description
- Response
- Name
result- Type
- enum
- Description
- A system-generated high level overall result of the operation.Enum Options:FAILUREPENDINGSUCCESSUNKNOWN
- Name
transaction- Type
- object
- Description
- Information about this transaction.
PUT/merchant/{merchantId}/order/{orderid}/transaction/{transactionid}
Verify
Request to verify the cardholder's account before processing the financial transaction. The card is verified using the verification method supported by the acquirer and the data provided in the request.
Request Parameters
Required Properties for a simple request.
- Name
apiOperation- Type
- string Required
- Description
- VERIFY
- Name
order- Type
- object Required
- Description
- Information about the order associated with this transaction.
- Name
sourceOfFunds- Type
- object Required
- Description
- The details describing the source of the funds to be used.
- Name
transaction- Type
- object Required
- Description
- Information about this transaction.
Response Parameters
Required Properties for a simple request.
- Name
browserPayment- Type
- object
- Description
- Information used to manage interactions with the payment provider if you are offering your payment page on a website or are redirecting the payer's browser to the provider's website.
- Name
merchant- Type
- string
- Description
- The unique identifier issued to you by your payment provider.
- Name
order- Type
- object
- Description
- Information about the order associated with this transaction.
- Name
response- Type
- object
- Description
- Response
- Name
result- Type
- enum
- Description
- A system-generated high level overall result of the operation.Enum Options:FAILUREPENDINGSUCCESSUNKNOWN
- Name
transaction- Type
- object
- Description
- Information about this transaction.
PUT/merchant/{merchantId}/order/{orderid}/transaction/{transactionid}
Void
Request to void a previous transaction. A void will reverse a previous transaction. Typically voids will only be successful when processed not long after the original transaction.
Request Parameters
Required Properties for a simple request.
- Name
apiOperation- Type
- string Required
- Description
- VOID
- Name
transaction- Type
- object Required
- Description
- Information about this transaction.
Response Parameters
Required Properties for a simple request.
- Name
browserPayment- Type
- object
- Description
- Information used to manage interactions with the payment provider if you are offering your payment page on a website or are redirecting the payer's browser to the provider's website.
- Name
merchant- Type
- string
- Description
- The unique identifier issued to you by your payment provider.
- Name
order- Type
- object
- Description
- Information about the order associated with this transaction.
- Name
response- Type
- object
- Description
- Response
- Name
result- Type
- enum
- Description
- A system-generated high level overall result of the operation.Enum Options:FAILUREPENDINGSUCCESSUNKNOWN
- Name
transaction- Type
- object
- Description
- Information about this transaction.