Quickstart

1. Get your API key

No dashboard signup or prior login is required for a sandbox merchant, but registering now requires verifying an email, solving a proof-of-work challenge, and passing a default-deny trust gate (your email/domain must be allowlisted, or you need an invitation token) before POST /v1/merchants will succeed. Full four-step flow, the proof-of-work solver, and the trust-gate details: Register a merchant.

Copy api_key from the final step's response — it's returned exactly once and starts with plaidly_sk_test_ for a sandbox merchant.

2. Create a payment session

Send a POST to /v1/payment_sessions with the payment details:

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"
    }
  }'

The response includes the wallet address where the customer sends funds:

{
  "session_id": "sess_01HX9K...",
  "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA36wzok3ei5FU",
  "expected_amount": 10,
  "currency": "USDC",
  "status": "pending",
  "expires_at": "2024-01-01T12:00:00Z"
}

3. Show payment address to customer

Display the address to your customer and ask them to send the requested amount on the selected chain and network.

You can also show a QR code by encoding the address as a deep link.

4. Handle the webhook

When the payment is confirmed on-chain, Plaidly sends a POST to your webhook_url:

{
  "event_type": "payment_session.completed",
  "session_id": "sess_01HX9K...",
  "status": "completed",
  "amount": 10,
  "currency": "USDC",
  "chain": "solana",
  "network": "mainnet",
  "timestamp": "1700000000"
}

Verify the X-Plaidly-Signature header before fulfilling the order. See HMAC verification.

5. Verify payment status (optional)

You can also poll the session status:

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

Next steps

• Webhook setup — configure and verify webhooks
• Sandbox mode — test without real funds
• Node.js SDK — use the official SDK