Custom payment provider
Connect your own payment server to a store. The signed HTTP contract Queek calls to start and confirm each payment, the eight connection checks, and a complete reference server.
A store can connect its own payment server. You give Queek a name, an optional logo and two HTTPS addresses, one that starts a payment and one that reports whether it was paid. Queek generates a signing secret for the pair. From then on, a customer who chooses to pay online is sent to the page your server names, and your server's own answer, checked by Queek, decides whether the order is paid.
Queek never sees the money and never handles card details. Your server collects it, in your account, in whatever way you like.
This page is the whole contract. A developer can build a working server from it in an afternoon: the reference server at the bottom is complete and runs as it is.
Who it is for, and where it cannot be used
Use it when a store already has, or wants to run, its own payment collection: a bank's gateway, a processor Queek does not list, an internal billing system, a wallet. The merchant is the operator of the server and is responsible for the payments, refunds and customer data that go through it.
It collects only the orders the store collects itself. It is never used for:
- orders from a marketplace or any other Queek-operated channel;
- orders where Queek carries the delivery;
- wallet payments, and the offline methods (cash and bank transfer), which never reach your server;
- orders paid with a Queek-funded coupon. A Queek-wide code is refused at checkout when the store collects the money itself, because Queek would owe the store a discount it never receives. The store's own codes work normally.
Other limits:
- One custom provider per store, in the store's currency only.
- Plan. The store's plan must include collecting into its own account (the Own payment account feature). That is the Growth plan and the plans above it, Scale and Enterprise. A store on a plan without it cannot activate the provider.
- Identity verification. The store must have completed identity verification (KYC tier 1) before it can activate the provider, and it is checked again at every checkout.
- Country. For now only stores in Nigeria can use it. A store in another country does not see the Custom provider in its list and cannot activate it. Paystack and Stripe accounts are not affected.
- Not on dev stores. Dev stores and template stores cannot activate it. A dev store always uses Queek's simulated payment page.
- Only the store owner can connect it, change its addresses or rotate its secret. Staff with the payments permission cannot.
How a payment flows
customer Queek your server
│ pays online │ │
│ ───────────────► │ POST /create (signed) ──────► │ start a payment
│ │ ◄── 200 {redirect_url} (signed)│
│ ◄── redirect ─── │ │
│ ───────────────────────────────────────────────► │ customer pays on your page
│ ◄── redirect to return_url ───────────────────── │
│ ───────────────► │ POST /verify (signed) ──────► │ was it paid?
│ │ ◄── 200 {status:"paid", …} ─── │
│ ◄── order page ─ │ order marked paid │Four things can trigger a check: the customer returning to Queek, an optional webhook from your server, Queek's own background re-check of open payments, and the storefront asking. Every one of them is only a trigger. The evidence is always the answer your verify URL gives, and Queek marks the order paid only when that answer is signed and matches the payment exactly.
Set it up
Add the provider
In the dashboard open Settings, then Payments, then Add payment method, and choose Custom provider. Fill in:
| Field | Rule |
|---|---|
| Name shown to customers | 2 to 40 characters. |
| Logo | Optional, chosen from your own files. Without one, customers see a plain icon. |
| Create payment URL | https, a public DNS name. A port is allowed. |
| Verify payment URL | https, on the same host as the create URL. |
| Mode | Live or Test. See Test and live. |
| Responsibility | Tick that you run this server and that payments, refunds and customer data that go through it are your responsibility. |
Save. Queek stops new checkouts on this provider until the connection is verified.
Copy the signing secret
The first save shows the signing secret (it starts with qcs_) once, with a Copy button.
Queek never shows it again; the page only keeps its last four characters so you can tell which one
is deployed. Put it in your server's environment or secret manager. Lost it? Rotate it.
Build the server
Implement the create and verify endpoints with the signing scheme. Start from the reference server.
Verify the connection
Press Verify connection. Queek sends your server a test payment that is never paid and runs eight checks. Each failure comes with one plain line telling you what to fix. A pass marks the connection verified.
Activate
Press Activate. New online payments at checkout now go to your server. Customers see your name and logo in the list of payment methods, and the store, the provider name and the domain they are about to pay on before any redirect.
Signing
Every request Queek sends, every answer your server returns and every webhook you send carries two headers, in both directions:
| Header | Value |
|---|---|
Queek-Timestamp | The Unix time in seconds when the message was signed. Digits only. |
Queek-Signature | Lowercase hexadecimal HMAC-SHA256 of the signed string, keyed with your signing secret. |
The signed string is the timestamp, a dot, and the raw body exactly as sent:
{Queek-Timestamp}.{raw body}For example, with timestamp 1793283000 and the body {"type":"payment.verify","contract_version":1,"payment_id":"9b2f0c1e"}
(secret qcs_example), the signed string is:
1793283000.{"type":"payment.verify","contract_version":1,"payment_id":"9b2f0c1e"}The rules:
- Sign and verify bytes, not objects. Verify against the raw request body before you parse it. When you answer, encode the JSON once and sign and send those same bytes. Re-encoding changes whitespace or key order and breaks the signature.
- Reject anything more than 300 seconds from your clock with
401, in either direction. Queek applies the same 300 seconds to your answers against its own clock, so keep your server's time synchronised. - Compare in constant time. Never use
==on signatures. - A wrong signature gets
401. A missing or malformed header is a wrong signature. - Sign every answer to
createandverifythat is2xx. Queek reads a2xxanswer only if its signature holds. An unsigned2xxis treated as if your server had not answered. Error answers (4xx,5xx) are never read at all, signed or not, so they need no signature. - There is no nonce. A replay inside the 300 seconds only repeats an idempotent read or a create for
the same
payment_id.
import crypto from 'node:crypto';
const TOLERANCE_SECONDS = 300;
const sign = (secret, timestamp, body) =>
crypto.createHmac('sha256', secret).update(`${timestamp}.`).update(body).digest('hex');
/** Is this request really from Queek? Pass the RAW body (a Buffer), before you parse anything. */
export function isAuthentic(secret, headers, rawBody) {
const timestamp = String(headers['queek-timestamp'] ?? '');
const signature = String(headers['queek-signature'] ?? '');
if (!/^\d+$/.test(timestamp)) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp)) > TOLERANCE_SECONDS) return false;
if (!/^[0-9a-f]{64}$/.test(signature)) return false;
return crypto.timingSafeEqual(Buffer.from(signature, 'hex'), Buffer.from(sign(secret, timestamp, rawBody), 'hex'));
}
/** Answer with a signed JSON body. Encode once and sign exactly what you send. */
export function reply(secret, res, status, data) {
const body = JSON.stringify(data);
const timestamp = String(Math.floor(Date.now() / 1000));
res.writeHead(status, {
'Content-Type': 'application/json',
'Queek-Timestamp': timestamp,
'Queek-Signature': sign(secret, timestamp, body),
});
res.end(body);
}Create a payment
POST to your create URL. Queek sends Content-Type: application/json, the two signing headers, and
a compact JSON body:
{
"type": "payment.create",
"contract_version": 1,
"payment_id": "9b2f0c1e-6a1d-4c39-9a44-1f0e5d2b7c11",
"amount": "50.00",
"currency": "USD",
"test": false,
"expires_at": "2026-10-29T14:30:00Z",
"description": "Order 10423",
"order_number": "10423",
"customer": { "email": "[email protected]", "name": "Alex Morgan", "phone": "+12025550147" },
"return_url": "https://api.usequeek.com/payment/gateway/custom/callback?reference=9b2f0c1e-6a1d-4c39-9a44-1f0e5d2b7c11",
"cancel_url": "https://api.usequeek.com/payment/gateway/custom/callback?reference=9b2f0c1e-6a1d-4c39-9a44-1f0e5d2b7c11&cancelled=1"
}| Field | Meaning |
|---|---|
type | Always payment.create. |
contract_version | 1. See Versioning. |
payment_id | Queek's id for this payment and your idempotency key. Treat it as an opaque string. It is a UUID for a real payment but the connection check sends QKV- plus a timestamp, so never assume a format. |
amount | A string in the currency's major unit with its usual decimal places, such as "50.00". Charge exactly this. |
currency | ISO 4217 code, the store's currency. The examples on this page use USD. |
test | true when the store set the provider to Test mode. |
expires_at | UTC, format YYYY-MM-DDTHH:MM:SSZ, 30 minutes after the request. Never accept payment after it. |
description | Short text for the payment. |
order_number | The order's number as the store and customer see it. Empty during the connection check. |
customer | The customer's email, name and phone. Any of them can be an empty string. |
return_url, cancel_url | Where to send the customer's browser afterwards. See Return and cancel. |
Your answer
Answer 200 with a signed JSON body:
{ "redirect_url": "https://pay.example.com/s/abc123", "provider_ref": "abc123" }| Field | Rule |
|---|---|
redirect_url | Required. https, on the same host and the same port as your create URL, no userinfo, at most 2048 bytes. Queek sends the customer here. |
provider_ref | Your own reference for the payment. Recommended. |
Any other outcome is a failure: a non-2xx status, a redirect (3xx is never followed), malformed
JSON, an unsigned answer, or a redirect_url that breaks the rule. The customer then sees that
payment is unavailable, the order is placed without a payment link, and there is no fallback to
another provider. Your error body is never shown to the customer.
Verify a payment
POST to your verify URL, signed the same way:
{ "type": "payment.verify", "contract_version": 1, "payment_id": "9b2f0c1e-6a1d-4c39-9a44-1f0e5d2b7c11" }Answer 200 with a signed JSON body:
{
"payment_id": "9b2f0c1e-6a1d-4c39-9a44-1f0e5d2b7c11",
"status": "paid",
"amount": "50.00",
"currency": "USD",
"provider_ref": "abc123",
"fee": "0.75"
}| Field | Rule |
|---|---|
payment_id | Required. Echo the id you were asked about. |
status | paid, pending, failed or expired. |
amount, currency | Required. Send them for every status: what you hold for this payment, so Queek can compare. |
provider_ref | Required and non-empty when the status is paid. Send it always. |
fee | Optional, a string in the major unit: the fee your processor took. |
Answer 404 for a payment_id your server never created. Never answer paid for one.
What counts as paid
Queek marks an order paid only when all of these hold:
- The answer is
2xx, with a valid signature. statusispaid.payment_idequals the id Queek asked about.provider_refis non-empty.amountandcurrencyequal Queek's record of the payment exactly.
What happens otherwise:
| Your answer | Result |
|---|---|
paid, but amount or currency differs | The order stays unpaid, the payment is flagged and the merchant is alerted once. |
pending | Nothing changes. Queek asks again later. |
failed or expired | Recorded. The order stays unpaid and the customer can try again. |
Unsigned, wrong payment_id, malformed, or not 2xx | Treated as no answer. Nothing changes. |
Any other status value | Not paid. |
verify is read-only. Queek may call it any number of times for the same payment, so answer it
from your records every time.
Webhooks
A webhook is an optional trigger. It lets your server say "ask me about this payment now" the moment a customer pays, instead of waiting for the customer's return or Queek's next re-check. It carries no evidence: Queek ignores everything in it except which payment to ask about.
POST https://api.usequeek.com/webhooks/gateway/custom
Content-Type: application/json
Queek-Timestamp: 1793283000
Queek-Signature: <hex>
{ "type": "payment.updated", "payment_id": "9b2f0c1e-6a1d-4c39-9a44-1f0e5d2b7c11" }Sign it exactly like a response, with the same secret. Queek answers:
| Status | Meaning |
|---|---|
200 | Delivered. The body's status says what Queek did (paid, duplicate, unpaid, ignored, mismatch). It is informational: any 2xx means delivered. A payment_id Queek does not know, or an event type other than payment.updated, is 200 with ignored. |
401 | The signature was wrong or older or newer than 300 seconds. Fix it; do not retry the same message. |
500 | Queek's own check of the payment failed. Retry. |
429 | Too many deliveries from one address (120 a minute). Retry later. |
Retry on 5xx, 429 and network errors with exponential backoff, for up to 24 hours. Duplicates are
harmless: Queek finalises a payment once however many triggers arrive.
Send the webhook before you redirect the customer, and wait for it. When a payment completes,
deliver the webhook first (one attempt, with a timeout of about 8 seconds) and only then send the
customer's browser to return_url; retry in the background if that first attempt fails. The
customer's return and your webhook can otherwise reach Queek at the same moment. Queek confirms a
payment once, so whichever arrives second is answered duplicate. If the second one is the
customer's return, they can briefly be shown the payment-failed page although the order ends up paid.
The reference server does this.
Return and cancel URLs
When the customer finishes, send their browser to return_url. When they back out, send it to
cancel_url. Both point at Queek and carry the payment in the query string; do not change or
rebuild them, only redirect to them as given.
Neither URL proves anything. Queek receives the browser, calls your verify URL, and then shows the
customer the paid order or the payment-failed page. A customer who arrives on return_url without
having paid simply finds the order unpaid and can try again. Cancelling does not fail the payment by
itself: it stays open until it expires.
Idempotency, timeouts and retries
| Topic | Contract |
|---|---|
Create is idempotent on payment_id | The same payment_id is always the same payment, with the same amount and currency. When the customer comes back to pay, Queek sends another create with the same payment_id and a later expires_at. Return the open session, or a fresh one. Never charge twice and never change the amount. |
| Queek does not retry a create | One request per attempt. The customer's own retry is a new create with the same payment_id. |
| Verify | Read-only and repeatable. Background re-checks run every 10 minutes for payments still open. |
| Timeouts | Connect 3 seconds, 5 seconds in total, for every call. A slower server counts as unreachable. |
| Redirects | Never followed. A 3xx is a failure. |
| Answer size | At most 64 KB. |
| Compression | Queek does not ask for it and does not decompress. Answer uncompressed. A gzip-only server or proxy reads as malformed. |
| Limits on Queek's side | At most 60 creates a minute per store and 5 per order a minute. The return URL accepts 60 visits a minute from one address and the webhook 120. |
Expiry
Every payment expires 30 minutes after the create call, at expires_at. Refuse to take
money after it, and answer expired from verify for an unpaid payment past it.
Queek's background re-check keeps asking until 30 minutes after expires_at, so a payment
completed in the last seconds is still found. After that Queek no longer checks in the
background, so send the webhook as soon as a payment completes. An expired payment is not
dead: when the customer comes back to pay, Queek sends a new create with the same payment_id
and a later expires_at.
Test and live
The provider has a Mode. In Test mode Queek puts "test": true in every create request, and in
live mode "test": false. That is the only difference on Queek's side: orders are real orders, the
requests are the same and nothing is simulated. Your server decides what test means. When test
is true, use your processor's sandbox and never take real money; when it is false, charge for
real.
Switching the mode means saving the provider again, which puts the connection back to pending until you verify it. Open payments are not affected by a save that changes nothing else.
The eight connection checks
Verify connection sends your server a test payment (an amount of 100 in the store's currency, never paid) and runs these checks in order. The first failure is reported with its line; checks that could not run after a failure show as not checked. The whole run is limited to 25 seconds, and you can run it five times a minute.
| # | Check | Passes when | If it fails |
|---|---|---|---|
| 1 | Addresses | Both URLs are public https addresses on one host. | Use a public https:// address, and put both URLs on the same domain. |
| 2 | Create answers | The create URL answers 200 with JSON within 5 seconds. | We couldn't reach the host: check the address, TLS certificate and firewall. Took longer than 5 seconds: answer faster, hand slow work to a background job. Answered another status: it must answer 200 with a redirect_url. |
| 3 | Create is signed | The create answer carries a valid Queek-Signature made with your signing secret. | Sign the answer with {timestamp}.{raw body} and the secret Queek showed. Check the secret is the current one, the timestamp is in seconds and the body you sign is the body you send. |
| 4 | Payment page is on your domain | redirect_url is https on the create URL's host and port, with no userinfo, within 2048 bytes. | Serve the payment page from the same host and port as the create URL. If your processor's page is on another domain, redirect to it from a page on yours. |
| 5 | Verify reports the payment | Verify of that payment is signed, is not paid, echoes the payment_id and names exactly Queek's amount and currency. | Answer pending (never paid) for an unpaid payment, echo payment_id, and return the amount and currency you were sent, not your processor's rounded values. |
| 6 | Wrong signature is refused | A verify request signed with a wrong secret gets 401. | Check the signature before doing anything else, and answer 401 when it does not match. |
| 7 | Old requests are refused | A correctly signed verify request with a 10-minute-old timestamp gets 401. | Reject any timestamp more than 300 seconds from your clock. |
| 8 | Unknown payments are never paid | Verify of a payment_id your server never created gets 404, or at least a status that is not paid. | Answer 404 for ids you do not have. Do not default unknown ids to a status. |
Rotating the secret
Rotate secret in the dashboard issues a new signing secret, shown once. The old secret stops working at once and the connection goes back to pending, so new checkouts stop until you put the new secret on your server and verify again. Rotate at a quiet moment, and wait for open payments to finish first (they live 30 minutes at most).
Editing the create or verify URL does the same: new checkouts stop until the connection is verified again.
Payments in flight
A payment started on the old addresses or the old secret is the old server's. Whoever controls the
new address or secret must never be able to confirm it, so Queek does not confirm it through the
new settings, even if the new server answers a valid signed paid.
When you change the addresses or rotate the secret:
- each payment still open on the old settings is flagged for manual review, and the owner gets one notification saying how many are open;
- nothing is failed or refunded;
- check each flagged payment in your own payment system and, if the customer paid, approve the payment by hand.
A save that changes neither the addresses nor the secret leaves open payments alone. Payments started after the change confirm normally.
Refunds
Refunds are manual. Queek never sends your server a refund request, and there is no refund endpoint to build. Refund the customer from your own payment system.
Security requirements
Queek enforces all of these on every call, not only when you save:
- https only. A port is allowed. No plain
http. - Public hosts only. The address must be a DNS name that resolves to a public address. IP
literals,
localhost, internal zones, private, loopback and link-local ranges, userinfo (user@host), spaces and{}are refused. Queek resolves the name itself for each request and connects to that address, so a name that later points at a private address is refused too. - One host. The create and verify URLs share a host, and
redirect_urlmust be on that host and port. - No redirects followed. Answer at the address you were given.
- Authenticate by signature, never by source address. Verify the signature on every request before reading it, and keep the secret in a secret manager, never in a browser or an app bundle.
- One secret per store. If one server handles several stores, give each store its own URLs (a different path is enough) and choose the secret from the path.
- Customer data. Your server receives the customer's email, name and phone number with each payment. It is the merchant's responsibility from there.
Custom payment providers are available to every eligible store by default. Queek can still switch them off globally. While that switch is off the provider is not offered, no new payment is started, and payments already in flight are still confirmed.
Reference server
A complete server in plain Node (18 or newer, no dependencies). It signs every answer, checks every
request, keeps payment_id idempotent, locks the amount, expires payments, serves a stand-in payment
page and sends the optional webhook, which it awaits before redirecting the customer.
QUEEK_SIGNING_SECRET=qcs_your_secret \
PUBLIC_BASE_URL=https://pay.example.com \
node server.mjsPUBLIC_BASE_URL is the public https origin of your create and verify URLs, including the port if it
is not 443. Queek must be able to reach it, so for local work put an HTTPS tunnel in front of port
3000. The create URL is then https://pay.example.com/create and the verify URL
https://pay.example.com/verify.
// A complete payment server for Queek's custom payment provider contract (v1).
// Node 18 or newer, no dependencies: QUEEK_SIGNING_SECRET=qcs_... PUBLIC_BASE_URL=https://pay.example.com node server.mjs
import crypto from 'node:crypto';
import http from 'node:http';
const SECRET = process.env.QUEEK_SIGNING_SECRET;
const PUBLIC_BASE_URL = (process.env.PUBLIC_BASE_URL ?? '').replace(/\/$/, ''); // the https origin of your create URL, port included
const PORT = Number(process.env.PORT ?? 3000);
const QUEEK_WEBHOOK_URL = process.env.QUEEK_WEBHOOK_URL ?? 'https://api.usequeek.com/webhooks/gateway/custom';
const TOLERANCE_SECONDS = 300;
if (!SECRET || !PUBLIC_BASE_URL) {
console.error('Set QUEEK_SIGNING_SECRET and PUBLIC_BASE_URL.');
process.exit(1);
}
// payment_id -> { amount, currency, expiresAt, returnUrl, cancelUrl, providerRef, paid }
// In memory for the example. Keep these in a database, keyed by payment_id.
const payments = new Map();
// ---- signing: HMAC-SHA256 over "{timestamp}.{raw body}", hex, in both directions ----
const sign = (timestamp, body) =>
crypto.createHmac('sha256', SECRET).update(`${timestamp}.`).update(body).digest('hex');
function isAuthentic(req, rawBody) {
const timestamp = String(req.headers['queek-timestamp'] ?? '');
const signature = String(req.headers['queek-signature'] ?? '');
if (!/^\d+$/.test(timestamp)) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp)) > TOLERANCE_SECONDS) return false;
const expected = Buffer.from(sign(timestamp, rawBody), 'hex');
const received = Buffer.from(/^[0-9a-f]{64}$/.test(signature) ? signature : '', 'hex');
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}
function signedHeaders(body) {
const timestamp = String(Math.floor(Date.now() / 1000));
return {
'Content-Type': 'application/json',
'Queek-Timestamp': timestamp,
'Queek-Signature': sign(timestamp, body),
};
}
// Encode once, sign those exact bytes, send those exact bytes.
function reply(res, status, data) {
const body = JSON.stringify(data);
res.writeHead(status, signedHeaders(body));
res.end(body);
}
// ---- tell Queek a payment changed (optional: Queek also checks when the customer returns) ----
// The first attempt is awaited by the caller (see pay): the webhook and the customer's return must not race. Retries run in the background.
async function notifyQueek(paymentId, attempt = 0) {
const body = JSON.stringify({ type: 'payment.updated', payment_id: paymentId });
try {
const res = await fetch(QUEEK_WEBHOOK_URL, { method: 'POST', headers: signedHeaders(body), body, signal: AbortSignal.timeout(8_000) });
if (res.status < 300 || (res.status >= 400 && res.status < 500)) return;
} catch {
// network error: retry below
}
if (attempt < 8) setTimeout(() => notifyQueek(paymentId, attempt + 1), Math.min(2 ** attempt * 5_000, 15 * 60_000));
}
// ---- the two endpoints Queek calls ----
function create(res, body) {
const id = String(body.payment_id ?? '');
if (!id || typeof body.amount !== 'string' || typeof body.currency !== 'string') {
return reply(res, 400, { error: 'invalid_request' });
}
let payment = payments.get(id);
if (payment && (payment.amount !== body.amount || payment.currency !== body.currency)) {
return reply(res, 409, { error: 'amount_locked' }); // one payment_id, one amount and currency, always
}
if (payment?.paid) return reply(res, 409, { error: 'already_paid' });
if (!payment) {
payment = { amount: body.amount, currency: body.currency, paid: false, providerRef: `ref_${crypto.randomUUID()}` };
payments.set(id, payment);
}
// A repeated create (the customer came back to pay) is the same payment with a later expiry.
payment.expiresAt = Date.parse(body.expires_at);
payment.returnUrl = body.return_url;
payment.cancelUrl = body.cancel_url;
payment.test = body.test === true;
// The redirect must be https on the same host AND port as your create URL.
reply(res, 200, { redirect_url: `${PUBLIC_BASE_URL}/pay/${encodeURIComponent(id)}`, provider_ref: payment.providerRef });
}
function verify(res, body) {
const payment = payments.get(String(body.payment_id ?? ''));
if (!payment) return reply(res, 404, { error: 'not_found' }); // never created here: 404, never "paid"
const expired = !payment.paid && Date.now() > payment.expiresAt;
reply(res, 200, {
payment_id: body.payment_id,
status: payment.paid ? 'paid' : expired ? 'expired' : 'pending',
amount: payment.amount,
currency: payment.currency,
provider_ref: payment.providerRef,
});
}
// ---- the hosted payment page the customer is redirected to (replace with your real checkout) ----
function page(res, id, payment) {
res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
res.end(`<!doctype html><meta charset="utf-8"><title>Pay</title>
<h1>Pay ${payment.amount} ${payment.currency}</h1>
<form method="post" action="/pay/${encodeURIComponent(id)}"><button>Pay now</button></form>
<p><a href="${payment.cancelUrl}">Cancel</a></p>`);
}
async function pay(res, id, payment) {
if (Date.now() > payment.expiresAt) {
res.writeHead(410, { 'Content-Type': 'text/plain' });
return res.end('This payment has expired. Go back to the store and try again.');
}
payment.paid = true; // a real server marks it paid only when its processor confirms the money
await notifyQueek(id); // optional trigger: wait for the first delivery BEFORE sending the customer back, so the two cannot race
res.writeHead(303, { Location: payment.returnUrl }); // Queek then verifies; the return itself proves nothing
res.end();
}
// ---- routing ----
http
.createServer((req, res) => {
const chunks = [];
req.on('data', (chunk) => chunks.push(chunk));
req.on('end', () => {
const raw = Buffer.concat(chunks);
const { pathname } = new URL(req.url, PUBLIC_BASE_URL);
if (req.method === 'POST' && (pathname === '/create' || pathname === '/verify')) {
if (!isAuthentic(req, raw)) return reply(res, 401, { error: 'unauthorized' });
let body;
try {
body = JSON.parse(raw.toString('utf8'));
} catch {
return reply(res, 400, { error: 'invalid_json' });
}
return pathname === '/create' ? create(res, body) : verify(res, body);
}
const match = pathname.match(/^\/pay\/([^/]+)$/);
const id = match ? decodeURIComponent(match[1]) : '';
const payment = payments.get(id);
if (payment && req.method === 'GET') return page(res, id, payment);
if (payment && req.method === 'POST') return pay(res, id, payment);
res.writeHead(404, { 'Content-Type': 'text/plain' });
res.end('Not found');
});
})
.listen(PORT, () => console.log(`Payment server on :${PORT}, public address ${PUBLIC_BASE_URL}`));Before going live, replace the stand-in payment page with your real checkout and mark a payment
paid only when your processor has confirmed the money. Store payments in a database, keyed by
payment_id.
FAQ
Do I have to host the payment page? The page the customer lands on must be on your create URL's
host and port. If your processor's hosted page is on another domain, make redirect_url a page on
your domain that redirects the browser onward. Queek only checks the first address.
Is the webhook required? No. The customer's return triggers a check, and Queek's background re-check
covers customers who never come back, until 30 minutes after expires_at. The webhook makes confirmation
immediate. If you do send it, wait for it before you redirect the customer (see Webhooks).
What if my server is down when Queek verifies? An unreachable or slow server is treated as no answer. The payment stays open and Queek asks again. It does not fail the order.
Can I take a different amount than amount? No. If the amount or currency in your verify answer
differs from Queek's, the order stays unpaid and is flagged.
Does Queek add a processing fee? No. For these orders Queek adds no processing fee line: the customer pays the order total, and the money goes to you.
What does the customer see? At checkout, your name and logo for the provider, and the store, the provider name and the domain before the redirect. After paying they land back on Queek's order page.
Which currencies? The store's currency only.
Can several stores share a server? Yes, with one secret per store. See Security requirements.
What if my signature checks pass in testing but fail in Verify connection? Check, in this order, that you use the secret currently shown by Queek, that you sign the raw bytes you send, that the timestamp is in seconds, and that a proxy does not compress or rewrite the body.
How do I pause it? Deactivate the provider in the dashboard. New payments stop being offered through your server and the signing secret is deleted. To use it again, save it and verify it again.
Versioning
Every request carries contract_version, currently 1. Fields are only ever added to v1, so ignore
fields you do not know. A breaking change becomes version 2 and is served side by side.