Create or Select a Checkout

Live today: create a session by amount + rail

Today "checkout" means a payment_sessions resource: a specific amount, on a specific rail (see Configure rails), with a TTL.

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

Full request/response schema: Create a stablecoin payment session.

"Selecting" an existing checkout

There is no GET /v1/payment_sessions list/search endpoint today — only GET /v1/payment_sessions/{session_id} for a session whose ID you already have. If your integration needs to re-show or resume a checkout, you must persist the session_id yourself (e.g. keyed by your own order_id in metadata) at creation time; there is no server-side lookup by metadata or by merchant.

curl https://api.plaidly.io/v1/payment_sessions/<SESSION_ID> \
  -H "X-API-Key: your_api_key"

Live: checkout referencing a published catalog price

The catalog (see Create a store, product, and price) shipped in BDT-223 and is deployed. A checkout is created by resolving an already-published price_id into a checkout intent, rather than restating amount + paymentMethod by hand:

curl -X POST https://api.plaidly.io/v1/catalog/prices/<PRICE_ID>/checkout-intent

{
  "checkout_reference_id": "ccs_01HX9K...",
  "price_id": "price_01HX9K...",
  "plan_id": "plan_01HX9K...",
  "product_id": "prod_01HX9K...",
  "store_id": "store_01HX9K...",
  "merchant_id": "mer_01HX9K...",
  "amount_subunits": "25000000",
  "currency_or_token": "USDC",
  "allowed_payment_methods": ["solana:mainnet:USDC", "ethereum:mainnet:USDC"],
  "expires_at": "2026-07-12T13:30:00Z"
}

This call is public (no auth, no request body beyond the price_id path param) — a buyer agent can call it directly. It fails unless the price and its parent plan/product/store are all published and not archived. There is no separate POST /v1/checkouts endpoint: the checkout intent above gives you amount_subunits + currency_or_token + allowed_payment_methods, and whoever holds the merchant's X-API-Key still creates the actual payable resource with POST /v1/payment_sessions (converting amount_subunits to a decimal amount using the token's decimals from Configure rails, picking one of allowed_payment_methods as paymentMethod, and placing checkout_reference_id into that request's metadata object):

curl -X POST https://api.plaidly.io/v1/payment_sessions \
  -H "X-API-Key: your_api_key" \
  -H "Idempotency-Key: order-42-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25.00,
    "expires_in": "45m",
    "paymentMethod": {
      "methodID": 0,
      "chain": "solana",
      "token": "USDC",
      "network": "mainnet"
    },
    "metadata": { "order_id": "order-42", "checkout_reference_id": "ccs_01HX9K..." }
  }'

There is currently no server-side merchant/product rail-policy intersection — see Configure rails for what's live vs. still planned on that front; allowed_payment_methods on the price is the only rail restriction enforced today.

Next

• Verify a webhook event
• Simulate a payment (sandbox only)