Getting Started

Integrating PayByToken requires only a few simple steps.

PayByToken getstarted

The flow is straightforward:

Get API Key
Log in to the Merchant Portal and retrieve your secret API key.
Create a Checkout Session
Use the API to create a Checkout Session. This automatically generates:
- A hosted checkout URL where your users will complete payment.
- A Payment Intent with a trackable status.
Set Webhooks
Register webhook endpoints to receive asynchronous updates about Payment Intent status changes (e.g., confirmed, succeeded).

With these three steps, you can start accepting crypto payments via PayByToken. 🚀

Get API key

Navigate to Developers → API Keys to obtain your secret key:

sk_test_907...de66

Use this key in the Authorization header for every API request:

Authorization: Bearer sk_test_907...de66

Create a Checkout Session

PayByToken provides a hosted checkout flow.

You only need to create a Checkout Session.

The system automatically generates a Payment Intent and returns a payment page URL.

Request

curl https://api-prod.paybytoken.io/api/v1/checkout_sessions \
  -X POST \
  -H "Authorization: Bearer sk_test_907...de66" \
  -H "Content-Type: application/json" \
  -d '{
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel",
    "currency": "USD",
    "line_items": [{
      "unit_amount": "10",
      "quantity": 1,
      "product_data": {
        "name": "Pro Subscription",
        "description": "1-month access"
      }
    }],
    "supported_tokens": [
      { "chain": "base", "currency": "USDC" },
      { "chain": "ethereum", "currency": "USDC" }
    ]
  }'

Respone

{
  "id": "chk_test_t23yxf0Vv0M6Xc8lFTcIpaxQ",
  "account_id": "acct_t24daokSqxEmdQGD",
  "payment_intent_id": null,
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel",
  "return_url": null,
  "url": "https://checkout.paybytoken.io/pay?session_id=chk_test_t23yxf0Vv0M6Xc8lFTcIpaxQ",
  "amount_subtotal": "10",
  "amount_total": "10",
  "currency": "USD",
  "chain": null,
  "selected_token": null,
  "supported_tokens": [
    {
      "name": "USD Coin",
      "chain": "base",
      "currency": "USDC",
      "decimals": 6,
      "chain_name": "Base",
      "chain_logo_url": "https://paybytoken.oss-cn-hongkong.aliyuncs.com/token/base-logo.png",
      "contract_address": "0xBd02F04420F7bA751d6240f053E2decfb6c90821",
      "currency_logo_url": "https://paybytoken.oss-cn-hongkong.aliyuncs.com/token/usdc-logo.png"
    },
    {
      "name": "USD Coin",
      "chain": "ethereum",
      "currency": "USDC",
      "decimals": 6,
      "chain_name": "Ethereum",
      "chain_logo_url": "https://paybytoken.oss-cn-hongkong.aliyuncs.com/token/eth-logo.png",
      "contract_address": "0x1C0c0a3843f952DcD9159C9101f8E74844d92fED",
      "currency_logo_url": "https://paybytoken.oss-cn-hongkong.aliyuncs.com/token/usdc-logo.png"
    }
  ],
  "mode": "payment",
  "discounts": [],
  "line_items": [
    {
      "quantity": 1,
      "unit_amount": "10",
      "amount_total": "10",
      "product_data": {
        "name": "Gucci Authentication Course",
        "images": ["https://authclass-prod.oss-cn-hongkong.aliyuncs.com/20250116a056bca0d300fe8e.png"],
        "description": "Become an expert in Gucci bag authentication with this comprehensive course."
      }
    }
  ],
  "status": "open",
  "customer_id": null,
  "customer_email": null,
  "csrf_token": "d3d0706e504028b6f7693e168789df09742b5bf435b099b787a18da24ff27683",
  "description": null,
  "metadata": null,
  "exchange_rate": null,
  "expired_at": "2025-09-05T10:12:51.000Z",
  "used_at": null,
  "accessed_at": null,
  "created_at": "2025-09-05T09:12:51.000Z",
  "updated_at": "2025-09-05T09:12:51.000Z"
}

The response includes:

url — hosted payment page
id — Checkout Session ID
payment_intent — auto-created Payment Intent ID

Return the url to your frontend and redirect the user there.

Check Payment Intent Status

If you need to confirm payment programmatically, query the Payment Intent ID.

Get Payment Intent

curl https://api-prod.paybytoken.io/v1/payment_intents/pay_t24b28nbodnk4icGMyE7   \
  -H "Authorization: Bearer sk_test_xxx"

Example Response

{
  "id": "pay_t24b28nbodnk4icGMyE7",
  "amount": "10",
  "currency": "USDC",
  "chain": "base",
  "status": "succeeded",
  "one_time_address": "0x123...",
  "created": 1736423434
}

Common statuses:

Status	Description
`pending_method`	⏳ waiting for user to provide payment method
`pending_confirmation`	⏳ waiting for server confirmation
`pending_additional_payment`	💰 requires extra payment (e.g., chain fee, top-up)
`confirmed`	📌 intent confirmed, not yet final
`succeeded`	✅ payment completed successfully
`cancelled`	🚫 cancelled by user or system
`failed`	❌ payment failed

Set webhooks

Use webhooks to receive asynchronous notifications (e.g., payment confirmation).

Create a Webhook

curl https://api-prod.paybytoken.io/v1/webhook_endpoints \
    -X POST   -H "Authorization: Bearer sk_test_xxx" \
    -H "Content-Type: application/json" \
    -d '{
        "url":"https://example.com/webhook"
    }'

The response includes a secret (e.g., whsec_...).
Save it securely and use it to verify webhook signatures.

Minimal Server Example

Here’s a minimal Node.js server integrating Checkout Sessions, Payment Intent status, and Webhooks.

import express from "express";
import fetch from "node-fetch";

const app = express();
app.use(express.json({ type: "*/*" })); // keep raw body if you plan to verify signatures

// 1) Create Checkout Session → return hosted payment page URL
app.post("/create-checkout", async (req, res) => {
  const r = await fetch("https://api-prod.paybytoken.io/api/v1/checkout_sessions", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.PBT_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      success_url: "https://example.com/success",
      cancel_url: "https://example.com/cancel",
      currency: "USD",
      line_items: [{
        unit_amount: "10",
        quantity: 1,
        product_data: { name: "Pro Subscription" }
      }],
      supported_tokens: [{ chain: "base", currency: "USDC" }]
    })
  });
  const data = await r.json();
  res.json({ checkout_url: data.url, payment_intent: data.payment_intent, session_id: data.id });
});

// 2) Check Payment Intent status
app.get("/payment-status/:id", async (req, res) => {
  const r = await fetch(`https://api-prod.paybytoken.io/v1/payment_intents/${req.params.id}`, {
    headers: { "Authorization": `Bearer ${process.env.PBT_API_KEY}` }
  });
  const data = await r.json();
  res.json(data);
});

// 3) Webhook endpoint
app.post("/webhook", (req, res) => {
  // TODO: Verify signature using webhook secret
  // TODO: Handle events (e.g., payment confirmation)
  res.sendStatus(200);
});

app.listen(3000, () => {
  console.log("Server running on http://localhost:3000");
});

🎉 You are now ready to process payments with PayByToken!

Get API key​

Create a Checkout Session​

Request​

Respone​

Check Payment Intent Status​

Get Payment Intent​

Example Response​

Set webhooks​

Create a Webhook​

Minimal Server Example​