Documentation

Payment system for partners and AI bots, with added monetization features

Part 1: Introduction & Authentication#

PAYchat Partner API#

Build seamless USDT payments into your app with our simple REST API.

Welcome#

PAYchat Partner API lets you:

• Accept payments — payment links, QR codes, and escrow
• Send money — instantly transfer USDT to any Telegram user
• Track everything — real-time webhooks and detailed analytics

Base URL: https://paychat.info/api/partner

To receive callbacks (webhooks): Partner Dashboard → Webhooks tab → enter your HTTPS endpoint → click Test.

Official SDK#

npm install paychat-sdk

import PAYchatClient from 'paychat-sdk';

const client = new PAYchatClient('pk_your_api_key');

const payment = await client.createPayment({
  amount: 10,
  description: 'Limited Edition T-Shirt'
});

console.log(payment.payment.payment_url);

SDK v2.0.1 — https://www.npmjs.com/package/paychat-sdk

Authentication#

Your Credentials#

The Secret Key is never sent in requests — it only verifies webhook signatures.

How to Authenticate#

x-api-key: pk_your_api_key_here

This is not a Bearer token.

Example Request#

curl https://paychat.info/api/partner/balance \
  -H "x-api-key: pk_abc123..."

Access Conditions#

Keep Your Keys Safe#

• Never expose keys in client-side code
• Don't commit keys to version control
• Use environment variables
• Regenerate immediately if compromised

Part 2: Plans & Pricing#

Plans#

Pricing#

Fees are charged per API call, not as a percentage of transaction volume, and are deducted from your balance. A volume discount applies based on your balance plus the combined balance of users you referred.

→ Full pricing, discount tiers, and worked examples

For your live rate and current discount tier, call GET /api/partner/fee-info. For plan details, GET /api/partner/plans.

Volume Discount (Based on Total Holdings)#

Total Holdings = Your Balance + Referred Users' Balances

Live figures: GET /fee-info and GET /plans.

How It Works#

1. Pay once → lifetime API access
2. API fees deducted from your balance per call
3. More holdings = higher discount = lower fees
4. Refer users → their balances count toward your discount

Part 3: Rate Limits & Spend Limits#

Rate Limits#

Limits are per endpoint. All GET endpoints share a single counter.

Response Headers#

When You Hit the Limit#

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please retry later."
  }
}

Tip: check the Retry-After header to know when to retry.

Spend Limits#

Optional per-partner caps. A value of 0 means unlimited.

The daily counter resets on the UTC date change. The amount is reserved at check time — if the withdrawal later fails, the reserved amount stays counted until the next reset.

Idempotency#

Pass idempotency_key in the request body — not as a header.

Supported on POST /payments, POST /withdrawals, POST /escrows, POST /qr-payments.

Part 4: API Endpoints Overview#

All Endpoints#

Payments#

QR Payments#

Escrow#

Withdrawals & Deposits#

Gifts, Lucky Drops & Collects#

Paid from your partner balance. Detailed reference to follow.

M-Pesa#

Balance & Reporting#

Webhooks#

Account#

Partner Shop#

See Part 16 and Part 17.

Connect PAYchat#

See Part 16 › Connect PAYchat.

Testing (test keys only)#

Public Endpoints (No API Key Required)#

Minimum Amounts#

These differ per resource — a common source of INVALID_AMOUNT.

Part 5: Create Payment#

Create a Payment#

Endpoint: POST /api/partner/payments

Request Body#

Example Request#

curl -X POST https://paychat.info/api/partner/payments \
  -H "x-api-key: pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 29.99,
    "description": "Limited Edition T-Shirt",
    "metadata": {
      "user_id": "user_123",
      "item": "tshirt_black_L"
    }
  }'

Example Response#

{
  "success": true,
  "payment": {
    "id": "x7k2m9",
    "link_id": "x7k2m9",
    "amount": 29.99,
    "currency": "USDT",
    "description": "Limited Edition T-Shirt",
    "status": "pending",
    "payment_url": "https://t.me/paychat_aibot?start=x7k2m9",
    "expires_at": "2026-08-14T12:00:00.000Z",
    "metadata": {
      "user_id": "user_123",
      "item": "tshirt_black_L"
    },
    "created_at": "2026-08-13T12:00:00.000Z"
  }
}

⚠️ id is the 6-character link_id. Use this value for GET /payments/:link_id. Earlier SDK versions returned a separate pay_xxx identifier that was not queryable — it has been removed.

⚠️ expires_at is informational. No background job closes the link and payment is not blocked after that time. Enforce a cutoff in your own code if you need one.

What to Do Next#

1. Redirect your customer to payment_url
2. They complete payment in Telegram
3. You receive a payment.completed webhook
4. Funds are added to your balance instantly

Check Payment Status#

Endpoint: GET /api/partner/payments/:link_id

curl https://paychat.info/api/partner/payments/x7k2m9 \
  -H "x-api-key: pk_your_key"

Example Response (Completed)#

