Transaction Operations

If you are integrated to the gateway via DirectAPI, you can use DirectAPI 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.

The functionality available to you is limited to the capability of the acquirer(s) configured on your gateway merchant profile. Where a functionality is not supported for the acquirer on the gateway, any operation requests to execute that functionality will be rejected by the gateway for that acquirer.
Payment details in transaction requests, where supported, may be provided through multiple sources. See Multiple Sources of Payment Details.

Initial Transaction Operations

This section describes the operations you can use to initiate a transaction.

Authorize

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

For some browser payments, you can initiate an Authorize operation using the Initiate Browser Payment operation. For more information, see Implementing a Browser Payment Integration.

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 Expiry

Authorizations have a validity period after which they expire. The authorization validity period (in milliseconds) 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:

  • reject any Capture requests against the order
  • 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 "Enable Automatic Authorization Reversals" 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.

Authorization Update

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.

FAQs

What if I want to capture my Authorization in part only?

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.

It’s recommended that you integrate to DirectAPI v50 or later to void authorizations of partially captured orders.

You can provide the expected number of Captures for the order in the field order.expectedNumberOfCaptures in the Capture request or the via the Merchant Administration UI. 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.

The field order.expectedNumberOfCaptures can only be submitted from version 44 of DirectAPI.
What if I no longer want to capture my Authorization?

You can void your Authorization by submitting a VOID request with the transaction ID for the Authorization to be voided in field transaction.targetTransactionId.

What if I need to capture more than I have authorized?

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

Can I capture an Authorization that I have performed outside of the gateway?

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

Pay

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

For some browser payments, for example, PayPal, Giropay, Sofortbanking, etc, you can initiate a Pay operation using the Initiate Browser Payment operation. For more information, see Implementing a Browser Payment Integration.

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 CommWeb 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.
Auto-Capture may also be performed on a referred Authorize transaction, by providing the manual authorization code.
Verify

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]

Standalone Capture

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.

The Authorization Code is optional for transactions with transaction source "CARD_PRESENT". This allows for Standalone Capture to be performed on card present payments authorized offline.

Standalone Capture API Reference [REST][NVP]

Standalone Refund

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]

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.

Subsequent operations are supported through Direct Payment or Batch integration models.
Update Authorization

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.
For Mastercard transactions, increasing the authorization amount automatically extends the authorization validity period.

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.

Automatic approval of Update Authorization requests by the gateway (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.itemAmount
  • order.shippingAndHandlingAmount
  • order.taxAmount
  • order.discount.amount (card payments only)
  • order.gratuityAmount (card payments only)
Providing 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).
For PayPal payments, providing 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.

Update Authorization API Reference [REST][NVP]

Capture

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.

From DirectAPI v15 onwards, if you want to capture funds against a successful authorization performed using the gateway then do NOT provide card details in your Capture request.

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

Excessive Capture

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.

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.

Capture API Reference [REST][NVP]

Refund

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.

From DirectAPI v15 onwards, if you want to refund against a successful Capture or Pay performed using the gateway, then do NOT provide card details in your Refund request.
Excessive Refund

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 DirectAPI 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 DirectAPI for an order where the total captured amount is $100 USD and you have set the excessive refund limit for DirectAPI transactions as $20 USD then you can refund up to $120 USD.

This feature is available for orders performed through both Merchant Administration and the DirectAPI. For refunds submitted via Merchant Administration, the excess permitted for the order is checked against the refund limit set for the operator in the Operator Settings in Merchant Administration.

Refund API Reference [REST][NVP]

Retrieve Transaction

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

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

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]

Referral

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]

Chargeback

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.

If you share your SE Number/Bank merchant ID (the identifier allocated to you by your acquiring bank) across multiple gateway profiles, then a standalone chargeback transaction will be created for each profile.

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_PROCESSED or DISPUTED: 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=DISPUTED indicates that a dispute has been raised but no funds have been moved yet.
    • order.status=CHARGEBACK_PROCESSED indicates that a chargeback claim has been processed and funds will be moved either from or to the merchant account.
  • order.chargeback.amount
  • order.chargeback.currency
  • transaction.dispute parameter group: Information about the chargeback dispute, for example dispute event, date, etc.
  • transaction.type=CHARGEBACK
  • transaction.source=SERVICE_PROVIDER
  • gatewayEntryPoint=SERVICE_PROVIDER_API
The gateway records the chargeback transactions for information purposes only — the transaction is not sent for downstream processing to the acquirer.

Chargeback Transaction API Reference[REST][NVP]

Copyright © 2020 Commonwealth Bank of Australia