PRIME DIRECTIVE: This file is a decision engine. It contains no product knowledge. Product knowledge lives in

products/

. Authoritative implementation facts come only from MCP tool calls — never from memory or training.

MCP PREFERENCE: Always prefer

juspay-mcp

tools for live merchant data (credentials, settings, gateway config, integration status). Use

juspay-docs-mcp

only for documentation structure and page content.

• Did I authenticate with

  juspay-mcp

  before calling any

  juspay-mcp

  tools? If not, Please trigger the authentication flow now.
• Did I call

  juspay_get_merchant_details

  to establish merchant context before asking for credentials?
• Did I read

  products/

  before calling

  explore_product

  ? Can I conclude from the catalog alone?
• Did I scan the codebase before asking disambiguation questions (language, framework)?
• Did I call

  doc_fetch_tool

  before writing any code?
• Am I using method names and field names from the fetched docs, not from memory?
• For SDK/web redirect products: did I fetch test resources and run tests for each checklist stage wherever possible

• Use native select / choice UI
• Do NOT ask for free-text replies if options are known
• Wait for a selection before continuing
• Do NOT rephrase the same question again after rendering choices
• Do NOT ask for information you can derive — from the codebase, from

  juspay-mcp

  live data, or from the catalog

juspay-mcp:juspay_get_merchant_details()

• $MERCHANT_ID

  — from the

  merchantId

  field

• $CLIENT_ID

  — always default to

  $MERCHANT_ID

  . Never extract this from the API response. Inform the user:

  "Client ID is typically the same as your merchant ID (

  $MERCHANT_ID

  ). If you use a different client ID, please provide it now — otherwise I'll proceed with

  $MERCHANT_ID

  ." Wait for confirmation or a custom value before continuing.

• $INTEGRATION_TYPE

  — from the

  integrationType

  field, which is an array; take the first element (e.g.

  ["PP"]

  →

  "PP"

  )

$INTEGRATION_TYPE

$INTEGRATION_TYPE

PP

hyper-checkout

ec_sdk

ec-headless

ec_api

ec-api

"Based on your account configuration, it looks like you're set up for [Product Name].

Shall I proceed with integrating [Product Name]?

1. Yes, proceed
2. No, let me choose a different product type
3. No, let me choose a specific product"

• Option 1 → set

  $PRODUCT

  to the inferred product ID and skip to Phase 1
• Option 2 → go to Step 0B-Fallback (product type list)
• Option 3 → show the full flat product list from

  $PRODUCT_CATALOG

  and let the user pick directly

$INTEGRATION_TYPE

What type of product are you looking to integrate?

1. Checkout
2. UPI
3. Payouts
4. Billing
5. Not sure

Which Checkout product would you like to integrate?

• Hyper Checkout
• Express Checkout SDK
• Express Checkout API

Which UPI product would you like to integrate?

• UPI TPAP
• Hyper UPI

Please describe your use case and I'll recommend the right product and integration flow.

$INTENT

$INTENT

intent signals

$PRODUCT_CATALOG

$CANDIDATES[]

• "checkout UI", "payment page", "mobile SDK" → prefer products with runtime platforms (android, ios, web, etc.)
• "API only", "server-side", "REST", "backend" → prefer products with no runtime platforms
• "recurring", "subscriptions", "mandates" → billing/mandate products
• "payout", "transfer", "disburse" → payout products
• "UPI", "TPAP", "P2P", "P2M" → UPI products

explore_product

• The

  platforms

  list either matches

  $DETECTED_PLATFORM

  exactly, or has only one option
• No further platform disambiguation is required to start code generation

explore_product

juspay-docs-mcp:explore_product({ product: <candidate-id> })

• Product title
• Platform IDs — runtime IDs signal a client SDK;

  docs

  only signals a server API; a mix signals both
• Number of numbered base integration pages (complexity signal)
• List of supported platforms if a client SDK is present

products/

explore_product

"Based on what you described, here's what I recommend:

[Product Title] — [one-line reason tied to their intent]

(Alternative) [Product Title] — [reason]

Which would you like to integrate? Or pick from the full list below:"

$PRODUCT_CATALOG

$PRODUCT

• Product title and description

• platforms[]

  — every platform entry with its ID and title
• For each platform:

  sections[]

  → for each section:

  sectionTitle

  ,

  pages[]