{
  "success": true,
  "payment": {
    "id": "x7k2m9",
    "link_id": "x7k2m9",
    "amount": 29.99,
    "currency": "USDT",
    "description": "Limited Edition T-Shirt",
    "metadata": { "user_id": "user_123" },
    "status": "completed",
    "fee": 0.0004,
    "net_amount": 29.9896,
    "payer": { "telegram_id": "987654321" },
    "paid_at": "2026-08-13T12:30:00.000Z",
    "created_at": "2026-08-13T12:00:00.000Z"
  }
}

fee and net_amount are 0 and full amount respectively while status is pending.

Payment Status Values#

Part 6: QR Payments#

Create a QR Payment#

Endpoint: POST /api/partner/qr-payments

Request Body#

⚠️ expires_hours is measured in hours. If omitted, the QR code does not expire.

Example Request#

curl -X POST https://paychat.info/api/partner/qr-payments \
  -H "x-api-key: pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15.00,
    "description": "Coffee Shop Order",
    "expires_hours": 1
  }'

Example Response#

{
  "success": true,
  "qr_payment": {
    "id": "qr_a1b2c3d4e5f6",
    "amount": 15.00,
    "description": "Coffee Shop Order",
    "is_fixed_amount": true,
    "min_amount": null,
    "max_amount": null,
    "single_use": true,
    "status": "active",
    "payment_url": "https://t.me/paychat_aibot?start=qr_a1b2c3d4e5f6",
    "qr_image_url": "https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=...",
    "metadata": null,
    "expires_at": "2026-08-13T13:00:00.000Z",
    "created_at": "2026-08-13T12:00:00.000Z"
  }
}

Variable Amount (Tip Jar)#

curl -X POST https://paychat.info/api/partner/qr-payments \
  -H "x-api-key: pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "is_fixed_amount": false,
    "min_amount": 1,
    "max_amount": 100,
    "single_use": false,
    "description": "Tip Jar"
  }'

min_amount greater than max_amount returns INVALID_RANGE.

QR Status Values#

⚠️ There is no expired status. expires_at is stored for your reference only — no background job transitions the record, and the payment flow does not check it. A QR code past its expiry still reports active and can still be paid. Compare expires_at yourself, or call DELETE /qr-payments/:id to close it.

processing is a short-lived lock. If the payment fails, the record returns to active.

DELETE only accepts QR codes currently in active status — otherwise QR_NOT_FOUND is returned.

{
  "success": true,
  "message": "QR payment deactivated",
  "id": "qr_a1b2c3d4e5f6"
}

Part 7: Escrow#

Create an Escrow#

Hold buyer funds until the seller delivers.

Endpoint: POST /api/partner/escrows

Request Body#

Things to Know#

Example Request#

curl -X POST https://paychat.info/api/partner/escrows \
  -H "x-api-key: pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "buyer_telegram_id": "123456789",
    "seller_telegram_id": "987654321",
    "amount": 100.00,
    "description": "Freelance Project",
    "expires_hours": 72
  }'

Example Response#

{
  "success": true,
  "escrow": {
    "id": "esc_a1b2c3d4e5f6",
    "buyer_telegram_id": "123456789",
    "seller_telegram_id": "987654321",
    "amount": 100.00,
    "fee": 1.00,
    "net_amount": 99.00,
    "description": "Freelance Project",
    "metadata": null,
    "status": "pending",
    "payment_url": "https://t.me/paychat_aibot?start=esc_a1b2c3d4e5f6",
    "expires_at": "2026-08-16T12:00:00.000Z",
    "created_at": "2026-08-13T12:00:00.000Z"
  }
}

Response fields are flat — buyer_telegram_id and seller_telegram_id, not nested buyer / seller objects.

Escrow Lifecycle#

Release / Cancel#

# Release funds to the seller
curl -X POST https://paychat.info/api/partner/escrows/esc_a1b2c3d4e5f6/release \
  -H "x-api-key: pk_your_key"

# Cancel and refund the buyer
curl -X POST https://paychat.info/api/partner/escrows/esc_a1b2c3d4e5f6/cancel \
  -H "x-api-key: pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Buyer requested refund"}'

An escrow already being processed returns ESCROW_PROCESSING.

Part 8: Send Withdrawal#

Send a Withdrawal#

Endpoint: POST /api/partner/withdrawals

Request Body#

Example Request#

curl -X POST https://paychat.info/api/partner/withdrawals \
  -H "x-api-key: pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "telegram_id": "123456789",
    "amount": 10.00,
    "memo": "Referral bonus - Thanks!",
    "idempotency_key": "wd_order_5521"
  }'

Example Response#

{
  "success": true,
  "withdrawal": {
    "id": "wd_xyz789abc",
    "telegram_id": "123456789",
    "amount": 10.00,
    "status": "completed",
    "memo": "Referral bonus - Thanks!",
    "created_at": "2026-08-13T12:00:00.000Z"
  },
  "referral_added": true
}

referral_added is true only on the recipient's first transaction with you.

Good to Know#

Part 9: Deposits#

Fund Your Partner Account#

Endpoint: POST /api/partner/deposits

