MCP Request Format

This section provides technical details for developers building custom MCP clients or integrating with PayU Remote MCP programmatically.

PayU Remote MCP uses the JSON-RPC 2.0 protocol over HTTP. All requests are sent to a single endpoint with OAuth 2.1 bearer token authentication.

Service Endpoint

Authentication Header

All requests must include an OAuth bearer token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Obtaining Access Tokens

Access tokens are obtained through the OAuth 2.1 flow:

1. Initiate authorization request with PKCE
2. User authenticates via browser
3. Receive authorization code
4. Exchange code for access token
5. Use token in Authorization header

📘

Note

Most MCP clients handle token management automatically. You only need to implement this if building a custom client.

Tool Call Format

Request Structure

POST https://api.payu.in/mcp
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "TOOL_NAME",
    "arguments": {
      "param1": "value1",
      "param2": "value2"
    }
  },
  "id": 1
}

Request Fields

Response Format

Successful Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Result of the tool call"
      }
    ]
  }
}

Response Fields

Error Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32600,
    "message": "Invalid Request",
    "data": {
      "details": "Additional error information"
    }
  }
}

Error Codes

Example Requests

List Tools

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "params": {},
  "id": 1
}

Get Transaction Details

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get-transaction-details",
    "arguments": {
      "transactionId": "TX-98765"
    }
  },
  "id": 2
}

Process Refund

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "process-refund",
    "arguments": {
      "transactionId": "TX-12345",
      "amount": 500.00,
      "reason": "Customer request"
    }
  },
  "id": 3
}

HTTP Headers

Required Headers

Optional Headers

Rate Limiting

The service implements rate limiting to ensure fair usage:

• Rate limits are applied per merchant account
• Exceeding limits returns HTTP 429 (Too Many Requests)
• Include Retry-After header indicates wait time

Best Practices

1. Reuse Connections - Use HTTP keep-alive for better performance
2. Handle Errors Gracefully - Implement proper error handling for all response codes
3. Implement Retry Logic - Retry failed requests with exponential backoff
4. Validate Responses - Always validate the response structure before processing
5. Log Request IDs - Include unique request IDs for debugging

Next Steps

• MCP Tools: Check all available tools and their parameters
• MCP FAQs: Refer the Frequently Asked Questions if you are facing issues with MCP.