• For each page:

  pageTitle

  and the

  md content link

  URL

Pages numbered "1. …", "2. …" are base integration pages in required order. Preserve that order exactly.

pubspec.yaml

flutter

package.json

react-native

react-native

package.json

@capacitor/core

capacitor

config.xml

package.json

cordova

cordova

build.gradle

AndroidManifest.xml

android

*.xcodeproj

Podfile

ios

package.json

index.html

.html

web

iframe-web

"I detected your project is a [Platform] app (found

[signal file]

).

Shall I proceed with [Platform]?

1. Yes, use [Platform]
2. No, let me choose a different platform"

$DOC_MAP

• Android: ask Java vs Kotlin
• iOS: ask Swift vs Objective-C, CocoaPods vs SPM
• Web: if both

  web

  and

  iframe-web

  are in the doc map, ask which variant

$PLATFORM

$DOC_MAP

"This product has both a backend API and a client SDK. What do you need?

1. Backend API only
2. Client SDK only
3. Both"

api-only

sdk

doc_fetch_tool

juspay-docs-mcp:doc_fetch_tool({ url: "<md content link from $DOC_MAP>" })

1. Pre-Requisites / Overview — always first; defines credentials, auth format, version constraints
2. Numbered base integration pages — in exact numbered order from

   explore_product

3. Webhooks, Order Status API
4. Error Codes (resources section)
5. Advanced sections — only if user asks

• $PARAMS

  — every request field, method param, constructor arg (required vs optional)

• $CODE_EXAMPLES

  — exact method names, class names, key identifiers from the docs

• $ERROR_CODES

  — all status values, error codes, failure reasons

• $VERSION_CONSTRAINTS

  — min SDK version, min language/platform version

• $WARNINGS

  — any "note", "important", "warning" callout blocks

"I've read the documentation. I'll collect what I need."

$MERCHANT_ID

$CLIENT_ID

$INTEGRATION_TYPE

juspay_get_merchant_details()

juspay-mcp:juspay_get_webhook_settings()
juspay-mcp:juspay_get_general_settings()

• $WEBHOOK_URL

  — existing webhook URL if configured (check if non-empty)

• $WEBHOOK_EVENTS

  — currently subscribed events

• $RETURN_URL

  — existing return URL if configured (check if non-empty)

$WEBHOOK_URL

api/juspay/webhook

api/webhook

webhooks

$WEBHOOK_PATH

"No webhook URL is configured. Your app has a webhook handler at

$WEBHOOK_PATH

. Please provide your deployed base URL so I can set it to

https://<your-domain>/$WEBHOOK_PATH

.

If you don't have a deployed URL yet, you can:

• Run

  ngrok http <port>

  locally to get a temporary public URL
• Leave this for now and configure it on the Juspay dashboard before going live"

https://www.webhook.com

juspay_update_webhook_settings

juspay-mcp:juspay_update_webhook_settings({
  webHookurl: <base-url> + "/" + <$WEBHOOK_PATH>,
  webhookEvents: <merge existing $WEBHOOK_EVENTS with standard events for this product>
})

"Webhook URL set to

<url>

. The following events are now enabled:

• EVENT_NAME_1

• EVENT_NAME_2

• (list every event where the value is

  true

  in the updated config)"

$WEBHOOK_URL

$RETURN_URL

"No return URL is configured for your account. Please provide the URL customers should be redirected to after payment completes. This must be a real route in your app that can handle the payment return/order status response."

• If it matches, call:

juspay-mcp:juspay_update_general_settings({ returnUrl: <user-provided URL> })

• If it does not match, warn the user:

"The URL you provided does not appear to exist in the current codebase as a return handler. Are you sure you want to use this?"

$RETURN_URL

juspay-mcp:juspay_create_api_key({ description: "integrate-skill-<product>-<date>" })

$API_KEY

"A new API key has been created for your account for testing this integration"

1. Required params — each required field the user must supply (skip auto-generated fields and anything already resolved: $MERCHANT_ID, $CLIENT_ID, $API_KEY, $WEBHOOK_URL)
2. Platform version check (SDK path only) — if docs specify a minimum version
3. Backend language — if not already detected from codebase