Request Body#

Any other network value returns INVALID_NETWORK. If you already have an open request, you get ACTIVE_REQUEST_EXISTS.

Example Request#

curl -X POST https://paychat.info/api/partner/deposits \
  -H "x-api-key: pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50, "network": "tron"}'

Deposit Status Values#

Deposits do not emit webhooks. Poll GET /deposits/:id instead.

Get Deposit Address#

Endpoint: GET /api/partner/deposit-address

Example Response#

{
  "success": true,
  "deposit": {
    "address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "network": "TRON (TRC20)",
    "currency": "USDT",
    "memo": "partner_abc123",
    "note": "Include the memo when sending to identify your deposit"
  }
}

This endpoint returns the TRON (TRC-20) address only. To deposit over TON, create a deposit request with POST /deposits and "network": "ton".

Important: always include the memo when sending funds so we can credit your account.

Part 10: Balance, Transactions & Stats#

Check Your Balance#

Endpoint: GET /api/partner/balance

{
  "success": true,
  "balance": {
    "available": 1250.50,
    "currency": "USDT",
    "monthly_volume": 48200.00,
    "fee_rate": 0.01
  }
}

Total holdings and referral balances are not returned here. Use GET /fee-info for your discount tier and referral totals.

Fee Info#

Endpoint: GET /api/partner/fee-info

Returns your current discount tier, effective per-call fee, total holdings, and how much more balance is needed to reach the next tier.

List Transactions#

Endpoint: GET /api/partner/transactions

Query Parameters#

Example Response#

{
  "success": true,
  "transactions": [
    {
      "id": 1,
      "partner_id": "ptn_abc123",
      "type": "payment",
      "telegram_id": "123456789",
      "amount": 29.99,
      "fee": 0.0004,
      "net_amount": 29.9896,
      "status": "completed",
      "created_at": "2026-08-13T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 156,
    "limit": 10,
    "offset": 0
  }
}

Dashboard & Stats#

GET /escrows, GET /qr-payments, and GET /deposits return a subset of fields and no pagination object. Use the detail endpoint for the full record.

Part 11: Webhooks#

Webhooks#

Available Events#

Partner Shop Events#

Payloads and rules are in Part 16 › Order Status Webhooks. Shop events carry click_id instead of metadata.

There are no qr.created, qr.expired, or deposit events. Poll the relevant GET endpoint instead.

Setting Up Webhooks#

1. Set your webhook URL

curl -X PUT https://paychat.info/api/partner/webhook \
  -H "x-api-key: pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"webhook_url": "https://your-server.com/webhooks/paychat"}'

2. Test it

curl -X POST https://paychat.info/api/partner/webhook-test \
  -H "x-api-key: pk_your_key"

Webhook URL Requirements#

The URL must be a public HTTPS endpoint. The following are rejected with INVALID_WEBHOOK_URL:

• Any http:// URL
• localhost or any .local hostname
• Private ranges: 10.x, 172.16–31.x, 192.168.x
• Loopback: 127.x, ::1
• Link-local: 169.254.x (including cloud metadata endpoints)
• CGNAT: 100.64–127.x
• Multicast and reserved ranges
• Bare hostnames with no dot, and integer or hex-encoded IP forms

Webhook Headers#

Webhook Payload: payment.completed#

{
  "event": "payment.completed",
  "data": {
    "payment_id": "x7k2m9",
    "status": "completed",
    "transaction_id": "x7k2m9",
    "amount": 29.99,
    "fee": 0.0004,
    "net_amount": 29.9896,
    "metadata": {
      "user_id": "user_123",
      "item": "tshirt_black_L"
    },
    "payer": { "telegram_id": "987654321" }
  },
  "created_at": "2026-08-13T12:00:00.000Z"
}

Whatever you attached as metadata on creation is echoed back here — no follow-up GET needed. This applies to payment.completed, qr.paid, escrow.created, escrow.paid, escrow.released, and escrow.cancelled. withdraw.completed carries memo instead.

Webhook Payload: withdraw.completed#

{
  "event": "withdraw.completed",
  "data": {
    "withdrawal_id": "wd_xyz789",
    "telegram_id": "123456789",
    "amount": 10.00,
    "memo": "Referral bonus"
  },
  "created_at": "2026-08-13T12:00:00.000Z"
}

Part 12: Webhook Security & Retries#

Verifying Webhooks#

How Signatures Work#

1. We build the message {timestamp}.{JSON.stringify(payload)}
2. We sign it with your Secret Key using HMAC-SHA256
3. We send the result in X-PAYchat-Signature

Signature Format#

X-PAYchat-Signature: t=1704628800,v1=abc123def456...

Reject requests whose timestamp is older than 5 minutes.

Verification Code (Node.js)#

const crypto = require('crypto');

function verifyWebhook(payload, signatureHeader, secretKey) {
  const parts = signatureHeader.split(',');
  const timestamp = parts.find(p => p.startsWith('t=')).split('=')[1];
  const signature = parts.find(p => p.startsWith('v1=')).split('=')[1];

  // Reject stale timestamps
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp)) > 300) return false;

  const message = `${timestamp}.${JSON.stringify(payload)}`;
  const expected = crypto
    .createHmac('sha256', secretKey)
    .update(message)
    .digest('hex');

  return signature === expected;
}

