Manage cardholder transactions
A transaction is a collection of actions performed with a card. The actions are represented by individual messages such as an authorization, a reversal, a clearing first presentment, and a dispute. These messages define the transaction lifecycle.
During its lifecycle, a transaction will transition through various phases, depending on the actions taken by the cardholder, merchant, issuer, and card scheme. The sequence of these phases collectively defines the transaction's progression from initiation to completion.
Typically, a successful transaction will transition through authorization, clearing, and settlement phases.
In the European Union (EU), transactions are processed using Mastercard’s dual message system, in which:
The merchant first sends an authorization message to instantly verify and hold the funds in the cardholder’s account.
Upon verification, the merchant then sends a clearing message at a later point in time to debit or credit the cardholder.
For example, when a cardholder makes an online purchase:
- The purchase details are sent to the card issuer for approval. This is known as an authorization message.
- After the items are sent out, another message, called the first presentment, is sent to the issuer. This message initiates the clearing phase, where the merchant finalizes the transaction by submitting a capture request.
- The actual transfer of funds happens between the merchant and the cardholder issuer. This is known as the settlement phase.
Information
You can access transactional data using:
Webhooks are typically used to send automated notifications to cardholders or populate data in your system to follow how cards are used.
Webhooks provide an almost real-time, automated method for tracking transactional messages. You'll receive notifications as soon as a message is processed.
For more information, refer to the list of supported webhook event types.
Authorization approved
Presentment received
With the Transaction API, you can view aggregated and granular-level data. It provides events associated with each transaction, and offers search capabilities to retrieve transactions using criteria.
The Transaction API can be used to help with your operational needs. For example, to investigate a transaction or monitor performance.
For the full API specification, see our API reference.
If you've set up webhook notifications, you'll be notified of changes in a transaction's status with a webhook.
Authorization, the initial phase of a transaction, is used to confirm that:
- The card and cardholder are genuine.
- The cardholder has sufficient funds to complete the transaction.
- The specific transaction is not restricted.
Authorization requests are sent from the merchant to the issuer in near real-time, with responses typically being sent back to the merchant within 1 second.
If you’ve enabled the authorization relay service, submitting an authorization request will trigger a relay.
Clearing is also referred to as first presentment. A transaction enters the clearing phase when the merchant submits a capture request to finalize the hold on the funds and post the transaction on the cardholder’s account.
The merchant may choose to only capture a portion of the initial authorization amount in a capture request. This is known as a partial capture. The remainder can be captured in a subsequent capture request, canceled, or will expire if no action is taken.
Clearing messages contain additional information about the transaction. For example, reconciliation amounts, interchange fees, acquirer fees, and cardholder billing amounts. Mastercard uses this information to calculate the final amounts to be settled.
Information
Reconciliation amount is the amount settled with the card scheme, excluding interchange fees or any other fees. This amount is represented in the settlement currency of the issuer.
When clearing is completed, the transaction enters the settlement phase, in which funds are transferred between the merchant and card issuer.
Mastercard runs five daily settlements per week, which Checkout.com consumes and reports back to you. With shared BINs, this is reported on a per-cardholder basis.
A reversal is the process of canceling or updating a previous authorization before it enters the clearing phase. This process can be initiated by either the merchant or the issuer.
The merchant may also choose to only reverse a portion of the initial authorization amount, known as a partial reversal. The remainder can then be captured in a partial capture request from the acquirer and enter clearing.
A refund occurs when a cardholder requests that the merchant returns the funds from a transaction after clearing has been completed.
A refund can either be included within a transaction’s clearing information, or be preceded by a refund authorization request which the issuer can approve or decline.
A chargeback occurs when the issuer disputes a completed transaction on behalf of the cardholder. It can be raised for the full amount that was cleared or partial amount, and is sent to the merchant.
In some cases, the issuer can reverse a chargeback. For example, a cardholder accepts liability for a dispute after a chargeback is initiated but before it is responded to by the acquirer.
The transaction status field in the API response indicates the current phase of the transaction.
| Status | Description |
|---|---|
| At least one authorization is approved, but there has been no movement of money. A transaction can remain in this status for some time, such as until a clearing first presentment is received. |
| A transaction that cannot proceed further from the authorization phase is marked as declined. |
| A transaction moves to this status when a presentment is received, regardless of the amount. |
| A transaction that is fully reversed by the merchant or the issuer is considered canceled. If a transaction has been authorized and is partially reversed by the merchant or acquirer, it will remain in the authorized phase, with the amount updated accordingly. |
| This status indicates that a refund has been cleared, and the funds have been returned to the cardholder’s account. A transaction moves to this status irrespective of the amount that has been refunded (the refund can be full or partial). |
| This status applies to a cleared transaction that is being charged back. A chargeback is initiated during this phase. |
The amounts object in our API provides a detailed breakdown of the financial aspects of a transaction. It aggregates various monetary amounts related to the current transaction.
| Amount type | Description |
|---|---|
| Amount held internally to cover the transaction, but not debited from the account. It represents the difference among the total amount authorized, the sum of the total amount reversed, and the total amount cleared. This value is useful to understand the current liability on the account pending final settlement. |
| Amount authorized for the transaction. It aggregates the billing amounts from all approved authorizations associated with this transaction. This value is useful to track the total amount approved for spending or withdrawal, offering a clear view of the potential financial commitment. |
| Amount reversed by either the merchant or the issuer. It includes the billing amounts from all approved reversals and issuer-initiated reversals tied to this transaction. This value is useful to understand the actual amounts that have moved through the transaction process and have been settled. |
| Amount cleared by the scheme, summing up the billing amounts from all presentments associated with this transaction. This value is useful to understand the actual amounts that have moved through the transaction process and have been settled. |
| Amount refunded to the cardholder. It includes the billing amounts from all presentments of the type This value is useful to track the total refunds processed, offering insight into the amount returned to the cardholder post-transaction. |