# Mastercard Gateway Onboarding and Production Enablement Guide
source: https://developer.mastercard.com/mastercard-gateway/documentation/tutorials-and-guides/onboarding-go-live/index.md

This guide explains how to onboard, configure, and go live with Mastercard Gateway.

It describes the onboarding process for Merchant Service Organization (MSO) administrators, Payment Service Provider (PSP) administrators, integrators, enterprise merchants, and Independent Software Vendor (ISV) or platform providers. You learn how to create and configure merchants, move from testing to production, and access support resources.

After completing this guide, you will understand the end-to-end process, from initial setup to processing live transactions.

## Roles and responsibilities {#roles-and-responsibilities}

This guide is for organizations and teams that onboard merchants to Mastercard Gateway.

Acquirers provide acquiring services and payment processing infrastructure. They typically do not create merchants in the gateway unless their operating model requires it.
MSOs and PSPs onboard, configure, and manage merchants. Depending on their operating model, they may also integrate directly with gateway APIs.
Enterprise merchants are onboarded directly in the gateway and may manage their own merchant configuration or multiple sub-merchants.
ISVs develop platform integrations for merchants or partners. Depending on their business and technical model, they may also integrate directly with gateway APIs.

In this guide, MSO or PSP refers to partner organizations that create, configure, or manage merchants. When a specific commercial or operational distinction applies, the guide uses the appropriate term.

## Merchant onboarding process {#merchant-onboarding-process}

The merchant onboarding process begins when you set up a MSO, PSP, or merchant entity. You then enable the required services, create or link merchants, configure payment and routing settings, integrate with Mastercard Gateway APIs when required, test the implementation, and request production access.

Follow these steps to onboard merchants and go live:

1. Set up the MSO, PSP, or merchant entity

   * Create the organization or merchant profile.
   * Assign the required privileges.
2. Enable services and entitlements

   * Enable the services, features, and data access required for onboarding and transaction processing.
3. Create or link merchants

   * Create merchants individually, in bulk, or through onboarding APIs.
   * Link each merchant to the appropriate MSO, PSP, or parent organization, where applicable.
4. Configure merchant settings

   * Enable payment features.
   * Configure acquirer routing.
   * Configure authentication, security, reporting, and notification settings.
5. Integrate with Mastercard Gateway APIs

   * Implement the API calls required for your integration model.
6. Test the integration in the sandbox environment

   * Validate transaction flows, responses, error handling, and enabled features before you request production access.
7. Go live

   * Complete the production setup.
   * Obtain production credentials.
   * Begin processing live transactions.

## MSO or PSP onboarding {#mso-or-psp-onboarding}

MSO and PSP onboarding focuses on preparing a partner organization to create, configure, and manage merchants in Mastercard Gateway.

During onboarding, create the MSO or PSP entity and assign the privileges required for its role. You Enable the services and features that support onboarding and merchant management activities. These capabilities typically include API access, merchant onboarding APIs, and tools for creating and managing merchants individually or in bulk.

After onboarding is complete, the MSO or PSP can create, configure, and manage merchants based on its assigned privileges and enabled services.

## Service enablement and entitlements {#service-enablement-and-entitlements}

Mastercard Gateway controls the services, features, and data that each organization can access. Service enablement determines which capabilities an organization can use, while entitlements define permissions, data visibility, and relationships between Merchant Service Organizations (MSOs), Payment Service Providers (PSPs), and merchants.

This includes:

* Enabling services such as reporting, tokenization, notifications, and merchant onboarding tools.
* Defining the data that each organization can view and manage.
* Linking merchants to the appropriate MSO or PSP so that the organization can manage them within its approved access boundaries.

## Merchant onboarding through an MSO or PSP {#merchant-onboarding-through-an-mso-or-psp}

MSOs and PSPs onboard merchants through their merchant management capabilities. Depending on the onboarding model, they can create merchants individually, in bulk, or through merchant onboarding APIs.

To streamline onboarding and support growth, MSOs and PSPs can use merchant templates, bulk creation tools, and onboarding APIs. These capabilities allow them to create, configure, and manage merchants at scale.

## Configure merchant settings {#configure-merchant-settings}

After you create a merchant, configure the settings required to process transactions. Enable the payment operations the merchant supports, such as authorization, capture, and refund. Configure acquirer connections and transaction routing, and enable any additional features your business requires, such as EMV 3-D Secure authentication, tokenization, notifications, and reporting.

When you complete these configuration tasks, the merchant is ready to process transactions.

## Manage entitlements and data access {#manage-entitlements-and-data-access}

Organization relationships and assigned permissions control access to services and data. MSOs and PSPs can access data only for the merchants linked to them, while built-in controls maintain separation between organizations.

