Mastercard AgentPay Migration

Overview

MasterCardAgentPayModule is a retired compatibility module. Version 2.0 is hidden from Workflow Studio and never reads payment credentials, constructs a provider request, authorizes or refunds money, registers a webhook, or reports payment success.

The former implementation treated a hard-coded Mastercard Send URL and bearer token as an AgentPay contract, accepted incomplete account and financial controls, and substituted values such as unknown or PENDING when a provider response lacked required evidence. Those assumptions are not safe enough for a financial write. Version 2.0 removes the network path and always returns MODULE_RETIRED.

The class and Spring bean remain loadable so saved workflows can be inspected and migrated without deserialization failures. It is not a working Mastercard connector.

Usage

Do not add MasterCardAgentPayModule to a new workflow. For each saved task that references it:

1. Stop the task before retrying; the compatibility response is non-retryable.
2. Reconcile any payment attempt made by an older runtime directly with the contracted provider.
3. Select a provider connector backed by a reviewed API contract and an approved commercial account.
4. Rebuild amount, currency, customer, confirmation, idempotency, and reconciliation mappings explicitly.
5. Bind a least-privilege READY IntegrationAccount to that replacement.
6. Validate the replacement in an authorized sandbox before enabling production money movement.

StripeModule is a possible governed replacement only when changing the payment provider and flow is explicitly approved. It is not a drop-in Mastercard migration.

Inputs

The compatibility shell recognizes legacy fields only so old tasks are understandable. It never parses, stores, logs, or transmits their values.

Name	Type	Required	Version 2.0 behavior
integration_account_id	string	No	Never resolved; no SecureField is read.
transaction_type	string	No	PURCHASE or REFUND is ignored.
amount_cents	integer	No	Ignored; no financial limit or provider request runs.
currency	string	No	Ignored.
merchant_reference	string	No	Not stored or transmitted.
idempotency_key	string	No	Ignored; it cannot re-enable payment behavior.

Other legacy fields, including card acceptor details, webhook URLs, risk controls, and metadata, have no effect.

Outputs

Name	Type	Description
status	string	Always error.
error.code	string	Always MODULE_RETIRED.
error.message	string	Safe migration guidance.
error.retryable	boolean	Always false.
error.migrationTargets	array	Approved alternatives to evaluate; currently StripeModule.
error.requiredAction	string	Financial-control review required before migration.

No transaction identifier, authorization state, settlement state, amount, webhook state, timestamp, provider response, or success marker is produced.

IntegrationAccount Requirements

MasterCardAgentPayModule accepts, loads, and decrypts no IntegrationAccount. There is no account status, token, key, environment flag, or workflow role that re-enables its legacy code path.

For a replacement, use only the authentication model required by that connector's reviewed provider contract. Keep secrets in IntegrationAccount SecureFields, require the connector's documented READY state, use least-privilege scopes, and do not place PAN, CVV, tokens, or credentials in workflow input or logs.

Configuration

Direct metadata lookup exposes two advanced legacy hints so old configuration can be recognized:

Field	Legacy purpose	Version 2.0 behavior
transaction_type	Selected PURCHASE or REFUND.	Never executed.
environment	Selected sandbox or production.	Never resolved.

The module is discoverable=false; Workflow Studio does not offer it for new tasks.

Operations

Version 2.0 implements one deterministic compatibility operation: block execution and return migration guidance.

The Stripe Payments ExecModule supports bounded, reviewed Stripe operations with explicit financial confirmation and caller-owned idempotency keys. Use it only after approving the provider migration. Otherwise, wait for a dedicated connector based on the exact contracted Mastercard product, authentication, request, response, approval, and reconciliation contract.

Mastercard publishes distinct product surfaces for Agent Pay, Mastercard Send, and Mastercard Track. A marketing name or a different Mastercard API must not be used to infer a financial endpoint.

Errors and Failure Modes

Failure	Meaning	Recovery
MODULE_RETIRED	The task still references the retired prototype. No credential or provider request occurred.	Replace the task with a reviewed payment connector.
Prior-runtime ambiguous payment	An older version timed out or returned incomplete evidence after a financial request.	Reconcile directly with the provider using approved merchant records before any retry.
Replacement validation error	Amount, currency, resource ID, confirmation, account, or idempotency input is invalid.	Correct the named field; confirm no request was sent.
Replacement ambiguous write	Commit state is unknown after a timeout or transient provider response.	Reconcile provider state by the same idempotency key before a deliberate retry.

The compatibility response never includes legacy values, credentials, exception text, provider bodies, payment data, or merchant identifiers.

Example

Legacy task input:

{
  "transaction_type": "PURCHASE",
  "amount_cents": 1000,
  "currency": "USD",
  "merchant_reference": "order_123"
}

Expected result:

{
  "status": "error",
  "error": {
    "code": "MODULE_RETIRED",
    "message": "MasterCardAgentPayModule is retired; choose a contracted payment provider connector",
    "retryable": false,
    "migrationTargets": ["StripeModule"],
    "requiredAction": "Review provider, PCI, approval, idempotency, and reconciliation controls before migration"
  }
}

Notes

• Pagination: not applicable; the compatibility shell performs no provider read.
• Limits: legacy values are ignored. Replacement connectors must enforce amount, payload, timeout, response, and pagination bounds.
• Idempotency: repeated execution returns the same failure shape and has no external side effect. This does not prove an older financial attempt failed.
• API constraints: no Mastercard API is called. A future connector must implement the exact contracted product rather than reuse a guessed endpoint.
• Destructive behavior: none in version 2.0. The compatibility shell cannot authorize, capture, refund, transfer, or cancel money.
• Observability: one bounded warning records that execution was blocked; payment values and credentials are not logged.
• Runtime boundary: source metadata changes appear in the live Workflow Studio catalog only after a separate ValkyrAI runtime deployment. Until then, /v1/modules/metadata may still expose version 1.0.