Gateway Integration

CyberSource® & MPGS Gateway Platform Integration

End-to-end implementation, migration and optimisation advisory for the two most widely deployed enterprise payment gateway platforms — Visa’s CyberSource and Mastercard Payment Gateway Services (MPGS). From initial architecture through to fraud tuning, network tokenisation and scheme certification, our consultants have delivered in production for issuing banks, PSPs, e-commerce platforms and super-apps.

Request a Gateway Review Explore Capabilities ↓

Platform Overview

Two distinct enterprise gateway ecosystems — each requiring deep specialisation to implement correctly and optimise at scale.

Visa Subsidiary

CyberSource®

Global payment management platform — 190+ countries, unified REST API, advanced fraud decisioning

  • REST API v2 — unified endpoint for auth, capture, refund, void, credit
  • Secure Acceptance Hosted Checkout & Flex Microform (PCI SAQ A)
  • Decision Manager (DM) — rules-based & ML fraud engine
  • Token Management Service (TMS) — payment network & TMS tokens
  • Payer Authentication (PA) — Cardinal Commerce & native 3DS 2.x
  • Reporting API — TDR, conversion reports, on-demand & subscription
  • Value Added Services: tax, AVS, CVN, recurring billing
  • Simple Order API (SOAP) → REST migration pathway
CyberSource Deep-Dive ↓
Mastercard

MPGS

Mastercard Payment Gateway Services — flexible REST API, Hosted Checkout, PayFac & network tokenisation

  • Web Services REST API — session-based & direct integration
  • Hosted Checkout — fully customisable redirect flow
  • Hosted Session + Direct API — SAQ A-EP card collection
  • 3DS 2.x — Initiate Authentication & Authenticate Payer flows
  • MDES network tokenisation — provisioning & cryptogram handling
  • Sub-merchant / PayFac configuration — split settlement
  • Batch processing — file spec, SFTP delivery, response handling
  • JavaScript & Mobile SDK integration
MPGS Deep-Dive ↓
CyberSource®

CyberSource® Deep-Dive

Comprehensive advisory across every major CyberSource product module — from REST API architecture to advanced fraud rule creation and token hierarchy design.

REST API v2 Architecture

CyberSource REST API v2 consolidates the full payment lifecycle into a single unified endpoint framework. Each resource — /pts/v2/payments, /pts/v2/captures, /pts/v2/refunds, /pts/v2/voids — follows consistent JSON request/response conventions with HTTP verb semantics. Idempotency is enforced via the v-c-idempotency-id header: re-submitting an identical request within the 24-hour window returns the original response without re-processing — critical for network-timeout retry logic. Webhooks deliver asynchronous event notifications (payment.updated, fraud.case.review) to registered HTTPS endpoints, enabling event-driven order management without polling.

Authentication uses HTTP Signature (preferred) or JWT Bearer tokens. HTTP Signature requires a merchant key ID, a secret key, and a digest of the request body — we assist clients in building correct signature generation libraries across Java, .NET, PHP, Python and Node.js SDKs, as well as validating webhook signature payloads on receipt.

Secure Acceptance & Flex Microform — PCI Scope Reduction

Secure Acceptance Hosted Checkout redirects the cardholder to a CyberSource-hosted page, reducing the merchant to PCI DSS SAQ A scope. Configuration is managed through Business Center: form customisation, locale mapping, payment method ordering, 3DS trigger thresholds, and post-payment redirect URLs are all profile-driven. Signed data fields and a HMAC-SHA256 signature prevent parameter tampering.

Flex Microform allows merchants to embed individual card number and CVV fields as iframes within their own checkout page while keeping raw PAN data off the merchant server. The microform.createField() JavaScript call renders a Flex-hosted iframe; the resulting transient token is included in the server-side authorisation request. This achieves PCI SAQ A-EP scope whilst preserving full UX control. We advise on Flex v2 migration from Flex v1 (which uses a different transient token format and is deprecated).

Decision Manager (DM) — Fraud Rule Management

