API The Desk

The Desk obsługuje cztery tryby integracji. Wybierz ten, który pasuje do twoich ograniczeń; API pod spodem jest to samo.

Trzy kroki: stwórz sesję, przekieruj klienta, obsłuż webhook. Sample poniżej to produkcyjny checkout route w Node.js.

// Create a checkout session and redirect your customer.
// Authorization resolves the merchant wallet server-side — no wallet in the body.

const res = await fetch('https://pay.qistdigital.com/api/v1/checkout/init', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.QIST_API_KEY}`, // sk_live_…
  },
  body: JSON.stringify({
    amount_cents: 5000,                       // €50.00 — integer, in cents
    currency: 'EUR',                          // EUR, USD, GBP, CAD, AUD, CHF
    email: 'buyer@example.com',               // optional, shown in checkout
    success_url: 'https://mystore.com/success',
    cancel_url:  'https://mystore.com/cart',
    webhook_url: 'https://mystore.com/api/qist-webhook',
    metadata: { order_id: '1234' },
  }),
});

const { id, url, tracking_number } = await res.json();
// => { id: 'cs_abc…', url: 'https://pay.qistdigital.com/session/cs_abc…',
//      tracking_number: '0x…', provider: 'gateway', status: 'pending', … }

// Redirect your customer to the hosted checkout.
return Response.redirect(url, 303);

To cały happy path. Klient ląduje na hosted checkoucie na , wybiera kartę albo krypto, a twój webhook odpala się w ciągu 30s od płatności.

Dwa schematy, zależnie od trybu integracji:

Base URL: . Wszystkie endpointy gadają JSON-em, zwracają jeden obiekt na sukces, a obiekt na 4xx/5xx.

Gdy sesja dociera do stanu terminalnego, POST-ujemy podpisany event JSON na , który skonfigurowałeś (per-sesja albo w dashboardzie). Zawsze parsuj body requestu do weryfikacji podpisu — re-serializacja JSON zmienia kolejność kluczy i psuje HMAC.

POST /your-endpoint  HTTP/1.1
Host: mystore.com
Content-Type: application/json
x-peptidepay-signature: t=1745300551,v1=3f9b5c1e8a7d…    ← HMAC-SHA256, hex

{
  "event":      "order.paid",
  "session_id": "cs_abc123",
  "order_id":   "1234",
  "address_in": "0xAb12…",
  "status":     "paid",
  "amount":     5000,
  "currency":   "EUR",
  "txid":       "0xfa89b2…",
  "paid_at":    "2026-04-23T10:02:31.000Z",
  "attempt":    1
}

Tylko jest dostarczane dziś — sesje expired i failed są obserwowalne przez (status idzie na po TTL 24h; terminalne failure pokazują ). Możemy dodać push eventy dla nich w przyszłym release.

Merchanci z kontem signup dostają sekret , a każde dostarczenie niesie header w formacie . Oblicz i constant-time porównaj z . Odrzuć cokolwiek starszego niż 5 minut.

// Node.js — Express/Next.js route handler
import crypto from 'node:crypto';

const SECRET = process.env.QIST_WEBHOOK_SECRET; // dashboard → Webhooks

export async function POST(req) {
  const rawBody = await req.text();                 // MUST be the raw bytes
  const header  = req.headers.get('x-peptidepay-signature') ?? '';
  const [ tPart, v1Part ] = header.split(',');
  const t  = tPart?.split('=')[1];
  const v1 = v1Part?.split('=')[1];
  if (!t || !v1) return new Response('bad sig', { status: 400 });

  // Reject replays older than 5 minutes.
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300)
    return new Response('stale', { status: 400 });

  const expected = crypto
    .createHmac('sha256', SECRET)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  const ok =
    v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(v1, 'hex'), Buffer.from(expected, 'hex'));
  if (!ok) return new Response('invalid sig', { status: 401 });

  const event = JSON.parse(rawBody);
  // Idempotency: dedupe by event.session_id in your DB — retries re-fire
  // the same event (with an incrementing "attempt" field) until you 2xx.
  if (event.event === 'order.paid') {
    await markOrderPaid(event.order_id, event.txid);
  }
  return new Response('ok');
}

Retry-ujemy nie-2xx odpowiedzi (i timeouty > 5s) na exponential backoff. Sześć prób w sumie przez ~42 godziny:

• Próba 1 — natychmiast przy potwierdzeniu.
• Próba 2 — +5 minut.
• Próba 3 — +15 minut.
• Próba 4 — +1 godzina.
• Próba 5 — +4 godziny.
• Próba 6 — +12 godzin, potem +24 godziny (ostatnia).

Po 6 nieudanych próbach event idzie do dead-letter. Zawsze możesz re-requestować aktualny stan przez .

Widzę 'invalid signature' na każdym dostarczeniu

Twój framework sparsował body jako JSON zanim go zhaszowałeś. Czytaj RAW bajty (Express: express.raw({type:'*/*'}); Next.js: req.text(); Laravel: request()->getContent(); Rails: request.raw_post). Nigdy nie re-serializuj przed haszowaniem.

IP whitelist — z jakich IP wysyłacie?

Dostarczenia aktualnie lecą z Vercel Edge (dynamiczne IP). Nie publikujemy statycznego zakresu. Jak MUSISZ whitelistować, użyj header podpisu jako auth gate i akceptuj dowolne source IP — HMAC to prawdziwy check tożsamości.

HTTPS wymagane?

Tak. Odmawiamy POST-owania na endpointy http:// (confusable deputy / plaintext replay risk). Darmowy URL https ngrok działa ok do lokalnego testowania.

Mój endpoint jest wolny — mogę wydłużyć 5s timeout?

Nie. Odpowiedz 2xx od razu, potem przetwarzaj asynchronicznie (job queue, setImmediate, goroutine). Długie blokujące handlery zawsze kończą się timeoutem.

API jest na tyle małe, że jest zupełnie ok — ale Node SDK daje ci typy, automatyczne retry i helper , który ogarnia weryfikację podpisu za ciebie.

// npm install github:kinerette/peptide-pay-sdk
// The published package is still named "peptide-pay"; we alias the client
// to Qist here so your code reads cleanly.

import { PeptidePay as Qist } from 'peptide-pay';

const qist = new Qist(process.env.QIST_API_KEY);

// Create a session
const session = await qist.checkout.create({
  amount_cents: 5000,
  currency: 'EUR',
  customer_email: 'buyer@example.com',
  success_url: 'https://mystore.com/success',
  cancel_url:  'https://mystore.com/cart',
  metadata: { order_id: '1234' },
});

// Retrieve a session
const latest = await qist.sessions.retrieve(session.id);

// Verify + parse a webhook (throws on invalid signature)
app.post('/webhooks/qist', express.raw({ type: '*/*' }), (req, res) => {
  const event = qist.webhooks.constructEvent(
    req.body,
    req.headers['x-peptidepay-signature'],  // signature header is unchanged
    process.env.QIST_WEBHOOK_SECRET,
  );
  // event.event === 'order.paid' (currently the only event delivered)
  res.sendStatus(200);
});

Flat — pełna prowizja The Desk. Bez subskrypcji, bez miesięcznej, bez opłat za chargebacki. Opłaty on-rampy kartowej (~4.5% pobierane przez upstreamowy card processor) są pass-through — klient je płaci, nigdy nie dotykają twojego payoutu.

Pełne rozbicie z policzonymi przykładami na /fees.

The Desk nie ma sieci sandbox — każde rozliczenie to prawdziwy transfer on-chain. Najmniej ryzykowny test to , którą sam sobie zwracasz. Żeby przećwiczyć webhook end-to-end bez płacenia, użyj symulatora testowego poniżej.

• Symulator webhooków: POST na /api/v1/test/fire-webhook z kluczem sk_test_ odpala podpisany order.paid na twoim endpoincie — bez płatności, bez zwrotu.
• Karta dev MoonPay: , dowolna data ważności w przyszłości, dowolny CVV, ZIP 10001.
• Testowanie webhooków lokalnie: wystaw localhost przez ngrok, wklej URL do pola per sesja.

Pełna lokalna pętla (ngrok)

# Test your webhook receiver WITHOUT a real on-ramp payment.
# Do NOT test by paying a tiny amount: anything below an on-ramp's
# minimum (~$20) hits the gateway's "below minimum" error + KYC — that's
# the live on-ramp, not your webhook. Use the signed simulator instead.

# 1. Expose your local webhook endpoint
ngrok http 3000

# 2. Create a TEST session with your sk_test_ key. Amount can be anything
#    (the simulator ignores on-ramp minimums). Note the "id" it returns.
curl -X POST 'https://pay.qistdigital.com/api/v1/checkout/init' \
  -H "Authorization: Bearer $QIST_TEST_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "amount_cents": 5000,
    "currency": "EUR",
    "customer_email": "test+sandbox@yours.com",
    "webhook_url": "https://xxxx.ngrok-free.app/webhooks/qist"
  }'

# 3. Fire a SIGNED order.paid straight at your endpoint — no on-ramp, no
#    minimum, no KYC. (webhook_url_override also accepts localhost / ngrok
#    / loca.lt / trycloudflare.com if you'd rather not set it on the session.)
curl -X POST 'https://pay.qistdigital.com/api/v1/test/fire-webhook' \
  -H "Authorization: Bearer $QIST_TEST_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "session_id": "PASTE_id_FROM_STEP_2" }'

# 4. The response echoes your receiver's HTTP status + the exact signature
#    header we sent, so you can line it up against your HMAC verification.

Wszystkie błędy dzielą kształt . Kody statusu są standardowe REST.

Sesja jest 'paid' w dashboardzie, ale mój webhook nigdy się nie odpalił

Sprawdź, że webhook_url jest osiągalny przez publiczny HTTPS (curl-nij go spoza twojego LAN). Jak jest ok, pooluj GET /sessions/{id} dla potwierdzenia statusu — dashboard /app pokazuje staty dostarczenia webhooka (success rate, liczniki). Sześć prób przez 42h przed dead-letter; zawsze możesz re-syncować przez polling.

HMAC mismatch — podpis zawsze nieprawidłowy

99% czasu: haszujesz re-serializowane body zamiast raw bajtów. Frameworki auto-parsują JSON zanim twój handler się odpali; potrzebujesz raw buffera. Next.js: req.text() przed jakimkolwiek .json(). Express: app.use('/webhooks', express.raw({ type: '*/*' }), …). Rails: request.raw_post. Sprawdź też, że liczysz `HMAC(whsec_secret, t + '.' + rawBody)` — NIE tylko `HMAC(whsec_secret, rawBody)`. Prefiks timestampa jest WYMAGANY.

MoonPay mówi 'service unavailable in your country'

MoonPay restrykcje ~20 krajów (Iran, Korea Północna, Kuba, pełna lista na ich stronie). Domyślny provider to 'gateway' — smart picker auto-fallbackuje do Revolut, Transak albo Banxa, które pokrywają inne geografie. Jak przypiąłeś konkretnego providera z provider: 'moonpay', odepnij i daj routerowi wybrać.

Mój wallet nie dostał USDC po evencie 'paid'

Sprawdź polygonscan.com/address/<twój-wallet> pod transfery USDC (Polygon POS). Rozliczenie ląduje 97% do ciebie i 3% do The Desk - jak nie widzisz przychodzących 97%, mogłeś wkleić zły wallet do wywołania init. Potwierdź ponownie przez GET /sessions/{id} - pole txid wskazuje prawdziwy on-chain transfer.

Klient został obciążony dwa razy

Nie powinno się zdarzyć. Każda sesja ma jeden addressIn rozliczenia; drugie przelew na ten sam adres staje się osobną sesją po naszej stronie i kredytujemy tylko pierwszy do twojego zamówienia. Jak się zdarzy, screenshot dwóch txid z polygonscan + id sesji i mail na hi@pay.qistdigital.com - zwrócimy duplikat z naszej treasury.

Dostaję 502 'Payment infrastructure temporarily unavailable'

Nasz upstream rozliczenia jest zdegradowany (< 0.5% requestów). Retry za 30s z tym samym Idempotency-Key - nasz cache zwraca oryginalną odpowiedź gdy tylko wallet się wygeneruje poprawnie. Trackuj /status dla live incydentów.