Migration Guide - Pandabase

Who this is for

This guide is for teams that currently use the Pandabase Store API (with individual store credentials) and want to migrate to the Platform API for centralized merchant management, fee splitting, and unified reporting. If you are building a new integration from scratch, start with the Platform Overview instead.

Before you begin

Make sure you have:

An approved Platform Partner account with plt_ and psk_ credentials
Access to the Platform sandbox environment
A list of existing stores you want to migrate to platform-managed merchants

You do not need to shut down your Store API integration before starting the migration. Both APIs can operate in parallel during the transition period.

Key differences

Authentication

	Store API	Platform API
Credential	Bearer token (`stk_`) or HMAC (`shk_`)	Platform ID (`plt_`) + HMAC-SHA512 (`psk_`)
Scope	Single store	All merchants on your platform
Merchant context	Implicit (bound to token)	Explicit (`X-Merchant-Context` header)
Signing algorithm	HMAC-SHA256	HMAC-SHA512

What to change: Replace your Authorization: Bearer stk_xxx header with the platform authentication scheme. Every request that targets a specific merchant must include the X-Merchant-Context header.

Payments

	Store API	Platform API
Object	Checkout session	Platform Intent
Endpoint	`POST /v2/checkouts`	`POST /v2/platforms/intents`
Fee control	No (Pandabase fee only)	Yes (`platformFee` field)
Capture modes	Automatic only	Automatic or manual
Refund window	30 days	180 days
Multi-merchant	No	Yes (via `X-Merchant-Context`)

What to change: Replace checkout session creation with Platform Intent creation. Add your platformFee to each intent. If you need to verify orders before charging, use captureMethod: "manual".

Merchants

	Store API	Platform API
Creation	Manual signup on pandabase.io	Programmatic via Provisioning API
Verification	Self-service by merchant	Pandabase.js Verification SDK embedded in your flow
Management	Each merchant manages their own store	Your platform manages all merchants centrally
Capabilities	All enabled by default	Granular, per-merchant, controlled by your platform

What to change: Instead of giving each merchant a Pandabase account, provision them as sub-accounts through the Provisioning API. Embed the Verification SDK in your onboarding flow.

Settlements

	Store API	Platform API
Schedule	Merchant requests payouts manually	T+2 automatic settlement to merchants
Fee splitting	Not available	Automatic platform fee on every transaction
Platform payouts	Not applicable	Weekly platform fee payouts
Holds and transfers	Not available	Full Money Management API

What to change: Remove any manual payout logic. The settlement pipeline handles distribution automatically. Use the Money Management API if you need holds, transfers, or on-demand payouts.

Webhooks

	Store API	Platform API
Events	`PAYMENT_*` events	`INTENT_`, `MERCHANT_`, `SETTLEMENT_*` events
Scope	Per store	Platform-wide (includes merchant context)
Signing	HMAC-SHA256	HMAC-SHA512
Configuration	Per store in dashboard	Platform-level via API

What to change: Update your webhook endpoint to handle the new event names and payload structure. Update signature verification to use HMAC-SHA512.

Migration steps

Step 1: Set up your platform integration

Build and test the Platform API integration in the sandbox environment alongside your existing Store API integration. Both can run in parallel.

Configure platform authentication

Implement the HMAC-SHA512 signing logic using your psk_ secret. Test against the sandbox API.

import crypto from "crypto";

function signRequest(method: string, path: string, body: string, timestamp: number, secret: string): string {
  const canonical = [
    method.toUpperCase(),
    path,
    timestamp.toString(),
    crypto.createHash("sha256").update(body || "").digest("hex"),
  ].join("\n");
  return crypto.createHmac("sha512", secret).update(canonical).digest("hex");
}

Set up platform webhooks

Test merchant provisioning

Create test merchants in the sandbox and verify the full lifecycle: provisioning, verification, capability activation.

Test Platform Intents

Create test intents against sandbox merchants. Verify payment completion, webhook delivery, and settlement.

Step 2: Migrate existing merchants