Decision Manager is CyberSource’s rules-based and machine-learning fraud scoring engine. Passive mode allows DM to score every transaction and record recommendations without affecting authorisation flow — ideal for baseline benchmarking and data collection before live deployment. Active mode uses DM decisions to accept, review, or reject transactions in real time.

In passive mode, DM attaches a riskInformation.score.factorCodes array and a riskInformation.score.result (ACCEPT, REVIEW, REJECT) to every response. Merchants can harvest weeks of passive-mode data, identify FP and FN patterns against actual chargeback outcomes, and build rule sets tuned to their specific traffic profile before switching to active mode.

Rule creation in Business Center Rule Manager supports velocity rules (count of transactions from a given IP, BIN, email or device fingerprint within a configurable time window), BIN-country mismatch rules, device fingerprint rules using the ThreatMetrix integration, and custom list (positive/negative) matching. Rules are combined via AND/OR boolean logic into strategies. The chargeback feedback loop (uploading chargeback files back to CyberSource) enables the ML model to learn from confirmed fraud, improving score accuracy over time.

Case management workflow: REVIEW decisions surface in the Case Management queue for manual analyst decisioning. Agents can inspect device fingerprint details, velocity counts, address verification results, and order history. Accept/Reject decisions in the queue can optionally trigger a real-time capture or void via the API.

Token Management Service (TMS)

CyberSource TMS supports two distinct token types that are frequently confused:

  • TMS tokens — a CyberSource-proprietary token referencing a stored card on CyberSource infrastructure. The token value is a 64-character hex string that maps to a Payment Instrument resource. TMS tokens never leave the CyberSource ecosystem.
  • Payment Network Tokens (PNT) — issued by the card network (Visa Token Service / Mastercard MDES) and usable cross-processor. CyberSource acts as the Token Requestor (TR), performing token provisioning and cryptogram generation on behalf of the merchant. Network tokens are recommended for recurring / subscription use cases due to improved issuer approval rates and lifecycle management (card expiry updates propagate automatically).

The TMS resource hierarchy is: Customer → Payment Instrument (the card token) → Instrument Identifier (the underlying PAN reference, never exposed in full). Instrument Identifiers enable cross-instrument reporting and chargeback correlation without storing PANs. We guide clients through the correct token hierarchy design for their subscription billing, marketplace, and stored-credential use cases.

Payer Authentication — 3DS 2.x

CyberSource Payer Authentication (PA) supports the full EMV 3-D Secure 2.x specification via two integration paths:

  • Cardinal Commerce (external) — Cardinal’s Cruise JavaScript SDK handles device fingerprinting (Method URL collection) and the cardholder challenge UI. The merchant passes the Cardinal JWT and referenceId to CyberSource for the authorisation-with-payer-authentication request.
  • CyberSource-native 3DS — CyberSource manages the full 3DS 2.x flow internally, including ACS communication, frictionless vs challenge determination, and result mapping. The merchant only calls POST /risk/v1/authentication-setups (setup), POST /risk/v1/authentications (check enrollment), and includes POST /risk/v1/authorization-with-authentication to combine auth and 3DS.

Authentication result mapping is critical for correct liability shift: ECI (Electronic Commerce Indicator) carries liability classification (05 = fully authenticated, 06 = attempted, 07 = not enrolled / no 3DS). CAVV (Cardholder Authentication Verification Value) is the cryptogram the acquirer passes to the network. dsTransactionId (replacing legacy XID in 3DS 2.x) is the Directory Server transaction reference — a mandatory field on Visa and Mastercard authorisations where 3DS 2.x was performed.

Reporting API

CyberSource offers two reporting modes: subscription reports (automatically generated and delivered on a schedule to SFTP or pulled via API) and on-demand reports (triggered via POST /reporting/v3/report-requests with a date range and report type). Key report types include the Transaction Detail Report (TDR) — a full record of every transaction including decision fields, rule codes, and processor response codes — and the Conversion Report, which tracks the authorisation-to-capture funnel and identifies abandoned payment sessions. We assist clients in parsing TDR CSV schema changes across API versions and building automated reconciliation pipelines.