app.post('/webhooks/paychat', (req, res) => {
  const isValid = verifyWebhook(
    req.body,
    req.headers['x-paychat-signature'],
    process.env.PAYCHAT_SECRET_KEY
  );

  if (!isValid) return res.status(401).send('Invalid signature');

  res.status(200).send('OK');
});

Or use the SDK:

import { PAYchatClient } from 'paychat-sdk';

// Node.js
PAYchatClient.verifyWebhook(payload, signature, 'sk_your_secret_key');

// Browser / Workers
await PAYchatClient.verifyWebhookAsync(payload, signature, 'sk_your_secret_key');

Webhook Retries#

If your server doesn't respond with a 2xx status, we retry automatically.

Retry Schedule#

Retries run on a background scheduler. A delivery is abandoned after 5 total attempts and marked failed.

Failed deliveries can be replayed manually with POST /webhooks/:id/retry.

Requirements for Success#

Part 13: Error Handling#

Error Handling#

Error Response Format#

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable description"
  }
}

Some errors add context fields — for example DAILY_LIMIT_EXCEEDED also returns daily_limit, daily_used, and amount.

HTTP Status Codes#

Authentication & Access#

Limits#

Validation#

Resource State#

Execution#

Client-Side (SDK only)#

Part 14: Code Examples#

Using the Official SDK (Recommended)#

npm install paychat-sdk

import PAYchatClient from 'paychat-sdk';

const client = new PAYchatClient('pk_your_api_key');

// Payment link
const payment = await client.createPayment({
  amount: 29.99,
  description: 'Limited Edition Hoodie',
  metadata: { user_id: '123' }
});

// QR payment — expiresHours is in HOURS
const qr = await client.createQRPayment({
  amount: 15.00,
  description: 'Coffee Shop Order',
  expiresHours: 1
});
console.log(qr.qr_payment.qr_image_url);

// Escrow — minimum 1 USDT, 1% fee
const escrow = await client.createEscrow({
  amount: 100,
  buyerTelegramId: '123456789',
  sellerTelegramId: '987654321',
  description: 'Freelance Project'
});
await client.releaseEscrow(escrow.escrow.id);

// Withdrawal
const withdrawal = await client.createWithdrawal({
  telegramId: '123456789',
  amount: 5.00,
  memo: 'Referral bonus'
});

// Balance
const balance = await client.getBalance();

// Webhook verification
const isValid = PAYchatClient.verifyWebhook(payload, signature, 'sk_your_secret_key');

Raw HTTP (any language)#

Node.js Setup#

const axios = require('axios');

const paychat = axios.create({
  baseURL: 'https://paychat.info/api/partner',
  headers: {
    'x-api-key': process.env.PAYCHAT_API_KEY,
    'Content-Type': 'application/json'
  }
});

Create a Payment#

async function createPayment(amount, description, metadata = {}) {
  try {
    const { data } = await paychat.post('/payments', {
      amount,
      description,
      metadata,
      idempotency_key: `pay_${Date.now()}_${Math.random()}`
    });

    console.log('Payment URL:', data.payment.payment_url);
    console.log('Lookup ID:', data.payment.id); // 6-char link_id
    return data.payment;

  } catch (error) {
    console.error('Error:', error.response?.data?.error?.message);
    throw error;
  }
}

Send Money to a User#

async function sendReward(telegramId, amount, memo) {
  try {
    const { data } = await paychat.post('/withdrawals', {
      telegram_id: telegramId,
      amount,
      memo,
      idempotency_key: `wd_${telegramId}_${Date.now()}`
    });
    return data.withdrawal;

  } catch (error) {
    const code = error.response?.data?.error?.code;
    if (code === 'INSUFFICIENT_BALANCE') {
      console.error('Not enough balance! Please deposit more funds.');
    }
    if (code === 'DAILY_LIMIT_EXCEEDED') {
      console.error('Daily spend cap reached.');
    }
    throw error;
  }
}

Handle Webhooks (Express)#

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

app.post('/webhooks/paychat', (req, res) => {
  const signature = req.headers['x-paychat-signature'];
  if (!verifySignature(req.body, signature)) {
    return res.status(401).send('Invalid signature');
  }

  switch (req.headers['x-paychat-event']) {
    case 'payment.completed': handlePayment(req.body.data); break;
    case 'withdraw.completed': handleWithdrawal(req.body.data); break;
    case 'qr.paid': handleQR(req.body.data); break;
    case 'escrow.paid': handleEscrowPaid(req.body.data); break;
    case 'escrow.released': handleEscrowReleased(req.body.data); break;
  }

  res.status(200).send('OK');
});

