MerchantPaymentGateway Configuration — MPGS

Generated page — source of truth is schema/mpgs.yaml and templates/mpgs-uat.j2. Do not edit this file directly.

What is a MerchantPaymentGateway?

When you configure a merchant in MGMT, you are not configuring one payment gateway connection. You are configuring an array of gateway connections, one per payment method and processing role. Each entry in this array is a merchantPaymentGateway (MPG) record.

This distinction matters because different payment types route differently:

• A card-present transaction routes through a synchronous channel.
• A tokenised MOTO transaction can route synchronously or asynchronously depending on the terminal configuration.
• An ecommerce transaction goes through a hosted payment page (no host credentials needed at the MPG layer) and then a separate back-end processing channel.

If you configure only one MPG entry, only one payment type works. A correctly provisioned MPGS merchant has five MPG entries. Provisioning fewer is not a partial configuration — it is a broken one.

MPGS MPG Array — Overview

The MPGS provisioning template (templates/mpgs-uat.j2) defines exactly five MPG entries. Each is identified by its paymentMethod (PM slot) and defaultFlag.

The defaultFlag tells the system which entry to use when a terminal does not specify a channel. defaultFlag: 1 is the primary entry; defaultFlag: 0 is the secondary entry activated by async terminal configuration.

Entry 1 — PM0 Bank Card (Card Present)

Card-present transactions route through the MPGS sync channel. This entry uses host credentials directly — the gateway authenticates against MPGS using the API key and password configured here.

Why this entry exists: Card-present payments are synchronous by nature. The terminal holds the card until the response arrives. This MPG entry tells MGMT which MPGS host to call, which channel to route through, and what credentials to use.

Secret fields: host_key and host_password must never be committed to source control. Supply via your secrets manager at provisioning time.

Entries 2 and 3 — PM1 Token (Sync + Async)

Token MOTO requires two MPG entries for PM1, not one. This is the most commonly misunderstood aspect of MPGS provisioning.

Why two entries?

MGMT routes a token transaction based on the asyncFlag set on the terminal config. When asyncFlag=0, MGMT selects the MPG entry with defaultFlag=1 (sync). When asyncFlag=1, MGMT selects the MPG entry with defaultFlag=0 (async).

A terminal configured for async processing (asyncFlag=1 in terminalConfig) needs the async MPG entry to exist. If it does not exist, that terminal cannot process token transactions. The two entries use different channels — the sync channel for immediate responses and the async channel for deferred processing.

Both entries use the same host credentials. The difference is the channelId and defaultFlag.

Entry 2 — Token Sync (defaultFlag=1)

Entry 3 — Token Async (defaultFlag=0)

Relationship to Terminal Config: The asyncFlag on each terminalConfig row determines which MPG entry is used for that terminal. See Terminal Configuration for how asyncFlag maps to these entries.

Entry 4 — PM4 Ecom Widget (Hosted Payment Page)

The ecom widget entry handles the payment form — the hosted page that the customer sees when entering card details. This entry routes the browser session to the MPGS hosted payment page.

Why no host credentials here? The hosted payment page is served directly by MPGS. Astral does not handle card data at this layer. The channelId tells MGMT which MPGS instance to route the browser to, but credentials are not required — MPGS authenticates the session independently using the merchant account embedded in the HPP configuration.

This is different from ecom processing (Entry 5), which authenticates with host credentials to submit the transaction after the customer completes the payment form.

No extData credentials on this entry — this is correct and expected. The absence of host_url, host_key, and host_password is intentional, not an omission.

Entry 5 — PM4 Ecom Processing (Transaction Back-End)

The ecom processing entry handles the transaction submission after the customer completes the hosted payment page. This entry calls MPGS directly with host credentials to authorise, capture, or refund the transaction.

This entry also carries the card BIN range routing table (extData10). This tells MPGS how to classify card networks by BIN prefix — which ranges are Visa, Mastercard, Amex, Discover, Diners, JCB. Transactions outside the configured ranges may fail routing.

Card BIN Range Routing (extData10)

The default BIN range table from schema/mpgs.yaml:

40-45,visa|2221-2720,mastercard|51-55,mastercard|34-34,amex|37-37,amex|
60-649,discover|30-39,diners|3528-3589,jcb

Format: {start_bin}-{end_bin},{scheme} entries separated by |. Transactions are matched against this table to determine the card network. This value should be confirmed with the MPGS integration owner before use in production.

Common Gateway Field

One field applies identically to all five MPG entries.

Channel ID Summary (UAT)

The three channel IDs used across the five MPG entries:

UNCONFIRMED — UAT only. These channel IDs are extracted from values/mpgs-uat.yaml. SIT and PROD channel IDs are not available in this repository. See Open Item OI-003.

Provisioning Checklist

Before submitting the MPG configuration, verify:

• [ ] All five entries are present (PM0, PM1×2, PM4×2)
• [ ] PM1 has both defaultFlag=1 (sync) and defaultFlag=0 (async) entries
• [ ] PM4 widget entry has no host credentials (extData1/2/3)
• [ ] PM4 processing entry has host credentials and a BIN range table
• [ ] Sync channel ID is used for PM0 and PM1 sync
• [ ] Async channel ID is used for PM1 async and PM4 processing
• [ ] Ecom widget channel ID is distinct from sync and async channels
• [ ] All secret fields are supplied via secrets manager, not hardcoded

Open Items

See Also

• Merchant Configuration — group and merchant fields
• Terminal Configuration — how asyncFlag maps to MPG entries
• Tokenisation — STS token space and repository setup
• Payment Methods Reference — what PM0, PM1, PM4 mean
• Field Catalog — full field definitions with types and constraints