Description

n8n-nodes-phonepe

This n8n community node lets you integrate PhonePe Payment Gateway into your workflows. It supports payment creation, status checking, refunds, and secure webhook verification.

🚀 Features

• Create Payment Links – Generate UPI payment links for customers
• Check Payment Status – Query transaction status in real-time
• Process Refunds – Initiate full or partial refunds
• Verify Webhooks – Cryptographically validate PhonePe callbacks to prevent fraud

📦 Installation

Community Nodes (Recommended)

1. Go to Settings > Community Nodes in your n8n instance
2. Click Install and enter: n8n-nodes-phonepe
3. Agree to the risks and click Install

Manual Installation

npm install n8n-nodes-phonepe

For self-hosted n8n, restart your instance after installation.

🔐 Credentials Setup

You'll need PhonePe merchant credentials to use this node:

1. Merchant ID – Your unique merchant identifier (e.g., PGTESTPAYUAT86)
2. Salt Key – Secret key for checksum generation
3. Salt Index – Usually 1 (check your PhonePe dashboard)

Getting Test Credentials

For development, use PhonePe's sandbox environment:

• Merchant ID: PGTESTPAYUAT86
• Salt Key: 099eb0cd-02cf-4e2a-8aca-3e6c6aff0399
• Salt Index: 1

⚠️ Never use sandbox credentials in production!

Getting Production Credentials

1. Register at PhonePe Merchant Dashboard
2. Complete KYC verification
3. Find credentials under Settings > API Keys

🎯 Operations

1. Create Payment Link

Generate a payment link for customers to complete UPI payments.

Inputs:

• Transaction ID (max 35 alphanumeric characters)
• Amount in INR (minimum ₹1)
• Redirect URL (where to send customers after payment)
• Callback URL (webhook endpoint for payment updates)

Output:

{
  "success": true,
  "code": "PAYMENT_INITIATED",
  "data": {
    "merchantId": "PGTESTPAYUAT86",
    "merchantTransactionId": "TX123456",
    "instrumentResponse": {
      "type": "PAY_PAGE",
      "redirectInfo": {
        "url": "https://mercury-uat.phonepe.com/transact/pg?token=..."
      }
    }
  }
}

2. Check Payment Status

Query the current status of any transaction.

Inputs:

• Transaction ID of the payment to check

Output:

{
  "success": true,
  "code": "PAYMENT_SUCCESS",
  "data": {
    "merchantId": "PGTESTPAYUAT86",
    "merchantTransactionId": "TX123456",
    "transactionId": "T2411191234567890123456",
    "amount": 10000,
    "state": "COMPLETED"
  }
}

3. Refund Payment

Initiate a full or partial refund for completed transactions.

Inputs:

• Original Transaction ID
• Refund Amount in INR (must be > 0 and ≤ original amount)

Output:

{
  "success": true,
  "code": "PAYMENT_PENDING",
  "data": {
    "merchantId": "PGTESTPAYUAT86",
    "merchantTransactionId": "TX123456_REFUND_1700123456789",
    "transactionId": "TR2411191234567890123456",
    "amount": 5000,
    "state": "PENDING"
  }
}

4. Verify Webhook

🔒 Security Feature – Validate that webhook callbacks are genuinely from PhonePe, not spoofed by attackers.

Why This Matters:
Without verification, an attacker could send fake "payment successful" webhooks to your system, causing you to ship products without receiving payment.

Inputs:

• Webhook Payload (base64) – The response field from PhonePe's callback
• X-VERIFY Header – The signature header from the webhook request

Output:

{
  "isValid": true,
  "status": "VERIFIED",
  "message": "Webhook signature is valid",
  "webhookData": {
    "merchantId": "PGTESTPAYUAT86",
    "transactionId": "T2411191234567890123456",
    "amount": 10000,
    "state": "COMPLETED"
  }
}

📝 Example Workflows

Basic Payment Flow

1. Manual Trigger
   ↓
2. PhonePe Node → Create Payment Link
   ↓
3. Send Email with payment link

Webhook Verification Flow

1. Webhook Trigger (receives PhonePe callback)
   ↓
2. PhonePe Node → Verify Webhook
   ↓
3. IF Node → Check if "isValid" is true
   ↓
   ├─ TRUE  → Update database, Send confirmation
   └─ FALSE → Log security alert, Notify admin

Refund Processing

1. Customer requests refund
   ↓
2. PhonePe Node → Check Payment Status
   ↓
3. IF Node → Check if state is "COMPLETED"
   ↓
4. PhonePe Node → Refund Payment
   ↓
5. Send refund confirmation email

🔒 Security Best Practices

1. Always Verify Webhooks

Never trust webhook data without verification. Use the "Verify Webhook" operation before processing payments.

2. Use HTTPS Callback URLs

PhonePe requires HTTPS endpoints for production. Use ngrok or similar tools for local testing.

3. Validate Transaction IDs

The node validates that transaction IDs are:

• Alphanumeric (letters, numbers, hyphens, underscores)
• Maximum 35 characters
• Unique per transaction

4. Rate Limiting

Implement rate limiting in your workflows to prevent API abuse. PhonePe may suspend accounts that exceed rate limits.

5. Store Credentials Securely

• Never commit credentials to version control
• Use n8n's encrypted credential storage
• Rotate salt keys periodically in production

🐛 Troubleshooting

"Invalid X-VERIFY header"

• Cause: Incorrect salt key or salt index
• Solution: Verify credentials in PhonePe dashboard

"Transaction ID already exists"

• Cause: Duplicate transaction ID
• Solution: Generate unique IDs (append timestamp: TX${Date.now()})

"Amount must be greater than 0"

• Cause: Invalid amount input
• Solution: Ensure amount is a positive number in INR

"Webhook signature is invalid"

• Cause: Webhook may be spoofed or credentials don't match
• Solution: Verify you're using the correct merchant credentials

🧪 Testing

See TESTING.md for detailed testing instructions with the sandbox environment.

📚 Resources

• PhonePe API Documentation
• n8n Community Nodes
• PhonePe Merchant Dashboard

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request with tests

📄 License

MIT

💬 Support

• Issues: GitHub Issues
• Questions: n8n Community Forum
• Email: mhp8195@gmail.com

⚠️ Disclaimer

This is a community-maintained node, not officially supported by PhonePe. Use at your own risk and ensure compliance with PhonePe's terms of service.

Built with ❤️ for the n8n community