For example, an MSO or PSP can receive transaction events for its assigned merchants, but it cannot view or manage data for unrelated merchants.

## API integration {#api-integration}

API integration depends on the operating model. In some cases, the merchant integrates directly with the gateway. In other cases, an MSO, PSP, ISV, platform provider, or another approved party builds and manages the integration on behalf of the merchant.

* The integrating party connects to the required gateway API endpoints.
* The integration supports transaction operations such as authorisation, capture, refund, and status checks.
* The credentials, merchant identifiers, and enabled features must match the organisation and merchant being used for each transaction.

## Test the integration {#test-the-integration}

Before you request production access, validate your implementation in the test (sandbox) environment. Use testing to confirm that credentials, configuration, transaction flows, and error handling work as expected.

### Before you start testing {#before-you-start-testing}

Ensure that:

* You have a test merchant account and test Merchant ID provisioned by your MSO, PSP, or account team.
* Your integration is set up, either through API integration or a hosted solution.
* Your credentials and configuration are complete.
* The required payment methods and features are enabled.

### Move to production {#move-to-production}

After you complete testing successfully, submit a production access request. Once approved, Mastercard Gateway activates the approved configuration in the production environment and issues production credentials.

Production activation may include:

* Enabling production endpoints.
* Applying routing rules.
* Activating approved features.
* Issuing production credentials for the merchant, MSO, PSP, ISV, or platform provider integration model.

### Production readiness checklist {#production-readiness-checklist}

Before you go live, confirm that:

* You received and successfully used the test merchant account and credentials.
* The merchant profile is fully configured.
* Authentication is configured and operating correctly.
* The required payment methods, transaction types, and features are enabled.
* You successfully tested all supported payment flows.
* Your integration handles responses, declines, and error conditions correctly.
* You validated security controls, routing, reporting, and notification settings.
* You submitted and received approval for the production access request.
* You received production credentials.

### Validate production activation {#validate-production-activation}

Mastercard Gateway issues production credentials based on the approved operating model:

* Merchants receive merchant-level API credentials.
* MSOs and PSPs receive partner-level credentials.
* ISVs and platform providers receive credentials based on their approved integration model.

After you receive production credentials, complete a controlled production validation. Depending on the agreed go-live process, this validation may include low-value live transactions or another approved validation method.

Confirm that:

* Routing works as expected.
* Enabled features are available.
* Credentials authenticate successfully.
* Access controls are correctly applied.

When you complete these validation activities, your Mastercard Gateway implementation is ready to process live transactions.

## Get support and escalate issues {#get-support-and-escalate-issues}

If you need help with onboarding, testing, production access, or transaction processing, contact Mastercard Gateway Customer Technical Support.

Contact support when you:

* Cannot access the portal or required tools.
* Cannot view or manage merchants that should be assigned to your organization.
* Need help with entitlements, permissions, or service enablement.
* Encounter API authentication or integration issues.
* Need assistance testing transactions or troubleshooting errors.
* Have questions about production readiness or production access.
* Do not receive expected credentials, notifications, or transaction responses.

When you contact support, include enough information for the support team to identify and investigate the issue. Provide:

* Organization name.
* Environment (test or production).
* Merchant ID or organization identifier, where applicable.
* Transaction ID or correlation ID, if relevant.
* Error messages and timestamps.
* A description of the issue and the steps required to reproduce it.

If a request remains unresolved beyond the agreed timeline, first check the request status. If additional assistance is needed, escalate through your account manager, partner manager, or Mastercard contact.

#### Contact Mastercard Gateway Customer Technical Support {#contact-mastercard-gateway-customer-technical-support}

The preferred way to contact support is through Support Case Management (SCM) in Mastercard Connect.

1. Sign in to [Mastercard Connect](https://www.mastercardconnect.com/).
2. Open Support Case Management (SCM).
3. Complete and submit the support request form.
4. Return to SCM to review updates and track progress.

## FAQs {#faqs}

This issue typically occurs when the merchant is not linked to the correct MSO or PSP. Verify that the merchant exists and that the relationship between the merchant and the MSO or PSP is configured correctly. Required services, permissions, or features may not be enabled for the organization or merchant. Review the assigned entitlements and confirm that they meet your integration and operational requirements. If necessary, contact your administrator or support team. Authentication failures often occur because of incorrect credentials, authentication configuration issues, or expired keys. Verify that you are using the correct credentials and that your authentication configuration matches the approved setup. Production credentials are issued after the required testing, validation, and approval activities are complete. Confirm that your production access request has been submitted and approved and that all prerequisites have been satisfied. Portal access issues can occur when an account has not been provisioned, the required permissions are missing, or incorrect credentials are used. Verify your access has been granted and that you are using the correct credentials.