function verifySignature(payload, header) {
  const parts = header.split(',');
  const timestamp = parts.find(p => p.startsWith('t=')).split('=')[1];
  const signature = parts.find(p => p.startsWith('v1=')).split('=')[1];

  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp)) > 300) return false;

  const message = `${timestamp}.${JSON.stringify(payload)}`;
  const expected = crypto
    .createHmac('sha256', process.env.PAYCHAT_SECRET_KEY)
    .update(message)
    .digest('hex');

  return signature === expected;
}

app.listen(3000);

Part 15: FAQ#

Frequently Asked Questions#

General#

Q: What if my balance is too low?

A: Auto-charge triggers if enabled. Otherwise the API returns BALANCE_TOO_LOW (Free plan) or INSUFFICIENT_BALANCE.

Q: How do referred users affect my discount?

A: The first withdrawal to a user registers them as your referral. Their balance counts toward your total holdings, increasing your discount rate.

Q: What if my API key is exposed?

A: Regenerate it immediately:

curl -X POST https://paychat.info/api/partner/regenerate-key \
  -H "x-api-key: pk_your_current_key"

Your old key becomes invalid instantly. The Secret Key is rotated at the same time — update your webhook verification code too.

Payments#

Q: Which ID do I use to check a payment?

A: The payment.id from the create response — a 6-character link_id. It is also returned as payment.link_id.

Q: Is metadata sent in webhooks?

A: Yes. Whatever you attached on creation is echoed in payment.completed, qr.paid, and every escrow.* event (see Part 11). withdraw.completed carries memo instead, and Partner Shop events carry click_id instead of metadata.

Q: What currencies are supported?

A: USDT. Deposits accept the TRON (TRC-20) and TON networks.

Q: When do I receive funds?

A: Instantly — as soon as the customer completes payment.

QR Payments#

Q: Why doesn't my QR code expire?

A: expires_hours is measured in hours, and if omitted the QR never expires. Even when set, expires_at is informational — the status is not auto-updated and the payment flow does not block on it. Enforce expiry in your own code, or call DELETE /qr-payments/:id.

Q: What's the minimum QR amount?

A: 0.01 USDT for fixed-amount QR codes — higher than the 0.000001 minimum for payment links.

Escrow#

Q: What does escrow cost?

A: 1% of the amount, deducted from the seller payout. A 100 USDT escrow pays the seller 99 USDT.

Q: What if the seller has no PAYchat account?

A: An account is created automatically when the escrow is made.

Withdrawals#

Q: What if the recipient doesn't have PAYchat?

A: We create an account automatically. They receive a Telegram message with instructions.

Q: Is there a minimum withdrawal?

A: 0.000001 USDT.

Webhooks#

Q: What if my webhook endpoint is down?

A: We retry up to 5 times over roughly 2.5 hours. You can also replay manually with POST /webhooks/:id/retry.

Q: Why was my webhook URL rejected?

A: It must be a public HTTPS endpoint. See the Webhook URL Requirements table — private, loopback, and link-local addresses are blocked.

Security#

Q: What's idempotency_key for?

A: It prevents duplicate transactions if the same request is sent twice. Send it in the request body, not as a header. Keys are retained for 24 hours.

Q: How do I verify webhooks are really from PAYchat?

A: Check X-PAYchat-Signature with your Secret Key, and reject timestamps older than 5 minutes.

Need Help?#

PAYchat Partner API — Documentation#

Payment system for partners and AI agents. Base URL: https://paychat.info/api/partner

Quick start (no signup, works for AI agents)#

1. POST https://paychat.info/api/partner/sandbox/start — no auth. Returns JSON with a claim_url. Limit: 3 issues per IP per day.
2. GET the claim_url — returns a sandbox api_key (prefix pk_test_, valid 30 days, 1,000 calls/month) plus ready-to-run curl examples.
3. Call any endpoint with header X-API-Key: <api_key>.

Sandbox keys run in test mode: no real funds move, and payments are completed via the simulator below. Live keys (pk_) require a PAYchat account — register as a partner in the Telegram Mini App.

Authentication#

Every request needs the header X-API-Key. Keys starting with pk_test_ are test/sandbox; keys starting with pk_ are live. A missing or wrong key returns 401 INVALID_API_KEY with a hint field pointing back to the sandbox start endpoint. Expired sandbox keys return SANDBOX_EXPIRED.

Idempotency#

Write endpoints accept an optional idempotency_key in the body. Repeating a request with the same key within 24 hours returns the original response instead of creating a duplicate.

Payments#

POST /payments — create a payment link. Body: amount (USDT, required), description, metadata, idempotency_key. The returned id is a payment link id; the link expires in 24 hours. Test-mode payments are marked api_mode: "test".

GET /payments/:id — fetch one payment.

Escrow#

POST /escrows — create an escrow between two Telegram users. Body: buyer_telegram_id (required), seller_telegram_id (required), amount (required, minimum 1 USDT), description, metadata, idempotency_key, expires_hours (default 72). Errors: INVALID_PARAMS (missing required fields), INVALID_AMOUNT (below 1 USDT).

GET /escrows — list escrows. GET /escrows/:id — fetch one. POST /escrows/:id/release — release funds to the seller. POST /escrows/:id/cancel — cancel and refund.

