Quickstart

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

Step 1 — Install the Node SDK

npm install @pinetreepayments/node

Then create an API key in your PineTree dashboard under Developer → API Keys. Copy the full pt_live_* key — it is only shown once.

Step 2 — Create a Checkout Session

Call this from your server. Never from a browser.

import { PineTree } from "@pinetreepayments/node"

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

const session = await pinetree.checkout.sessions.create({
  amount: 49.99,
  currency: "USD",
  reference: "order_1042",
  successUrl: "https://yoursite.com/paid",
  cancelUrl: "https://yoursite.com/cancel"
})

res.redirect(session.checkoutUrl)

Step 3 — Configure Your Webhook Endpoint

In your PineTree dashboard, go to Developer → Webhooks. Add your HTTPS endpoint URL and copy the signing secret. The endpoint must be publicly reachable and return a 2xx response after durable processing.

Step 4 — Verify and Fulfill

app.post("/webhooks/pinetree", express.raw({ type: "application/json" }), (req, res) => {
  const event = pinetree.webhooks.constructEvent(
    req.body,
    req.headers,
    process.env.PINETREE_WEBHOOK_SECRET
  )

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

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

Authentication

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

Key Types

Required Headers (Server)

Authorization: Bearer pt_live_your_api_key_here
Content-Type: application/json

Optional Header

Idempotency-Key: order_1042

The Idempotency-Key header is optional but strongly recommended on POST /api/v1/checkout/sessions. See Idempotency for details.

Browser Checkout Header

When creating checkout sessions from browser code, use a public key instead of a secret key:

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

Public keys (pk_live_*) are created and revoked from Developer → API Keys → Public Keys in your PineTree dashboard, the same way secret keys are managed.

Invalid Credentials

PineTree issues pt_live_* keys only. There is no pt_test_* variant. All keys operate against live payment infrastructure.

API Keys

Create permission-limited keys from the Developer area. Use the smallest permission set required for each integration. Secret keys are only shown once at creation time.

Secret Keys

Secret keys (pt_live_*) authenticate server-to-server REST requests. Store them in environment variables, not in source code or configuration files that may be committed to version control.

# .env
PINETREE_API_KEY=pt_live_a1b2c3d4e5f6...
PINETREE_WEBHOOK_SECRET=your_webhook_signing_secret

Public Browser Keys

Public keys (pk_live_*) are safe to embed in browser JavaScript. They can only create checkout sessions and cannot access payments, webhook deliveries, or any private merchant data.

Permissions

Best Practices

• Grant only the permissions required for the specific integration.
• Use separate keys for different services or environments.
• Revoke any key that may have been accidentally exposed.
• Monitor Last Used timestamps in the dashboard to identify stale keys.
• Store secret keys in a secrets manager or environment variables — never in code.

Checkout Sessions

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

Create a Session

Request body

{
  "amount": 49.99,                     // required — major currency units. 49.99 means $49.99
  "currency": "USD",                   // optional — defaults to "USD"
  "reference": "order_1042",           // optional — your order/cart ID
  "customer": {
    "email": "jane@example.com"        // optional
  },
  "successUrl": "https://yoursite.com/paid",
  "cancelUrl":  "https://yoursite.com/cancel",
  "metadata": { "cartId": "cart_123" },
  "rails": ["solana", "base"]          // optional — limit available payment methods
}

Response

{
  "id": "3f9a1c2e-4b6d-4a11-9c2f-8e1a6d2b7f40",
  "object": "checkout.session",
  "status": "open",
  "amount": 49.99,
  "currency": "USD",
  "reference": "order_1042",
  "customer": { "email": "jane@example.com" },
  "metadata": { "cartId": "cart_123" },
  "checkoutUrl": "https://app.pinetree-payments.com/checkout/8f2a1b9c3d4e5f60",
  "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"
}

List Sessions

// List response envelope
{
  "object": "list",
  "data": [ /* checkout.session objects */ ],
  "hasMore": true,
  "nextCursor": "eyJjcmVhdGVkQXQiOi..."
}

Retrieve a Session

Cancel a Session

Expire a Session

Session Statuses

Sessions that are not explicitly canceled or expired will expire automatically after 24 hours.

Browser Checkout

Create checkout sessions from browser code using a public key. Public keys are safe to embed in frontend JavaScript and cannot access private merchant data.

Browser Checkout Endpoint

Raw Fetch Example

const 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: 49.99,
      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

npm install @pinetreepayments/js

import { PineTreeJS } from "@pinetreepayments/js"

const ptjs = new PineTreeJS("pk_live_your_public_key_here")

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

React SDK

npm install @pinetreepayments/react

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

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

function CheckoutPage() {
  return (
    <PineTreeCheckoutButton
      amount={49.99}
      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 payment.confirmed webhooks — not polling — for order fulfillment.

Retrieve a Payment

Payment Object Fields

Payment Object

{
  "id": "3f9a1c2e-4b6d-4a11-9c2f-8e1a6d2b7f40",
  "object": "payment",
  "status": "paid",
  "amount": 49.99,
  "currency": "USD",
  "rail": "solana",
  "network": "solana",
  "reference": "order_1042",
  "metadata": {},
  "createdAt": "2026-06-22T17:59:30.000Z",
  "updatedAt": "2026-06-22T18:00:05.000Z"
}

Status Mapping

Session Statuses

Checkout Session status tracks the aggregate state of the session, which may span multiple payment attempts. Session status and Payment status use similar but not identical labels.

Providers, Rails & Assets

Rails are payment paths. Assets are what the customer pays on that path.

Supported Rails

Card processing via Shift4 is available to approved merchants through the PineTree merchant onboarding flow. Contact info@pinetree-payments.com to apply. Additional card processors are available in early access.

Provider vs. Rail vs. Asset

A provider is the company powering payments — the external payment platform or processor that moves the money (Shift4, Stripe, FluidPay, Speed). A rail is the payment network — the path a Checkout Session travels on (solana, base, bitcoin_lightning, shift4, stripe, fluidpay). An asset is the currency/token the customer actually pays with (SOL, USDC, ETH, BTC, USD).

solana and base are native PineTree rails: there is no separate third-party processor behind them, so the rail identifier is the provider, and both are live today. bitcoin_lightning, shift4, stripe, and fluidpay each have a distinct backing provider — see the table below for current availability.

Providers

Rail and Asset by Payment Type

Restricting Rails on a Session

Pass the optional rails array when creating a session to limit which payment methods are offered on the hosted checkout page:

{
  "amount": 49.99,
  "currency": "USD",
  "rails": ["solana", "base"]    // only show Solana and Base options
}

Payment States

Confirmed is the positive visible payment state and the only state that should trigger order fulfillment. All other terminal states — Failed, Expired, Incomplete — must never trigger fulfillment.

State Lifecycle

  CREATED → PENDING → PROCESSING → CONFIRMED  (status: "paid")
                                  └→ FAILED     (status: "failed")
             └→ INCOMPLETE                      (status: "incomplete")
  CREATED → EXPIRED                             (status: "expired")

Webhooks

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

Setup

1. Go to Developer → Webhooks in your PineTree dashboard.
2. Enter your HTTPS endpoint URL. HTTP endpoints are not accepted.
3. Copy the signing secret shown on the page. It is only shown once.
4. Store the secret as PINETREE_WEBHOOK_SECRET in your environment.

Webhook Headers

Signature Formula

PineTree signs each delivery with HMAC-SHA256 over the timestamp and the raw request body:

signed_payload    = PineTree-Timestamp + "." + raw_request_body
expected_sig      = HMAC_SHA256(webhook_secret, signed_payload)
header_sig        = PineTree-Signature header value

// Verified if: constant_time_equals(expected_sig, header_sig)
// and: abs(now - PineTree-Timestamp) < 300 seconds

Verification — Node SDK

// CRITICAL: Use express.raw() — do NOT parse the body before this call
app.post(
  "/webhooks/pinetree",
  express.raw({ type: "application/json" }),
  (req, res) => {
    let event
    try {
      event = pinetree.webhooks.constructEvent(
        req.body,
        req.headers,
        process.env.PINETREE_WEBHOOK_SECRET
      )
    } catch (err) {
      return res.status(400).send("Signature verification failed")
    }

    const alreadySeen = await checkAndStoreEventId(event.eventId)
    if (alreadySeen) return res.json({ received: true })

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

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

Reliability Rules

• PineTree delivers events at least once. Your endpoint must handle duplicate events idempotently.
• Return a 2xx response only after writing event data to durable storage.
• If your endpoint returns a non-2xx, PineTree will retry with backoff — see Webhook Deliveries.
• Do not fulfill orders based on the customer redirect URL alone. Always wait for payment.confirmed.

Webhook Payload

Every PineTree webhook is delivered as a JSON object with a standard payments-v1 envelope. The event type, schema, and event ID are at the top level. The payment or session object is inside data.object.

Event Envelope

{
  "eventId":   "evt_01abc...",          // unique — store for deduplication
  "object":    "event",
  "type":      "payment.confirmed",
  "schema":    "payments-v1",
  "createdAt": "2026-06-22T18:00:00.000Z",
  "livemode":  true,
  "data": {
    "object": { /* payment or checkout.session object */ }
  }
}

Payment Event Payload

{
  "eventId":   "evt_01abc...",
  "object":    "event",
  "type":      "payment.confirmed",
  "schema":    "payments-v1",
  "createdAt": "2026-06-22T18:00:00.000Z",
  "livemode":  true,
  "data": {
    "object": {
      "id":          "3f9a1c2e-4b6d-4a11-9c2f-8e1a6d2b7f40",
      "object":      "payment",
      "status":      "paid",
      "network":     "solana",
      "amount":      49.99,
      "currency":    "USD",
      "reference":   "order_1042",
      "confirmedAt": "2026-06-22T18:00:05.000Z",
      "metadata":    { "cartId": "cart_123" }
    }
  }
}

Checkout Session Event Payload

{
  "eventId":   "evt_02def...",
  "object":    "event",
  "type":      "checkout.session.completed",
  "schema":    "payments-v1",
  "createdAt": "2026-06-22T18:00:05.000Z",
  "livemode":  true,
  "data": {
    "object": {
      "id":             "3f9a1c2e-4b6d-4a11-9c2f-8e1a6d2b7f40",
      "object":         "checkout.session",
      "status":         "paid",
      "amount":         49.99,
      "currency":       "USD",
      "reference":      "order_1042",
      "customer":       { "email": "jane@example.com" },
      "metadata":       { "cartId": "cart_123" },
      "checkoutUrl":    "https://app.pinetree-payments.com/checkout/8f2a1b9c3d4e5f60",
      "paymentId":      "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",
      "supportedRails": ["solana", "base", "bitcoin_lightning"],
      "successUrl":     "https://yoursite.com/paid",
      "cancelUrl":      "https://yoursite.com/cancel",
      "createdAt":      "2026-06-22T17:59:00.000Z",
      "expiresAt":      "2026-06-23T17:59:00.000Z"
    }
  }
}

Payment Event Object Fields

Webhook Events

Implemented merchant webhook events in the payments-v1 schema. Use eventId to deduplicate — PineTree delivers at least once.

Payment Events

Checkout Session Events

Payment Link Events

Legacy Events

Legacy event aliases from prior API versions are accepted and normalized to their canonical equivalents. Use the canonical event names listed above for all new integrations.

Webhook Deliveries

Use Webhook Deliveries to inspect delivery history, debug failed events, and manually trigger retries from your server tooling or automation.

// List response envelope
{
  "object": "list",
  "data": [ /* webhook.delivery objects */ ],
  "hasMore": false,
  "nextCursor": null
}

// Node SDK — manual retry
const delivery = await pinetree.webhookDeliveries.retry("6c7d8e9f-0a1b-4c2d-9e3f-4a5b6c7d8e9f")
console.log(delivery.status)         // "delivered" if retry succeeded
console.log(delivery.attemptCount)   // total attempts including this retry

Webhook Delivery Object

{
  "id": "6c7d8e9f-0a1b-4c2d-9e3f-4a5b6c7d8e9f",
  "object": "webhook.delivery",
  "eventType": "payment.confirmed",
  "status": "delivered",
  "attemptCount": 1,
  "nextAttemptAt": null,
  "lastAttemptAt": "2026-06-22T18:00:06.000Z",
  "lastStatusCode": 200,
  "lastError": null,
  "deliveredAt": "2026-06-22T18:00:06.000Z",
  "deadLetteredAt": null,
  "createdAt": "2026-06-22T18:00:00.000Z"
}

Delivery Statuses

Automatic Retry Schedule

PineTree retries failed deliveries with backoff. After 10 failed attempts the delivery moves to dead_letter.

Use POST /api/v1/webhook-deliveries/{id}/retry to manually retry a dead_letter delivery after fixing the issue on your endpoint.

Errors

All errors return a consistent JSON structure with a type, code, message, and requestId. Include the requestId when contacting support.

Error Response Shape

{
  "error": {
    "type":      "authentication_error",
    "code":      "missing_api_key",
    "message":   "A PineTree API key is required.",
    "requestId": "3f9a1c2e-4b6d-4a11-9c2f-8e1a6d2b7f40"
  }
}

Error Types

Common Error Codes

Node SDK

The Node SDK throws V1ApiError on any non-2xx response, carrying the same type, code, and requestId shown above. Check error.type/error.code to branch your handling.

Idempotency

Add an Idempotency-Key header to POST /api/v1/checkout/sessions to safely retry the request without creating duplicate sessions. The key is optional but strongly recommended for any production integration.

How It Works

REST Example

POST /api/v1/checkout/sessions HTTP/1.1
Authorization: Bearer pt_live_...
Content-Type: application/json
Idempotency-Key: order_1042          ← use your stable order ID

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

Node SDK Example

const session = await pinetree.checkout.sessions.create(
  {
    amount: 49.99,
    currency: "USD",
    reference: "order_1042",
    successUrl: "https://yoursite.com/paid",
    cancelUrl:  "https://yoursite.com/cancel",
  },
  { idempotencyKey: "order_1042" }
)

Best Practices

• Use a stable, unique value per order — your order ID or cart ID is ideal.
• Do not reuse the same idempotency key for different orders.
• On network failure or timeout, retry with the same idempotency key and same body.
• If you receive a 409 idempotency_key_conflict, do not retry — generate a new session for the new request.

SDKs

PineTree provides official SDKs for Node.js (server), JavaScript (browser), and React. Use the Node SDK for all server-side operations. Use the JS and React SDKs with public browser keys only.

Node SDK — @pinetreepayments/node

npm install @pinetreepayments/node

Use on your server with a pt_live_* secret key. Requires Node.js 18+.

import { PineTree } from "@pinetreepayments/node"

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

// Checkout Sessions
const session = await pinetree.checkout.sessions.create(
  { amount: 49.99, currency: "USD", reference: "order_1042" },
  { idempotencyKey: "order_1042" }
)
await pinetree.checkout.sessions.retrieve(session.id)
await pinetree.checkout.sessions.list({ status: "paid", limit: 20 })
await pinetree.checkout.sessions.cancel(session.id)
await pinetree.checkout.sessions.expire(session.id)

// Payments — retrieve only; there is no payments.list()
const payment = await pinetree.payments.retrieve("3f9a1c2e-4b6d-4a11-9c2f-8e1a6d2b7f40")
// → payment.status === "paid" means confirmed

// Webhook Deliveries
const deliveries = await pinetree.webhookDeliveries.list({ status: "failed" })
await pinetree.webhookDeliveries.retry("6c7d8e9f-0a1b-4c2d-9e3f-4a5b6c7d8e9f")

// Verify a webhook signature
const event = pinetree.webhooks.constructEvent(
  req.body,           // raw Buffer — must be raw, not parsed
  req.headers,
  process.env.PINETREE_WEBHOOK_SECRET
)

JavaScript SDK — @pinetreepayments/js

npm install @pinetreepayments/js

Use in browser environments with a pk_live_* public key. Cannot use secret keys.

import { PineTreeJS } from "@pinetreepayments/js"

const ptjs = new PineTreeJS("pk_live_your_public_key_here")

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

ptjs.checkout.open(session)   // redirects to hosted checkout

React SDK — @pinetreepayments/react

npm install @pinetreepayments/react

React components and hooks for checkout buttons. Uses @pinetreepayments/js under the hood with a pk_live_* public key.

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

export function Providers({ children }) {
  return (
    <PineTreeProvider publicKey="pk_live_your_public_key_here">
      {children}
    </PineTreeProvider>
  )
}

export function BuyButton({ orderId, amount }) {
  return (
    <PineTreeCheckoutButton
      amount={amount}
      currency="USD"
      reference={orderId}
      successUrl={`${window.location.origin}/paid`}
      cancelUrl={`${window.location.origin}/cancel`}
    >
      Pay with Crypto
    </PineTreeCheckoutButton>
  )
}

Testing

PineTree currently issues only pt_live_* keys — there is no separate PineTree sandbox or test-mode environment. Test PineTree integrations with small live amounts and an HTTPS tunnel for local webhook development.

Test Webhooks Locally

Use an HTTPS tunnel to expose your local server to PineTree's webhook delivery:

ngrok http 3000

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

Integration Test Checklist

• Happy path — Create session → customer pays → payment.confirmed received → order fulfilled.
• Failed payment — payment.failed received → order not fulfilled.
• Expired session — Session times out → payment.expired received → order not fulfilled.
• Incomplete session — Customer abandons → payment.incomplete received → order not fulfilled.
• Duplicate delivery — Replay the same event ID → your handler skips fulfillment on the second call.
• Signature tampered — Modify the payload → constructEvent throws → handler returns 400.
• Idempotent creation — Create session twice with same Idempotency-Key → same session returned, no duplicate.
• Webhook retry — Make your endpoint return 500 → verify retry appears in Webhook Deliveries list.

Useful Environment Variables

PINETREE_API_KEY=pt_live_a1b2c3d4...
PINETREE_WEBHOOK_SECRET=your_webhook_signing_secret
NEXT_PUBLIC_PINETREE_PUBLIC_KEY=pk_live_...  # browser usage

Go-Live Checklist

Complete all items before accepting real customer payments at volume.

API Keys & Credentials

• Secret API key created with the minimum required permissions.
• Secret key stored in environment variables, not in source code.
• Secret key is not present in any frontend bundle, browser console, or public repository.
• Public browser key (pk_live_*) used for all frontend checkout flows.

Webhooks

• Webhook endpoint is HTTPS only.
• Webhook signing secret stored as PINETREE_WEBHOOK_SECRET.
• PineTree-Signature verified on every incoming event using raw body.
• Body is not JSON-parsed before calling constructEvent.
• Endpoint returns 2xx after durable write, not before.
• PineTree-Event-Id stored and checked to deduplicate at-least-once delivery.
• Dead-letter deliveries are monitored and alerted on.

Payment Flows

• Orders are fulfilled only after payment.confirmed.
• Customer redirect to successUrl does not trigger fulfillment alone.
• payment.failed, payment.expired, payment.incomplete never trigger fulfillment.
• Happy path tested end-to-end with a small live transaction.
• Failed and expired flows tested.
• Duplicate event handling verified.

Rails & Providers

• At least one payment rail is configured and verified in the merchant dashboard.
• Treasury wallet addresses are verified for each enabled crypto rail.
• If Shift4 card processing is enabled: merchant application is approved for production processing.
• If Stripe card processing is enabled (early access): Connect account is active with the capabilities your integration needs — Connect, Payments, Terminal — enabled.
• If FluidPay card processing is enabled (early access): merchant onboarding and provider approval are complete.
• Session successUrl and cancelUrl are production HTTPS URLs.

Not Yet Supported

The following capabilities are planned for future PineTree API versions. None of these are required for the current hosted checkout and webhook integration pattern.

Support

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

Contact

What to Include in a Support Request

Include the following in support requests: merchant account email, API endpoint, requestId from the error response, Checkout Session ID, Payment ID, webhook Event ID, error type and code, and approximate timestamp (UTC).

Common Questions