---
title: P3P Client and Server SDKs
slug: ai/p3p/sdks
hidden: false
sidebar_order: 3
metadata:
  title: P3P SDKs – SDK Libraries for Agentic Commerce & Paid APIs
  description: >-
    Pine Labs P3P SDKs — TypeScript and Python client/server SDKs for
    Machine     Payment Protocol. Install p3p-client-sdk and p3p-server-sdk    
    for automated HTTP 402 handling, payment token creation, and verifiable    
    receipts.
sidebar_label: P3P SDKs
excerpt: >-
  Install and use Pine Labs P3P Client and Server SDKs for TypeScript and  
  Python.
---

SDKs handle the protocol mechanics — challenges, tokens, retries, capture, and receipts — so your code stays focused on the business logic. Every HTTP interaction remains observable for debugging, but you never construct headers or manage token lifecycles manually.

## Install SDK

<CodeTabs>
  <Tab label="TypeScript">    

          ```bash
# Client
              npm i p3p-client-sdk

# Server
              npm i p3p-server-sdk
  ```    

       <br/>
        <div style="padding:0 10px">
          #### Get TypeScript SDK from npm:

        <CardGrid>
        <Card title="Client SDK" description="p3p-client-sdk on npm" href="https://www.npmjs.com/package/p3p-client-sdk/v/0.1.6" icon="package" />
        <Card title="Server SDK" description="p3p-server-sdk on npm" href="https://www.npmjs.com/package/p3p-server-sdk/v/0.1.4" icon="package" />
        </CardGrid>

<table>
  <thead>
    <tr>
      <th style={{ width: "15%" }}>Variant</th>
      <th style={{ width: "35%" }}>Main import</th>
      <th style={{ width: "50%" }}>What it does</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong>Client</strong></td>
      <td><code>PineLabsOnlineClient</code> from <code>p3p-client-sdk</code></td>
      <td>Creates one-time payment tokens, handles <code>402</code>, retries with <code>P3P-Credential: Payment</code>, and reads receipts.</td>
    </tr>
    <tr>
      <td><strong>Server</strong></td>
      <td><code>PineLabsOnlineP3P</code> or <code>decidePayment</code> from <code>p3p-server-sdk</code></td>
      <td>Creates mandates, prices routes, returns challenges, verifies credentials, captures payment, and returns <code>Payment-Receipt</code>.</td>
    </tr>
  </tbody>
</table>

  </div>
    </Tab>

    <Tab label="Python">
     
             ```bash
          # Client
                pip install pinelabs-online-p3p-client-sdk

          # Server
                pip install pinelabs-online-p3p-server-sdk
            ```

        <br/>
        <div style="padding:0 10px">
        #### Get Python SDK from PyPI:

        <CardGrid>
        <Card title="Client SDK" description="pinelabs-online-p3p-client-sdk on PyPI" href="https://pypi.org/project/pinelabs-online-p3p-client-sdk/0.1.4/" icon="package" />
        <Card title="Server SDK" description="pinelabs-online-p3p-server-sdk on PyPI" href="https://pypi.org/project/pinelabs-online-p3p-server-sdk/0.1.3/" icon="package" />
        </CardGrid>

        ---

<table>
  <thead>
    <tr>
      <th style={{ width: "15%" }}>Variant</th>
      <th style={{ width: "35%" }}>Main import</th>
      <th style={{ width: "50%" }}>What it does</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong>Client</strong></td>
      <td>
        <code>PineLabsOnlineClient</code> from
        <code>pinelabs_p3p_client</code>
      </td>
      <td>
        Creates tokens, handles <code>402</code>, retries through
        <code>httpx</code> with <code>P3P-Credential: Payment</code>, and
        reads receipts.
      </td>
    </tr>
    <tr>
      <td><strong>Server</strong></td>
      <td>
        <code>PaymentRequired</code> from
        <code>pinelabs_p3p_server.fastapi_mw</code>
      </td>
      <td>
        Creates mandates, protects FastAPI routes, returns challenges,
        captures payment, and attaches <code>Payment-Receipt</code>.
      </td>
    </tr>
  </tbody>
</table>

        </div>
    </Tab>
</CodeTabs>

---

## Client Paid Request Example

<Tabs>
<Tab label="TypeScript">

```ts
import {
  P3PCustomerAuthMode,
  P3PEnvironment,
  PaymentMethod,
  PineLabsOnlineClient
} from "p3p-client-sdk";

const client = PineLabsOnlineClient.create({
  selectedPaymentMethod: PaymentMethod.RESERVE_PAY,
  clientId: process.env.PINELABS_CLIENT_ID!,
  clientSecret: process.env.PINELABS_CLIENT_SECRET!,
  env: P3PEnvironment.SANDBOX,
});

const response = await client.get(
  "https://server.example.com/api/weather",
  {},
  {
    customerReference: "customer-ref-123",
    mobileNumber: "9876543210"
  }
);

```

