# Migrate to Direct Payment API version 100 source: https://developer.mastercard.com/mastercard-gateway/documentation/tutorials-and-guides/migration-guides/mig-direct-payment-v100/index.md The following operations have updated features and breaking changes for version 100. | Integration | Operation | Integration available from | |-------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------|----------------------------| | Direct payment: [Transaction](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) | Authorize | All versions | | | Balance Inquiry | 46+ | | | Capture | All versions | | | Disbursement | 62+ | | | Pay | All versions | | | Referral | 4+ | | | Refund | All versions | | | Retrieve order | 11+ | | | Retrieve Transaction | All versions | | | Update Application Transaction Counter | 100 | | | Update Authorization | 11+ | | | Verify | 7+ | | | Void | 4+ | ## Migrate Authorize to version 100 {#migrate-authorize-to-version-100} https://mtf.gateway.mastercard.com/api/rest/version/100/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} This is the Migration guide for upgrading from versions 1 to 100 of the [Transaction Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) operation. ### Breaking changes {#breaking-changes} This table describes the breaking changes from versions 1 to 100. | Field | Version 1 | Version 100 | Action required | |-------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------|-------------------------------------------------|-------------------------------------------------------------------------------------------------| | API Endpoint | /version/1/... | /version/100/... | Update all endpoint references | | Authentication format | Basic auth with blank user ID | `merchant.` | Update credentials format | | `merchantid` | Present | Present | Case changed to `merchantId` | | `orderid` | Present | Present | Changed from integer to string | | Card - `card.expiry.month` - `card.expiry.year` - `card.number` | Present | Not present | `sourceOfFunds` replaces card as the main payment source group. | | `sourceOfFunds` - `sourceOfFunds.provided.card.expiry.month` - `sourceOfFunds.provided.card.expiry.year` - `sourceOfFunds.provided.card.number` | Not present | Not present | Replaces card as the main payment source group. | | `transaction` - `transaction.amount` - `transaction.currency` | N/A | N/A | `transaction.currency`: ISO 4217 Alpha code | | `order` | Optional | Required for crypto, debt, high-risk securities | - `order.currency`: ISO 4217 Alpha code - `order.amount`: Required if `netAmount` not provided. | ### Payload comparison {#payload-comparison} This table describes the payload comparison from versions 1 to 100. | Category | Field or Feature | Version 1 | Version 100 | Notes | |-------------------------|----------------------------------------------------------------------|----------------|------------------|----------------------------------------------------------------------------------------| | Endpoint | API Version | /version/1/... | /version/100/... | Updated version path | | Core fields | `apiOperation` | AUTHORIZE | AUTHORIZE | No change | | | `merchantId`, `orderId`, `transactionId` | Required | Required | No change | | Card details | `card.number`, `card.expiry`, `card.securityCode` | Required | Optional | In version 100, card details can be provided through session, token, or device payment | | Authentication | `authentication.3ds`, 3ds1, 3ds2 | Not present | Extensive | Version 100 supports full 3DS 1 and 2 authentication flows | | Session support | `session.id` | Not present | Optional | Enables session-based card detail retrieval | | Agreement support | `agreement.` | Not present | Optional | Supports recurring, installment, and unscheduled payments | | Account funding | `accountFunding.` | Not present | Optional | For P2P, payroll, crypto. | | Debt repayment | `debtRepayment.` | Not present | Optional | Required for MCC 6012, 6051 | | Cruise and airline data | `cruise.`, `airline.` | Not present | Optional | Industry-specific enhancements | | Device info | `device.` | Basic | Extended | Version 100 includes browser, fingerprint, hostname. | | POS terminal info | `posTerminal.` | Not present | Optional | For card-present transactions | | Customer info | `customer.` | Basic | Extended | Version 100 includes identification, account history. | | Order details | `order.` | Basic | Extended | Version 100 supports tax, discount, shipping, wallet. | | Risk management | `risk.` | Basic | Extended | Version 100 supports custom risk fields, bypass rules | | Currency conversion | `currencyConversion.` | Not present | Optional | For Dynamic Currency Conversion (DCC) | | Payment plans | `paymentPlan.` | Not present | Optional | For installment payments | | Browser / App payments | `browserPayment.`, `appPayment.` | Not present | Optional | For redirect and in-app flows | | Initiator info | `initiator.` | Not present | Optional | Tracks who initiated the transaction | | Line of business | `lineOfBusiness` | Not present | Optional | For multi-business merchant profiles | | Response enhancements | `authorizationResponse.`, `availableBalance.`, `order.fundingStatus` | Basic | Extended | Version 100 includes more granular response information | ### Response format changes {#response-format-changes} For [Authorize](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) response format changes, see the [Changelog](https://gateway.mastercard.com/api/documentation/apiDocumentation/rest-json/version/latest/changelog.html?locale=en_US). ## Migrate Balance Inquiry to Version 100 {#migrate-balance-inquiry-to-version-100} https://mtf.gateway.mastercard.com/api/rest/version/100/merchant/{merchantId}/balanceInquiry This is the Migration guide for upgrading from versions 46 to 100 of the [Transaction Balance Inquiry](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) operation, including a comparison table of breaking changes and new features. ### Breaking changes {#breaking-changes-1} This table describes the breaking changes from versions 46 to 100. | Field or Feature | Version 46 | Version 100 | Notes | |------------------------------------------------|-----------------|---------------------------|----------------------------------------------------------------------------| | API version | /version/46/... | /version/100/... | Update required | | `apiOperation` | AUTHORIZE | AUTHORIZE | No change | | `order.subMerchant.identifier` | Optional | Required | Now mandatory for sub-merchant transactions | | `order.subMerchant.tradingName` | Optional | Required | Required for sub-merchant display on statements | | `order.subMerchant.disputeContactPhone` | Not present | Present | New field for high-dispute merchants | | `order.subMerchant.governmentCountryCode` | Not present | Present | Required for government-controlled merchants | | `order.subMerchant.marketplaceId` | Not present | Present | Required for Visa marketplace merchants | | `availableBalance.` | Required | Optional | The amount available to spend by redeeming rewards available for the card. | | `availableBalance.reward.payerNominatedAmount` | Not present | Present | Indicates if payer must specify redemption amount | | `availableBalance.reward.program` | Single value | Multiple values supported | Now supports multiple reward programs | | `response.gatewayCode` | Limited values | Expanded values | Includes BALANCE_UNKNOWN for partial eligibility | | `sourceOfFunds.provided.card.expiry.year` | Not present | Not present | Year, as shown on the card. | | `sourceOfFunds.provided.card.maskedFpan` | Not present | Present | New masked FPAN for display purposes | | `sourceOfFunds.provided.card.storedOnFile` | Not present | Present | Indicates if card is stored or not | | `sourceOfFunds.token` | Optional | Optional | Behavior-clarified overrides session or card details | | `sourceOfFunds.type` | Required | Conditionally required | Optional if using token only | ### Payload comparison {#payload-comparison-1} This table describes the payload comparison from versions 1 to 100. | Field or Feature | Version 46 | Version 100 | |-----------------------------|------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------| | API endpoint | /version/46/... | /version/100/... | | Authentication | Certificate or Basic | Same | | Required fields | `merchantId`, `order.currency`, `sourceOfFunds.type` | Same | | Sub-merchant fields | All optional | `identifier` and `tradingName` are required | | New fields introduced | N/A | `maskedFpan`, `maskedFpanExpiry`, `storedOnFile`, `governmentCountryCode`, `marketplaceId`, `disputeContactPhone`, `payerNominatedAmount` | | Card data handling | Basic PAN, expiry, CVV | Adds masked FPAN, expiry, and stored card indicators | | Tokenization support | Basic | Enhanced with override logic | | Mobile wallet support | Apple Pay, Android Pay, Samsung Pay | Same, with more detailed guidance | | Response gatewayCode values | BALANCE_AVAILABLE, NO_BALANCE, TIMED_OUT | Adds BALANCE_UNKNOWN | | Reward programs | AMERICAN_EXPRESS_MEMBERSHIP_REWARDS | Adds BANCOMER_MEMBERSHIP_REWARDS | | Error handling | Basic fields | Adds `supportCode`, `validationType` | | Field validation | Less strict | More detailed and scenario-specific | | Session handling | Supported | Same | | Encryption support | P2PE, PIN | Same, with extended IV length (up to 64 chars) | | Track data | Track1, Track2 | Same | | Gift card support | Basic | Same | | Response fields | Basic | Adds `payerNominatedAmount` and more conditional logic | ### Response format changes {#response-format-changes-1} For [Balance Inquiry](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) response format changes, see the [Changelog](https://gateway.mastercard.com/api/documentation/apiDocumentation/rest-json/version/100/changelog.html?locale=en_US). ## Migrate Capture to version 100 {#migrate-capture-to-version-100} https://mtf.gateway.mastercard.com/api/rest/version/100/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} This is the Migration guide for upgrading from versions 1 to 100 of the [Transaction Capture](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) operation, including a comparison table of breaking changes and new features. ### Breaking changes {#breaking-changes-2} This table describes the breaking changes from versions 1 to 100. | Field or Feature | Version 1 | Version 100 | Notes | |------------------|----------------|------------------|-----------------| | API endpoint | /version/1/... | /version/100/... | Update required | ### Response format changes {#response-format-changes-2} No new required fields or deprecated fields were introduced. ## Migrate Disbursement to version 100 {#migrate-disbursement-to-version-100} https://mtf.gateway.mastercard.com/api/rest/version/100/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} This is the Migration guide for upgrading from versions 62 to 100 of the [Transaction Disbursement](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) operation, including a comparison table of breaking changes and new features. ### Breaking changes {#breaking-changes-3} This table describes the breaking changes from versions 62 to 100. | Field or Feature | Version 62 | Version 100 | Notes | |---------------------------------------------|-----------------------------------------|------------------------------------------------------------------------------------------|-------------------------| | API endpoint | /version/62/... | /version/100/... | Update required | | `order.amount` | Sum of sub-totals must equal net amount | The total amount for the order. This is the net amount plus any merchant charge amounts. | Validation logic change | | `order.industryPracticePaymentReason` | Not present | New enum for delayed charges, no-show penalties | New field | | `device.ipAddress` | IPv4 only | IPv4 + IPv6 - used in EMV 3DS | Format expansion | | `sourceOfFunds.token` | Merchant-supplied token creation | Gateway token used for processing; precedence clarified | Behavior change | | `accountFunding` | Not present | Conditional for account funding transactions | New domain | | `agreement` | Present | Additional fields | Field expansion | | `authentication.psd2.trustedMerchantStatus` | Not present | Conditional field for PSD2 exemption | New field | | `authentication.status` | Not present | Includes code and description | New field | | `authentication.purpose` | Limited values | Adds AGREEMENT_CANCELLATION, ADD_CARD, MAINTAIN_CARD | Enum expansion | | `currencyConversion` | Flexible | Must match between auth and transaction | Logic enforcement | | `gatewayEntryPoint` | Limited values | Adds CHECKOUT_VIA_WEBSITE | Enum expansion | | `order.walletProvider` | List of wallet values | Removes AMEX_EXPRESS_CHECKOUT, MASTERPASS_ONLINE, and VISA_CHECKOUT | Behavior change | | `paymentPlan` | Present | Present | Behavior change | ### Response format changes {#response-format-changes-3} For [Disbursement](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) response format changes, see the [Changelog](https://gateway.mastercard.com/api/documentation/apiDocumentation/rest-json/version/100/changelog.html?locale=en_US). ## Migrate Pay to version 100 {#migrate-pay-to-version-100} https://mtf.gateway.mastercard.com/api/rest/version/100/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} This is the Migration guide for upgrading from versions 1 to 100 of the [Transaction Pay](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) operation. ### Breaking changes {#breaking-changes-4} This table describes the breaking changes from versions 1 to 100. | Field or Feature | Version 1 | Version 100 | Change type | |---------------------------------|----------------------------------|------------------------------------------------------------------|--------------------------------| | API endpoint | /version/1/... | /version/100/... | Update all endpoint references | | Authentication Format | Basic auth with blank user ID | `merchant.` | Update credentials format | | `merchantid` | Lowercase | `merchantId` | Breaking | | `orderid` | Present | Present | Changed from integer to string | | `card` | Conditional | Replaced by `sourceOfFunds`, `accountFunding` | Breaking | | `sourceOfFunds` | Not present | Information about the payment type and the source of the funds | Breaking | | `sourceOfFunds.token` | Merchant-supplied token creation | Token used for processing - precedence clarified | Behavior change | | `accountFunding` | Not present | Optional field that is required for account funding transactions | Addition | | `debtRepayment.recipient.*` | Not present | Optional field that is required for debt repayment transactions | Addition | | `authentication.purpose` | Limited | Adds AGREEMENT_CANCELLATION, ADD_CARD, MAINTAIN_CARD | Enum expansion | | `authentication.psd2.exemption` | Limited | Adds AUTHENTICATION_OUTAGE, TRUSTED_MERCHANT | Enum expansion | | `initiator` | Not present | Adds AGENT, SERVICE_PROVIDER, GATEWAY | Enum expansion | ### Payload key differences {#payload-key-differences} | Feature | Version 1 | Version 100 | |------------------------------|--------------------------------------------------------|----------------------------------------------------------------------------------------------| | Payload scope | Core fields for a basic PAY transaction | Extensive payload with support for multiple industries, for example, airline, cruise, wallet | | Card details | Basic card fields, for example, number, expiry, holder | Includes device payment, tokenization, EMV, PIN, and encryption support | | Order details | Basic order ID, amount, currency | Rich order metadata: tax, shipping, discounts, merchant category | | Customer info | Basic IP and billing address | Full customer profile, authentication history, national ID, phone, email | | Industry support | Generic merchant transactions | Airline, cruise, travel, wallet, and Open Banking integrations | | Risk and response fields | Basic AVS, CSC, gateway codes | Full risk assessment, 3DS, PSD2 exemptions, authentication tokens | | Payment plans and agreements | Not included | Full support for recurring, installment, unscheduled payments | | Device and POS info | Not included | Detailed device fingerprinting, POS terminal capabilities. | | Shipping info | Basic address | Full shipping contact, method, origin, and billing match indicators | | Error handling | Basic fields | Adds `supportCode`, `validationType` | ### Response format changes {#response-format-changes-4} For [Pay](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) response format changes, see the [Changelog](https://gateway.mastercard.com/api/documentation/apiDocumentation/rest-json/version/100/changelog.html?locale=en_US). ## Migrate Referral to version 100 {#migrate-referral-to-version-100} https://mtf.gateway.mastercard.com/api/rest/version/100/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} This is the Migration guide for upgrading from versions 1 to 100 of the [Transaction Referral](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) operation. ### Breaking changes {#breaking-changes-5} This table describes the breaking changes from versions 1 to 100. | Area | Change | Impact | |-----------------------|----------------------------------------------------------------------------------------------------------|----------------------------------------------------------------| | API endpoint | /version/4/... | /version/100/... | | Authentication format | Basic auth with blank user ID | `merchant.` | | Field structure | New nested structures like `authentication.3ds2`, `accountFunding.recipient.account` | Requires restructuring of request payloads | | New required fields | Fields like `order.purchaseType`, `initiator.entity`, `agreement.id` are conditionally required | Missing these in certain contexts will cause validation errors | | 3DS 2.x support | New fields: `authentication.3ds2.transactionStatus`, `acsReference`, `dsReference` | Upgrade 3DS to 3DS2 | | Stored credentials | Requires `storedOnFile`, `payerConsentForStoringCardDetails`, `agreement.id` | Tokenization flows must be updated for compliance | | Enum value changes | Enums like `authenticationStatus`, `gatewayCode`, `transaction.type` are now case-sensitive and expanded | Incorrect casing or outdated values will cause failures | | Response format | New fields like `authenticationTokenVerification`, `currencyConversion`, `availableBalance` | Response parsing logic must be updated | | Deprecated fields | Some fields from v4 are deprecated or replaced, for example, `billing.address.street2` | Using deprecated fields may result in ignored or rejected data | | Error handling | Enhanced error diagnostics: `error.cause`, `error.supportCode`, `error.validationType` | Error handling logic must be updated to interpret new codes | | POS metadata | New fields like `posTerminal.inputCapability`, `device.browser`, `device.ipAddress` | Required for fraud prevention and compliance in some regions | ### Payload comparison {#payload-comparison-2} This table describes the payload comparison from versions 4 to 100. | Field | Version 4 | Version 100 | Change type | Notes | |----------------------------------------------|-------------|-------------|-------------|-------------------------------------------------------| | `merchantId`, `orderId`, `transactionId` | Required | Required | No Change | Path parameters | | `transaction.authorizationCode` | Required | Required | No Change | Core field | | `transaction.reference` | Optional | Optional | No Change | Optional identifier | | `initiator.userId` | Not present | Present | Added | Identifies who initiated the transaction | | `order.custom`, `order.customerNote` | Not present | Present | Added | Custom metadata | | `partnerSolutionId` | Not present | Present | Added | For integrations via third-party platforms | | `responseControls.sensitiveData` | Not present | Present | Added | Controls masking in response | | `accountFunding.*` | Not present | Present | Added | For account funding transactions | | `agreement.*` | Not present | Present | Added | For stored credentials and recurring payments | | `authentication.*` | Limited | Expanded | Changed | Full 3DS 2.x support added | | `order.purchaseType` | Not present | Present | Added | Required for certain MCCs, for example, 6012, 6051 | | `order.subMerchant.*`, `order.marketplace.*` | Not present | Present | Added | For marketplaces and aggregators | | `device.*`, `posTerminal.*` | Not present | Present | Added | Device metadata for fraud prevention | | `currencyConversion.*` | Not present | Present | Added | Dynamic Currency Conversion support | | `response.authenticationTokenVerification` | Not present | Present | Added | Token verification result | | `response.cardholderVerification.*` | Not present | Present | Added | Detailed AVS/CSC verification | | `response.gatewayRecommendation` | Not present | Present | Added | Suggests next action for example, retry, authenticate | | `result` | Present | Present | No Change | Overall result of the operation | ### Response format changes {#response-format-changes-5} For [Referral](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) response format changes, see the [Changelog](https://gateway.mastercard.com/api/documentation/apiDocumentation/rest-json/version/100/changelog.html?locale=en_US). ## Migrate Refund to version 100 {#migrate-refund-to-version-100} https://mtf.gateway.mastercard.com/api/rest/version/100/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} This is the Migration guide for upgrading from versions 1 to 100 of the Transaction Refund operation. ### Payload comparison {#payload-comparison-3} This table describes the payload comparison from versions 1 to 100. | Field | Version 1 | Version 100 | Notes | |-----------------------------------|------------------------|---------------------------------------------------------|----------------------------------------------------------| | Authentication | userid | format changed to `merchant.` | Existing basic auth integrations must update credentials | | Endpoint | /version/1/... | /version/100/... | Requires endpoint refactoring | | `apiOperation` | REFUND | REFUND | Same in both | | `merchantId` | Required | Required | Same, but version 100 limits to 12 characters | | `orderId` | Integer | String | Changed from integer to string | | `transactionId` | String | String | Same | | `transaction.amount` | Decimal | Decimal | Same | | `transaction.currency` | ISO 4217 currency code | ISO 4217 currency code | Same | | `transaction.reference` | Optional | Optional | Same | | `correlationId` | Optional | Optional | Same | | `sourceOfFunds` | Not allowed | Optional (for standalone refunds) | New in version 100 | | `accountFunding` | Not present | Optional | New in version 100 | | `agreement` | Not present | Optional | New in version 100 | | `airline` | Not present | Optional | New in version 100 | | `billing` | Not present | Optional | New in version 100 | | `customer` | Not present | Optional | New in version 100 | | `device` | Not present | Optional | New in version 100 | | `initiator.userId` | Present | Present | Same | | `order.reference` | Optional | Optional | Same | | `order.totalAuthorizedAmount` | Present | Not explicitly listed | Possibly replaced by `order.amount` | | `order.totalCapturedAmount` | Present | Not explicitly listed | Possibly replaced by `order.amount` | | `order.totalRefundedAmount` | Present | Not explicitly listed | Possibly replaced by `order.amount` | | `response.gatewayCode` | Present | Present | Same | | `result` | Present | Present | Same | | `transaction.type` | REFUND | REFUND | Same | | `transaction.targetTransactionId` | Not required | Optional | New in version 100 for linking to original transaction | | `transaction.item[]` | Not present | Optional | New in version 100 | | `transaction.taxAmount` | Not present | Optional | New in version 100 | | `transaction.discountAmount` | Not present | Optional | New in version 100 | ### Response format changes {#response-format-changes-6} For [Refund](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) response format changes, see the [Changelog](https://gateway.mastercard.com/api/documentation/apiDocumentation/rest-json/version/100/changelog.html?locale=en_US). ## Migrate Retrieve Order to version 100 {#migrate-retrieve-order-to-version-100} https://mtf.gateway.mastercard.com/api/rest/version/100/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} This is the Migration guide for upgrading from versions 11 to 100 of the [Transaction Retrieve Order](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) operation. ### Payload comparison {#payload-comparison-4} This table describes the payload comparison from versions 11 to 100. | Category | Version 11 | Version 100 | Notes | |-------------------------|--------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------| | Endpoint | /version/11/... | /version/100/... | Requires endpoint refactoring | | Authentication | Basic auth with blank `userid` | Basic auth with `merchant.` | Breaking change | | Core fields | `amount`, `currency`, `id`, `result`, `transaction[n]` | Same | Core fields retained | | New top-level fields | Not present | `merchantAmount`, `merchantCurrency`, `funding`, `fundingStatus`, `status`, `referenceOrderId`, `industryPracticePaymentReason` | version 100 adds extensive metadata | | Customer info | `customer.email`, `customer.ipAddress` | Expanded: `customer.firstName`, `lastName`, `mobilePhone`, `taxRegistrationId`, `nationalId` | More granular customer profiling | | Device info | `customer.browser`, `ipAddress` | `device.browser`, `ipAddress`, `mobilePhoneModel` | Device block introduced | | Authentication (3DS) | `transaction[n].3DSecure` | `authentication.3ds`, 3ds1, 3ds2, `authenticationStatus`, `authenticationVersion` | Fully modular 3DS support | | Agreement block | Not present | `agreement` and `transaction[n].agreement` | For recurring, installment, unscheduled payments | | Account funding | Not present | `accountFunding` and `transaction[n].accountFunding` | For wallet top-ups, P2P transfers | | Risk assessment | `risk.gatewayCode`, `reviewResult` | `risk.response.gatewayCode`, `review`, `rule[n]`, `totalScore` | More detailed and structured | | Shipping info | `shipping.address`, `method`, `phone` | Adds `shipping.contact`, `origin`, `sameAsBilling`, `source` | More complete shipping context | | Item details | `item[n].name`, `quantity`, `unitPrice` | Adds `brand`, `category`, `detail`, `industryCategory`, `unitDiscountAmount` | Level 3 data support | | Tax details | `taxAmount` | Adds `tax[n]`, `taxStatus`, `taxRegistrationId`, `localTaxRegistrationId` | Granular tax breakdown | | Discounts | Not present | `discount.amount`, `code`, `description` | New in version 100 | | Merchant charges | Not present | `merchantCharge.amount`, `type`, `calculatedBy` | For surcharges | | Sub-merchant support | Not present | `subMerchant` block | For marketplaces and aggregators | | Payment plans | `paymentPlan` (basic) | Expanded: `firstPaymentAmount`, `interest.rate`, `receiptText` | More flexible installment options | | Browser or app payments | `browserPayment` | Adds `appPayment`, `browserPayment.paypal`, `redirectUrl` | Broader support for payment flows | | Funding info | Not present | `funding.amount`, `currency`, `fundingStatus` | For reconciliation and settlement | | Chargeback info | Not present | `chargeback.amount`, `currency` | New in version 100 | | Enum expansion | Limited | Expanded across `result`, `gatewayCode`, `risk`, `authenticationStatus` | Must update enum handling logic | ### Response format changes {#response-format-changes-7} For [Retrieve Order](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) response format changes, see the [Changelog](https://gateway.mastercard.com/api/documentation/apiDocumentation/rest-json/version/100/changelog.html?locale=en_US). ## Migrate Retrieve Transaction to version 100 {#migrate-retrieve-transaction-to-version-100} https://mtf.gateway.mastercard.com/api/rest/version/100/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} This is the Migration guide for upgrading from versions 1 to 100 of the [Retrieve Transaction](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) operation. ### Breaking changes {#breaking-changes-6} This table describes the breaking changes from versions 1 to 100. | Field or Feature | Version 1 | Version 100 | Change | |-----------------------|-------------------------------|-------------------------|--------------------------------| | API endpoint | /version/1/... | /version/100/... | Update all endpoint references | | Authentication format | Basic auth with blank user ID | `merchant.` | Update credentials format | ### Field restructuring {#field-restructuring} This table describes the field restructuring from versions 1 to 100. | Version 1 field | Version 100 field | Change | |---------------------------------|------------------------------------------------------------|--------------------------------------| | `card.` | Conditional, replaced by `sourceOfFunds`, `accountFunding` | Breaking | | `customer.*` | `customer.*` and `device.*` | Split: device info moved to `device` | | `response.3dsecure.gatewayCode` | `authentication.3ds.gatewayCode` | Moved under `authentication` | | `response.risk.*` | `risk.response.*` | Restructured | | `transaction.*` | `transaction.*` | Mostly unchanged, but expanded | ### Payload comparison {#payload-comparison-5} This table describes the payload comparison from versions 1 to 100. | Field or section | Version 1 | Version 100 | Change type | Notes | |-----------------------------------------|-----------------|--------------------|-------------|----------------------------------------------| | `merchantId` | Present | Present | Changed | Max length reduced from 40 to 12 | | `orderId` | Present integer | Present string | Changed | Data type changed from integer to string | | `transactionId` | Present | Present | Unchanged | | | `correlationId` | Present | Present | Unchanged | Optional in both | | `responseControls` | Not present | Present | Added | Controls how sensitive data is returned | | `card` | Present | Present - Expanded | Enhanced | More detailed structure in version 100 | | `authentication` | Not present | Present | Added | Includes 3DS, PSD2, and payer authentication | | `accountFunding` | Not present | Present | Added | For account-to-account transfers | | `authorizationResponse` | Not present | Present | Added | Detailed issuer/acquirer response | | `availableBalance` | Not present | Present | Added | EBT and funds balance info | | `browserPayment` | Not present | Present | Added | For web-based payment flows | | `cruise`, `airline`, `shipping` | Not present | Present | Added | Industry-specific extensions | | `device`, `initiator`, `lineOfBusiness` | Not present | Present | Added | Contextual metadata | | `order` | Present - Basic | Present - Expanded | Enhanced | Includes tax, surcharge, rewards. | | `transaction` | Present | Present - Expanded | Enhanced | Includes funding, dispute, itemization | | `risk` | Present | Present - Expanded | Enhanced | More granular risk scoring and rules | | `error` | Present | Present - Expanded | Enhanced | More detailed error diagnostics | | `sourceOfFunds` | Not present | Present | Added | Supports cards, ACH, wallets. | | `subgatewayMerchant` | Not present | Present | Added | For gateway operators managing sub-merchants | ### Response format changes {#response-format-changes-8} For [Retrieve Transaction](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) response format changes, see the [Changelog](https://gateway.mastercard.com/api/documentation/apiDocumentation/rest-json/version/100/changelog.html?locale=en_US). ## Update Application Transaction Counter {#update-application-transaction-counter} https://mtf.gateway.mastercard.com/api/rest/version/100/merchant/{merchantId}/applicationTransactionCounter Warning: The [Update Application Transaction Counter](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) API is only present in version 100. ## Migrate Update Authorization to Version 100 {#migrate-update-authorization-to-version-100} https://mtf.gateway.mastercard.com/api/rest/version/100/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} This is the Migration guide for upgrading from versions 11 to 100 of the [Update Authorization](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) operation. ### Breaking changes {#breaking-changes-7} This table describes the breaking changes from versions 11 to 100. | Area | Change | Impact | Action required | |--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------|-----------------------------------------------------| | Authentication | Basic HTTP authentication now requires `merchant.` in the `userid` field | Credentials format has changed | Update your integration to use the new format | | API endpoint | /version/100/... | Changed API versions | Upgrade version endpoint to 100 | | Transaction ID semantics | `transactionid` now must be unique per attempt, including retries | Reuse of transaction IDs for retries is no longer allowed | Ensure each retry uses a new `transactionid` | | Field requirements | Some previously optional fields are now required in specific contexts, for example, `order.merchantCharge.type` when `order.merchantCharge.amount` is provided | May cause validation errors | Review and provide required fields based on context | | 3DS fields | 3DS fields have been restructured under `authentication.3ds`, `authentication.3ds1`, and `authentication.3ds2` | Old 3DS field structure is deprecated | Update to use the new 3DS structure | | Response structure | Response fields are more granular and nested, for example, `authorizationResponse`, `authentication`, `risk` | Parsing logic may break | Update response parsing logic accordingly | ### New features and enhancements {#new-features-and-enhancements} This table describes the new features and enhancements. | Feature | Description | Benefit | |--------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------| | `order` | Includes fields like `order.discount`, `order.dutyAmount`, `order.gratuityAmount`, `order.merchantCharge`, `order.netAmount`. | Enables more detailed order breakdowns | | `initiator.userId` | Identifies the user who initiated the transaction | Useful for audit and tracking | | `partnerSolutionId` | Identifies the integration partner or platform | Helps with partner analytics and support | | `responseControls.sensitiveData` | Controls how sensitive data is returned | Improves security and compliance | | `authentication.psd2` | Supports PSD2 exemptions and trusted merchant status | Enables SCA compliance and smoother user experience | | `accountFunding` and `debtRepayment` | New transaction types with detailed recipient and purpose fields | Supports broader use cases like payroll, crypto, and bill payments | | `agreement` object | Supports recurring, installment, and unscheduled payments | Enables advanced billing models | | `posTerminal` enhancements | Includes detailed terminal capabilities and location info | Improves support for card-present transactions | ### Payload comparison {#payload-comparison-6} This table describes the payload comparison from versions 1 to 100. | Field | Version 11 | Version 100 | Change type | |--------------------------------------|-----------------------|--------------------|-------------| | `apiOperation` | Present | Present | Unchanged | | `correlationId` | Present | Present | Unchanged | | `initiator.userId` | Not present | Present | Added | | `order.reference` | Present | Present | Unchanged | | `order.custom` | Not present | Present | Added | | `order.discount.amount` | Not present | Present | Added | | `order.dutyAmount` | Not present | Present | Added | | `order.gratuityAmount` | Not present | Present | Added | | `order.merchantCharge` | Not present | Present | Added | | `order.netAmount` | Not present | Present | Added | | `order.shippingAndHandlingTaxAmount` | Not present | Present | Added | | `order.shippingAndHandlingTaxRate` | Not present | Present | Added | | `order.taxAmount` | Present | Present | Unchanged | | `partnerSolutionId` | Not present | Present | Added | | `responseControls.sensitiveData` | Not present | Present | Added | | `transaction.amount` | Present | Present | Unchanged | | `transaction.currency` | Present | Present | Unchanged | | `transaction.merchantNote` | Not present | Present | Added | | `transaction.reference` | Present | Present | Unchanged | | `accountFunding` | Not present | Present | Added | | `action.refundAuthorization` | Not present | Present | Added | | `agreement` | Not present | Present | Added | | `airline` | Present | Present | Unchanged | | `appPayment` | Not present | Present | Added | | `authentication` | Present - as 3DSecure | Present - expanded | Expanded | | `authorizationResponse` | Present | Present | Unchanged | | `availableBalance` | Not present | Present | Added | | `billing` | Present | Present | Unchanged | | `browserPayment` | Present | Present | Unchanged | | `constraints` | Not present | Present | Added | | `cruise` | Not present | Present | Added | | `currencyConversion` | Present | Present | Unchanged | | `customer` | Present | Present | Unchanged | | `debtRepayment` | Not present | Present | Added | | `device` | Present | Present | Unchanged | | `gatewayEntryPoint` | Not present | Present | Added | | `initiator` | Not present | Present | Added | | `lineOfBusiness` | Not present | Present | Added | | `merchant` | Present | Present | Unchanged | | `order` | Present | Present | Unchanged | | `risk` | Not present | Present | Added | | `shipping` | Present | Present | Unchanged | | `sourceOfFunds` | Present | Present | Unchanged | | `transaction` | Present | Present | Unchanged | | `error` | Present | Present | Unchanged | ### Response format changes {#response-format-changes-9} For [Update Authorization](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) response format changes, see the [Changelog](https://gateway.mastercard.com/api/documentation/apiDocumentation/rest-json/version/100/changelog.html?locale=en_US). ## Migrate Verify to version 100 {#migrate-verify-to-version-100} https://mtf.gateway.mastercard.com/api/rest/version/100/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} This is the Migration guide for upgrading from versions 7 to 100 of the [Transaction Verify](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) operation. ### Breaking changes {#breaking-changes-8} This table describes the breaking changes from versions 7 to 100. | Area | Version 7 | Version 100 | Notes | |---------------------|----------------------------------------------------|-------------------------------------------------------------------|-------------------------------------------------------------------| | API endpoint | /version/7/... | /version/100/... | Update your endpoint URL to use version 100. | | Authentication | Basic auth with blank username | Basic auth with `merchant.` as username | Update your authentication header accordingly. | | `orderid` | Present | Present | Changed from integer to string | | Card details | `cardDetails.card` | `sourceOfFunds.provided.card` | Replace cardDetails with `sourceOfFunds.provided`. | | Transaction object | `transaction.currency` and `transaction.reference` | `order.currency`, `order.reference` | Use order object for currency and reference. | | 3DSecure fields | `3DSecure.*` | `authentication.3ds.*`, `authentication.3ds2.*` | Replace old 3DS fields with new structured authentication object. | | Billing or shipping | Flat structure | Nested with `billing.address`, `shipping.address` | Update field paths accordingly. | | Response structure | Flat | Deeply nested with `response.*`, `authorizationResponse.*` | Update response parsing logic. | ### Payload comparison {#payload-comparison-7} This table describes the payload comparison from versions 7 to 100. | Field or Section | Version 7 | Version 100 | Change type | |------------------------------------------|---------------------------------------|-------------------------------------------------------------|-------------------------| | `apiOperation` | VERIFY | VERIFY | Unchanged | | `merchantId`, `orderid`, `transactionid` | Required | Required | Unchanged | | `cardDetails` | Required with card, token, or session | Replaced by `sourceOfFunds` | Renamed or Restructured | | `sourceOfFunds` | Not present | Required card, token, session, ACH. | Added | | `authentication` | Limited 3DS fields | Full 3DS1, 3DS2, PSD2 support | Expanded | | `billing` | Basic address and phone | Extended with company, state codes | Enhanced | | `shipping` | Basic address and contact | Extended with contact.email, method | Enhanced | | `customer` | Only email | Full profile: name, phone, ID, tax ID | Expanded | | `order` | Only reference | Full structure: amount, currency, tax, discount | Expanded | | `transaction` | Basic: currency, reference, source | Extended: `merchantNote`, `payerConsent`, `serviceLocation` | Expanded | | `correlationId` | Optional | Optional | Unchanged | | `paymentPlan` | Present | Present with more fields | Enhanced | | `3DSecure` | Basic response fields | Moved under authentication | Restructured | | `airline` | Present | Present with more fields | Enhanced | | `authorizationResponse` | Present | Present with more fields | Enhanced | | `risk` | Basic bypass rules | Full risk assessment, custom fields | Expanded | | `device` | Limited - browser, IP | Full device fingerprinting, ANI. | Added | | `agreement` | Not present | Present - recurring, installment. | Added | | `accountFunding` | Not present | Present - for wallet or account transfers | Added | | `debtRepayment` | Not present | Present - MCC 6012 or 6051 | Added | | `posTerminal` | Present | Extended with mobile, serial, location. | Enhanced | | `responseControls` | Not present | Present, for example, `sensitiveData` masking | Added | ### Response format changes {#response-format-changes-10} For [Verify](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) response format changes, see the [Changelog](https://gateway.mastercard.com/api/documentation/apiDocumentation/rest-json/version/100/changelog.html?locale=en_US). ## Migrate Void to version 100 {#migrate-void-to-version-100} https://mtf.gateway.mastercard.com/api/rest/version/100/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} This is the Migration guide for upgrading from versions 4 to 100 of the [Transaction Void](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) operation. ### Breaking changes {#breaking-changes-9} This table describes the breaking changes from versions 4 to 100. | Area | Version 4 | Version 100 | Impact | |----------------------|--------------------------------|---------------------------------------------------------------------------------------|--------------------------------------------------| | Authentication | Basic auth with blank username | Basic auth requires `merchant.` as username | Update required for authentication headers | | Order ID type | Integer | String up to 40 characters | Must change data type and validation logic | | Field structure | Flat structure | Deeply nested and modular, for example `sourceOfFunds`, `authentication`, `agreement` | Requires refactoring request payloads | | Transaction ID reuse | Retry allowed with same ID | Each retry must use a new unique transaction ID | Update retry logic to generate new IDs | | Response fields | Limited | Extensive, includes risk, funding, disputes | Update response parsing and error handling logic | ### Payload comparison {#payload-comparison-8} This table describes the payload comparison from versions 4 to 100. | Field | Version 4 | Version 100 | Change type | Notes | |-----------------------------------|-----------|-------------|-------------|---------------------------------------------------------------------| | `apiOperation` | Present | Present | Unchanged | Fixed to VOID | | `correlationId` | Present | Present | Unchanged | Optional | | `initiator.userId` | Absent | Present | Added | Identifies who initiated the transaction | | `order.custom` | Absent | Present | Added | Custom merchant-defined order info | | `partnerSolutionId` | Absent | Present | Added | For integrations via third-party solutions | | `posTerminal.onlineReasonCode` | Absent | Present | Added | Reason for sending transaction online | | `responseControls.sensitiveData` | Absent | Present | Added | Controls sensitive data in response | | `sourceOfFunds` | Absent | Present | Added | Full support for card, token, session | | `transaction.reference` | Present | Present | Unchanged | Optional | | `transaction.targetTransactionId` | Present | Present | Unchanged | Required | | `authentication` | Present | Present | Expanded | More detailed 3DS1, 3DS2, PSD2 support in version 100 | | `authorizationResponse` | Present | Present | Expanded | More fields and codes in version 100 | | `billing` | Present | Present | Unchanged | Address and phone | | `shipping` | Present | Present | Unchanged | Address and contact | | `order` | Present | Present | Expanded | Version 100 includes more fields like `custom`, `reward`, `funding` | | `transaction` | Present | Present | Expanded | Version 100 includes more metadata and nested fields | | `device` | Absent | Present | Added | Device and browser info | | `risk` | Present | Present | Expanded | Version 100 includes more granular risk rules | | `result` | Present | Present | Unchanged | SUCCESS, FAILURE | | `error` | Present | Present | Unchanged | Error handling structure | ### Response format changes {#response-format-changes-11} For [Void](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) response format changes, see the [Changelog](https://gateway.mastercard.com/api/documentation/apiDocumentation/rest-json/version/100/changelog.html?locale=en_US).