Transaction Operations

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.targetTransactionId field.
• Provide the expected number of Captures for the order in the order.expectedNumberOfCaptures in 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 provide order.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, update order.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., update order.expectedNumberOfCaptures=3 in the second Capture request then the gateway will not reverse the outstanding amount until upon receiving the third Capture request.

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

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".

Pay API Reference [REST][NVP]

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 Payment 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.

Verify API Reference [REST][NVP]

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.

Standalone Refund API Reference [REST][NVP]

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.

Disbursement API Reference [REST][NVP]

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.

Order Subtotals

You can provide the following subtotal amounts in the Update Authorization request for card or PayPal payments:

• order.itemAmount
• order.shippingAndHandlingAmount
• order.taxAmount
• order.discount.amount (card payments only)
• order.gratuityAmount (card payments only)

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).

Update Authorization API Reference [REST][NVP]

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".

If you want to partially capture an authorization, and for other related information, see FAQs.

Capture API Reference [REST][NVP]

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.

Refund API Reference [REST][NVP]

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.

Disbursement API Reference [REST][NVP]

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 Transaction API Reference [REST][NVP]

Retrieve Order allows you to retrieve details of an order and all the transactions associated with this order.

Retrieve Order API Reference [REST][NVP]

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.

Void API Reference [REST][NVP]

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.

Referral Transaction API Reference[REST][NVP]