Decision Manager Rule Operators Reference

Field Operator Value Example Use Case
billTo.ipAddress VELOCITY_COUNT > 5 in 24h Detect rapid-fire carding from same IP
card.prefix (BIN) NOT_IN_LIST Positive BIN list Restrict to approved issuer BIN ranges
deviceFingerprintID VELOCITY_COUNT > 3 in 1h Multiple cards tested from same device
billTo.email REGEX_MATCH .*@tempmail\..* Disposable email detection
card.cardType EQUALS Prepaid Flag prepaid cards for manual review
billTo.country vs card.prefix country MISMATCH — BIN-to-billing country mismatch
orderInformation.amountDetails.totalAmount GREATER_THAN 5000.00 High-value order step-up review

Simple Order API → REST API Migration Checklist

Migration Note: Simple Order API (SOAP / NVP) has an extended deprecation timeline, but new features (TMS v2, network tokens, Flex Microform v2) are REST-only. Plan migration before forced cutover deadlines.
01
Inventory all integration points — list every Simple Order API call in use: authorisation, capture, refund, void, credit, tax service, DM, TMS v1 token operations.
02
Map fields to REST equivalents — Simple Order uses flat NVP fields (e.g. ccAuthService_run=true); REST uses nested JSON objects. CyberSource publishes a field mapping guide but many edge-case fields (custom DM variables, custom fields 1–4) need manual mapping validation.
03
Migrate authentication — replace Basic Auth (merchant ID + transaction key) with HTTP Signature or JWT. Update key rotation procedures accordingly.
04
Update idempotency handling — replace application-level retry logic with v-c-idempotency-id header to prevent duplicate charges on network retries.
05
Migrate TMS tokens — Simple Order subscription tokens (paySubscriptionCreateService) are not directly compatible with TMS v2 Payment Instrument tokens. Bulk migration requires a CyberSource-assisted token porting engagement.
06
Test in CyberSource Test Environment — validate all transaction types, verify webhook delivery and signature, confirm DM passive-mode data matches expected fields.
07
Parallel run and cutover — run both integrations in shadow mode against a test processor, compare response codes and transaction IDs, then perform a phased production cutover with rollback capability.
Mastercard

MPGS Deep-Dive

Mastercard Payment Gateway Services — full integration advisory from session creation through to PayFac onboarding and MDES network tokenisation.

Web Services REST API — Session-Based & Direct Integration

MPGS exposes a RESTful Web Services API at https://<gateway>/api/rest/version/<n>/merchant/<merchantId>/. Two primary integration modes are available:

  • Session-based integration — card data is captured via Hosted Session or Hosted Checkout; the merchant server interacts only with a session ID. This is the recommended path for PCI scope minimisation.
  • Direct integration — the merchant server receives raw card data and passes it directly in the PAY request body. Requires full PCI DSS assessment (SAQ D or AOC).

Hosted Checkout — Redirect Flow

Hosted Checkout redirects the cardholder to a Mastercard-hosted payment page. The merchant initiates the session via POST /session, receiving a successIndicator and a redirect URL. Key customisation parameters in the session creation request include: interaction.displayControl.billingAddress, interaction.displayControl.customerEmail, interaction.locale (BCP-47 language tag, e.g. en_GB, ar_AE), interaction.theme (custom CSS theme ID), and interaction.timeout.value (session expiry in seconds). Post-payment, MPGS redirects to the merchant’s returnUrl with a resultIndicator parameter; the merchant verifies this matches the successIndicator to confirm payment success without relying on redirect parameters alone.

Hosted Session + Direct API (PCI SAQ A-EP)

Hosted Session enables the merchant to embed card collection fields within their own checkout page using MPGS-hosted iframes, while the merchant server performs the payment operation using the resulting session ID. The flow is:

