Agentic Payment Link

The Agentic Payment link let your agentic workflow or LLM-based application create gateway payment links and check their status directly through the Model Context Protocol (MCP), without your application needing to call the underlying REST APIs itself.

A typical flow looks like this:

1. A consumer reaches a point in your merchant application or chat experience where a payment is needed.
2. Your MCP client calls IPG_LINK_PAYMENT_GET_LINK to obtain a hosted payment page URL.
3. You share that URL with the consumer, who completes the payment on Fiserv's hosted payment page.
4. Your MCP client calls IPG_LINK_PAYMENT_GET_STATUS to confirm the outcome and continue the conversation or workflow.

All requests are authenticated with a bearer token (OAuth 2.0 / OpenID Connect) scoped to your merchant store, and are routed through Fiserv's API gateway.

What you need before you start

• A gateway (IPG) generated Store ID, User ID, and password issued during onboarding. The KeyCloak username is the combination of {StoreID}@{UserID}.
• Optionally, a Time-based One-Time Password (TOTP) secret if your account has one-time-password login enabled.
• An MCP client (agentic runtime, LLM application, or any client library) that supports:
  • the MCP streamable HTTP transport, and
  • OAuth 2.0 Authorization Code flow with PKCE.

Environments

Test / CI

Production

Connecting your MCP client

1. Client configuration

Configure your MCP client with the MCP endpoint for your target environment (see Environments above) and the following values:

2. OAuth discovery

Most MCP clients discover the OAuth endpoints automatically. If yours needs them explicitly, resolve them in this order:

{mcpBaseUrl} is the MCP endpoint for your target environment; {keycloakIssuer} is the matching Identity Provider issuer (see Environments).

3. Authenticate

1. Your MCP client opens a browser to the Keycloak authorization_endpoint with your client_id, requested scope, and a PKCE code_challenge.
2. Log in with your Store ID and User ID in the form {StoreID}@{UserID}, plus your password (and TOTP code, if enabled).
3. Keycloak redirects back to your local callback URI with an authorization code.
4. Your MCP client exchanges the code for an access token at the token_endpoint.

The resulting bearer token carries these claims:

4. Session handshake

Once authenticated, your MCP client performs the standard MCP handshake before making tool calls:

initialize            -> server capabilities
notifications/initialized
tools/list             -> IPG_LINK_PAYMENT_GET_LINK, IPG_LINK_PAYMENT_GET_STATUS
tools/call              -> your actual request

Send the bearer token on every request as Authorization: Bearer <token>.

❗️

If calls suddenly start failing with a generic 500 Internal Server Error after your client has been idle for a while, reconnect your MCP client to start a fresh session rather than retrying — see Error handling.

Tools reference

IPG_LINK_PAYMENT_GET_LINK

Creates a new hosted payment link for a given amount and currency.

Presence: m = mandatory, c = conditional, o = optional.

Request

{
  "payment_link": {
    "amount": 10.00,
    "currency": "EUR"
  }
}

Response

{
  "paymentLink": {
    "storeId": "120995513002",
    "orderId": "PL-100000775467",
    "paymentLinkId": "BpLgK3",
    "paymentLinkURL": "https://checkout-lane.com/pl/BpLgK3",
    "expiryDateTime": "2026-06-29T15:35:33+02:00"
  }
}

IPG_LINK_PAYMENT_GET_STATUS

Retrieves the current status of a previously created payment link.

Request

{
  "payment_link_status": {
    "link_id": "BpLgK3"
  }
}

Response

Presence: m = mandatory (always present), c = conditional (present once the link has actually been used/paid).

{
  "transactionStatus": "APPROVED",
  "transactionType": "SALE",
  "transactionAmount": { "total": 10.0, "currency": "EUR" },
  "paymentMethodUsed": {
    "cards": { "cardNumber": "411111******1111", "brand": "VISA" }
  },
  "ipgTransactionDetails": {
    "transactionResult": "APPROVED",
    "approvalCode": "Y:804167:4661560435:PPXM:5147258943",
    "processor": { "responseCode": "00", "responseMessage": "Function performed error-free" },
    "transactionState": "CAPTURED",
    "ipgTransactionId": "84661560435"
  }
}

Error handling

Operational rules