For each existing Pandabase store that you want to bring under platform management, provision a new merchant sub-account.

POST /v2/platforms/merchants
Authorization: Platform plt_xxx
X-Platform-Signature: {signature}

{
  "externalId": "existing_store_stk_xxx",
  "businessName": "Existing Merchant",
  "email": "merchant@example.com",
  "country": "US",
  "category": "DIGITAL_PRODUCTS",
  "onboardingTier": "STANDARD",
  "capabilities": {
    "payments": true,
    "subscriptions": false,
    "payouts": true
  },
  "metadata": {
    "migratedFrom": "stk_xxx",
    "migrationDate": "2026-03-20"
  }
}

Migrated merchants go through the standard compliance review process. Existing verification from their direct Pandabase account does not carry over automatically. Contact platforms@pandabase.io to discuss expedited review for bulk migrations.

Keep a mapping between the old store credentials and the new merchant IDs. You will need this during the traffic cutover.

Step 3: Update payment creation

Replace checkout session creation with Platform Intent creation. Map your existing payment logic to the new API. Before (Store API):

const checkout = await fetch("https://api.pandabase.io/v2/checkouts", {
  method: "POST",
  headers: {
    Authorization: "Bearer stk_xxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    items: [{ productId: "prod_xxx", quantity: 1 }],
    metadata: { orderId: "order_123" },
  }),
});

After (Platform API):

const timestamp = Date.now();
const body = JSON.stringify({
  amount: 4999,
  currency: "USD",
  description: "Pro Plan",
  customer: { email: "buyer@example.com" },
  lineItems: [{ name: "Pro Plan", amount: 4999, quantity: 1 }],
  platformFee: 500,
  returnUrl: "https://yourplatform.com/success",
  metadata: { orderId: "order_123" },
});

const signature = signRequest(
  "POST",
  "/v2/platforms/intents",
  body,
  timestamp,
  PSK_SECRET,
);

const intent = await fetch("https://api.pandabase.io/v2/platforms/intents", {
  method: "POST",
  headers: {
    Authorization: "Platform plt_xxx",
    "X-Platform-Signature": signature,
    "X-Merchant-Context": "shp_provisioned_xxx",
    "X-Request-Timestamp": timestamp.toString(),
    "X-Idempotency-Key": `intent_order_123`,
    "Content-Type": "application/json",
  },
  body,
});

Step 4: Update webhook handling

Add handlers for Platform API events alongside your existing Store API handlers. Event mapping:

Store API event	Platform API event
`PAYMENT_PENDING`	`INTENT_CREATED`
`PAYMENT_PROCESSING`	`INTENT_PROCESSING`
`PAYMENT_COMPLETED`	`INTENT_COMPLETED`
`PAYMENT_FAILED`	`INTENT_FAILED`
`PAYMENT_REFUNDED`	`INTENT_REFUNDED`
`PAYMENT_DISPUTED`	`INTENT_DISPUTED`
`PAYMENT_DISPUTE_WON`	`INTENT_DISPUTE_WON`
`PAYMENT_DISPUTE_LOST`	`INTENT_DISPUTE_LOST`
(no equivalent)	`MERCHANT_*` events
(no equivalent)	`SETTLEMENT_*` events

Before (Store API verification):

import crypto from "crypto";

function verifyStoreWebhook(
  body: string,
  signature: string,
  timestamp: string,
  secret: string,
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(timestamp + "." + body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(expected, "hex"),
  );
}

After (Platform API verification):

import crypto from "crypto";

function verifyPlatformWebhook(
  body: string,
  signature: string,
  timestamp: string,
  secret: string,
): boolean {
  const expected = crypto
    .createHmac("sha512", secret)
    .update(timestamp + "." + body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(expected, "hex"),
  );
}

Step 5: Update frontend payment flow

If you use Pandabase.js for payment forms, update the initialization to use your platform credentials. Before (Store API):

const pandabase = Pandabase.init("stk_xxx", { mode: "production" });

After (Platform API):

