Mastercard Gateway

03. 01. 2025

The SDK.finance Core platform includes an External Integration Service (MPGS Integration Service Application) designed to connect with MPGS (Mastercard Payment Gateway Services) for card processing operations.

The MPGS Integration Service is a standalone application offered as an optional module when purchasing the main SDK Core platform. It provides the technical integration required to operate with the Mastercard Payment Gateway Service (MPGS) provider.

This integration service implements a set of basic external provider APIs to support MPGS Hosted Checkout integration. Additionally, it includes internal APIs for creating essential objects within the SDK system during card operations (e.g., account top-ups via card). These APIs support both back-end processes and can also be used for front-end operations (web or mobile apps).

The SDK system delivers a foundational technical integration (“skeleton”) with core features for card processing through the MPGS Hosted Checkout integration.

Note: All features available from the vendor (MPGS) to the client—whether using the source code or cloud version—depend on the client’s specific needs and their agreement with the vendor.

On the SDK.finance side, a streamlined integration with the MPGS Hosted Checkout provider is implemented through the MPGS Integration Service, ensuring quick and efficient connectivity.

How to start using the integration

Make an Agreement with the provider. It is required for the client to make an agreement with the service provider. All features that will be available from the vendor (MPGS) to the client (for both, the source code or cloud clients) depend on the client’s needs and their agreements with the vendor (MPGS).

Get credentials from the provider. After the agreement, the service provider provides the client with the credentials to access the Test and Production Environment. These accesses must be used for provider connectivity setup.

Set up the provider connectivity settings in the SDK platform. Set up the system configuration file.

Set up the commission profile. Specify the provider and total commission for the operation “MPGS Top up” in the Contract/Provider Commission settings.

Set up the gate product in the SDK platform.

How it works (on the example of the account Top up operation via debit Card)

The user of the SDK platform initiates a Top-Up via Debit Card operation through the front-end app (web or mobile). The front end uses API calls to create a Business Process in the SDK system according to predefined conditions.

As a result, the Business Process triggers the MPGS Integration Service, which sends requests via the provider’s REST API to initiate a Hosted Checkout API session with the MPGS provider’s system.

On the provider’s side, the payment data is processed, and the SDK system receives a redirect from the provider with the result of the operation.

After receiving the provider’s response, the SDK system processes it and triggers the internal Top-Up Business Process to transition its status according to the provider’s response.

As a result, the SDK system completes the operation and successfully tops up the account.

Supported operations

Note: All features available from the vendor (MPGS) to the client—whether using the source code or cloud version—depend on the client’s specific needs and their agreement with the vendor (MPGS).

Supported Methods by MPGS Integration Service in the SDK Platform

The MPGS Integration Service Application in the SDK platform supports the following implemented Mastercard Payment Gateway (REST) APIs:

Hosted Checkout: Initiate Checkout – Sends a request to initiate a Hosted Checkout interaction. This interaction provides a Hosted Payment Page where the payer securely enters payment data and completes the payment. Since the sensitive data is entered directly on the provider’s hosted page, it ensures data security and PCI compliance.
Transaction: Retrieve Order – Sends a request to retrieve detailed information about an order and all associated transactions. This allows the system to fetch additional payment data from the provider for further processing.

Operational Scope (Test Environment)

Individual and Merchant users can top up their accounts using a payment card via the MPGS provider (Top-Up via Provider) in the test environment.

Business process and APIs flow

Step 1. Integration setup

As a Platform Owner:

Sign an agreement with the provider (to get access credentials and Merchant Id)
Register at the MPGS system (Merchant Portal)

As an Administrator of the platform:

Check in the SDK Core configuration the availability of the MPGS Integration Service Application and host to connect the MPGS Integration Service Application (application-card-processing-mpgs-checkout.yaml ->anable: ${MPGS_SERVICE_ENABLED:true} and url: ${MPGS_SERVICE_URL:localhost:8081})
Set up connectivity with the provider (application.yaml → api-keys)

There are preliminary steps that must be done as part of integration settings before the Top up via provider operation will be performed by the end-user.

Step 2. Contract setup

As an Administrator of the platform:

Set up Provider and Total commissions and activate MPGS Top up operation

Step 3. Initiate the Top up via provider (Top up via Debit Card) operation by the Individual/Merchant User of the SDK platform

As an Individual or Merchant user:

Choose a top-up wallet by payment card
Specify the channel (provider) to top up the account (for now only MPGS and Mock are available)
Specifies the amount to top up (after the amount was specified system calls API POST /gate/transactions/calculate to calculate the commissions and display the calculation result to the user
Press the “Next” button (system calls API POST/gate/transactions, set gateProviderId (Id of MPGS provider), way, type parameters, and receive the transaction id in response).

After the system calls API POST /gate/transactions/[transactionId]/submit with transaction id and payer fields data (set parameter useCustomerAuthorization, value=false). Under the hood, the SDK back-end calls MPGS API to create an authorized hosted checkout session. In POST /gate/transactions/[transactionId]/submit response the back-end will return the data for the MPGS Hosted Payment Page rendering with the session id.

Enter the card details in the opened hosted checkout payment page and “Process” (the hosted checkout payment page sends specified transaction details to the MPGS)

After the form will send data to the MPGS the user will be redirected to the redirect URL according to the submission result (redirects URL are provided during payment initiation). In SDK system the Top up via provider operation is created in the “Pending” status which shows that SDK is waiting for the processing result from MPGS (BusinessProcess.status=Pending for Top up operation)

List of APIs (SDK and MPGS) used by Top up via MPGS Business Process

SDK APIs		MPGS APIs
URL	Description	URL	Description
POST /gate/transactions/calculate	To calculate the commissions and display the calculation result to the user
POST /gate/transactions	To create the gate transaction for Top up (create an operation inside SDK system)
POST /gate/transactions/[transactionId]/submit	To submit created transaction (under the hood, on this stage the SDK system back-end calls MPGS API to create an authorized hosted checkout session)	POST /merchant/{merchantId}/session	Request to initiate a Hosted Checkout interaction, i.e. a Hosted Payment Page or Embedded Page interaction that allows the payer to select their payment details and make the payment. See Implementing a Hosted Checkout Integration for details.
		GET /merchant/{merchantId}/order/{orderid}	Request to retrieve the details of an order and all transactions associated with this order.

Set up commissions and activate operations

To activate the “MPGS Top up” operation for the user this operation must be added to the user`s Contract and the Vendor and total commission must be specified.

To add the “MPGS Top up” in the Contract from Back-office UI check the Vendors section of the Back Office UI.