</Tab>
<Tab label="Python">

```python
from pinelabs_p3p_client import (
    ClientRuntimeContext,
    P3PCustomerAuthMode,
    P3PEnvironment,
    PaymentMethod,
    PineLabsOnlineClient,
    PineLabsOnlineClientConfig,
)

client = PineLabsOnlineClient.create(PineLabsOnlineClientConfig(
    selectedPaymentMethod=PaymentMethod.RESERVE_PAY,
    env=P3PEnvironment.SANDBOX,
    clientId="client-client-id",
    clientSecret="client-client-secret",
))

response = client.get(
    "https://server.example.com/api/weather",
    context=ClientRuntimeContext(
        customerReference="customer-ref-123",
        mobileNumber="9876543210",
    ),
)

```

</Tab>
</Tabs>

---

## Server Route Protection Example

<Tabs>
<Tab label="TypeScript">

```ts
import {
  Amount,
  ChargeOptions,
  P3PEnvironment,
  PaymentGateway,
  PaymentMethod,
  decidePayment
} from "p3p-server-sdk";

const decision = await decidePayment({
  credentialHeader: request.headers.get("P3P-Credential") ?? undefined,
	  config: {
	    clientId: process.env.PINELABS_CLIENT_ID!,
	    clientSecret: process.env.PINELABS_CLIENT_SECRET!,
	    paymentGateway: PaymentGateway.PineLabsOnline,
    availablePaymentMethods: [PaymentMethod.RESERVE_PAY],
	    env: P3PEnvironment.SANDBOX,
    realm: P3PEnvironment.SANDBOX
  },
  chargeOptions: new ChargeOptions(new Amount(10000, "INR"), "/api/weather")
});
```

</Tab>
<Tab label="Python">

```python
import os
from fastapi import Depends, FastAPI
from pinelabs_p3p_server import (
    Amount,
    ChargeOptions,
    P3PEnvironment,
    PaymentGateway,
    PaymentMethod,
    PineLabsOnlineServerConfig,
)
from pinelabs_p3p_server.fastapi_mw import PaymentRequired

app = FastAPI()
config = PineLabsOnlineServerConfig(
  clientId=os.environ["PINELABS_CLIENT_ID"],
  clientSecret=os.environ["PINELABS_CLIENT_SECRET"],
  paymentGateway=PaymentGateway.PineLabsOnline,
  availablePaymentMethods=[PaymentMethod.RESERVE_PAY],
  env=P3PEnvironment.SANDBOX,
)

require_payment = PaymentRequired(
    config,
    ChargeOptions(amount=Amount(value=10000, currency="INR"), resource="/api/weather"),
)

@app.get("/api/weather", dependencies=[Depends(require_payment)])
async def weather():
    return {"forecast": "Clear", "paid": True}
```

</Tab>
</Tabs>

---

## SDK Methods Reference

| Helper | Use |
|---|---|
| `client.get/post/put/delete/patch/request` | Call server endpoints with automatic `402` handling |
| `client.methods.createToken` / `client.methods.create_token` | Create a one-time payment token |
| `PineLabsOnlineP3P.create(config).createMandate(...)` / `PineLabsOnlineP3P.create(config).create_mandate(...)` | Create UPI ReservePay payment capacity for a customer |
| `decidePayment` / `decide_payment` | Framework-agnostic route helper for challenge, verification, capture, and receipts |
| `PineLabsOnlineP3P.create(config)` | Create a server SDK instance for lower-level control |

---

## Headers

| Header | Direction | Meaning |
| --- | --- | --- |
| `WWW-Authenticate` | Server to client | Carries the unpaid request challenge with amount, resource, and expiry. |
| `P3P-Credential` | Client to server | Carries the payment credential on retry. |
| `Payment-Receipt` | Server to client | Carries receipt details after capture succeeds. |


## Protocol Objects

| Object | Purpose |
| --- | --- |
| Mandate | Customer-approved payment capacity for the current UPI ReservePay rail. |
| Challenge | Server-signed payment requirement returned in `WWW-Authenticate`. |
| Token | Short-lived Pine Labs payment token created by the client SDK. |
| Credential | Client retry header: `P3P-Credential: Payment <payload>`. |
| Capture | Server-side debit request to Pine Labs P3P. |
| Receipt | Server response header: `Payment-Receipt: Payment <payload>`. |


## Resources

<div className="not-prose card-grid-2">
  <div className="card-grid-item">
    <h4>P3P Quickstart</h4>
    <p>Build your first paid endpoint end-to-end </p>
    <a href="../p3p/quickstart">View Docs →</a>
  </div>
  <div className="card-grid-item">
    <h4>P3P Overview</h4>
    <p>Protocol architecture and concepts</p>
    <a href="../p3p">View Docs →</a>
  </div>
</div>