const pandabase = Pandabase.init("plt_xxx", { mode: "production" });

const payment = pandabase.createPaymentElement({
  clientSecret, // from your Platform Intent creation response
  appearance: {
    theme: "auto",
    variables: { colorPrimary: "#0071e3" },
  },
});

payment.mount("#payment-container");

Step 6: Cut over traffic

Once your Platform API integration is tested and all merchants are provisioned:

Enable dual-write

For a transition period, create both a checkout session and a Platform Intent for each payment. Route customers to the Platform Intent. Keep the Store API path as a fallback.

Monitor

Verify that Platform Intent payments are completing successfully, webhooks are being delivered, and settlements are processing. Compare completion rates between the two paths.

Disable Store API path

Once you are confident the Platform API is working correctly, remove the Store API payment path. Stop creating checkout sessions.

Revoke old credentials

Revoke the individual stk_ and shk_ tokens for each migrated store. This prevents any residual traffic from hitting the old endpoints.

Step 7: Clean up

After the migration is complete:

Remove Store API authentication code
Remove Store API webhook handlers
Remove the old credential mapping
Update internal documentation and runbooks
Notify merchants (if applicable) about any changes to their experience

Parallel operation

During migration, both APIs can run simultaneously without conflict. Payments created through the Store API and Platform API are completely independent. There is no risk of duplicate charges or settlement conflicts. The only constraint is that a single payment must be created through one API or the other. You cannot create a checkout session and a Platform Intent for the same transaction.

Timeline

There is no deadline to complete the migration. You can run both APIs indefinitely if needed. However, once all merchants are provisioned on the Platform API, there is no benefit to maintaining the Store API integration. For most platforms, the migration takes 2 to 4 weeks:

Week	Milestone
1	Platform API integration built and tested in sandbox
2	Merchants provisioned and verified
3	Dual-write enabled, traffic gradually shifted
4	Store API path disabled, old credentials revoked

Common issues

Merchants stuck in PENDING_REVIEW

Merchants provisioned during migration go through the standard compliance review. If review is taking longer than expected, check that the merchant completed verification through the Pandabase.js Verification SDK. Contact platforms@pandabase.io for bulk migration assistance.

Webhook signature failures after migration

The most common cause is using SHA-256 instead of SHA-512. Platform webhooks use HMAC-SHA512. Double-check your verification function.

Settlement timing differences

Store API payouts are merchant-initiated. Platform API settlements are automatic on a T+2 schedule. Merchants who are used to controlling their own payout timing may notice funds arriving on a different cadence. Communicate this change proactively.

Platform fee not appearing

Ensure you are including the platformFee field in every intent creation request. If omitted, it defaults to 0 and you will not earn fees on that transaction.

Support

For migration assistance:

Email: platforms@pandabase.io with subject [MIGRATION]
Bulk migrations (50+ merchants): Contact us for expedited review and dedicated support

Basics

​Who this is for

​Before you begin

​Key differences

​Authentication

​Payments

​Merchants

​Settlements

​Webhooks

​Migration steps

​Step 1: Set up your platform integration

​Step 2: Migrate existing merchants

​Step 3: Update payment creation

​Step 4: Update webhook handling

​Step 5: Update frontend payment flow

​Step 6: Cut over traffic

​Step 7: Clean up

​Parallel operation

​Timeline

​Common issues

​Merchants stuck in PENDING_REVIEW

​Webhook signature failures after migration

​Settlement timing differences

​Platform fee not appearing

​Support

Who this is for

Before you begin

Key differences

Authentication

Payments

Merchants

Settlements

Webhooks

Migration steps

Step 1: Set up your platform integration

Step 2: Migrate existing merchants

Step 3: Update payment creation

Step 4: Update webhook handling

Step 5: Update frontend payment flow

Step 6: Cut over traffic

Step 7: Clean up

Parallel operation

Timeline

Common issues

Merchants stuck in PENDING_REVIEW

Webhook signature failures after migration

Settlement timing differences

Platform fee not appearing

Support