Withdrawals#

POST /withdrawals — pay out to a PAYchat user. Body: telegram_id, amount, memo, idempotency_key.

QR payments#

POST /qr-payments — create a QR payment. Body: amount, description, metadata, idempotency_key, is_fixed_amount (default true), min_amount, max_amount (for variable-amount QR), single_use (default true), expires_hours. GET /qr-payments, GET /qr-payments/:id, DELETE /qr-payments/:id.

Test simulator (test mode only)#

POST /test/simulate-payment — mark a test payment or escrow as paid, firing the same webhooks as a real payment. Body: type ("payment" or "escrow"), id (the object id).

Webhooks#

Set your webhook URL via PUT /webhook (HTTPS only). Delivery log: GET /webhooks; retry: POST /webhooks/:id/retry; send a test event: POST /webhook-test. Events: payment.completed, escrow.created, escrow.paid, escrow.released, escrow.cancelled.

Account & info#

GET /balance — partner balance. GET /fee-info — per-call costs and volume discounts. GET /dashboard, GET /stats, GET /transactions — activity overviews. GET /plans — plans and pricing (no auth needed).

Not for autonomous agents#

POST /transfer moves funds between users and requires the end user's PIN session inside the PAYchat Mini App. AI agents cannot call it standalone; use payments or escrow instead.

Also available#

Read-only user-side OpenAPI (MCP tools): https://paychat.info/mcp/openapi.json. MCP API keys are issued by users inside the PAYchat Mini App.

Questions → https://t.me/paychat_group

Start → https://t.me/paychat_aibot?start=partner

Part 16: Partner Shop#

Partner Shop#

Build your own storefront from PAYchat escrow products and Telegram channel ads. You design the catalog and the cart. Payment always happens inside the PAYchat Mini App. Every deal from your shop is tracked with orders and webhooks, and you earn a commission on deals from buyers who joined PAYchat through your shop (see Attribution & Commission).

How It Works#

1. Load the catalog with GET /shop/products and GET /shop/channels
2. Show the items in your own shop and cart
3. Create a checkout with POST /shop/checkouts (or keep a connected user's cart in sync with POST /shop/carts)
4. Send the buyer to the checkout url — it opens the PAYchat Mini App
5. The buyer pays inside the Mini App
6. Follow each deal with the order endpoints and webhooks. Each completed deal sends you shop.order.completed with your commission

Shop Endpoints#

All use x-api-key and the same access conditions as other endpoints (see Part 1). Errors use the standard format (see Part 13).

List Products#

Endpoint: GET /api/partner/shop/products

A product is listed only while it is open for sale — the same rule as the PAYchat Mini App feed: publicly posted for sale, waiting for a buyer, not expired, and in stock. Adult products are never listed.

Query Parameters#

Products come in the same order as the PAYchat Mini App feed (sales and saves rank higher). An unrecognized category or country value is ignored and no filter is applied.

Example Request#

curl "https://paychat.info/api/partner/shop/products?category=digital&limit=20" \
  -H "x-api-key: pk_your_key"

Product Fields#

The response also returns limit and offset. There is no total count.

Person Object#

Used for seller in products and owner in channels. Sellers and channel owners are always masked, the same way the PAYchat Mini App shows them.

Show name exactly as returned and do not try to reveal the seller.

List Channels#

Endpoint: GET /api/partner/shop/channels

A channel is listed while it is accepting ads and has a price. Adult, gambling, hacking and similar channels are never listed.

Query Parameters#

Channels come in the same order as the PAYchat Mini App channel list for the same filters. A channel the owner has paused is not listed until they resume.

Top-level Fields#

Channel Fields#

members and avg_views refresh about every 6 hours. Cache accordingly.

Create a Checkout#

Endpoint: POST /api/partner/shop/checkouts

Request Body#

Item: product#

Item: channel_ad#

Ad Text Formatting#

Everything else is posted as plain text. HTML tags are not interpreted. If Telegram rejects the formatted text, the ad is posted as plain text with the markers visible. Links are not allowed in the text — use button_url. Videos are not supported.

Ad Photo#

Rules#

Example Request#

curl -X POST https://paychat.info/api/partner/shop/checkouts \
  -H "x-api-key: pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "type": "product", "id": "PRODUCT_ID" },
      { "type": "channel_ad", "channel_id": 12, "slot_at": "asap", "ad_text": "Try PAYchat", "button_url": "paychat.info", "button_text": "Open", "repeat_count": 7, "repeat_freq": 1 }
    ],
    "click_id": "gclid_abc123"
  }'

Example Response#

