Pine Labs Online P3P Server SDK (Python)

Python SDK for Pine Labs Online P3P server integrations. It mirrors p3p-server-sdk, creates mandates, generates HTTP 402 payment challenges, verifies client credentials, captures payments through P3P, and builds Payment-Receipt headers.

Installation

pip install pinelabs-online-p3p-server-sdk[flask]
pip install pinelabs-online-p3p-server-sdk[fastapi]

Import module: pinelabs_p3p_server. Requires Python 3.9 or newer.

Config

from pinelabs_p3p_server import (
    P3PEnvironment,
    PaymentGateway,
    PaymentMethod,
    PineLabsOnlineServerConfig,
)

config = PineLabsOnlineServerConfig(
    clientId="...",
    clientSecret="...",
    merchantId="...",
    env=P3PEnvironment.SANDBOX,
    paymentGateway=PaymentGateway.PineLabsOnline,
    availablePaymentMethods=[PaymentMethod.RESERVE_PAY, PaymentMethod.OTM, PaymentMethod.CARD],
)

clientId, clientSecret, and merchantId are mandatory. The client credentials are used internally for POST /api/auth/v1/token; merchantId is sent as Merchant-ID on MPP calls for RESERVE_PAY, OTM, CARD, and CREDIT_EMI. Missing MID is rejected while creating the SDK, before any network call. The local challenge HMAC key is derived internally from clientSecret with a stable SDK prefix, so there is no separate challenge-signing config field. The SDK caches and refreshes bearer tokens before expiry. env selects the Pine Labs host used for auth and /mpp/v1/* service calls.

Environment defaults:

Mandates

from pinelabs_p3p_server import Amount, CreateMandateOptions, CreatePreAuthorizationOptions, PineLabsOnlineP3P

p3p = PineLabsOnlineP3P.create(config)
mandate = p3p.create_mandate(CreateMandateOptions(
    mobileNumber="9876543210",
    customerReference="9876543210",
    amount=Amount(value=100000, currency="INR"),
    paymentMethod=PaymentMethod.RESERVE_PAY,
    callbackUrl="https://merchant.example/payments/callback",
    validityInDays=20,
))

This maps to POST /mpp/v1/pre-authorize and sends customer.mobile_number. callbackUrl is serialized as the top-level callback_url field. The snake-case callback_url spelling is also accepted. The field remains optional for backward compatibility; when omitted, the SDK preserves the existing request shape.

Card pre-authorization uses the same endpoint and returns the service contract shape directly:

pre_authorization = p3p.create_pre_authorization(CreatePreAuthorizationOptions(
    paymentMethod=PaymentMethod.CREDIT_EMI,
    mobileNumber="9876543210",
    amount=Amount(value=1000, currency="INR"),
    callbackUrl="https://merchant.example/payments/callback",
    validityInDays=7,
    description="Credit EMI pre-auth for order-123",
    merchantMetadata={
        "p3p_offer_required": "true",
        # The discovery response filtered to the one selected
        # entity -> tenure -> offer.
        "offer_data": selected_offer_data,
    },
))

print(pre_authorization.payment_method_reference_id)
# `challenge_url` / `redirect_url` points at the hosted checkout where the
# customer completes 3DS / card authorization. Open it in an iframe or
# redirect the customer to it, then wait for the mandate to become ACTIVE
# before capturing.
print(pre_authorization.redirect_url or pre_authorization.challenge_url)

merchantMetadata.offer_data accepts the selected offer JSON object directly at the SDK boundary. The SDK serializes it into Pine's string-valued merchant metadata wire field; do not base64-encode it or include unselected entities, tenures, or offers. PaymentMethod.CREDIT_EMI is preserved as payment_method: "CREDIT_EMI" in the Pine pre-authorization request; the SDK never changes it to CARD.

End-to-End Card Payment

The full CARD flow uses payment_method_reference_id returned by create_pre_authorization to link the eventual debit back to the customer's authorized card:

import time

# 1. Create a card pre-authorization (customer completes the hosted checkout).
pre_auth = p3p.create_pre_authorization(CreatePreAuthorizationOptions(
    paymentMethod=PaymentMethod.CARD,
    mobileNumber="9876543210",
    amount=Amount(value=50000, currency="INR"),
    validityInDays=7,
))

# 2. Direct the customer to the checkout URL (iframe or redirect).
checkout_url = pre_auth.redirect_url or pre_auth.challenge_url

# 3. Poll the mandate until it becomes ACTIVE.
mandate = p3p.get_mandate(pre_auth.payment_method_reference_id)
while mandate.payment_status != "ACTIVE":
    time.sleep(2)
    mandate = p3p.get_mandate(pre_auth.payment_method_reference_id)

# 4. Charge the card via the standard 402 flow. The Server SDK issues a
#    Payment challenge and, once the Client SDK returns a Payment credential
#    that carries a token bound to this pre-auth, calls POST /mpp/v1/debit
#    with `payment_method_reference_id=pre_auth.payment_method_reference_id`.

On the client side, the Client SDK creates the payment token with paymentMethod=PaymentMethod.CARD — see the Client SDK README for the matching runtime context.

RAP card flows

RAP remains a CARD payment method. Pass a typed rapDetails value; the SDK nests it under payment_method_details.rap_details. MPP, not the SDK, creates the flattened PL_RAP_* metadata.

from pinelabs_p3p_server import (
    RAPAutonomousExecutionDetails,
    RAPAutonomousRegistrationDetails,
    RAPIntentConstraints,
    RAPOperation,
)

registration = p3p.create_pre_authorization(CreatePreAuthorizationOptions(
    paymentMethod=PaymentMethod.CARD,
    mobileNumber="9876543210",
    amount=Amount(value=500000, currency="INR"),
    validityInDays=56,
    rapDetails=RAPAutonomousRegistrationDetails(
        operation=RAPOperation.AUTONOMOUS_REGISTRATION,
        contractVersion="1",
        requestId="rap-aut-reg-001",
        intentId="intent-001",
        agentId="PL_AGENT_0001",
        agentName="Pine Labs Shopping Agent",
        consumerReference="consumer-001",
        intentConstraints=RAPIntentConstraints(
            bindingType="VERIFIED_NAMES",
            boundVerifiedNames="Vijay Sales,Croma",
            maxPerDrawMinor="150000",
            maxTotalMinor="500000",
            maxDraws="12",
            drawConfirmation="AUTO",
            validFrom="2026-09-01T00:00:00+05:30",
            validTill="2026-10-19T23:59:59+05:30",
        ),
    ),
))

result = p3p.capture(CaptureOptions(
    token=payment_token,
    amount=Amount(value=149900, currency="INR"),
    paymentMethod=PaymentMethod.CARD,
    mobileNumber="9876543210",
    rapDetails=RAPAutonomousExecutionDetails(
        operation=RAPOperation.AUTONOMOUS_EXECUTION,
        contractVersion="1",
        requestId="rap-aut-exec-001",
        registrationId=registration.payment_method_reference_id,
    ),
))

When RAP is present and no explicit idempotency key is supplied, the SDK uses rapDetails.requestId. For executions it also defaults challenge_id and payment_method_reference_id to registrationId. Authorised operations use the corresponding authorised registration/execution dataclasses and typed cart models.

Paid Resource Flow

from flask import Flask, jsonify
from pinelabs_p3p_server import Amount, ChargeOptions
from pinelabs_p3p_server.flask_mw import payment_required

app = Flask(__name__)

@app.get("/api/premium")
@payment_required(config, ChargeOptions(
    amount=Amount(value=50000, currency="INR"),
    resource="/api/premium",
))
def premium():
    return jsonify({"data": "premium content"})

The middleware reads P3P-Credential: Payment <payload>, not Authorization, so it does not conflict with application bearer auth.

Capture

from pinelabs_p3p_server import CaptureOptions

result = p3p.capture(CaptureOptions(
    token="MPP_TOK_123",
    amount=Amount(value=50000, currency="INR"),
    paymentMethod=PaymentMethod.RESERVE_PAY,
    customerReference="9876543210",
    mobileNumber="9876543210",
    challengeId="ch_123",
    merchantOrderReference="order-123",
))

The debit body uses customer.mobile_number, payment_amount, payment_token, and challenge_id. The SDK sends both Idempotency-Key and the configured Merchant-ID.

If /mpp/v1/debit returns 202 Accepted, the SDK treats that as an accepted-but-processing debit. It does not re-POST /mpp/v1/debit — Pine Labs rejects a resubmit with the same Idempotency-Key (422). Instead the SDK resolves the terminal status by polling the read-only endpoint GET /mpp/v1/debit/{id}:

• polls up to maxRetries times until the debit reaches a terminal status
• respects Retry-After from the 202 response when Pine Labs returns it
• falls back to initialRetryDelayMs otherwise
• genuine transient failures on the initial POST (network errors, HTTP 429, and 5xx) are still retried by the SDK's request layer

If the poll budget is exhausted and the debit is still non-terminal, the SDK returns a pending result (with idempotencyKey) and the middleware should return 202 without serving the protected resource. Application code can reconcile later via p3p.get_debit_status(idempotency_key).

Generic Middleware Helper

from pinelabs_p3p_server.server.middleware import decide_payment

decision = decide_payment(
    credential_header=request.headers.get("P3P-Credential"),
    config=config,
    charge_options=ChargeOptions(
        amount=Amount(value=50000, currency="INR"),
        resource="/api/premium-data",
    ),
)

To reconcile a pending debit later, use the status lookup helper:

latest = p3p.get_debit_status("idem_key_123")

This calls GET /mpp/v1/debit/{id} and returns the same debit payload family as the original debit call, so application code can resolve pending payments by idempotency key.

License

MIT