Quickstart

Create a checkout session server-side, redirect the customer, then fulfill only after a confirmed webhook.

1. Install the Node SDK

Copynpm install @pinetreepayments/node

2. Create a checkout session

Copyimport { PineTree } from "@pinetreepayments/node"

const pinetree = new PineTree(process.env.PINETREE_API_KEY)

const session = await pinetree.checkout.sessions.create(
  {
    amount: 2500,
    currency: "USD",
    reference: "order_1042",
    customer: {
      email: "jane@example.com"
    },
    successUrl: "https://yoursite.com/paid",
    cancelUrl: "https://yoursite.com/cancel",
    metadata: {
      cartId: "cart_123"
    }
  },
  {
    idempotencyKey: "order_1042"
  }
)

res.redirect(session.checkoutUrl)

3. Verify webhooks before fulfillment

Copyapp.post(
  "/webhooks/pinetree",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    let event

    try {
      event = pinetree.webhooks.constructEvent(
        req.body,
        req.headers,
        process.env.PINETREE_WEBHOOK_SECRET
      )
    } catch (error) {
      return res.status(400).send("Invalid webhook signature")
    }

    if (await alreadyProcessed(event.eventId)) {
      return res.json({ received: true, duplicate: true })
    }

    if (event.type === "payment.confirmed") {
      await fulfillOrder(event.data.object.reference)
      await markProcessed(event.eventId)
    }

    res.json({ received: true })
  }
)

Use express.raw() or the equivalent raw-body handler in your framework. Do not JSON-parse the request body before verifying the webhook signature.

Authentication

Use secret keys on your server. Use browser keys only for public checkout creation. Never expose secret API keys in frontend code.

Required server headers

CopyAuthorization: Bearer pt_live_your_api_key_here
Content-Type: application/json

Optional idempotency header

CopyIdempotency-Key: order_1042

The Idempotency-Key header is optional but strongly recommended on POST /api/v1/checkout/sessions to prevent duplicate sessions on retries.

Browser checkout header

CopyX-PineTree-Public-Key: pk_live_your_public_key_here
Content-Type: application/json

Security requirement: Never use pt_live_* keys in frontend JavaScript, browser code, mobile apps, or public repositories. Revoke any secret key that may have been exposed.

API Keys

Create narrowly scoped keys from the Developer area. Use the smallest scope set required for each integration. Secret keys are only shown once at creation time.

Recommended environment variables

CopyPINETREE_API_KEY=pt_live_a1b2c3d4e5f6...
PINETREE_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_PINETREE_PUBLIC_KEY=pk_live_...

Permissions

Best practices

1. Grant only the scopes required for the integration.
2. Use separate keys for different services or environments.
3. Store secret keys in environment variables or a secrets manager.
4. Monitor last-used timestamps in the dashboard.
5. Revoke compromised or unused keys.

Checkout Sessions

Checkout Sessions create hosted payment pages. Create sessions from your server and fulfill orders only after confirmed webhook events.

checkoutUrl is opaque: Redirect customers directly to checkoutUrl. Do not construct or parse this URL manually.

Copy{
  "amount": 2500,
  "currency": "USD",
  "reference": "order_1042",
  "customer": {
    "email": "jane@example.com"
  },
  "successUrl": "https://yoursite.com/paid",
  "cancelUrl": "https://yoursite.com/cancel",
  "metadata": {
    "cartId": "cart_123"
  },
  "rails": ["solana", "base"]
}

Copy{
  "id": "cs_01abc",
  "object": "checkout.session",
  "status": "open",
  "amount": 2500,
  "currency": "USD",
  "reference": "order_1042",
  "customer": {
    "email": "jane@example.com"
  },
  "metadata": {
    "cartId": "cart_123"
  },
  "checkoutUrl": "https://app.pinetree-payments.com/checkout/tok_01abc...",
  "paymentId": null,
  "supportedRails": ["solana", "base", "bitcoin_lightning"],
  "successUrl": "https://yoursite.com/paid",
  "cancelUrl": "https://yoursite.com/cancel",
  "createdAt": "2026-06-22T12:00:00.000Z",
  "expiresAt": "2026-06-23T12:00:00.000Z"
}

