canonical: https://jentic.com/apis/phonepe.com/phonepe

# PhonePe Payment Gateway API

Jentic publishes the only available OpenAPI specification for PhonePe Payment Gateway API, keeping it validated and agent-ready. PhonePe provides a payment gateway for Indian digital payments supporting UPI, credit cards, debit cards, and net banking. The API covers payment initiation, transaction status checks, refund processing, and VPA (Virtual Payment Address) validation across 6 endpoints designed for merchants integrating PhonePe as a payment method in India.

## For AI agents

Initiate payments, check transaction status, process refunds, and validate UPI VPA addresses through PhonePe's Indian payment gateway supporting UPI and card payments.

## Scope

Does not handle international payments, subscription billing, or payout disbursements - use for Indian domestic payment collection via UPI and cards only.

## Capabilities

- Initiate payment transactions via UPI, credit card, debit card, or net banking in India
- Check real-time transaction status by merchant transaction ID
- Process full or partial refunds for completed payment transactions
- Validate UPI Virtual Payment Addresses before initiating payments
- Track refund status by merchant ID and transaction reference
- Support SHA256-based request verification for secure server-to-server communication

## Use cases

### E-Commerce Payment Collection in India

Accept payments from Indian customers through UPI, credit cards, debit cards, and net banking via PhonePe's payment gateway. The API handles payment page redirection, transaction processing, and callback notifications. PhonePe processes over 5 billion UPI transactions monthly, making it one of the largest payment processors in India.

Example prompt: Create a payment request for INR 999 via UPI with a merchant transaction ID and redirect the customer to the PhonePe payment page

### Transaction Status Verification

Verify payment outcomes programmatically after a customer completes or abandons a payment flow. The status endpoint returns the current state of any transaction by merchant ID and transaction reference, enabling order fulfillment systems to confirm payment before shipping. Supports both synchronous polling and callback-based notification.

Example prompt: Query the transaction status endpoint for merchant ID MERCHANT123 and transaction ID TXN456 to confirm whether the payment succeeded

### Refund Processing

Issue refunds for completed transactions when orders are cancelled or returned. PhonePe supports full and partial refunds credited back to the original payment method. The refund status endpoint lets you track whether the refund has been processed and when funds were returned to the customer.

Example prompt: Submit a refund request for INR 499 on transaction TXN456 under merchant MERCHANT123 and verify the refund status

### AI Agent Payment Processing via Jentic

AI agents handling Indian e-commerce workflows can initiate payments and check transaction status through Jentic without managing PhonePe credentials directly. The agent searches for UPI payment operations, loads the schema including the SHA256 verification header format, and executes calls with Jentic handling cryptographic signing.

Example prompt: Search Jentic for 'initiate a UPI payment in India', load the PhonePe pay operation schema, and execute a payment request for INR 1500 with a generated merchant transaction ID

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/pg/v1/pay` | Initiate a payment transaction via UPI, card, or net banking |
| GET | `/pg/v1/status/{merchantId}/{merchantTransactionId}` | Check payment transaction status |
| POST | `/pg/v1/refund` | Initiate a refund for a completed transaction |
| GET | `/pg/v1/refund/{merchantId}/{merchantTransactionId}` | Check refund status |
| GET | `/v3/transaction/{merchantId}/{transactionId}/status` | Legacy transaction status check (v3) |
| POST | `/pg/v1/validate/vpa` | Validate a UPI Virtual Payment Address |

## Key resources

- **Payments** — Initiate payment transactions and check their status
- **Refunds** — Process and track refunds for completed payments
- **VPA Validation** — Validate UPI Virtual Payment Addresses before transactions

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 63 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 100 / 100
  - Developer Experience & Jentic Compatibility: 60 / 100
  - AI-Readiness & Agent Experience: 45 / 100
  - Agent Usability: 94 / 100
  - Security: 50 / 100
  - AI Discoverability: 67 / 100
- **View full report:** https://jentic.com/apis/phonepe.com/phonepe/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the PhonePe Payment Gateway API by hand means computing its SHA256 X-VERIFY header from the payload, endpoint, and salt key on each request against api.phonepe.com/apis/hermes, and choosing between production and preprod hosts yourself. Through Jentic you install once, import the PhonePe Payment Gateway API from the API Directory, store the salt credentials once, and your agent calls it.
- **Permission scoping:** PhonePe puts the merchant and transaction ids in the URL path (`/pg/v1/status/{merchantId}/{merchantTransactionId}`, `/pg/v1/refund/{merchantId}/{merchantTransactionId}`), so a rule can pin your agent to reading status for your merchant; the pay, refund, and VPA validate operations carry their target in the request body, so there you limit the agent to the operations it needs. You choose the operations it may call, so initiating a payment or a refund is not included unless you add it.
- **Credential handling:** Your PhonePe salt key and salt index are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'check a UPI payment status', and Jentic returns the matching PhonePe operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Cashfree API** — Indian payment gateway supporting UPI, cards, wallets, and bank transfers
- **Stripe API** — Global payment processing with Indian payment method support including UPI
- **Twilio API** — SMS notifications for payment confirmations and OTP delivery

## FAQ

### Why is there no official OpenAPI spec for PhonePe Payment Gateway API?

PhonePe does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call PhonePe Payment Gateway API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the PhonePe Payment Gateway API use?

PhonePe uses a SHA256-based verification header called X-VERIFY. It is computed as SHA256(base64EncodedPayload + endpoint + saltKey) concatenated with the salt index. Through Jentic, the salt key is stored in your Jentic One instance and the verification header is computed automatically at execution time.

### Can I validate a UPI VPA before initiating payment?

Yes. Use POST `/pg/v1/validate/vpa` to check whether a Virtual Payment Address is valid and active before sending a payment request. This prevents failed transactions due to incorrect or inactive UPI addresses.

### What payment methods does the PhonePe API support?

The POST `/pg/v1/pay` endpoint supports UPI (collect and intent), credit cards, debit cards, and net banking. The payment method is specified in the request payload. UPI is the most common method, handling both same-device and cross-device flows.

### How do I check transaction status through Jentic?

Search Jentic for 'check PhonePe payment status' to find the GET `/pg/v1/status/{merchantId}/{merchantTransactionId}` operation. Load the schema, provide your merchant ID and transaction reference, and execute. Jentic handles the X-VERIFY header computation using your stored salt key.

### How long does a PhonePe refund take to process?

Refund processing time depends on the original payment method. UPI refunds typically complete within 1-5 business days. Use GET `/pg/v1/refund/{merchantId}/{merchantTransactionId}` to track the current refund status programmatically.

### Can I limit what my agent is allowed to do with the PhonePe Payment Gateway API?

Yes. Because you run Jentic One yourself, your own rules decide which PhonePe operations and credentials the agent may use. Since the merchant and transaction IDs sit in the URL path for GET `/pg/v1/status/{merchantId}/{merchantTransactionId}` and GET `/pg/v1/refund/{merchantId}/{merchantTransactionId}`, you can pin the agent to reading status for your own merchant. The pay, refund, and VPA-validate operations carry their target in the request body, so you grant only the ones the agent needs; initiating a payment or a refund is excluded unless you add it.