1. Auth / credentials setup — use environment variables, never hardcode values
2. Core integration — API call or SDK install → init → open → response handler
3. Webhook handler — if docs have a webhooks section; include signature verification
4. Status verification utility — if docs have a status/order API
5. DB schema — Read existing codebase to generate a DB schema for storing transaction/order IDs, statuses, and any other relevant info for reconciliation and status checks. Use field names from the docs.
   • Ask the user if they want to see the raw SQL or a Prisma/TypeORM/Mongoose schema based on their detected backend language/framework.
   • If the product has a status API, include fields for storing Juspay order/transaction IDs to correlate with their internal orders.
   • Generate validation rules based on any constraints mentioned in the docs (e.g. max length, required fields).
6. Error handling — use error codes from the docs to show how to handle different cases

• [credential from docs] stored as env var
• API key generated via dashboard or juspay-mcp

• Successful sandbox transaction
• Error case from $ERROR_CODES tested
• Webhooks verified end-to-end

• [stageDisplayName] ⚠️ Critical ← only if criticalResult is true [stageDescription]

- Do **not** show `status` — it is not updated in real time
- Mark stages with `criticalResult: true` as ⚠️ Critical
- Group stages by their parent section key

• Switched to production environment and keys
• Production end-to-end test passed

undefined

package.json

"dev"

npm run dev

yarn dev

pubspec.yaml

Important: Shell environment variables override

.env

files in Vite/Node. Before starting the server, check if any required env vars (e.g.

JUSPAY_API_KEY

) are already set in the shell and would conflict with the project's

.env

. Unset them if they don't belong to this project.

curl

1. Session / order creation endpoint — POST with a real order ID from the DB; expect a payment link back; verify

   juspay_order_id

   is written to the DB row.
2. Order status endpoint — GET with the Juspay order ID from step 1; expect a status response from Juspay.
3. Webhook endpoint — POST a synthetic

   ORDER_SUCCEEDED

   payload using the

   juspay_order_id

   from step 1; use

   curl -w "%{http_code}"

   and assert the HTTP status code is 200 (Juspay marks a webhook as "not notified" for any non-200 response and retries with progressive delays); also verify the body contains

   {"status":"ok"}

   and query the DB to confirm

   payment_status

   and

   juspay_payment_id

   were updated.
4. Webhook endpoint (failure) — POST a synthetic

   ORDER_FAILED

   payload; assert HTTP 200 and verify

   payment_status = failed

   in the DB.

• Read the server logs for the actual error message
• Diagnose and fix the root cause (wrong env var, bad header, type mismatch, etc.)
• Re-run until the test passes

$PRODUCT_TYPE = sdk

$PRODUCT_TYPE = hybrid

juspay-docs-mcp:doc_fetch_tool({ url: "<test-resources md content link from $DOC_MAP>" })

• $TEST_CARDS

  — card numbers, expiry, CVV for the Dummy PG / simulator

• $TEST_UPI_VPA

  — VPA values for UPI success/failure (e.g.

  success@upi

  ,

  failure@upi

  )

• $DUMMY_PG_FLOWS

  — how to trigger success vs failure for each payment method on the simulator

1. No product knowledge in this file. Product IDs, platform lists, and credential names come from

   products/

   or MCP responses — never from this file or training data.
2. Read

   products/

   before matching intent. Do not guess which product fits based on training-data familiarity.
3. Call

   explore_product

   before recommending. Phase 0D is mandatory. You must know the product's type and integration complexity before presenting it as a recommendation.
4. Never construct doc URLs. All URLs come from the

   md content link

   field in

   explore_product

   responses.
5. Never fabricate. If a page didn't load or a section wasn't in the docs, say so. Offer the raw URL for the user to check manually.
6. Product type comes from

   explore_product

   . Do not infer type from the product name or training data.
7. Platform list comes from

   $DOC_MAP

   . Present exactly the platforms that

   explore_product

   returned — no more, no less.
8. API-only products never get a platform question. If

   $DOC_MAP

   has no runtime platform IDs, skip platform selection entirely.
9. Code examples come from the docs. Use the exact method names, class names, and code structure from the fetched documentation pages as your source of truth.
10. Parameters come from the docs. The actual required fields are what the fetched pages say.
11. Code uses doc-sourced names only. If a method or class name doesn't appear in the fetched pages, do not use it.
12. Error codes come from the docs. Collect them from every page you fetch. Do not invent them.