Copy{
  "object": "list",
  "data": [
    {
      "id": "cs_01abc",
      "object": "checkout.session",
      "status": "open"
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJjcmVhdGVkQXQiOi..."
}

Browser Checkout

Browser checkout lets your frontend create a limited Checkout Session using a public browser key. Public keys are safe to embed in browser JavaScript, but they can only create checkout sessions.

Public key limitation: pk_live_* keys cannot retrieve payments, list webhook deliveries, retry webhooks, or access private merchant data.

Fetch example

Copyconst response = await fetch(
  "https://app.pinetree-payments.com/api/v1/browser/checkout/sessions",
  {
    method: "POST",
    headers: {
      "X-PineTree-Public-Key": "pk_live_your_public_key_here",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      amount: 2500,
      currency: "USD",
      reference: "order_1042",
      successUrl: window.location.origin + "/paid",
      cancelUrl: window.location.origin + "/cancel"
    })
  }
)

const session = await response.json()
window.location.href = session.checkoutUrl

JavaScript SDK

Copynpm install @pinetreepayments/js

Copyimport { PineTreeJS } from "@pinetreepayments/js"

const ptjs = new PineTreeJS("pk_live_your_public_key_here")

const session = await ptjs.checkout.createSession({
  amount: 2500,
  currency: "USD",
  reference: "order_1042",
  successUrl: window.location.origin + "/paid",
  cancelUrl: window.location.origin + "/cancel"
})

ptjs.checkout.open(session)

React SDK

Copynpm install @pinetreepayments/react

Copyimport { PineTreeProvider, PineTreeCheckoutButton } from "@pinetreepayments/react"

export function App() {
  return (
    <PineTreeProvider publicKey="pk_live_your_public_key_here">
      <CheckoutButton />
    </PineTreeProvider>
  )
}

function CheckoutButton() {
  return (
    <PineTreeCheckoutButton
      amount={2500}
      currency="USD"
      reference="order_1042"
      successUrl={window.location.origin + "/paid"}
      cancelUrl={window.location.origin + "/cancel"}
    >
      Pay with Crypto
    </PineTreeCheckoutButton>
  )
}

Payments

Use Payments for reconciliation, status lookup, and back-office workflows. Use webhook events as the primary fulfillment signal.

Status naming: The visible state Confirmed maps to API status paid. Do not check for status === "confirmed". For polling, check status === "paid". For fulfillment, use payment.confirmed.

Payment object

Example response

Copy{
  "id": "pay_01abc",
  "object": "payment",
  "status": "paid",
  "amount": 2500,
  "currency": "USD",
  "rail": "solana",
  "asset": "USDC",
  "reference": "order_1042",
  "checkoutSessionId": "cs_01abc",
  "confirmedAt": "2026-06-22T18:00:05.000Z",
  "metadata": {
    "cartId": "cart_123"
  }
}

Session Statuses

Checkout Session status tracks the aggregate lifecycle of the session. Session status and Payment status are related but not always identical.

For fulfillment, use payment.confirmed or checkout.session.completed webhooks. Use session retrieval for UI state and reconciliation.

Rails & Assets

Rails are payment paths. Assets are what the customer pays on that path. PineTree stores and returns both values separately.

Token-specific tracking

PineTree does not combine the rail and asset into one rail name. Instead, both values are stored and returned separately.

Do not combine rail and asset: Use rail for the payment path and asset for what the customer paid.

Restrict rails on a session

Copy{
  "amount": 2500,
  "currency": "USD",
  "rails": ["solana", "base"]
}

Card processing: Shift4 card processing is available for approved merchants. Stripe and Fluid Pay are early-access card provider paths and are not generally public card-processing rails yet.

Payment States

Confirmed is the successful visible payment state. Failed, Expired, and Incomplete are separate terminal outcomes.

The visible state Confirmed maps to status: "paid" in the API Payment object. Do not check status === "confirmed".

Webhooks

Webhook deliveries are signed with PineTree headers. Verify the raw body before processing.

Signature formula

Copysigned_payload = PineTree-Timestamp + "." + raw_request_body
expected_signature = HMAC_SHA256(webhook_secret, signed_payload)

Verification

Copyconst event = pinetree.webhooks.constructEvent(
  req.body,
  req.headers,
  process.env.PINETREE_WEBHOOK_SECRET
)

Use raw request body verification. Return 2xx only after durable processing. PineTree delivers events at least once, so store PineTree-Event-Id and deduplicate.

Webhook Payload

Every PineTree webhook is delivered as a JSON object with a standard payments-v1 envelope.

Event envelope

Copy{
  "eventId": "evt_01abc",
  "object": "event",
  "type": "payment.confirmed",
  "schema": "payments-v1",
  "createdAt": "2026-06-22T18:00:00.000Z",
  "livemode": true,
  "data": {
    "object": {
      "id": "pay_01abc",
      "object": "payment",
      "status": "paid",
      "network": "solana",
      "amount": 2500,
      "currency": "USD",
      "reference": "order_1042",
      "confirmedAt": "2026-06-22T18:00:05.000Z",
      "metadata": {
        "cartId": "cart_123"
      }
    }
  }
}

network vs rail: Webhook payment events use network for the rail identifier. The REST Payment object uses rail for the same concept. Use event.data.object.network inside webhook handlers.

Webhook Events

Implemented merchant webhook events in the payments-v1 schema.

Use the canonical event names above for new integrations.

Webhook Deliveries

Use Webhook Deliveries to inspect delivery history and retry failed events.

Delivery statuses

Retry schedule

Node SDK retry

Copyconst delivery = await pinetree.webhookDeliveries.retry("wdel_01abc")
console.log(delivery.status)

Errors

Errors return a consistent JSON structure with a type, code, message, and request ID.

Copy{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "A PineTree API key is required.",
    "requestId": "req_01abc"
  }
}

