API Reference

The Plaidly API is documented via an OpenAPI 3.1 specification (openapi: "3.1.0", info.version: "1.0").

Spec download: GET https://api.plaidly.io/openapi.json currently requires the same auth as merchant endpoints (verified live 2026-07-11 — an unauthenticated request returns 401 with {"code":7,"message":"missing or invalid authorization header"}). Register a sandbox merchant first (see Register a merchant) and pass its api_key, or use the copy checked into plaidly-api/api/openapi.yaml.

curl https://api.plaidly.io/openapi.json \
  -H "X-API-Key: your_api_key" \
  -o plaidly-openapi.json

You can import the resulting file directly into Postman, Insomnia, or any OpenAPI-compatible tool. Or browse the source directly: api/openapi.yaml.

Base URL

https://api.plaidly.io

All endpoints are versioned under /v1. See Versioning & deprecation policy for what that guarantees.

Authentication

Public read endpoints need no auth. Merchant-scoped endpoints use X-API-Key.

Endpoints

Payment sessions

Merchants

Discovery

Operations

Catalog

There is no distinct entitlement resource or endpoint — entitlement is a freeform metadata object field on plan. Full walkthrough: Create a store, product, and price and Create or select a checkout.

Request format

All request bodies use application/json:

curl -X POST https://api.plaidly.io/v1/payment_sessions \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10.0,
    "expires_in": "15m",
    "paymentMethod": {
      "methodID": 0,
      "chain": "solana",
      "token": "USDC",
      "network": "mainnet"
    },
    "metadata": { "order_id": "ord_123" }
  }'

Response format

Most responses are application/json. Successful responses include the resource object directly (no {"session": {...}} wrapper):

{
  "session_id": "sess_test_01HX...",
  "merchant_id": "mer_01HX...",
  "expected_amount": 10,
  "received_amount": 0,
  "address": "7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV",
  "status": "pending",
  "demo": false,
  "paymentMethod": {
    "methodID": 0,
    "chain": "solana",
    "token": "USDC",
    "network": "mainnet"
  }
}

Error format

{
  "code": 5,
  "message": "idempotency key was already used with a different payload"
}

code is a small integer enum today (not a string slug like "session_not_found") — see the full code table and the richer envelope the platform is converging on in Error model.

Status codes

Rate limits

Each merchant gets a default limit of 60 requests per minute, set on the Merchant object as rate_limit_per_minute (visible via GET /v1/me) — it is per-merchant, not a single global constant, and can differ from the default. Exceeding it returns 429.

There are currently no X-RateLimit-* response headers — you cannot introspect remaining quota from response headers today; track your own request rate against the rate_limit_per_minute value from GET /v1/me instead.

Idempotency

POST requests to a subset of endpoints support idempotency via the Idempotency-Key header. See Idempotency for exactly which endpoints support it today.