UPI callbacks are a set of low-latency, server-to-server APIs that enable external Payment Service Provider (PSP) banking partners to integrate with Google Pay's backend and communicate asynchronous Unified Payments Interface (UPI) events from the National Payments Corporation of India (NPCI).
In the UPI ecosystem, Google Pay operates as a Third-Party Application Provider (TPAP) in partnership with regulated PSP banks. When a UPI transaction or account mapping update is initiated by a Google Pay user, an external UPI user, or a merchant, the request routes through NPCI. NPCI invokes the partner PSP to communicate incoming payment requests, settlement results, dispute adjustments, or UPI number mapping changes. The PSP then uses the UPI Callback API to synchronize these updates with Google Pay in real time.
These low-latency APIs use standardized, structured payloads designed to map cleanly from NPCI transaction messaging.
Note: Production endpoints, detailed API specifications, payload schemas, and integration guides are restricted to authorized PSP banking partners. Contact your Google representative to request allowlist access to the full partner documentation.
High-level use cases
Partner PSP banks use the UPI Callback API across three core use cases:
| Use case | Summary |
|---|---|
| Initiate incoming collect requests | Forwards an incoming peer-to-peer (P2P) or peer-to-merchant (P2M) UPI collect request from NPCI to Google Pay so the payer can review and authorize or decline the payment in the Google Pay app. |
| Send transaction confirmation and status notifications | Communicates transaction settlement results, incoming Virtual Payment Address (VPA) payments, collect request approvals or declines, debit and credit leg reversals, and customer dispute updates to Google Pay. |
| Send UPI number porting notifications | Notifies Google Pay when a user ports their 10-digit mobile number (UPI number) in NPCI's central UPI Mapper away from a Google Pay VPA to another VPA. |
Business logic and workflows
The UPI Callback API keeps Google Pay transaction state, user notifications, and VPA routing synchronized with NPCI and partner PSP systems through the following workflows.
1. Server-to-server authentication
All callback requests from a partner PSP to Google Pay require mutual partner onboarding, allowed service identities, and short-lived OAuth 2.0 server-to-server credentials over TLS:
- Partner identity allowlisting: During onboarding, the partner PSP registers a dedicated service identity that Google explicitly allowlists for the bank's assigned VPA namespace.
- Short-lived token exchange: The PSP authenticates its service identity with Google's authorization service to obtain short-lived OAuth 2.0 access tokens rather than relying on static API keys.
- Encrypted delivery: Each callback request is transmitted over TLS with the short-lived authorization token and validated against the partner's allowed identity before processing.
2. Initiating incoming collect requests
When an external user (for example, on BHIM or another UPI app) or a merchant initiates a collect ("pull") request targeting a Google Pay user's VPA:
- NPCI notification: NPCI routes the collect request to the PSP bank associated with the Google Pay user's VPA.
- Callback to Google Pay: The PSP forwards the collect request to
Google Pay, including:
- Core transaction context: Transaction and reference identifiers, payer and payee party context, requested payment amount, and the validity window for the collect request.
- Merchant and regulatory context (P2M flows): For merchant-initiated collect requests, the PSP also includes merchant classification metadata and applicable Goods and Services Tax (GST) or billing context.
- User review and authorization: Google Pay validates the request, enforces the expiration window to protect users from stale prompts, and sends an in-app notification so the payer can review the details and either authorize the payment using their UPI PIN or decline it.
3. Transaction confirmation and status notifications
Whenever NPCI sends a transaction confirmation, settlement update, or dispute update to a PSP for a transaction involving a Google Pay user, the PSP sends a status notification callback to Google Pay.
Supported transaction scenarios
The confirmation workflow covers five primary transaction scenarios:
- External collect resolution: A Google Pay user initiates a collect request targeting an external UPI user, and the external user approves or declines the request.
- Incoming VPA payment: An external UPI user sends a direct push payment to a Google Pay user's VPA.
- Outgoing VPA payment: NPCI confirms the final settlement status of a direct push payment initiated by a Google Pay user to any VPA.
- Collect approval confirmation: NPCI confirms the final settlement status after a Google Pay user approves an incoming collect request.
- Collect decline confirmation: NPCI confirms the final status after a Google Pay user declines or rejects an incoming collect request.
Settlement legs, reversals, and payment instruments
- Dual-leg settlement and reversal tracking: A UPI transaction settles across both a remitter (debit) leg and a beneficiary (credit) leg. The PSP reports the overall transaction status along with the individual status of each leg. If a failed debit or credit triggers an automatic reversal, the PSP communicates the reversal status for the affected leg so Google Pay can display accurate payment and refund progress to the user.
- Supported payment instruments: The callback identifies the underlying account type used for the transaction, supporting standard savings and current bank accounts, overdraft accounts, and RuPay credit cards linked to UPI.
- Risk and dispute updates: The PSP also forwards transaction risk signals and automated dispute or chargeback adjustments from NPCI so Google Pay can update the user's in-app transaction history and complaint resolution status.
4. UPI number porting notifications
NPCI's central UPI Mapper enables users to link their 10-digit mobile number as an interoperable UPI number mapped to a primary VPA. When a user ports their UPI number away from a Google Pay VPA to another VPA (either on an external UPI app or to a different PSP handle within Google Pay):
- NPCI porting notification: NPCI notifies the PSP associated with the user's previous VPA that the UPI number mapping has changed.
- Mapper synchronization: The PSP sends a porting callback to Google Pay to communicate the updated VPA mapping context.
- Routing state update: Google Pay updates its mapper records so subsequent phone-number-based UPI payments and notifications reflect the user's current VPA linkage.
5. Synchronous acknowledgment and delivery reliability
Google Pay processes and acknowledges callback requests synchronously so partner PSPs receive immediate confirmation of receipt. Callback handling is designed for high-throughput, idempotent event processing to prevent duplicate collect prompts or redundant status notifications during network retries.
Partner security, reliability, and onboarding
The Google Pay UPI Callback API is built for regulated PSP banking partners operating at national payment scale:
- Defense-in-depth access controls: API access is restricted to verified, allowed PSP service identities scoped to the partner bank's authorized VPA handle namespace, preventing unauthorized access or cross-partner spoofing.
- Customer transparency and reduced support load: Real-time synchronization of dual-leg settlement states, automatic reversals, and NPCI dispute updates gives users accurate, self-serve payment visibility in Google Pay, reducing customer-support inquiries for partner banks.
- Structured partner onboarding: Production endpoint URLs, service identifiers, and full integration specifications are provisioned during partner onboarding following security review and sandbox certification. Contact your Google representative to initiate onboarding and request allowlist access to the technical documentation.