{
  "success": true,
  "checkout": {
    "id": "shop_1a2b3c4d5e6f7a8b9c0d",
    "startapp": "shop_1a2b3c4d5e6f7a8b9c0d",
    "url": "https://t.me/paychat_aibot?startapp=shop_1a2b3c4d5e6f7a8b9c0d
    "app_url": null,
    "items": [
      { "type": "product", "id": "PRODUCT_ID" },
      { "type": "channel_ad", "channel_id": 12, "slot_at": "2026-11-01T09:05:00.000Z", "asap": 1, "ad_text": "Try PAYchat", "repeat_count": 7, "repeat_freq": 1, "ad_image": null, "format": "24", "btn_url": "https://paychat.info", "btn_text": "Open" }
    ],
    "click_id": "gclid_abc123",
    "mode": "live",
    "expires_at": "2026-11-08T09:00:00.000Z"
  },
  "note": "Conversion webhook event shop.order.completed is sent to your webhook_url when each deal completes."
}

⚠️ A checkout does not reserve stock or lock a price. Availability is checked only when the checkout is created, so a product can still sell out before your buyer pays.

Errors#

Sync a Connected User's Cart#

Endpoint: POST /api/partner/shop/carts

For users who linked PAYchat to your site (see Connect PAYchat). Send the user's cart whenever it changes; the same cart then appears in the user's PAYchat Chat tab and opens prefilled, so they can finish paying in the Mini App even if they leave your site.

Request Body#

Errors#

Conversion Webhook: shop.order.completed#

Sent to the URL set with PUT /webhook, signed and retried the same way as other webhooks (see Part 12). If no webhook URL is set, nothing is sent.

Example Payload#

{
  "event": "shop.order.completed",
  "data": {
    "checkout_id": "shop_1a2b3c4d5e6f7a8b9c0d",
    "click_id": "gclid_abc123",
    "escrow_id": "DEAL_ID",
    "group_id": "DEAL_ID",
    "item": "esc:PRODUCT_ID",
    "amount": 25,
    "commission": 0.125,
    "currency": "USDT",
    "completed_at": "2026-09-14T08:30:00.000Z"
  },
  "created_at": "2026-09-14T08:30:00.000Z"
}

Payload data Fields#

Attribution & Commission#

Testing with a Test Key#

Use a test checkout only to check your integration and the Mini App screens. Do not pay for an item unless you really want to buy it. To test your webhook endpoint, use POST /webhook-test (see Part 12).

What the Buyer Sees in the Mini App#

1. The checkout url opens the PAYchat Mini App on a Shop cart screen. It lists your items, the buyer's balance and the total.
2. A new user first sets a PIN and date of birth. The cart appears when they finish.
3. Products are paid one by one with the buyer's PIN. When the cart has two or more channel ads, a Pay all button pays them together with one PIN. Paid items show Paid. Items that are no longer for sale show Not available right now.
4. If the balance is too low, the item shows the missing amount and a Go to Deposit button. After topping up, the buyer returns to the Shop cart. The cart also stays in the Chat tab while it has unpaid items, until the checkout expires.
5. For a channel ad, the buyer can edit the ad text (5–4,096 characters, or up to 1,024 with a photo) before paying. The photo and button from your checkout are posted with the ad. A repeat ad shows the total for all runs and is paid once. A phone number must be verified the first time.
6. After payment, the deal continues in the PAYchat deal room like any other PAYchat escrow deal: delivery, confirmation and disputes. For a channel ad, the channel owner reviews the ad and accepts; funds stay locked until the post is verified.

A checkout link can be opened again at any time before expires_at. It can also be shared: every Telegram user who opens it is tracked for you separately. Opening your own checkout records nothing.

Tracking Google Ads Conversions#

The purchase happens inside Telegram, so a tag on your website cannot see it. Report conversions from your server:

1. When a visitor arrives from an ad, store the gclid on your server and link it to a short ID of your own.
2. Send that short ID as click_id when you create the checkout.
3. When shop.order.paid or shop.order.completed arrives, find the gclid by click_id and upload an offline conversion to Google Ads, using amount as the conversion value.

shop.order.completed is sent when the deal completes, which can be days after the click because of the inspection period or the ad schedule. Choose a conversion window long enough to cover it, or count conversions on shop.order.paid. One checkout can produce several events, one per item or ad run.

Order Status Webhooks#

Besides shop.order.completed, PAYchat sends a status event for every deal that comes from your shop. Webhooks are signed and retried the same way as other webhooks (see Part 12).

Common data Fields#

Every status event carries these fields.

paid / disputed / cancelled#

Add status, currency and at (time the change was detected).

{
  "event": "shop.order.cancelled",
  "data": {
    "checkout_id": "shop_1a2b3c4d5e6f7a8b9c0d",
    "click_id": "gclid_abc123",
    "escrow_id": "esc_a1b2c3d4e5f6",
    "group_id": "esc_a1b2c3d4e5f6",
    "run_no": 1,
    "run_count": 7,
    "item": "ad:12",
    "amount": 10,
    "status": "cancelled",
    "currency": "USDT",
    "at": "2026-09-14T08:30:00.000Z"
  },
  "created_at": "2026-09-14T08:30:00.000Z"
}

ad_posted / ad_removed#

The post is monitored only until the run pays out (24 h after posting). A removal inside that window sends shop.order.ad_removed with early: true; the owner is paid pro-rata for the time kept and the run still ends with shop.order.completed. After payout the post is no longer watched, so a later removal sends nothing.

