P3P Quickstart – Build Agent-Native Payment Flows

Official Pine Labs developer documentation for integrating the Pine Labs Payment Protocol (P3P).

Supported rails

1. UPI ReservePay (available now) — Customer approves a mandate; each paid request debits the approved reserve
2. Cards (future scope) — P3P challenge/receipt unchanged; funding becomes card-specific
3. Crypto (future scope) — Wallet, signature, and settlement become rail-specific

Integration flow

1. Merchant onboarding yields PINELABS_CLIENT_ID and PINELABS_CLIENT_SECRET
2. Create mandate via server SDK before client paid routes
3. Customer approves mandate via UPI deep link in their banking app
4. decidePayment() wraps routes with challenge → verify → capture cycle
5. On HTTP 402, client SDK decodes challenge, creates one-time token, retries with P3P-Credential: Payment
6. Store Payment-Receipt with order/audit records

Environments

Sandbox credentials pair with P3PEnvironment.SANDBOX; production credentials with P3PEnvironment.PRODUCTION.

Security requirements

PINELABS_CLIENT_SECRET derives the local challenge HMAC key and must be stored securely. Confirm mandate limits, refund behavior, and receipt storage with Pine Labs integration owners before production launch.

Agent-native design

Documentation targets trusted backends and AI agents using client credentials or customer-key mode for customer API token integrations.