Transaction Operations
If you are integrated to the gateway via API, you can use API operations to process transactions, retrieve transaction details, store card details, etc. To perform an operation, you must have the requisite privilege on your merchant profile with the gateway. To check which operations are available for you to use, contact your payment service provider.
Initial transaction operations
This section describes the operations you can use to initiate a transaction.
The Authorize operation verifies your payer's card details, checks that your payer has sufficient funds available against their line of credit, and attempts to reserve the requested funds. The payer's credit limit is reduced by the authorized amount, and the funds are reserved for a period of time (in most cases 5-8 days), as determined by the card scheme and the payer's card issuing rules.
The authorization does not debit funds from your payer's account, but reserves the total order amount, ready for the Capture operation to debit the card and transfer the funds to your account. Authorize transactions do not appear on the payer's account statement as opposed to Capture transactions.
For a successful authorization, the gateway returns result=SUCCESS in the transaction response. You can perform Authorize as a subsequent operation only if the initial transaction is a Verify, and the card details in the Authorize request and the Verify transaction match.
Authorize is also known as "Auth", "Authorization".
Order Certainty
You can indicate a certainty level on the authorization amount that will be captured by providing the order.certainty field in the Authorize request. To do this, you must have the "Change Order Certainty" privilege enabled on your merchant profile by your payment service provider. You can set the field to either of the following values:
- FINAL: The full authorized amount is expected to be captured with one or more captures within the mandated time (typically 7 days). The order will only be cancelled in exceptional circumstances (for example, the payer cancelled their purchase). Providing this value on your transaction may qualify the transaction for lower processing fees.
- ESTIMATED: The amount authorized is an estimate of the amount that will be captured within the mandated time (typically 30-31 days). It is possible that the amount captured will be less or not be captured at all, or the authorization may be cancelled. Providing this value on your transaction may cost you higher processing fees.
The request is rejected where you do not have the privilege to change the order certainty and the value you provide in this field does not match the default order certainty value configured on your merchant profile.
Authorize API Reference [REST][NVP]
Authorization Reversals
The gateway can reverse outstanding authorization amounts for uncaptured, partially captured, or expired authorizations, where supported for the acquirer. This allows you to comply with the card scheme requirements for full and partial reversals.
Uncaptured Authorizations
If you do not wish to capture the authorized amount after submitting an Authorize request, you must void your authorization by submitting a VOID request. Provide the transaction ID for the authorization to be voided in the transaction.targetTransactionId field.
Partially Captured Authorizations
When submitting a Capture request for an order you can provide a Capture amount lower than the Authorized amount for the order (order.AuthorizedAmount). If you do not intend to capture the remaining authorized amount you may void the outstanding authorized amount, where supported for the acquirer.
You can attempt to void/reverse the outstanding authorization amount using two ways:
- Submit a VOID request with the transaction ID for the Authorization to be voided in the
transaction.targetTransactionIdfield. - Provide the expected number of Captures for the order in the
order.expectedNumberOfCapturesin the Capture request or via Merchant Administration. In the event that the total number of Captures for the order (including the current Capture) exceeds or equals the total expected number of Capture requests, the gateway will automatically trigger a void of the outstanding authorized amount, where this is supported for the acquirer. To allow this, you must have the "Automatically Reverse Outstanding Authorization Amounts" privilege enabled on your merchant profile by your payment service provider.
For example, if you provideorder.expectedNumberOfCaptures=2 in the first Capture request then the gateway automatically reverses the remaining authorized amount upon processing the second Capture request.
If you decrease the expected number of captures in the subsequent Capture requests, i.e, updateorder.expectedNumberOfCaptures=1 in the second Capture request then the gateway automatically reverses the remaining authorized amount upon processing the second Capture request. This is because 2 (the total number of Captures for the order, including the current Capture) exceeds 1 (the expected number of Captures). However, if you increase the expected number of Captures in subsequent Capture requests, i.e., updateorder.expectedNumberOfCaptures=3 in the second Capture request then the gateway will not reverse the outstanding amount until upon receiving the third Capture request.
order.expectedNumberOfCaptures can only be submitted from version 44 of API.Expired Authorizations
Authorizations have a validity period after which they expire. The authorization validity period can be configured in the gateway for an acquirer, card type, and order certainty combination.
When you submit an Authorize request to the gateway, the gateway determines the authorization expiry date and time based on the configured authorization validity period (using card type, acquirer, order certainty combination). Where supported for the acquirer, the authorization expiry is returned in the authorizationResponse.autoExpiry field in the Retrieve Transaction operation response. This field contains the date and time the gateway will automatically expire the authorization.
Once the authorization validity period expires, the gateway will:
- automatically attempt to void the authorization and release funds back to the payer (where supported for the acquirer). To allow this, you must have the "Automatically Reverse Expired Authorizations" privilege enabled on your merchant profile by your payment service provider.
If the order has already been partially captured, and if your acquirer supports voiding authorizations for partial captures, the gateway will attempt to void/reverse the outstanding authorization amount.
- reject any Capture requests against the order
Authorization Updates
The gateway allows you to extend the authorization period and optionally increase or decrease the authorization amount for valid authorizations where supported for the acquirer. To do this, you must have the "Update Authorization" privilege enabled on your merchant profile by your payment service provider. For more information, see Update Authorization.
Authorization Deferrals
The gateway allows you to defer an authorization if you are unable to submit an Authorize or Pay transaction at the time it was completed with the payer. The failure may be due to connectivity or system issues, or other limitations that require you to defer the submission until the system was back online. Identifying deferred authorizations is mandatory to comply with Visa scheme requirements.
Listed below are some scenarios where you must indicate the authorization as a deferred authorization for Visa card payments:
- If you are a merchant accepting card-present payments on a POS terminal where the POS authorization system is offline then the authorization that you submit downstream when the system is back online must be marked as deferred.
- If you are a retail merchant accepting payment via telephone orders where the POS authorization system is offline then the authorization that you submit downstream when the system is back online must be marked as deferred.
To defer an authorization, provide the transaction.deferredAuthorization field in the Authorize, Pay or Standalone Capture request and set its value to TRUE. If you do not provide this field, the default value will be set to FALSE.
For transit merchants, the authorization that you submit for the aggregated amount at the end of the travel period for all payments within a travel period must be marked as deferred. For more information, see Aggregated Transit Fare Payments.
FAQs
To capture more than the authorized amount for an order, your merchant profile on the gateway must be enabled for the Excessive Capture privilege. See Excessive Captures
Yes, this is called a Standalone Capture request and where supported for the acquirer you can simply submit a Capture request with the Authorization Code as returned by your acquirer (in the authorization response).
The Pay operation effectively combines an Authorize and a Capture into one message. A single transaction authorizes the payment and transfers funds from your payer's account into your account.
If you want to submit Pay as a subsequent operation, you must have a successful verification transaction, and the card details in the Pay request and the Verify transaction must match.
The order certainty level for a Pay transaction is set to FINAL. For more information, see Order Certainty.
Pay is also known as "Sale", "Purchase".
Initiate Browser Payment operation. For more information, see Implementing a Browser Payment Integration.Auto Capture
Auto-capture is a variant of the Pay operation that allows a merchant with a privilege to perform a Pay transaction and using an acquirer that only supports Authorize/Capture transactions to perform an Authorize followed by an auto-triggered Capture. With this transaction type, a Pay request is transformed into Authorize and Capture operations.
This operation may be performed using the Direct Payment, Hosted Session, or Batch integration models.
The transaction identifier for both Authorize and Capture requests will be the transaction identifier supplied by you in the original Pay request. In the Pay response, the transaction.type field will indicate the last transaction attempted to fulfill the request, i.e. Authorize or Capture.
You may use the Retrieve operation to retrieve the results of an Auto-capture operation. The results of the last transaction attempted to fulfill the request are returned.
You may void an auto-captured Pay transaction using the Void Pay operation. When you perform this operation, the Mastercard Gateway:
- attempts a "Void Capture" for the Capture transaction.
- if the "Void Capture" is successful, then a "Void Authorization" is attempted for the Authorization. If the "Void Capture" is unsuccessful, then the response indicates that the void failed; and Void Authorization is not attempted.
Authorization Deferrals
You can provide an indicator in the Pay request to defer the authorization. For more information, see Authorization Deferrals.
The Verify operation allows you to verify the payer's account details before performing a Pay or an Authorize transaction. It verifies the payment details using the verification method supported by the acquirer. For example, if the acquirer supports Address Verification Service (AVS), then Verify sends an AVS Only transaction with the transaction amount of zero and the address details of the payer.
A Standalone Capture transaction is a Capture transaction where the authorization was performed externally to the gateway. When submitting a Standalone Capture to the gateway, you must provide the externally generated Authorization Code in the transaction.authorizationCode field, and the other mandatory fields.
You can submit Standalone Captures if you have the Capture privilege enabled on your merchant profile.
Standalone Capture API Reference [REST][NVP]
Authorization Deferrals
You can provide an indicator in the Standalone Capture request to defer the authorization. For more information, see Authorization Deferrals.
A Standalone Refund transaction is a Refund transaction that allows you to transfer funds from your account back to the payer without a previous purchase. Standalone refunds may be performed when you wish to credit the payer's account without associating the credit to a previous transaction.
The Disbursement operation allows you to send funds to a payer's card account when required, e.g. for gaming or betting winnings or when paying towards a payer's credit card bill. When performing a Disbursement, the payer's billing and shipping details are not required and Card Security Code (CSC) validation is not applicable. A Disbursement may be performed without prior transactions or after Verifying the payer's account details.
Subsequent operations
This section describes operations you can perform on the initial transactions, Authorize or Pay.
To check which operations are configured on your merchant profile, contact your payment service provider.
The Update Authorization operation allows you to:
- Extend the validity period of an existing authorization
- Optionally increase or decrease the authorization amount
If you only want to extend the authorization period, do not submit transaction.amount in the request. The updated authorization expiry date and time is returned in the authorizationResponse.autoExpiry field in the Retrieve Transaction response. It's recommended that you submit the Update Authorization request within the validity period of the original authorization.
If you provide a transaction amount that is greater than the amount of the existing authorization, the authorization amount is updated to the new amount. For example, if the existing authorization amount is 100 USD, and you provide 120 USD as the transaction amount in the Update Authorization request then the new authorization amount available for capture will be 120 USD.
If you provide a transaction amount that is less than the amount of the existing authorization, the authorization amount is updated to the new amount. For example, if the existing authorization amount is 100 USD, and you provide 80 USD as the transaction amount in the Update Authorization request then the new authorization amount available for capture will be 80 USD. The gateway automatically processes a reversal request for the remaining authorization amount of 20 USD (where supported for the acquirer).
Note that the gateway can update an existing authorization only if the following conditions are met:
- Your merchant profile on the gateway must be enabled for the "Update Authorization" privilege by your payment service provider.
- The order currency must match the currency on the existing authorization.
- The existing authorization must be valid, successful, and fully approved.
Order Totals
After a successful Update Authorization request (for a card or PayPal), the order amount (order.amount) and the total authorized amount(order.totalAuthorizedAmount) are updated to the transaction amount (transaction.amount) of the Update Authorization transaction. This applies regardless of whether the Update Authorization transaction was submitted to the acquirer or automatically approved by the gateway (response.gatewayCode=APPROVED_AUTO). However, if you choose to bypass the authorization update for an excessive Capture request (by submitting transaction.authorizationAdjustmentActions=NO_ACTION, see Excessive Captures) and the gateway submits an excessive Capture to the acquirer, the order totals are NOT updated.
response.gatewayCode=APPROVED_AUTO) is only applicable when the provided amount is greater than the amount of the existing authorization. Order Subtotals
You can provide the following subtotal amounts in the Update Authorization request for card or PayPal payments:
order.itemAmountorder.shippingAndHandlingAmountorder.taxAmountorder.discount.amount(card payments only)order.gratuityAmount(card payments only)
order.cashbackAmount in the Update Authorization request is not supported.The gateway does NOT validate if the subtotal amounts add up to the transaction.amount(i.e.,order.amount); however, you must ensure this for PayPal payments.
Surcharging
You can update a surcharge amount in the Update Authorization request using either of the following fields:
order.surchargeAmount: Use this field if you are providing a pre-calculated surcharge amount.order.netAmount: Use this field if the gateway calculates the surcharge amount (based on your surcharging rules).
order.surchargeAmount is not supported and requests with this field will be rejected. If you provide order.netAmount on a PayPal payment, the transaction will be processed without a surcharge being applied.The Capture operation uses the authorization obtained after the initial Authorize operation to transfer funds from the payer's account to your account. A Capture should always be preceded by a successful authorization, and at a minimum the authorization ID must be sent with the Capture request. The currency used when capturing an amount must match the currency used in the authorization transaction.
Captures are normally batched by the gateway or by the acquirer's host, so the funds aren't effectively transferred until the batch is closed and the settlement occurs.
Capture is also known as "Bill", "Complete".
The total amount you capture can exceed the original authorized amount if excessive capture privilege is enabled on your merchant profile.
Excessive capture is a variation of capture where you can perform captures for amounts greater than the authorized amount. The excess permitted is specified as a percentage of the original authorized amount, and is determined by your payment service provider. You can perform only one excessive capture per non-partially captured order if the capture reaches or exceeds the original authorized amount.
When you submit an excessive Capture request, the gateway will automatically attempt to update the authorization amount to the amount you want to capture. If the acquirer supports updating authorizations, the gateway submits the Update Authorization request to the acquirer. If not, the gateway will automatically approve an authorization update (up to the excessive Capture limit configured for your merchant profile).
Submit transaction.authorizationAjustmentAction=NO_ACTION in the Capture request, if you do not want the gateway to attempt to update the authorization before submitting the Capture to the acquirer. Note that where the authorization value does not match the capture the order may not have chargeback protection.
If you want to partially capture an authorization, and for other related information, see FAQs.
Refund allows you to credit funds for an existing order back to the payer's account. Refunds can only be performed where a funds transfer has been completed through either a Pay or a Capture. You can perform any number of refund transactions on the original transaction, but cannot refund more than the total that has been obtained via all purchase or capture transactions associated with the order.
Refunds are performed for many reasons, for example, the return of unwanted, incorrect, or faulty goods.
Refund Authorization
Before submitting your refund request to the acquirer for clearing and settlement, by default, the gateway automatically attempts to authorize your refund with the issuer (where supported by the acquirer). This allows the issuers to verify the card details provided in the refund request to ensure the refund will be successful.
The refund authorization is performed online and returns a response in real time. This has many benefits:
- You get immediate notification from card issuers if the refund will be successful or not. This allows you to take appropriate actions when the issuer responds with a decline. For example, the if card used for refund transaction is no longer valid, the issuer rejects the refund authorization. You can contact the payer to arrange refund through a different payment instrument.
- Card issuer gets immediate notification of the refund request, which allows issuers to instantly display information about the refund to the payer. It also allows them to manage payer queries/complaints effectively.
If you do not want the gateway to submit authorization request for refunds, you must be enabled for "Enable Refunds without Authorizations" privilege. Even when you have this privilege enabled, you can request authorization on refunds by setting the field action.refundAuthorization = true in the Refund API request.
If the refund authorization is successful, the Payment Server proceeds with the refund else the refund is declined. The outcome of the refund transaction is returned in the transaction response. Authorization code received from the issuer will be displayed in Merchant Administration.
Refund of a specific capture
You must select the targeted Capture in the Refund section, and then enter the refund amount. If there are multiple captures then the new UI will display else if there is a single capture the existing UI will display.
During the transition with API, the transaction.targetTransactionld is mandatory only when there are multiple captures.
The total refunded amount for an order can exceed the amount that has been successfully captured for an order if excessive refund privilege is enabled on your merchant profile.
The excess permitted over the captured amount for API transactions can be configured on a per currency basis in the Integration Settings in Merchant Administration. If you do not set an excessive refund limit for a currency, excessive refunds for orders in this currency are rejected.
When submitting a refund, the total refunded amount for the order (inclusive of the attempted refund) must not exceed the total amount captured for the order by more than the maximum excess permitted. For example, if you are submitting an excessive refund via API for an order where the total captured amount is $100 USD and you have set the excessive refund limit for API transactions as $20 USD then you can refund up to $120 USD.
The Disbursement operation allows you to send funds to a payer's card account when required, e.g. for gaming or betting winnings or when paying towards a payer's credit card bill. When performing a Disbursement, the payer's billing and shipping details are not required and Card Security Code (CSC) validation is not applicable. A Disbursement may be performed without prior transactions or after Verifying the payer's account details.
Retrieve Transaction allows you to retrieve details of a transaction using the Order ID and Transaction ID. Both are required as the Transaction ID identifies a transaction within an order.
Retrieve Order allows you to retrieve details of an order and all the transactions associated with this order.
Void attempts to immediately remove/reverse a transaction request. Voids can only be performed on transactions that have not yet been sent to the bank by the acquirer for processing at the end of day. Once a transaction has been sent by the acquirer for processing, you must perform a Refund instead of a Void.
You can void Authorize, Capture, Pay, or Refund transactions. A void performed on an Authorize will immediately release any reserved funds. In all other transaction types, the void will prevent the funds transfer from occurring.
The Referral operation resubmits 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.
The payer may be required to provide additional information in order for the issuer to approve the transaction and provide an authorization code/manual authorization ID.
A chargeback occurs when a payer disputes a payment made to you. For example, the goods were not received, or the payer did not authorize the payment to you. Your payment service provider might choose to import details of chargeback transactions into the gateway so that they are available to you for search and reporting purposes. Your payment service provider may choose to record each chargeback transaction against the original order, or create a new order with a standalone chargeback transaction.
The gateway can create multiple chargeback transactions for a single order. You can perform subsequent transactions on an order containing a chargeback transaction, for example, voids or refunds.
A successfully recorded chargeback transaction will return the following fields in the Retrieve Transaction/Retrieve Order response:
order.status=CHARGEBACK_PROCESSEDorDISPUTED: When a chargeback transaction is created, the status of the corresponding order is updated to represent that there has been a dispute raised by the payer.order.status=DISPUTEDindicates that a dispute has been raised but no funds have been moved yet.order.status=CHARGEBACK_PROCESSEDindicates that a chargeback claim has been processed and funds will be moved either from or to the merchant account.
order.chargeback.amountorder.chargeback.currencytransaction.disputeparameter group: Information about the chargeback dispute, for example dispute event, date, etc.transaction.type=CHARGEBACKtransaction.source=SERVICE_PROVIDERgatewayEntryPoint=SERVICE_PROVIDER_API