Migrate to Direct Payment API version 100
The following operations have updated features and breaking changes for version 100.
| Integration | Operation | Integration available from |
|---|---|---|
| Direct payment: 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
https://test-tnpost.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 operation.
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.<merchantID> |
Update credentials format |
merchantid |
Present | Present | Case changed to merchantId |
orderid |
Present | Present | Changed from integer to string |
Card
|
Present | Not present | sourceOfFunds replaces card as the main payment source group. |
sourceOfFunds
|
Not present | Not present | Replaces card as the main payment source group. |
transaction
|
N/A | N/A | transaction.currency: ISO 4217 Alpha code |
order |
Optional | Required for crypto, debt, high-risk securities |
|
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 via 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
For Authorize response format changes, see the Changelog.
Migrate Balance Inquiry to version 100
https://test-tnpost.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 operation, including a comparison table of breaking changes and new features.
Breaking changes
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
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
For Balance Inquiry response format changes, see the Changelog.
Migrate Capture to version 100
https://test-tnpost.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 operation, including a comparison table of breaking changes and new features.
Breaking changes
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
No new required fields or deprecated fields were introduced.
Migrate Disbursement to version 100
https://test-tnpost.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 operation, including a comparison table of breaking changes and new features.
Breaking changes
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
For Disbursement response format changes, see the Changelog.
Migrate Pay to version 100
https://test-tnpost.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 operation.
Breaking changes
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.<merchantId> |
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
| 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 sgreements | 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
For Pay response format changes, see the Changelog.
Migrate Referral to version 100
https://test-tnpost.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 operation.
Breaking changes
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.<merchantId> |
| 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
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
For Referral response format changes, see the Changelog.
Migrate Refund to version 100
https://test-tnpost.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
This table describes the payload comparison from versions 1 to 100.
| Field | Version 1 | Version 100 | Notes |
|---|---|---|---|
| Authentication | userid |
format changed to merchant.<your gateway merchant ID> |
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
For Refund response format changes, see the Changelog.
Migrate Retrieve Order to version 100
https://test-tnpost.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 operation.
Payload comparison
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.<ID> |
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
For Retrieve Order response format changes, see the Changelog.
Migrate Retrieve Transaction to version 100
https://test-tnpost.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 operation.
Breaking changes
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.<merchantId> | Update credentials format |
Field restructuring
This table desribes 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
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
For Retrieve Transaction response format changes, see the Changelog.
Update Application Transaction Counter
https://test-tnpost.mtf.gateway.mastercard.com/api/rest/version/100/merchant/{merchantId}/applicationTransactionCounter
The Update Application Transaction Counter API is only present in version 100.
Migrate Update Authorization to version 100
https://test-tnpost.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 operation.
Breaking changes
This table describes the breaking changes from versions 11 to 100.
| Area | Change | Impact | Action required |
|---|---|---|---|
| Authentication | Basic HTTP authentication now requires merchant.<your gateway merchant ID> 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
This table describes the nNew 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
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
For Update Authorization response format changes, see the Changelog.
Migrate Verify to version 100
https://test-tnpost.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 operation.
Breaking changes
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.<your gateway merchant ID> 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
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
For Verify response format changes, see the Changelog.
Migrate Void to version 100
https://test-tnpost.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 operation.
Breaking changes
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.<merchantId> 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
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
For Void response format changes, see the Changelog.