Skip to main content

Mastercard

Mastercard cards (debit, credit, prepaid, etc.) are widely accepted in e-commerce and physical environments. Card tokenization and consumer authentication (via the 3-D Secure protocol) improve the consumer experience and security of payments.

FeaturesDetails
MethodCredit/Debit Card, Sync
Merchant countriesAsia-Pacific/Europe
Consumer countriesGlobal
Processing currenciesAll *
Increments✅
Captures✅
Partial/Multiple partial captures✅
Cancels✅
Partial/Multiple partial cancels⚠️ (Only one partial cancel is supported)
Refunds✅
Partial/Multiple partial refunds✅
Recurring✅
Installments-
Credits✅
Disputes✅
Min AmountN/A
Account verification✅
note

* Currencies with 0, 2, and 3 decimal places are supported. For currencies with 3 decimal places, the last digit of the amount must be zero; that is, the amount must be rounded to two decimal places.

3-D Secure​

The 3-D Secure pass-through authorization model is the one supported in this region. This means the customer is authenticated using an external 3-D Secure MPI before the payment request is made. Authentication information is then included in the threedsPassThrough block of the payment request.

The following ecommerce indicator (ECI) values are supported:

  • 00
  • N0
  • 01
  • 02
  • N2
  • 06
  • 07

Strong customer authentication (SCA) exemptions​

The following SCA exemptions are supported:

  • delegated_authentication
  • low_value
  • secure_corporate
  • transaction_risk_analysis

Secure remote payments​

Secure remote payments are supported. Cryptogram and other relevant information for the secure remote payment must be included in the secureRemotePayment block of the payment request.

Mail order/Telephone order (MOTO)​

Mail and telephone orders are supported.

Account verification (Zero auth)​

An account verification is an authorization request with an amount of 0.

Address verification service (AVS)​

The address verification service is not supported.

Scheme transaction reference​

Mastercard supports two ways to link a merchant initiated transaction (MIT) to the initial cardholder transaction:

  • schemeTransactionId — the existing scheme transaction ID (Mastercard Trace ID). It is returned in paymentMethod.scheme.transactionId of the initial payment response.
  • schemeTransactionLinkId — the new Transaction Link Identifier (TLID). It is returned in paymentMethod.scheme.transactionLinkId of the initial payment response.

For subsequent MITs, send the relevant identifier in the corresponding request field.

Industry practices​

The following industry practice types are supported:

  • delayed_charges
  • no_show
  • resubmission *

Due to the way industry practice transactions are supported, any customer initiated transaction (CIT) that includes an agreement between the cardholder and the merchant for a potential subsequent industry practice MIT, should be flagged with the industry practice type.

For example, when a customer is booking a hotel room in a hotel that charges a no-show fee if the customer doesn't show up, the transaction to book the hotel room should be flagged with industry practice set to no_show and no scheme transaction reference as this is the CIT. If the customer doesn't show up, the transaction to charge the no-show fee will be a MIT transaction with industry practice set to no_show and the scheme transaction reference returned in the previous CIT transaction (e.g. schemeTransactionId or schemeTransactionLinkId).

Sample request for a customer initiated transaction that includes an agreement for a potential subsequent industry practice MIT:

{
    "processingAccountId": "2HdN2jq6XWmlkhqRC2gDTNYCvNH",
    "merchantReference": "B2A8734D-9450-4915-A63D-FE5C21F09550",
    "amount": {
        "value": 200,
        "currency": "hkd"
    },
    "paymentMethod": {
        "type": "mastercard",
        "mastercard": {
            "account": {
                "number": "5555555555554444",
                "expiryMonth": "1",
                "expiryYear": "2030",
                "cvv": "333"
            },
            "capture": "manual",
            "industryPractice": {
                "type": "no_show"
            }
        }
    }
}

If the agreement between the cardholder and the merchant for a potential subsequent industry practice MIT includes more than one type of industry practice, like no-show fee if the customer doesn't show up and delayed charges for mini bar expenses, choose one of them for the customer initiated transaction that sets the agreement up.

Issuer/scheme responses​

When a transaction is processed, issuers and card schemes may include relevant information in their response. The following response fields for paymentMethod.type mastercard are supported in this region, and will contain the information provided by the issuer or card scheme if available:

  • scheme:
    • approvalCode
    • avsResult
    • cvvResult
    • eci
    • transactionId
    • transactionLinkId
    • merchantAdviceCode
    • responseCode

Auto-cancellation​

Card schemes require a period of time within which the authorized amount must be captured. This period can vary depending on the Merchant Category Code (MCC), but is typically 30 days for Mastercard. Automatic cancellation is not currently being performed for Mastercard authorizations. Merchants are responsible for cancelling authorizations that remain uncaptured within the applicable period.

Payment flow​

Card flow

Payment​

Request​
{
    "processingAccountId": "2HdN2jq6XWmlkhqRC2gDTNYCvNH",
    "merchantReference": "B2A8734D-9450-4915-A63D-FE5C21F09550",
    "amount": {
        "value": 200,
        "currency": "hkd"
    },
    "paymentMethod": {
        "type": "mastercard",
        "mastercard": {
            "account": {
                "number": "5555555555554444",
                "expiryMonth": "1",
                "expiryYear": "2030",
                "cvv": "333"
            },
            "capture": "manual"
        }
    }
}
Response​
{
    "id": "2DCstfsS93GWIPhkv5che8rvAQe",
    "merchantReference": "B2A8734D-9450-4915-A63D-FE5C21F09550",
    "status": "succeeded",
    "paymentMethod": {
        "type": "mastercard",
        "scheme": {
            "approvalCode": "707595",
            "cvvResult": "M",
            "transactionLinkId": "A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7"
        }
    }
}