01
createSession — server-side call to POST /session returns a session.id (format: SESSION0002xxxxxxxx). The session ID is passed to the browser.
02
JS SDK initialisation — PaymentSession.configure() binds the Hosted Session iframes to the merchant’s card number and CVV input containers. The SDK is loaded from the MPGS CDN; the merchant never touches raw PAN data in JavaScript.
03
updateSession — PaymentSession.updateSessionFromForm() tokenises the card data into the session on the MPGS server. The callback provides a session.updateStatus of OK on success.
04
PAY operation — server-side PUT /order/<orderId>/transaction/<txnId> with transaction.type=PAYMENT and the session.id. MPGS decrypts the session, retrieves card data, and forwards to the acquirer.

3DS 2.x with MPGS

MPGS implements EMV 3DS 2.x natively. The JavaScript SDK exposes two key methods: 

// Step 1 — Initiate Authentication (Device Fingerprint / Method URL)
ThreeDS.initiateAuthentication(sessionId, orderId, transactionId, function(data) {
    if (data.status === 'AUTHENTICATION_AVAILABLE') {
        // Proceed to authenticatePayer
    } else if (data.status === 'CARD_NOT_ENROLLED') {
        // Proceed to payment without 3DS
    }
});

// Step 2 — Authenticate Payer (Challenge or Frictionless)
ThreeDS.authenticatePayer(sessionId, orderId, transactionId, function(data) {
    if (data.response.gatewayRecommendation === 'PROCEED') {
        // Submit PAY with authentication data attached to session
    } else if (data.response.gatewayRecommendation === 'DO_NOT_PROCEED') {
        // Decline — issuer rejected 3DS
    }
});

After authenticatePayer completes, the session carries the 3DS authentication result (ECI, CAVV/AAV, dsTransactionId). These are automatically included in the subsequent PAY operation — no manual field mapping required on the merchant side. We advise on correct authentication.redirectResponseUrl handling for the challenge flow and Content-Security-Policy headers required to allow the ACS iframe.

MDES Network Tokenisation via MPGS

Mastercard Digital Enablement Service (MDES) enables payment network tokens to replace PANs in recurring and stored-credential flows. MPGS acts as a registered Token Service Provider (TSP) on behalf of merchants. The provisioning flow:

  • Merchant initiates a tokenisation request by including "tokenize": true in the PAY or UPDATE_SESSION request; MPGS requests a network token from MDES.
  • MDES returns a Token PAN (DPAN) and a Token Expiry. Subsequent transactions use the DPAN with a per-transaction cryptogram (TAVV — Token Authentication Verification Value) generated fresh for each authorisation.
  • Token lifecycle management — MDES pushes token updates (card expiry refreshes, account lifecycle events) back to MPGS. The merchant’s stored session/token remains valid across card reissues — a key improvement in recurring billing approval rates.
  • Token Vault operations (suspend / resume / delete) — Post go-live, merchants must implement the MDES Token Vault API for full lifecycle management. A suspend call temporarily deactivates a token (e.g. reported lost card pending investigation); a resume re-activates it; a delete permanently decommissions it. Failure to implement suspend and delete flows correctly is the most common post-launch compliance gap identified in MDES operational reviews.

Sub-Merchant & PayFac Configuration

MPGS supports the Payment Facilitator model natively. Configuration involves:

  • Master merchant — the PayFac entity registered with Mastercard and onboarded directly on MPGS. Holds the merchant agreement and liability.
  • Sub-merchant IDs — each end-merchant is assigned a unique sub-merchant ID. All transactions include the subMerchant.identifier field, enabling Mastercard to identify the true merchant of record for compliance and chargeback routing.
  • Split settlement — MPGS supports split-payment instructions so settlement funds are distributed between the PayFac and sub-merchant according to configured rules, reducing the PayFac’s reconciliation burden.

Batch Processing

