PhonePe payment integration

PhonePe implements the five required payment operations: charge, status, cancel, refund and refund_status. Each request is signed by Tringify. The app stores merchant credentials and installation authorization; Tringify owns the attempt, captured payments, checking schedule and refund state. The app stores no payment or refund ledger and never reports an outcome to Tringify.

Charge uses the Tringify session_id as PhonePe merchantOrderId and returns it as provider_session_id. The shopper opens PhonePe’s HTTPS checkout page and returns directly to the return_url supplied by Tringify. That navigation carries no payment result. A repeated charge uses the same merchant order reference. PhonePe supports INR payments with at most two decimal places and a minimum amount of 1.00.

The app derives PhonePe expireAfter from the attempt’s expires_at. PhonePe accepts an expiry between five minutes and one hour. Requests outside that range are refused with INVALID_EXPIRY; the app does not silently extend an attempt. Tringify decides how a late captured payment is applied or refunded.

Status reads the merchant order live from PhonePe with all attempt details. A paid answer lists every completed transaction with transaction_id, exact amount, currency_code and captured_at from PhonePe’s timestamp, represented as RFC 3339. An unavailable or incomplete provider response returns a retryable error. A missing timestamp is never replaced with the time of the status request.

PhonePe Standard Checkout has no API to close an order. Cancel therefore performs the same live read and answers the same StatusResponse as status. A paid response remains paid; a pending PhonePe order remains pending until its provider expiry or a later result. Cancellation is not evidence that money could not move.

Refund passes refund_id unchanged as PhonePe merchantRefundId, verifies the original captured transaction and uses the account holding that attempt. Repeated requests use the same refund reference. An uncertain or duplicate refund-create response is checked using that reference. refund_status reads PhonePe live and returns refunded, pending or failed. Refund amounts are INR, with at most two decimal places and a minimum of 1.00.

Verified PhonePe notifications send only an empty-body POST to the named payment attempt or refund wake endpoint. A wake never contains an outcome. It asks Tringify to call status or refund_status. Lost, repeated or late notifications cannot change the correctness of the payment result because Tringify checks the provider independently.

Changing or disconnecting an account stops new charges on it while retaining its credentials for live checks and refunds. Account lookups are bounded to 32 retained accounts per store. The app keeps at most 256 previous webhook credential records per store and refuses a credential change at the limit. It never discards a still-valid credential to make room. Both merchant admin hosts open the same embedded PhonePe Settings page; no separate mobile setting or plan limit is introduced.

The previous webhook credential remains valid until a notification verifies with its replacement, and then for another 72 hours. The app enforces this expiry on each credential lookup. Uninstall removes platform authorization; the store-data-erasure event removes secrets for the installation it names, without altering a newer installation.

A captured-payment response must include the provider’s payment time. A Hermes response without a payment timestamp cannot produce a paid answer and returns a retryable error. New charges and connection readiness therefore require PhonePe Standard Checkout credentials. Existing Hermes credentials remain available for historical refunds and signature verification. No timestamp is invented for an incomplete provider result.

Themes and sales channels use the normal platform checkout flow. Returning from PhonePe is navigation only; never infer paid status from a return URL or a PhonePe browser message. Store API consumers and MCP tools read Tringify’s recorded payment and refund state. Platform payment webhooks describe that recorded state. There is no PhonePe-specific result-reporting endpoint, MCP outcome-reporting tool or theme payment-state store.

See the Store API integration note, payment notifications, and checkout integration.