{
  "event": "shop.order.ad_removed",
  "data": {
    "checkout_id": "shop_1a2b3c4d5e6f7a8b9c0d",
    "click_id": "gclid_abc123",
    "escrow_id": "esc_a1b2c3d4e5f6",
    "group_id": "esc_a1b2c3d4e5f6",
    "run_no": 1,
    "run_count": 7,
    "item": "ad:12",
    "amount": 10,
    "views": 1240,
    "posted_at": "2026-09-20T09:00:40.000Z",
    "removed_at": "2026-09-20T14:12:05.000Z",
    "early": true
  },
  "created_at": "2026-09-20T14:13:00.000Z"
}

Check Order Status#

Get a Checkout#

Endpoint: GET /api/partner/shop/checkouts/:id

Returns a checkout you created and every order placed through it. Only your own checkouts can be read.

List Orders#

Endpoint: GET /api/partner/shop/orders

Newest orders come first. The response also returns limit and offset.

Order Object#

{
  "escrow_id": "esc_a1b2c3d4e5f6",
  "checkout_id": "shop_1a2b3c4d5e6f7a8b9c0d",
  "click_id": "gclid_abc123",
  "group_id": "esc_a1b2c3d4e5f6",
  "run_no": 1,
  "run_count": 7,
  "item": "ad:12",
  "amount": 10,
  "currency": "USDT",
  "status": "paid",
  "paid_at": "2026-09-14T08:30:00.000Z",
  "updated_at": "2026-09-20T09:01:00.000Z",
  "ad": {
    "accepted_at": "2026-09-14T09:00:00.000Z",
    "slot_at": "2026-09-20T09:00:00.000Z",
    "asap": false,
    "keep_hours": 24,
    "posted_at": "2026-09-20T09:00:40.000Z",
    "removed_at": null,
    "last_alive_at": "2026-09-20T12:30:00.000Z",
    "views": 1240,
    "live": true
  }
}

An order appears up to about one minute after payment. A repeat_count: 7 purchase produces seven orders sharing one group_id. Buyer identity is never returned.

Errors#

Connect PAYchat#

Let a user link their PAYchat account to your site without ever seeing an API key. Your site gets a stable, pseudonymous ext_uid for that user — never their Telegram ID. Use it with POST /shop/carts.

Flow#

1. POST /connect/requests → you get a code and a connect_url
2. Show the user a Connect PAYchat button that opens connect_url
3. The first time, the PAYchat Mini App shows your site name and an Approve / Reject screen. A user who already approved your site is approved again automatically, without the screen
4. Poll GET /connect/requests/:code until status leaves pending. On approved, store ext_uid; on rejected or expired, let the user start over

Create a Request#

Endpoint: POST /api/partner/connect/requests

{
  "success": true,
  "code": "pcon_1a2b3c4d5e6f7a8b9c0d",
  "connect_url": "https://t.me/paychat_aibot?start=pcon_1a2b3c4d5e6f7a8b9c0d",
  "expires_in": 900,
  "next": "Poll GET /api/partner/connect/requests/pcon_1a2b3c4d5e6f7a8b9c0d until status is approved."
}

A request expires 15 minutes after creation.

Poll a Request#

Endpoint: GET /api/partner/connect/requests/:code

Responses are sent with Cache-Control: no-store. Polling counts against the shared GET rate limit (see Part 3).

About ext_uid#

Errors#

Part 17: Channel Ads — How a Deal Runs#

Who Does What#

Your site lists channels and creates checkouts. Everything that touches money or the Telegram channel runs inside PAYchat.

Your site never posts to a channel and never moves funds. There is no endpoint for reporting "posted", "retention complete" or "removed early" — PAYchat detects all of these itself and pushes shop.order.ad_posted / shop.order.ad_removed to you.

Lifecycle of One Run#

Each run is its own deal (escrow_id). Runs of one purchase share a group_id.

paid ─ owner accepts ─────────────► ad.accepted_at
     ─ bot posts ─────────────────► ad.posted_at          → shop.order.ad_posted
     ─ 24 h up ───────────────────► owner paid            → shop.order.completed
                                     (post stays in the channel)
     ─ owner removes within 24 h ─► ad.removed_at         → shop.order.ad_removed (early:true)
                                     then pro-rata payout  → shop.order.completed
     ─ owner silent 24h / declines / pauses channel
       / bot lost rights / post not made within 30 min of slot
       / advertiser cancels before acceptance ────────────► cancelled, refund
                                                          → shop.order.cancelled
     ─ advertiser disputes ───────► disputed → completed | cancelled

Top-level status is always paid, disputed, completed or cancelled. The finer ad lifecycle is in ad.* on the Order object.

Refund Rules#

All of this is automatic. The partner API has no route that releases or refunds buyer funds. For a repeat purchase, expect one shop.order.cancelled per cancelled run.

Good to Know#

Recent Changes (Sep 11 – Nov 1, 2026)#

Partner-facing changes only. Dates are when the change was finalized. Newer rows replace older ones where they differ.