For high-volume recurring billing and bulk payment scenarios, MPGS provides a batch file interface. Key specifications:

  • File format: fixed-width or CSV depending on MPGS version and acquirer configuration
  • Delivery: SFTP to MPGS batch server; PGP encryption of file contents required
  • Header record: batch reference, merchant ID, record count, total amount
  • Transaction records: order ID, amount, currency, transaction type, tokenised card reference
  • Response file: returned within the configured SLA (typically 4 hours); contains per-transaction result codes and authorisation codes
  • Error handling: records with validation failures are rejected individually; the remainder are processed — partial batch success is the norm, not an error state

MPGS Operation Codes Reference

Operation HTTP Method Endpoint Pattern Purpose
CREATE_CHECKOUT_SESSION POST /session Initialise Hosted Checkout or Hosted Session
PAY PUT /order/{id}/transaction/{txnId} Capture a one-time payment (auth + capture)
AUTHORIZE PUT /order/{id}/transaction/{txnId} Auth-only — capture deferred
CAPTURE POST /order/{id}/transaction/{txnId} Capture a previously authorised transaction
REFUND POST /order/{id}/transaction/{txnId} Refund a captured payment (full or partial)
VOID POST /order/{id}/transaction/{txnId} Void an authorised (not yet captured) transaction
RETRIEVE_ORDER GET /order/{id} Fetch full order history and status
VERIFY PUT /order/{id}/transaction/{txnId} Card verification (zero-amount auth) for account validation
INITIATE_BROWSER_PAYMENT POST /order/{id}/transaction/{txnId} Redirect-based alternative payment method initiation

Frequently Asked Questions

A payment gateway handles the merchant-facing integration layer: it accepts payment data via API, web form, or SDK; performs tokenization, 3DS invocation, and fraud pre-screening (e.g. CyberSource Decision Manager); and routes the transaction toward the card network. A payment switch handles the network-facing routing layer: it translates between message formats (ISO 8583, ISO 20022), routes authorisation requests to the correct scheme or acquirer network, manages message retries and timeouts, and handles response mapping. CyberSource and MPGS function as both gateway and switch in integrated deployments, but enterprises with high volume or multi-scheme requirements often deploy a dedicated switch (e.g. ACI, FIS, Finastra) behind the gateway for network redundancy and format normalisation.

CyberSource acts as a 3DS Requestor Environment (3DRE) on behalf of the merchant. When 3DS2 is enabled, CyberSource's Payer Authentication service collects device and browser data, invokes the scheme's 3DS Server, and forwards the Authentication Request (AReq) to the Issuer's ACS. The ACS response (ARes) carries the authentication result and, on challenge, the CReq/CRes exchange is managed by CyberSource's hosted challenge window or the merchant's own frame. The CAVV, ECI, and transaction ID returned by the ACS are embedded by CyberSource in the authorisation request to the scheme. For issuers with a hosted ACS, no changes to the ACS are required — the integration point is the issuer's 3DS2 enrollment and ACS URL published in the scheme's Directory Server.

Dynamic Currency Conversion (DCC) in MPGS requires a DCC provider agreement and the enablement of the DCC service in your MPGS merchant profile. The MPGS Checkout API supports DCC through the Session-based API flow: when a transaction currency differs from the card's billing currency, MPGS queries the configured DCC provider for a conversion rate, presents it to the cardholder for acceptance, and includes the DCC details in the authorisation request to the acquirer. The acquirer must be DCC-enabled and the merchant's scheme agreement must permit DCC at the MCC and market level. Key fields in the ISO 8583 authorisation include DE 49 (transaction currency) and DE 51 (billing currency), with the conversion rate data carried in private-use DEs per the acquirer's specification. MPGS also supports Multi-Currency Pricing (MCP), which is scheme-controlled and distinct from DCC.

Ready to optimise your gateway integration?

Whether you’re implementing CyberSource or MPGS for the first time, migrating from a legacy API, or tuning fraud decisioning and tokenisation, our consultants are available for scoped engagements — from architecture review to full implementation support.

Book a Gateway Consultation View Case Studies