Subsequent Operations
When using the Hosted Session integration method, the payment process for a new order starts with an initial transaction, most often a PAY or AUTHORIZE transaction. For a full list of available initial transactions, see Transactions.
The initial transaction defines all important information for the order, it includes:
- Details about the order itself, such as, ID, amount, and currency.
- Payment method to be used for the payment.
- Payment details of the payer.
If you are using a PAY transaction and the payer receives the goods they ordered and is happy with them, the order is complete and no other actions are needed. However, in many scenarios subsequent transactions can be needed to handle the remaining lifecycle of the order.
Subsequent scenarios
The following scenarios are examples of situations where you need to send subsequent transactions for your existing order:
- If you use a
VERIFYtransaction, often created with the order amount set to zero, as the initial transaction to verify the payer's account details, you need to follow up with aPAYorAUTHORIZEtransaction to define the correct order amount and initiate the money transfer. - If you use an
AUTHORIZEtransaction as the initial transaction, you need to follow up with aCAPTUREtransaction, when you are ready to ship the goods and want the money to exchange hands. If there is a delay in your ability to ship the goods, you may also need to use theUPDATE AUTHORIZATIONtransaction to keep the authorization active until you are ready to capture it. - If the order is cancelled for any reason, you need to use the
VOIDtransaction to immediately cancel it with the gateway as well. If the payment details have already been sent to the bank, you need to use theVOIDtransaction to immediately cancel it with the gateway as well. If the payment details have already been sent to the bank, you need to use theREFUNDtransaction, which is also needed if the payer is not happy with their purchase and wants to return it. In the rare event that the transaction fails because the acquirer requires further authorization, you can use aREFUNDtransaction, which is also needed if the payer is not happy with their purchase and wants to return it. In the rare event that the transaction fails because the acquirer requires further authorization, you can use aREFERRALtransaction to retry the payment operation with the necessary additional details.
The RETRIEVE TRANSACTION and RETRIEVE ORDER API operations can also be considered subsequent transactions, though they are used only to retrieve details of an existing order, and do not impact the order lifecycle. For a list of all available subsequent transactions, see Transactions.
Linking to initial transaction
All the transactions related to the same order must be linked so that the various payment systems like the ANZ eGate payment gateway and banks can identify them as belonging together.
The linking is done by using the same order ID in every transaction related to the order. The order ID is provided as a path parameter in the request URL.
Shared data in subsequent transactions
Linking different transactions together within the same order means that you only need to provide specific data about the order once. The gateway stores the details for the order and can use them as needed, when processing any subsequent transactions.
In any subsequent transaction, you only need to provide the data specific to that transaction. For example:
- In a
CAPTUREtransaction, provide the amount and currency for the goods you are shipping at that point, which may be the full or partial order amount. - In a
REFUNDtransaction, provide the amount and currency for the refund you are sending, which may be the full or partial order amount. - In a
VOIDtransaction, provide the transaction ID of the exact transaction you want to cancel. - In a
REFERRALtransaction, provide the authorization code that allows the issuer to approve the previously failed transaction.
If you provide identical information in multiple transactions within an order, the gateway ignores it. If you update any information in a subsequent transaction, the gateway updates the order details accordingly. For example, you have first provided a shipping address in the initial AUTHORIZE transaction, and the payer moves. You can then add a new shipping address to the CAPTURE transaction.