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
VERIFY
transaction, 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 aPAY
orAUTHORIZE
transaction to define the correct order amount and initiate the money transfer. - If you use an
AUTHORIZE
transaction as the initial transaction, you need to follow up with aCAPTURE
transaction, 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 AUTHORIZATION
transaction 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
VOID
transaction to immediately cancel it with the gateway as well. If the payment details have already been sent to the bank, you need to use theVOID
transaction to immediately cancel it with the gateway as well. If the payment details have already been sent to the bank, you need to use theREFUND
transaction, 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 aREFUND
transaction, 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 aREFERRAL
transaction 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 Mastercard 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
CAPTURE
transaction, 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
REFUND
transaction, provide the amount and currency for the refund you are sending, which may be the full or partial order amount. - In a
VOID
transaction, provide the transaction ID of the exact transaction you want to cancel. - In a
REFERRAL
transaction, 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.