Subsequent Operations
When using the Direct Payment 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 the important information for the order:
- 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 as the initial transaction to verify the payer's account details, you need to follow up with a PAY or AUTHORIZE 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 a CAPTURE transaction, when you are ready to ship the goods or provide the service and want the money to exchange hands. If there is a delay in your ability to ship the goods or provide the service, you may also need to use the UPDATE 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 the REFUND 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 a REFERRAL transaction to retry the payment operation with the necessary additional details. The RETRIEVE TRANSACTION and RETRIEVE ORDER API operations can also be considered subsequent API operations, 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 API operations, see Operations. For a list of all available 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, you need to provide a minimum of, amount and currency for the goods you are shipping at that point, which may be the full or partial order amount. If you include additional data, for example, airline data or level 1/level 2 data, you need to submit additional data. For more information, please see the Supplementary Data section.
- In a REFUND transaction, you need to provide the amount and currency for the refund you are sending, which may be the full or partial order amount.
- In a VOID transaction, you need to provide the transaction ID of the exact transaction you want to cancel.
- In a REFERRAL transaction, you need to provide the authorization code that allows the issuer to approve the previously failed transaction.