Orders
An order is used to link all the transactions that relate to one instance of a sale between you and your payer. It is intended to represent the classical paper "order" concept, where you sell a bill of goods to your customers. As such it has all the typical order data such as, the line items for the goods that were bought, who paid for them and how, where they are to be shipped, and most importantly, the amount paid.
Transactions in an order
An order can contain one or more transactions. Some orders have just one transaction, a pay transaction, also known as purchase transaction, where the goods are paid in full and dispatched straight away.
Others have two main transactions, an authorization transaction that checks that the payer's bank account has enough money and reserves the money, and then a capture transaction, that moves the money from the payer’s account to yours. The authorize or capture model is usually used when you cannot guarantee that the goods can be dispatched at the time they were requested by the payer. At times, you may need to refund some or all of the order money, or maybe deliver the goods in several partial deliveries. All those movements of money represent transactions against one order, and the order is the entity that links the transactions together into one instance of a sale.
The following example describes the order status lifecycle related to a common card transaction flow:
- If you use 3D Secure (3DS) authentication with card payments, you first use various authentication operations to confirm that the payer is who they say they are.
After a successful authentication, the order status is
AUTHENTICATED. - Use the
AUTHORIZEtransaction where the payer gives you their permission to charge them. The order status changes toAUTHORIZEDafter the issuer confirms a successful authorization. - When you are ready to ship the order, you send the
CAPTUREtransaction that initiates the money transfer process. If you ship in multiple parts, you can perform multiple partial captures, as needed. The order status will change to CAPTURED, when the entire authorized amount has been captured. If you have performed a partial capture and there is outstanding authorized amount left in the order, the order status becomesPARTIALLY_CAPTURED. - If the payer returns the product, you can perform one full or one or more partial refunds, as needed. The order status changes to REFUNDED or PARTIALLY_REFUNDED, depending on the captured amount available to refund.
Non card payments may follow slightly different flows depending on the payment method. Their specific flow is documented within the integration guide for that payment method.
When you use Mastercard Gateway for processing orders, you can provide all the information about the order in the initial transaction. For example, details such as billing, shipping, payment, and the full amount.
In subsequent transactions related to the same order, you need not repeat the general order data and can just reference the original order. For example, in a refund transaction you can simply provide the order ID and the amount that you want to refund, and the gateway uses the initial transaction to gather all the details that the bank needs to transfer the money.