Common error codes

Idempotency

Use idempotency keys to safely retry Checkout Session creation without duplicate sessions.

REST example

CopyPOST /api/v1/checkout/sessions HTTP/1.1
Authorization: Bearer pt_live_...
Content-Type: application/json
Idempotency-Key: order_1042

{
  "amount": 2500,
  "currency": "USD",
  "reference": "order_1042"
}

Node SDK example

Copyconst session = await pinetree.checkout.sessions.create(
  {
    amount: 2500,
    currency: "USD",
    reference: "order_1042"
  },
  {
    idempotencyKey: "order_1042"
  }
)

Use a stable, unique value per order. Do not reuse the same idempotency key for different orders.

SDKs

Use the Node SDK on servers, the JavaScript SDK in browser flows, and the React SDK for checkout components.

SDK packages are available to approved early-access merchants. Contact info@pinetree-payments.com for access.

Node SDK

Copynpm install @pinetreepayments/node

Copyimport { PineTree } from "@pinetreepayments/node"

const pinetree = new PineTree(process.env.PINETREE_API_KEY)

const session = await pinetree.checkout.sessions.create({
  amount: 2500,
  currency: "USD",
  reference: "order_1042"
})

const payment = await pinetree.payments.retrieve("pay_01abc")

const deliveries = await pinetree.webhookDeliveries.list({
  status: "failed"
})

await pinetree.webhookDeliveries.retry("wdel_01abc")

JavaScript SDK

Copynpm install @pinetreepayments/js

React SDK

Copynpm install @pinetreepayments/react

Testing

PineTree currently uses live keys only. There is no separate sandbox or test-mode key prefix. Test with small live amounts and an HTTPS tunnel for local webhook development.

Copyngrok http 3000

# Register your HTTPS URL in Developer - Webhooks
https://abc123.ngrok-free.app/webhooks/pinetree

Testing checklist

1. Create a checkout session.
2. Complete a small live payment.
3. Verify payment.confirmed arrives.
4. Replay the same event and confirm deduplication.
5. Test failed, expired, and incomplete paths.
6. Temporarily return 500 and verify webhook retry behavior.

Go Live

Complete these checks before accepting real payments at volume.

Do not fulfill based on the customer redirect alone. Always rely on verified webhook events.

Not Yet Supported

The following capabilities are planned for future PineTree API versions. They are not required for the current hosted checkout and webhook integration flow.

Support

Contact PineTree for integration help, API access, SDK issues, and merchant onboarding questions.

Include this in support requests

1. Merchant account email or merchant ID.
2. API endpoint used.
3. requestId from the error response.
4. Checkout Session ID.
5. Payment ID.
6. Webhook Event ID.
7. Error type and code.
8. Approximate timestamp in UTC.