Upgrade your API version
API version support changes
Mastercard Gateway is updating API version support as part of an ongoing platform modernization program.
Hosted Checkout decommission
- Mastercard Gateway will decommission Hosted Checkout (HCO), including version 62 and all earlier versions.
- HCO follows a decommission plan that is separate from the decommission plan for the other API versions.
- The HCO decommission date is 1 October 2026.
API version decommission
- Mastercard Gateway will decommission API versions v48, v47, v43, v40, v38, v37, v35, and all earlier on 31 March 2027.
- If you use any of these versions, you must migrate to version 100 before 31 March 2027.
Migration toolkit
Mastercard Gateway provides these resources to support your upgrade to version 100:
- Migration guides that cover the upgrade from selected API versions to version 100. Refer to the guide that matches your current integration type:
- Postman examples for version 100 that you can run against your integration.
- A Changelog that documents all modifications in new API versions.
- Steps to test your migrated API versions.
Before you begin
This diagram describes the tasks to complete before you upgrade your API version.
Choose your integration type
To migrate from a legacy version of the Gateway API, follow the guide that most closely represents your current integration and features.
Treat each guide as a starting point. Test and validate your own use cases, data flows, and business logic. Refer to the API reference and the Changelog for complete information.
This table lists the migration guide to follow for each integration type and operation.
| If your current integration is... | Operation | Integration available from | Upgrade to version 100 |
|---|---|---|---|
| Hosted Checkout | Initiate Checkout | 63 and later | Refer to the Hosted Checkout migration guide. |
| Hosted Session: Session | Create checkout session | 27 to 62 | Refer to the Hosted Session migration guide. |
| Retrieve session | 18 and later | ||
| Update Session | 18 and later | ||
| Create Payment Page Session | 17 to 26 | ||
| Authorize with session | 2 to 3 | ||
| Create Session | 2 and later | ||
| Pay with session | 2 to 3 | ||
| Save Card (with system-generated token) with Session | 2 to 3 | ||
| Save Card with Session | 2 to 3 | ||
| Direct Payment: Transaction | Authorize | All versions | Refer to the Direct Payment migration guide. |
| Balance Inquiry | 46 and later | ||
| Capture | All versions | ||
| Disbursement | 62 and later | ||
| Pay | All versions | ||
| Referral | 4 and later | ||
| Refund | All versions | ||
| Retrieve order | 11 and later | ||
| Retrieve Transaction | All versions | ||
| Update Application Transaction Counter | 100 | ||
| Update Authorization | 11 and later | ||
| Verify | 7 and later | ||
| Void | 4 and later | ||
| Hosted Batch: Batch | Close Batch | 4 and later | Refer to the Hosted Batch migration guide. |
Support
We understand that API migrations can be complex, and we are committed to supporting you throughout this process. Contact our dedicated support team if you have any questions or require additional assistance. If you need technical support during your migration to version 100, contact your Mastercard Gateway account manager or email the support team at gateway_support@mastercard.com.
Frequently asked questions
Which API versions does Mastercard Gateway support?
This table lists the support status of each API version.
| Status | Versions |
|---|---|
| Supported after the platform updates | v100 (latest), v85, v84, v83, v82, v81, v80, v79, v78, v77, v76, v75, v74, v73, v72, v71, v70, v69, v68, v67, v66, v65, v64, v63, v62, v61, v60, v59, v58, v57, v56, v55, v54, v53, v52, v51, v50, v49, v46, v45, v44, v42, v41, v39, v36 |
| Scheduled for decommission on 31 March 2027 | v48, v47, v43, v40, v38, v37, v35, and all earlier versions |
Why should I migrate to version 100?
Older API versions do not receive new platform enhancements and might not support newer Gateway capabilities. Mastercard recommends that you migrate directly to version 100 wherever possible. A direct migration reduces future upgrade effort and gives you access to ongoing Gateway enhancements.
Does this affect Hosted Checkout?
Yes. Mastercard Gateway will decommission Hosted Checkout (HCO), including version 62 and all earlier versions, on 1 October 2026. HCO follows a decommission plan that is separate from the decommission plan for other API versions.
What happens if I do not migrate?
Mastercard Gateway might no longer support your integration after 31 March 2027.
How do I identify the API versions that I use?
You can find your API version information in Merchant Administration or the Merchant Manager portal. Gateway Support can also help you identify your API versions.